payload-live-preview 1.4.0 → 1.5.0

package/dist/core.d.cts

@@ -1,3 +1,141 @@
+/**
+ * Connection state + heartbeat.
+ *
+ * Tracks whether the runtime is currently receiving updates from a
+ * trusted origin and fires a callback when the heartbeat times out.
+ *
+ * The heartbeat is reset on every valid message and considered dead
+ * after `timeoutMs` of silence. The host typically responds by
+ * re-sending the `ready` handshake to attempt reconnection.
+ *
+ * @module @core/state
+ */
+type ConnectionStatus = 'disconnected' | 'connecting' | 'connected';
+
+/**
+ * The shape of a live-preview inspection snapshot.
+ *
+ * This module is types only. The snapshot is assembled by
+ * `LivePreviewRuntime.inspect()` as a plain object literal, because the inline
+ * runtime pays for every byte of indirection and the assembly needs access to
+ * internal state the runtime does not otherwise expose.
+ *
+ * A snapshot is a read of what the runtime already holds. It discloses nothing
+ * that is not already observable on the page: the trusted origins are inside
+ * the injected script, the field names are `data-payload-field` attributes in
+ * the DOM, and the counters are derived from those. It is therefore available
+ * in production rather than gated to development builds — a preview that
+ * misbehaves only on the deployed site is exactly the case where the
+ * information is worth having, and a development-only gate would withhold it
+ * there.
+ *
+ * Nothing here is transmitted anywhere. Reading a snapshot performs no I/O.
+ *
+ * @module @core/inspection/types
+ */
+
+/** Origin trust as the runtime currently sees it. */
+interface InspectionOrigins {
+    /**
+     * Origins the runtime is willing to accept messages from, as configured.
+     * An empty list means no explicit allow-list was given, which is the
+     * condition under which referrer and localhost heuristics decide instead.
+     */
+    readonly trusted: readonly string[];
+    /**
+     * The origin the runtime locked onto after its first accepted update, or
+     * `undefined` while still unlocked. Once locked, every other origin is
+     * refused for the rest of the session.
+     */
+    readonly locked: string | undefined;
+}
+/** Protocol versions and the capabilities they enable. */
+interface InspectionProtocol {
+    /** This library's protocol version. */
+    readonly ours: number;
+    /** The remote party's version, or `undefined` if it never announced one. */
+    readonly theirs: number | undefined;
+    /** `min(ours, theirs ?? 1)` — what both sides actually share. */
+    readonly negotiated: number;
+    /** Capability flags enabled at the negotiated version. */
+    readonly capabilities: readonly string[];
+}
+/** Revision accounting for the update pipeline. */
+interface InspectionRevisions {
+    /** Updates accepted since the runtime started. */
+    readonly accepted: number;
+    /**
+     * Updates that were still in flight when a newer one arrived and were
+     * therefore abandoned. A number that tracks `accepted` closely means the
+     * editor is out-typing the pipeline, which is normal; it is only a problem
+     * when the last update is among the abandoned ones.
+     */
+    readonly superseded: number;
+    /** Revision currently in flight, or `undefined` when the pipeline is idle. */
+    readonly active: number | undefined;
+}
+/** What the DOM offers the runtime to write into. */
+interface InspectionBindings {
+    /** Elements carrying a binding. */
+    readonly elements: number;
+    /** Distinct field names across those elements. */
+    readonly fields: number;
+    /** Those field names, sorted. */
+    readonly fieldNames: readonly string[];
+    /**
+     * Field names that arrived in an update but matched no binding, as far as
+     * the runtime has observed. This is the list to read when a field refuses
+     * to update: a name here is a markup problem, a name absent from here and
+     * from `fieldNames` was never sent.
+     */
+    readonly orphanFields: readonly string[];
+    /** Whether `scopeBindingsByOwner` is active. */
+    readonly ownerScoped: boolean;
+    /** Distinct document owners currently on the page, sorted. */
+    readonly owners: readonly string[];
+}
+/** Scheduler work in progress. */
+interface InspectionScheduler {
+    /** Writes buffered for the next flush. */
+    readonly pending: number;
+    /**
+     * Writes held back because their element is offscreen and the binding count
+     * is above `visibilityGateThreshold`. These are applied when the element
+     * scrolls into view — never, on a page nobody scrolls.
+     */
+    readonly deferred: number;
+    /** The binding count above which the visibility gate starts deferring. */
+    readonly visibilityGateThreshold: number;
+    /** Whether the binding count is above that threshold right now. */
+    readonly visibilityGateActive: boolean;
+    /** Stats of the most recent flush, or `undefined` if none has run. */
+    readonly lastFlush: {
+        readonly applied: number;
+        readonly deferred: number;
+        readonly durationMs: number;
+    } | undefined;
+}
+/**
+ * A point-in-time read of runtime state, for diagnosing a preview that is not
+ * behaving. Every field is a plain value; the snapshot holds no references
+ * into runtime internals and does not change after it is returned.
+ */
+interface LivePreviewInspection {
+    /** Package version that produced this snapshot. */
+    readonly version: string;
+    /** Whether the runtime is started, and whether it has been destroyed. */
+    readonly started: boolean;
+    /** Connection status as reported to the `connect`/`disconnect` events. */
+    readonly status: ConnectionStatus;
+    readonly origins: InspectionOrigins;
+    readonly protocol: InspectionProtocol;
+    readonly revisions: InspectionRevisions;
+    readonly bindings: InspectionBindings;
+    readonly scheduler: InspectionScheduler;
+    /** Field types with a registered renderer, sorted. */
+    readonly renderers: readonly string[];
+}
+
 /**
  * Payload Live Preview message protocol.
  *
@@ -113,6 +251,101 @@ type PayloadFieldType = 'text' | 'textarea' | 'richText' | 'email' | 'number' |
  */
 type PayloadFieldCondition = (data: unknown, siblingData: unknown) => boolean;
 
+/**
+ * Stable identifiers for everything the runtime reports.
+ *
+ * Prose gets reworded; a code does not. A consumer filtering logs, an alert
+ * rule, or a bug report referring to `LP0301` keeps meaning the same thing
+ * after the sentence around it is rewritten, and a code is greppable in a way
+ * that a sentence fragment is not.
+ *
+ * Codes are grouped by the question they answer:
+ *
+ * - `LP01xx` — configuration and origin trust: the runtime is running, but it
+ *   was set up in a way that will bite.
+ * - `LP02xx` — bindings and markup: an update had nowhere to land.
+ * - `LP03xx` — updates and scheduling: the update landed somewhere other than
+ *   the DOM, or not yet.
+ * - `LP04xx` — rendering: a value reached an element and was refused.
+ * - `LP05xx` — protocol and messages: something arrived that was not accepted.
+ * - `LP06xx` — consumer callbacks: code the consumer supplied threw.
+ * - `LP07xx` — audit findings from `pll doctor`, which reports on a served
+ *   response rather than on a running runtime.
+ *
+ * A code is part of the public contract. Codes are never reused for a
+ * different meaning and never renumbered; a retired code stays retired.
+ * `LP0604` is unassigned: a throwing token validator is deliberately treated
+ * as a rejection and reported as `LP0502`, so there is nothing distinct to
+ * report yet. The number stays reserved rather than being handed to something
+ * else.
+ *
+ * The runtime writes these as string literals at each reporting site rather
+ * than reading them from this record, so the inline build pays for the six
+ * characters it prints and nothing more. This record exists so consumers can
+ * refer to a code by name instead of copying a literal.
+ *
+ * @module @core/diagnostic-codes
+ */
+/**
+ * Every diagnostic code the runtime can report, by name.
+ *
+ * ```ts
+ * client.events.on('error', (e) => {
+ *   if (e.code === DIAGNOSTIC_CODES.TransformThrew) reportToSentry(e.error);
+ * });
+ * ```
+ */
+declare const DIAGNOSTIC_CODES: Readonly<{
+    /** No trusted origin configured in production; nothing will be accepted. */
+    readonly NoTrustedOrigin: "LP0101";
+    /** Origin trust rests on `document.referrer`, so any framing site is trusted. */
+    readonly ReferrerOnlyTrust: "LP0102";
+    /** 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. */
+    readonly UnattributableUpdate: "LP0202";
+    /** 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. */
+    readonly UnsafeAttributeWrite: "LP0401";
+    /** A text element has structured children, so replacing its text was skipped. */
+    readonly TextTargetHasChildren: "LP0402";
+    /** A structural container has no array template, so the update was skipped. */
+    readonly MissingArrayTemplate: "LP0403";
+    /** A message was rejected before it reached the update pipeline. */
+    readonly MessageRejected: "LP0501";
+    /** A preview token was rejected. */
+    readonly TokenRejected: "LP0502";
+    /** A consumer event handler threw. */
+    readonly HandlerThrew: "LP0601";
+    /** A consumer transform threw; the original value was kept. */
+    readonly TransformThrew: "LP0602";
+    /** A renderer threw while writing a value. */
+    readonly RendererThrew: "LP0603";
+    /** Runtime startup failed. */
+    readonly StartupFailed: "LP0605";
+    /** Sending the ready handshake failed. */
+    readonly ReadyFailed: "LP0606";
+    /** 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. */
+    readonly AuditFrameOptionsBlocks: "LP0703";
+    /** Binding attributes are served to anonymous visitors. */
+    readonly AuditBindingsExposed: "LP0704";
+    /** More bindings than the default visibility gate will write eagerly. */
+    readonly AuditGateThresholdExceeded: "LP0705";
+    /** Owner markers exist, but some bindings are outside all of them. */
+    readonly AuditUnownedBindings: "LP0706";
+    /** The preview response carries no bindings at all. */
+    readonly AuditNoBindings: "LP0707";
+    /** The URL did not return an HTML page, so nothing else can be judged. */
+    readonly AuditNotAPage: "LP0708";
+}>;
+/** A diagnostic code, as it appears in log output and on the `error` event. */
+type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[keyof typeof DIAGNOSTIC_CODES];
+
 /**
  * Public event payload shapes for the live preview lifecycle.
  *
@@ -193,11 +426,14 @@ interface LivePreviewEventMap {
     /**
      * Fired on errors that the runtime caught but cannot fully recover from.
      *
-     * The `context` string identifies where the error originated.
+     * The `context` string identifies where the error originated. `code` says
+     * the same thing in a form that survives rewording — branch on `code`, read
+     * `context` when you want the human-readable origin.
      */
     readonly error: {
         readonly error: Error;
         readonly context: string;
+        readonly code: DiagnosticCode;
     };
     /**
      * Fired during destroy after browser observers and the message listener are
@@ -657,6 +893,15 @@ declare class LivePreviewClient {
     /** Current connection status. */
     get status(): 'disconnected' | 'connecting' | 'connected';
     /** Number of valid updates received so far. */
+    /**
+     * Point-in-time read of runtime state, for diagnosing a preview that is not
+     * updating. Performs no I/O and transmits nothing.
+     *
+     * Read `bindings.orphanFields` when a field refuses to update, and
+     * `scheduler.deferred` together with `scheduler.visibilityGateActive` when
+     * updates stop below the fold.
+     */
+    inspect(): LivePreviewInspection;
     get updateCount(): number;
     /** `true` once `destroy()` has been called. */
     get destroyed(): boolean;
@@ -1364,4 +1609,4 @@ declare function createPreviewBindings(options: PreviewBindingsOptions): Preview
 
 declare const CORE_ENTRY = true;
 
-export { type BindOptions, CORE_ENTRY, type CachedElement, EventEmitter, type EventHandler, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldType, type FrameAncestorsOptions, LIBRARY_PROTOCOL_VERSION, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, OriginDetector, type OwnerBindingAttributes, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PreviewBindings, type PreviewBindingsOptions, type ProtocolCapability, type ProtocolNegotiation, type RenderContext, type SanitizerDocument, type SuppressedBinding, type Unsubscribe, VERSION, type ValueAt, bind, bindByPath, buildFrameAncestors, buildScriptSrcWithNonce, createPreviewBindings, detectInitialLocale, escapeHtml, escapeHtmlAttribute, generateCspNonce, hasCapability, initLivePreview, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isSafeUrl, negotiateProtocol, sanitizeHtml, setCspCrypto, setSanitizerDocument };
+export { type BindOptions, CORE_ENTRY, type CachedElement, type ConnectionStatus, DIAGNOSTIC_CODES, type DiagnosticCode, EventEmitter, type EventHandler, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldType, type FrameAncestorsOptions, type InspectionBindings, type InspectionOrigins, type InspectionProtocol, type InspectionRevisions, type InspectionScheduler, LIBRARY_PROTOCOL_VERSION, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewInspection, OriginDetector, type OwnerBindingAttributes, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PreviewBindings, type PreviewBindingsOptions, type ProtocolCapability, type ProtocolNegotiation, type RenderContext, type SanitizerDocument, type SuppressedBinding, type Unsubscribe, VERSION, type ValueAt, bind, bindByPath, buildFrameAncestors, buildScriptSrcWithNonce, createPreviewBindings, detectInitialLocale, escapeHtml, escapeHtmlAttribute, generateCspNonce, hasCapability, initLivePreview, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isSafeUrl, negotiateProtocol, sanitizeHtml, setCspCrypto, setSanitizerDocument };

package/dist/core.d.ts

@@ -1,3 +1,141 @@
+/**
+ * Connection state + heartbeat.
+ *
+ * Tracks whether the runtime is currently receiving updates from a
+ * trusted origin and fires a callback when the heartbeat times out.
+ *
+ * The heartbeat is reset on every valid message and considered dead
+ * after `timeoutMs` of silence. The host typically responds by
+ * re-sending the `ready` handshake to attempt reconnection.
+ *
+ * @module @core/state
+ */
+type ConnectionStatus = 'disconnected' | 'connecting' | 'connected';
+
+/**
+ * The shape of a live-preview inspection snapshot.
+ *
+ * This module is types only. The snapshot is assembled by
+ * `LivePreviewRuntime.inspect()` as a plain object literal, because the inline
+ * runtime pays for every byte of indirection and the assembly needs access to
+ * internal state the runtime does not otherwise expose.
+ *
+ * A snapshot is a read of what the runtime already holds. It discloses nothing
+ * that is not already observable on the page: the trusted origins are inside
+ * the injected script, the field names are `data-payload-field` attributes in
+ * the DOM, and the counters are derived from those. It is therefore available
+ * in production rather than gated to development builds — a preview that
+ * misbehaves only on the deployed site is exactly the case where the
+ * information is worth having, and a development-only gate would withhold it
+ * there.
+ *
+ * Nothing here is transmitted anywhere. Reading a snapshot performs no I/O.
+ *
+ * @module @core/inspection/types
+ */
+
+/** Origin trust as the runtime currently sees it. */
+interface InspectionOrigins {
+    /**
+     * Origins the runtime is willing to accept messages from, as configured.
+     * An empty list means no explicit allow-list was given, which is the
+     * condition under which referrer and localhost heuristics decide instead.
+     */
+    readonly trusted: readonly string[];
+    /**
+     * The origin the runtime locked onto after its first accepted update, or
+     * `undefined` while still unlocked. Once locked, every other origin is
+     * refused for the rest of the session.
+     */
+    readonly locked: string | undefined;
+}
+/** Protocol versions and the capabilities they enable. */
+interface InspectionProtocol {
+    /** This library's protocol version. */
+    readonly ours: number;
+    /** The remote party's version, or `undefined` if it never announced one. */
+    readonly theirs: number | undefined;
+    /** `min(ours, theirs ?? 1)` — what both sides actually share. */
+    readonly negotiated: number;
+    /** Capability flags enabled at the negotiated version. */
+    readonly capabilities: readonly string[];
+}
+/** Revision accounting for the update pipeline. */
+interface InspectionRevisions {
+    /** Updates accepted since the runtime started. */
+    readonly accepted: number;
+    /**
+     * Updates that were still in flight when a newer one arrived and were
+     * therefore abandoned. A number that tracks `accepted` closely means the
+     * editor is out-typing the pipeline, which is normal; it is only a problem
+     * when the last update is among the abandoned ones.
+     */
+    readonly superseded: number;
+    /** Revision currently in flight, or `undefined` when the pipeline is idle. */
+    readonly active: number | undefined;
+}
+/** What the DOM offers the runtime to write into. */
+interface InspectionBindings {
+    /** Elements carrying a binding. */
+    readonly elements: number;
+    /** Distinct field names across those elements. */
+    readonly fields: number;
+    /** Those field names, sorted. */
+    readonly fieldNames: readonly string[];
+    /**
+     * Field names that arrived in an update but matched no binding, as far as
+     * the runtime has observed. This is the list to read when a field refuses
+     * to update: a name here is a markup problem, a name absent from here and
+     * from `fieldNames` was never sent.
+     */
+    readonly orphanFields: readonly string[];
+    /** Whether `scopeBindingsByOwner` is active. */
+    readonly ownerScoped: boolean;
+    /** Distinct document owners currently on the page, sorted. */
+    readonly owners: readonly string[];
+}
+/** Scheduler work in progress. */
+interface InspectionScheduler {
+    /** Writes buffered for the next flush. */
+    readonly pending: number;
+    /**
+     * Writes held back because their element is offscreen and the binding count
+     * is above `visibilityGateThreshold`. These are applied when the element
+     * scrolls into view — never, on a page nobody scrolls.
+     */
+    readonly deferred: number;
+    /** The binding count above which the visibility gate starts deferring. */
+    readonly visibilityGateThreshold: number;
+    /** Whether the binding count is above that threshold right now. */
+    readonly visibilityGateActive: boolean;
+    /** Stats of the most recent flush, or `undefined` if none has run. */
+    readonly lastFlush: {
+        readonly applied: number;
+        readonly deferred: number;
+        readonly durationMs: number;
+    } | undefined;
+}
+/**
+ * A point-in-time read of runtime state, for diagnosing a preview that is not
+ * behaving. Every field is a plain value; the snapshot holds no references
+ * into runtime internals and does not change after it is returned.
+ */
+interface LivePreviewInspection {
+    /** Package version that produced this snapshot. */
+    readonly version: string;
+    /** Whether the runtime is started, and whether it has been destroyed. */
+    readonly started: boolean;
+    /** Connection status as reported to the `connect`/`disconnect` events. */
+    readonly status: ConnectionStatus;
+    readonly origins: InspectionOrigins;
+    readonly protocol: InspectionProtocol;
+    readonly revisions: InspectionRevisions;
+    readonly bindings: InspectionBindings;
+    readonly scheduler: InspectionScheduler;
+    /** Field types with a registered renderer, sorted. */
+    readonly renderers: readonly string[];
+}
+
 /**
  * Payload Live Preview message protocol.
  *
@@ -113,6 +251,101 @@ type PayloadFieldType = 'text' | 'textarea' | 'richText' | 'email' | 'number' |
  */
 type PayloadFieldCondition = (data: unknown, siblingData: unknown) => boolean;
 
+/**
+ * Stable identifiers for everything the runtime reports.
+ *
+ * Prose gets reworded; a code does not. A consumer filtering logs, an alert
+ * rule, or a bug report referring to `LP0301` keeps meaning the same thing
+ * after the sentence around it is rewritten, and a code is greppable in a way
+ * that a sentence fragment is not.
+ *
+ * Codes are grouped by the question they answer:
+ *
+ * - `LP01xx` — configuration and origin trust: the runtime is running, but it
+ *   was set up in a way that will bite.
+ * - `LP02xx` — bindings and markup: an update had nowhere to land.
+ * - `LP03xx` — updates and scheduling: the update landed somewhere other than
+ *   the DOM, or not yet.
+ * - `LP04xx` — rendering: a value reached an element and was refused.
+ * - `LP05xx` — protocol and messages: something arrived that was not accepted.
+ * - `LP06xx` — consumer callbacks: code the consumer supplied threw.
+ * - `LP07xx` — audit findings from `pll doctor`, which reports on a served
+ *   response rather than on a running runtime.
+ *
+ * A code is part of the public contract. Codes are never reused for a
+ * different meaning and never renumbered; a retired code stays retired.
+ * `LP0604` is unassigned: a throwing token validator is deliberately treated
+ * as a rejection and reported as `LP0502`, so there is nothing distinct to
+ * report yet. The number stays reserved rather than being handed to something
+ * else.
+ *
+ * The runtime writes these as string literals at each reporting site rather
+ * than reading them from this record, so the inline build pays for the six
+ * characters it prints and nothing more. This record exists so consumers can
+ * refer to a code by name instead of copying a literal.
+ *
+ * @module @core/diagnostic-codes
+ */
+/**
+ * Every diagnostic code the runtime can report, by name.
+ *
+ * ```ts
+ * client.events.on('error', (e) => {
+ *   if (e.code === DIAGNOSTIC_CODES.TransformThrew) reportToSentry(e.error);
+ * });
+ * ```
+ */
+declare const DIAGNOSTIC_CODES: Readonly<{
+    /** No trusted origin configured in production; nothing will be accepted. */
+    readonly NoTrustedOrigin: "LP0101";
+    /** Origin trust rests on `document.referrer`, so any framing site is trusted. */
+    readonly ReferrerOnlyTrust: "LP0102";
+    /** 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. */
+    readonly UnattributableUpdate: "LP0202";
+    /** 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. */
+    readonly UnsafeAttributeWrite: "LP0401";
+    /** A text element has structured children, so replacing its text was skipped. */
+    readonly TextTargetHasChildren: "LP0402";
+    /** A structural container has no array template, so the update was skipped. */
+    readonly MissingArrayTemplate: "LP0403";
+    /** A message was rejected before it reached the update pipeline. */
+    readonly MessageRejected: "LP0501";
+    /** A preview token was rejected. */
+    readonly TokenRejected: "LP0502";
+    /** A consumer event handler threw. */
+    readonly HandlerThrew: "LP0601";
+    /** A consumer transform threw; the original value was kept. */
+    readonly TransformThrew: "LP0602";
+    /** A renderer threw while writing a value. */
+    readonly RendererThrew: "LP0603";
+    /** Runtime startup failed. */
+    readonly StartupFailed: "LP0605";
+    /** Sending the ready handshake failed. */
+    readonly ReadyFailed: "LP0606";
+    /** 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. */
+    readonly AuditFrameOptionsBlocks: "LP0703";
+    /** Binding attributes are served to anonymous visitors. */
+    readonly AuditBindingsExposed: "LP0704";
+    /** More bindings than the default visibility gate will write eagerly. */
+    readonly AuditGateThresholdExceeded: "LP0705";
+    /** Owner markers exist, but some bindings are outside all of them. */
+    readonly AuditUnownedBindings: "LP0706";
+    /** The preview response carries no bindings at all. */
+    readonly AuditNoBindings: "LP0707";
+    /** The URL did not return an HTML page, so nothing else can be judged. */
+    readonly AuditNotAPage: "LP0708";
+}>;
+/** A diagnostic code, as it appears in log output and on the `error` event. */
+type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[keyof typeof DIAGNOSTIC_CODES];
+
 /**
  * Public event payload shapes for the live preview lifecycle.
  *
@@ -193,11 +426,14 @@ interface LivePreviewEventMap {
     /**
      * Fired on errors that the runtime caught but cannot fully recover from.
      *
-     * The `context` string identifies where the error originated.
+     * The `context` string identifies where the error originated. `code` says
+     * the same thing in a form that survives rewording — branch on `code`, read
+     * `context` when you want the human-readable origin.
      */
     readonly error: {
         readonly error: Error;
         readonly context: string;
+        readonly code: DiagnosticCode;
     };
     /**
      * Fired during destroy after browser observers and the message listener are
@@ -657,6 +893,15 @@ declare class LivePreviewClient {
     /** Current connection status. */
     get status(): 'disconnected' | 'connecting' | 'connected';
     /** Number of valid updates received so far. */
+    /**
+     * Point-in-time read of runtime state, for diagnosing a preview that is not
+     * updating. Performs no I/O and transmits nothing.
+     *
+     * Read `bindings.orphanFields` when a field refuses to update, and
+     * `scheduler.deferred` together with `scheduler.visibilityGateActive` when
+     * updates stop below the fold.
+     */
+    inspect(): LivePreviewInspection;
     get updateCount(): number;
     /** `true` once `destroy()` has been called. */
     get destroyed(): boolean;
@@ -1364,4 +1609,4 @@ declare function createPreviewBindings(options: PreviewBindingsOptions): Preview
 
 declare const CORE_ENTRY = true;
 
-export { type BindOptions, CORE_ENTRY, type CachedElement, EventEmitter, type EventHandler, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldType, type FrameAncestorsOptions, LIBRARY_PROTOCOL_VERSION, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, OriginDetector, type OwnerBindingAttributes, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PreviewBindings, type PreviewBindingsOptions, type ProtocolCapability, type ProtocolNegotiation, type RenderContext, type SanitizerDocument, type SuppressedBinding, type Unsubscribe, VERSION, type ValueAt, bind, bindByPath, buildFrameAncestors, buildScriptSrcWithNonce, createPreviewBindings, detectInitialLocale, escapeHtml, escapeHtmlAttribute, generateCspNonce, hasCapability, initLivePreview, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isSafeUrl, negotiateProtocol, sanitizeHtml, setCspCrypto, setSanitizerDocument };
+export { type BindOptions, CORE_ENTRY, type CachedElement, type ConnectionStatus, DIAGNOSTIC_CODES, type DiagnosticCode, EventEmitter, type EventHandler, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldType, type FrameAncestorsOptions, type InspectionBindings, type InspectionOrigins, type InspectionProtocol, type InspectionRevisions, type InspectionScheduler, LIBRARY_PROTOCOL_VERSION, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewInspection, OriginDetector, type OwnerBindingAttributes, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PreviewBindings, type PreviewBindingsOptions, type ProtocolCapability, type ProtocolNegotiation, type RenderContext, type SanitizerDocument, type SuppressedBinding, type Unsubscribe, VERSION, type ValueAt, bind, bindByPath, buildFrameAncestors, buildScriptSrcWithNonce, createPreviewBindings, detectInitialLocale, escapeHtml, escapeHtmlAttribute, generateCspNonce, hasCapability, initLivePreview, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isSafeUrl, negotiateProtocol, sanitizeHtml, setCspCrypto, setSanitizerDocument };