@notionhq/custom-blocks-host 0.3.8 → 0.4.0

package/src/createCustomBlockHost.ts

@@ -10,6 +10,7 @@ import {
 } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
 import {
 	type CustomBlockInitErrorInfo,
+	CustomBlockInitializationError,
 	initMessageSchema,
 } from "@notionhq/custom-blocks-protocol/messages/init.js"
 import type { InvalidSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/invalidSandboxMessage.js"
@@ -30,25 +31,34 @@ import type { notionThemeSchema } from "@notionhq/custom-blocks-protocol/theme.j
 import type { notionUserSchema } from "@notionhq/custom-blocks-protocol/users/user.js"
 import type { InferInput } from "valibot"
 import * as v from "valibot"
+import { normalizeHostToSandboxMessage } from "./compatibility/normalizeHostToSandboxMessage.js"
+import { isAllowedLocalPreviewUrl } from "./isAllowedLocalPreviewUrl.js"
 import {
 	contextUnavailableError,
+	invalidLocalPreviewUrlError,
 	invalidPropertyBindingError,
 	missingDataSourceBindingError,
 	missingPropertyBindingError,
 	unknownInitializationError,
 } from "./lifecycle/initErrors.js"
 import { createInitializationController } from "./lifecycle/initializationController.js"
-import { loadCustomBlockManifest } from "./lifecycle/loadCustomBlockManifest.js"
-import type { CustomBlockHostManifestOptions } from "./lifecycle/manifestOptions.js"
-import { normalizeHostToSandboxMessage } from "./lifecycle/normalizeHostToSandboxMessage.js"
+import { resolveManifest } from "./lifecycle/resolveManifest.js"
 import type {
 	CustomBlockHostDataSourcesPayload,
 	CustomBlockHostInitialState,
 	CustomBlockHostInitialStateResult,
+	CustomBlockHostManifestResult,
 	CustomBlockHostNormalizedDataSourcesPayload,
+	CustomBlockHostNormalizedManifestResult,
 	CustomBlockHostPrepareInitialState,
+	CustomBlockHostStatus,
+	CustomBlockManifestSource,
+} from "./lifecycle/types.js"
+import {
+	customBlockHostInitialStateSchema,
+	customBlockHostManifestResultSchema,
+	customBlockHostPreparedStateResultSchema,
 } from "./lifecycle/types.js"
-import { customBlockHostInitialStateSchema } from "./lifecycle/types.js"
 import { parseExternalUrl } from "./messages/parseExternalUrl.js"
 import { createSandboxMessageRouter } from "./messages/sandboxMessageRouter.js"
 import type {
@@ -70,9 +80,20 @@ import { unreachable } from "./utils.js"
 // Earlier SDKs cannot represent this context, so the host reports context_unavailable.
 const BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE = 5
 
-export type CustomBlockHostOptions = CustomBlockHostManifestOptions & {
+export type CustomBlockHostOptions = {
+	manifestSource: CustomBlockManifestSource
+	/**
+	 * Returns success with a persisted manifest or an explicit loading error, never null or
+	 * undefined. The host validates the result and applies manifest defaults. It calls this
+	 * when created, regardless of manifestSource. A returned error prevents initialization
+	 * only when manifestSource is "host".
+	 */
+	getPersistedManifest: (args: {
+		signal: AbortSignal
+	}) => Promise<CustomBlockHostManifestResult>
 	iframe: HTMLIFrameElement
-	sandboxOrigin: string
+	/** Full block URL. Its origin is used to authenticate bridge messages. */
+	sandboxUrl: string
 	/**
 	 * Minimum sandbox protocol version to accept. Defaults to the host runtime
 	 * minimum. Higher values retire older SDKs; lower values cannot enable
@@ -82,22 +103,12 @@ export type CustomBlockHostOptions = CustomBlockHostManifestOptions & {
 	noConnectTimeoutMs?: number
 	noInitResultTimeoutMs?: number
 	handlers: CustomBlockHostHandlers
-	/** Callback fired when the initialization handshake with the sandbox completed successfully. */
-	onInitialized?: (state: {
-		manifest: CustomBlockManifest
-		initialHeight?: number
-	}) => void
-	/**
-	 * 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.
-	 */
-	onConnectionFailure: ((error: CustomBlockHostFailure) => void) | undefined
+	/** Reports accepted lifecycle transitions, starting synchronously with waitingForConnect. */
+	onStatusChange: (state: CustomBlockHostStatus) => void
 	/** Releases adapter resources when a query ends, including replacement and terminal errors. */
 	onQueryUnsubscribed: ((subscriptionId: string) => void) | undefined
 	onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void
-	/** Runs once, as soon as the manifest is validated, independently of connect. */
+	/** Runs once, after the selected manifest is validated. */
 	prepareInitialState: CustomBlockHostPrepareInitialState
 	initialStateTimeoutMs?: number
 }
@@ -130,16 +141,16 @@ export function createCustomBlockHost(
 		iframe,
 		prepareInitialState: prepareAdapterState,
 		handlers,
-		onInitialized,
-		onConnectionFailure,
+		onStatusChange,
 		onLog,
 		onQueryUnsubscribed,
-		sandboxOrigin,
 		minBridgeProtocolVersion: configuredMinBridgeProtocolVersion,
 		noConnectTimeoutMs,
 		initialStateTimeoutMs,
 		noInitResultTimeoutMs,
 	} = options
+	const sandboxUrl = parseSandboxUrl(options.sandboxUrl, options.manifestSource)
+	const sandboxOrigin = sandboxUrl.origin
 	// 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(
@@ -175,7 +186,7 @@ export function createCustomBlockHost(
 			case "preparingInit":
 			case "waitingForInitResult":
 			case "initialized":
-			case "error":
+			case "failed":
 				break
 			// A stopped host must not send messages, including pending responses.
 			// Return from the function to skip delivery below.
@@ -210,7 +221,7 @@ export function createCustomBlockHost(
 			case "waitingForConnect":
 			case "preparingInit":
 			case "waitingForInitResult":
-			case "error":
+			case "failed":
 			case "stopped":
 				return
 			default:
@@ -304,7 +315,7 @@ export function createCustomBlockHost(
 	function updateHostState(update: HostStateUpdates) {
 		if (
 			initializationController.status === "stopped" ||
-			initializationController.status === "error"
+			initializationController.status === "failed"
 		) {
 			return
 		}
@@ -419,15 +430,30 @@ export function createCustomBlockHost(
 	}
 
 	const initializationController = createInitializationController({
+		manifestSource: options.manifestSource,
 		async prepareInit(connect) {
+			const connectManifest =
+				connect.status === "success" ? connect.manifest : undefined
 			sandboxBridgeProtocolVersion = connect.bridgeProtocolVersion
-			const result = await preparation
+			onStatusChange({
+				status: "preparingInit",
+				localManifest: isAllowedLocalPreviewUrl({
+					url: sandboxUrl,
+					hostOrigin: window.location.origin,
+				})
+					? connectManifest
+					: undefined,
+				bridgeProtocolVersion: connect.bridgeProtocolVersion,
+				sdkVersion: connect.sdkVersion,
+			})
+			const result = await (preparation ?? prepare(connectManifest))
 			if (initializationController.status !== "preparingInit") {
 				return result
 			}
 			return finalizeInitialState(result)
 		},
 		sendInitMessage,
+		onInitSent: () => onStatusChange({ status: "waitingForInitResult" }),
 		warn: payload => emit("warn", payload),
 		flushPendingHostStateChanges,
 		minBridgeProtocolVersion,
@@ -437,12 +463,16 @@ export function createCustomBlockHost(
 		stopHostWithFailure: stopWithFailure,
 		onInitResult(message) {
 			if (message.status === "success" && manifest !== undefined) {
-				onInitialized?.({ manifest, initialHeight: message.initialHeight })
+				onStatusChange({
+					status: "initialized",
+					resolvedManifest: manifest,
+					initialHeight: message.initialHeight,
+				})
 			}
 		},
 		onConnectionFailure: failure => {
 			preparationController.abort()
-			onConnectionFailure?.(failure)
+			onStatusChange({ status: "failed", error: failure })
 		},
 	})
 
@@ -484,46 +514,64 @@ export function createCustomBlockHost(
 		return { status: "success", initialState }
 	}
 
-	// Attach rejection handling immediately: preparation may finish before connect.
-	const preparation = prepare().catch(
-		(error: unknown): CustomBlockHostInitialStateResult => {
-			if (!preparationController.signal.aborted) {
-				emit("warn", {
-					message: "Failed to prepare custom block initialization",
-					error,
-				})
-			}
-			return { status: "error", error: unknownInitializationError() }
-		},
-	)
+	// Neither manifest source waits for the other. Observe rejections immediately,
+	// including failures from a host manifest that is not selected.
+	const hostManifest = readHostManifest().catch(handlePreparationError)
+	const preparation =
+		options.manifestSource === "host"
+			? prepare(undefined).catch(handlePreparationError)
+			: undefined
 
-	async function prepare(): Promise<CustomBlockHostInitialStateResult> {
-		const loaded = await loadCustomBlockManifest({
-			...options,
-			sandboxOrigin,
+	async function readHostManifest(): Promise<CustomBlockHostNormalizedManifestResult> {
+		preparationController.signal.throwIfAborted()
+		const result = await options.getPersistedManifest({
 			signal: preparationController.signal,
-			onError: error => {
-				emit("warn", {
-					message: "Failed to load custom block manifest",
-					error,
-				})
-			},
 		})
-		if (loaded.status === "error") {
-			return loaded
-		}
-		if (preparationController.signal.aborted) {
-			return { status: "error", error: unknownInitializationError() }
+		preparationController.signal.throwIfAborted()
+		return v.parse(customBlockHostManifestResultSchema, result)
+	}
+
+	function handlePreparationError(error: unknown): {
+		status: "error"
+		error: CustomBlockInitErrorInfo
+	} {
+		if (!preparationController.signal.aborted) {
+			emit("warn", {
+				message: "Failed to prepare custom block initialization",
+				error,
+			})
 		}
-		const result = await prepareAdapterState({
-			manifest: loaded.manifest,
-			signal: preparationController.signal,
+		return { status: "error", error: unknownInitializationError() }
+	}
+
+	async function prepare(
+		connectManifest: CustomBlockManifest | undefined,
+	): Promise<CustomBlockHostInitialStateResult> {
+		preparationController.signal.throwIfAborted()
+		const manifestResult = await resolveManifest({
+			manifestSource: options.manifestSource,
+			hostManifest,
+			connectManifest,
 		})
+		preparationController.signal.throwIfAborted()
+		if (manifestResult.status === "error") {
+			return manifestResult
+		}
+		const result = v.parse(
+			customBlockHostPreparedStateResultSchema,
+			await prepareAdapterState({
+				manifest: manifestResult.manifest,
+				signal: preparationController.signal,
+			}),
+		)
 		return result.status === "error"
 			? result
 			: {
 					status: "success",
-					initialState: { ...result.initialState, manifest: loaded.manifest },
+					initialState: {
+						...result.initialState,
+						manifest: manifestResult.manifest,
+					},
 				}
 	}
 
@@ -552,7 +600,7 @@ export function createCustomBlockHost(
 
 	window.addEventListener("message", onMessage)
 	iframe.addEventListener("load", initializationController.onIframeLoad)
-	function stop() {
+	function releaseResources() {
 		navigationAbortController.abort()
 		preparationController.abort()
 		window.removeEventListener("message", onMessage)
@@ -561,12 +609,29 @@ export function createCustomBlockHost(
 		querySubscriptions.unsubscribeAll()
 	}
 
+	function stop() {
+		const previousStatus = initializationController.status
+		releaseResources()
+		if (previousStatus !== "stopped" && previousStatus !== "failed") {
+			onStatusChange({ status: "stopped" })
+		}
+	}
+
 	function stopWithFailure(error: CustomBlockHostFailure) {
-		stop()
+		if (initializationController.status === "stopped") {
+			return
+		}
+		if (initializationController.status === "failed") {
+			releaseResources()
+			return
+		}
+		releaseResources()
 		emit("warn", error)
-		onConnectionFailure?.(error)
+		onStatusChange({ status: "failed", error })
 	}
 
+	onStatusChange({ status: "waitingForConnect" })
+
 	return {
 		stop,
 		setTheme(theme) {
@@ -642,6 +707,31 @@ export function createCustomBlockHost(
 	}
 }
 
+function parseSandboxUrl(
+	url: string,
+	manifestSource: CustomBlockManifestSource,
+): URL {
+	let parsed: URL
+	try {
+		parsed = new URL(url)
+	} catch (error) {
+		if (manifestSource === "host") {
+			throw error
+		}
+		throw new CustomBlockInitializationError(invalidLocalPreviewUrlError())
+	}
+	if (
+		manifestSource === "sandbox" &&
+		!isAllowedLocalPreviewUrl({
+			url: parsed,
+			hostOrigin: window.location.origin,
+		})
+	) {
+		throw new CustomBlockInitializationError(invalidLocalPreviewUrlError())
+	}
+	return parsed
+}
+
 function getCollectionSchema(
 	dataSources: CustomBlockHostNormalizedDataSourcesPayload | undefined,
 	dataSourceId: NotionDataSourceId,

package/src/index.ts

@@ -1,51 +1,3 @@
-export type { LegacyNotionDataSourcePageBridge } from "@notionhq/custom-blocks-protocol/dataSources/dataSourcePage.js"
-export type { NotionPropertySchemasById } from "@notionhq/custom-blocks-protocol/dataSources/propertySchema.js"
-export type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/errors.js"
-export type { NotionPageId } from "@notionhq/custom-blocks-protocol/ids.js"
-export type { CustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest.js"
-export type { CreatePageMessage } from "@notionhq/custom-blocks-protocol/messages/createPage.js"
-export type { GetPageMessage } from "@notionhq/custom-blocks-protocol/messages/getPage.js"
-export type { GetUserMessage } from "@notionhq/custom-blocks-protocol/messages/getUser.js"
-export type { ListUsersMessage } from "@notionhq/custom-blocks-protocol/messages/listUsers.js"
-export type { OpenExternalUrlMessage } from "@notionhq/custom-blocks-protocol/messages/openExternalUrl.js"
-export type { OpenPageMessage } from "@notionhq/custom-blocks-protocol/messages/openPage.js"
-export type {
-	CustomBlockCheckboxFilterOperator,
-	CustomBlockContainsFilterOperator,
-	CustomBlockCreatedByFilterOperator,
-	CustomBlockDateFilterOperator,
-	CustomBlockNumberFilterOperator,
-	CustomBlockOptionFilterOperator,
-	CustomBlockPeopleFilterOperator,
-	CustomBlockPersonFilterValue,
-	CustomBlockRelationFilterOperator,
-	CustomBlockStatusFilterOperator,
-	CustomBlockStatusGroupFilterOperator,
-	CustomBlockStatusGroupName,
-	CustomBlockTextFilterOperator,
-	QueryDataSourceMessage,
-	ResolvedCustomBlockDataSourceFilter,
-	ResolvedCustomBlockDataSourcePropertyFilter,
-	ResolvedCustomBlockDataSourceSort,
-} from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
-export type { ResizeMessage } from "@notionhq/custom-blocks-protocol/messages/resize.js"
-export type { UpdatePageMessage } from "@notionhq/custom-blocks-protocol/messages/updatePage.js"
-export type {
-	NotionDateInput,
-	NotionFileInput,
-	NotionPageCover,
-	NotionPageData,
-	NotionPageIcon,
-	NotionPagePropertyReadMap,
-	NotionPagePropertyValue,
-	NotionPagePropertyWriteMap,
-	NotionRichTextItem,
-	NotionSelectOptionInput,
-} from "@notionhq/custom-blocks-protocol/pages/page.js"
-export {
-	LATEST_BRIDGE_PROTOCOL_VERSION,
-	LEGACY_PROPERTY_SHAPE_PROTOCOL_VERSION,
-} from "@notionhq/custom-blocks-protocol/protocolVersion.js"
 export {
 	type AutoBindableProperty,
 	getAutoBoundPropertyIdsByKey,
@@ -61,16 +13,17 @@ export {
 	toNotionDateValue,
 } from "./dateValue.js"
 export { toNotionPageId } from "./ids.js"
-export type { CustomBlockHostManifestOptions } from "./lifecycle/manifestOptions.js"
+export { isAllowedLocalPreviewUrl } from "./isAllowedLocalPreviewUrl.js"
 export type {
-	ConnectSuccessMessage,
 	CustomBlockHostDataSourcesPayload,
 	CustomBlockHostInitialState,
 	CustomBlockHostInitialStateResult,
+	CustomBlockHostManifestResult,
 	CustomBlockHostPreparedStateResult,
 	CustomBlockHostPrepareInitialState,
+	CustomBlockHostStatus,
+	CustomBlockManifestSource,
 } from "./lifecycle/types.js"
-export { isLocalCustomBlockUrl } from "./localBlockUrl.js"
 export type {
 	CreatePageMessageInput,
 	CustomBlockHostCreatePageResult,

package/src/{localBlockUrl.ts → isAllowedLocalPreviewUrl.ts}

@@ -1,10 +1,12 @@
+import { isLocalBlockServerUrl } from "@notionhq/custom-blocks-protocol/isLocalBlockServerUrl.js"
+
 /**
  * Checks whether a URL can serve a local custom block over HTTP or HTTPS.
  * Accepts localhost, any .localhost subdomain, and 127.0.0.1 without credentials.
  * Local refers to the block server, not the environment where the host runs.
  * Requires the embedding page's origin and rejects URLs that share that origin.
  */
-export function isLocalCustomBlockUrl({
+export function isAllowedLocalPreviewUrl({
 	url,
 	hostOrigin,
 }: {
@@ -15,11 +17,6 @@ export function isLocalCustomBlockUrl({
 		typeof hostOrigin === "string" &&
 		hostOrigin !== "" &&
 		url.origin !== hostOrigin &&
-		(url.protocol === "http:" || url.protocol === "https:") &&
-		(url.hostname === "localhost" ||
-			url.hostname === "127.0.0.1" ||
-			url.hostname.endsWith(".localhost")) &&
-		url.username === "" &&
-		url.password === ""
+		isLocalBlockServerUrl(url)
 	)
 }

package/src/lifecycle/initErrors.ts

@@ -120,3 +120,12 @@ export function unknownInitializationError(): CustomBlockErrorInfo<"unknown_erro
 		isRetryable: false,
 	}
 }
+
+export function invalidLocalPreviewUrlError(): CustomBlockErrorInfo<"invalid_local_preview_url"> {
+	return {
+		code: "invalid_local_preview_url",
+		message:
+			"Local custom blocks require an HTTP(S) URL on localhost, a .localhost subdomain, or 127.0.0.1, without credentials and on a different origin from the host.",
+		isRetryable: false,
+	}
+}

package/src/lifecycle/initializationController.ts

@@ -18,8 +18,8 @@ import {
 } from "./initErrors.js"
 import { isValidBridgeProtocolVersion } from "./protocolVersion.js"
 import type {
-	ConnectSuccessMessage,
 	CustomBlockHostInitialStateResult,
+	CustomBlockManifestSource,
 	InitStatus,
 } from "./types.js"
 
@@ -28,8 +28,9 @@ const DEFAULT_INITIAL_STATE_TIMEOUT_MS = 5_000
 const DEFAULT_NO_INIT_RESULT_TIMEOUT_MS = 5_000
 
 export type InitializationControllerOptions = {
+	manifestSource: CustomBlockManifestSource
 	prepareInit: (
-		connect: ConnectSuccessMessage,
+		connect: ConnectMessage,
 	) => Promise<CustomBlockHostInitialStateResult>
 	sendInitMessage: (message: InferInput<typeof initMessageSchema>) => void
 	warn: (payload: unknown) => void
@@ -39,8 +40,9 @@ export type InitializationControllerOptions = {
 	initialStateTimeoutMs?: number
 	noInitResultTimeoutMs?: number
 	stopHostWithFailure: (error: CustomBlockHostFailure) => void
-	onInitResult?: (message: InitResultMessage) => void
-	onConnectionFailure: ((error: CustomBlockHostFailure) => void) | undefined
+	onInitResult: (message: InitResultMessage) => void
+	onInitSent: () => void
+	onConnectionFailure: (error: CustomBlockHostFailure) => void
 }
 
 export type InitializationController = {
@@ -65,6 +67,7 @@ export function createInitializationController(
 	options: InitializationControllerOptions,
 ): InitializationController {
 	const {
+		manifestSource,
 		prepareInit,
 		sendInitMessage,
 		warn,
@@ -75,6 +78,7 @@ export function createInitializationController(
 		noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS,
 		stopHostWithFailure,
 		onInitResult,
+		onInitSent,
 		onConnectionFailure,
 	} = options
 
@@ -120,13 +124,13 @@ export function createInitializationController(
 				break
 			case "waitingForInitResult":
 			case "initialized":
-			case "error":
+			case "failed":
 			case "stopped":
 				return
 			default:
 				return unreachable(initStatus)
 		}
-		initStatus = "error"
+		initStatus = "failed"
 		activeInitializationId = initializationId
 		clearNoConnectTimeout()
 		clearInitialStateTimeout()
@@ -136,10 +140,10 @@ export function createInitializationController(
 			status: "error",
 			error,
 		})
-		onConnectionFailure?.({ ...error, phase, source })
+		onConnectionFailure({ ...error, phase, source })
 	}
 
-	async function prepareAndSendInit(connect: ConnectSuccessMessage) {
+	async function prepareAndSendInit(connect: ConnectMessage) {
 		if (initStatus !== "waitingForConnect") {
 			return
 		}
@@ -194,13 +198,20 @@ export function createInitializationController(
 				dataSources: preparation.initialState.dataSources,
 			}
 			sendInitMessage(message)
+			if (initStatus !== "waitingForInitResult") {
+				return
+			}
+			onInitSent()
+			if (initStatus !== "waitingForInitResult") {
+				return
+			}
 			noInitResultTimeoutId = window.setTimeout(() => {
 				if (initStatus !== "waitingForInitResult") {
 					return
 				}
-				initStatus = "error"
+				initStatus = "failed"
 				const error = noInitResultError()
-				onConnectionFailure?.({ ...error, phase: "initResult", source: "host" })
+				onConnectionFailure({ ...error, phase: "initResult", source: "host" })
 				warn({
 					...error,
 					initializationId: connect.initializationId,
@@ -258,8 +269,12 @@ export function createInitializationController(
 			return
 		}
 
-		// If the sandbox reported an error during `connect`, return it as an `init` error.
-		if (message.status === "error") {
+		// Invalid sandbox metadata does not prevent initialization from a host manifest.
+		if (
+			message.status === "error" &&
+			(manifestSource === "sandbox" ||
+				message.error.code !== "manifest_invalid")
+		) {
 			sendInitError({
 				initializationId: message.initializationId,
 				error: message.error,
@@ -322,9 +337,9 @@ export function createInitializationController(
 		}
 		clearNoConnectTimeout()
 		clearNoInitResultTimeout()
-		initStatus = "error"
+		initStatus = "failed"
 		warn(error)
-		onConnectionFailure?.({ ...error, phase: "initResult", source: "host" })
+		onConnectionFailure({ ...error, phase: "initResult", source: "host" })
 	}
 
 	function onIframeLoad() {
@@ -353,10 +368,10 @@ export function createInitializationController(
 				// Only do anything if the iframe loaded before the `connect` message was sent.
 				return
 			}
-			initStatus = "error"
+			initStatus = "failed"
 			const error = noConnectError()
 			warn(error)
-			onConnectionFailure?.({ ...error, phase: "connect", source: "host" })
+			onConnectionFailure({ ...error, phase: "connect", source: "host" })
 		}, noConnectTimeoutMs)
 	}
 
@@ -372,17 +387,17 @@ export function createInitializationController(
 			return
 		}
 		clearNoInitResultTimeout()
-		initStatus = message.status === "success" ? "initialized" : "error"
+		initStatus = message.status === "success" ? "initialized" : "failed"
 		if (message.status === "success") {
 			flushPendingHostStateChanges()
 		} else {
-			onConnectionFailure?.({
+			onConnectionFailure({
 				...message.error,
 				phase: "initResult",
 				source: "sandbox",
 			})
 		}
-		onInitResult?.(message)
+		onInitResult(message)
 	}
 
 	function stop() {

package/src/lifecycle/resolveManifest.ts

@@ -0,0 +1,31 @@
+import type { CustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest.js"
+import type {
+	CustomBlockHostNormalizedManifestResult,
+	CustomBlockManifestSource,
+} from "./types.js"
+
+/**
+ * Select the host's manifest result or the sandbox's connect declaration. Both
+ * sources are already validated. Forward host errors unchanged, and report
+ * manifest_unavailable if the sandbox omits its declaration.
+ */
+export async function resolveManifest(args: {
+	manifestSource: CustomBlockManifestSource
+	hostManifest: Promise<CustomBlockHostNormalizedManifestResult>
+	connectManifest: CustomBlockManifest | undefined
+}): Promise<CustomBlockHostNormalizedManifestResult> {
+	if (args.manifestSource === "host") {
+		return args.hostManifest
+	}
+	if (args.connectManifest !== undefined) {
+		return { status: "success", manifest: args.connectManifest }
+	}
+	return {
+		status: "error",
+		error: {
+			code: "manifest_unavailable",
+			message: "The sandbox did not provide a manifest in connect.",
+			isRetryable: false,
+		},
+	}
+}