payload-live-preview 2.0.0-beta.0 → 2.0.0

package/dist/core.d.cts

@@ -1,4 +1,5 @@
 /** The package version, read from package.json so the entries and the inline runtime cannot drift. */
+/** @internal */
 declare const VERSION: string;
 
 /** Connection status and the heartbeat that decides a disconnect. */
@@ -83,6 +84,23 @@ interface InspectionBindings {
     readonly ownerScoped: boolean;
     /** Distinct document owners currently on the page, sorted. */
     readonly owners: readonly string[];
+    /**
+     * Bindings the runtime found by value on the connection's first message
+     * (`autoBind: 'unique'`, ADR 0014), sorted by field, each with the value it
+     * matched on and the attribute it matched in — `undefined` for a text match.
+     * These are the elements that change without a `data-payload-field` in the
+     * template; every one of them carries `data-payload-guessed` in the DOM.
+     */
+    readonly guessed: readonly {
+        readonly field: string;
+        readonly matched: string;
+        readonly attribute: string | undefined;
+    }[];
+    /** `autoBind` as configured, and what the one search cost; `searchMs` is `undefined` until it ran. */
+    readonly autoBind: {
+        readonly mode: 'off' | 'unique';
+        readonly searchMs: number | undefined;
+    };
 }
 /** Scheduler work in progress. */
 interface InspectionScheduler {
@@ -122,14 +140,49 @@ interface LivePreviewInspection {
     readonly plugins: readonly PluginInspection[];
     /** Server-rendered fragment boundaries: whether a handler exists and what happened to renders. */
     readonly fragments: InspectionFragments;
-    /** Route refreshes: whether a strategy exists, how many ran, failed, or were stopped by the loop guard. */
+    /** Route refreshes: whether a strategy exists, how many ran, failed, were paced, or were stopped by the loop guard. */
     readonly route: InspectionRoute;
+    /** Patches the runtime knew could not match the server's render, and what became of them. */
+    readonly fidelity: InspectionFidelity;
+    /**
+     * Whether the page declared a framework that hydrates it, and how far the
+     * wait for its first commit — React's, or Vue's mount — got (ADR 0015).
+     * `waiting` is why a preview on a Next or Nuxt page is not connected yet;
+     * `timed-out` is LP0607.
+     */
+    readonly hydration: {
+        readonly mode: 'off' | 'react' | 'vue';
+        readonly state: 'idle' | 'waiting' | 'committed' | 'timed-out';
+    };
+}
+/**
+ * The fidelity verdicts as `inspect()` reports them (LP0411). A positive
+ * `unfaithful` beside `escalated: 0` is a page that keeps a degraded patch —
+ * because `mode` says so, or because neither `fragments.handler` nor
+ * `route.handler` is there to escalate to.
+ */
+interface InspectionFidelity {
+    /** `onUnfaithfulPatch` as resolved from both of its names. */
+    readonly mode: 'ignore' | 'warn' | 'escalate';
+    /** Bindings reported unfaithful since start — once per element, like LP0411, and under every mode. */
+    readonly unfaithful: number;
+    /** Of those, how many were handed to the fragment or route strategy. */
+    readonly escalated: number;
+    /** The field names behind `unfaithful`, sorted. Cumulative. */
+    readonly fields: readonly string[];
 }
 /** The route strategy as `inspect()` reports it. */
 interface InspectionRoute {
     readonly handler: boolean;
     readonly refreshes: number;
+    /** Refreshes that broke: the request, the answer, or the morph. */
     readonly failed: number;
+    /**
+     * Refreshes the strategy's own minimum interval held back (LP0805). Each is
+     * run once the window closes unless a newer revision takes its place, so this
+     * counts pacing and not loss — and it is deliberately not `failed`.
+     */
+    readonly refused: number;
     /** Second refresh requests for one revision, refused with LP0805. */
     readonly loopStopped: number;
 }
@@ -227,7 +280,9 @@ type PayloadFieldCondition = (data: unknown, siblingData: unknown) => boolean;
  *
  * Browser-side reporting sites write the literal (`code: 'LP0603'`) rather than
  * reading it from this record: the frozen table would then ship in the inline
- * runtime for the sake of six characters. Server-side tools may import it.
+ * runtime for the sake of six characters — it did, 1 287 B in every page, for
+ * the one read Z6 left in the strategy runner, and `diagnostic-codes.test.ts`
+ * now holds the artifact free of it. Server-side tools may import it.
  */
 /**
  * Every diagnostic code the runtime can report, by name.
@@ -245,6 +300,8 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly ReferrerOnlyTrust: "LP0102";
     /** A plugin declares a runtime range this runtime does not satisfy; it was refused. */
     readonly PluginIncompatible: "LP0103";
+    /** The page carries the lean runtime and needs a feature that profile leaves out. */
+    readonly ProfileFeatureOmitted: "LP0104";
     /** An update named a field with no binding anchor on the page. */
     readonly OrphanField: "LP0201";
     /** Owner scoping is on and the update names no document it could belong to. */
@@ -265,10 +322,24 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly StructuralUnstableKeys: "LP0406";
     /** A binding asks for a delivery strategy this release does not have; it is left unchanged. */
     readonly UnsupportedStrategy: "LP0407";
+    /** `data-payload-format` names a format the vocabulary does not contain; the default formatting was used instead. */
+    readonly UnknownValueFormat: "LP0408";
+    /** The strict sanitizer removed an attribute the 1.x `'compat'` policy kept. */
+    readonly SanitizerDroppedAttribute: "LP0409";
+    /** A Lexical block has no renderer; the markup the server rendered for it is kept instead. */
+    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. */
+    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";
     /** A message was rejected before it reached the update pipeline. */
     readonly MessageRejected: "LP0501";
     /** A preview token was rejected. */
     readonly TokenRejected: "LP0502";
+    /** A trusted origin sent a message this protocol version does not recognise. */
+    readonly ProtocolShapeUnknown: "LP0503";
     /** A consumer event handler threw. */
     readonly HandlerThrew: "LP0601";
     /** A consumer transform threw; the original value was kept. */
@@ -279,11 +350,13 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly StartupFailed: "LP0605";
     /** Sending the ready handshake failed. */
     readonly ReadyFailed: "LP0606";
+    /** The page declared hydration, but no React commit or Vue mount 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";
     /** The preview response declares no `frame-ancestors`. */
     readonly AuditNoFrameAncestors: "LP0702";
-    /** `X-Frame-Options` forbids framing, which no CSP can undo. */
+    /** `X-Frame-Options` forbids framing, which no CSP can undo; `SAMEORIGIN` forbids it from another origin only. */
     readonly AuditFrameOptionsBlocks: "LP0703";
     /** Binding attributes are served to anonymous visitors. */
     readonly AuditBindingsExposed: "LP0704";
@@ -303,10 +376,12 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly FragmentUnauthorized: "LP0803";
     /** A fragment response arrived for a revision that was already superseded and was discarded. */
     readonly FragmentSuperseded: "LP0804";
-    /** A route refresh was requested again for the same revision; the loop guard stopped it. */
+    /** A route refresh was refused: the loop guard, or the strategy's minimum interval. */
     readonly RouteRefreshLoop: "LP0805";
     /** A boundary asks for the fragment strategy but no fragment handler is configured; it is patched. */
     readonly FragmentStrategyUnavailable: "LP0806";
+    /** A revision changed a field with no binding; `onUnfaithfulPatch` refreshed the route. */
+    readonly UnboundChangeRefresh: "LP0807";
     /** A readiness row is not yet at its 2.0 value; `pll doctor --v2` reports it. */
     readonly V2ReadinessGap: "LP0709";
     /** The preview runtime is served to anonymous visitors, not only inside the admin frame. */
@@ -369,7 +444,21 @@ interface RouteContext {
     readonly signal: AbortSignal;
     readonly isCurrent: () => boolean;
     readonly log: (code: DiagnosticCode, detail: string) => void;
+    /**
+     * Ask to be run again in `delayMs`, once. A strategy that refuses a refresh
+     * because it is rate-limiting itself uses this: the window is a rate limit
+     * and not a filter, so what falls inside it still has to reach the preview.
+     * The runtime runs at most one such request, and only while the revision that
+     * asked is still the current one.
+     */
+    readonly retryAfter?: (delayMs: number) => void;
 }
+/**
+ * What one refresh did. `refused` is the strategy's own brake and not a
+ * failure — it is counted separately, because a number that mixes a planned
+ * pause with a broken request cannot be read.
+ */
+type RouteOutcome = 'refreshed' | 'failed' | 'refused' | 'superseded';
 /**
  * Whether a revision needs the whole route re-rendered, and how. After a
  * refresh the runtime rescans and re-applies the revision, so the unsaved
@@ -377,7 +466,7 @@ interface RouteContext {
  */
 interface RouteStrategy {
     readonly plan: (root: ParentNode, changedFields: ReadonlySet<string>) => boolean;
-    readonly refresh: (context: RouteContext) => Promise<'refreshed' | 'failed' | 'superseded'>;
+    readonly refresh: (context: RouteContext) => Promise<RouteOutcome>;
 }
 interface StrategyHandlers {
     readonly fragment?: FragmentStrategy;
@@ -450,7 +539,15 @@ interface LivePreviewEventMap {
     readonly documentSave: {
         readonly timestamp: number;
     };
-    /** A data update carried `externallyUpdatedRelationship`: a related document changed in an admin drawer, so the update re-renders unconditionally. */
+    /**
+     * A save in another document reached the page through
+     * `externallyUpdatedRelationship` — an admin-drawer edit. Fires once per
+     * such save, not once per message: the panel repeats its last document
+     * event in every later message, including its own saves of the previewed
+     * document, and neither of those is news. That update re-renders every
+     * bound field even under `skipUnchanged`, because a drawer edit changes
+     * populated values while the form values stay put.
+     */
     readonly relationshipUpdate: {
         readonly detail: PayloadDocumentEventDetail;
         readonly timestamp: number;
@@ -496,6 +593,53 @@ declare class EventEmitter<TMap extends object = LivePreviewEventMap> {
     eventNames(): (keyof TMap)[];
 }
 
+/**
+ * `'strict'` (default) strips `id`, `name` and `data-payload-*` and passes
+ * other `data-*` only via `allowedDataAttributes`; `'compat'` keeps them.
+ */
+type SanitizerPolicyMode = 'compat' | 'strict';
+interface SanitizeOptions {
+    /** Overrides the module default set by `setSanitizerPolicy()`. */
+    readonly policy?: SanitizerPolicyMode;
+    /** `data-*` attributes (full names) that pass under `'strict'`; `data-payload-*` never does. */
+    readonly allowedDataAttributes?: readonly string[];
+    /**
+     * Keep `input`, `button`, `textarea`, `select`, `option` and `label` — only
+     * for markup the page author wrote, never for CMS content. `form`,
+     * handlers, `style` and unsafe URLs stay dropped.
+     */
+    readonly allowFormControls?: boolean;
+    /** Extra tags to allow. Lower-case, untrimmed. */
+    readonly additionalAllowedTags?: readonly string[];
+    /**
+     * Extra per-tag attributes, lower-case. Cannot re-admit handlers, `style`,
+     * or — under `'strict'` — `id`, `name` and `data-payload-*`.
+     */
+    readonly additionalAllowedAttributes?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * The input is a page-author item template, so `'strict'` keeps the
+     * applier's reconciliation attributes (`TEMPLATE_ATTRIBUTES`) and nothing
+     * else — every other `data-payload-*` is still stripped, so a template can
+     * never add a binding.
+     */
+    readonly templateMode?: boolean;
+}
+/** The `Document` surface the sanitizer needs; jsdom, linkedom and happy-dom all provide it. */
+interface SanitizerDocument {
+    createElement: (tagName: string) => {
+        innerHTML: string;
+        readonly content: ParentNode;
+    };
+}
+/** Supply a `Document` for SSR, e.g. linkedom's `parseHTML(...).document`; `null` clears it. */
+declare function setSanitizerDocument(doc: SanitizerDocument | null): void;
+/**
+ * Sanitize `html`; malformed input is recovered by the parser first.
+ *
+ * @throws {SanitizerEnvironmentError} when no DOM is available.
+ */
+declare function sanitizeHtml(html: string, options?: SanitizeOptions): string;
+
 /** Types shared by the runtime primitives. */
 
 /** Payload's field set plus the DOM-binding categories `html`, `url`, `image` and `structural-array`. */
@@ -532,7 +676,7 @@ interface CachedElement {
     /** Nearest enclosing `data-payload-fragment` boundary. Resolved by the cache. */
     readonly fragmentBoundary?: Element;
     /** `data-payload-boundary`: an anchor that hides itself while its field is empty. */
-    readonly boundary?: boolean;
+    readonly hidesWhenEmpty?: boolean;
     /** Write the value into this attribute instead of the content; policed writes. */
     readonly targetAttribute?: string;
     /** Optional sibling-field path bound to the element's `href` attribute. */
@@ -547,8 +691,16 @@ interface CachedElement {
     readonly arraySeparator?: string;
     /** Optional locale code locked onto this element (overrides the global locale). */
     readonly locale?: string;
+    /** Raw `data-payload-format`; the date and number renderers read the vocabulary. */
+    readonly format?: string;
     /** The document this binding belongs to, from the nearest `data-payload-owner`. */
     readonly owner?: string;
+    /**
+     * The value an auto-binding matched on (`data-payload-guessed`), for a
+     * binding the runtime found by value rather than one the template declared.
+     * Absent for a declared binding.
+     */
+    readonly guessed?: string;
 }
 /** What a renderer is given; `allFields` lets it resolve a sibling field. */
 interface RenderContext {
@@ -560,6 +712,20 @@ interface RenderContext {
     readonly schema: PayloadFieldSchema | undefined;
     /** The project's rich-text renderer, when the client was configured with one. */
     readonly renderRichText?: RichTextRenderer;
+    /**
+     * This instance's sanitizer policy, for every HTML write the renderer makes.
+     * Absent, the process default set by `setSanitizerPolicy()` applies.
+     */
+    readonly sanitizerPolicy?: SanitizerPolicyMode;
+    /**
+     * Say that this write cannot reproduce what the server drew, so
+     * `onUnfaithfulPatch` can have a strategy render the region instead of
+     * leaving a degraded patch on the page. The built-in rich-text renderer
+     * calls it for a Lexical block whose markup it had to drop; a project
+     * renderer may call it for any value it can only approximate. `reason`
+     * completes the sentence 'field "x" …' in LP0411.
+     */
+    readonly reportUnfaithful?: (target: CachedElement, reason: string) => void;
 }
 /**
  * A renderer writes one value into its element. It must not throw: one bad
@@ -636,6 +802,10 @@ interface LivePreviewPlugin {
  * one side — the adapter's request decision or the browser runtime — and a
  * test asserts the profile assigns every readiness row that has an option, so
  * a row added later cannot be forgotten. See ADR 0007.
+ *
+ * It lives in the leaf `types` domain, like `merge-depth.ts`, because the
+ * inline generator resolves the profile too, and the generator is server-side
+ * code that may not reach the browser runtime in `core`.
  */
 /** `'v2'` is the 2.0 default; `'v1'` is the 1.x table. */
 type DefaultsProfile = 'v1' | 'v2';
@@ -672,6 +842,13 @@ interface LivePreviewClientConfig {
     readonly skipUnchanged?: boolean;
     /** Scroll the preview to the field being edited when its value changes. Default `false`. */
     readonly revealEditedField?: boolean;
+    /**
+     * Find bindings by value on the connection's first message: a scalar whose
+     * value is the whole content of exactly one element is bound to it as if
+     * `data-payload-field` stood there; every guess is stamped `data-payload-guessed`
+     * and listed in `inspect().bindings.guessed`. Default `'off'`.
+     */
+    readonly autoBind?: 'off' | 'unique';
     /** Fields whose change re-applies other bindings regardless of their own value: `{ price: ['priceLabel'] }`. Used with `skipUnchanged`. */
     readonly dependencies?: Readonly<Record<string, readonly string[]>>;
     /** Strategy handlers beyond patching; `createFragmentStrategy()` from `payload-live-preview/fragment` builds one. */
@@ -696,7 +873,11 @@ interface LivePreviewClientConfig {
     readonly disableLocalhostMatching?: boolean;
     /** Which windows may post updates. Default `'parent-or-opener'`; `defaults: 'v1'` sets `'any'`. */
     readonly eventSourcePolicy?: EventSourcePolicy;
-    /** Sanitizer policy for rich text and HTML writes. Default `'strict'`; `defaults: 'v1'` sets `'compat'`. */
+    /**
+     * Sanitizer policy for this client's rich text and HTML writes. Default
+     * `'strict'`; `defaults: 'v1'` sets `'compat'`. Per instance: it leaves the
+     * process default that `setSanitizerPolicy()` sets for direct `sanitizeHtml()` calls alone.
+     */
     readonly sanitizerPolicy?: 'compat' | 'strict';
     /** `'v2'` (default) is the 2.0 table; `'v1'` restores every 1.x row at once. Explicit options win. */
     readonly defaults?: DefaultsProfile;
@@ -754,7 +935,7 @@ declare function initLivePreview(config?: LivePreviewClientConfig): LivePreviewC
 /** HTML and CSS escaping primitives (OWASP XSS Prevention Cheat Sheet). DOM-free. */
 /** Escape `text` for an element body or a *quoted* attribute value; strings only, and unquoted attributes are not covered. */
 declare function escapeHtml(text: string): string;
-/** Escape a value for a *quoted* HTML attribute, leaving URL characters intact; it validates no scheme, so run `isSafeUrl()` on `href`/`src` first. */
+/** Escape a value for a *quoted* HTML attribute, leaving URL characters intact; it validates no scheme, so run `isSafeUrl()` on `href`/`src` first. @internal */
 declare function escapeHtmlAttribute(value: string): string;
 
 /**
@@ -763,56 +944,9 @@ declare function escapeHtmlAttribute(value: string): string;
  */
 /** `true` only for absolute `http`/`https`/`mailto`/`tel` URLs, protocol-relative URLs, paths, `#`/`?` fragments and relative paths. */
 declare function isSafeUrl(url: unknown): boolean;
-/** Whether a safe URL points at another HTTP(S) origin, protocol-relative forms included, and so needs `noopener` hardening. */
+/** Whether a URL points at another HTTP(S) origin, protocol-relative forms included, and so needs `noopener` hardening; every URL these two patterns match is one `isSafeUrl` admits. */
 declare function isExternalHttpUrl(url: string): boolean;
 
-/**
- * `'strict'` (default) strips `id`, `name` and `data-payload-*` and passes
- * other `data-*` only via `allowedDataAttributes`; `'compat'` keeps them.
- */
-type SanitizerPolicyMode = 'compat' | 'strict';
-interface SanitizeOptions {
-    /** Overrides the module default set by `setSanitizerPolicy()`. */
-    readonly policy?: SanitizerPolicyMode;
-    /** `data-*` attributes (full names) that pass under `'strict'`; `data-payload-*` never does. */
-    readonly allowedDataAttributes?: readonly string[];
-    /**
-     * Keep `input`, `button`, `textarea`, `select`, `option` and `label` — only
-     * for markup the page author wrote, never for CMS content. `form`,
-     * handlers, `style` and unsafe URLs stay dropped.
-     */
-    readonly allowFormControls?: boolean;
-    /** Extra tags to allow. Lower-case, untrimmed. */
-    readonly additionalAllowedTags?: readonly string[];
-    /**
-     * Extra per-tag attributes, lower-case. Cannot re-admit handlers, `style`,
-     * or — under `'strict'` — `id`, `name` and `data-payload-*`.
-     */
-    readonly additionalAllowedAttributes?: Readonly<Record<string, readonly string[]>>;
-    /**
-     * The input is a page-author item template, so `'strict'` keeps the
-     * applier's reconciliation attributes (`TEMPLATE_ATTRIBUTES`) and nothing
-     * else — every other `data-payload-*` is still stripped, so a template can
-     * never add a binding.
-     */
-    readonly templateMode?: boolean;
-}
-/** The `Document` surface the sanitizer needs; jsdom, linkedom and happy-dom all provide it. */
-interface SanitizerDocument {
-    createElement: (tagName: string) => {
-        innerHTML: string;
-        readonly content: ParentNode;
-    };
-}
-/** Supply a `Document` for SSR, e.g. linkedom's `parseHTML(...).document`; `null` clears it. */
-declare function setSanitizerDocument(doc: SanitizerDocument | null): void;
-/**
- * Sanitize `html`; malformed input is recovered by the parser first.
- *
- * @throws {SanitizerEnvironmentError} when no DOM is available.
- */
-declare function sanitizeHtml(html: string, options?: SanitizeOptions): string;
-
 /**
  * Content-Security-Policy helpers: nonce generation, directive builders and
  * the header merge every adapter uses. Isomorphic; needs only Web Crypto.
@@ -821,9 +955,9 @@ declare function sanitizeHtml(html: string, options?: SanitizeOptions): string;
 interface WebCryptoLike {
     getRandomValues: <T extends ArrayBufferView | null>(array: T) => T;
 }
-/** Supply a Web Crypto implementation for runtimes without `globalThis.crypto`; `null` clears it. */
+/** Supply a Web Crypto implementation for runtimes without `globalThis.crypto`; `null` clears it. @internal */
 declare function setCspCrypto(crypto: WebCryptoLike | null): void;
-/** A base64url nonce of `bytes` random bytes (default 16); throws without Web Crypto, since a predictable nonce silently defeats the CSP. */
+/** A base64url nonce of `bytes` random bytes (default 16); throws without Web Crypto, since a predictable nonce silently defeats the CSP. @internal */
 declare function generateCspNonce(bytes?: number): string;
 interface FrameAncestorsOptions {
     readonly self?: boolean;
@@ -836,6 +970,7 @@ declare function buildFrameAncestors(options?: FrameAncestorsOptions): string;
  * A `script-src` value permitting one nonce plus optional extra sources.
  * `'strict-dynamic'` is opt-in: it makes CSP 3 browsers ignore `'self'` and
  * host sources, so every script on the page must then carry the nonce.
+ * @internal
  */
 declare function buildScriptSrcWithNonce(nonce: string, options?: {
     readonly self?: boolean;
@@ -898,12 +1033,14 @@ declare function isAuthorizedPreviewContext(value: unknown): value is Authorized
  * Where the runtime is running: framed, opened, or on a developer's machine.
  * Nothing reads bundler-injected variables; a Vite consumer passes
  * `import.meta.env.X` explicitly (docs/astro.md).
+ * @internal
  */
 declare function isInIframe(): boolean;
+/** @internal */
 declare function isInPopup(): boolean;
-/** An iframe or a popup; top-level navigation never starts the preview. */
+/** An iframe or a popup; top-level navigation never starts the preview. @internal */
 declare function isInPreviewContext(): boolean;
-/** Under Node, `NODE_ENV !== 'production'`; in a browser the hostname, which is the only signal a bundle has. */
+/** Under Node, `NODE_ENV !== 'production'`; in a browser the hostname, which is the only signal a bundle has. @internal */
 declare function isDevMode(): boolean;
 
 /**
@@ -945,6 +1082,7 @@ declare class OriginDetector {
 }
 
 /** The locale for `Intl` renders before Payload names one: `<html lang>`, then `navigator.language`, then `'en'`. */
+/** @internal */
 declare function detectInitialLocale(): string;
 
 /**
@@ -952,10 +1090,11 @@ declare function detectInitialLocale(): string;
  * announces or by observation, since the stock Payload admin announces none:
  * what it can do is read off the messages it sends. See ADR 0010.
  */
-/** Bumped only when this library's understanding of the wire format changes. */
+/** Bumped only when this library's understanding of the wire format changes. @internal */
 declare const LIBRARY_PROTOCOL_VERSION = 4;
-/** How a capability becomes active. */
+/** How a capability becomes active. @internal */
 type CapabilitySource = 'version' | 'observed';
+/** @internal */
 interface CapabilityDeclaration {
     /** Enabled once the negotiated version reaches this (for announced peers). */
     readonly since: number;
@@ -995,7 +1134,7 @@ declare const CAPABILITY_DECLARATIONS: {
     };
 };
 type ProtocolCapability = keyof typeof CAPABILITY_DECLARATIONS;
-/** Every declared capability, in declaration order. */
+/** Every declared capability, in declaration order. @internal */
 declare const PROTOCOL_CAPABILITIES: readonly ProtocolCapability[];
 interface ProtocolNegotiation {
     /** This library's protocol version. */
@@ -1011,6 +1150,7 @@ interface ProtocolNegotiation {
 }
 /** Deterministic; the runtime re-runs it whenever either input changes. */
 declare function negotiateProtocol(theirs: number | undefined, observed?: Iterable<ProtocolCapability>): ProtocolNegotiation;
+/** @internal */
 declare function hasCapability(negotiation: ProtocolNegotiation, capability: ProtocolCapability): boolean;
 
 /**
@@ -1056,15 +1196,48 @@ interface ProtocolProfile {
  */
 declare function detectProtocolProfile(observed: ReadonlySet<ProtocolCapability>): ProtocolProfile;
 
+/**
+ * The seam between a host framework's own router and the route strategy.
+ *
+ * The route strategy answers a revision by fetching the route and morphing it
+ * into the living page. On a page whose DOM belongs to a reconciler that is
+ * working against the framework, and it was seen to break once: `removeChild`
+ * on `null` inside React's commit phase, over markup this package had patched.
+ * A host that re-renders the route itself does the same job without the morph
+ * and without the second HTML request, so it is given the chance to.
+ *
+ * Why a named slot on `window` and not a reference: the runtime is an inline
+ * script that builds its strategy before any application code has hydrated, so
+ * there is nothing to hand a component; `window.__livePreview`, the only other
+ * public surface, is created later and not at all outside a preview; and the
+ * two richer extension points — plugins and events — are reachable only through
+ * the programmatic client, which a page using an adapter does not have. One
+ * slot, written by whoever mounts and read at the moment of a refresh, is the
+ * smallest thing that survives both orders of arrival.
+ */
+/**
+ * A host's own route refresh. It must settle once the fresh markup is
+ * committed: the runtime re-applies the revision on top of it, and doing that
+ * against the markup being replaced would write into nodes about to be dropped.
+ */
+type RouteRefresh = () => void | Promise<void>;
+/**
+ * Lend the runtime the host's route refresh; the return value undoes it, for a
+ * component's cleanup. A later registration wins, and undoing one that has
+ * already been replaced does nothing — two components on one page would
+ * otherwise take the slot from each other on unmount.
+ */
+declare function registerRouteRefresh(refresh: RouteRefresh): () => void;
+
 /** Type-level field paths, so a binding name is checked at compile time against the codegen schema. */
 /** String keys of `T`. */
 type FieldName<T> = Extract<keyof T, string>;
-/** Dotted paths into `T`, capped at three levels so IntelliSense stays usable. */
+/** Dotted paths into `T`, capped at three levels so IntelliSense stays usable. @internal */
 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;
 type Prev<N extends 0 | 1 | 2 | 3> = N extends 3 ? 2 : N extends 2 ? 1 : N extends 1 ? 0 : 0;
-/** The value type at a dotted path, or `unknown` when the path does not exist. */
+/** The value type at a dotted path, or `unknown` when the path does not exist. @internal */
 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;
 
 /**
@@ -1116,15 +1289,25 @@ declare function bindByPath<T = Record<string, unknown>>(picker: (data: T) => un
 interface OwnerBindingAttributes {
     readonly 'data-payload-owner': string;
 }
+/** The attributes marking a server-rendered boundary (ADR 0011, docs/hybrid.md). */
+interface FragmentBoundaryAttributes {
+    readonly 'data-payload-fragment': string;
+    readonly 'data-payload-fragment-key'?: string;
+    readonly 'data-payload-depends'?: string;
+}
+interface FragmentBoundaryOptions {
+    /** Distinguishes boundaries when one registry id renders several on a page. */
+    readonly key?: string;
+    /** The fields that re-render the boundary. Without it, every update does. */
+    readonly dependsOn?: readonly string[];
+}
 /** No attributes at all: an unauthorized response is byte-identical to one that never knew about live preview. */
 type SuppressedBinding = Readonly<Record<string, never>>;
-interface PreviewBindingsCommonOptions {
-    /** Document this subtree belongs to, emitted as `data-payload-owner`; needed with `scopeBindingsByOwner`. */
-    readonly owner?: string;
-}
 /** The verdict from `authorizePreviewRequest()`, or `null` for a public response. Only a branded context authorizes emission. */
-interface PreviewBindingsOptions extends PreviewBindingsCommonOptions {
+interface PreviewBindingsOptions {
     readonly authorization: AuthorizedPreviewContext | null;
+    /** Document this subtree belongs to, emitted as `data-payload-owner`; needed with `scopeBindingsByOwner`. */
+    readonly owner?: string;
 }
 /** Request-scoped binding helpers carrying one authorization decision. */
 interface PreviewBindings {
@@ -1135,6 +1318,12 @@ interface PreviewBindings {
     bindByPath: <T = Record<string, unknown>>(picker: (data: T) => unknown, options?: BindOptions) => FieldBindingAttributes | SuppressedBinding;
     /** Owner marker for this subtree, or nothing while unauthorized or without an owner. */
     owner: () => OwnerBindingAttributes | SuppressedBinding;
+    /**
+     * A server-rendered boundary, or nothing while unauthorized — the id and the
+     * fields it depends on describe the content model as much as a binding does.
+     * The registry behind `id` is the endpoint's (docs/hybrid.md).
+     */
+    boundary: (id: string, options?: FragmentBoundaryOptions) => FragmentBoundaryAttributes | SuppressedBinding;
 }
 /** Request-scoped `bind`, `bindByPath` and `owner`, all suppressed unless `authorization` is a real context. */
 declare function createPreviewBindings(options: PreviewBindingsOptions): PreviewBindings;
@@ -1143,6 +1332,7 @@ declare function createPreviewBindings(options: PreviewBindingsOptions): Preview
  * Hydrated islands own their subtree, so the runtime never patches inside one.
  * Instead every flush dispatches `payload-live-preview:update` on each island
  * root with the update in `detail`. `data-payload-island="patch"` opts back in.
+ * @internal
  */
 declare const ISLAND_EVENT = "payload-live-preview:update";
 interface IslandUpdateDetail {
@@ -1151,7 +1341,7 @@ interface IslandUpdateDetail {
     readonly receivedAt: number;
     readonly locale: string | undefined;
 }
-/** Whether `element` (or an ancestor) is an island that did not opt into patching. */
+/** Whether `element` (or an ancestor) is an island that did not opt into patching. @internal */
 declare function isInsideIsland(element: Element): boolean;
 
 /**
@@ -1173,6 +1363,7 @@ declare function isInsideIsland(element: Element): boolean;
  * @packageDocumentation
  */
 
+/** @internal */
 declare const CORE_ENTRY = true;
 
-export { AUTHORIZED_PREVIEW_BRAND_KEY, type AuthorizedPreviewContext, 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 FragmentContext, type FragmentReport, type FragmentStrategy, type FrameAncestorsOptions, ISLAND_EVENT, type InspectionBindings, 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 PreviewBindingsCommonOptions, type PreviewBindingsOptions, type ProtocolCapability, type ProtocolNegotiation, type ProtocolProfile, type ProtocolProfileName, type RenderContext, type RendererKey, type RichTextRenderer, type RouteContext, 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, sanitizeHtml, setCspCrypto, setSanitizerDocument };
+export { AUTHORIZED_PREVIEW_BRAND_KEY, type AuthorizedPreviewContext, 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 RichTextRenderer, type RouteContext, type RouteOutcome, 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 };