@notionhq/custom-blocks-host 0.1.31 → 0.2.0

package/src/createCustomBlockHost.ts

@@ -1,12 +1,7 @@
-import {
-	DEFAULT_CONTRAST_MODE,
-	type NotionContrastMode,
-} from "@notionhq/custom-blocks-protocol/contrast.js"
+import type { NotionContrastMode } from "@notionhq/custom-blocks-protocol/contrast.js"
 import type { NotionCollectionSchema } from "@notionhq/custom-blocks-protocol/dataSources/dataSource.js"
 import type { NotionDataSourceId } from "@notionhq/custom-blocks-protocol/ids.js"
 import type { CustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest.js"
-import type { ContrastModeChangedMessage } from "@notionhq/custom-blocks-protocol/messages/contrastModeChanged.js"
-import type { DataSourcesChangedMessage } from "@notionhq/custom-blocks-protocol/messages/dataSourcesChanged.js"
 import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
 import type {
 	CustomBlockInitErrorCode,
@@ -14,15 +9,12 @@ import type {
 } from "@notionhq/custom-blocks-protocol/messages/init.js"
 import type { InvalidSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/invalidSandboxMessage.js"
 import type { BridgeMessagePayload } from "@notionhq/custom-blocks-protocol/messages/messagePayload.js"
-import type { PageChangedMessage } from "@notionhq/custom-blocks-protocol/messages/pageChanged.js"
-import type { ParentChangedMessage } from "@notionhq/custom-blocks-protocol/messages/parentChanged.js"
 import type { QueryDataSourceMessage } from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
 import type {
 	CustomBlockQueryDataSourceErrorInfo,
 	QueryDataSourceResultMessage,
 } from "@notionhq/custom-blocks-protocol/messages/queryDataSourceResult.js"
 import type { SandboxToHostMessage } from "@notionhq/custom-blocks-protocol/messages/sandboxToHost.js"
-import type { ThemeChangedMessage } from "@notionhq/custom-blocks-protocol/messages/themeChanged.js"
 import type { CustomBlockPage } from "@notionhq/custom-blocks-protocol/pages/page.js"
 import type { NotionParent } from "@notionhq/custom-blocks-protocol/parent.js"
 import { LATEST_BRIDGE_PROTOCOL_VERSION } from "@notionhq/custom-blocks-protocol/protocolVersion.js"
@@ -33,7 +25,9 @@ import { createInitializationController } from "./lifecycle/initializationContro
 import { normalizeHostToSandboxMessage } from "./lifecycle/normalizeHostToSandboxMessage.js"
 import type {
 	CustomBlockHostDataSourcesPayload,
+	CustomBlockHostGetInitialState,
 	CustomBlockHostInitialState,
+	CustomBlockHostInitialStateResult,
 } from "./lifecycle/types.js"
 import { createSandboxMessageRouter } from "./messages/sandboxMessageRouter.js"
 import type {
@@ -59,19 +53,15 @@ 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: {
@@ -86,6 +76,8 @@ export type CustomBlockHostOptions = {
 	 */
 	onFailure?: (error: CustomBlockHostFailure) => void
 	onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void
+	getInitialState: CustomBlockHostGetInitialState
+	initialStateTimeoutMs?: number
 }
 
 export type CustomBlockHostHandle = {
@@ -127,7 +119,7 @@ export function createCustomBlockHost(
 ): CustomBlockHostHandle {
 	const {
 		iframe,
-		initialState,
+		getInitialState,
 		handlers,
 		onManifest,
 		onInitialized,
@@ -136,31 +128,25 @@ export function createCustomBlockHost(
 		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.
+	// 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
+	type HostStateUpdates = Partial<
+		Omit<CustomBlockHostInitialState, "blockId" | "manifest">
+	>
+	let pendingState: HostStateUpdates = {}
+	let hasPreparedInitialState = false
+	let manifest: CustomBlockManifest | undefined
 	let activeDataSources: CustomBlockHostDataSourcesPayload | undefined
 	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: CustomBlockHostDataSourcesPayload | undefined
-	let pendingCurrentUserChange = false
 	const querySubscriptions = new QuerySubscriptions()
 
 	function emit(direction: CustomBlockHostLogDirection, payload: unknown) {
@@ -171,6 +157,7 @@ export function createCustomBlockHost(
 		const status = initializationController.status
 		switch (status) {
 			case "waitingForConnect":
+			case "preparingInit":
 			case "waitingForInitResult":
 			case "initialized":
 			case "error":
@@ -211,6 +198,7 @@ export function createCustomBlockHost(
 				return
 			// Send state updates and handler results only after initialization succeeds.
 			case "waitingForConnect":
+			case "preparingInit":
 			case "waitingForInitResult":
 			case "error":
 			case "stopped":
@@ -290,95 +278,69 @@ export function createCustomBlockHost(
 		})
 	}
 
-	/**
-	 * 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 not send pending state changes until the sandbox responds.
-	 */
+	function updateHostState(update: HostStateUpdates) {
+		if (
+			initializationController.status === "stopped" ||
+			initializationController.status === "error"
+		) {
+			return
+		}
+		Object.assign(pendingState, update)
+		flushPendingHostStateChanges()
+	}
+
 	function flushPendingHostStateChanges() {
-		if (pendingThemeChange) {
-			pendingThemeChange = false
-			sendInitializedMessage({ 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
 		}
-		if (pendingContrastModeChange) {
-			pendingContrastModeChange = false
-			sendInitializedMessage({ type: "contrastModeChanged", contrastMode })
+		const changes = pendingState
+		pendingState = {}
+		if (changes.theme !== undefined) {
+			sendInitializedMessage({ type: "themeChanged", theme: changes.theme })
+		}
+		if (changes.contrastMode !== undefined) {
+			sendInitializedMessage({
+				type: "contrastModeChanged",
+				contrastMode: changes.contrastMode,
+			})
 		}
-		if (pendingParentChange) {
-			pendingParentChange = false
-			sendInitializedMessage({ type: "parentChanged", parent })
+		if (changes.parent !== undefined) {
+			sendInitializedMessage({ type: "parentChanged", parent: changes.parent })
 		}
-		if (pendingPageChange) {
-			pendingPageChange = false
-			sendInitializedMessage({ type: "pageChanged", page })
+		if (changes.page !== undefined) {
+			sendInitializedMessage({ type: "pageChanged", page: changes.page })
 		}
-		if (pendingDataSourcesChange !== undefined) {
-			const nextDataSources = pendingDataSourcesChange
-			pendingDataSourcesChange = undefined
+		if (changes.dataSources !== undefined) {
 			sendInitializedMessage({
 				type: "dataSourcesChanged",
-				dataSources: nextDataSources,
+				dataSources: changes.dataSources,
 			})
 		}
-		if (pendingCurrentUserChange) {
-			pendingCurrentUserChange = false
-			sendInitializedMessage({ 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),
-				}
-			}
-			activeDataSources = resolvedDataSources
-			return {
-				status: "success",
-				manifest,
-				dataSources: resolvedDataSources,
+			const result = await getInitialState(connect)
+			if (initializationController.status !== "preparingInit") {
+				return result
 			}
+			return prepareInitialState(result)
 		},
 		sendInitMessage,
 		warn: payload => emit("warn", payload),
 		flushPendingHostStateChanges,
 		minBridgeProtocolVersion,
 		noConnectTimeoutMs,
+		initialStateTimeoutMs,
 		noInitResultTimeoutMs,
 		stopHostWithFailure: stopWithFailure,
 		onInitResult(message) {
@@ -389,6 +351,41 @@ export function createCustomBlockHost(
 		onFailure,
 	})
 
+	function prepareInitialState(
+		result: CustomBlockHostInitialStateResult,
+	): CustomBlockHostInitialStateResult {
+		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,
@@ -429,98 +426,47 @@ export function createCustomBlockHost(
 
 	return {
 		stop,
-		setTheme(nextTheme) {
-			theme = nextTheme
-			if (initializationController.status !== "initialized") {
-				if (initializationController.status === "waitingForInitResult") {
-					pendingThemeChange = true
-				}
-				return
-			}
-			const message: ThemeChangedMessage = { type: "themeChanged", theme }
-			sendInitializedMessage(message)
+		setTheme(theme) {
+			updateHostState({ theme })
 		},
-		setContrastMode(nextContrastMode) {
-			contrastMode = nextContrastMode
-			if (initializationController.status !== "initialized") {
-				if (initializationController.status === "waitingForInitResult") {
-					pendingContrastModeChange = true
-				}
-				return
-			}
-			const message: ContrastModeChangedMessage = {
-				type: "contrastModeChanged",
-				contrastMode,
-			}
-			sendInitializedMessage(message)
+		setContrastMode(contrastMode) {
+			updateHostState({ contrastMode })
 		},
-		setParent(nextParent) {
-			parent = nextParent
-			if (initializationController.status !== "initialized") {
-				if (initializationController.status === "waitingForInitResult") {
-					pendingParentChange = true
-				}
-				return
-			}
-			const message: ParentChangedMessage = { type: "parentChanged", parent }
-			sendInitializedMessage(message)
+		setParent(parent) {
+			updateHostState({ parent })
 		},
-		setPage(nextPage) {
-			page = nextPage
+		setPage(page) {
 			if (
-				nextPage.type === "unavailable" &&
+				page.type === "unavailable" &&
 				sandboxBridgeProtocolVersion <
 					BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE &&
-				(initializationController.status === "waitingForInitResult" ||
+				((initializationController.status === "preparingInit" &&
+					hasPreparedInitialState) ||
+					initializationController.status === "waitingForInitResult" ||
 					initializationController.status === "initialized")
 			) {
 				stopWithFailure(initErrorForFailureReason("context_unavailable"))
 				return
 			}
-			if (initializationController.status !== "initialized") {
-				if (initializationController.status === "waitingForInitResult") {
-					pendingPageChange = true
-				}
-				return
-			}
-			const message: PageChangedMessage = { type: "pageChanged", page }
-			sendInitializedMessage(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 !== "initialized") {
-				if (initializationController.status === "waitingForInitResult") {
-					pendingDataSourcesChange = nextDataSources
-				}
-				return
-			}
-			const message: DataSourcesChangedMessage = {
-				type: "dataSourcesChanged",
-				dataSources: nextDataSources,
-			}
-			sendInitializedMessage(message)
-		},
-		setCurrentUser(nextCurrentUser) {
-			currentUser = nextCurrentUser
-			if (initializationController.status !== "initialized") {
-				if (initializationController.status === "waitingForInitResult") {
-					pendingCurrentUserChange = true
-				}
-				return
-			}
-			sendInitializedMessage({ type: "currentUserChanged", currentUser })
+			activeDataSources = dataSources
+			updateHostState({ dataSources })
 		},
 		refreshQuery({ dataSourceId }) {
 			if (initializationController.status !== "initialized") {

package/src/index.ts

@@ -23,8 +23,9 @@ export {
 export type {
 	ConnectSuccessMessage,
 	CustomBlockHostDataSourcesPayload,
-	CustomBlockHostInitialDataSources,
+	CustomBlockHostGetInitialState,
 	CustomBlockHostInitialState,
+	CustomBlockHostInitialStateResult,
 } from "./lifecycle/types.js"
 export type {
 	CreatePageMessageInput,

package/src/lifecycle/initErrors.ts

@@ -90,6 +90,12 @@ export function initErrorForFailureReason(
 				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,