@notionhq/custom-blocks-host 0.1.8 → 0.1.10

package/dist/messages/sandboxMessageRouter.js

@@ -0,0 +1,107 @@
+import { isInitHandshakeMessage } from "../protocol/messages/isInitHandshakeMessage.js";
+import { sandboxToHostMessageSchema } from "../protocol/messages/sandboxToHost.js";
+import * as v from "valibot";
+import { initErrorForFailureReason } from "../lifecycle/initErrors.js";
+import { unreachable } from "../utils.js";
+import { getInvalidSandboxMessageResponse } from "./invalidSandboxMessage.js";
+const initializationIdentitySchema = v.object({
+    initializationId: v.string(),
+});
+export function createSandboxMessageRouter(options) {
+    const { iframe, sandboxOrigin, getInitStatus, emit, post, onInvalidConnect, onInvalidInitResult, onConnect, onInitResult, onQueryDataSource, onUnsubscribeDataSourceQuery, onCreatePage, onGetPage, onGetUser, onListUsers, onUpdatePage, onResize, } = options;
+    function onInvalidSandboxMessage(data, issues) {
+        emit("warn", {
+            message: "Ignored unsupported sandbox message",
+            payload: data,
+            issues,
+        });
+        const response = getInvalidSandboxMessageResponse(data);
+        if (response.incomingType === "connect") {
+            const parsedIdentity = v.safeParse(initializationIdentitySchema, data);
+            if (parsedIdentity.success) {
+                const responseType = onInvalidConnect({
+                    initializationId: parsedIdentity.output.initializationId,
+                    error: initErrorForFailureReason("invalid_connect_payload"),
+                });
+                if (responseType === "initErrorSent") {
+                    // The controller already sent `init.error`, so no need to also send a NACK.
+                    return;
+                }
+            }
+        }
+        if (response.incomingType === "initResult") {
+            const parsedIdentity = v.safeParse(initializationIdentitySchema, data);
+            onInvalidInitResult({
+                initializationId: parsedIdentity.success
+                    ? parsedIdentity.output.initializationId
+                    : undefined,
+                error: initErrorForFailureReason("invalid_init_result_payload"),
+            });
+        }
+        // Other messages get NACKed indicating they were invalid and skipped
+        if (response.nack !== undefined) {
+            post(response.nack);
+        }
+    }
+    return function onMessage(event) {
+        // Verify the sender is this host's iframe, not another window with the same origin.
+        const isExpectedSource = event.source === iframe.contentWindow;
+        // Verify the sender's origin, since the iframe can navigate to another origin.
+        const isExpectedOrigin = event.origin === sandboxOrigin;
+        if (!isExpectedSource || !isExpectedOrigin) {
+            return;
+        }
+        // Parse and validate the message from the sandbox.
+        const parsed = v.safeParse(sandboxToHostMessageSchema, event.data);
+        if (!parsed.success) {
+            onInvalidSandboxMessage(event.data, parsed.issues);
+            return;
+        }
+        const message = parsed.output;
+        if (!isInitHandshakeMessage(message) && getInitStatus() !== "success") {
+            emit("warn", {
+                message: `Ignored ${message.type} before initialization completed`,
+                payload: message,
+            });
+            return;
+        }
+        emit("in", message);
+        switch (message.type) {
+            case "connect":
+                onConnect(message);
+                return;
+            case "initResult":
+                onInitResult(message);
+                return;
+            case "queryDataSource":
+                void onQueryDataSource(message);
+                return;
+            case "unsubscribeDataSourceQuery":
+                onUnsubscribeDataSourceQuery(message);
+                return;
+            case "createPage":
+                void onCreatePage(message);
+                return;
+            case "getPage":
+                void onGetPage(message);
+                return;
+            case "getUser":
+                void onGetUser(message);
+                return;
+            case "listUsers":
+                void onListUsers(message);
+                return;
+            case "updatePage":
+                void onUpdatePage(message);
+                return;
+            case "resize":
+                onResize(message);
+                return;
+            case "invalidHostMessage":
+                // The inbound log records this rejection. Do not reply, to avoid an error-response loop.
+                return;
+            default:
+                unreachable(message);
+        }
+    };
+}

package/dist/messages/types.d.ts

@@ -1,4 +1,3 @@
-import type { BridgeMessagePayload } from "../protocol/messagePayload.js";
 import type { CreatePageMessage } from "../protocol/messages/createPage.js";
 import type { CreatePageResultMessage, CustomBlockCreatePageErrorInfo } from "../protocol/messages/createPageResult.js";
 import type { CustomBlockGetPageErrorInfo, GetPageMessage, GetPageResultMessage } from "../protocol/messages/getPage.js";
@@ -6,6 +5,7 @@ import type { CustomBlockGetUserErrorInfo, GetUserMessage, GetUserResultMessage
 import type { CustomBlockInitErrorInfo } from "../protocol/messages/init.js";
 import type { CustomBlockInitResultErrorInfo } from "../protocol/messages/initResult.js";
 import type { CustomBlockListUsersErrorInfo, ListUsersMessage, ListUsersResultMessage } from "../protocol/messages/listUsers.js";
+import type { BridgeMessagePayload } from "../protocol/messages/messagePayload.js";
 import type { QueryDataSourceMessage } from "../protocol/messages/queryDataSource.js";
 import type { ResizeMessage } from "../protocol/messages/resize.js";
 import type { UpdatePageMessage } from "../protocol/messages/updatePage.js";

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,EAAE,oBAAoB,EAAE,MAAM,oDAAoD,CAAA;AAC9F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EACX,uBAAuB,EACvB,8BAA8B,EAC9B,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EACX,2BAA2B,EAC3B,cAAc,EACd,oBAAoB,EACpB,MAAM,sDAAsD,CAAA;AAC7D,OAAO,KAAK,EACX,2BAA2B,EAC3B,cAAc,EACd,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,MAAM,wDAAwD,CAAA;AAC/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAA;AAC1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAA;AACxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EACX,8BAA8B,EAC9B,uBAAuB,EACvB,MAAM,+DAA+D,CAAA;AACtE,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,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,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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/messages/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EACX,uBAAuB,EACvB,8BAA8B,EAC9B,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EACX,2BAA2B,EAC3B,cAAc,EACd,oBAAoB,EACpB,MAAM,sDAAsD,CAAA;AAC7D,OAAO,KAAK,EACX,2BAA2B,EAC3B,cAAc,EACd,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,MAAM,wDAAwD,CAAA;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6DAA6D,CAAA;AACvG,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAA;AAC1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAA;AACxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EACX,8BAA8B,EAC9B,uBAAuB,EACvB,MAAM,+DAA+D,CAAA;AACtE,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,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,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"}

package/dist/protocol/index.d.ts

@@ -15,9 +15,7 @@ export * from "./dataSources/propertySchema.js";
 export * from "./dataSources/recordPointer.js";
 export * from "./errors.js";
 export * from "./ids.js";
-export * from "./incomingType.js";
 export * from "./manifest.js";
-export * from "./messagePayload.js";
 export * from "./messages/connect.js";
 export * from "./messages/contrastModeChanged.js";
 export * from "./messages/createPage.js";
@@ -27,11 +25,14 @@ export * from "./messages/dataSourcesChanged.js";
 export * from "./messages/getPage.js";
 export * from "./messages/getUser.js";
 export * from "./messages/hostToSandbox.js";
+export * from "./messages/incomingType.js";
 export * from "./messages/init.js";
 export * from "./messages/initResult.js";
 export * from "./messages/invalidHostMessage.js";
 export * from "./messages/invalidSandboxMessage.js";
+export * from "./messages/isInitHandshakeMessage.js";
 export * from "./messages/listUsers.js";
+export * from "./messages/messagePayload.js";
 export * from "./messages/pageChanged.js";
 export * from "./messages/parentChanged.js";
 export * from "./messages/queryDataSource.js";

package/dist/protocol/index.js

@@ -15,9 +15,7 @@ export * from "./dataSources/propertySchema.js";
 export * from "./dataSources/recordPointer.js";
 export * from "./errors.js";
 export * from "./ids.js";
-export * from "./incomingType.js";
 export * from "./manifest.js";
-export * from "./messagePayload.js";
 export * from "./messages/connect.js";
 export * from "./messages/contrastModeChanged.js";
 export * from "./messages/createPage.js";
@@ -27,11 +25,14 @@ export * from "./messages/dataSourcesChanged.js";
 export * from "./messages/getPage.js";
 export * from "./messages/getUser.js";
 export * from "./messages/hostToSandbox.js";
+export * from "./messages/incomingType.js";
 export * from "./messages/init.js";
 export * from "./messages/initResult.js";
 export * from "./messages/invalidHostMessage.js";
 export * from "./messages/invalidSandboxMessage.js";
+export * from "./messages/isInitHandshakeMessage.js";
 export * from "./messages/listUsers.js";
+export * from "./messages/messagePayload.js";
 export * from "./messages/pageChanged.js";
 export * from "./messages/parentChanged.js";
 export * from "./messages/queryDataSource.js";

package/dist/protocol/messages/isInitHandshakeMessage.d.ts

@@ -0,0 +1,4 @@
+import type { HostToSandboxMessage } from "./hostToSandbox.js";
+import type { SandboxToHostMessage } from "./sandboxToHost.js";
+/** Returns whether a message belongs to the initialization handshake. */
+export declare function isInitHandshakeMessage(message: SandboxToHostMessage | HostToSandboxMessage): boolean;

package/dist/protocol/messages/isInitHandshakeMessage.js

@@ -0,0 +1,11 @@
+/** Returns whether a message belongs to the initialization handshake. */
+export function isInitHandshakeMessage(message) {
+    switch (message.type) {
+        case "connect":
+        case "init":
+        case "initResult":
+            return true;
+        default:
+            return false;
+    }
+}

package/dist/protocol/{messagePayload.d.ts → messages/messagePayload.d.ts}

@@ -1,4 +1,4 @@
-import type { CustomBlockErrorInfo } from "./errors.js";
+import type { CustomBlockErrorInfo } from "../errors.js";
 type WithTypedErrorInfo<T, TErrorInfo extends CustomBlockErrorInfo | undefined> = TErrorInfo extends CustomBlockErrorInfo ? T extends {
     error: CustomBlockErrorInfo;
 } ? Omit<T, "error"> & {

package/dist/queries/types.d.ts

@@ -1,4 +1,4 @@
-import type { BridgeMessagePayload } from "../protocol/messagePayload.js";
+import type { BridgeMessagePayload } from "../protocol/messages/messagePayload.js";
 import type { CustomBlockQueryDataSourceErrorInfo, QueryDataSourceResultMessage } from "../protocol/messages/queryDataSourceResult.js";
 export type CustomBlockHostQueryDataSourceResult = BridgeMessagePayload<QueryDataSourceResultMessage, CustomBlockQueryDataSourceErrorInfo>;
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/queries/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oDAAoD,CAAA;AAC9F,OAAO,KAAK,EACX,mCAAmC,EACnC,4BAA4B,EAC5B,MAAM,oEAAoE,CAAA;AAE3E,MAAM,MAAM,oCAAoC,GAAG,oBAAoB,CACtE,4BAA4B,EAC5B,mCAAmC,CACnC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/queries/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6DAA6D,CAAA;AACvG,OAAO,KAAK,EACX,mCAAmC,EACnC,4BAA4B,EAC5B,MAAM,oEAAoE,CAAA;AAE3E,MAAM,MAAM,oCAAoC,GAAG,oBAAoB,CACtE,4BAA4B,EAC5B,mCAAmC,CACnC,CAAA"}

package/package.json

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

package/src/createCustomBlockHost.ts

@@ -4,7 +4,6 @@ import {
 } from "@notionhq/custom-blocks-protocol/contrast.js"
 import type { NotionDataSourceId } from "@notionhq/custom-blocks-protocol/ids.js"
 import type { CustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest.js"
-import type { ConnectMessage } from "@notionhq/custom-blocks-protocol/messages/connect.js"
 import type { ContrastModeChangedMessage } from "@notionhq/custom-blocks-protocol/messages/contrastModeChanged.js"
 import type { CreatePageMessage } from "@notionhq/custom-blocks-protocol/messages/createPage.js"
 import type { CreatePageResultMessage } from "@notionhq/custom-blocks-protocol/messages/createPageResult.js"
@@ -19,7 +18,6 @@ import type {
 } from "@notionhq/custom-blocks-protocol/messages/getUser.js"
 import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
 import type { CustomBlockInitErrorCode } from "@notionhq/custom-blocks-protocol/messages/init.js"
-import type { InitResultMessage } from "@notionhq/custom-blocks-protocol/messages/initResult.js"
 import type {
 	ListUsersMessage,
 	ListUsersResultMessage,
@@ -28,7 +26,6 @@ import type { PageChangedMessage } from "@notionhq/custom-blocks-protocol/messag
 import type { ParentChangedMessage } from "@notionhq/custom-blocks-protocol/messages/parentChanged.js"
 import type { QueryDataSourceMessage } from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
 import type { QueryDataSourceResultMessage } from "@notionhq/custom-blocks-protocol/messages/queryDataSourceResult.js"
-import { sandboxToHostMessageSchema } from "@notionhq/custom-blocks-protocol/messages/sandboxToHost.js"
 import type { ThemeChangedMessage } from "@notionhq/custom-blocks-protocol/messages/themeChanged.js"
 import type { UpdatePageMessage } from "@notionhq/custom-blocks-protocol/messages/updatePage.js"
 import type { UpdatePageResultMessage } from "@notionhq/custom-blocks-protocol/messages/updatePageResult.js"
@@ -37,15 +34,13 @@ import type { NotionParent } from "@notionhq/custom-blocks-protocol/parent.js"
 import { CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION } from "@notionhq/custom-blocks-protocol/protocolVersion.js"
 import type { NotionTheme } from "@notionhq/custom-blocks-protocol/theme.js"
 import type { NotionUser } from "@notionhq/custom-blocks-protocol/users/user.js"
-import * as v from "valibot"
 import { initErrorForFailureReason } from "./lifecycle/initErrors.js"
 import { createInitializationController } from "./lifecycle/initializationController.js"
 import type {
-	ConnectSuccessMessage,
 	CustomBlockHostDataSourcesPayload,
 	CustomBlockHostInitialState,
 } from "./lifecycle/types.js"
-import { getInvalidSandboxMessageResponse } from "./messages/invalidSandboxMessage.js"
+import { createSandboxMessageRouter } from "./messages/sandboxMessageRouter.js"
 import type {
 	CustomBlockHostHandlers,
 	CustomBlockHostInitializationFailure,
@@ -58,7 +53,6 @@ import {
 import type { CustomBlockHostQueryDataSourceResult } from "./queries/types.js"
 import { validateQueryDataSourceFilter } from "./queries/validateQueryDataSourceFilter.js"
 import { validateQueryDataSourceSorts } from "./queries/validateQueryDataSourceSorts.js"
-import { unreachable } from "./utils.js"
 
 export type CustomBlockHostOptions = {
 	iframe: HTMLIFrameElement
@@ -68,19 +62,22 @@ export type CustomBlockHostOptions = {
 	noInitResultTimeoutMs?: number
 	initialState: CustomBlockHostInitialState
 	handlers: CustomBlockHostHandlers
-	onConnect?: (message: ConnectSuccessMessage) => void
-	onInitResult?: (message: InitResultMessage) => void
+	/** 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: {
+		manifest: CustomBlockManifest
+		initialHeight?: number
+	}) => void
+	/** Callback fired when the initialization handshake with the sandbox failed or timed out. */
 	onInitializationFailure?: (
 		error: CustomBlockHostInitializationFailure,
 	) => void
 	/**
-	 * A `connect` arrived after this host's initialization settled — the
-	 * document was replaced, or its first `connect` came after the host
-	 * stopped waiting. Either way the host cannot serve it: the embedder
-	 * should recreate host and iframe together so the document can run a
-	 * fresh handshake.
+	 * Callback fired when the current host and iframe must restart.
+	 * Recreate both to continue.
 	 */
-	onIgnoredConnect?: (message: ConnectMessage) => void
+	onRestartRequired?: () => void
 	onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void
 }
 
@@ -96,10 +93,6 @@ export type CustomBlockHostHandle = {
 	refreshQuery: (args: { dataSourceId: NotionDataSourceId }) => void
 }
 
-const initializationIdentitySchema = v.object({
-	initializationId: v.string(),
-})
-
 export function createCustomBlockHost(
 	options: CustomBlockHostOptions,
 ): CustomBlockHostHandle {
@@ -107,10 +100,10 @@ export function createCustomBlockHost(
 		iframe,
 		initialState,
 		handlers,
-		onConnect,
-		onInitResult,
+		onManifest,
+		onInitialized,
 		onInitializationFailure,
-		onIgnoredConnect,
+		onRestartRequired,
 		onLog,
 		sandboxOrigin,
 		minBridgeProtocolVersion: configuredMinBridgeProtocolVersion,
@@ -322,6 +315,13 @@ export function createCustomBlockHost(
 		}),
 		prepareInit(connect) {
 			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(
@@ -347,121 +347,35 @@ export function createCustomBlockHost(
 		minBridgeProtocolVersion,
 		noConnectTimeoutMs,
 		noInitResultTimeoutMs,
-		onConnect,
-		onInitResult,
-		onIgnoredConnect,
+		onInitResult(message) {
+			if (message.status === "success" && manifest !== undefined) {
+				onInitialized?.({ manifest, initialHeight: message.initialHeight })
+			}
+		},
+		onRestartRequired,
 		onInitializationFailure,
 	})
 
-	function onInvalidSandboxMessage(
-		data: unknown,
-		issues: readonly v.BaseIssue<unknown>[],
-	) {
-		emit("warn", {
-			message: "Ignored unsupported sandbox message",
-			payload: data,
-			issues,
-		})
-		const response = getInvalidSandboxMessageResponse(data)
-
-		const parsedIdentity = v.safeParse(initializationIdentitySchema, data)
-		const initializationId = parsedIdentity.success
-			? parsedIdentity.output.initializationId
-			: undefined
-		if (response.incomingType === "connect") {
-			if (initializationController.handleInvalidConnect(initializationId)) {
-				if (initializationId === undefined && response.nack !== undefined) {
-					post(response.nack)
-				}
-				return
-			}
-		}
-		if (
-			response.incomingType === "initResult" &&
-			initializationController.handleInvalidInitResult()
-		) {
-			if (response.nack !== undefined) {
-				post(response.nack)
-			}
-			return
-		}
-		if (response.nack !== undefined) {
-			post(response.nack)
-		}
-	}
-
-	function onMessage(event: MessageEvent) {
-		// Ignore messages from windows other than this host's iframe.
-		if (event.source !== iframe.contentWindow) {
-			return
-		}
-
-		// Ignore messages that do not come from the configured sandbox origin.
-		if (event.origin !== sandboxOrigin) {
-			return
-		}
-
-		const parsed = v.safeParse(sandboxToHostMessageSchema, event.data)
-		if (!parsed.success) {
-			onInvalidSandboxMessage(event.data, parsed.issues)
-			return
-		}
-
-		const message = parsed.output
-		emit("in", message)
-
-		if (
-			message.type !== "connect" &&
-			message.type !== "initResult" &&
-			initializationController.status !== "success"
-		) {
-			// Ignore all non-handshake messages until initialization succeeds.
-			if (message.type !== "resize") {
-				emit("warn", {
-					message: `Ignored ${message.type} before initialization completed`,
-					payload: message,
-				})
-			}
-			return
-		}
-
-		switch (message.type) {
-			case "connect":
-				initializationController.handleConnect(message)
-				return
-			case "initResult":
-				initializationController.handleInitResult(message)
-				return
-			case "queryDataSource":
-				void handleQuery(message)
-				return
-			case "unsubscribeDataSourceQuery":
-				querySubscriptions.unsubscribe(message.subscriptionId)
-				return
-			case "createPage":
-				void handleCreatePage(message)
-				return
-			case "getPage":
-				void handleGetPage(message)
-				return
-			case "getUser":
-				void handleGetUser(message)
-				return
-			case "listUsers":
-				void handleListUsers(message)
-				return
-			case "updatePage":
-				void handleUpdatePage(message)
-				return
-			case "resize":
-				handlers.resize?.(message)
-				return
-			case "invalidHostMessage":
-				return
-			default:
-				unreachable(message)
-		}
-	}
+	const onMessage = createSandboxMessageRouter({
+		iframe,
+		sandboxOrigin,
+		getInitStatus: () => initializationController.status,
+		emit,
+		post,
+		onInvalidConnect: initializationController.handleInvalidConnect,
+		onInvalidInitResult: initializationController.handleInvalidInitResult,
+		onConnect: initializationController.handleConnect,
+		onInitResult: initializationController.handleInitResult,
+		onQueryDataSource: handleQuery,
+		onUnsubscribeDataSourceQuery: message =>
+			querySubscriptions.unsubscribe(message.subscriptionId),
+		onCreatePage: handleCreatePage,
+		onGetPage: handleGetPage,
+		onGetUser: handleGetUser,
+		onListUsers: handleListUsers,
+		onUpdatePage: handleUpdatePage,
+		onResize: message => handlers.resize?.(message),
+	})
 
 	window.addEventListener("message", onMessage)
 	iframe.addEventListener("load", initializationController.onIframeLoad)
@@ -524,6 +438,7 @@ export function createCustomBlockHost(
 		setDataSources(nextDataSources) {
 			if (
 				initializationController.hasConnectedSandbox &&
+				manifest !== undefined &&
 				getBindingErrorCode(manifest, nextDataSources) !== undefined
 			) {
 				emit("warn", {

package/src/lifecycle/initializationController.ts

@@ -53,9 +53,8 @@ export type InitializationControllerOptions = {
 	minBridgeProtocolVersion: number
 	noConnectTimeoutMs?: number
 	noInitResultTimeoutMs?: number
-	onConnect?: (message: ConnectSuccessMessage) => void
 	onInitResult?: (message: InitResultMessage) => void
-	onIgnoredConnect?: (message: ConnectMessage) => void
+	onRestartRequired?: () => void
 	onInitializationFailure?: (
 		error: CustomBlockHostInitializationFailure,
 	) => void
@@ -66,8 +65,14 @@ export type InitializationController = {
 	readonly hasConnectedSandbox: boolean
 	handleConnect: (message: ConnectMessage) => void
 	handleInitResult: (message: InitResultMessage) => void
-	handleInvalidConnect: (initializationId?: string) => boolean
-	handleInvalidInitResult: () => boolean
+	handleInvalidConnect: (args: {
+		initializationId: string
+		error: CustomBlockInitErrorInfo
+	}) => "initErrorSent" | "nack"
+	handleInvalidInitResult: (args: {
+		initializationId: string | undefined
+		error: CustomBlockInitErrorInfo
+	}) => void
 	onIframeLoad: () => void
 	stop: () => void
 }
@@ -85,9 +90,8 @@ export function createInitializationController(
 		minBridgeProtocolVersion,
 		noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS,
 		noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS,
-		onConnect,
 		onInitResult,
-		onIgnoredConnect,
+		onRestartRequired,
 		onInitializationFailure,
 	} = options
 
@@ -111,10 +115,11 @@ export function createInitializationController(
 		}
 	}
 
-	function sendInitError(
-		initializationId: string,
-		error: CustomBlockInitErrorInfo,
-	) {
+	function sendInitError(args: {
+		initializationId: string
+		error: CustomBlockInitErrorInfo
+	}) {
+		const { initializationId, error } = args
 		if (initStatus !== "waitingForConnect") {
 			return
 		}
@@ -134,10 +139,12 @@ export function createInitializationController(
 		if (initStatus !== "waitingForConnect") {
 			return false
 		}
-		onConnect?.(connect)
 		const preparation = prepareInit(connect)
 		if (preparation.status === "error") {
-			sendInitError(connect.initializationId, preparation.error)
+			sendInitError({
+				initializationId: connect.initializationId,
+				error: preparation.error,
+			})
 			return false
 		}
 		initStatus = "waitingForInitResult"
@@ -185,7 +192,7 @@ export function createInitializationController(
 					"Ignored connect after initialization settled; recreate the host and iframe to re-initialize",
 				initializationId: message.initializationId,
 			})
-			onIgnoredConnect?.(message)
+			onRestartRequired?.()
 			return
 		}
 
@@ -194,7 +201,10 @@ export function createInitializationController(
 			const initError = initErrorForFailureReason("invalid_protocol_version", {
 				currentBridgeProtocolVersion: message.bridgeProtocolVersion,
 			})
-			sendInitError(message.initializationId, initError)
+			sendInitError({
+				initializationId: message.initializationId,
+				error: initError,
+			})
 			return
 		}
 		if (message.bridgeProtocolVersion < minBridgeProtocolVersion) {
@@ -205,13 +215,19 @@ export function createInitializationController(
 					minBridgeProtocolVersion,
 				},
 			)
-			sendInitError(message.initializationId, initError)
+			sendInitError({
+				initializationId: message.initializationId,
+				error: initError,
+			})
 			return
 		}
 
 		// If the sandbox reported an error during `connect`, return it as an `init` error.
 		if (message.status === "error") {
-			sendInitError(message.initializationId, message.error)
+			sendInitError({
+				initializationId: message.initializationId,
+				error: message.error,
+			})
 			return
 		}
 
@@ -220,32 +236,37 @@ export function createInitializationController(
 		}
 	}
 
-	function handleInvalidConnect(initializationId?: string): boolean {
+	function handleInvalidConnect(args: {
+		initializationId: string
+		error: CustomBlockInitErrorInfo
+	}): "initErrorSent" | "nack" {
+		const { initializationId, error } = args
 		if (initStatus !== "waitingForConnect") {
-			return false
-		}
-		const error = initErrorForFailureReason("invalid_connect_payload")
-		if (initializationId === undefined) {
-			initStatus = "error"
-			clearNoConnectTimeout()
-			warn(error)
-			onInitializationFailure?.(error)
-		} else {
-			sendInitError(initializationId, error)
+			// `connect` messages received when not waiting for one are NACKed like generic invalid messages.
+			return "nack"
 		}
-		return true
+		// The sandbox awaits `init`. Reply with `init.error` using its initialization ID.
+		sendInitError({ initializationId, error })
+		return "initErrorSent"
 	}
 
-	function handleInvalidInitResult(): boolean {
-		if (initStatus !== "waitingForInitResult") {
-			return false
+	function handleInvalidInitResult(args: {
+		initializationId: string | undefined
+		error: CustomBlockInitErrorInfo
+	}): void {
+		const { initializationId, error } = args
+		if (
+			initStatus !== "waitingForInitResult" ||
+			initializationId === undefined ||
+			initializationId !== activeInitializationId
+		) {
+			return
 		}
+		clearNoConnectTimeout()
 		clearNoInitResultTimeout()
 		initStatus = "error"
-		const error = initErrorForFailureReason("invalid_init_result_payload")
 		warn(error)
 		onInitializationFailure?.(error)
-		return true
 	}
 
 	function onIframeLoad() {