payload-live-preview 1.2.2 → 1.4.0

package/dist/index.d.cts

@@ -634,6 +634,25 @@ declare class LivePreviewClient {
      * roll back, and be retried by a later call.
      */
     start(): boolean;
+    /**
+     * Release the message ingress while keeping this client usable.
+     *
+     * For the document lifecycle, not for teardown: a back/forward-cache restore
+     * does not re-run module scripts, so a client that stays attached across
+     * `pagehide` returns bound to a frozen page and silently stops updating.
+     * Plugins, renderers and transforms survive; `resume()` brings the same
+     * client back. Returns `false` when there was nothing running to suspend.
+     */
+    suspend(): boolean;
+    /**
+     * Reacquire after `suspend()`.
+     *
+     * Deliberately the same path as `start()`: a restored document needs the
+     * cache rebuilt, the observers rebound and the handshake rebroadcast, which
+     * is exactly what starting does. Returns `false` for a destroyed client or
+     * one that was never started.
+     */
+    resume(): boolean;
     /**
      * Stop the runtime and tear down every plugin. Idempotent.
      */
@@ -664,6 +683,58 @@ declare class LivePreviewClient {
  */
 declare function initLivePreview(config?: LivePreviewClientConfig): LivePreviewClient | null;
 
+/**
+ * Document-lifecycle owner for the live-preview client.
+ *
+ * The runtime learns about messages, not about navigation. Two browser
+ * behaviours make that gap visible, and both are silent:
+ *
+ *   - A **back/forward-cache restore** does not re-run module scripts. A client
+ *     that stays attached across `pagehide` comes back bound to a document the
+ *     browser froze and thawed, and simply stops updating.
+ *   - A **soft navigation** replaces page content without a new document. The
+ *     bindings the cache holds are gone, and nothing tells the runtime.
+ *
+ * This binds both to `suspend()`/`resume()`/`refreshCache()` in one place, so a
+ * consumer that uses no framework adapter can own the lifecycle with one call
+ * instead of re-deriving it — which is what every integration has had to do so
+ * far.
+ *
+ * @module @client/navigation-lifecycle
+ */
+/** The part of the client this owner drives. */
+interface NavigationLifecycleTarget {
+    suspend(): boolean;
+    resume(): boolean;
+    refreshCache(): void;
+}
+interface NavigationLifecycleOptions {
+    /**
+     * Event target for `pagehide`/`pageshow`. Defaults to `window`.
+     *
+     * These fire on the window, not the document, and only there — binding them
+     * anywhere else silently never fires.
+     */
+    readonly windowTarget?: EventTarget;
+    /**
+     * Event target for soft-navigation events. Defaults to `document`.
+     */
+    readonly documentTarget?: EventTarget;
+    /**
+     * Soft-navigation events after which the DOM has been replaced and the
+     * binding cache has to be rebuilt — for example `astro:page-load`.
+     *
+     * Empty by default: the package cannot know which framework is present, and
+     * guessing would either miss the event or rebuild on an unrelated one.
+     */
+    readonly softNavigationEvents?: readonly string[];
+}
+/**
+ * Bind the document lifecycle. Returns an unbind function; calling it twice is
+ * harmless.
+ */
+declare function bindNavigationLifecycle(target: NavigationLifecycleTarget, options?: NavigationLifecycleOptions): () => void;
+
 interface RuntimeBuildInfo {
     readonly generatedAt: string;
     readonly size: number;
@@ -1925,4 +1996,4 @@ interface PreviewBindings {
  */
 declare function createPreviewBindings(options: PreviewBindingsOptions): PreviewBindings;
 
-export { type AnalyticsSnapshot, type BindOptions, type BlockRenderContext, type BlockRenderer, type CachedElement, type CspDirectiveMerge, type DocumentSaveHandler, type DocumentSavePluginOptions, type DocumentSaveStrategy, EventEmitter, type EventHandler, type FetchPreviewDocumentOptions, type FetchPreviewGlobalOptions, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldTransform, type FieldType, type FrameAncestorsOptions, type InlineScriptConfig, LIBRARY_PROTOCOL_VERSION, type LexicalNode, type LexicalRoot, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewPlugin, OriginDetector, type OwnerBindingAttributes, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PayloadMedia, type PayloadRelationship, type PluginContext, type PluginDisposer, type PluginEvents, type PreviewBindings, type PreviewBindingsOptions, type PreviewFetchBaseOptions, type PreviewRequestLike, type PreviewRequestOptions, type PreviewWhere, type ProtocolCapability, type ProtocolNegotiation, type RenderContext, type SanitizerDocument, type SuppressedBinding, type Unsubscribe, VERSION, type ValueAt, bind, bindByPath, buildBuiltinRenderers, buildFrameAncestors, buildScriptSrcWithNonce, createAnalyticsPlugin, createPreviewBindings, debugPlugin, detectInitialLocale, documentSavePlugin, escapeHtml, escapeHtmlAttribute, fetchPreviewDocument, fetchPreviewGlobal, generateCspNonce, generateInlineScript, hasCapability, highlightPlugin, initLivePreview, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isLexicalContent, isPreviewRequest, isSafeUrl, lexicalToHtml, lexicalToPlainText, mergeCspHeader, negotiateProtocol, registerBlockRenderer, registerBuiltinRenderer, runtimeBuildInfo, sanitizeHtml, setCspCrypto, setSanitizerDocument, wrapWithScriptTag };
+export { type AnalyticsSnapshot, type BindOptions, type BlockRenderContext, type BlockRenderer, type CachedElement, type CspDirectiveMerge, type DocumentSaveHandler, type DocumentSavePluginOptions, type DocumentSaveStrategy, EventEmitter, type EventHandler, type FetchPreviewDocumentOptions, type FetchPreviewGlobalOptions, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldTransform, type FieldType, type FrameAncestorsOptions, type InlineScriptConfig, LIBRARY_PROTOCOL_VERSION, type LexicalNode, type LexicalRoot, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewPlugin, type NavigationLifecycleOptions, type NavigationLifecycleTarget, OriginDetector, type OwnerBindingAttributes, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PayloadMedia, type PayloadRelationship, type PluginContext, type PluginDisposer, type PluginEvents, type PreviewBindings, type PreviewBindingsOptions, type PreviewFetchBaseOptions, type PreviewRequestLike, type PreviewRequestOptions, type PreviewWhere, type ProtocolCapability, type ProtocolNegotiation, type RenderContext, type SanitizerDocument, type SuppressedBinding, type Unsubscribe, VERSION, type ValueAt, bind, bindByPath, bindNavigationLifecycle, buildBuiltinRenderers, buildFrameAncestors, buildScriptSrcWithNonce, createAnalyticsPlugin, createPreviewBindings, debugPlugin, detectInitialLocale, documentSavePlugin, escapeHtml, escapeHtmlAttribute, fetchPreviewDocument, fetchPreviewGlobal, generateCspNonce, generateInlineScript, hasCapability, highlightPlugin, initLivePreview, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isLexicalContent, isPreviewRequest, isSafeUrl, lexicalToHtml, lexicalToPlainText, mergeCspHeader, negotiateProtocol, registerBlockRenderer, registerBuiltinRenderer, runtimeBuildInfo, sanitizeHtml, setCspCrypto, setSanitizerDocument, wrapWithScriptTag };

package/dist/index.d.ts

@@ -634,6 +634,25 @@ declare class LivePreviewClient {
      * roll back, and be retried by a later call.
      */
     start(): boolean;
+    /**
+     * Release the message ingress while keeping this client usable.
+     *
+     * For the document lifecycle, not for teardown: a back/forward-cache restore
+     * does not re-run module scripts, so a client that stays attached across
+     * `pagehide` returns bound to a frozen page and silently stops updating.
+     * Plugins, renderers and transforms survive; `resume()` brings the same
+     * client back. Returns `false` when there was nothing running to suspend.
+     */
+    suspend(): boolean;
+    /**
+     * Reacquire after `suspend()`.
+     *
+     * Deliberately the same path as `start()`: a restored document needs the
+     * cache rebuilt, the observers rebound and the handshake rebroadcast, which
+     * is exactly what starting does. Returns `false` for a destroyed client or
+     * one that was never started.
+     */
+    resume(): boolean;
     /**
      * Stop the runtime and tear down every plugin. Idempotent.
      */
@@ -664,6 +683,58 @@ declare class LivePreviewClient {
  */
 declare function initLivePreview(config?: LivePreviewClientConfig): LivePreviewClient | null;
 
+/**
+ * Document-lifecycle owner for the live-preview client.
+ *
+ * The runtime learns about messages, not about navigation. Two browser
+ * behaviours make that gap visible, and both are silent:
+ *
+ *   - A **back/forward-cache restore** does not re-run module scripts. A client
+ *     that stays attached across `pagehide` comes back bound to a document the
+ *     browser froze and thawed, and simply stops updating.
+ *   - A **soft navigation** replaces page content without a new document. The
+ *     bindings the cache holds are gone, and nothing tells the runtime.
+ *
+ * This binds both to `suspend()`/`resume()`/`refreshCache()` in one place, so a
+ * consumer that uses no framework adapter can own the lifecycle with one call
+ * instead of re-deriving it — which is what every integration has had to do so
+ * far.
+ *
+ * @module @client/navigation-lifecycle
+ */
+/** The part of the client this owner drives. */
+interface NavigationLifecycleTarget {
+    suspend(): boolean;
+    resume(): boolean;
+    refreshCache(): void;
+}
+interface NavigationLifecycleOptions {
+    /**
+     * Event target for `pagehide`/`pageshow`. Defaults to `window`.
+     *
+     * These fire on the window, not the document, and only there — binding them
+     * anywhere else silently never fires.
+     */
+    readonly windowTarget?: EventTarget;
+    /**
+     * Event target for soft-navigation events. Defaults to `document`.
+     */
+    readonly documentTarget?: EventTarget;
+    /**
+     * Soft-navigation events after which the DOM has been replaced and the
+     * binding cache has to be rebuilt — for example `astro:page-load`.
+     *
+     * Empty by default: the package cannot know which framework is present, and
+     * guessing would either miss the event or rebuild on an unrelated one.
+     */
+    readonly softNavigationEvents?: readonly string[];
+}
+/**
+ * Bind the document lifecycle. Returns an unbind function; calling it twice is
+ * harmless.
+ */
+declare function bindNavigationLifecycle(target: NavigationLifecycleTarget, options?: NavigationLifecycleOptions): () => void;
+
 interface RuntimeBuildInfo {
     readonly generatedAt: string;
     readonly size: number;
@@ -1925,4 +1996,4 @@ interface PreviewBindings {
  */
 declare function createPreviewBindings(options: PreviewBindingsOptions): PreviewBindings;
 
-export { type AnalyticsSnapshot, type BindOptions, type BlockRenderContext, type BlockRenderer, type CachedElement, type CspDirectiveMerge, type DocumentSaveHandler, type DocumentSavePluginOptions, type DocumentSaveStrategy, EventEmitter, type EventHandler, type FetchPreviewDocumentOptions, type FetchPreviewGlobalOptions, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldTransform, type FieldType, type FrameAncestorsOptions, type InlineScriptConfig, LIBRARY_PROTOCOL_VERSION, type LexicalNode, type LexicalRoot, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewPlugin, OriginDetector, type OwnerBindingAttributes, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PayloadMedia, type PayloadRelationship, type PluginContext, type PluginDisposer, type PluginEvents, type PreviewBindings, type PreviewBindingsOptions, type PreviewFetchBaseOptions, type PreviewRequestLike, type PreviewRequestOptions, type PreviewWhere, type ProtocolCapability, type ProtocolNegotiation, type RenderContext, type SanitizerDocument, type SuppressedBinding, type Unsubscribe, VERSION, type ValueAt, bind, bindByPath, buildBuiltinRenderers, buildFrameAncestors, buildScriptSrcWithNonce, createAnalyticsPlugin, createPreviewBindings, debugPlugin, detectInitialLocale, documentSavePlugin, escapeHtml, escapeHtmlAttribute, fetchPreviewDocument, fetchPreviewGlobal, generateCspNonce, generateInlineScript, hasCapability, highlightPlugin, initLivePreview, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isLexicalContent, isPreviewRequest, isSafeUrl, lexicalToHtml, lexicalToPlainText, mergeCspHeader, negotiateProtocol, registerBlockRenderer, registerBuiltinRenderer, runtimeBuildInfo, sanitizeHtml, setCspCrypto, setSanitizerDocument, wrapWithScriptTag };
+export { type AnalyticsSnapshot, type BindOptions, type BlockRenderContext, type BlockRenderer, type CachedElement, type CspDirectiveMerge, type DocumentSaveHandler, type DocumentSavePluginOptions, type DocumentSaveStrategy, EventEmitter, type EventHandler, type FetchPreviewDocumentOptions, type FetchPreviewGlobalOptions, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldTransform, type FieldType, type FrameAncestorsOptions, type InlineScriptConfig, LIBRARY_PROTOCOL_VERSION, type LexicalNode, type LexicalRoot, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewPlugin, type NavigationLifecycleOptions, type NavigationLifecycleTarget, OriginDetector, type OwnerBindingAttributes, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PayloadMedia, type PayloadRelationship, type PluginContext, type PluginDisposer, type PluginEvents, type PreviewBindings, type PreviewBindingsOptions, type PreviewFetchBaseOptions, type PreviewRequestLike, type PreviewRequestOptions, type PreviewWhere, type ProtocolCapability, type ProtocolNegotiation, type RenderContext, type SanitizerDocument, type SuppressedBinding, type Unsubscribe, VERSION, type ValueAt, bind, bindByPath, bindNavigationLifecycle, buildBuiltinRenderers, buildFrameAncestors, buildScriptSrcWithNonce, createAnalyticsPlugin, createPreviewBindings, debugPlugin, detectInitialLocale, documentSavePlugin, escapeHtml, escapeHtmlAttribute, fetchPreviewDocument, fetchPreviewGlobal, generateCspNonce, generateInlineScript, hasCapability, highlightPlugin, initLivePreview, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isLexicalContent, isPreviewRequest, isSafeUrl, lexicalToHtml, lexicalToPlainText, mergeCspHeader, negotiateProtocol, registerBlockRenderer, registerBuiltinRenderer, runtimeBuildInfo, sanitizeHtml, setCspCrypto, setSanitizerDocument, wrapWithScriptTag };