@notionhq/custom-blocks-host 0.1.26 → 0.1.28

package/README.md

@@ -77,11 +77,8 @@ const host = createCustomBlockHost({
   onInitialized: state => {
     console.log("Initialized manifest", state.manifest)
   },
-  onInitializationFailure: error => {
-    showInitializationError(error)
-  },
-  onRestartRequired: () => {
-    remountHostAndIframe()
+  onFailure: error => {
+    showHostError(error)
   },
   onLog: (direction, payload) => {
     console.log(direction, payload)
@@ -93,7 +90,28 @@ const host = createCustomBlockHost({
 supports. Set a higher value to retire older SDKs. Lower values cannot enable versions the runtime
 no longer supports. The host does not enforce a maximum protocol version.
 
-Each host instance initializes once:
+Each host handles one initialization handshake with one sandbox iframe:
+
+- Create the host before navigating the iframe to the sandbox URL.
+- The host accepts the first `connect` attempt and ignores subsequent `connect` messages, including
+  malformed ones. A connection after an initialization timeout does not restart it.
+- The first observed iframe `load` is allowed, including when initialization completes before it.
+- A second observed `load` stops the host and reports retryable `iframe_reloaded` through
+  `onFailure`. A reload or navigation can replace the sandbox document, so the host ends the
+  connection instead of continuing to serve the replacement.
+- Stopping removes message and load listeners, clears initialization timers, ends query
+  subscriptions, and prevents further outbound messages, including pending responses.
+- To retry or apply a deployment or configuration change, the embedder creates a new host and
+  iframe. The host does not restart automatically.
+
+The stop takes effect at the second observed load. It does not prevent navigation or isolate the
+original document before that event: a replacement document at the same origin can receive messages
+and invoke handlers until the host stops.
+
+SDKs using protocol 5 or later support unavailable page context. For older SDKs, an unavailable
+initial page fails initialization with `context_unavailable`. If page context becomes unavailable
+after initialization, the host stops and reports the same error instead of sending an unsupported
+`pageChanged` message.
 
 - `onManifest` provides the selected manifest as soon as it is available after `connect`, before
   binding validation and `onInitialized`. Use it to configure bindings even when initialization
@@ -101,10 +119,8 @@ Each host instance initializes once:
 
 - `onInitialized` reports success after the sandbox accepts initialization. It provides the selected
   `manifest` and the sandbox's optional `initialHeight`.
-- `onInitializationFailure` reports an initialization error or timeout.
-- `onRestartRequired` reports a connection attempt after the host accepts its first connection or
-  stops waiting. Recreate the host and iframe together to accept a new connection. This can occur
-  after the iframe document changes or a connection arrives after a timeout.
+- `onFailure` reports a handshake failure, timeout, unavailable page context, or iframe reload. It
+  can run after initialization succeeds.
 
 The host uses the manifest from `connect`, or `initialState.manifest` if `connect` omits it. If
 neither exists, initialization fails with `manifest_unavailable`.
@@ -145,7 +161,7 @@ filter types fail protocol validation.
 host derive bindings from the sandbox-provided manifest.
 
 Set `sandboxOrigin` to the iframe's exact origin. The runtime targets outbound messages to that
-origin and rejects inbound messages from any other origin. The runtime also accepts
+origin and accepts inbound messages only from that iframe and origin. The runtime also accepts
 `noConnectTimeoutMs` and `noInitResultTimeoutMs`; both default to five seconds.
 
 ### Initialization and malformed messages
@@ -186,8 +202,7 @@ timeout. Malformed messages do not restart initialization after it succeeds or f
 The host accepts a valid `initResult.error` as a terminal initialization failure. It logs and
 ignores a valid `initResult` with a stale `initializationId` or an unexpected state.
 
-Hosts do not retry malformed messages. A host that receives a `connect` after initialization has
-settled must use `onRestartRequired` to recreate the host and iframe together.
+The host does not retry malformed messages.
 
 ## Updating live state
 
@@ -207,9 +222,10 @@ State updates are sent after `initResult.success`. Updates made earlier are held
 initialization completes. `refreshQuery()` re-runs `queryDataSource` for every active subscription
 with the supplied data source ID, preserving each subscription's filter, sorts, and limit.
 
-The runtime removes a subscription when it receives `unsubscribeDataSourceQuery`. Repeated
-unsubscribe messages are safe. The runtime also ignores results from a query that was unsubscribed
-while its handler was running.
+After `stop()`, the host drops outbound messages, including pending request responses. The runtime
+removes a subscription when it receives `unsubscribeDataSourceQuery`. Repeated unsubscribe messages
+are safe. The runtime also ignores results from a query that was unsubscribed while its handler was
+running.
 
 Call `stop()` when the iframe is removed. It detaches listeners, clears timeouts, and discards
 active query subscriptions.

package/dist/createCustomBlockHost.d.ts

@@ -7,7 +7,7 @@ import type { NotionParent } from "./protocol/parent.js";
 import type { NotionTheme } from "./protocol/theme.js";
 import type { NotionUser } from "./protocol/users/user.js";
 import type { CustomBlockHostDataSourcesPayload, CustomBlockHostInitialState } from "./lifecycle/types.js";
-import type { CustomBlockHostHandlers, CustomBlockHostInitializationFailure, CustomBlockHostLogDirection } from "./messages/types.js";
+import type { CustomBlockHostFailure, CustomBlockHostHandlers, CustomBlockHostLogDirection } from "./messages/types.js";
 export type CustomBlockHostOptions = {
     iframe: HTMLIFrameElement;
     sandboxOrigin: string;
@@ -31,12 +31,13 @@ export type CustomBlockHostOptions = {
         manifest: CustomBlockManifest;
         initialHeight?: number;
     }) => void;
-    /** Callback fired when the initialization handshake with the sandbox failed or timed out. */
-    onInitializationFailure?: (error: CustomBlockHostInitializationFailure) => void;
     /**
-     * Callback fired when the current host and iframe must restart. Recreate both to continue.
+     * Reports a handshake failure, timeout, unavailable page context, or iframe reload.
+     * Iframe reloads and unavailable page context for older SDKs stop the host
+     * before this callback runs.
+     * This callback can run after initialization succeeds.
      */
-    onRestartRequired?: () => void;
+    onFailure?: (error: CustomBlockHostFailure) => void;
     onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void;
 };
 export type CustomBlockHostHandle = {

package/dist/createCustomBlockHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createCustomBlockHost.d.ts","sourceRoot":"","sources":["../src/createCustomBlockHost.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,kBAAkB,EACvB,MAAM,8CAA8C,CAAA;AAErD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAA;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AAavF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AAoBtG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAE9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gDAAgD,CAAA;AAIhF,OAAO,KAAK,EACX,iCAAiC,EACjC,2BAA2B,EAC3B,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EACX,uBAAuB,EACvB,oCAAoC,EACpC,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAU5B,MAAM,MAAM,sBAAsB,GAAG;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,YAAY,EAAE,2BAA2B,CAAA;IACzC,QAAQ,EAAE,uBAAuB,CAAA;IACjC;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,CAAA;IACpD,gGAAgG;IAChG,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;QACvB,QAAQ,EAAE,mBAAmB,CAAA;QAC7B,aAAa,CAAC,EAAE,MAAM,CAAA;KACtB,KAAK,IAAI,CAAA;IACV,6FAA6F;IAC7F,uBAAuB,CAAC,EAAE,CACzB,KAAK,EAAE,oCAAoC,KACvC,IAAI,CAAA;IACT;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAA;IAC9B,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,2BAA2B,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC1E,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,IAAI,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAC7C,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IACtC,eAAe,EAAE,CAAC,YAAY,EAAE,kBAAkB,KAAK,IAAI,CAAA;IAC3D,SAAS,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAA;IACzC,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,cAAc,EAAE,CAAC,WAAW,EAAE,iCAAiC,KAAK,IAAI,CAAA;IACxE,cAAc,EAAE,CAAC,WAAW,EAAE,UAAU,KAAK,IAAI,CAAA;IACjD,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,YAAY,EAAE,kBAAkB,CAAA;KAAE,KAAK,IAAI,CAAA;CAClE,CAAA;AAED,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CAgZvB"}
+{"version":3,"file":"createCustomBlockHost.d.ts","sourceRoot":"","sources":["../src/createCustomBlockHost.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,kBAAkB,EACvB,MAAM,8CAA8C,CAAA;AAErD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAA;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AAavF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AAoBtG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAE9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gDAAgD,CAAA;AAIhF,OAAO,KAAK,EACX,iCAAiC,EACjC,2BAA2B,EAC3B,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EACX,sBAAsB,EACtB,uBAAuB,EACvB,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAc5B,MAAM,MAAM,sBAAsB,GAAG;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,YAAY,EAAE,2BAA2B,CAAA;IACzC,QAAQ,EAAE,uBAAuB,CAAA;IACjC;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,CAAA;IACpD,gGAAgG;IAChG,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;QACvB,QAAQ,EAAE,mBAAmB,CAAA;QAC7B,aAAa,CAAC,EAAE,MAAM,CAAA;KACtB,KAAK,IAAI,CAAA;IACV;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAA;IACnD,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,2BAA2B,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC1E,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,IAAI,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAC7C,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IACtC,eAAe,EAAE,CAAC,YAAY,EAAE,kBAAkB,KAAK,IAAI,CAAA;IAC3D,SAAS,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAA;IACzC,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,cAAc,EAAE,CAAC,WAAW,EAAE,iCAAiC,KAAK,IAAI,CAAA;IACxE,cAAc,EAAE,CAAC,WAAW,EAAE,UAAU,KAAK,IAAI,CAAA;IACjD,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,YAAY,EAAE,kBAAkB,CAAA;KAAE,KAAK,IAAI,CAAA;CAClE,CAAA;AAED,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CA+avB"}

package/dist/createCustomBlockHost.js

@@ -8,8 +8,11 @@ import { MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION } from "./protocolVersion.js
 import { QuerySubscriptions, } from "./queries/querySubscriptions.js";
 import { validateQueryDataSourceFilter } from "./queries/validateQueryDataSourceFilter.js";
 import { validateQueryDataSourceSorts } from "./queries/validateQueryDataSourceSorts.js";
+// Bridge protocol version that introduced page: { type: "unavailable" }.
+// Earlier SDKs cannot represent this context, so the host reports context_unavailable.
+const BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE = 5;
 export function createCustomBlockHost(options) {
-    const { iframe, initialState, handlers, onManifest, onInitialized, onInitializationFailure, onRestartRequired, onLog, sandboxOrigin, minBridgeProtocolVersion: configuredMinBridgeProtocolVersion, noConnectTimeoutMs, noInitResultTimeoutMs, } = options;
+    const { iframe, initialState, handlers, onManifest, onInitialized, onFailure, onLog, sandboxOrigin, minBridgeProtocolVersion: configuredMinBridgeProtocolVersion, noConnectTimeoutMs, noInitResultTimeoutMs, } = options;
     // Callers can retire older SDKs, but cannot restore support for protocols the runtime no longer
     // implements. Omission uses the runtime minimum.
     const minBridgeProtocolVersion = Math.max(configuredMinBridgeProtocolVersion ??
@@ -34,6 +37,10 @@ export function createCustomBlockHost(options) {
         onLog?.(direction, payload);
     }
     function post(message) {
+        if (initializationController.status === "stopped") {
+            // The parent page can stop this host. Do not send messages after the host stops.
+            return;
+        }
         const sandboxMessage = normalizeHostToSandboxMessage(message, sandboxBridgeProtocolVersion);
         emit("out", sandboxMessage);
         iframe.contentWindow?.postMessage(sandboxMessage, sandboxOrigin);
@@ -194,6 +201,14 @@ export function createCustomBlockHost(options) {
         }),
         prepareInit(connect) {
             sandboxBridgeProtocolVersion = connect.bridgeProtocolVersion;
+            if (sandboxBridgeProtocolVersion <
+                BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE &&
+                page.type === "unavailable") {
+                return {
+                    status: "error",
+                    error: initErrorForFailureReason("context_unavailable"),
+                };
+            }
             manifest = connect.manifest ?? initialState.manifest;
             if (manifest === undefined) {
                 return {
@@ -223,13 +238,13 @@ export function createCustomBlockHost(options) {
         minBridgeProtocolVersion,
         noConnectTimeoutMs,
         noInitResultTimeoutMs,
+        stopHostWithFailure: stopWithFailure,
         onInitResult(message) {
             if (message.status === "success" && manifest !== undefined) {
                 onInitialized?.({ manifest, initialHeight: message.initialHeight });
             }
         },
-        onRestartRequired,
-        onInitializationFailure,
+        onFailure,
     });
     const onMessage = createSandboxMessageRouter({
         iframe,
@@ -253,13 +268,19 @@ export function createCustomBlockHost(options) {
     });
     window.addEventListener("message", onMessage);
     iframe.addEventListener("load", initializationController.onIframeLoad);
+    function stop() {
+        window.removeEventListener("message", onMessage);
+        iframe.removeEventListener("load", initializationController.onIframeLoad);
+        initializationController.stop();
+        querySubscriptions.unsubscribeAll();
+    }
+    function stopWithFailure(error) {
+        stop();
+        emit("warn", error);
+        onFailure?.(error);
+    }
     return {
-        stop() {
-            window.removeEventListener("message", onMessage);
-            iframe.removeEventListener("load", initializationController.onIframeLoad);
-            initializationController.stop();
-            querySubscriptions.unsubscribeAll();
-        },
+        stop,
         post,
         setTheme(nextTheme) {
             theme = nextTheme;
@@ -299,6 +320,14 @@ export function createCustomBlockHost(options) {
         },
         setPage(nextPage) {
             page = nextPage;
+            if (nextPage.type === "unavailable" &&
+                sandboxBridgeProtocolVersion <
+                    BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE &&
+                (initializationController.status === "waitingForInitResult" ||
+                    initializationController.status === "success")) {
+                stopWithFailure(initErrorForFailureReason("context_unavailable"));
+                return;
+            }
             if (initializationController.status !== "success") {
                 if (initializationController.status === "waitingForInitResult") {
                     pendingPageChange = true;

package/dist/index.d.ts

@@ -10,6 +10,6 @@ export type { NotionPagePropertyValue, NotionPagePropertyWriteMap, NotionRichTex
 export { type AutoBindableProperty, getAutoBoundPropertyIdsByKey, } from "./autoBindProperties.js";
 export { type CustomBlockHostHandle, type CustomBlockHostOptions, createCustomBlockHost, } from "./createCustomBlockHost.js";
 export type { ConnectSuccessMessage, CustomBlockHostDataSourcesPayload, CustomBlockHostInitialDataSources, CustomBlockHostInitialState, } from "./lifecycle/types.js";
-export type { CreatePageMessageInput, CustomBlockHostCreatePageResult, CustomBlockHostGetPageResult, CustomBlockHostGetUserResult, CustomBlockHostHandlers, CustomBlockHostInitializationFailure, CustomBlockHostListUsersResult, CustomBlockHostLogDirection, CustomBlockHostOpenPageResult, CustomBlockHostUpdatePageResult, GetPageMessageInput, GetUserMessageInput, ListUsersMessageInput, OpenPageMessageInput, QueryDataSourceMessageInput, ResizeMessageInput, UpdatePageMessageInput, } from "./messages/types.js";
+export type { CreatePageMessageInput, CustomBlockHostCreatePageResult, CustomBlockHostFailure, CustomBlockHostGetPageResult, CustomBlockHostGetUserResult, CustomBlockHostHandlers, CustomBlockHostListUsersResult, CustomBlockHostLogDirection, CustomBlockHostOpenPageResult, CustomBlockHostUpdatePageResult, GetPageMessageInput, GetUserMessageInput, ListUsersMessageInput, OpenPageMessageInput, QueryDataSourceMessageInput, ResizeMessageInput, UpdatePageMessageInput, } from "./messages/types.js";
 export type { CustomBlockHostQueryDataSourceResult } from "./queries/types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,YAAY,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,YAAY,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,YAAY,EAAE,gBAAgB,EAAE,MAAM,wDAAwD,CAAA;AAC9F,YAAY,EAAE,eAAe,EAAE,MAAM,uDAAuD,CAAA;AAC5F,YAAY,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAA;AAC1G,YAAY,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAA;AACxF,YAAY,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,YAAY,EACX,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,GAClB,MAAM,gDAAgD,CAAA;AACvD,OAAO,EACN,KAAK,oBAAoB,EACzB,4BAA4B,GAC5B,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,qBAAqB,GACrB,MAAM,4BAA4B,CAAA;AACnC,YAAY,EACX,qBAAqB,EACrB,iCAAiC,EACjC,iCAAiC,EACjC,2BAA2B,GAC3B,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACX,sBAAsB,EACtB,+BAA+B,EAC/B,4BAA4B,EAC5B,4BAA4B,EAC5B,uBAAuB,EACvB,oCAAoC,EACpC,8BAA8B,EAC9B,2BAA2B,EAC3B,6BAA6B,EAC7B,+BAA+B,EAC/B,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,2BAA2B,EAC3B,kBAAkB,EAClB,sBAAsB,GACtB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,oCAAoC,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,YAAY,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,YAAY,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,YAAY,EAAE,gBAAgB,EAAE,MAAM,wDAAwD,CAAA;AAC9F,YAAY,EAAE,eAAe,EAAE,MAAM,uDAAuD,CAAA;AAC5F,YAAY,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAA;AAC1G,YAAY,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAA;AACxF,YAAY,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,YAAY,EACX,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,GAClB,MAAM,gDAAgD,CAAA;AACvD,OAAO,EACN,KAAK,oBAAoB,EACzB,4BAA4B,GAC5B,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,qBAAqB,GACrB,MAAM,4BAA4B,CAAA;AACnC,YAAY,EACX,qBAAqB,EACrB,iCAAiC,EACjC,iCAAiC,EACjC,2BAA2B,GAC3B,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACX,sBAAsB,EACtB,+BAA+B,EAC/B,sBAAsB,EACtB,4BAA4B,EAC5B,4BAA4B,EAC5B,uBAAuB,EACvB,8BAA8B,EAC9B,2BAA2B,EAC3B,6BAA6B,EAC7B,+BAA+B,EAC/B,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,2BAA2B,EAC3B,kBAAkB,EAClB,sBAAsB,GACtB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,oCAAoC,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/lifecycle/initializationController.d.ts

@@ -9,7 +9,7 @@ import type { CustomBlockPage } from "../protocol/pages/page.js";
 import type { NotionParent } from "../protocol/parent.js";
 import type { NotionTheme } from "../protocol/theme.js";
 import type { NotionUser } from "../protocol/users/user.js";
-import type { CustomBlockHostInitializationFailure } from "../messages/types.js";
+import type { CustomBlockHostFailure } from "../messages/types.js";
 import type { ConnectSuccessMessage, CustomBlockHostDataSourcesPayload, InitStatus } from "./types.js";
 type InitializationState = {
     theme: NotionTheme;
@@ -36,9 +36,9 @@ export type InitializationControllerOptions = {
     minBridgeProtocolVersion: number;
     noConnectTimeoutMs?: number;
     noInitResultTimeoutMs?: number;
+    stopHostWithFailure: (error: CustomBlockHostFailure) => void;
     onInitResult?: (message: InitResultMessage) => void;
-    onRestartRequired?: () => void;
-    onInitializationFailure?: (error: CustomBlockHostInitializationFailure) => void;
+    onFailure?: (error: CustomBlockHostFailure) => void;
 };
 export type InitializationController = {
     readonly status: InitStatus;
@@ -46,10 +46,10 @@ export type InitializationController = {
     handleConnect: (message: ConnectMessage) => void;
     handleInitResult: (message: InitResultMessage) => void;
     handleInvalidConnect: (args: {
-        initializationId: string;
+        initializationId: string | undefined;
         error: CustomBlockInitErrorInfo;
         bridgeProtocolVersion: number | undefined;
-    }) => "initErrorSent" | "nack";
+    }) => "handled" | "nack";
     handleInvalidInitResult: (args: {
         initializationId: string | undefined;
         error: CustomBlockInitErrorInfo;

package/dist/lifecycle/initializationController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initializationController.d.ts","sourceRoot":"","sources":["../../src/lifecycle/initializationController.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"initializationController.d.ts","sourceRoot":"","sources":["../../src/lifecycle/initializationController.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/initializationController.js

@@ -3,11 +3,12 @@ import { isValidBridgeProtocolVersion } from "./protocolVersion.js";
 const DEFAULT_NO_CONNECT_TIMEOUT_MS = 5_000;
 const DEFAULT_NO_INIT_RESULT_TIMEOUT_MS = 5_000;
 export function createInitializationController(options) {
-    const { blockId, getState, prepareInit, post, warn, flushPendingHostStateChanges, minBridgeProtocolVersion, noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS, noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS, onInitResult, onRestartRequired, onInitializationFailure, } = options;
+    const { blockId, getState, prepareInit, post, warn, flushPendingHostStateChanges, minBridgeProtocolVersion, noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS, noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS, stopHostWithFailure, onInitResult, onFailure, } = options;
     let initStatus = "waitingForConnect";
     let noConnectTimeoutId;
     let noInitResultTimeoutId;
     let activeInitializationId;
+    let hasObservedIframeLoad = false;
     let hasConnectedSandbox = false;
     function clearNoConnectTimeout() {
         if (noConnectTimeoutId !== undefined) {
@@ -35,7 +36,7 @@ export function createInitializationController(options) {
             status: "error",
             error,
         });
-        onInitializationFailure?.(error);
+        onFailure?.(error);
     }
     function sendInit(connect) {
         if (initStatus !== "waitingForConnect") {
@@ -77,22 +78,15 @@ export function createInitializationController(options) {
                 message: "Sandbox did not send initResult",
                 initializationId: connect.initializationId,
             });
-            onInitializationFailure?.(error);
+            onFailure?.(error);
         }, noInitResultTimeoutMs);
         return true;
     }
     function handleConnect(message) {
+        if (initStatus === "stopped") {
+            return;
+        }
         if (initStatus !== "waitingForConnect") {
-            // A sandbox document sends `connect` exactly once, so this connect
-            // belongs to a replacement document — or arrived after this host
-            // already gave up waiting. The host is single-initialization; the
-            // embedder must recreate it together with the iframe for the new
-            // document to initialize.
-            warn({
-                message: "Ignored connect after initialization settled; recreate the host and iframe to re-initialize",
-                initializationId: message.initializationId,
-            });
-            onRestartRequired?.();
             return;
         }
         // Verify the bridge protocol version is valid.
@@ -130,11 +124,16 @@ export function createInitializationController(options) {
         }
     }
     function handleInvalidConnect(args) {
+        if (initStatus === "stopped") {
+            return "handled";
+        }
         if (initStatus !== "waitingForConnect") {
-            // `connect` messages received when not waiting for one are NACKed like generic invalid messages.
-            return "nack";
+            return "handled";
         }
         const { initializationId, bridgeProtocolVersion } = args;
+        if (initializationId === undefined) {
+            return "nack";
+        }
         let error = args.error;
         // Prefer a specific protocol version error over the generic connect payload error
         // when the malformed message includes a numeric version.
@@ -150,7 +149,7 @@ export function createInitializationController(options) {
             }
         }
         sendInitError({ initializationId, error });
-        return "initErrorSent";
+        return "handled";
     }
     function handleInvalidInitResult(args) {
         const { initializationId, error } = args;
@@ -163,9 +162,21 @@ export function createInitializationController(options) {
         clearNoInitResultTimeout();
         initStatus = "error";
         warn(error);
-        onInitializationFailure?.(error);
+        onFailure?.(error);
     }
     function onIframeLoad() {
+        if (initStatus === "stopped") {
+            return;
+        }
+        if (hasObservedIframeLoad) {
+            stopHostWithFailure({
+                code: "iframe_reloaded",
+                message: "The iframe reloaded. Create a new host and iframe to reconnect.",
+                isRetryable: true,
+            });
+            return;
+        }
+        hasObservedIframeLoad = true;
         clearNoConnectTimeout();
         if (initStatus !== "waitingForConnect") {
             // Only set the timeout if the iframe loaded before the `connect` message was sent.
@@ -179,7 +190,7 @@ export function createInitializationController(options) {
             initStatus = "error";
             const error = initErrorForFailureReason("no_connect");
             warn(error);
-            onInitializationFailure?.(error);
+            onFailure?.(error);
         }, noConnectTimeoutMs);
     }
     function handleInitResult(message) {
@@ -198,11 +209,12 @@ export function createInitializationController(options) {
         }
         else {
             initStatus = "error";
-            onInitializationFailure?.(message.error);
+            onFailure?.(message.error);
         }
         onInitResult?.(message);
     }
     function stop() {
+        initStatus = "stopped";
         clearNoConnectTimeout();
         clearNoInitResultTimeout();
     }

package/dist/lifecycle/types.d.ts

@@ -10,7 +10,18 @@ import type { NotionUser } from "../protocol/users/user.js";
 export type ConnectSuccessMessage = Extract<ConnectMessage, {
     status: "success";
 }>;
-export type InitStatus = "waitingForConnect" | "waitingForInitResult" | "success" | "error";
+/** Tracks initialization and lifetime for one host instance. */
+export type InitStatus = 
+/** The host is waiting for the sandbox's first `connect` message. */
+"waitingForConnect"
+/** The host is waiting for a matching `initResult` after it sends `init`. */
+ | "waitingForInitResult"
+/** The host is initialized and can send live updates. */
+ | "success"
+/** The host is in an error state after an initialization failure or timeout. */
+ | "error"
+/** The host is stopped and no longer sends or accepts sandbox messages. */
+ | "stopped";
 export type CustomBlockHostDataSourcesPayload = {
     bindings: NotionDataSourceBindings;
 };

package/dist/lifecycle/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lifecycle/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAA;AACtF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4DAA4D,CAAA;AAC1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AACvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gDAAgD,CAAA;AAEhF,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAC1C,cAAc,EACd;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CACrB,CAAA;AAED,MAAM,MAAM,UAAU,GACnB,mBAAmB,GACnB,sBAAsB,GACtB,SAAS,GACT,OAAO,CAAA;AAEV,MAAM,MAAM,iCAAiC,GAAG;IAC/C,QAAQ,EAAE,wBAAwB,CAAA;CAClC,CAAA;AAED,MAAM,MAAM,iCAAiC,GAC1C,iCAAiC,GACjC,CAAC,CAAC,OAAO,EAAE,qBAAqB,KAAK,iCAAiC,CAAC,CAAA;AAE1E,MAAM,MAAM,2BAA2B,GAAG;IACzC,KAAK,EAAE,WAAW,CAAA;IAClB;;;OAGG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAA;IACjC,OAAO,EAAE,aAAa,CAAA;IACtB,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,eAAe,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAA;IAC9B,WAAW,EAAE,iCAAiC,CAAA;IAC9C,WAAW,EAAE,UAAU,CAAA;CACvB,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lifecycle/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAA;AACtF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4DAA4D,CAAA;AAC1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AACvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gDAAgD,CAAA;AAEhF,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAC1C,cAAc,EACd;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CACrB,CAAA;AAED,gEAAgE;AAChE,MAAM,MAAM,UAAU;AACrB,qEAAqE;AACnE,mBAAmB;AACrB,6EAA6E;GAC3E,sBAAsB;AACxB,yDAAyD;GACvD,SAAS;AACX,gFAAgF;GAC9E,OAAO;AACT,2EAA2E;GACzE,SAAS,CAAA;AAEZ,MAAM,MAAM,iCAAiC,GAAG;IAC/C,QAAQ,EAAE,wBAAwB,CAAA;CAClC,CAAA;AAED,MAAM,MAAM,iCAAiC,GAC1C,iCAAiC,GACjC,CAAC,CAAC,OAAO,EAAE,qBAAqB,KAAK,iCAAiC,CAAC,CAAA;AAE1E,MAAM,MAAM,2BAA2B,GAAG;IACzC,KAAK,EAAE,WAAW,CAAA;IAClB;;;OAGG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAA;IACjC,OAAO,EAAE,aAAa,CAAA;IACtB,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,eAAe,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAA;IAC9B,WAAW,EAAE,iCAAiC,CAAA;IAC9C,WAAW,EAAE,UAAU,CAAA;CACvB,CAAA"}

package/dist/messages/sandboxMessageRouter.js

@@ -23,19 +23,19 @@ export function createSandboxMessageRouter(options) {
         const response = getInvalidSandboxMessageResponse(data);
         if (response.incomingType === "connect") {
             const parsedIdentity = v.safeParse(initializationIdentitySchema, data);
-            if (parsedIdentity.success) {
-                const parsedVersion = v.safeParse(bridgeProtocolVersionSchema, data);
-                const responseType = onInvalidConnect({
-                    initializationId: parsedIdentity.output.initializationId,
-                    error: initErrorForFailureReason("invalid_connect_payload"),
-                    bridgeProtocolVersion: parsedVersion.success
-                        ? parsedVersion.output.bridgeProtocolVersion
-                        : undefined,
-                });
-                if (responseType === "initErrorSent") {
-                    // The controller already sent `init.error`, so no need to also send a NACK.
-                    return;
-                }
+            const parsedVersion = v.safeParse(bridgeProtocolVersionSchema, data);
+            const responseType = onInvalidConnect({
+                initializationId: parsedIdentity.success
+                    ? parsedIdentity.output.initializationId
+                    : undefined,
+                error: initErrorForFailureReason("invalid_connect_payload"),
+                bridgeProtocolVersion: parsedVersion.success
+                    ? parsedVersion.output.bridgeProtocolVersion
+                    : undefined,
+            });
+            if (responseType === "handled") {
+                // The controller sent init.error or stopped the host; neither needs a NACK.
+                return;
             }
         }
         if (response.incomingType === "initResult") {

package/dist/messages/types.d.ts

@@ -30,7 +30,7 @@ export type CustomBlockHostHandlers = {
     updatePage?: (message: UpdatePageMessage) => MaybePromise<CustomBlockHostUpdatePageResult>;
     resize?: (message: ResizeMessage) => void;
 };
-export type CustomBlockHostInitializationFailure = CustomBlockInitErrorInfo | CustomBlockInitResultErrorInfo;
+export type CustomBlockHostFailure = CustomBlockInitErrorInfo | CustomBlockInitResultErrorInfo;
 export type CustomBlockHostLogDirection = "in" | "out" | "warn";
 export type CreatePageMessageInput = InferInput<typeof createPageMessageSchema>;
 export type GetPageMessageInput = InferInput<typeof getPageMessageSchema>;

package/dist/messages/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/messages/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,iBAAiB,EACjB,uBAAuB,EACvB,MAAM,yDAAyD,CAAA;AAChE,OAAO,KAAK,EACX,uBAAuB,EACvB,8BAA8B,EAC9B,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EACX,2BAA2B,EAC3B,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,MAAM,sDAAsD,CAAA;AAC7D,OAAO,KAAK,EACX,2BAA2B,EAC3B,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,MAAM,sDAAsD,CAAA;AAC7D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mDAAmD,CAAA;AACjG,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,yDAAyD,CAAA;AAC7G,OAAO,KAAK,EACX,6BAA6B,EAC7B,gBAAgB,EAChB,sBAAsB,EACtB,sBAAsB,EACtB,MAAM,wDAAwD,CAAA;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6DAA6D,CAAA;AACvG,OAAO,KAAK,EACX,4BAA4B,EAC5B,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,MAAM,uDAAuD,CAAA;AAC9D,OAAO,KAAK,EACX,sBAAsB,EACtB,4BAA4B,EAC5B,MAAM,8DAA8D,CAAA;AACrE,OAAO,KAAK,EACX,aAAa,EACb,mBAAmB,EACnB,MAAM,qDAAqD,CAAA;AAC5D,OAAO,KAAK,EACX,iBAAiB,EACjB,uBAAuB,EACvB,MAAM,yDAAyD,CAAA;AAChE,OAAO,KAAK,EACX,8BAA8B,EAC9B,uBAAuB,EACvB,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,qBAAqB,CAAA;AAE/E,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AAErC,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,CACjE,uBAAuB,EACvB,8BAA8B,CAC9B,CAAA;AAED,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,CAC9D,oBAAoB,EACpB,2BAA2B,CAC3B,CAAA;AAED,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,CACjE,uBAAuB,EACvB,8BAA8B,CAC9B,CAAA;AAED,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,CAC9D,oBAAoB,EACpB,2BAA2B,CAC3B,CAAA;AAED,MAAM,MAAM,8BAA8B,GAAG,oBAAoB,CAChE,sBAAsB,EACtB,6BAA6B,CAC7B,CAAA;AAED,MAAM,MAAM,6BAA6B,GAAG,oBAAoB,CAC/D,qBAAqB,EACrB,4BAA4B,CAC5B,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG;IACrC,eAAe,EAAE,CAChB,OAAO,EAAE,sBAAsB,KAC3B,YAAY,CAAC,oCAAoC,CAAC,CAAA;IACvD,UAAU,CAAC,EAAE,CACZ,OAAO,EAAE,iBAAiB,KACtB,YAAY,CAAC,+BAA+B,CAAC,CAAA;IAClD,OAAO,CAAC,EAAE,CACT,OAAO,EAAE,cAAc,KACnB,YAAY,CAAC,4BAA4B,CAAC,CAAA;IAC/C,OAAO,CAAC,EAAE,CACT,OAAO,EAAE,cAAc,KACnB,YAAY,CAAC,4BAA4B,CAAC,CAAA;IAC/C,SAAS,CAAC,EAAE,CACX,OAAO,EAAE,gBAAgB,KACrB,YAAY,CAAC,8BAA8B,CAAC,CAAA;IACjD,QAAQ,CAAC,EAAE,CACV,OAAO,EAAE,eAAe,KACpB,YAAY,CAAC,6BAA6B,CAAC,CAAA;IAChD,UAAU,CAAC,EAAE,CACZ,OAAO,EAAE,iBAAiB,KACtB,YAAY,CAAC,+BAA+B,CAAC,CAAA;IAClD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;CACzC,CAAA;AAED,MAAM,MAAM,oCAAoC,GAC7C,wBAAwB,GACxB,8BAA8B,CAAA;AAEjC,MAAM,MAAM,2BAA2B,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,CAAA;AAE/D,MAAM,MAAM,sBAAsB,GAAG,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE/E,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEzE,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEzE,MAAM,MAAM,qBAAqB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE7E,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAE3E,MAAM,MAAM,2BAA2B,GAAG,UAAU,CACnD,OAAO,4BAA4B,CACnC,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAEvE,MAAM,MAAM,sBAAsB,GAAG,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/messages/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notionhq/custom-blocks-host",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "Reusable host runtime for Notion custom blocks.",
   "license": "MIT",
   "type": "module",

package/src/createCustomBlockHost.ts

@@ -51,8 +51,8 @@ import type {
 } from "./lifecycle/types.js"
 import { createSandboxMessageRouter } from "./messages/sandboxMessageRouter.js"
 import type {
+	CustomBlockHostFailure,
 	CustomBlockHostHandlers,
-	CustomBlockHostInitializationFailure,
 	CustomBlockHostLogDirection,
 } from "./messages/types.js"
 import { MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION } from "./protocolVersion.js"
@@ -64,6 +64,10 @@ import type { CustomBlockHostQueryDataSourceResult } from "./queries/types.js"
 import { validateQueryDataSourceFilter } from "./queries/validateQueryDataSourceFilter.js"
 import { validateQueryDataSourceSorts } from "./queries/validateQueryDataSourceSorts.js"
 
+// Bridge protocol version that introduced page: { type: "unavailable" }.
+// Earlier SDKs cannot represent this context, so the host reports context_unavailable.
+const BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE = 5
+
 export type CustomBlockHostOptions = {
 	iframe: HTMLIFrameElement
 	sandboxOrigin: string
@@ -87,14 +91,13 @@ export type CustomBlockHostOptions = {
 		manifest: CustomBlockManifest
 		initialHeight?: number
 	}) => void
-	/** Callback fired when the initialization handshake with the sandbox failed or timed out. */
-	onInitializationFailure?: (
-		error: CustomBlockHostInitializationFailure,
-	) => void
 	/**
-	 * Callback fired when the current host and iframe must restart. Recreate both to continue.
+	 * Reports a handshake failure, timeout, unavailable page context, or iframe reload.
+	 * Iframe reloads and unavailable page context for older SDKs stop the host
+	 * before this callback runs.
+	 * This callback can run after initialization succeeds.
 	 */
-	onRestartRequired?: () => void
+	onFailure?: (error: CustomBlockHostFailure) => void
 	onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void
 }
 
@@ -119,8 +122,7 @@ export function createCustomBlockHost(
 		handlers,
 		onManifest,
 		onInitialized,
-		onInitializationFailure,
-		onRestartRequired,
+		onFailure,
 		onLog,
 		sandboxOrigin,
 		minBridgeProtocolVersion: configuredMinBridgeProtocolVersion,
@@ -157,6 +159,10 @@ export function createCustomBlockHost(
 	}
 
 	function post(message: HostToSandboxMessage) {
+		if (initializationController.status === "stopped") {
+			// The parent page can stop this host. Do not send messages after the host stops.
+			return
+		}
 		const sandboxMessage = normalizeHostToSandboxMessage(
 			message,
 			sandboxBridgeProtocolVersion,
@@ -340,6 +346,16 @@ export function createCustomBlockHost(
 		}),
 		prepareInit(connect) {
 			sandboxBridgeProtocolVersion = connect.bridgeProtocolVersion
+			if (
+				sandboxBridgeProtocolVersion <
+					BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE &&
+				page.type === "unavailable"
+			) {
+				return {
+					status: "error",
+					error: initErrorForFailureReason("context_unavailable"),
+				}
+			}
 			manifest = connect.manifest ?? initialState.manifest
 			if (manifest === undefined) {
 				return {
@@ -373,13 +389,13 @@ export function createCustomBlockHost(
 		minBridgeProtocolVersion,
 		noConnectTimeoutMs,
 		noInitResultTimeoutMs,
+		stopHostWithFailure: stopWithFailure,
 		onInitResult(message) {
 			if (message.status === "success" && manifest !== undefined) {
 				onInitialized?.({ manifest, initialHeight: message.initialHeight })
 			}
 		},
-		onRestartRequired,
-		onInitializationFailure,
+		onFailure,
 	})
 
 	const onMessage = createSandboxMessageRouter({
@@ -407,13 +423,21 @@ export function createCustomBlockHost(
 	window.addEventListener("message", onMessage)
 	iframe.addEventListener("load", initializationController.onIframeLoad)
 
+	function stop() {
+		window.removeEventListener("message", onMessage)
+		iframe.removeEventListener("load", initializationController.onIframeLoad)
+		initializationController.stop()
+		querySubscriptions.unsubscribeAll()
+	}
+
+	function stopWithFailure(error: CustomBlockHostFailure) {
+		stop()
+		emit("warn", error)
+		onFailure?.(error)
+	}
+
 	return {
-		stop() {
-			window.removeEventListener("message", onMessage)
-			iframe.removeEventListener("load", initializationController.onIframeLoad)
-			initializationController.stop()
-			querySubscriptions.unsubscribeAll()
-		},
+		stop,
 		post,
 		setTheme(nextTheme) {
 			theme = nextTheme
@@ -453,6 +477,16 @@ export function createCustomBlockHost(
 		},
 		setPage(nextPage) {
 			page = nextPage
+			if (
+				nextPage.type === "unavailable" &&
+				sandboxBridgeProtocolVersion <
+					BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE &&
+				(initializationController.status === "waitingForInitResult" ||
+					initializationController.status === "success")
+			) {
+				stopWithFailure(initErrorForFailureReason("context_unavailable"))
+				return
+			}
 			if (initializationController.status !== "success") {
 				if (initializationController.status === "waitingForInitResult") {
 					pendingPageChange = true

package/src/index.ts

@@ -29,10 +29,10 @@ export type {
 export type {
 	CreatePageMessageInput,
 	CustomBlockHostCreatePageResult,
+	CustomBlockHostFailure,
 	CustomBlockHostGetPageResult,
 	CustomBlockHostGetUserResult,
 	CustomBlockHostHandlers,
-	CustomBlockHostInitializationFailure,
 	CustomBlockHostListUsersResult,
 	CustomBlockHostLogDirection,
 	CustomBlockHostOpenPageResult,

package/src/lifecycle/initializationController.ts

@@ -12,7 +12,7 @@ import type { CustomBlockPage } from "@notionhq/custom-blocks-protocol/pages/pag
 import type { NotionParent } from "@notionhq/custom-blocks-protocol/parent.js"
 import type { NotionTheme } from "@notionhq/custom-blocks-protocol/theme.js"
 import type { NotionUser } from "@notionhq/custom-blocks-protocol/users/user.js"
-import type { CustomBlockHostInitializationFailure } from "../messages/types.js"
+import type { CustomBlockHostFailure } from "../messages/types.js"
 import { initErrorForFailureReason } from "./initErrors.js"
 import { isValidBridgeProtocolVersion } from "./protocolVersion.js"
 import type {
@@ -53,11 +53,9 @@ export type InitializationControllerOptions = {
 	minBridgeProtocolVersion: number
 	noConnectTimeoutMs?: number
 	noInitResultTimeoutMs?: number
+	stopHostWithFailure: (error: CustomBlockHostFailure) => void
 	onInitResult?: (message: InitResultMessage) => void
-	onRestartRequired?: () => void
-	onInitializationFailure?: (
-		error: CustomBlockHostInitializationFailure,
-	) => void
+	onFailure?: (error: CustomBlockHostFailure) => void
 }
 
 export type InitializationController = {
@@ -66,10 +64,10 @@ export type InitializationController = {
 	handleConnect: (message: ConnectMessage) => void
 	handleInitResult: (message: InitResultMessage) => void
 	handleInvalidConnect: (args: {
-		initializationId: string
+		initializationId: string | undefined
 		error: CustomBlockInitErrorInfo
 		bridgeProtocolVersion: number | undefined
-	}) => "initErrorSent" | "nack"
+	}) => "handled" | "nack"
 	handleInvalidInitResult: (args: {
 		initializationId: string | undefined
 		error: CustomBlockInitErrorInfo
@@ -91,15 +89,16 @@ export function createInitializationController(
 		minBridgeProtocolVersion,
 		noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS,
 		noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS,
+		stopHostWithFailure,
 		onInitResult,
-		onRestartRequired,
-		onInitializationFailure,
+		onFailure,
 	} = options
 
 	let initStatus: InitStatus = "waitingForConnect"
 	let noConnectTimeoutId: number | undefined
 	let noInitResultTimeoutId: number | undefined
 	let activeInitializationId: string | undefined
+	let hasObservedIframeLoad = false
 	let hasConnectedSandbox = false
 
 	function clearNoConnectTimeout() {
@@ -133,7 +132,7 @@ export function createInitializationController(
 			status: "error",
 			error,
 		})
-		onInitializationFailure?.(error)
+		onFailure?.(error)
 	}
 
 	function sendInit(connect: ConnectSuccessMessage): boolean {
@@ -176,24 +175,16 @@ export function createInitializationController(
 				message: "Sandbox did not send initResult",
 				initializationId: connect.initializationId,
 			})
-			onInitializationFailure?.(error)
+			onFailure?.(error)
 		}, noInitResultTimeoutMs)
 		return true
 	}
 
 	function handleConnect(message: ConnectMessage) {
+		if (initStatus === "stopped") {
+			return
+		}
 		if (initStatus !== "waitingForConnect") {
-			// A sandbox document sends `connect` exactly once, so this connect
-			// belongs to a replacement document — or arrived after this host
-			// already gave up waiting. The host is single-initialization; the
-			// embedder must recreate it together with the iframe for the new
-			// document to initialize.
-			warn({
-				message:
-					"Ignored connect after initialization settled; recreate the host and iframe to re-initialize",
-				initializationId: message.initializationId,
-			})
-			onRestartRequired?.()
 			return
 		}
 
@@ -238,16 +229,21 @@ export function createInitializationController(
 	}
 
 	function handleInvalidConnect(args: {
-		initializationId: string
+		initializationId: string | undefined
 		error: CustomBlockInitErrorInfo
 		bridgeProtocolVersion: number | undefined
-	}): "initErrorSent" | "nack" {
+	}): "handled" | "nack" {
+		if (initStatus === "stopped") {
+			return "handled"
+		}
 		if (initStatus !== "waitingForConnect") {
-			// `connect` messages received when not waiting for one are NACKed like generic invalid messages.
-			return "nack"
+			return "handled"
 		}
 
 		const { initializationId, bridgeProtocolVersion } = args
+		if (initializationId === undefined) {
+			return "nack"
+		}
 		let error = args.error
 		// Prefer a specific protocol version error over the generic connect payload error
 		// when the malformed message includes a numeric version.
@@ -262,7 +258,7 @@ export function createInitializationController(
 			}
 		}
 		sendInitError({ initializationId, error })
-		return "initErrorSent"
+		return "handled"
 	}
 
 	function handleInvalidInitResult(args: {
@@ -281,10 +277,23 @@ export function createInitializationController(
 		clearNoInitResultTimeout()
 		initStatus = "error"
 		warn(error)
-		onInitializationFailure?.(error)
+		onFailure?.(error)
 	}
 
 	function onIframeLoad() {
+		if (initStatus === "stopped") {
+			return
+		}
+		if (hasObservedIframeLoad) {
+			stopHostWithFailure({
+				code: "iframe_reloaded",
+				message:
+					"The iframe reloaded. Create a new host and iframe to reconnect.",
+				isRetryable: true,
+			})
+			return
+		}
+		hasObservedIframeLoad = true
 		clearNoConnectTimeout()
 		if (initStatus !== "waitingForConnect") {
 			// Only set the timeout if the iframe loaded before the `connect` message was sent.
@@ -298,7 +307,7 @@ export function createInitializationController(
 			initStatus = "error"
 			const error = initErrorForFailureReason("no_connect")
 			warn(error)
-			onInitializationFailure?.(error)
+			onFailure?.(error)
 		}, noConnectTimeoutMs)
 	}
 
@@ -319,12 +328,13 @@ export function createInitializationController(
 			flushPendingHostStateChanges()
 		} else {
 			initStatus = "error"
-			onInitializationFailure?.(message.error)
+			onFailure?.(message.error)
 		}
 		onInitResult?.(message)
 	}
 
 	function stop() {
+		initStatus = "stopped"
 		clearNoConnectTimeout()
 		clearNoInitResultTimeout()
 	}

package/src/lifecycle/types.ts

@@ -13,11 +13,18 @@ export type ConnectSuccessMessage = Extract<
 	{ status: "success" }
 >
 
+/** Tracks initialization and lifetime for one host instance. */
 export type InitStatus =
+	/** The host is waiting for the sandbox's first `connect` message. */
 	| "waitingForConnect"
+	/** The host is waiting for a matching `initResult` after it sends `init`. */
 	| "waitingForInitResult"
+	/** The host is initialized and can send live updates. */
 	| "success"
+	/** The host is in an error state after an initialization failure or timeout. */
 	| "error"
+	/** The host is stopped and no longer sends or accepts sandbox messages. */
+	| "stopped"
 
 export type CustomBlockHostDataSourcesPayload = {
 	bindings: NotionDataSourceBindings

package/src/messages/sandboxMessageRouter.ts

@@ -90,19 +90,19 @@ export function createSandboxMessageRouter(
 
 		if (response.incomingType === "connect") {
 			const parsedIdentity = v.safeParse(initializationIdentitySchema, data)
-			if (parsedIdentity.success) {
-				const parsedVersion = v.safeParse(bridgeProtocolVersionSchema, data)
-				const responseType = onInvalidConnect({
-					initializationId: parsedIdentity.output.initializationId,
-					error: initErrorForFailureReason("invalid_connect_payload"),
-					bridgeProtocolVersion: parsedVersion.success
-						? parsedVersion.output.bridgeProtocolVersion
-						: undefined,
-				})
-				if (responseType === "initErrorSent") {
-					// The controller already sent `init.error`, so no need to also send a NACK.
-					return
-				}
+			const parsedVersion = v.safeParse(bridgeProtocolVersionSchema, data)
+			const responseType = onInvalidConnect({
+				initializationId: parsedIdentity.success
+					? parsedIdentity.output.initializationId
+					: undefined,
+				error: initErrorForFailureReason("invalid_connect_payload"),
+				bridgeProtocolVersion: parsedVersion.success
+					? parsedVersion.output.bridgeProtocolVersion
+					: undefined,
+			})
+			if (responseType === "handled") {
+				// The controller sent init.error or stopped the host; neither needs a NACK.
+				return
 			}
 		}
 

package/src/messages/types.ts

@@ -109,7 +109,7 @@ export type CustomBlockHostHandlers = {
 	resize?: (message: ResizeMessage) => void
 }
 
-export type CustomBlockHostInitializationFailure =
+export type CustomBlockHostFailure =
 	| CustomBlockInitErrorInfo
 	| CustomBlockInitResultErrorInfo