@notionhq/custom-blocks 0.0.76 → 0.0.78

package/docs/lifecycle.md

@@ -4,9 +4,15 @@ The SDK ↔ host handshake, the React wrapper that runs it, and the auto-resize
 
 ## Handshake
 
-`initCustomBlock()` posts `ready` to `window.parent` and awaits the host's `init` (theme, block ID/parent/page ID, current user, and `dataSources: { bindings }` keyed by semantic data-source key, which the SDK resolves against the manifest). The promise resolves with the normalized initial state, captured in `CustomBlockInitPayload` — `await` it before mounting React so hooks always see populated state.
+`initCustomBlock()` completes a three-message handshake:
 
-- Default `timeoutMs` is 15000; rejects with `CustomBlockInitError` code `init_timeout` if the host doesn't respond.
+1. The SDK sends `connect` with a new initialization ID and some version info.
+2. The host replies with `init`, echoing that initialization ID and providing the manifest, block context, current user, and data source bindings.
+3. The SDK confirms that state is compatible and sends `initResult` with the same initialization ID.
+
+The promise resolves only after the SDK sends `initResult.success`. Await it before mounting React so hooks always see initialized state.
+
+- Rejects with `CustomBlockInitializationError` code `init_timeout` if the host doesn't respond.
 - In a top-level browser tab (no parent frame), rejects with `NotInIframeError` code `not_in_iframe`. `<NotionCustomBlock>` catches this, seeds placeholders, and renders `children` behind a warning banner so dev-time previews still work.
 - After init, `*Changed` events (e.g. `themeChanged`, `parentChanged`, `dataSourcesChanged`) push updates and the relevant hooks re-render.
 - `initCustomBlock` is idempotent; subsequent calls return the same promise.
@@ -44,7 +50,7 @@ function useCustomBlockInit(
 
 type UseCustomBlockInitResult =
   | { isLoaded: false; error: undefined }
-  | { isLoaded: false; error: CustomBlockInitFailure }
+  | { isLoaded: false; error: CustomBlockInitializationError }
   | { isLoaded: true; error: undefined; initial: CustomBlockInitPayload };
 ```
 
@@ -69,39 +75,21 @@ function initCustomBlock(
 type InitCustomBlockOptions = { timeoutMs?: number };
 ```
 
-The lower-level promise API. `<NotionCustomBlock>` and `useCustomBlockInit` both call it for you. Reach for it directly only when you want to `await` init at module scope (e.g. before `ReactDOM.createRoot`). If the host replies with an init error, the promise rejects with `CustomBlockInitError`.
+The lower-level promise API. `<NotionCustomBlock>` and `useCustomBlockInit` both call it for you. Reach for it directly only when you want to `await` init at module scope (e.g. before `ReactDOM.createRoot`). Expected failures reject with `CustomBlockInitializationError`.
 
-### `CustomBlockInitError`
+### `CustomBlockInitializationError`
 
-```ts
-class CustomBlockInitError extends Error {
-  code: CustomBlockInitErrorCode;
-  isRetryable: boolean;
-}
+The code tells you where initialization failed:
 
-type CustomBlockInitErrorCode =
-  | "no_ready"
-  | "invalid_ready"
-  | "manifest_unavailable"
-  | "manifest_invalid"
-  | "invalid_protocol_version"
-  | "unsupported_protocol_version"
-  | "context_unavailable"
-  | "current_user_unavailable"
-  | "missing_data_source_binding"
-  | "data_source_unavailable"
-  | "missing_property_binding"
-  | "invalid_property_binding"
-  | "not_in_iframe"
-  | "init_timeout"
-  | "unknown_error";
-```
+- `CustomBlockInitErrorCode`: the host rejected initialization in `init.error`.
+- `CustomBlockInitResultErrorCode`: the SDK could not apply the host's state and reported why in `initResult.error`.
+- `not_in_iframe` and `init_timeout`: the SDK failed before the handshake completed.
 
-Thrown when the host rejects initialization instead of returning the initial theme, block location, current user, and data sources. Use `error instanceof CustomBlockInitError`, `error.code`, and `error.isRetryable` to branch on host-reported setup failures. See [Error handling](./errors.md) for the shared structured error contract.
+All code types are open string unions, so keep a default branch. Use `isRetryable` to decide whether offering a retry makes sense, and treat `message` as display text rather than a stable identifier. See [Error handling](./errors.md) for the shared error contract.
 
 ### `customBlock`
 
-Framework-neutral runtime APIs for renderers that do not use React hooks. `customBlock.getState()` returns a `CustomBlockState` snapshot that hides internal query cache details. Initialized-only getters (`getTheme`, `getBlockId`, `getParent`, `getPage`, and `getCurrentUser`) throw until `initCustomBlock()` resolves. `getManifest()` is not gated on init — it returns the declared manifest (or `null`) regardless.
+Framework-neutral runtime APIs for renderers that do not use React hooks. `customBlock.getState()` returns a `CustomBlockState` snapshot that hides internal query cache details. Initialized-only getters (e.g. `getTheme`, `getBlockId`, `getParent`) throw until `initCustomBlock()` resolves.
 
 `customBlock` covers runtime state and sizing. Row querying still goes through `useDataSource`, while imperative APIs such as `pages.*` and `users.*` are already framework-neutral functions.
 
@@ -127,7 +115,7 @@ stopAutoResize();
 
 ### `NotInIframeError`
 
-Thrown when `initCustomBlock` is called in a top-level tab (no parent frame). It has `code: "not_in_iframe"` and `isRetryable: false`. `<NotionCustomBlock>` catches it and falls back to a standalone preview with a warning banner; direct callers can `instanceof NotInIframeError` to apply their own policy.
+Thrown when `initCustomBlock` is called in a top-level tab (no parent frame). It extends `CustomBlockInitializationError`, has `code: "not_in_iframe"` and `isRetryable: false`, and can be detected specifically with `instanceof NotInIframeError`. `<NotionCustomBlock>` catches it and falls back to a standalone preview with a warning banner.
 
 ### `useCustomBlockAutoResize({ enabled? })`
 
@@ -154,7 +142,7 @@ function App() {
 Press `\` while focused in a custom block to toggle a debug overlay that replaces the block's children with a `<pre>` log of every `postMessage` sent and received over the bridge. Each line is formatted as:
 
 ```
-[ISO timestamp] sent/received: {"type":"ready", …}
+[ISO timestamp] sent/received: {"type":"connect", …}
 ```
 
 The log is intentionally plain — no filtering or decoration — so it can be copied and pasted directly to a local coding agent for debugging.

package/docs/manifest.md

@@ -18,7 +18,7 @@ A custom block declares its required data sources in `custom_blocks.json` at the
 }
 ```
 
-`initCustomBlock()` fetches the manifest and forwards it with `ready`. The `notionCustomBlock()` Vite plugin from `@notionhq/custom-blocks/vite` serves it in dev and emits it into `dist/` on build. If the file is missing, the SDK sends `ready` with `status: "success"` and `manifest: null`, which means the block has no declared data requirements. If the file is unavailable for another reason or invalid, the SDK sends `ready` with `status: "error"` and an `error` payload. Hosts should reject `init` by forwarding that full error payload unchanged.
+`initCustomBlock()` fetches the manifest and forwards it with `connect`. The `notionCustomBlock()` Vite plugin from `@notionhq/custom-blocks/vite` serves it in dev and emits it into `dist/` on build. If the file is missing, the SDK omits `manifest` from `connect`. If the file is unavailable for another reason or invalid, the SDK sends `connect` with `status: "error"` and an `error` payload. The host returns its authoritative manifest in `init`. The SDK uses that manifest even when it differs from the manifest sent in `connect`.
 
 ## Vite plugin
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/custom-blocks",
-	"version": "0.0.76",
+	"version": "0.0.78",
 	"license": "MIT",
 	"type": "module",
 	"publishConfig": {

package/src/bridge/SandboxBridge.ts

@@ -32,6 +32,7 @@ import {
 import { readIncomingType } from "./incomingType.js"
 import type { ManifestLoadResult } from "./loadManifest.js"
 import type { CustomBlockManifest } from "./manifest.js"
+import type { ConnectMessage } from "./messages/connect.js"
 import type {
 	CreatePageMessage,
 	CreatePageMessageParent,
@@ -39,12 +40,19 @@ import type {
 import type { CustomBlockCreatePageErrorInfo } from "./messages/createPageResult.js"
 import type { GetUserMessage } from "./messages/getUser.js"
 import { hostToSandboxMessageSchema } from "./messages/hostToSandbox.js"
-import { CustomBlockInitError, type InitMessage } from "./messages/init.js"
+import {
+	CustomBlockInitializationError,
+	type InitMessage,
+	initMessageSchema,
+} from "./messages/init.js"
+import type {
+	CustomBlockInitResultErrorInfo,
+	InitResultMessage,
+} from "./messages/initResult.js"
 import type { InvalidHostMessage } from "./messages/invalidHostMessage.js"
 import type { ListUsersMessage } from "./messages/listUsers.js"
 import type { QueryDataSourceMessage } from "./messages/queryDataSource.js"
 import type { CustomBlockQueryDataSourceErrorInfo } from "./messages/queryDataSourceResult.js"
-import type { ReadyMessage } from "./messages/ready.js"
 import type { ResizeMessage } from "./messages/resize.js"
 import type { UpdatePageMessage } from "./messages/updatePage.js"
 import { PendingRequests } from "./pendingRequests.js"
@@ -55,7 +63,6 @@ import type { NotionUser } from "./users/user.js"
  * single host needs to support multiple custom blocks built with different versions of the bridge
  * protocol. Increment this number any time a breaking change is made to the bridge protocol.
  */
-// TODO(custom-blocks): Update when bumping bridge protocol version to 3.
 export const CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION = 2
 
 /**
@@ -92,20 +99,22 @@ export class SandboxBridge {
 	private readonly pendingUpdatePage = new PendingRequests<UpdatePageResult>(
 		"custom-block-update-page",
 	)
-	private hasSentReady = false
+	private hasSentConnect = false
+	private hasReceivedInit = false
+	private initializationId: string | undefined
 	private latestDataSourceBindings: NotionDataSourceBindings = {}
-	private resolveInit: ((message: InitMessage) => void) | undefined
+	private isMockState = false
+	private resolveInit: (() => void) | undefined
 	private rejectInit: ((reason: Error) => void) | undefined
-	private readonly initMessage: Promise<InitMessage> = new Promise(
+	private readonly initMessage: Promise<void> = new Promise(
 		(resolve, reject) => {
 			this.resolveInit = resolve
 			this.rejectInit = reject
 		},
 	)
-	private manifest: CustomBlockManifest | null = null
 
 	constructor() {
-		// `ready` is sent later by `initCustomBlock` (after the manifest fetch
+		// `connect` is sent later by `initCustomBlock` (after the manifest fetch
 		// resolves). Top-level / no-iframe rejection is handled there too, so
 		// the constructor just attaches the listener.
 		if (typeof window !== "undefined") {
@@ -138,7 +147,7 @@ export class SandboxBridge {
 		return () => this.messageLogListeners.delete(listener)
 	}
 
-	awaitInit(signal?: AbortSignal): Promise<InitMessage> {
+	awaitInit(signal?: AbortSignal): Promise<void> {
 		if (!signal) {
 			return this.initMessage
 		}
@@ -150,9 +159,9 @@ export class SandboxBridge {
 			const onAbort = () => reject(signal.reason)
 			signal.addEventListener("abort", onAbort, { once: true })
 			this.initMessage.then(
-				message => {
+				() => {
 					signal.removeEventListener("abort", onAbort)
-					resolve(message)
+					resolve()
 				},
 				err => {
 					signal.removeEventListener("abort", onAbort)
@@ -162,34 +171,38 @@ export class SandboxBridge {
 		})
 	}
 
-	sendReady(manifestResult: ManifestLoadResult) {
+	sendConnect(manifestResult: ManifestLoadResult) {
 		if (typeof window === "undefined") {
 			return
 		}
-		if (this.hasSentReady) {
-			console.warn("[custom-blocks-sdk] ignoring duplicate ready message")
+		if (this.hasSentConnect) {
+			console.warn("[custom-blocks-sdk] ignoring duplicate connect message")
 			return
 		}
 		const { manifest, error } = manifestResult
-		this.hasSentReady = true
-		this.manifest = manifest
-		const readyMessage: ReadyMessage =
+		this.hasSentConnect = true
+		const initializationId = `custom-block-initialization-${this.nextRequestId}`
+		this.nextRequestId += 1
+		this.initializationId = initializationId
+		const connectMessage: ConnectMessage =
 			error !== undefined
 				? {
-						type: "ready",
+						type: "connect",
+						initializationId,
 						status: "error",
 						bridgeProtocolVersion: CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION,
 						sdkVersion: CUSTOM_BLOCKS_SDK_VERSION,
 						error,
 					}
 				: {
-						type: "ready",
+						type: "connect",
+						initializationId,
 						status: "success",
 						bridgeProtocolVersion: CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION,
 						sdkVersion: CUSTOM_BLOCKS_SDK_VERSION,
-						manifest,
+						...(manifest !== null ? { manifest } : {}),
 					}
-		this.postToHost(readyMessage)
+		this.postToHost(connectMessage)
 	}
 
 	private postToHost(message: unknown) {
@@ -254,7 +267,18 @@ export class SandboxBridge {
 		// `init` is the only message valid before initialization. Handle it up
 		// front so every later case can assume `status === "initialized"`.
 		if (message.type === "init") {
-			this.applyInit(message)
+			if (message.initializationId !== this.initializationId) {
+				console.warn(
+					`[custom-blocks-sdk] ignoring init for unknown initializationId ${message.initializationId}`,
+				)
+				return
+			}
+			if (this.hasReceivedInit) {
+				console.warn("[custom-blocks-sdk] ignoring duplicate init message")
+				return
+			}
+			this.hasReceivedInit = true
+			this.applyInit(message, true)
 			return
 		}
 
@@ -309,10 +333,12 @@ export class SandboxBridge {
 				const dataSources = reuseDataSourcesForUnchangedBindings({
 					previousDataSources: hostState.dataSources,
 					previousBindings: this.latestDataSourceBindings,
-					nextDataSources: resolveDataSources({
-						manifest: this.manifest,
-						dataSourceBindings: nextBindings,
-					}),
+					nextDataSources: this.isMockState
+						? resolveMockDataSources(nextBindings)
+						: resolveDataSources({
+								manifest: hostState.manifest,
+								dataSourceBindings: nextBindings,
+							}),
 					nextBindings,
 				})
 				this.latestDataSourceBindings = nextBindings
@@ -400,32 +426,23 @@ export class SandboxBridge {
 
 			case "queryDataSourceResult": {
 				const queryEntry = Object.entries(hostState.dataSourceState).find(
-					([, state]) => state.latestSnapshotId === message.snapshotId,
+					([, state]) => state.subscriptionId === message.subscriptionId,
 				)
 				if (queryEntry === undefined) {
 					return
 				}
 				const [key, currentState] = queryEntry
-				if (currentState.latestRequestId !== message.requestId) {
-					return
-				}
 				const queryResult =
-					"status" in message
-						? message.status === "error"
-							? {
-									items: [],
-									hasMore: false,
-									error: message.error,
-								}
-							: {
-									items: message.items,
-									hasMore: message.hasMore,
-									error: undefined,
-								}
+					message.status === "error"
+						? {
+								items: [],
+								hasMore: false,
+								error: message.error,
+							}
 						: {
 								items: message.items,
 								hasMore: message.hasMore,
-								error: message.error,
+								error: undefined,
 							}
 				this.hostState = {
 					...hostState,
@@ -436,10 +453,7 @@ export class SandboxBridge {
 							isLoading: false,
 							hasMore: queryResult.hasMore,
 							error: queryResult.error,
-							// Keep the request ID so later host-pushed refreshes for the
-							// same subscription still match.
-							latestRequestId: message.requestId,
-							latestSnapshotId: message.snapshotId,
+							subscriptionId: message.subscriptionId,
 							latestLimit: currentState.latestLimit,
 						},
 					},
@@ -463,16 +477,6 @@ export class SandboxBridge {
 		return this.hostState
 	}
 
-	/**
-	 * The author-declared manifest loaded from `custom_blocks.json` and forwarded
-	 * to the host in `ready`. `null` when it failed to load/parse and the host
-	 * should reject init via `ready.status: "error"`. Static for the lifetime
-	 * of the sandbox.
-	 */
-	getManifest(): CustomBlockManifest | null {
-		return this.manifest
-	}
-
 	/**
 	 * Apply an `init` payload as if it had arrived from the host. Lets callers
 	 * seed the bridge directly (e.g. the React provider's standalone preview
@@ -480,10 +484,14 @@ export class SandboxBridge {
 	 * of why it's being seeded.
 	 */
 	setMockState(message: InitMessage) {
-		this.applyInit(message)
+		this.isMockState = true
+		this.applyInit(v.parse(initMessageSchema, message), false)
 	}
 
-	private applyInit(message: InitMessage) {
+	private applyInit(message: InitMessage, postResult: boolean) {
+		if (postResult) {
+			this.isMockState = false
+		}
 		if (message.status === "error") {
 			// The host couldn't construct block location for this block (most commonly the parent record
 			// failed to resolve). Surface the failure through the `awaitInit` promise so callers see
@@ -495,7 +503,7 @@ export class SandboxBridge {
 				`[custom-blocks-sdk] host reported init error (${message.error.code}): ${message.error.message}`,
 			)
 			if (this.rejectInit) {
-				this.rejectInit(new CustomBlockInitError(message.error))
+				this.rejectInit(new CustomBlockInitializationError(message.error))
 				this.resolveInit = undefined
 				this.rejectInit = undefined
 			}
@@ -505,10 +513,28 @@ export class SandboxBridge {
 		const { blockId, parent, page } = message
 
 		this.latestDataSourceBindings = message.dataSources.bindings
-		const dataSources = resolveDataSources({
-			manifest: this.manifest,
-			dataSourceBindings: this.latestDataSourceBindings,
-		})
+		const dataSources = postResult
+			? resolveDataSources({
+					manifest: message.manifest,
+					dataSourceBindings: this.latestDataSourceBindings,
+				})
+			: resolveMockDataSources(this.latestDataSourceBindings)
+		const bindingError = getInitBindingError(message.manifest, dataSources)
+		if (postResult && bindingError !== undefined) {
+			const result: InitResultMessage = {
+				type: "initResult",
+				initializationId: message.initializationId,
+				status: "error",
+				error: bindingError,
+			}
+			this.postToHost(result)
+			if (this.rejectInit) {
+				this.rejectInit(new CustomBlockInitializationError(bindingError))
+				this.resolveInit = undefined
+				this.rejectInit = undefined
+			}
+			return
+		}
 		this.hostState = {
 			status: "initialized",
 			theme: message.theme,
@@ -516,15 +542,24 @@ export class SandboxBridge {
 			parent,
 			page,
 			currentUser: message.currentUser,
+			manifest: message.manifest,
 			dataSources,
 			dataSourceState: {},
 		}
 		this.notify()
+		if (postResult) {
+			const result: InitResultMessage = {
+				type: "initResult",
+				initializationId: message.initializationId,
+				status: "success",
+			}
+			this.postToHost(result)
+		}
 		// Resolve the awaitInit promise once. Subsequent `init` messages
 		// (the host shouldn't send these, but be tolerant) update state but
 		// don't re-resolve.
 		if (this.resolveInit) {
-			this.resolveInit(message)
+			this.resolveInit()
 			this.resolveInit = undefined
 			this.rejectInit = undefined
 		}
@@ -558,21 +593,18 @@ export class SandboxBridge {
 		}
 
 		const limit = resolveDataSourceQueryLimit(options.limit)
-		const snapshotId = makeDataSourceSnapshotId({
+		const subscriptionId = makeDataSourceSubscriptionId({
 			key,
 		})
 
 		if (
 			currentState.isLoading &&
-			currentState.latestSnapshotId === snapshotId &&
+			currentState.subscriptionId === subscriptionId &&
 			currentState.latestLimit === limit
 		) {
 			return
 		}
 
-		const requestId = `custom-block-query-${this.nextRequestId}`
-		this.nextRequestId += 1
-
 		this.hostState = {
 			...this.hostState,
 			dataSourceState: {
@@ -581,8 +613,7 @@ export class SandboxBridge {
 					...currentState,
 					isLoading: true,
 					error: undefined,
-					latestRequestId: requestId,
-					latestSnapshotId: snapshotId,
+					subscriptionId,
 					latestLimit: limit,
 				},
 			},
@@ -591,8 +622,7 @@ export class SandboxBridge {
 
 		const outbound: QueryDataSourceMessage = {
 			type: "queryDataSource",
-			requestId,
-			snapshotId,
+			subscriptionId,
 			dataSourceId: dataSource.collectionPointer.id,
 			limit,
 		}
@@ -615,8 +645,7 @@ export class SandboxBridge {
 					...currentState,
 					isLoading: false,
 					error,
-					latestRequestId: undefined,
-					latestSnapshotId: undefined,
+					subscriptionId: undefined,
 					latestLimit: undefined,
 				},
 			},
@@ -907,11 +936,56 @@ function resolveDataSourceQueryLimit(limit: number | undefined): number {
 	return limit
 }
 
-function makeDataSourceSnapshotId(args: { key: string }): string {
+function makeDataSourceSubscriptionId(args: { key: string }): string {
 	const { key } = args
 	return `data-source:${encodeURIComponent(key)}`
 }
 
+function getInitBindingError(
+	manifest: CustomBlockManifest,
+	dataSources: NotionDataSource[],
+): CustomBlockInitResultErrorInfo | undefined {
+	for (const [dataSourceKey, manifestDataSource] of Object.entries(
+		manifest.dataSources,
+	)) {
+		const dataSource = dataSources.find(entry => entry.key === dataSourceKey)
+		if (
+			dataSource?.collectionPointer === undefined ||
+			dataSource.collectionSchema === undefined
+		) {
+			return {
+				code: "invalid_init_bindings",
+				message: `Host did not provide a complete binding for data source "${dataSourceKey}".`,
+				isRetryable: false,
+			}
+		}
+		for (const propertyKey of Object.keys(
+			manifestDataSource.properties ?? {},
+		)) {
+			if (dataSource.propertyIdsByKey[propertyKey] === undefined) {
+				return {
+					code: "invalid_init_bindings",
+					message: `Host did not provide a valid binding for property "${dataSourceKey}.${propertyKey}".`,
+					isRetryable: false,
+				}
+			}
+		}
+	}
+	return undefined
+}
+
+function resolveMockDataSources(
+	bindings: NotionDataSourceBindings,
+): NotionDataSource[] {
+	return Object.entries(bindings).map(([key, binding]) => ({
+		key,
+		collectionPointer: binding.collectionPointer,
+		collectionSchema: binding.collectionSchema,
+		propertyIdsByKey: { ...(binding.propertyIdsByKey ?? {}) },
+		propertySchemasById: binding.collectionSchema?.propertiesById ?? {},
+	}))
+}
+
 function formatInvalidHostReason(
 	incomingType: string | undefined,
 	issues: readonly v.BaseIssue<unknown>[],

package/src/bridge/dataSources/resolve.ts

@@ -5,7 +5,7 @@ import type {
 } from "./dataSource.js"
 
 type ResolveDataSourcesArgs = {
-	manifest: CustomBlockManifest | null
+	manifest: CustomBlockManifest
 	dataSourceBindings: NotionDataSourceBindings
 }
 
@@ -13,23 +13,12 @@ type ResolveDataSourcesArgs = {
  * Builds the public {@link NotionDataSource} list the SDK exposes to consumers.
  *
  * Combines the host-supplied bindings (collection pointers + schemas) with the
- * manifest's declared data-source keys. Property mappings are host-owned: the
- * SDK validates the supplied property id against the manifest and live schema,
- * but does not infer a missing mapping.
+ * manifest's declared data-source keys. The host owns every mapping; the SDK
+ * validates supplied IDs but never infers omitted bindings.
  */
 export function resolveDataSources(
 	args: ResolveDataSourcesArgs,
 ): NotionDataSource[] {
-	if (args.manifest === null) {
-		return Object.entries(args.dataSourceBindings).map(([key, binding]) => ({
-			key,
-			collectionPointer: binding.collectionPointer,
-			collectionSchema: binding.collectionSchema,
-			propertyIdsByKey: { ...(binding.propertyIdsByKey ?? {}) },
-			propertySchemasById: binding.collectionSchema?.propertiesById ?? {},
-		}))
-	}
-
 	return Object.entries(args.manifest.dataSources).map(
 		([key, manifestDataSource]) => {
 			const binding = args.dataSourceBindings[key]

package/src/bridge/hostState.ts

@@ -8,6 +8,7 @@ import type {
 import type { NotionDataSourceValue } from "./dataSources/dataSourceValue.js"
 import type { NotionPropertySchema } from "./dataSources/propertySchema.js"
 import type { NotionBlockId } from "./ids.js"
+import type { CustomBlockManifest } from "./manifest.js"
 import type { CustomBlockQueryDataSourceErrorInfo } from "./messages/queryDataSourceResult.js"
 import type { CustomBlockPage, NotionPageId } from "./pages/page.js"
 import type { NotionParent } from "./parent.js"
@@ -28,6 +29,7 @@ export type InitializedHostState = {
 	parent: NotionParent
 	page: CustomBlockPage
 	currentUser: NotionUser
+	manifest: CustomBlockManifest
 	dataSources: NotionDataSource[]
 	dataSourceState: Record<string, DataSourceQueryState>
 }
@@ -38,8 +40,7 @@ export type DataSourceQueryState = {
 	isLoading: boolean
 	hasMore: boolean
 	error?: CustomBlockQueryDataSourceErrorInfo
-	latestRequestId?: string
-	latestSnapshotId?: string
+	subscriptionId?: string
 	latestLimit?: number
 }
 

package/src/bridge/loadManifest.ts

@@ -4,13 +4,13 @@ import { type CustomBlockManifest, manifestSchema } from "./manifest.js"
 
 const MANIFEST_URL = "custom_blocks.json"
 
-export type CustomBlockReadyErrorCode =
+export type CustomBlockConnectErrorCode =
 	| "manifest_unavailable"
 	| "manifest_invalid"
 	| (string & {})
 
-export type CustomBlockReadyError =
-	CustomBlockErrorInfo<CustomBlockReadyErrorCode>
+export type CustomBlockConnectError =
+	CustomBlockErrorInfo<CustomBlockConnectErrorCode>
 
 export type ManifestLoadResult =
 	| {
@@ -19,7 +19,7 @@ export type ManifestLoadResult =
 	  }
 	| {
 			manifest: null
-			error: CustomBlockReadyError
+			error: CustomBlockConnectError
 	  }
 
 /**
@@ -27,7 +27,7 @@ export type ManifestLoadResult =
  * A missing manifest means the block has no declared data requirements.
  * Other failures return a structured error so the host can reject the manifest.
  * The SDK validates the manifest locally for author feedback; the host still
- * validates the ready message as the iframe trust boundary.
+ * validates the connect message as the iframe trust boundary.
  */
 export async function loadManifest(): Promise<ManifestLoadResult> {
 	if (typeof fetch !== "function") {
@@ -48,7 +48,7 @@ export async function loadManifest(): Promise<ManifestLoadResult> {
 			manifest: null,
 			// Consider this retryable because it may have just been a network issue. Because `init`
 			// errors are considered terminal, the host should "retry" by reloading the iframe and
-			// sending another `ready` message.
+			// sending another `connect` message.
 			error: { code: "manifest_unavailable", message, isRetryable: true },
 		}
 	}

package/src/bridge/manifest.ts

@@ -3,9 +3,9 @@ import { notionPropertyTypeSchema } from "./dataSources/propertySchema.js"
 
 /**
  * User-authored manifest declaring the data sources the custom block expects.
- * Lives at `custom_blocks.json` in the project root and is forwarded to the host with
- * the bridge `ready` message so the host can pre-bind data sources, surface
- * configuration UI, etc. The `notionCustomBlock` Vite plugin from
+ * Lives at `custom_blocks.json` in the project root. The sandbox may send it in
+ * `connect`, and the host returns the authoritative manifest in `init`. The
+ * `notionCustomBlock` Vite plugin from
  * `@notionhq/custom-blocks/vite` wires the JSON file into the dev server and
  * the build output.
  */