@notionhq/custom-blocks 0.1.45 → 0.1.47

package/docs/users.md

@@ -29,14 +29,15 @@ For non-React renderers, read the same state through `customBlock` after initial
 
 ```ts
 await initCustomBlock()
-const me = customBlock.getCurrentUser()
 
-const unsubscribe = customBlock.subscribe(() => {
-	const nextMe = customBlock.getCurrentUser()
+const unsubscribe = customBlock.subscribeToCurrentUser(nextMe => {
 	// Update your renderer with nextMe.
 })
 ```
 
+Call `unsubscribe()` when your renderer is removed. The callback receives the initial profile and later changes.
+See [context subscriptions](./block-location.md#reading-values-and-following-changes) for initialization and equality rules.
+
 ## Listing users
 
 `users.list(input?)` returns workspace users visible to the current custom block, mirroring Notion's [`GET /v1/users`](https://developers.notion.com/reference/get-users) shape.

package/package.json

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

package/src/bridge/SandboxBridge.ts

@@ -5,7 +5,6 @@ import type {
 	NotionDataSourceBindings,
 } from "@notionhq/custom-blocks-protocol/dataSources/dataSource.js"
 import type { NotionPageId } from "@notionhq/custom-blocks-protocol/ids.js"
-import { readIncomingType } from "@notionhq/custom-blocks-protocol/incomingType.js"
 import type { CustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest.js"
 import type { ConnectMessage } from "@notionhq/custom-blocks-protocol/messages/connect.js"
 import type {
@@ -18,6 +17,7 @@ import {
 	hostToSandboxMessageSchema,
 	type PrimeableHostToSandboxMessage,
 } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
+import { readIncomingType } from "@notionhq/custom-blocks-protocol/messages/incomingType.js"
 import {
 	CustomBlockInitializationError,
 	type InitMessage,
@@ -173,28 +173,8 @@ export class SandboxBridge {
 		return () => this.messageLogListeners.delete(listener)
 	}
 
-	awaitInit(signal?: AbortSignal): Promise<void> {
-		if (!signal) {
-			return this.initMessage
-		}
-		return new Promise((resolve, reject) => {
-			if (signal.aborted) {
-				reject(signal.reason)
-				return
-			}
-			const onAbort = () => reject(signal.reason)
-			signal.addEventListener("abort", onAbort, { once: true })
-			this.initMessage.then(
-				() => {
-					signal.removeEventListener("abort", onAbort)
-					resolve()
-				},
-				err => {
-					signal.removeEventListener("abort", onAbort)
-					reject(err)
-				},
-			)
-		})
+	awaitInit(): Promise<void> {
+		return this.initMessage
 	}
 
 	sendConnect(manifestResult: ManifestLoadResult) {

package/src/bridge/sandboxClient.ts

@@ -42,8 +42,8 @@ export const customBlockHost = {
 		getBridge().sendConnect(manifestResult)
 	},
 
-	awaitInit: (signal?: AbortSignal): Promise<void> => {
-		return getBridge().awaitInit(signal)
+	awaitInit: (): Promise<void> => {
+		return getBridge().awaitInit()
 	},
 
 	subscribe: (listener: () => void) => {

package/src/customBlock.ts

@@ -12,8 +12,10 @@ import type {
 	CustomBlockHostState,
 	InitializedHostState,
 } from "./bridge/hostState.js"
+import { notifyListener } from "./bridge/notifyListener.js"
 import { customBlockHost } from "./bridge/sandboxClient.js"
 
+/** @deprecated Use individual context types and getters after `initCustomBlock` resolves. */
 export type CustomBlockState =
 	| {
 			status: "uninitialized"
@@ -31,47 +33,144 @@ export type CustomBlockState =
 			dataSources: NotionDataSource[]
 	  }
 
+type Unsubscribe = () => void
+
 /**
- * Framework-neutral runtime state APIs for a custom block. Call `initCustomBlock`
- * before reading initialized values, and use `subscribe` to react to host pushes.
+ * Read block and app context with getters, or follow changes with subscriptions.
+ * Getters throw if called before `initCustomBlock()` completes. Subscriptions
+ * can be registered before initialization and deliver the initial value once
+ * initialization completes, followed by changes to that value.
+ *
+ * Each subscription returns an unsubscribe function. Call it when the
+ * subscription is no longer needed.
  */
 export const customBlock = {
-	subscribe(listener: () => void): () => void {
+	/** @deprecated Use an individual subscription method, such as `subscribeToTheme()` or `subscribeToCurrentUser()`. */
+	subscribe(listener: () => void): Unsubscribe {
 		return customBlockHost.subscribe(listener)
 	},
 
+	/** @deprecated Use an individual getter method, such as `getTheme()` or `getCurrentUser()`, after `initCustomBlock()` resolves. */
 	getState(): CustomBlockState {
 		return toPublicState(customBlockHost.getState())
 	},
 
+	/**
+	 * Get the current user viewing the block.
+	 * Throws if called before SDK initialization completes.
+	 */
 	getCurrentUser(): NotionUser {
 		return getInitializedHostState("getCurrentUser").currentUser
 	},
 
+	/**
+	 * Subscribes to the current `currentUser` and future changes.
+	 * Waits for initialization before delivering the initial value.
+	 */
+	subscribeToCurrentUser(listener: (value: NotionUser) => void): Unsubscribe {
+		return subscribeToContext({ key: "currentUser", listener })
+	},
+
+	/**
+	 * Get the host's current theme.
+	 * Throws if called before SDK initialization completes.
+	 */
 	getTheme(): NotionTheme {
 		return getInitializedHostState("getTheme").theme
 	},
 
+	/**
+	 * Subscribes to the current `theme` and future changes.
+	 * Waits for initialization before delivering the initial value.
+	 */
+	subscribeToTheme(listener: (value: NotionTheme) => void): Unsubscribe {
+		return subscribeToContext({ key: "theme", listener })
+	},
+
+	/**
+	 * Get the host's current contrast mode.
+	 * Throws if called before SDK initialization completes.
+	 */
 	getContrastMode(): NotionContrastMode {
 		return getInitializedHostState("getContrastMode").contrastMode
 	},
 
+	/**
+	 * Subscribes to the current `contrastMode` and future changes.
+	 * Waits for initialization before delivering the initial value.
+	 */
+	subscribeToContrastMode(
+		listener: (value: NotionContrastMode) => void,
+	): Unsubscribe {
+		return subscribeToContext({ key: "contrastMode", listener })
+	},
+
+	/**
+	 * Get the custom block's ID. The ID is stable for the lifetime of the block.
+	 * Throws if called before SDK initialization completes.
+	 */
 	getBlockId(): NotionBlockId {
 		return getInitializedHostState("getBlockId").blockId
 	},
 
+	/**
+	 * Delivers the block ID once. The ID is stable for the lifetime of the block.
+	 * Waits for initialization before delivering the initial value.
+	 */
+	subscribeToBlockId(listener: (value: NotionBlockId) => void): Unsubscribe {
+		return subscribeToContext({ key: "blockId", listener })
+	},
+
+	/**
+	 * Get the custom block's parent.
+	 * Throws if called before SDK initialization completes.
+	 */
 	getParent(): NotionParent {
 		return getInitializedHostState("getParent").parent
 	},
 
+	/**
+	 * Subscribes to the current `parent` and future changes.
+	 * Waits for initialization before delivering the initial value.
+	 */
+	subscribeToParent(listener: (value: NotionParent) => void): Unsubscribe {
+		return subscribeToContext({ key: "parent", listener })
+	},
+
+	/**
+	 * Get the containing page and its parent.
+	 * Throws if called before SDK initialization completes.
+	 */
 	getPage(): CustomBlockPage {
 		return getInitializedHostState("getPage").page
 	},
 
+	/**
+	 * Subscribes to the current `page` and future changes.
+	 * Waits for initialization before delivering the initial value.
+	 */
+	subscribeToPage(listener: (value: CustomBlockPage) => void): Unsubscribe {
+		return subscribeToContext({ key: "page", listener })
+	},
+
+	/**
+	 * Get the block's declared data source manifest.
+	 * Throws if called before SDK initialization completes.
+	 */
 	getManifest(): CustomBlockManifest {
 		return getInitializedHostState("getManifest").manifest
 	},
 
+	/**
+	 * Subscribes to the current `manifest` and future changes.
+	 * Waits for initialization before delivering the initial value.
+	 */
+	subscribeToManifest(
+		listener: (value: CustomBlockManifest) => void,
+	): Unsubscribe {
+		return subscribeToContext({ key: "manifest", listener })
+	},
+
 	autoResize,
 
 	/**
@@ -119,3 +218,40 @@ function getInitializedHostState(methodName: string): InitializedHostState {
 	}
 	return hostState
 }
+
+/**
+ * Subscribe to one context value. Wait for initialization before delivering
+ * the initial value, then deliver updates when that value changes.
+ * Return a function that stops delivery, including before initialization.
+ */
+function subscribeToContext<K extends keyof InitializedHostState>(args: {
+	key: K
+	listener: (value: InitializedHostState[K]) => void
+}): Unsubscribe {
+	const { key, listener } = args
+	let active = true
+	let delivered = false
+	let previous: InitializedHostState[K] | undefined
+	const deliverIfChanged = () => {
+		const state = customBlockHost.getState()
+		if (!active || state.status !== "initialized") {
+			return
+		}
+		const next = state[key]
+		// Use referential equality to keep the implementation simple.
+		// Callbacks can receive different objects with the same contents.
+		// We have not benchmarked this choice. Deep equality may also be suitable.
+		if (delivered && Object.is(previous, next)) {
+			return
+		}
+		previous = next
+		delivered = true
+		notifyListener(() => listener(next))
+	}
+	const unsubscribe = customBlockHost.subscribe(deliverIfChanged)
+	deliverIfChanged()
+	return () => {
+		active = false
+		unsubscribe()
+	}
+}

package/src/index.ts

@@ -101,7 +101,6 @@ export { pages, users } from "./bridge/sandboxClient.js"
 export { type CustomBlockState, customBlock } from "./customBlock.js"
 export {
 	type CustomBlockInitPayload,
-	type InitCustomBlockOptions,
 	initCustomBlock,
 	NotInIframeError,
 } from "./init.js"

package/src/init.ts

@@ -42,21 +42,6 @@ export class NotInIframeError extends CustomBlockInitializationError {
 	declare code: "not_in_iframe"
 }
 
-/**
- * Options for {@link initCustomBlock}.
- */
-export type InitCustomBlockOptions = {
-	/**
-	 * How long to wait for the host's `init` response before rejecting with an error.
-	 *
-	 * @default 15000 - Intentionally longer than Notion's 10s host-dependency watchdog
-	 * so host-owned init errors can arrive before the SDK's generic fallback appears.
-	 */
-	timeoutMs?: number
-}
-
-const DEFAULT_INIT_TIMEOUT_MS = 15_000
-
 const NOT_IN_IFRAME_MESSAGE =
 	"<NotionCustomBlock> only works inside an iframe — use the dev shell or deploy to Notion."
 
@@ -69,15 +54,13 @@ let initPromise: Promise<CustomBlockInitPayload> | undefined
  * user, data sources) once the host has initialized the block. Rejects with a
  * `CustomBlockInitializationError` if initialization fails.
  *
- * Idempotent: subsequent calls return the same promise as the first and ignore any new options.
+ * Idempotent: subsequent calls return the same promise as the first.
  * Mount your React tree (or call any SDK hook) only after the returned promise resolves.
  */
-export function initCustomBlock(
-	opts: InitCustomBlockOptions = {},
-): Promise<CustomBlockInitPayload> {
+export function initCustomBlock(): Promise<CustomBlockInitPayload> {
 	if (initPromise === undefined) {
 		customBlockHost.start()
-		initPromise = performHandshake(opts)
+		initPromise = performHandshake()
 	}
 	return initPromise
 }
@@ -93,13 +76,11 @@ export function initCustomBlock(
  * Resolves with the `init` payload after the process above. Rejects with a
  * `CustomBlockInitializationError` if any step fails.
  */
-async function performHandshake(
-	opts: InitCustomBlockOptions,
-): Promise<CustomBlockInitPayload> {
+async function performHandshake(): Promise<CustomBlockInitPayload> {
 	try {
 		// Fail fast with a typed error when rendered as a standalone tab and not in a parent frame.
-		// Otherwise, it would eventually hit the timeout, since `postMessage` to `window.parent`
-		// would just hit the same window and never arrive.
+		// Otherwise, `postMessage` to `window.parent` would just hit the same window and never
+		// arrive.
 		if (typeof window !== "undefined" && window.parent === window) {
 			throw new NotInIframeError()
 		}
@@ -108,8 +89,7 @@ async function performHandshake(
 		const manifestResult = await attemptToLoadSelfHostedManifest()
 		customBlockHost.sendConnect(manifestResult)
 
-		const timeoutMs = opts.timeoutMs ?? DEFAULT_INIT_TIMEOUT_MS
-		await awaitHostInitWithTimeout(timeoutMs)
+		await customBlockHost.awaitInit()
 
 		const hostState = customBlockHost.getState()
 		switch (hostState.status) {
@@ -144,28 +124,3 @@ async function performHandshake(
 		})
 	}
 }
-
-async function awaitHostInitWithTimeout(timeoutMs: number): Promise<void> {
-	try {
-		await customBlockHost.awaitInit(AbortSignal.timeout(timeoutMs))
-	} catch (error) {
-		if (isTimeoutError(error)) {
-			throw new CustomBlockInitializationError({
-				code: "init_timeout",
-				message:
-					"Host did not respond to the `connect` message before the timeout.",
-				isRetryable: true,
-			})
-		}
-		throw error
-	}
-}
-
-function isTimeoutError(error: unknown): boolean {
-	return (
-		typeof error === "object" &&
-		error !== null &&
-		"name" in error &&
-		(error.name === "TimeoutError" || error.name === "AbortError")
-	)
-}

package/src/react/NotionCustomBlock.tsx

@@ -1,7 +1,7 @@
 import type { CustomBlockInitializationError } from "@notionhq/custom-blocks-protocol/messages/init.js"
 import { type ReactNode, useEffect, useLayoutEffect, useState } from "react"
 import { customBlockHost } from "../bridge/sandboxClient.js"
-import { type InitCustomBlockOptions, NotInIframeError } from "../init.js"
+import { NotInIframeError } from "../init.js"
 import { DebugMessageLog } from "./DebugMessageLog.js"
 import { seedStandalonePreviewState } from "./standalonePreview.js"
 import { useCustomBlockAutoResize } from "./useCustomBlockAutoResize.js"
@@ -12,7 +12,7 @@ import "./NotionCustomBlock.css"
 /**
  * Props accepted by {@link NotionCustomBlock}.
  */
-export type NotionCustomBlockProps = InitCustomBlockOptions & {
+export type NotionCustomBlockProps = {
 	children: ReactNode
 	/**
 	 * Rendered while the SDK ↔ host handshake is in progress. Defaults to
@@ -37,8 +37,7 @@ export type NotionCustomBlockProps = InitCustomBlockOptions & {
 
 /**
  * Top-level wrapper that runs the SDK ↔ host handshake and gates `children`
- * until it resolves. Passes `timeoutMs` straight through to
- * {@link initCustomBlock}.
+ * until it resolves.
  *
  * Templates that prefer not to write a `Root` gating component (or top-level
  * `await`) can mount their app entirely inside this provider:
@@ -56,12 +55,11 @@ export type NotionCustomBlockProps = InitCustomBlockOptions & {
  */
 export function NotionCustomBlock({
 	children,
-	timeoutMs,
 	fallback = null,
 	errorFallback,
 	autoResize = true,
 }: NotionCustomBlockProps) {
-	const init = useCustomBlockInit({ timeoutMs })
+	const init = useCustomBlockInit()
 	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

package/src/react/useCustomBlockInit.ts

@@ -1,18 +1,14 @@
 import type { CustomBlockInitializationError } from "@notionhq/custom-blocks-protocol/messages/init.js"
 import { useEffect, useState } from "react"
-import {
-	type CustomBlockInitPayload,
-	type InitCustomBlockOptions,
-	initCustomBlock,
-} from "../init.js"
+import { type CustomBlockInitPayload, initCustomBlock } from "../init.js"
 
 /**
  * Discriminated state returned by {@link useCustomBlockInit}.
  *
  * Branch on `isLoaded`/`error`:
  * - `{ isLoaded: false, error: undefined }` — handshake in progress.
- * - `{ isLoaded: false, error: CustomBlockInitializationError }` — handshake failed (most commonly a
- *   `CustomBlockInitializationError` with code `init_timeout` because the host never sent `init`).
+ * - `{ isLoaded: false, error: CustomBlockInitializationError }` — handshake failed because
+ *   the host or SDK reported a terminal initialization error.
  * - `{ isLoaded: true, initial }` — handshake complete; safe to render
  *   children that call `useTheme`, `useBlockId`, etc.
  */
@@ -38,17 +34,14 @@ export type UseCustomBlockInitResult =
  *   return <App />
  * }
  */
-export function useCustomBlockInit(
-	opts?: InitCustomBlockOptions,
-): UseCustomBlockInitResult {
+export function useCustomBlockInit(): UseCustomBlockInitResult {
 	const [state, setState] = useState<UseCustomBlockInitResult>({
 		isLoaded: false,
 		error: undefined,
 	})
-	// biome-ignore lint/correctness/useExhaustiveDependencies(opts): Initialization caches its first options and promise. Later options are ignored, so changes should not resubscribe to the same promise.
 	useEffect(() => {
 		let cancelled = false
-		initCustomBlock(opts).then(
+		initCustomBlock().then(
 			initial => {
 				if (!cancelled) {
 					setState({ isLoaded: true, error: undefined, initial })

package/src/react/useRuntimeState.ts

@@ -17,7 +17,10 @@ import { customBlock } from "../customBlock.js"
  * const blockId = useBlockId()
  */
 export function useBlockId(): NotionBlockId {
-	return useSyncExternalStore(customBlock.subscribe, customBlock.getBlockId)
+	return useSyncExternalStore(
+		customBlock.subscribeToBlockId,
+		customBlock.getBlockId,
+	)
 }
 
 /**
@@ -30,7 +33,10 @@ export function useBlockId(): NotionBlockId {
  * const parent = useParent()
  */
 export function useParent(): NotionParent {
-	return useSyncExternalStore(customBlock.subscribe, customBlock.getParent)
+	return useSyncExternalStore(
+		customBlock.subscribeToParent,
+		customBlock.getParent,
+	)
 }
 
 /**
@@ -43,11 +49,11 @@ export function useParent(): NotionParent {
  * const page = usePage()
  */
 export function usePage(): CustomBlockPage {
-	return useSyncExternalStore(customBlock.subscribe, customBlock.getPage)
+	return useSyncExternalStore(customBlock.subscribeToPage, customBlock.getPage)
 }
 
 /**
- * Returns the host's current theme. Re-renders on every `themeChanged` message from the host.
+ * Returns the host's current theme. Re-renders when the theme changes.
  *
  * Throws if called before `initCustomBlock` has resolved.
  *
@@ -55,12 +61,14 @@ export function usePage(): CustomBlockPage {
  * const theme = useTheme()
  */
 export function useTheme(): NotionTheme {
-	return useSyncExternalStore(customBlock.subscribe, customBlock.getTheme)
+	return useSyncExternalStore(
+		customBlock.subscribeToTheme,
+		customBlock.getTheme,
+	)
 }
 
 /**
- * Returns the host's contrast preference. Re-renders on every protocol-v3
- * `contrastModeChanged` message from the host.
+ * Returns the host's contrast preference. Re-renders when the contrast preference changes.
  *
  * Throws if called before `initCustomBlock` has resolved.
  *
@@ -69,14 +77,13 @@ export function useTheme(): NotionTheme {
  */
 export function useContrastMode(): NotionContrastMode {
 	return useSyncExternalStore(
-		customBlock.subscribe,
+		customBlock.subscribeToContrastMode,
 		customBlock.getContrastMode,
 	)
 }
 
 /**
- * Returns the viewing user's Notion profile. Re-renders whenever the host sends a
- * `currentUserChanged` message.
+ * Returns the viewing user's Notion profile. Re-renders when the profile data changes.
  *
  * Throws if called before `initCustomBlock` has resolved. `await` it before mounting.
  *
@@ -85,7 +92,10 @@ export function useContrastMode(): NotionContrastMode {
  * console.log(me.id, me.name, me.person.email)
  */
 export function useCurrentUser(): NotionUser {
-	return useSyncExternalStore(customBlock.subscribe, customBlock.getCurrentUser)
+	return useSyncExternalStore(
+		customBlock.subscribeToCurrentUser,
+		customBlock.getCurrentUser,
+	)
 }
 
 /**
@@ -101,5 +111,8 @@ export function useCurrentUser(): NotionUser {
  * resolved property IDs and schemas.
  */
 export function useManifest(): CustomBlockManifest {
-	return useSyncExternalStore(customBlock.subscribe, customBlock.getManifest)
+	return useSyncExternalStore(
+		customBlock.subscribeToManifest,
+		customBlock.getManifest,
+	)
 }

package/src/types.ts

@@ -5,7 +5,6 @@ import type {
 	NotionDataSourceId,
 	NotionPageId,
 } from "@notionhq/custom-blocks-protocol/ids.js"
-import type { BridgeMessagePayload } from "@notionhq/custom-blocks-protocol/messagePayload.js"
 import type { NotionCreatePagePosition } from "@notionhq/custom-blocks-protocol/messages/createPage.js"
 import type {
 	CreatePageResultMessage,
@@ -24,6 +23,7 @@ import type {
 	ListUsersMessage,
 	ListUsersResultMessage,
 } from "@notionhq/custom-blocks-protocol/messages/listUsers.js"
+import type { BridgeMessagePayload } from "@notionhq/custom-blocks-protocol/messages/messagePayload.js"
 import type {
 	CustomBlockCheckboxFilterOperator,
 	CustomBlockContainsFilterOperator,