@notionhq/custom-blocks 0.1.20 → 0.1.21

package/README.md

@@ -81,7 +81,7 @@ export function App() {
 }
 ```
 
-`<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.
+`<NotionCustomBlock>` runs the SDK ↔ host handshake (`connect` → `init` → `initResult`) and only mounts `children` once the host state is available. It measures the initial content before sending `initResult`, so the host can reveal the iframe at its correct height. Inside the wrapper, every hook returns non-nullable values — there's no separate gating component to write. It continues observing content height changes automatically.
 
 ## Notion design tokens
 
@@ -97,7 +97,7 @@ The stylesheet is scoped rather than installed globally. Render portals inside `
 
 API surface, one page per category. Import framework-neutral APIs from `@notionhq/custom-blocks`; import React hooks and components from `@notionhq/custom-blocks/react`. Hover docs in your editor cover the per-field detail; these pages cover usage shape and the gotchas.
 
-- [`docs/lifecycle.md`](./docs/lifecycle.md) — `<NotionCustomBlock>`, `useCustomBlockInit`, `initCustomBlock`, `customBlock.autoResize`, `NotInIframeError`, `useCustomBlockAutoResize`. The handshake, the React wrapper, sizing.
+- [`docs/lifecycle.md`](./docs/lifecycle.md) — `<NotionCustomBlock>`, `useCustomBlockInit`, `initCustomBlock`, `NotInIframeError`, `useCustomBlockAutoResize`. The handshake, the React wrapper, sizing.
 - [`docs/block-location.md`](./docs/block-location.md) — `useBlockId`, `useParent`, `usePage`, `useTheme`, and `useContrastMode`. Where the block sits and how to read the host's appearance.
 - [`docs/data-sources.md`](./docs/data-sources.md) — `useDataSource`, `useManifest`, `customBlock.getManifest`, the row, property, and date-value types, plus a worked example.
 - [`docs/pages.md`](./docs/pages.md) — `pages.create / get / update / delete`, parent variants (including the recommended `data_source_key`), property input shapes.

package/dist/bridge/SandboxBridge.d.ts

@@ -26,6 +26,8 @@ export declare class SandboxBridge {
     private hasSentConnect;
     private hasReceivedInit;
     private initializationId;
+    private hasSentInitResult;
+    private pendingOutboundMessages;
     private latestDataSourceBindings;
     private isMockState;
     private isListening;
@@ -40,6 +42,9 @@ export declare class SandboxBridge {
     awaitInit(signal?: AbortSignal): Promise<void>;
     sendConnect(manifestResult: ManifestLoadResult): void;
     private postToHost;
+    private sendToHost;
+    private flushPendingOutboundMessages;
+    private getMessageType;
     private notify;
     private handleMessage;
     subscribe(listener: () => void): () => boolean;
@@ -51,7 +56,13 @@ export declare class SandboxBridge {
      * of why it's being seeded.
      */
     setMockState(message: InitMessage): void;
+    completeInitialization(): void;
     private applyInit;
+    /**
+     * Lets the initial application render commit before we acknowledge init. The host keeps the
+     * iframe covered throughout this frame, so it can apply the measured height before first paint.
+     */
+    private scheduleInitResult;
     queryDataSource(key: string, options?: UseDataSourceOptions): void;
     private setDataSourceQueryError;
     postResize(height: number): void;

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

@@ -11,6 +11,7 @@ import { resolveDataSources } from "./dataSources/resolve.js";
 import { resolvePropertyWriteMapForDataSource } from "./dataSources/resolveProperty.js";
 import { createEmptyDataSourceQueryState, } from "./hostState.js";
 import { PendingRequests } from "./pendingRequests.js";
+const INIT_RESULT_TIMER_FALLBACK_MS = 100;
 export class SandboxBridge {
     constructor() {
         this.hostState = {
@@ -29,6 +30,8 @@ export class SandboxBridge {
         this.pendingUpdatePage = new PendingRequests("custom-block-update-page");
         this.hasSentConnect = false;
         this.hasReceivedInit = false;
+        this.hasSentInitResult = false;
+        this.pendingOutboundMessages = [];
         this.latestDataSourceBindings = {};
         this.isMockState = false;
         this.isListening = false;
@@ -343,10 +346,32 @@ export class SandboxBridge {
         this.postToHost(connectMessage);
     }
     postToHost(message) {
+        if (this.hostState.status === "initialized" &&
+            !this.hasSentInitResult &&
+            !this.isMockState &&
+            this.getMessageType(message) !== "initResult") {
+            this.pendingOutboundMessages.push(message);
+            return;
+        }
+        this.sendToHost(message);
+    }
+    sendToHost(message) {
         console.debug("[custom-blocks-sdk] outbound postMessage", message);
         this.logMessage("sent", message);
         window.parent.postMessage(message, "*");
     }
+    flushPendingOutboundMessages() {
+        const pendingMessages = this.pendingOutboundMessages;
+        this.pendingOutboundMessages = [];
+        for (const message of pendingMessages) {
+            this.sendToHost(message);
+        }
+    }
+    getMessageType(message) {
+        return typeof message === "object" && message !== null && "type" in message
+            ? message.type
+            : undefined;
+    }
     subscribe(listener) {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
@@ -364,6 +389,22 @@ export class SandboxBridge {
         this.isMockState = true;
         this.applyInit(v.parse(initMessageSchema, message), false);
     }
+    completeInitialization() {
+        if (this.hasSentInitResult ||
+            this.initializationId === undefined ||
+            this.hostState.status !== "initialized") {
+            return;
+        }
+        const result = {
+            type: "initResult",
+            initializationId: this.initializationId,
+            status: "success",
+            initialHeight: getInitialContentHeight(),
+        };
+        this.hasSentInitResult = true;
+        this.postToHost(result);
+        this.flushPendingOutboundMessages();
+    }
     applyInit(message, postResult) {
         if (postResult) {
             this.isMockState = false;
@@ -424,14 +465,6 @@ export class SandboxBridge {
             contrastMode: message.contrastMode,
         });
         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.
@@ -440,6 +473,34 @@ export class SandboxBridge {
             this.resolveInit = undefined;
             this.rejectInit = undefined;
         }
+        if (postResult) {
+            this.scheduleInitResult(message.initializationId);
+        }
+    }
+    /**
+     * Lets the initial application render commit before we acknowledge init. The host keeps the
+     * iframe covered throughout this frame, so it can apply the measured height before first paint.
+     */
+    scheduleInitResult(initializationId) {
+        let didAcknowledge = false;
+        let fallbackTimerId;
+        const acknowledge = () => {
+            if (didAcknowledge) {
+                return;
+            }
+            didAcknowledge = true;
+            if (fallbackTimerId !== undefined) {
+                window.clearTimeout(fallbackTimerId);
+            }
+            if (this.initializationId !== initializationId) {
+                return;
+            }
+            this.completeInitialization();
+        };
+        fallbackTimerId = window.setTimeout(acknowledge, INIT_RESULT_TIMER_FALLBACK_MS);
+        if (typeof requestAnimationFrame === "function") {
+            requestAnimationFrame(acknowledge);
+        }
     }
     queryDataSource(key, options = {}) {
         if (this.hostState.status !== "initialized") {
@@ -712,6 +773,16 @@ export class SandboxBridge {
     }
 }
 SandboxBridge.MAX_LOG_ENTRIES = 100;
+function getInitialContentHeight() {
+    if (typeof document === "undefined") {
+        return 0;
+    }
+    const root = document.getElementById("root");
+    if (root === null) {
+        return 0;
+    }
+    return Math.ceil(root.getBoundingClientRect().height);
+}
 /**
  * Makes the document canvas match the host appearance before acknowledging init.
  *

package/dist/bridge/sandboxClient.d.ts

@@ -15,6 +15,7 @@ export declare const customBlockHost: {
      * standalone preview state.
      */
     setMockState: (message: InitMessage) => void;
+    completeInitialization: () => void;
     postResize: (height: number) => void;
 };
 export declare const customBlockDataSources: {

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

@@ -1 +1 @@
-{"version":3,"file":"sandboxClient.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/sandboxClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mDAAmD,CAAA;AACpF,OAAO,KAAK,EACX,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,aAAa,EACb,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,MAAM,aAAa,CAAA;AACpB,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EAExB,MAAM,gBAAgB,CAAA;AACvB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,oBAAoB,CAAA;AAExE,YAAY,EAAE,eAAe,EAAE,CAAA;AAW/B,eAAO,MAAM,eAAe;;kCAKG,kBAAkB;yBAI3B,WAAW,KAAG,OAAO,CAAC,IAAI,CAAC;0BAI1B,MAAM,IAAI;oBAIlB,oBAAoB;IAIlC;;;OAGG;4BACqB,WAAW;yBAId,MAAM;CAG3B,CAAA;AAED,eAAO,MAAM,sBAAsB;iBACrB,MAAM,YAAY,oBAAoB;yBAKvC,oBAAoB,OAC1B,MAAM,KACT,mBAAmB;CAKtB,CAAA;AAED,eAAO,MAAM,UAAU;uBACL,SAAS,eAAe,EAAE;0BAIrB,MAAM,IAAI;CAGhC,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,KAAK;IACjB;;OAEG;oBACa,cAAc,KAAG,OAAO,CAAC,gBAAgB,CAAC;IAI1D;;OAEG;kBACW,YAAY,KAAG,OAAO,CAAC,aAAa,CAAC;IAInD;;OAEG;oBACa,cAAc,KAAG,OAAO,CAAC,gBAAgB,CAAC;IAI1D;;OAEG;qBACc,YAAY,KAAG,OAAO,CAAC,gBAAgB,CAAC;CAGzD,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,KAAK;IACjB;;OAEG;mBACY,aAAa,KAAG,OAAO,CAAC,eAAe,CAAC;IAIvD;;OAEG;kBACW,YAAY,KAAG,OAAO,CAAC,aAAa,CAAC;CAGnD,CAAA"}
+{"version":3,"file":"sandboxClient.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/sandboxClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mDAAmD,CAAA;AACpF,OAAO,KAAK,EACX,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,aAAa,EACb,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,MAAM,aAAa,CAAA;AACpB,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EAExB,MAAM,gBAAgB,CAAA;AACvB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,oBAAoB,CAAA;AAExE,YAAY,EAAE,eAAe,EAAE,CAAA;AAW/B,eAAO,MAAM,eAAe;;kCAKG,kBAAkB;yBAI3B,WAAW,KAAG,OAAO,CAAC,IAAI,CAAC;0BAI1B,MAAM,IAAI;oBAIlB,oBAAoB;IAIlC;;;OAGG;4BACqB,WAAW;;yBAQd,MAAM;CAG3B,CAAA;AAED,eAAO,MAAM,sBAAsB;iBACrB,MAAM,YAAY,oBAAoB;yBAKvC,oBAAoB,OAC1B,MAAM,KACT,mBAAmB;CAKtB,CAAA;AAED,eAAO,MAAM,UAAU;uBACL,SAAS,eAAe,EAAE;0BAIrB,MAAM,IAAI;CAGhC,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,KAAK;IACjB;;OAEG;oBACa,cAAc,KAAG,OAAO,CAAC,gBAAgB,CAAC;IAI1D;;OAEG;kBACW,YAAY,KAAG,OAAO,CAAC,aAAa,CAAC;IAInD;;OAEG;oBACa,cAAc,KAAG,OAAO,CAAC,gBAAgB,CAAC;IAI1D;;OAEG;qBACc,YAAY,KAAG,OAAO,CAAC,gBAAgB,CAAC;CAGzD,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,KAAK;IACjB;;OAEG;mBACY,aAAa,KAAG,OAAO,CAAC,eAAe,CAAC;IAIvD;;OAEG;kBACW,YAAY,KAAG,OAAO,CAAC,aAAa,CAAC;CAGnD,CAAA"}

package/dist/bridge/sandboxClient.js

@@ -30,6 +30,9 @@ export const customBlockHost = {
     setMockState: (message) => {
         getBridge().setMockState(message);
     },
+    completeInitialization: () => {
+        getBridge().completeInitialization();
+    },
     postResize: (height) => {
         getBridge().postResize(height);
     },

package/dist/protocol/messages/initResult.d.ts

@@ -15,6 +15,8 @@ export declare const initResultMessageSchema: v.VariantSchema<"status", [v.Objec
     readonly type: v.LiteralSchema<"initResult", undefined>;
     readonly initializationId: v.StringSchema<undefined>;
     readonly status: v.LiteralSchema<"success", undefined>;
+    /** Height of the initial rendered custom-block content, in CSS pixels. */
+    readonly initialHeight: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.FiniteAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
 }, undefined>, v.ObjectSchema<{
     readonly type: v.LiteralSchema<"initResult", undefined>;
     readonly initializationId: v.StringSchema<undefined>;

package/dist/protocol/messages/initResult.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initResult.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/protocol/src/messages/initResult.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAI9E,eAAO,MAAM,oCAAoC,2BAAa,CAAA;AAE9D,MAAM,MAAM,8BAA8B,GACzC,oBAAoB,CAAC,uBAAuB,CAAC,CAAA;AAE9C,MAAM,MAAM,8BAA8B,GACzC,oBAAoB,CAAC,8BAA8B,CAAC,CAAA;AAErD,eAAO,MAAM,oCAAoC;;;;aAI/C,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;0BAYlC,CAAA;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAA"}
+{"version":3,"file":"initResult.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/protocol/src/messages/initResult.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAI9E,eAAO,MAAM,oCAAoC,2BAAa,CAAA;AAE9D,MAAM,MAAM,8BAA8B,GACzC,oBAAoB,CAAC,uBAAuB,CAAC,CAAA;AAE9C,MAAM,MAAM,8BAA8B,GACzC,oBAAoB,CAAC,8BAA8B,CAAC,CAAA;AAErD,eAAO,MAAM,oCAAoC;;;;aAI/C,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;IAKlC,0EAA0E;;;;;;;;;;;0BAU1E,CAAA;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAA"}

package/dist/protocol/messages/initResult.js

@@ -15,6 +15,9 @@ export const initResultMessageSchema = v.variant("status", [
         type: v.literal("initResult"),
         initializationId: v.string(),
         status: v.literal("success"),
+        /** Height of the initial rendered custom-block content, in CSS pixels. */
+        // TODO(custom-blocks): Make this required when bumping bridge protocol version 4.
+        initialHeight: v.optional(v.pipe(v.number(), v.finite(), v.minValue(0))),
     }),
     v.object({
         type: v.literal("initResult"),

package/dist/protocol/messages/sandboxToHost.d.ts

@@ -43,6 +43,7 @@ export declare const sandboxToHostMessageSchema: v.UnionSchema<[v.VariantSchema<
     readonly type: v.LiteralSchema<"initResult", undefined>;
     readonly initializationId: v.StringSchema<undefined>;
     readonly status: v.LiteralSchema<"success", undefined>;
+    readonly initialHeight: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.FiniteAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
 }, undefined>, v.ObjectSchema<{
     readonly type: v.LiteralSchema<"initResult", undefined>;
     readonly initializationId: v.StringSchema<undefined>;

package/dist/protocol/messages/sandboxToHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandboxToHost.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/protocol/src/messages/sandboxToHost.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAY5B;;;GAGG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAWrC,CAAA;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAC/C,OAAO,0BAA0B,CACjC,CAAA"}
+{"version":3,"file":"sandboxToHost.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/protocol/src/messages/sandboxToHost.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAY5B;;;GAGG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAWrC,CAAA;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAC/C,OAAO,0BAA0B,CACjC,CAAA"}

package/dist/react/NotionCustomBlock.d.ts

@@ -18,10 +18,9 @@ export type NotionCustomBlockProps = InitCustomBlockOptions & {
      */
     errorFallback?: ReactNode | ((error: Error) => ReactNode);
     /**
-     * Whether the provider should automatically post resize messages so the
-     * host iframe matches the content height of `#root`. Defaults to `true`.
-     * Pass `false` when you want to use the default block size and are ok
-     * with scrollbars within the Notion client.
+     * Whether to post resize messages after initialization and dynamically resize the block.
+     *
+     * @deprecated TODO(custom-blocks): Remove this prop when bumping the SDK version to 0.2.0.
      *
      * @default true
      */

package/dist/react/NotionCustomBlock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NotionCustomBlock.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/react/NotionCustomBlock.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAuB,MAAM,OAAO,CAAA;AAC3D,OAAO,EAAE,KAAK,sBAAsB,EAAoB,MAAM,aAAa,CAAA;AAM3E,OAAO,yBAAyB,CAAA;AAEhC;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,sBAAsB,GAAG;IAC7D,QAAQ,EAAE,SAAS,CAAA;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC,CAAA;IACzD;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,EACjC,QAAQ,EACR,SAAS,EACT,QAAe,EACf,aAAa,EACb,UAAiB,GACjB,EAAE,sBAAsB,2CA4DxB"}
+{"version":3,"file":"NotionCustomBlock.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/react/NotionCustomBlock.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAwC,MAAM,OAAO,CAAA;AAE5E,OAAO,EAAE,KAAK,sBAAsB,EAAoB,MAAM,aAAa,CAAA;AAM3E,OAAO,yBAAyB,CAAA;AAEhC;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,sBAAsB,GAAG;IAC7D,QAAQ,EAAE,SAAS,CAAA;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC,CAAA;IACzD;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,EACjC,QAAQ,EACR,SAAS,EACT,QAAe,EACf,aAAa,EACb,UAAiB,GACjB,EAAE,sBAAsB,2CAsExB"}

package/dist/react/NotionCustomBlock.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
+import { useEffect, useLayoutEffect, useState } from "react";
+import { customBlockHost } from "../bridge/sandboxClient.js";
 import { NotInIframeError } from "../index.js";
 import { DebugMessageLog } from "./DebugMessageLog.js";
 import { seedStandalonePreviewState } from "./standalonePreview.js";
@@ -28,7 +29,8 @@ import "./NotionCustomBlock.css";
  */
 export function NotionCustomBlock({ children, timeoutMs, fallback = null, errorFallback, autoResize = true, }) {
     const init = useCustomBlockInit({ timeoutMs });
-    useCustomBlockAutoResize({ enabled: autoResize });
+    useCustomBlockAutoResize({ enabled: init.isLoaded && autoResize });
+    // True if the block has no host (i.e. it's running in standalone preview).
     const isStandalone = init.error instanceof NotInIframeError;
     const host = useCustomBlockHost();
     const [debugOpen, setDebugOpen] = useState(false);
@@ -48,6 +50,14 @@ export function NotionCustomBlock({ children, timeoutMs, fallback = null, errorF
         console.warn(`[custom-blocks-sdk] ${init.error?.message}`);
         seedStandalonePreviewState();
     }, [isStandalone, init.error]);
+    useLayoutEffect(() => {
+        if (!init.isLoaded || isStandalone) {
+            return;
+        }
+        // Send `initResult` *after* React renders the block so the SDK can report its rendered
+        // height to the host as part of the `initResult` message.
+        customBlockHost.completeInitialization();
+    }, [init.isLoaded, isStandalone]);
     if (debugOpen) {
         return _jsx(DebugMessageLog, {});
     }

package/dist/react/useCustomBlockAutoResize.d.ts

@@ -2,16 +2,12 @@
  * Measures the sandbox's `#root` element and posts `resize` messages so the host iframe
  * matches the block's border-box height. Unchanged values are deduped.
  *
- * `<NotionCustomBlock>` calls this hook for you by default — only reach for it directly
- * when you need to drive `enabled` yourself (e.g. behind a debug toggle). In that case,
- * pass `autoResize={false}` to the provider to avoid running it twice. For full-bleed
- * views that should fill their slot, pass `autoResize={false}` and skip the hook.
+ * `<NotionCustomBlock>` calls this hook for you. Only use it directly in a custom
+ * initialization wrapper that does not render `<NotionCustomBlock>`.
  *
- * @example
- * <NotionCustomBlock autoResize={false}>
- *   <App />
- * </NotionCustomBlock>
+ * @deprecated Use CSS `max-height` and `overflow` to constrain block content instead.
  *
+ * @example
  * function App() {
  *   const [enabled, setEnabled] = useState(true)
  *   useCustomBlockAutoResize({ enabled })

package/dist/react/useCustomBlockAutoResize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCustomBlockAutoResize.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/react/useCustomBlockAutoResize.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CACvC,IAAI,GAAE;IACL;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CACZ,GACJ,IAAI,CAYN"}
+{"version":3,"file":"useCustomBlockAutoResize.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/react/useCustomBlockAutoResize.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACvC,IAAI,GAAE;IACL;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CACZ,GACJ,IAAI,CAYN"}

package/dist/react/useCustomBlockAutoResize.js

@@ -4,16 +4,12 @@ import { customBlock } from "../index.js";
  * Measures the sandbox's `#root` element and posts `resize` messages so the host iframe
  * matches the block's border-box height. Unchanged values are deduped.
  *
- * `<NotionCustomBlock>` calls this hook for you by default — only reach for it directly
- * when you need to drive `enabled` yourself (e.g. behind a debug toggle). In that case,
- * pass `autoResize={false}` to the provider to avoid running it twice. For full-bleed
- * views that should fill their slot, pass `autoResize={false}` and skip the hook.
+ * `<NotionCustomBlock>` calls this hook for you. Only use it directly in a custom
+ * initialization wrapper that does not render `<NotionCustomBlock>`.
  *
- * @example
- * <NotionCustomBlock autoResize={false}>
- *   <App />
- * </NotionCustomBlock>
+ * @deprecated Use CSS `max-height` and `overflow` to constrain block content instead.
  *
+ * @example
  * function App() {
  *   const [enabled, setEnabled] = useState(true)
  *   useCustomBlockAutoResize({ enabled })

package/dist/version.js

@@ -4,4 +4,4 @@
  *
  * WARNING: Generated during SDK publish. Do not edit in the published package.
  */
-export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.20"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.21"

package/docs/lifecycle.md

@@ -4,13 +4,13 @@ The SDK ↔ host handshake, the React wrapper that runs it, and the auto-resize
 
 ## Handshake
 
-`initCustomBlock()` completes a three-message handshake:
+`initCustomBlock()` handles three messages:
 
-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.
+1. The SDK sends `connect` with a new initialization ID and version information.
+2. The host sends `init`. It includes the same ID, the manifest, block context, current user, and data source bindings.
+3. The SDK sends `initResult` with the ID and the initial block height.
 
-The promise resolves only after the SDK sends `initResult.success`. Await it before mounting React so hooks always see initialized state.
+The promise resolves when the SDK applies the host state. Await it before React renders so hooks read initialized state. The SDK sends `initResult` after the initial render.
 
 - 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.
@@ -19,10 +19,16 @@ The promise resolves only after the SDK sends `initResult.success`. Await it bef
 
 ## Sizing
 
-The host owns width and height. Inside the iframe, `100vh` ≠ a screen and there's no meaningful "device width" — only iframe width. Layouts must reflow from a phone column to a desktop block.
+All blocks resize to fit their content. The Notion app limits block height to 10,000 pixels.
 
-- **Self-sizing content** is the default — `<NotionCustomBlock>` measures `#root` and posts `resize` messages so the iframe tracks your content. Pass `autoResize={false}` for full-bleed views, or to drive `useCustomBlockAutoResize` yourself.
-- Prefer container queries (`@container`) over viewport queries.
+To set a shorter height, set `max-height` and `overflow-y` on `#root`:
+
+```css
+#root {
+  max-height: 600px;
+  overflow-y: auto;
+}
+```
 
 ## API
 
@@ -35,11 +41,10 @@ type NotionCustomBlockProps = InitCustomBlockOptions & {
   children: ReactNode;
   fallback?: ReactNode;
   errorFallback?: ReactNode | ((error: Error) => ReactNode);
-  autoResize?: boolean; // defaults to true
 };
 ```
 
-Top-level wrapper. Runs the handshake, gates `children`, and (by default) drives auto-resize. `fallback` replaces the loading view (default `null`); `errorFallback` replaces the inline `<p role="alert">` shown if init rejects. `timeoutMs` flows through to `initCustomBlock`. Pass `autoResize={false}` for full-bleed views or to call `useCustomBlockAutoResize` yourself.
+Top-level wrapper. It starts the handshake and renders `children` after init. It measures `#root` before it shows the iframe and when content height changes. `fallback` replaces the loading view. Its default is `null`. `errorFallback` replaces the error message if init fails. `timeoutMs` passes to `initCustomBlock`.
 
 ### `useCustomBlockInit(opts?)`
 
@@ -120,23 +125,13 @@ Thrown when `initCustomBlock` is called in a top-level tab (no parent frame). It
 
 ### `useCustomBlockAutoResize({ enabled? })`
 
+Deprecated. Blocks resize automatically. Use CSS `max-height` and `overflow` to set a shorter height.
+
 ```ts
 function useCustomBlockAutoResize(args?: { enabled?: boolean }): void;
 ```
 
-React wrapper around `customBlock.autoResize({ target: document.getElementById("root") })`. Measures `#root`'s height and posts `resize` messages, deduping unchanged values. `<NotionCustomBlock>` runs this for you — only call it directly when you want to drive `enabled` yourself (e.g. a debug toggle), and pair with `autoResize={false}` so it doesn't run twice. The target must have intrinsic height; do not give it `height: 100%` or `100vh`.
-
-```tsx
-<NotionCustomBlock autoResize={false}>
-  <App />
-</NotionCustomBlock>;
-
-function App() {
-  const [enabled, setEnabled] = useState(true);
-  useCustomBlockAutoResize({ enabled });
-  return <div>…</div>;
-}
-```
+Deprecated React wrapper around `customBlock.autoResize({ target: document.getElementById("root") })`. It measures `#root`'s height and posts `resize` messages, deduping unchanged values. `<NotionCustomBlock>` runs this automatically.
 
 ## Debug console
 

package/package.json

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

package/src/bridge/SandboxBridge.ts

@@ -73,6 +73,8 @@ export type MessageLogEntry = {
 	data: unknown
 }
 
+const INIT_RESULT_TIMER_FALLBACK_MS = 100
+
 export class SandboxBridge {
 	private hostState: CustomBlockHostState = {
 		status: "uninitialized",
@@ -101,6 +103,8 @@ export class SandboxBridge {
 	private hasSentConnect = false
 	private hasReceivedInit = false
 	private initializationId: string | undefined
+	private hasSentInitResult = false
+	private pendingOutboundMessages: unknown[] = []
 	private latestDataSourceBindings: NotionDataSourceBindings = {}
 	private isMockState = false
 	private isListening = false
@@ -205,11 +209,38 @@ export class SandboxBridge {
 	}
 
 	private postToHost(message: unknown) {
+		if (
+			this.hostState.status === "initialized" &&
+			!this.hasSentInitResult &&
+			!this.isMockState &&
+			this.getMessageType(message) !== "initResult"
+		) {
+			this.pendingOutboundMessages.push(message)
+			return
+		}
+		this.sendToHost(message)
+	}
+
+	private sendToHost(message: unknown) {
 		console.debug("[custom-blocks-sdk] outbound postMessage", message)
 		this.logMessage("sent", message)
 		window.parent.postMessage(message, "*")
 	}
 
+	private flushPendingOutboundMessages() {
+		const pendingMessages = this.pendingOutboundMessages
+		this.pendingOutboundMessages = []
+		for (const message of pendingMessages) {
+			this.sendToHost(message)
+		}
+	}
+
+	private getMessageType(message: unknown): unknown {
+		return typeof message === "object" && message !== null && "type" in message
+			? message.type
+			: undefined
+	}
+
 	private notify = () => {
 		for (const listener of this.listeners) {
 			listener()
@@ -504,6 +535,25 @@ export class SandboxBridge {
 		this.applyInit(v.parse(initMessageSchema, message), false)
 	}
 
+	completeInitialization() {
+		if (
+			this.hasSentInitResult ||
+			this.initializationId === undefined ||
+			this.hostState.status !== "initialized"
+		) {
+			return
+		}
+		const result: InitResultMessage = {
+			type: "initResult",
+			initializationId: this.initializationId,
+			status: "success",
+			initialHeight: getInitialContentHeight(),
+		}
+		this.hasSentInitResult = true
+		this.postToHost(result)
+		this.flushPendingOutboundMessages()
+	}
+
 	private applyInit(message: InitMessage, postResult: boolean) {
 		if (postResult) {
 			this.isMockState = false
@@ -568,14 +618,6 @@ export class SandboxBridge {
 			contrastMode: message.contrastMode,
 		})
 		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.
@@ -584,6 +626,38 @@ export class SandboxBridge {
 			this.resolveInit = undefined
 			this.rejectInit = undefined
 		}
+		if (postResult) {
+			this.scheduleInitResult(message.initializationId)
+		}
+	}
+
+	/**
+	 * Lets the initial application render commit before we acknowledge init. The host keeps the
+	 * iframe covered throughout this frame, so it can apply the measured height before first paint.
+	 */
+	private scheduleInitResult(initializationId: string) {
+		let didAcknowledge = false
+		let fallbackTimerId: number | undefined
+		const acknowledge = () => {
+			if (didAcknowledge) {
+				return
+			}
+			didAcknowledge = true
+			if (fallbackTimerId !== undefined) {
+				window.clearTimeout(fallbackTimerId)
+			}
+			if (this.initializationId !== initializationId) {
+				return
+			}
+			this.completeInitialization()
+		}
+		fallbackTimerId = window.setTimeout(
+			acknowledge,
+			INIT_RESULT_TIMER_FALLBACK_MS,
+		)
+		if (typeof requestAnimationFrame === "function") {
+			requestAnimationFrame(acknowledge)
+		}
 	}
 
 	queryDataSource(key: string, options: UseDataSourceOptions = {}) {
@@ -902,6 +976,17 @@ export class SandboxBridge {
 	}
 }
 
+function getInitialContentHeight(): number {
+	if (typeof document === "undefined") {
+		return 0
+	}
+	const root = document.getElementById("root")
+	if (root === null) {
+		return 0
+	}
+	return Math.ceil(root.getBoundingClientRect().height)
+}
+
 /**
  * Makes the document canvas match the host appearance before acknowledging init.
  *

package/src/bridge/sandboxClient.ts

@@ -60,6 +60,10 @@ export const customBlockHost = {
 		getBridge().setMockState(message)
 	},
 
+	completeInitialization: () => {
+		getBridge().completeInitialization()
+	},
+
 	postResize: (height: number) => {
 		getBridge().postResize(height)
 	},

package/src/react/NotionCustomBlock.tsx

@@ -1,4 +1,5 @@
-import { type ReactNode, useEffect, useState } from "react"
+import { type ReactNode, useEffect, useLayoutEffect, useState } from "react"
+import { customBlockHost } from "../bridge/sandboxClient.js"
 import { type InitCustomBlockOptions, NotInIframeError } from "../index.js"
 import { DebugMessageLog } from "./DebugMessageLog.js"
 import { seedStandalonePreviewState } from "./standalonePreview.js"
@@ -24,10 +25,9 @@ export type NotionCustomBlockProps = InitCustomBlockOptions & {
 	 */
 	errorFallback?: ReactNode | ((error: Error) => ReactNode)
 	/**
-	 * Whether the provider should automatically post resize messages so the
-	 * host iframe matches the content height of `#root`. Defaults to `true`.
-	 * Pass `false` when you want to use the default block size and are ok
-	 * with scrollbars within the Notion client.
+	 * Whether to post resize messages after initialization and dynamically resize the block.
+	 *
+	 * @deprecated TODO(custom-blocks): Remove this prop when bumping the SDK version to 0.2.0.
 	 *
 	 * @default true
 	 */
@@ -61,7 +61,8 @@ export function NotionCustomBlock({
 	autoResize = true,
 }: NotionCustomBlockProps) {
 	const init = useCustomBlockInit({ timeoutMs })
-	useCustomBlockAutoResize({ enabled: autoResize })
+	useCustomBlockAutoResize({ enabled: init.isLoaded && autoResize })
+	// True if the block has no host (i.e. it's running in standalone preview).
 	const isStandalone = init.error instanceof NotInIframeError
 	const host = useCustomBlockHost()
 	const [debugOpen, setDebugOpen] = useState(false)
@@ -84,6 +85,15 @@ export function NotionCustomBlock({
 		seedStandalonePreviewState()
 	}, [isStandalone, init.error])
 
+	useLayoutEffect(() => {
+		if (!init.isLoaded || isStandalone) {
+			return
+		}
+		// Send `initResult` *after* React renders the block so the SDK can report its rendered
+		// height to the host as part of the `initResult` message.
+		customBlockHost.completeInitialization()
+	}, [init.isLoaded, isStandalone])
+
 	if (debugOpen) {
 		return <DebugMessageLog />
 	}

package/src/react/useCustomBlockAutoResize.ts

@@ -5,16 +5,12 @@ import { customBlock } from "../index.js"
  * Measures the sandbox's `#root` element and posts `resize` messages so the host iframe
  * matches the block's border-box height. Unchanged values are deduped.
  *
- * `<NotionCustomBlock>` calls this hook for you by default — only reach for it directly
- * when you need to drive `enabled` yourself (e.g. behind a debug toggle). In that case,
- * pass `autoResize={false}` to the provider to avoid running it twice. For full-bleed
- * views that should fill their slot, pass `autoResize={false}` and skip the hook.
+ * `<NotionCustomBlock>` calls this hook for you. Only use it directly in a custom
+ * initialization wrapper that does not render `<NotionCustomBlock>`.
  *
- * @example
- * <NotionCustomBlock autoResize={false}>
- *   <App />
- * </NotionCustomBlock>
+ * @deprecated Use CSS `max-height` and `overflow` to constrain block content instead.
  *
+ * @example
  * function App() {
  *   const [enabled, setEnabled] = useState(true)
  *   useCustomBlockAutoResize({ enabled })