@notionhq/custom-blocks-host 0.1.8 → 0.1.9

package/README.md

@@ -72,29 +72,42 @@ const host = createCustomBlockHost({
     listUsers: async (message) => listUsers(message),
     resize: (message) => resizeIframe(message.height),
   },
-  onConnect: (message) => {
-    console.log("Connected SDK", message.sdkVersion);
+  onManifest: (manifest) => {
+    console.log("Selected manifest", manifest);
   },
-  onIgnoredConnect: () => {
-    remountHostAndIframe();
+  onInitialized: (state) => {
+    console.log("Initialized manifest", state.manifest);
   },
   onInitializationFailure: (error) => {
     showInitializationError(error);
   },
+  onRestartRequired: () => {
+    remountHostAndIframe();
+  },
   onLog: (direction, payload) => {
     console.log(direction, payload);
   },
 });
 ```
 
-The host runs one initialization per instance. `onIgnoredConnect` fires when a
-`connect` arrives that the settled host cannot serve: the iframe document was
-replaced, or the document's first `connect` came after the no-connect timeout.
-Recreate the host and the iframe together so the document runs a fresh
-handshake against current host state.
+Each host instance initializes once:
+
+- `onManifest` provides the selected manifest as soon as it is available after
+  `connect`, before binding validation and `onInitialized`. Use it to configure
+  bindings even when initialization cannot yet succeed.
+
+- `onInitialized` reports success after the sandbox accepts initialization. It
+  provides the selected `manifest` and the sandbox's optional `initialHeight`.
+- `onInitializationFailure` reports an initialization error or timeout.
+- `onRestartRequired` reports a connection attempt after the host accepts its
+  first connection or stops waiting. Recreate the host and iframe together
+  to accept a new connection.
+  This can occur after the iframe document changes or a connection arrives
+  after a timeout.
 
-`onInitializationFailure` receives structured errors from failed `init`
-messages, failed `initResult` messages, and initialization timeouts.
+The host uses the manifest from `connect`, or `initialState.manifest` if
+`connect` omits it. If neither exists, initialization fails with
+`manifest_unavailable`.
 
 `queryDataSource` is required. Other request handlers are optional. Every
 request handler may return its result synchronously or as a promise. Results
@@ -157,7 +170,7 @@ failure. It logs and ignores a valid `initResult` with a stale
 `initializationId` or an unexpected state.
 
 Hosts do not retry malformed messages. A host that receives a `connect` after
-initialization has settled must use `onIgnoredConnect` to recreate the host
+initialization has settled must use `onRestartRequired` to recreate the host
 and iframe together.
 
 ## Updating live state

package/dist/createCustomBlockHost.d.ts

@@ -1,13 +1,12 @@
 import { type NotionContrastMode } from "./protocol/contrast.js";
 import type { NotionDataSourceId } from "./protocol/ids.js";
-import type { ConnectMessage } from "./protocol/messages/connect.js";
+import type { CustomBlockManifest } from "./protocol/manifest.js";
 import type { HostToSandboxMessage } from "./protocol/messages/hostToSandbox.js";
-import type { InitResultMessage } from "./protocol/messages/initResult.js";
 import type { CustomBlockPage } from "./protocol/pages/page.js";
 import type { NotionParent } from "./protocol/parent.js";
 import type { NotionTheme } from "./protocol/theme.js";
 import type { NotionUser } from "./protocol/users/user.js";
-import type { ConnectSuccessMessage, CustomBlockHostDataSourcesPayload, CustomBlockHostInitialState } from "./lifecycle/types.js";
+import type { CustomBlockHostDataSourcesPayload, CustomBlockHostInitialState } from "./lifecycle/types.js";
 import type { CustomBlockHostHandlers, CustomBlockHostInitializationFailure, CustomBlockHostLogDirection } from "./messages/types.js";
 export type CustomBlockHostOptions = {
     iframe: HTMLIFrameElement;
@@ -17,17 +16,20 @@ export type CustomBlockHostOptions = {
     noInitResultTimeoutMs?: number;
     initialState: CustomBlockHostInitialState;
     handlers: CustomBlockHostHandlers;
-    onConnect?: (message: ConnectSuccessMessage) => void;
-    onInitResult?: (message: InitResultMessage) => void;
+    /** Called as soon as the `manifest` is available after `connect`, before `onInitialized` and binding validation. */
+    onManifest?: (manifest: CustomBlockManifest) => void;
+    /** Callback fired when the initialization handshake with the sandbox completed successfully. */
+    onInitialized?: (state: {
+        manifest: CustomBlockManifest;
+        initialHeight?: number;
+    }) => void;
+    /** Callback fired when the initialization handshake with the sandbox failed or timed out. */
     onInitializationFailure?: (error: CustomBlockHostInitializationFailure) => void;
     /**
-     * A `connect` arrived after this host's initialization settled — the
-     * document was replaced, or its first `connect` came after the host
-     * stopped waiting. Either way the host cannot serve it: the embedder
-     * should recreate host and iframe together so the document can run a
-     * fresh handshake.
+     * Callback fired when the current host and iframe must restart.
+     * Recreate both to continue.
      */
-    onIgnoredConnect?: (message: ConnectMessage) => void;
+    onRestartRequired?: () => void;
     onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void;
 };
 export type CustomBlockHostHandle = {

package/dist/createCustomBlockHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createCustomBlockHost.d.ts","sourceRoot":"","sources":["../src/createCustomBlockHost.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,kBAAkB,EACvB,MAAM,8CAA8C,CAAA;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAA;AAEjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAa1F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AAEtG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAahG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAE9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gDAAgD,CAAA;AAIhF,OAAO,KAAK,EACX,qBAAqB,EACrB,iCAAiC,EACjC,2BAA2B,EAC3B,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EACX,uBAAuB,EACvB,oCAAoC,EACpC,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAU5B,MAAM,MAAM,sBAAsB,GAAG;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB,wBAAwB,EAAE,MAAM,CAAA;IAChC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,YAAY,EAAE,2BAA2B,CAAA;IACzC,QAAQ,EAAE,uBAAuB,CAAA;IACjC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACpD,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACnD,uBAAuB,CAAC,EAAE,CACzB,KAAK,EAAE,oCAAoC,KACvC,IAAI,CAAA;IACT;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IACpD,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,2BAA2B,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC1E,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,IAAI,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAC7C,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IACtC,eAAe,EAAE,CAAC,YAAY,EAAE,kBAAkB,KAAK,IAAI,CAAA;IAC3D,SAAS,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAA;IACzC,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,cAAc,EAAE,CAAC,WAAW,EAAE,iCAAiC,KAAK,IAAI,CAAA;IACxE,cAAc,EAAE,CAAC,WAAW,EAAE,UAAU,KAAK,IAAI,CAAA;IACjD,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,YAAY,EAAE,kBAAkB,CAAA;KAAE,KAAK,IAAI,CAAA;CAClE,CAAA;AAMD,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CAodvB"}
+{"version":3,"file":"createCustomBlockHost.d.ts","sourceRoot":"","sources":["../src/createCustomBlockHost.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,kBAAkB,EACvB,MAAM,8CAA8C,CAAA;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAA;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AAavF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AActG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAE9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gDAAgD,CAAA;AAIhF,OAAO,KAAK,EACX,iCAAiC,EACjC,2BAA2B,EAC3B,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EACX,uBAAuB,EACvB,oCAAoC,EACpC,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAU5B,MAAM,MAAM,sBAAsB,GAAG;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB,wBAAwB,EAAE,MAAM,CAAA;IAChC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,YAAY,EAAE,2BAA2B,CAAA;IACzC,QAAQ,EAAE,uBAAuB,CAAA;IACjC,oHAAoH;IACpH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,CAAA;IACpD,gGAAgG;IAChG,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;QACvB,QAAQ,EAAE,mBAAmB,CAAA;QAC7B,aAAa,CAAC,EAAE,MAAM,CAAA;KACtB,KAAK,IAAI,CAAA;IACV,6FAA6F;IAC7F,uBAAuB,CAAC,EAAE,CACzB,KAAK,EAAE,oCAAoC,KACvC,IAAI,CAAA;IACT;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAA;IAC9B,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,2BAA2B,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC1E,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,IAAI,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAC7C,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IACtC,eAAe,EAAE,CAAC,YAAY,EAAE,kBAAkB,KAAK,IAAI,CAAA;IAC3D,SAAS,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAA;IACzC,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,cAAc,EAAE,CAAC,WAAW,EAAE,iCAAiC,KAAK,IAAI,CAAA;IACxE,cAAc,EAAE,CAAC,WAAW,EAAE,UAAU,KAAK,IAAI,CAAA;IACjD,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,YAAY,EAAE,kBAAkB,CAAA;KAAE,KAAK,IAAI,CAAA;CAClE,CAAA;AAMD,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CA+dvB"}

package/dist/createCustomBlockHost.js

@@ -13,7 +13,7 @@ const initializationIdentitySchema = v.object({
     initializationId: v.string(),
 });
 export function createCustomBlockHost(options) {
-    const { iframe, initialState, handlers, onConnect, onInitResult, onInitializationFailure, onIgnoredConnect, onLog, sandboxOrigin, minBridgeProtocolVersion: configuredMinBridgeProtocolVersion, noConnectTimeoutMs, noInitResultTimeoutMs, } = options;
+    const { iframe, initialState, handlers, onManifest, onInitialized, onInitializationFailure, onRestartRequired, onLog, sandboxOrigin, minBridgeProtocolVersion: configuredMinBridgeProtocolVersion, noConnectTimeoutMs, noInitResultTimeoutMs, } = options;
     const minBridgeProtocolVersion = Math.max(configuredMinBridgeProtocolVersion ?? CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION, CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION);
     let theme = initialState.theme;
     let contrastMode = initialState.contrastMode ?? DEFAULT_CONTRAST_MODE;
@@ -188,6 +188,13 @@ export function createCustomBlockHost(options) {
         }),
         prepareInit(connect) {
             manifest = connect.manifest ?? initialState.manifest;
+            if (manifest === undefined) {
+                return {
+                    status: "error",
+                    error: initErrorForFailureReason("manifest_unavailable"),
+                };
+            }
+            onManifest?.(manifest);
             const resolvedDataSources = typeof dataSources === "function" ? dataSources(connect) : dataSources;
             const bindingErrorCode = getBindingErrorCode(manifest, resolvedDataSources);
             if (bindingErrorCode !== undefined) {
@@ -209,9 +216,12 @@ export function createCustomBlockHost(options) {
         minBridgeProtocolVersion,
         noConnectTimeoutMs,
         noInitResultTimeoutMs,
-        onConnect,
-        onInitResult,
-        onIgnoredConnect,
+        onInitResult(message) {
+            if (message.status === "success" && manifest !== undefined) {
+                onInitialized?.({ manifest, initialHeight: message.initialHeight });
+            }
+        },
+        onRestartRequired,
         onInitializationFailure,
     });
     function onInvalidSandboxMessage(data, issues) {
@@ -368,6 +378,7 @@ export function createCustomBlockHost(options) {
         },
         setDataSources(nextDataSources) {
             if (initializationController.hasConnectedSandbox &&
+                manifest !== undefined &&
                 getBindingErrorCode(manifest, nextDataSources) !== undefined) {
                 emit("warn", {
                     message: "Ignored invalid data source bindings update",

package/dist/lifecycle/initializationController.d.ts

@@ -36,9 +36,8 @@ export type InitializationControllerOptions = {
     minBridgeProtocolVersion: number;
     noConnectTimeoutMs?: number;
     noInitResultTimeoutMs?: number;
-    onConnect?: (message: ConnectSuccessMessage) => void;
     onInitResult?: (message: InitResultMessage) => void;
-    onIgnoredConnect?: (message: ConnectMessage) => void;
+    onRestartRequired?: () => void;
     onInitializationFailure?: (error: CustomBlockHostInitializationFailure) => void;
 };
 export type InitializationController = {

package/dist/lifecycle/initializationController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initializationController.d.ts","sourceRoot":"","sources":["../../src/lifecycle/initializationController.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"initializationController.d.ts","sourceRoot":"","sources":["../../src/lifecycle/initializationController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAA;AACtF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AACvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AACtG,OAAO,KAAK,EACX,wBAAwB,EAExB,MAAM,mDAAmD,CAAA;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gDAAgD,CAAA;AAChF,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,sBAAsB,CAAA;AAGhF,OAAO,KAAK,EACX,qBAAqB,EACrB,iCAAiC,EACjC,UAAU,EACV,MAAM,YAAY,CAAA;AAKnB,KAAK,mBAAmB,GAAG;IAC1B,KAAK,EAAE,WAAW,CAAA;IAClB,YAAY,EAAE,kBAAkB,CAAA;IAChC,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,eAAe,CAAA;IACrB,WAAW,EAAE,UAAU,CAAA;CACvB,CAAA;AAED,KAAK,yBAAyB,GAC3B;IACA,MAAM,EAAE,SAAS,CAAA;IACjB,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,WAAW,EAAE,iCAAiC,CAAA;CAC7C,GACD;IACA,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,wBAAwB,CAAA;CAC9B,CAAA;AAEJ,MAAM,MAAM,+BAA+B,GAAG;IAC7C,OAAO,EAAE,aAAa,CAAA;IACtB,QAAQ,EAAE,MAAM,mBAAmB,CAAA;IACnC,WAAW,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,yBAAyB,CAAA;IAC1E,IAAI,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAC7C,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IAChC,4BAA4B,EAAE,MAAM,IAAI,CAAA;IACxC,wBAAwB,EAAE,MAAM,CAAA;IAChC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACnD,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAA;IAC9B,uBAAuB,CAAC,EAAE,CACzB,KAAK,EAAE,oCAAoC,KACvC,IAAI,CAAA;CACT,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACtC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAA;IACrC,aAAa,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IAChD,gBAAgB,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACtD,oBAAoB,EAAE,CAAC,gBAAgB,CAAC,EAAE,MAAM,KAAK,OAAO,CAAA;IAC5D,uBAAuB,EAAE,MAAM,OAAO,CAAA;IACtC,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,IAAI,EAAE,MAAM,IAAI,CAAA;CAChB,CAAA;AAED,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,+BAA+B,GACtC,wBAAwB,CAuO1B"}

package/dist/lifecycle/initializationController.js

@@ -3,7 +3,7 @@ import { isValidBridgeProtocolVersion } from "./protocolVersion.js";
 const DEFAULT_NO_CONNECT_TIMEOUT_MS = 5_000;
 const DEFAULT_NO_INIT_RESULT_TIMEOUT_MS = 5_000;
 export function createInitializationController(options) {
-    const { blockId, getState, prepareInit, post, warn, flushPendingHostStateChanges, minBridgeProtocolVersion, noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS, noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS, onConnect, onInitResult, onIgnoredConnect, onInitializationFailure, } = options;
+    const { blockId, getState, prepareInit, post, warn, flushPendingHostStateChanges, minBridgeProtocolVersion, noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS, noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS, onInitResult, onRestartRequired, onInitializationFailure, } = options;
     let initStatus = "waitingForConnect";
     let noConnectTimeoutId;
     let noInitResultTimeoutId;
@@ -40,7 +40,6 @@ export function createInitializationController(options) {
         if (initStatus !== "waitingForConnect") {
             return false;
         }
-        onConnect?.(connect);
         const preparation = prepareInit(connect);
         if (preparation.status === "error") {
             sendInitError(connect.initializationId, preparation.error);
@@ -89,7 +88,7 @@ export function createInitializationController(options) {
                 message: "Ignored connect after initialization settled; recreate the host and iframe to re-initialize",
                 initializationId: message.initializationId,
             });
-            onIgnoredConnect?.(message);
+            onRestartRequired?.();
             return;
         }
         // Verify the bridge protocol version is valid.

package/dist/lifecycle/types.d.ts

@@ -21,7 +21,11 @@ export type CustomBlockHostInitialState = {
     blockId: NotionBlockId;
     parent: NotionParent;
     page: CustomBlockPage;
-    manifest: CustomBlockManifest;
+    /**
+     * The host's persisted manifest, when one exists. If omitted, the host
+     * requires the sandbox to provide a manifest in `connect`.
+     */
+    manifest?: CustomBlockManifest;
     dataSources: CustomBlockHostInitialDataSources;
     currentUser: NotionUser;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lifecycle/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAA;AACtF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4DAA4D,CAAA;AAC1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AACvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gDAAgD,CAAA;AAEhF,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAC1C,cAAc,EACd;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CACrB,CAAA;AAED,MAAM,MAAM,UAAU,GACnB,mBAAmB,GACnB,sBAAsB,GACtB,SAAS,GACT,OAAO,CAAA;AAEV,MAAM,MAAM,iCAAiC,GAAG;IAC/C,QAAQ,EAAE,wBAAwB,CAAA;CAClC,CAAA;AAED,MAAM,MAAM,iCAAiC,GAC1C,iCAAiC,GACjC,CAAC,CAAC,OAAO,EAAE,qBAAqB,KAAK,iCAAiC,CAAC,CAAA;AAE1E,MAAM,MAAM,2BAA2B,GAAG;IACzC,KAAK,EAAE,WAAW,CAAA;IAElB,YAAY,CAAC,EAAE,kBAAkB,CAAA;IACjC,OAAO,EAAE,aAAa,CAAA;IACtB,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,eAAe,CAAA;IACrB,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,WAAW,EAAE,iCAAiC,CAAA;IAC9C,WAAW,EAAE,UAAU,CAAA;CACvB,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lifecycle/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAA;AACtF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4DAA4D,CAAA;AAC1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AACvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gDAAgD,CAAA;AAEhF,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAC1C,cAAc,EACd;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CACrB,CAAA;AAED,MAAM,MAAM,UAAU,GACnB,mBAAmB,GACnB,sBAAsB,GACtB,SAAS,GACT,OAAO,CAAA;AAEV,MAAM,MAAM,iCAAiC,GAAG;IAC/C,QAAQ,EAAE,wBAAwB,CAAA;CAClC,CAAA;AAED,MAAM,MAAM,iCAAiC,GAC1C,iCAAiC,GACjC,CAAC,CAAC,OAAO,EAAE,qBAAqB,KAAK,iCAAiC,CAAC,CAAA;AAE1E,MAAM,MAAM,2BAA2B,GAAG;IACzC,KAAK,EAAE,WAAW,CAAA;IAElB,YAAY,CAAC,EAAE,kBAAkB,CAAA;IACjC,OAAO,EAAE,aAAa,CAAA;IACtB,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,eAAe,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAA;IAC9B,WAAW,EAAE,iCAAiC,CAAA;IAC9C,WAAW,EAAE,UAAU,CAAA;CACvB,CAAA"}

package/package.json

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

package/src/createCustomBlockHost.ts

@@ -4,7 +4,6 @@ import {
 } from "@notionhq/custom-blocks-protocol/contrast.js"
 import type { NotionDataSourceId } from "@notionhq/custom-blocks-protocol/ids.js"
 import type { CustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest.js"
-import type { ConnectMessage } from "@notionhq/custom-blocks-protocol/messages/connect.js"
 import type { ContrastModeChangedMessage } from "@notionhq/custom-blocks-protocol/messages/contrastModeChanged.js"
 import type { CreatePageMessage } from "@notionhq/custom-blocks-protocol/messages/createPage.js"
 import type { CreatePageResultMessage } from "@notionhq/custom-blocks-protocol/messages/createPageResult.js"
@@ -19,7 +18,6 @@ import type {
 } from "@notionhq/custom-blocks-protocol/messages/getUser.js"
 import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
 import type { CustomBlockInitErrorCode } from "@notionhq/custom-blocks-protocol/messages/init.js"
-import type { InitResultMessage } from "@notionhq/custom-blocks-protocol/messages/initResult.js"
 import type {
 	ListUsersMessage,
 	ListUsersResultMessage,
@@ -41,7 +39,6 @@ import * as v from "valibot"
 import { initErrorForFailureReason } from "./lifecycle/initErrors.js"
 import { createInitializationController } from "./lifecycle/initializationController.js"
 import type {
-	ConnectSuccessMessage,
 	CustomBlockHostDataSourcesPayload,
 	CustomBlockHostInitialState,
 } from "./lifecycle/types.js"
@@ -68,19 +65,22 @@ export type CustomBlockHostOptions = {
 	noInitResultTimeoutMs?: number
 	initialState: CustomBlockHostInitialState
 	handlers: CustomBlockHostHandlers
-	onConnect?: (message: ConnectSuccessMessage) => void
-	onInitResult?: (message: InitResultMessage) => void
+	/** Called as soon as the `manifest` is available after `connect`, before `onInitialized` and binding validation. */
+	onManifest?: (manifest: CustomBlockManifest) => void
+	/** Callback fired when the initialization handshake with the sandbox completed successfully. */
+	onInitialized?: (state: {
+		manifest: CustomBlockManifest
+		initialHeight?: number
+	}) => void
+	/** Callback fired when the initialization handshake with the sandbox failed or timed out. */
 	onInitializationFailure?: (
 		error: CustomBlockHostInitializationFailure,
 	) => void
 	/**
-	 * A `connect` arrived after this host's initialization settled — the
-	 * document was replaced, or its first `connect` came after the host
-	 * stopped waiting. Either way the host cannot serve it: the embedder
-	 * should recreate host and iframe together so the document can run a
-	 * fresh handshake.
+	 * Callback fired when the current host and iframe must restart.
+	 * Recreate both to continue.
 	 */
-	onIgnoredConnect?: (message: ConnectMessage) => void
+	onRestartRequired?: () => void
 	onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void
 }
 
@@ -107,10 +107,10 @@ export function createCustomBlockHost(
 		iframe,
 		initialState,
 		handlers,
-		onConnect,
-		onInitResult,
+		onManifest,
+		onInitialized,
 		onInitializationFailure,
-		onIgnoredConnect,
+		onRestartRequired,
 		onLog,
 		sandboxOrigin,
 		minBridgeProtocolVersion: configuredMinBridgeProtocolVersion,
@@ -322,6 +322,13 @@ export function createCustomBlockHost(
 		}),
 		prepareInit(connect) {
 			manifest = connect.manifest ?? initialState.manifest
+			if (manifest === undefined) {
+				return {
+					status: "error",
+					error: initErrorForFailureReason("manifest_unavailable"),
+				}
+			}
+			onManifest?.(manifest)
 			const resolvedDataSources =
 				typeof dataSources === "function" ? dataSources(connect) : dataSources
 			const bindingErrorCode = getBindingErrorCode(
@@ -347,9 +354,12 @@ export function createCustomBlockHost(
 		minBridgeProtocolVersion,
 		noConnectTimeoutMs,
 		noInitResultTimeoutMs,
-		onConnect,
-		onInitResult,
-		onIgnoredConnect,
+		onInitResult(message) {
+			if (message.status === "success" && manifest !== undefined) {
+				onInitialized?.({ manifest, initialHeight: message.initialHeight })
+			}
+		},
+		onRestartRequired,
 		onInitializationFailure,
 	})
 
@@ -524,6 +534,7 @@ export function createCustomBlockHost(
 		setDataSources(nextDataSources) {
 			if (
 				initializationController.hasConnectedSandbox &&
+				manifest !== undefined &&
 				getBindingErrorCode(manifest, nextDataSources) !== undefined
 			) {
 				emit("warn", {

package/src/lifecycle/initializationController.ts

@@ -53,9 +53,8 @@ export type InitializationControllerOptions = {
 	minBridgeProtocolVersion: number
 	noConnectTimeoutMs?: number
 	noInitResultTimeoutMs?: number
-	onConnect?: (message: ConnectSuccessMessage) => void
 	onInitResult?: (message: InitResultMessage) => void
-	onIgnoredConnect?: (message: ConnectMessage) => void
+	onRestartRequired?: () => void
 	onInitializationFailure?: (
 		error: CustomBlockHostInitializationFailure,
 	) => void
@@ -85,9 +84,8 @@ export function createInitializationController(
 		minBridgeProtocolVersion,
 		noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS,
 		noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS,
-		onConnect,
 		onInitResult,
-		onIgnoredConnect,
+		onRestartRequired,
 		onInitializationFailure,
 	} = options
 
@@ -134,7 +132,6 @@ export function createInitializationController(
 		if (initStatus !== "waitingForConnect") {
 			return false
 		}
-		onConnect?.(connect)
 		const preparation = prepareInit(connect)
 		if (preparation.status === "error") {
 			sendInitError(connect.initializationId, preparation.error)
@@ -185,7 +182,7 @@ export function createInitializationController(
 					"Ignored connect after initialization settled; recreate the host and iframe to re-initialize",
 				initializationId: message.initializationId,
 			})
-			onIgnoredConnect?.(message)
+			onRestartRequired?.()
 			return
 		}
 

package/src/lifecycle/types.ts

@@ -34,7 +34,11 @@ export type CustomBlockHostInitialState = {
 	blockId: NotionBlockId
 	parent: NotionParent
 	page: CustomBlockPage
-	manifest: CustomBlockManifest
+	/**
+	 * The host's persisted manifest, when one exists. If omitted, the host
+	 * requires the sandbox to provide a manifest in `connect`.
+	 */
+	manifest?: CustomBlockManifest
 	dataSources: CustomBlockHostInitialDataSources
 	currentUser: NotionUser
 }