@notionhq/custom-blocks 0.0.77 → 0.0.79

package/HOST.md

@@ -18,65 +18,98 @@ import {
 
 `readIncomingType()` is intentionally best-effort. Use it after validation fails so the host can avoid NACK loops and include a useful reason in `invalidSandboxMessage`.
 
-`createCustomBlockHost()` is an optional protocol loop for lightweight hosts. It owns iframe message listener setup, `ready` / `init`, protocol version checks, malformed-message NACKs, request routing, auto-resize callbacks, state-change messages, cleanup, and latest-query refresh bookkeeping. It deliberately does not know about any host's data model, permissions, iframe policy, analytics, or UI state.
+`createCustomBlockHost()` is an optional protocol loop for lightweight hosts. It owns iframe message listener setup, `connect` / `init` / `initResult`, protocol version checks, malformed-message NACKs, request routing, auto-resize callbacks, state-change messages, cleanup, and latest-query refresh bookkeeping. It deliberately does not know about any host's data model, permissions, iframe policy, analytics, or UI state.
 
 ```ts
 import { createCustomBlockHost } from "@notionhq/custom-blocks/host";
 
 const host = createCustomBlockHost({
   iframe,
+  minBridgeProtocolVersion: 3,
   initialState: {
     theme,
     blockId,
     parent,
     page,
     currentUser,
+    manifest: persistedManifest,
     dataSources: { bindings },
   },
   handlers: {
-    queryDataSource: async (message) => ({ status: "success", items: [], hasMore: false }),
+    queryDataSource: async (message) => ({
+      status: "success",
+      items: [],
+      hasMore: false,
+    }),
   },
 });
 ```
 
 Use it when the generic protocol loop is helpful. Hosts with more specialized runtime needs can keep using the schemas and message types directly.
 
-Related types: `CustomBlockHostOptions`, `CustomBlockHostInitialState`, `CustomBlockHostInitialDataSources`, `CustomBlockHostDataSourcesPayload`, `CustomBlockHostHandlers`, `CustomBlockHostHandle`, `CustomBlockHostLogDirection`, `CustomBlockHostQueryDataSourceResult`, `CustomBlockHostCreatePageResult`, `CustomBlockHostGetPageResult`, `CustomBlockHostUpdatePageResult`, `CustomBlockHostGetUserResult`, and `CustomBlockHostListUsersResult`.
+Responses return a `status`-discriminated result: `"success"` carries `items` and required `hasMore`; `"error"` carries the structured `error`. Set `hasMore` to `false` when no additional results are available.
+
+Related exports: `CustomBlockHostOptions`, `CustomBlockHostInitialState`, `CustomBlockHostInitialDataSources`, `CustomBlockHostDataSourcesPayload`, `ConnectSuccessMessage`, `CustomBlockHostHandlers`, `CustomBlockHostHandle`, `CustomBlockHostLogDirection`, `CustomBlockHostQueryDataSourceResult`, `CustomBlockHostCreatePageResult`, `CustomBlockHostGetPageResult`, `CustomBlockHostUpdatePageResult`, `CustomBlockHostGetUserResult`, and `CustomBlockHostListUsersResult`.
 
 ## Bridge protocol
 
 ### Lifecycle
 
-The bridge is established with a handshake: the sandbox posts a `ready` when `initCustomBlock()` starts, and the host validates it and replies exactly once with `init`. Hosts should log and ignore duplicate `ready` messages instead of re-running the handshake. After that, narrower messages stream live state updates.
+Initialization has three steps. A sandbox-generated `initializationId` identifies the handshake from start to finish. Ignore duplicate messages and messages carrying any other ID.
 
-The sandbox starts by sending `ready`. It declares the bridge protocol version, includes the custom blocks package semver as `sdkVersion` when available, and tells the host whether manifest discovery produced a usable manifest. Hosts should reject init when `ready` reports a manifest error, forwarding the sandbox's full error payload unchanged:
+#### 1. Sandbox sends `connect`
 
-```ts
-// sandbox → host
-{ type: "ready", status: "success", bridgeProtocolVersion, sdkVersion, manifest: { /* custom_blocks.json */ } }
+`connect` declares the bridge protocol version and SDK package version. A successful message may also include the manifest discovered in the sandbox:
 
-// sandbox → host, no manifest / no declared data requirements
-{ type: "ready", status: "success", bridgeProtocolVersion, sdkVersion, manifest: null }
+```ts
+// sandbox → host without manifest
+{ type: "connect", initializationId, status: "success", bridgeProtocolVersion, sdkVersion }
 
-// sandbox → host, manifest failed to load or validate
-{ type: "ready", status: "error", bridgeProtocolVersion, sdkVersion, error: { code: "manifest_invalid", message: "...", isRetryable: false } }
+// sandbox → host with explicit manifest
+{ type: "connect", initializationId, status: "success", bridgeProtocolVersion, sdkVersion, manifest: { /* ... */ } }
 ```
 
-The host replies with exactly one `init`, which has two statuses. On success it carries the full initial state — `theme`, `blockId`, `parent`, `page`, `currentUser` (the `NotionUser` shape from the user result messages), and `dataSources: { bindings }`:
+If `connect.status` is `"error"`, reply with `init.error` using the same `initializationId` and forward its complete error payload unchanged.
+
+#### 2. Host sends `init`
+
+The host sends exactly one `init` containing its authoritative manifest. It may
+use the manifest from `connect` as input, but the manifest it returns may differ;
+the sandbox applies the host's version.
+
+`init.success` carries the chosen manifest together with the initial theme, block context, current user, and data-source bindings:
 
 ```ts
 // host → sandbox
-{ type: "init", status: "success", theme, blockId, parent, page: { id, parent }, currentUser, dataSources: { bindings } }
+{ type: "init", initializationId, status: "success", theme, blockId, parent, page: { id, parent }, currentUser, manifest, dataSources: { bindings } }
 ```
 
-On failure it carries `error: { code, message, isRetryable }` (`CustomBlockInitErrorInfo` / `customBlockInitErrorInfoSchema`, with `code` drawn from `CustomBlockInitErrorCode` / `customBlockInitErrorCodeSchema`). The SDK surfaces this as a `CustomBlockInitError`:
+If the host cannot initialize the block, send `init.error` instead:
 
 ```ts
 // host → sandbox
-{ type: "init", status: "error", error: { code: "context_unavailable", message: "...", isRetryable: true } }
+{ type: "init", initializationId, status: "error", error: { code: "context_unavailable", message: "...", isRetryable: true } }
 ```
 
-After `init`, narrower messages update live state without re-running the handshake — `themeChanged`, `parentChanged`, `pageChanged`, `currentUserChanged`, and `dataSourcesChanged`. Each replaces just its slice of state:
+Use `CustomBlockInitErrorCode` / `CustomBlockInitErrorInfo` to construct this error and `customBlockInitErrorCodeSchema` / `customBlockInitErrorInfoSchema` to validate it. `init.error` is terminal; the sandbox does not reply with `initResult`.
+
+#### 3. Sandbox sends `initResult`
+
+After applying `init.success`, the sandbox acknowledges whether it accepted the manifest and bindings:
+
+```ts
+// sandbox → host
+{ type: "initResult", initializationId, status: "success" }
+
+// sandbox → host, host supplied bindings the SDK could not apply
+{ type: "initResult", initializationId, status: "error", error: { code: "invalid_init_bindings", message: "...", isRetryable: false } }
+```
+
+Use `CustomBlockInitResultErrorCode` / `CustomBlockInitResultErrorInfo` to construct this error and `customBlockInitResultErrorCodeSchema` / `customBlockInitResultErrorInfoSchema` to validate it.
+
+Wait for `initResult.success` before uncovering the iframe or sending live updates. `initResult.error` is terminal.
+
+After `initResult.success`, narrower messages update live state without re-running the handshake — `themeChanged`, `parentChanged`, `pageChanged`, `currentUserChanged`, and `dataSourcesChanged`. Each replaces just its slice of state:
 
 ```ts
 // host → sandbox, any time after init
@@ -88,7 +121,7 @@ After `init`, narrower messages update live state without re-running the handsha
 
 ### Versioning
 
-`ready` includes `bridgeProtocolVersion` (the host <-> sandbox version) and `sdkVersion` (the package semver). Hosts should reject or fail `init` when the sandbox reports a `bridgeProtocolVersion` the host does not implement, but should treat `sdkVersion` as purely analytics metadata.
+`connect` includes `bridgeProtocolVersion` (the host <-> sandbox version) and `sdkVersion` (the package semver). Hosts should reject or fail `init` when the sandbox reports a `bridgeProtocolVersion` the host does not implement, but should treat `sdkVersion` as purely analytics metadata.
 
 If the sandbox reports a version below the host's supported minimum, reply with `init.status: "error"` and `error.code: "unsupported_protocol_version"`. If the reported version is structurally invalid (not a positive integer — e.g. `0`, negative, fractional, `NaN`, or `Infinity`), reply with `error.code: "invalid_protocol_version"` instead.
 
@@ -142,9 +175,10 @@ Messages sent from the sandbox to the host. Parse `window` `message` events with
 
 | Wire type            | Type / schema                                             | Behavior                                                                                                                                                                                                                                |
 | -------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ready`              | `ReadyMessage` / `readyMessageSchema`                     | One-shot handshake; carries `bridgeProtocolVersion`, `sdkVersion`, and the manifest.                                                                                                                                                    |
+| `connect`            | `ConnectMessage` / `connectMessageSchema`                 | Starts the one-shot handshake with a sandbox-generated `initializationId`; carries `bridgeProtocolVersion`, `sdkVersion`, and the manifest.                                                                                 |
+| `initResult`         | `InitResultMessage` / `initResultMessageSchema`           | Echoes the handshake `initializationId` and reports whether the sandbox applied `init.success`.                                                                                                                             |
 | `queryDataSource`    | `QueryDataSourceMessage` / `queryDataSourceMessageSchema` | Starts or updates a `subscriptionId`-keyed subscription for rows in a raw `dataSourceId`. Later results for the same subscription replace its current value. |
-| `createPage`         | `CreatePageMessage` / `createPageMessageSchema`           | `requestId`-keyed page creation with properties and optional position; parent is `page_id` or `data_source_id`. Create-time icon and cover are not supported.                                                                            |
+| `createPage`         | `CreatePageMessage` / `createPageMessageSchema`           | `requestId`-keyed page creation with properties and optional position; parent is `page_id` or `data_source_id`. Create-time icon and cover are not supported.                                                               |
 | `getPage`            | `GetPageMessage` / `getPageMessageSchema`                 | `requestId`-keyed page fetch by page id.                                                                                                                                                                                                |
 | `updatePage`         | `UpdatePageMessage` / `updatePageMessageSchema`           | `requestId`-keyed patch (properties, icon, cover, or `archived`).                                                                                                                                                                       |
 | `getUser`            | `GetUserMessage` / `getUserMessageSchema`                 | `requestId`-keyed user fetch by user id.                                                                                                                                                                                                |
@@ -158,20 +192,20 @@ Messages sent from the sandbox to the host. Parse `window` `message` events with
 
 Messages sent from the host to the sandbox. Same `{ wire type, type / schema, behavior }` shape; the type / schema column points to the payload shape.
 
-| Wire type               | Type / schema                                                         | Behavior                                                                                                                      |
-| ----------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `init`                  | `InitMessage` / `initMessageSchema`                                   | Sent exactly once in response to `ready`; carries the success/error payload described under [Lifecycle](#lifecycle).          |
-| `themeChanged`          | `ThemeChangedMessage` / `themeChangedMessageSchema`                   | Replaces the current theme.                                                                                                   |
-| `parentChanged`         | `ParentChangedMessage` / `parentChangedMessageSchema`                 | Replaces the custom block parent without disturbing theme, block ID, page ID, user, or query state.                           |
-| `pageChanged`           | `PageChangedMessage` / `pageChangedMessageSchema`                     | Replaces the nearest page ancestor without disturbing theme, block ID, parent, user, or query state.                          |
-| `currentUserChanged`    | `CurrentUserChangedMessage` / `currentUserChangedMessageSchema`       | Replaces the current viewer record. Send when any viewer field changes (name, avatar, email).                                 |
-| `dataSourcesChanged`    | `DataSourcesChangedMessage` / `dataSourcesChangedMessageSchema`       | Replaces data-source bindings; the sandbox preserves cached query state for keys that still exist and drops removed keys.     |
-| `queryDataSourceResult` | `QueryDataSourceResultMessage` / `queryDataSourceResultMessageSchema` | `subscriptionId`-keyed update with `status: "success"`, `items`, and `hasMore`, or `status: "error"` and `error`. |
-| `createPageResult`      | `CreatePageResultMessage` / `createPageResultMessageSchema`           | `requestId`-keyed page response with `status: "success"` or `status: "error"`.                                                |
-| `getPageResult`         | `GetPageResultMessage` / `getPageResultMessageSchema`                 | Same success/error shape as `createPageResult`.                                                                               |
-| `updatePageResult`      | `UpdatePageResultMessage` / `updatePageResultMessageSchema`           | Same success/error shape as `createPageResult`.                                                                               |
-| `getUserResult`         | `GetUserResultMessage` / `getUserResultMessageSchema`                 | `requestId`-keyed user response with `status: "success"` or `status: "error"`.                                                |
-| `listUsersResult`       | `ListUsersResultMessage` / `listUsersResultMessageSchema`             | Same success/error shape as `getUserResult`.                                                                                  |
+| Wire type               | Type / schema                                                         | Behavior                                                                                                                                                 |
+| ----------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init`                  | `InitMessage` / `initMessageSchema`                                   | Sent exactly once in response to `connect`; echoes its `initializationId` and carries the success/error payload described under [Lifecycle](#lifecycle). |
+| `themeChanged`          | `ThemeChangedMessage` / `themeChangedMessageSchema`                   | Replaces the current theme.                                                                                                                              |
+| `parentChanged`         | `ParentChangedMessage` / `parentChangedMessageSchema`                 | Replaces the custom block parent without disturbing theme, block ID, page ID, user, or query state.                                                      |
+| `pageChanged`           | `PageChangedMessage` / `pageChangedMessageSchema`                     | Replaces the nearest page ancestor without disturbing theme, block ID, parent, user, or query state.                                                     |
+| `currentUserChanged`    | `CurrentUserChangedMessage` / `currentUserChangedMessageSchema`       | Replaces the current viewer record. Send when any viewer field changes (name, avatar, email).                                                            |
+| `dataSourcesChanged`    | `DataSourcesChangedMessage` / `dataSourcesChangedMessageSchema`       | Replaces data-source bindings; the sandbox preserves cached query state for keys that still exist and drops removed keys.                                |
+| `queryDataSourceResult` | `QueryDataSourceResultMessage` / `queryDataSourceResultMessageSchema` | `subscriptionId`-keyed update with `status: "success"`, `items`, and `hasMore`, or `status: "error"` and `error`.                                       |
+| `createPageResult`      | `CreatePageResultMessage` / `createPageResultMessageSchema`           | `requestId`-keyed page response with `status: "success"` or `status: "error"`.                                                                           |
+| `getPageResult`         | `GetPageResultMessage` / `getPageResultMessageSchema`                 | Same success/error shape as `createPageResult`.                                                                                                          |
+| `updatePageResult`      | `UpdatePageResultMessage` / `updatePageResultMessageSchema`           | Same success/error shape as `createPageResult`.                                                                                                          |
+| `getUserResult`         | `GetUserResultMessage` / `getUserResultMessageSchema`                 | `requestId`-keyed user response with `status: "success"` or `status: "error"`.                                                                           |
+| `listUsersResult`       | `ListUsersResultMessage` / `listUsersResultMessageSchema`             | Same success/error shape as `getUserResult`.                                                                                                             |
 | `invalidSandboxMessage` | `InvalidSandboxMessage` / `invalidSandboxMessageSchema`               | Host-side NACK for a sandbox message it could not parse.                                                                      |
 
 `HostToSandboxMessage` / `hostToSandboxMessageSchema` is the discriminated union over all of the above.

package/README.md

@@ -35,7 +35,7 @@ export function App() {
 }
 ```
 
-`<NotionCustomBlock>` runs the SDK ↔ host handshake (sends `ready` with the manifest, awaits `init`) and only mounts `children` once it resolves. Inside the wrapper, every hook returns non-nullable values — there's no separate gating component to write. It also runs `useCustomBlockAutoResize` for you by default; pass `autoResize={false}` to opt out.
+`<NotionCustomBlock>` runs the SDK ↔ host handshake (`connect` → `init` → `initResult`) and only mounts `children` once it resolves. Inside the wrapper, every hook returns non-nullable values — there's no separate gating component to write. It also runs `useCustomBlockAutoResize` for you by default; pass `autoResize={false}` to opt out.
 
 ## Reference
 

package/bin/src/bridge/manifest.js

@@ -2,9 +2,9 @@ import * as v from "valibot";
 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.
  */

package/dist/bridge/SandboxBridge.d.ts

@@ -3,14 +3,13 @@ import type { NotionDataSource } from "./dataSources/dataSource.js";
 import type { NotionDataSourcePageUpdateInput, NotionDataSourcePageUpdateResult } from "./dataSources/dataSourcePage.js";
 import { type CustomBlockHostState } from "./hostState.js";
 import type { ManifestLoadResult } from "./loadManifest.js";
-import type { CustomBlockManifest } from "./manifest.js";
 import { type InitMessage } from "./messages/init.js";
 /**
  * Used to ensure that the host and client are using the same version of the bridge protocol. A
  * 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.
  */
-export declare const CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION = 2;
+export declare const CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION = 3;
 /**
  * A single entry in the bridge message log. Kept intentionally plain so the log
  * is copy-pasteable to a local coding agent without needing extra context.
@@ -25,36 +24,32 @@ export declare class SandboxBridge {
     private listeners;
     private messageLog;
     private messageLogListeners;
+    private nextRequestId;
     private readonly pendingCreatePage;
     private readonly pendingGetPage;
     private readonly pendingGetUser;
     private readonly pendingListUsers;
     private readonly pendingUpdatePage;
-    private hasSentReady;
+    private hasSentConnect;
+    private hasReceivedInit;
+    private initializationId;
     private latestDataSourceBindings;
+    private isMockState;
     private resolveInit;
     private rejectInit;
     private readonly initMessage;
-    private manifest;
     constructor();
     private static MAX_LOG_ENTRIES;
     private logMessage;
     getMessageLog(): readonly MessageLogEntry[];
     subscribeToMessageLog(listener: () => void): () => boolean;
-    awaitInit(signal?: AbortSignal): Promise<InitMessage>;
-    sendReady(manifestResult: ManifestLoadResult): void;
+    awaitInit(signal?: AbortSignal): Promise<void>;
+    sendConnect(manifestResult: ManifestLoadResult): void;
     private postToHost;
     private notify;
     private handleMessage;
     subscribe(listener: () => void): () => boolean;
     getHostState(): CustomBlockHostState;
-    /**
-     * 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;
     /**
      * 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

package/dist/bridge/SandboxBridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SandboxBridge.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/SandboxBridge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SandboxBridge.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/SandboxBridge.ts"],"names":[],"mappings":"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"}

package/dist/bridge/SandboxBridge.js

@@ -6,14 +6,14 @@ import { resolvePropertyWriteMapForDataSource } from "./dataSources/resolvePrope
 import { createEmptyDataSourceQueryState, } from "./hostState.js";
 import { readIncomingType } from "./incomingType.js";
 import { hostToSandboxMessageSchema } from "./messages/hostToSandbox.js";
-import { CustomBlockInitError } from "./messages/init.js";
+import { CustomBlockInitializationError, initMessageSchema, } from "./messages/init.js";
 import { PendingRequests } from "./pendingRequests.js";
 /**
  * Used to ensure that the host and client are using the same version of the bridge protocol. A
  * 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.
  */
-export const CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION = 2;
+export const CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION = 3;
 export class SandboxBridge {
     constructor() {
         this.hostState = {
@@ -23,18 +23,20 @@ export class SandboxBridge {
         this.listeners = new Set();
         this.messageLog = [];
         this.messageLogListeners = new Set();
+        this.nextRequestId = 1;
         this.pendingCreatePage = new PendingRequests("custom-block-create-page");
         this.pendingGetPage = new PendingRequests("custom-block-get-page");
         this.pendingGetUser = new PendingRequests("custom-block-get-user");
         this.pendingListUsers = new PendingRequests("custom-block-list-users");
         this.pendingUpdatePage = new PendingRequests("custom-block-update-page");
-        this.hasSentReady = false;
+        this.hasSentConnect = false;
+        this.hasReceivedInit = false;
         this.latestDataSourceBindings = {};
+        this.isMockState = false;
         this.initMessage = new Promise((resolve, reject) => {
             this.resolveInit = resolve;
             this.rejectInit = reject;
         });
-        this.manifest = null;
         this.notify = () => {
             for (const listener of this.listeners) {
                 listener();
@@ -79,7 +81,16 @@ 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;
             }
             // Alias to keep TS's narrowed `InitializedHostState` across the switch
@@ -127,10 +138,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;
@@ -234,7 +247,7 @@ export class SandboxBridge {
                 }
             }
         };
-        // `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") {
@@ -272,42 +285,46 @@ export class SandboxBridge {
             }
             const onAbort = () => reject(signal.reason);
             signal.addEventListener("abort", onAbort, { once: true });
-            this.initMessage.then(message => {
+            this.initMessage.then(() => {
                 signal.removeEventListener("abort", onAbort);
-                resolve(message);
+                resolve();
             }, err => {
                 signal.removeEventListener("abort", onAbort);
                 reject(err);
             });
         });
     }
-    sendReady(manifestResult) {
+    sendConnect(manifestResult) {
         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 = error !== undefined
+        this.hasSentConnect = true;
+        const initializationId = `custom-block-initialization-${this.nextRequestId}`;
+        this.nextRequestId += 1;
+        this.initializationId = initializationId;
+        const 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);
     }
     postToHost(message) {
         console.debug("[custom-blocks-sdk] outbound postMessage", message);
@@ -321,15 +338,6 @@ export class SandboxBridge {
     getHostState() {
         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() {
-        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
@@ -337,9 +345,13 @@ export class SandboxBridge {
      * of why it's being seeded.
      */
     setMockState(message) {
-        this.applyInit(message);
+        this.isMockState = true;
+        this.applyInit(v.parse(initMessageSchema, message), false);
     }
-    applyInit(message) {
+    applyInit(message, postResult) {
+        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
@@ -349,7 +361,7 @@ export class SandboxBridge {
             // back over the bridge since the host has already given up.
             console.error(`[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;
             }
@@ -357,10 +369,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 = {
+                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,
@@ -368,15 +398,24 @@ export class SandboxBridge {
             parent,
             page,
             currentUser: message.currentUser,
+            manifest: message.manifest,
             dataSources,
             dataSourceState: {},
         };
         this.notify();
+        if (postResult) {
+            const result = {
+                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;
         }
@@ -693,6 +732,38 @@ function makeDataSourceSubscriptionId(args) {
     const { key } = args;
     return `data-source:${encodeURIComponent(key)}`;
 }
+function getInitBindingError(manifest, dataSources) {
+    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) {
+    return Object.entries(bindings).map(([key, binding]) => ({
+        key,
+        collectionPointer: binding.collectionPointer,
+        collectionSchema: binding.collectionSchema,
+        propertyIdsByKey: { ...(binding.propertyIdsByKey ?? {}) },
+        propertySchemasById: binding.collectionSchema?.propertiesById ?? {},
+    }));
+}
 function formatInvalidHostReason(incomingType, issues) {
     const labelled = incomingType
         ? `host message of type "${incomingType}"`

package/dist/bridge/dataSources/resolve.d.ts

@@ -1,16 +1,15 @@
 import type { CustomBlockManifest } from "../manifest.js";
 import type { NotionDataSource, NotionDataSourceBindings } from "./dataSource.js";
 type ResolveDataSourcesArgs = {
-    manifest: CustomBlockManifest | null;
+    manifest: CustomBlockManifest;
     dataSourceBindings: NotionDataSourceBindings;
 };
 /**
  * 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 declare function resolveDataSources(args: ResolveDataSourcesArgs): NotionDataSource[];
 export {};

package/dist/bridge/dataSources/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/dataSources/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AACzD,OAAO,KAAK,EACX,gBAAgB,EAChB,wBAAwB,EACxB,MAAM,iBAAiB,CAAA;AAExB,KAAK,sBAAsB,GAAG;IAC7B,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAA;IACpC,kBAAkB,EAAE,wBAAwB,CAAA;CAC5C,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,sBAAsB,GAC1B,gBAAgB,EAAE,CAyCpB"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/dataSources/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AACzD,OAAO,KAAK,EACX,gBAAgB,EAChB,wBAAwB,EACxB,MAAM,iBAAiB,CAAA;AAExB,KAAK,sBAAsB,GAAG;IAC7B,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,kBAAkB,EAAE,wBAAwB,CAAA;CAC5C,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,sBAAsB,GAC1B,gBAAgB,EAAE,CA+BpB"}

package/dist/bridge/dataSources/resolve.js

@@ -2,20 +2,10 @@
  * 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) {
-    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];
         const propertySchemasById = binding?.collectionSchema?.propertiesById ?? {};

package/dist/bridge/hostState.d.ts

@@ -2,6 +2,7 @@ import type { NotionDataSource } from "./dataSources/dataSource.js";
 import type { NotionDataSourcePage, NotionDataSourcePageBridge, NotionDataSourcePageUpdateInput, NotionDataSourcePageUpdateResult } from "./dataSources/dataSourcePage.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";
@@ -19,6 +20,7 @@ export type InitializedHostState = {
     parent: NotionParent;
     page: CustomBlockPage;
     currentUser: NotionUser;
+    manifest: CustomBlockManifest;
     dataSources: NotionDataSource[];
     dataSourceState: Record<string, DataSourceQueryState>;
 };