@notionhq/custom-blocks-host 0.1.30 → 0.2.0

package/README.md

@@ -47,16 +47,20 @@ import { createCustomBlockHost } from "@notionhq/custom-blocks-host"
 const host = createCustomBlockHost({
   iframe,
   sandboxOrigin: "https://example.com",
-  initialState: {
-    theme,
-    contrastMode,
-    blockId,
-    parent,
-    page,
-    currentUser,
-    manifest,
-    dataSources: { bindings },
-  },
+  minBridgeProtocolVersion: 3,
+  getInitialState: async () => ({
+    status: "success",
+    initialState: {
+      theme,
+      contrastMode,
+      blockId,
+      parent,
+      page,
+      currentUser,
+      manifest,
+      dataSources: { bindings },
+    },
+  }),
   handlers: {
     queryDataSource: async message => ({
       status: "success",
@@ -113,7 +117,26 @@ initial page fails initialization with `context_unavailable`. If page context be
 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
+`getInitialState` runs after the sandbox sends `connect`. It returns a promise for the initial state
+result. The host listens immediately and sends `init` only after `getInitialState` resolves. Await
+record and binding loads inside `getInitialState`.
+
+`getInitialState` selects the manifest that the host uses. The host uses this manifest even when
+`connect` supplies another. Production hosts can select persisted definitions. Preview hosts can
+select sandbox manifests. A successful result must include a manifest. If no manifest is available,
+return `manifest_unavailable`.
+
+`getInitialState` can return `{ status: "error", error }` to stop initialization. The host converts
+a thrown error or rejected promise to `unknown_error`. If preparation exceeds
+`initialStateTimeoutMs`, the host reports `initial_state_timeout` and stops the handshake.
+
+`no_connect` means the host did not receive `connect`. `no_init_result` means the sandbox did not
+acknowledge `init`. The SDK waits for the host without its own timeout.
+
+The host discards `getInitialState` results after a timeout or stop, including a stop caused by an
+iframe reload.
+
+- `onManifest` provides the selected manifest when `getInitialState` resolves successfully, before
   binding validation and `onInitialized`. Use it to configure bindings even when initialization
   cannot yet succeed.
 
@@ -122,9 +145,6 @@ after initialization, the host stops and reports the same error instead of sendi
 - `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`.
-
 `queryDataSource` is required. Other request handlers are optional. Every request handler may return
 its result synchronously or as a promise. Results use a `status` discriminator: successful results
 carry their response payload, while errors carry `{ code, message, isRetryable }`.
@@ -157,12 +177,13 @@ The runtime validates option names, supported sort types, and the limit of ten u
 properties before it invokes the handler. Sorts retain their array order. Extra fields and mixed
 filter types fail protocol validation.
 
-`initialState.dataSources` may also be a function of the successful `connect` message. This lets a
-host derive bindings from the sandbox-provided manifest.
+Derive bindings from the successful `connect` message inside `getInitialState` and return them in
+`initialState.dataSources`.
 
 Set `sandboxOrigin` to the iframe's exact origin. The runtime targets outbound messages to that
-origin and accepts inbound messages only from that iframe and origin. The runtime also accepts
-`noConnectTimeoutMs` and `noInitResultTimeoutMs`; both default to five seconds.
+origin and accepts inbound messages only from that iframe and origin. The runtime accepts
+`noConnectTimeoutMs`, `initialStateTimeoutMs`, and `noInitResultTimeoutMs`; all default to five
+seconds.
 
 ### Initialization and malformed messages
 
@@ -215,7 +236,6 @@ The returned handle exposes:
 - `setDataSources()`
 - `setCurrentUser()`
 - `refreshQuery()`
-- `post()`
 - `stop()`
 
 State updates are sent after `initResult.success`. Updates made earlier are held until

package/dist/createCustomBlockHost.d.ts

@@ -1,30 +1,25 @@
-import { type NotionContrastMode } from "./protocol/contrast.js";
+import type { NotionContrastMode } from "./protocol/contrast.js";
 import type { NotionDataSourceId } from "./protocol/ids.js";
 import type { CustomBlockManifest } from "./protocol/manifest.js";
-import type { HostToSandboxMessage } from "./protocol/messages/hostToSandbox.js";
 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 { CustomBlockHostDataSourcesPayload, CustomBlockHostInitialState } from "./lifecycle/types.js";
+import type { CustomBlockHostDataSourcesPayload, CustomBlockHostGetInitialState } from "./lifecycle/types.js";
 import type { CustomBlockHostFailure, CustomBlockHostHandlers, CustomBlockHostLogDirection } from "./messages/types.js";
 export type CustomBlockHostOptions = {
     iframe: HTMLIFrameElement;
     sandboxOrigin: string;
     /**
-     * Minimum sandbox protocol version to accept. Defaults to the host runtime minimum. Higher
-     * values retire older SDKs; lower values cannot enable protocol versions the runtime no longer
-     * supports.
+     * Minimum sandbox protocol version to accept. Defaults to the host runtime
+     * minimum. Higher values retire older SDKs; lower values cannot enable
+     * protocol versions the runtime no longer supports.
      */
     minBridgeProtocolVersion?: number;
     noConnectTimeoutMs?: number;
     noInitResultTimeoutMs?: number;
-    initialState: CustomBlockHostInitialState;
     handlers: CustomBlockHostHandlers;
-    /**
-     * Called as soon as the `manifest` is available after `connect`, before `onInitialized` and
-     * binding validation.
-     */
+    /** Called as soon as the `manifest` is available after `connect`, before `onInitialized` and binding validation. */
     onManifest?: (manifest: CustomBlockManifest) => void;
     /** Callback fired when the initialization handshake with the sandbox completed successfully. */
     onInitialized?: (state: {
@@ -39,10 +34,11 @@ export type CustomBlockHostOptions = {
      */
     onFailure?: (error: CustomBlockHostFailure) => void;
     onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void;
+    getInitialState: CustomBlockHostGetInitialState;
+    initialStateTimeoutMs?: number;
 };
 export type CustomBlockHostHandle = {
     stop: () => void;
-    post: (message: HostToSandboxMessage) => void;
     setTheme: (theme: NotionTheme) => void;
     setContrastMode: (contrastMode: NotionContrastMode) => void;
     setParent: (parent: NotionParent) => void;

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;AAGvF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AAYtG,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;AAyBD,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CAqXvB"}
+{"version":3,"file":"createCustomBlockHost.d.ts","sourceRoot":"","sources":["../src/createCustomBlockHost.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAA;AAEtF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAA;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AAcvF,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,8BAA8B,EAG9B,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EACX,sBAAsB,EACtB,uBAAuB,EACvB,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAe5B,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,QAAQ,EAAE,uBAAuB,CAAA;IACjC,oHAAoH;IACpH,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;IAC1E,eAAe,EAAE,8BAA8B,CAAA;IAC/C,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC9B,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,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;AAyBD,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CA8WvB"}

package/dist/createCustomBlockHost.js

@@ -1,4 +1,3 @@
-import { DEFAULT_CONTRAST_MODE, } from "./protocol/contrast.js";
 import { LATEST_BRIDGE_PROTOCOL_VERSION } from "./protocol/protocolVersion.js";
 import { initErrorForFailureReason } from "./lifecycle/initErrors.js";
 import { createInitializationController } from "./lifecycle/initializationController.js";
@@ -8,43 +7,68 @@ 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";
+import { unreachable } from "./utils.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, 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 { iframe, getInitialState, handlers, onManifest, onInitialized, onFailure, onLog, sandboxOrigin, minBridgeProtocolVersion: configuredMinBridgeProtocolVersion, noConnectTimeoutMs, initialStateTimeoutMs, 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 ??
         MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION, MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION);
-    let theme = initialState.theme;
-    let contrastMode = initialState.contrastMode ?? DEFAULT_CONTRAST_MODE;
-    let parent = initialState.parent;
-    let page = initialState.page;
-    let dataSources = initialState.dataSources;
+    let pendingState = {};
+    let hasPreparedInitialState = false;
+    let manifest;
     let activeDataSources;
     let sandboxBridgeProtocolVersion = LATEST_BRIDGE_PROTOCOL_VERSION;
-    let manifest = initialState.manifest;
-    let currentUser = initialState.currentUser;
-    let pendingThemeChange = false;
-    let pendingContrastModeChange = false;
-    let pendingParentChange = false;
-    let pendingPageChange = false;
-    let pendingDataSourcesChange;
-    let pendingCurrentUserChange = false;
     const querySubscriptions = new QuerySubscriptions();
     function emit(direction, payload) {
         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;
+    function postToSandbox(message) {
+        const status = initializationController.status;
+        switch (status) {
+            case "waitingForConnect":
+            case "preparingInit":
+            case "waitingForInitResult":
+            case "initialized":
+            case "error":
+                break;
+            // A stopped host must not send messages, including pending responses.
+            // Return from the function to skip delivery below.
+            case "stopped":
+                return;
+            default:
+                return unreachable(status);
         }
         const sandboxMessage = normalizeHostToSandboxMessage(message, sandboxBridgeProtocolVersion);
         emit("out", sandboxMessage);
         iframe.contentWindow?.postMessage(sandboxMessage, sandboxOrigin);
     }
+    function sendInitMessage(message) {
+        postToSandbox(message);
+    }
+    function sendNack(message) {
+        postToSandbox(message);
+    }
+    function sendInitializedMessage(message) {
+        const status = initializationController.status;
+        switch (status) {
+            case "initialized":
+                postToSandbox(message);
+                return;
+            // Send state updates and handler results only after initialization succeeds.
+            case "waitingForConnect":
+            case "preparingInit":
+            case "waitingForInitResult":
+            case "error":
+            case "stopped":
+                return;
+            default:
+                unreachable(status);
+        }
+    }
     /**
      * Invokes a one-shot handler and posts its result with the request's ID.
      * Each result type is named `<request type>Result` by the bridge protocol.
@@ -59,7 +83,7 @@ export function createCustomBlockHost(options) {
             requestId: message.requestId,
             ...response,
         };
-        post(result);
+        sendInitializedMessage(result);
     }
     function postQueryDataSourceResult(args) {
         const message = args.response.status === "error"
@@ -76,7 +100,7 @@ export function createCustomBlockHost(options) {
                 items: args.response.items,
                 hasMore: args.response.hasMore,
             };
-        post(message);
+        sendInitializedMessage(message);
     }
     async function handleQuery(message, token = querySubscriptions.subscribe(message)) {
         const collectionSchema = getCollectionSchema(activeDataSources, message.dataSourceId);
@@ -99,88 +123,65 @@ export function createCustomBlockHost(options) {
             response,
         });
     }
-    /**
-     * Sends any pending host state changes to the sandbox. It is possible for these to change
-     * between when the host sends `init` and when the sandbox responds with `initResult`. The host
-     * does send any pending state changes until hearing back from the sandbox.
-     */
+    function updateHostState(update) {
+        if (initializationController.status === "stopped" ||
+            initializationController.status === "error") {
+            return;
+        }
+        Object.assign(pendingState, update);
+        flushPendingHostStateChanges();
+    }
     function flushPendingHostStateChanges() {
-        if (pendingThemeChange) {
-            pendingThemeChange = false;
-            post({ type: "themeChanged", theme });
+        // Keep updates queued until the sandbox acknowledges initialization.
+        // Updates received before init is sent are included in its payload instead.
+        if (initializationController.status !== "initialized") {
+            return;
+        }
+        const changes = pendingState;
+        pendingState = {};
+        if (changes.theme !== undefined) {
+            sendInitializedMessage({ type: "themeChanged", theme: changes.theme });
         }
-        if (pendingContrastModeChange) {
-            pendingContrastModeChange = false;
-            post({ type: "contrastModeChanged", contrastMode });
+        if (changes.contrastMode !== undefined) {
+            sendInitializedMessage({
+                type: "contrastModeChanged",
+                contrastMode: changes.contrastMode,
+            });
         }
-        if (pendingParentChange) {
-            pendingParentChange = false;
-            post({ type: "parentChanged", parent });
+        if (changes.parent !== undefined) {
+            sendInitializedMessage({ type: "parentChanged", parent: changes.parent });
         }
-        if (pendingPageChange) {
-            pendingPageChange = false;
-            post({ type: "pageChanged", page });
+        if (changes.page !== undefined) {
+            sendInitializedMessage({ type: "pageChanged", page: changes.page });
         }
-        if (pendingDataSourcesChange !== undefined) {
-            const nextDataSources = pendingDataSourcesChange;
-            pendingDataSourcesChange = undefined;
-            post({
+        if (changes.dataSources !== undefined) {
+            sendInitializedMessage({
                 type: "dataSourcesChanged",
-                dataSources: nextDataSources,
+                dataSources: changes.dataSources,
             });
         }
-        if (pendingCurrentUserChange) {
-            pendingCurrentUserChange = false;
-            post({ type: "currentUserChanged", currentUser });
+        if (changes.currentUser !== undefined) {
+            sendInitializedMessage({
+                type: "currentUserChanged",
+                currentUser: changes.currentUser,
+            });
         }
     }
     const initializationController = createInitializationController({
-        blockId: initialState.blockId,
-        getState: () => ({
-            theme,
-            contrastMode,
-            parent,
-            page,
-            currentUser,
-        }),
-        prepareInit(connect) {
+        async 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 {
-                    status: "error",
-                    error: initErrorForFailureReason("manifest_unavailable"),
-                };
-            }
-            onManifest?.(manifest);
-            const resolvedDataSources = typeof dataSources === "function" ? dataSources(connect) : dataSources;
-            const bindingErrorCode = getBindingErrorCode(manifest, resolvedDataSources);
-            if (bindingErrorCode !== undefined) {
-                return {
-                    status: "error",
-                    error: initErrorForFailureReason(bindingErrorCode),
-                };
+            const result = await getInitialState(connect);
+            if (initializationController.status !== "preparingInit") {
+                return result;
             }
-            activeDataSources = resolvedDataSources;
-            return {
-                status: "success",
-                manifest,
-                dataSources: resolvedDataSources,
-            };
+            return prepareInitialState(result);
         },
-        post,
+        sendInitMessage,
         warn: payload => emit("warn", payload),
         flushPendingHostStateChanges,
         minBridgeProtocolVersion,
         noConnectTimeoutMs,
+        initialStateTimeoutMs,
         noInitResultTimeoutMs,
         stopHostWithFailure: stopWithFailure,
         onInitResult(message) {
@@ -190,12 +191,39 @@ export function createCustomBlockHost(options) {
         },
         onFailure,
     });
+    function prepareInitialState(result) {
+        if (result.status === "error") {
+            return result;
+        }
+        manifest = result.initialState.manifest;
+        onManifest?.(manifest);
+        const initialState = { ...result.initialState, ...pendingState };
+        pendingState = {};
+        if (sandboxBridgeProtocolVersion <
+            BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE &&
+            initialState.page.type === "unavailable") {
+            return {
+                status: "error",
+                error: initErrorForFailureReason("context_unavailable"),
+            };
+        }
+        const bindingErrorCode = getBindingErrorCode(initialState.manifest, initialState.dataSources);
+        if (bindingErrorCode !== undefined) {
+            return {
+                status: "error",
+                error: initErrorForFailureReason(bindingErrorCode),
+            };
+        }
+        activeDataSources = initialState.dataSources;
+        hasPreparedInitialState = true;
+        return { status: "success", initialState };
+    }
     const onMessage = createSandboxMessageRouter({
         iframe,
         sandboxOrigin,
         getInitStatus: () => initializationController.status,
         emit,
-        post,
+        sendNack,
         onInvalidConnect: initializationController.handleInvalidConnect,
         onInvalidInitResult: initializationController.handleInvalidInitResult,
         onConnect: initializationController.handleConnect,
@@ -225,98 +253,46 @@ export function createCustomBlockHost(options) {
     }
     return {
         stop,
-        post,
-        setTheme(nextTheme) {
-            theme = nextTheme;
-            if (initializationController.status !== "success") {
-                if (initializationController.status === "waitingForInitResult") {
-                    pendingThemeChange = true;
-                }
-                return;
-            }
-            const message = { type: "themeChanged", theme };
-            post(message);
+        setTheme(theme) {
+            updateHostState({ theme });
         },
-        setContrastMode(nextContrastMode) {
-            contrastMode = nextContrastMode;
-            if (initializationController.status !== "success") {
-                if (initializationController.status === "waitingForInitResult") {
-                    pendingContrastModeChange = true;
-                }
-                return;
-            }
-            const message = {
-                type: "contrastModeChanged",
-                contrastMode,
-            };
-            post(message);
+        setContrastMode(contrastMode) {
+            updateHostState({ contrastMode });
         },
-        setParent(nextParent) {
-            parent = nextParent;
-            if (initializationController.status !== "success") {
-                if (initializationController.status === "waitingForInitResult") {
-                    pendingParentChange = true;
-                }
-                return;
-            }
-            const message = { type: "parentChanged", parent };
-            post(message);
+        setParent(parent) {
+            updateHostState({ parent });
         },
-        setPage(nextPage) {
-            page = nextPage;
-            if (nextPage.type === "unavailable" &&
+        setPage(page) {
+            if (page.type === "unavailable" &&
                 sandboxBridgeProtocolVersion <
                     BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE &&
-                (initializationController.status === "waitingForInitResult" ||
-                    initializationController.status === "success")) {
+                ((initializationController.status === "preparingInit" &&
+                    hasPreparedInitialState) ||
+                    initializationController.status === "waitingForInitResult" ||
+                    initializationController.status === "initialized")) {
                 stopWithFailure(initErrorForFailureReason("context_unavailable"));
                 return;
             }
-            if (initializationController.status !== "success") {
-                if (initializationController.status === "waitingForInitResult") {
-                    pendingPageChange = true;
-                }
-                return;
-            }
-            const message = { type: "pageChanged", page };
-            post(message);
+            updateHostState({ page });
+        },
+        setCurrentUser(currentUser) {
+            updateHostState({ currentUser });
         },
-        setDataSources(nextDataSources) {
+        setDataSources(dataSources) {
             if (initializationController.hasConnectedSandbox &&
                 manifest !== undefined &&
-                getBindingErrorCode(manifest, nextDataSources) !== undefined) {
+                getBindingErrorCode(manifest, dataSources) !== undefined) {
                 emit("warn", {
                     message: "Ignored invalid data source bindings update",
-                    payload: nextDataSources,
+                    payload: dataSources,
                 });
                 return;
             }
-            dataSources = nextDataSources;
-            activeDataSources = nextDataSources;
-            if (initializationController.status !== "success") {
-                if (initializationController.status === "waitingForInitResult") {
-                    pendingDataSourcesChange = nextDataSources;
-                }
-                return;
-            }
-            const message = {
-                type: "dataSourcesChanged",
-                dataSources: nextDataSources,
-            };
-            post(message);
-        },
-        setCurrentUser(nextCurrentUser) {
-            currentUser = nextCurrentUser;
-            if (initializationController.status !== "success") {
-                if (initializationController.status === "waitingForInitResult") {
-                    pendingCurrentUserChange = true;
-                }
-                return;
-            }
-            post({ type: "currentUserChanged", currentUser });
+            activeDataSources = dataSources;
+            updateHostState({ dataSources });
         },
         refreshQuery({ dataSourceId }) {
-            if (initializationController.status !== "success") {
+            if (initializationController.status !== "initialized") {
                 return;
             }
             const refreshes = querySubscriptions.refresh(dataSourceId);

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export type { UpdatePageMessage } from "./protocol/messages/updatePage.js";
 export type { NotionPagePropertyValue, NotionPagePropertyWriteMap, NotionRichTextItem, } from "./protocol/pages/page.js";
 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 { ConnectSuccessMessage, CustomBlockHostDataSourcesPayload, CustomBlockHostGetInitialState, CustomBlockHostInitialState, CustomBlockHostInitialStateResult, } from "./lifecycle/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,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"}
+{"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,8BAA8B,EAC9B,2BAA2B,EAC3B,iCAAiC,GACjC,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/initErrors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initErrors.d.ts","sourceRoot":"","sources":["../../src/lifecycle/initErrors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,wBAAwB,EACxB,wBAAwB,EACxB,MAAM,mDAAmD,CAAA;AAK1D;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACxC,MAAM,EAAE,wBAAwB,EAChC,IAAI,GAAE;IACL,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,4BAA4B,CAAC,EAAE,MAAM,CAAA;CAChC,GACJ,wBAAwB,CA+I1B"}
+{"version":3,"file":"initErrors.d.ts","sourceRoot":"","sources":["../../src/lifecycle/initErrors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,wBAAwB,EACxB,wBAAwB,EACxB,MAAM,mDAAmD,CAAA;AAK1D;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACxC,MAAM,EAAE,wBAAwB,EAChC,IAAI,GAAE;IACL,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,4BAA4B,CAAC,EAAE,MAAM,CAAA;CAChC,GACJ,wBAAwB,CAqJ1B"}

package/dist/lifecycle/initErrors.js

@@ -77,6 +77,12 @@ export function initErrorForFailureReason(reason, data = {}) {
                 message: "Current user is unavailable.",
                 isRetryable: true,
             };
+        case "initial_state_timeout":
+            return {
+                code: reason,
+                message: "Host did not prepare initial state before the timeout.",
+                isRetryable: true,
+            };
         case "missing_data_source_binding":
             return {
                 code: reason,

package/dist/lifecycle/initializationController.d.ts

@@ -1,40 +1,16 @@
-import type { NotionContrastMode } from "../protocol/contrast.js";
-import type { NotionBlockId } from "../protocol/ids.js";
-import type { CustomBlockManifest } from "../protocol/manifest.js";
 import type { ConnectMessage } from "../protocol/messages/connect.js";
-import type { HostToSandboxMessage } from "../protocol/messages/hostToSandbox.js";
-import type { CustomBlockInitErrorInfo } from "../protocol/messages/init.js";
+import type { CustomBlockInitErrorInfo, InitMessage } from "../protocol/messages/init.js";
 import type { InitResultMessage } from "../protocol/messages/initResult.js";
-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 { CustomBlockHostFailure } from "../messages/types.js";
-import type { ConnectSuccessMessage, CustomBlockHostDataSourcesPayload, InitStatus } from "./types.js";
-type InitializationState = {
-    theme: NotionTheme;
-    contrastMode: NotionContrastMode;
-    parent: NotionParent;
-    page: CustomBlockPage;
-    currentUser: NotionUser;
-};
-type InitializationPreparation = {
-    status: "success";
-    manifest: CustomBlockManifest;
-    dataSources: CustomBlockHostDataSourcesPayload;
-} | {
-    status: "error";
-    error: CustomBlockInitErrorInfo;
-};
+import type { ConnectSuccessMessage, CustomBlockHostInitialStateResult, InitStatus } from "./types.js";
 export type InitializationControllerOptions = {
-    blockId: NotionBlockId;
-    getState: () => InitializationState;
-    prepareInit: (connect: ConnectSuccessMessage) => InitializationPreparation;
-    post: (message: HostToSandboxMessage) => void;
+    prepareInit: (connect: ConnectSuccessMessage) => Promise<CustomBlockHostInitialStateResult>;
+    sendInitMessage: (message: InitMessage) => void;
     warn: (payload: unknown) => void;
     flushPendingHostStateChanges: () => void;
     minBridgeProtocolVersion: number;
     noConnectTimeoutMs?: number;
+    initialStateTimeoutMs?: number;
     noInitResultTimeoutMs?: number;
     stopHostWithFailure: (error: CustomBlockHostFailure) => void;
     onInitResult?: (message: InitResultMessage) => void;
@@ -58,5 +34,4 @@ export type InitializationController = {
     stop: () => void;
 };
 export declare function createInitializationController(options: InitializationControllerOptions): InitializationController;
-export {};
 //# sourceMappingURL=initializationController.d.ts.map