@notionhq/custom-blocks 0.1.46 → 0.1.47

package/README.md

@@ -113,10 +113,9 @@ Hosts that omit a contrast mode use standard contrast.
 
 `NotionTokenScopeProps` has one required `children` prop.
 
-The CSS variables apply within the scope, not globally.
-Place portal containers inside `<NotionTokenScope>`, or wrap the portal content in another `<NotionTokenScope>`.
-Framework-neutral renderers can read the current appearance with `customBlock.getTheme()` and `customBlock.getContrastMode()`.
-See [Block location and appearance](./docs/block-location.md).
+CSS variables apply only within `<NotionTokenScope>`. Place portal containers inside that scope, or wrap the portal content in another `<NotionTokenScope>`.
+
+Outside React, use `customBlock.getTheme()` and `customBlock.getContrastMode()` to read the current appearance, or `customBlock.subscribeToTheme()` and `customBlock.subscribeToContrastMode()` to follow changes. See [Block location and appearance](./docs/block-location.md) for details.
 
 ## Reference
 

package/dist/customBlock.d.ts

@@ -8,6 +8,7 @@ import type { NotionTheme } from "./protocol/theme.js";
 import type { NotionUser } from "./protocol/users/user.js";
 import { autoResize } from "./autoResize.js";
 import { subscribeToDataSource } from "./bridge/dataSources/subscribe.js";
+/** @deprecated Use individual context types and getters after `initCustomBlock` resolves. */
 export type CustomBlockState = {
     status: "uninitialized";
     theme: NotionTheme;
@@ -22,20 +23,91 @@ export type CustomBlockState = {
     currentUser: NotionUser;
     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 declare const customBlock: {
-    subscribe(listener: () => void): () => void;
+    /** @deprecated Use an individual subscription method, such as `subscribeToTheme()` or `subscribeToCurrentUser()`. */
+    subscribe(listener: () => void): Unsubscribe;
+    /** @deprecated Use an individual getter method, such as `getTheme()` or `getCurrentUser()`, after `initCustomBlock()` resolves. */
     getState(): CustomBlockState;
+    /**
+     * Get the current user viewing the block.
+     * Throws if called before SDK initialization completes.
+     */
     getCurrentUser(): NotionUser;
+    /**
+     * Subscribes to the current `currentUser` and future changes.
+     * Waits for initialization before delivering the initial value.
+     */
+    subscribeToCurrentUser(listener: (value: NotionUser) => void): Unsubscribe;
+    /**
+     * Get the host's current theme.
+     * Throws if called before SDK initialization completes.
+     */
     getTheme(): NotionTheme;
+    /**
+     * Subscribes to the current `theme` and future changes.
+     * Waits for initialization before delivering the initial value.
+     */
+    subscribeToTheme(listener: (value: NotionTheme) => void): Unsubscribe;
+    /**
+     * Get the host's current contrast mode.
+     * Throws if called before SDK initialization completes.
+     */
     getContrastMode(): NotionContrastMode;
+    /**
+     * Subscribes to the current `contrastMode` and future changes.
+     * Waits for initialization before delivering the initial value.
+     */
+    subscribeToContrastMode(listener: (value: NotionContrastMode) => void): Unsubscribe;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Get the custom block's parent.
+     * Throws if called before SDK initialization completes.
+     */
     getParent(): NotionParent;
+    /**
+     * Subscribes to the current `parent` and future changes.
+     * Waits for initialization before delivering the initial value.
+     */
+    subscribeToParent(listener: (value: NotionParent) => void): Unsubscribe;
+    /**
+     * Get the containing page and its parent.
+     * Throws if called before SDK initialization completes.
+     */
     getPage(): CustomBlockPage;
+    /**
+     * Subscribes to the current `page` and future changes.
+     * Waits for initialization before delivering the initial value.
+     */
+    subscribeToPage(listener: (value: CustomBlockPage) => void): Unsubscribe;
+    /**
+     * Get the block's declared data source manifest.
+     * Throws if called before SDK initialization completes.
+     */
     getManifest(): CustomBlockManifest;
+    /**
+     * Subscribes to the current `manifest` and future changes.
+     * Waits for initialization before delivering the initial value.
+     */
+    subscribeToManifest(listener: (value: CustomBlockManifest) => void): Unsubscribe;
     autoResize: typeof autoResize;
     /**
      * Registers a listener that receives the current query snapshot and later updates.
@@ -43,4 +115,5 @@ export declare const customBlock: {
      */
     subscribeToDataSource: typeof subscribeToDataSource;
 };
+export {};
 //# sourceMappingURL=customBlock.d.ts.map

package/dist/customBlock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"customBlock.d.ts","sourceRoot":"","sources":["../src/customBlock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAA;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4DAA4D,CAAA;AAClG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AACvF,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,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAA;AAOzE,MAAM,MAAM,gBAAgB,GACzB;IACA,MAAM,EAAE,eAAe,CAAA;IACvB,KAAK,EAAE,WAAW,CAAA;IAClB,YAAY,EAAE,kBAAkB,CAAA;CAC/B,GACD;IACA,MAAM,EAAE,aAAa,CAAA;IACrB,KAAK,EAAE,WAAW,CAAA;IAClB,YAAY,EAAE,kBAAkB,CAAA;IAChC,OAAO,EAAE,aAAa,CAAA;IACtB,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,eAAe,CAAA;IACrB,WAAW,EAAE,UAAU,CAAA;IACvB,WAAW,EAAE,gBAAgB,EAAE,CAAA;CAC9B,CAAA;AAEJ;;;GAGG;AACH,eAAO,MAAM,WAAW;wBACH,MAAM,IAAI,GAAG,MAAM,IAAI;gBAI/B,gBAAgB;sBAIV,UAAU;gBAIhB,WAAW;uBAIJ,kBAAkB;kBAIvB,aAAa;iBAId,YAAY;eAId,eAAe;mBAIX,mBAAmB;;IAMlC;;;OAGG;;CAEH,CAAA"}
+{"version":3,"file":"customBlock.d.ts","sourceRoot":"","sources":["../src/customBlock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAA;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4DAA4D,CAAA;AAClG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AACvF,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,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAA;AAQzE,6FAA6F;AAC7F,MAAM,MAAM,gBAAgB,GACzB;IACA,MAAM,EAAE,eAAe,CAAA;IACvB,KAAK,EAAE,WAAW,CAAA;IAClB,YAAY,EAAE,kBAAkB,CAAA;CAC/B,GACD;IACA,MAAM,EAAE,aAAa,CAAA;IACrB,KAAK,EAAE,WAAW,CAAA;IAClB,YAAY,EAAE,kBAAkB,CAAA;IAChC,OAAO,EAAE,aAAa,CAAA;IACtB,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,eAAe,CAAA;IACrB,WAAW,EAAE,UAAU,CAAA;IACvB,WAAW,EAAE,gBAAgB,EAAE,CAAA;CAC9B,CAAA;AAEJ,KAAK,WAAW,GAAG,MAAM,IAAI,CAAA;AAE7B;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW;IACvB,qHAAqH;wBACjG,MAAM,IAAI,GAAG,WAAW;IAI5C,mIAAmI;gBACvH,gBAAgB;IAI5B;;;OAGG;sBACe,UAAU;IAI5B;;;OAGG;qCAC8B,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,WAAW;IAI1E;;;OAGG;gBACS,WAAW;IAIvB;;;OAGG;+BACwB,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,WAAW;IAIrE;;;OAGG;uBACgB,kBAAkB;IAIrC;;;OAGG;sCAEQ,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAC3C,WAAW;IAId;;;OAGG;kBACW,aAAa;IAI3B;;;OAGG;iCAC0B,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,WAAW;IAIzE;;;OAGG;iBACU,YAAY;IAIzB;;;OAGG;gCACyB,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,WAAW;IAIvE;;;OAGG;eACQ,eAAe;IAI1B;;;OAGG;8BACuB,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAAG,WAAW;IAIxE;;;OAGG;mBACY,mBAAmB;IAIlC;;;OAGG;kCAEQ,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAC5C,WAAW;;IAMd;;;OAGG;;CAEH,CAAA"}

package/dist/customBlock.js

@@ -1,38 +1,123 @@
 import { autoResize } from "./autoResize.js";
 import { subscribeToDataSource } from "./bridge/dataSources/subscribe.js";
+import { notifyListener } from "./bridge/notifyListener.js";
 import { customBlockHost } from "./bridge/sandboxClient.js";
 /**
- * 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 = {
+    /** @deprecated Use an individual subscription method, such as `subscribeToTheme()` or `subscribeToCurrentUser()`. */
     subscribe(listener) {
         return customBlockHost.subscribe(listener);
     },
+    /** @deprecated Use an individual getter method, such as `getTheme()` or `getCurrentUser()`, after `initCustomBlock()` resolves. */
     getState() {
         return toPublicState(customBlockHost.getState());
     },
+    /**
+     * Get the current user viewing the block.
+     * Throws if called before SDK initialization completes.
+     */
     getCurrentUser() {
         return getInitializedHostState("getCurrentUser").currentUser;
     },
+    /**
+     * Subscribes to the current `currentUser` and future changes.
+     * Waits for initialization before delivering the initial value.
+     */
+    subscribeToCurrentUser(listener) {
+        return subscribeToContext({ key: "currentUser", listener });
+    },
+    /**
+     * Get the host's current theme.
+     * Throws if called before SDK initialization completes.
+     */
     getTheme() {
         return getInitializedHostState("getTheme").theme;
     },
+    /**
+     * Subscribes to the current `theme` and future changes.
+     * Waits for initialization before delivering the initial value.
+     */
+    subscribeToTheme(listener) {
+        return subscribeToContext({ key: "theme", listener });
+    },
+    /**
+     * Get the host's current contrast mode.
+     * Throws if called before SDK initialization completes.
+     */
     getContrastMode() {
         return getInitializedHostState("getContrastMode").contrastMode;
     },
+    /**
+     * Subscribes to the current `contrastMode` and future changes.
+     * Waits for initialization before delivering the initial value.
+     */
+    subscribeToContrastMode(listener) {
+        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() {
         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) {
+        return subscribeToContext({ key: "blockId", listener });
+    },
+    /**
+     * Get the custom block's parent.
+     * Throws if called before SDK initialization completes.
+     */
     getParent() {
         return getInitializedHostState("getParent").parent;
     },
+    /**
+     * Subscribes to the current `parent` and future changes.
+     * Waits for initialization before delivering the initial value.
+     */
+    subscribeToParent(listener) {
+        return subscribeToContext({ key: "parent", listener });
+    },
+    /**
+     * Get the containing page and its parent.
+     * Throws if called before SDK initialization completes.
+     */
     getPage() {
         return getInitializedHostState("getPage").page;
     },
+    /**
+     * Subscribes to the current `page` and future changes.
+     * Waits for initialization before delivering the initial value.
+     */
+    subscribeToPage(listener) {
+        return subscribeToContext({ key: "page", listener });
+    },
+    /**
+     * Get the block's declared data source manifest.
+     * Throws if called before SDK initialization completes.
+     */
     getManifest() {
         return getInitializedHostState("getManifest").manifest;
     },
+    /**
+     * Subscribes to the current `manifest` and future changes.
+     * Waits for initialization before delivering the initial value.
+     */
+    subscribeToManifest(listener) {
+        return subscribeToContext({ key: "manifest", listener });
+    },
     autoResize,
     /**
      * Registers a listener that receives the current query snapshot and later updates.
@@ -74,3 +159,36 @@ function getInitializedHostState(methodName) {
     }
     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(args) {
+    const { key, listener } = args;
+    let active = true;
+    let delivered = false;
+    let previous;
+    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/dist/react/useRuntimeState.d.ts

@@ -35,7 +35,7 @@ export declare function useParent(): NotionParent;
  */
 export declare function usePage(): CustomBlockPage;
 /**
- * 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.
  *
@@ -44,8 +44,7 @@ export declare function usePage(): CustomBlockPage;
  */
 export declare function useTheme(): NotionTheme;
 /**
- * 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.
  *
@@ -54,8 +53,7 @@ export declare function useTheme(): NotionTheme;
  */
 export declare function useContrastMode(): NotionContrastMode;
 /**
- * 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.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"useRuntimeState.d.ts","sourceRoot":"","sources":["../../src/react/useRuntimeState.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,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;AAIhF;;;;;;;GAOG;AACH,wBAAgB,UAAU,IAAI,aAAa,CAE1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,IAAI,YAAY,CAExC;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,IAAI,eAAe,CAEzC;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,IAAI,WAAW,CAEtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,kBAAkB,CAKpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAE3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,IAAI,mBAAmB,CAEjD"}
+{"version":3,"file":"useRuntimeState.d.ts","sourceRoot":"","sources":["../../src/react/useRuntimeState.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,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;AAIhF;;;;;;;GAOG;AACH,wBAAgB,UAAU,IAAI,aAAa,CAK1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,IAAI,YAAY,CAKxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,IAAI,eAAe,CAEzC;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,IAAI,WAAW,CAKtC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,kBAAkB,CAKpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAK3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,IAAI,mBAAmB,CAKjD"}

package/dist/react/useRuntimeState.js

@@ -9,7 +9,7 @@ import { customBlock } from "../customBlock.js";
  * const blockId = useBlockId()
  */
 export function useBlockId() {
-    return useSyncExternalStore(customBlock.subscribe, customBlock.getBlockId);
+    return useSyncExternalStore(customBlock.subscribeToBlockId, customBlock.getBlockId);
 }
 /**
  * Returns the block's parent in the document tree. Re-renders when the host sends
@@ -21,7 +21,7 @@ export function useBlockId() {
  * const parent = useParent()
  */
 export function useParent() {
-    return useSyncExternalStore(customBlock.subscribe, customBlock.getParent);
+    return useSyncExternalStore(customBlock.subscribeToParent, customBlock.getParent);
 }
 /**
  * Returns the nearest enclosing page ancestor. Re-renders when the host sends
@@ -33,10 +33,10 @@ export function useParent() {
  * const page = usePage()
  */
 export function usePage() {
-    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.
  *
@@ -44,11 +44,10 @@ export function usePage() {
  * const theme = useTheme()
  */
 export function useTheme() {
-    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.
  *
@@ -56,11 +55,10 @@ export function useTheme() {
  * const contrastMode = useContrastMode()
  */
 export function useContrastMode() {
-    return useSyncExternalStore(customBlock.subscribe, customBlock.getContrastMode);
+    return useSyncExternalStore(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.
  *
@@ -69,7 +67,7 @@ export function useContrastMode() {
  * console.log(me.id, me.name, me.person.email)
  */
 export function useCurrentUser() {
-    return useSyncExternalStore(customBlock.subscribe, customBlock.getCurrentUser);
+    return useSyncExternalStore(customBlock.subscribeToCurrentUser, customBlock.getCurrentUser);
 }
 /**
  * Returns the manifest that the block declared and the host provided during initialization.
@@ -84,5 +82,5 @@ export function useCurrentUser() {
  * resolved property IDs and schemas.
  */
 export function useManifest() {
-    return useSyncExternalStore(customBlock.subscribe, customBlock.getManifest);
+    return useSyncExternalStore(customBlock.subscribeToManifest, customBlock.getManifest);
 }

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.46"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.47"

package/docs/block-location.md

@@ -1,38 +1,59 @@
-# Block Location & Appearance
+# Block location and appearance
 
-Every custom block runs inside a larger Notion document. These hooks expose the block's own ID, the container it sits inside, the nearest enclosing page ID, and the host's resolved display and contrast modes.
+Block and app context describes where the block runs and the host's appearance. Use getters for current values, subscriptions for initial values and later changes, or React hooks in components.
 
-## API
+## API overview
 
-The host bridge carries these values as explicit `blockId`, `parent`, and `page` fields.
+Import `customBlock` from `@notionhq/custom-blocks` for getters and subscriptions. Import React hooks from `@notionhq/custom-blocks/react`.
 
-### `useBlockId()`
+The getter and subscription names below are methods on `customBlock`.
 
-Returns the custom block's own ID.
+| Context | Getter | Subscription | React hook |
+| --- | --- | --- | --- |
+| Current user | `getCurrentUser()` | `subscribeToCurrentUser(callback)` | `useCurrentUser()` |
+| Custom block ID | `getBlockId()` | `subscribeToBlockId(callback)` | `useBlockId()` |
+| Parent | `getParent()` | `subscribeToParent(callback)` | `useParent()` |
+| Containing page | `getPage()` | `subscribeToPage(callback)` | `usePage()` |
+| Theme | `getTheme()` | `subscribeToTheme(callback)` | `useTheme()` |
+| Contrast mode | `getContrastMode()` | `subscribeToContrastMode(callback)` | `useContrastMode()` |
+| Manifest | `getManifest()` | `subscribeToManifest(callback)` | `useManifest()` |
 
-Re-renders when the host sends a block location update.
+## Reading values and following changes
 
-```ts
-function useBlockId(): NotionBlockId;
-```
+Getters return the current value and throw before initialization completes. In React, call context hooks inside `NotionCustomBlock`, which waits for initialization before rendering its children.
 
-For non-React renderers, use `customBlock.getBlockId()` after `initCustomBlock()` resolves:
+Subscriptions can register before initialization. They wait for initialization before delivering the initial value, or deliver immediately if initialization is complete. Start initialization with `initCustomBlock()` or `NotionCustomBlock`. Subscriptions do not start it themselves. These initialization APIs also report failures. Each subscription returns an unsubscribe function. Repeated cleanup calls have no effect.
+
+After initial delivery, subscriptions compare values with `Object.is`. Objects use referential equality: a new reference triggers a callback even if its contents are unchanged. Updates to other context values do not trigger the callback. React hooks follow the same comparison rules.
 
 ```ts
-await initCustomBlock();
+import { customBlock, initCustomBlock } from "@notionhq/custom-blocks"
+
+const unsubscribe = customBlock.subscribeToTheme(theme => {
+  console.log(theme) // Initial theme, then later changes.
+})
 
-const blockId = customBlock.getBlockId();
+await initCustomBlock()
+console.log(customBlock.getTheme()) // Read the current theme once.
+
+// Call unsubscribe() when the view is removed.
 ```
 
-### `useParent()`
+## Current user
 
-Returns the block's parent in the document tree.
+Use `getCurrentUser()`, `subscribeToCurrentUser()`, and `useCurrentUser()` to access the viewing user's `NotionUser`. See [users](./users.md#reading-the-current-user) for profile fields and user APIs.
 
-Re-renders when the host sends a block location update.
+## Custom block ID
 
-```ts
-function useParent(): NotionParent;
+Use `getBlockId()`, `subscribeToBlockId()`, and `useBlockId()` to access the custom block's own `NotionBlockId`.
+
+The ID is stable for the lifetime of the block. Each subscription delivers once, unless cancelled before initialization. You can register before initialization without an error.
 
+## Parent
+
+Use `getParent()`, `subscribeToParent()`, and `useParent()` to access the block's `NotionParent` in the document tree. For a custom collection view, the parent identifies the data source associated with the view.
+
+```ts
 type NotionParent =
   | { type: "page_id"; page_id: string } // inline custom block under a page
   | { type: "block_id"; block_id: NotionBlockId } // inline custom block under a toggle/column/callout/...
@@ -42,8 +63,6 @@ type NotionParent =
   | { type: "unavailable" }; // access denied; no parent ID or kind
 ```
 
-For non-React renderers, use `customBlock.getParent()` after `initCustomBlock()` resolves.
-
 To identify custom blocks in agent-owned instruction content:
 
 ```tsx
@@ -60,15 +79,11 @@ export function AgentInstructionBadge() {
 }
 ```
 
-### `usePage()`
-
-Returns the nearest enclosing `page` / `collection_view_page` ancestor.
+## Containing page
 
-Re-renders when the host sends a block location update — including when the containing page itself moves (its `parent` changes) without the page ID changing.
+Use `getPage()`, `subscribeToPage()`, and `usePage()` to access the nearest enclosing page or collection view page. The page's parent can change even when its ID stays the same.
 
 ```ts
-function usePage(): CustomBlockPage;
-
 type CustomBlockPage = {
   id: NotionPageId;
   parent: NotionParent; // the containing page's own parent
@@ -77,15 +92,10 @@ type CustomBlockPage = {
 
 `page.parent` allows determining if the custom block is in a freestanding page or part of a database. Don't confuse it with `useParent()`, which is the custom block's own parent.
 
-```tsx
-const page = usePage();
-const isInsideDatabaseRow = page.parent.type === "data_source_id";
-```
+A containing page whose parent has `type: "data_source_id"` belongs to a data source.
 
 For anything beyond location — title, icon, properties — fetch the page through the pages API: `pages.get(page.id)`.
 
-For non-React renderers, use `customBlock.getPage()` after `initCustomBlock()` resolves.
-
 When the viewer cannot access the parent resource, the host returns
 `{ type: "unavailable" }`, including on `usePage().parent`. This applies to every
 parent kind, including data sources, even when the readable child identifies
@@ -97,25 +107,13 @@ Treat `unavailable` as unknown when branching on location: it does not establish
 whether the containing page is a database row. A parent that is still loading
 is not reported as access denied.
 
-### `useTheme()`
-
-Returns the host's current theme.
+## Theme and contrast
 
-Re-renders on every `themeChanged` message.
-
-```ts
-function useTheme(): NotionTheme; // "light" | "dark"
-```
+Use design tokens to style the block. When your code needs the current appearance, use a getter, subscription, or React hook from the [API overview](#api-overview).
 
-The bundled Notion design-token stylesheet maps this value to `data-display-mode`, not `data-theme`; `data-theme` selects content color palettes such as `blue`, `red`, and `gray`.
+`NotionTheme` is `"light"` or `"dark"`. `NotionContrastMode` is `"standard"` or `"high"`. Hosts that omit a contrast mode use `"standard"`.
 
-For non-React renderers, use `customBlock.getTheme()`:
-
-```ts
-await initCustomBlock();
-
-const theme = customBlock.getTheme();
-```
+Getters read the current value after initialization. Subscriptions can register earlier. They deliver the initial value once initialized, then later changes. React hooks keep components current when called inside `NotionCustomBlock`.
 
 ```tsx
 import { usePage, useTheme } from "@notionhq/custom-blocks/react";
@@ -127,14 +125,12 @@ export function Header() {
 }
 ```
 
-### `useContrastMode()`
+For styling, `NotionTokenScope` applies theme and contrast mode to the bundled Notion CSS variables automatically. The stylesheet uses `data-display-mode` for light and dark mode. The separate `data-theme` attribute selects content color palettes such as `blue`, `red`, and `gray`.
 
-Returns the host's resolved contrast mode. Hosts that omit it during initialization default to `"standard"`; later changes arrive through `contrastModeChanged`.
+See [Reading values and following changes](#reading-values-and-following-changes) for a getter and subscription example, including cleanup.
 
-```ts
-function useContrastMode(): NotionContrastMode; // "standard" | "high"
-```
+## Manifest
 
-For non-React renderers, use `customBlock.getContrastMode()` after `initCustomBlock()` resolves.
+Use `getManifest()`, `subscribeToManifest()`, and `useManifest()` to access the declared `CustomBlockManifest`. The manifest stays fixed for the lifetime of the running block, so each subscription delivers it once. You can register before initialization without an error.
 
-For React apps, `<NotionTokenScope>` applies both appearance values to the bundled Notion CSS variables automatically.
+See [data sources](./data-sources.md) for manifest details and `subscribeToDataSource()` for query snapshots.

package/docs/data-sources.md

@@ -60,8 +60,6 @@ const unsubscribe = customBlock.subscribeToDataSource({
   },
 });
 
-// When the renderer unmounts:
-unsubscribe();
 ```
 
 To change the query or request more rows, unsubscribe and create a new subscription with different options.
@@ -235,7 +233,9 @@ Returns the block manifest received from the host during initialization. The man
 function customBlock.getManifest(): CustomBlockManifest;
 ```
 
-Framework-neutral getter for the same manifest returned by `useManifest()`. The manifest is static for the lifetime of the sandbox, so there is nothing to subscribe to.
+Framework-neutral getter for the same manifest returned by `useManifest()`.
+`customBlock.subscribeToManifest(callback)` follows the [context subscription contract](./block-location.md#reading-values-and-following-changes).
+The manifest stays fixed for the lifetime of the running block, so each subscription delivers it once. You can register before initialization without an error.
 
 ## Example: querying a data source
 

package/docs/lifecycle.md

@@ -143,20 +143,61 @@ All code types are open string unions, so keep a default branch. Use `isRetryabl
 
 ### `customBlock`
 
-Framework-neutral runtime APIs for renderers that do not use React hooks. `customBlock.getState()` returns a `CustomBlockState` snapshot that includes `theme` and `contrastMode` while hiding internal query cache details. All getters that read host state — `getTheme`, `getContrastMode`, `getBlockId`, `getParent`, `getPage`, `getCurrentUser`, and `getManifest` — throw until `initCustomBlock()` resolves. `getManifest()` then returns the authoritative manifest supplied by the host.
+The SDK provides getters, subscriptions, and React hooks for block and app context. Use `customBlock` for getters and subscriptions.
 
-`customBlock` covers runtime state, live data source snapshots, and sizing. Imperative APIs such as `pages.*` and `users.*` are also framework-neutral functions.
+#### Getter
+
+Getters return the current value, such as the theme, current user, or containing page. They throw if called before initialization completes.
 
 ```ts
-await initCustomBlock();
+import { customBlock, initCustomBlock } from "@notionhq/custom-blocks"
 
-const theme = customBlock.getTheme();
-const contrastMode = customBlock.getContrastMode();
-const unsubscribe = customBlock.subscribe(() => {
-  render(customBlock.getState());
-});
+await initCustomBlock()
+const theme = customBlock.getTheme()
+console.log(theme)
+```
+
+#### Subscription
+
+Subscriptions deliver the initial value and later changes. You can register them before initialization. They wait for initialization before delivering the initial value, or deliver immediately if initialization is complete.
+
+```ts
+import { customBlock, initCustomBlock } from "@notionhq/custom-blocks"
+
+const unsubscribe = customBlock.subscribeToTheme(theme => {
+  console.log(theme)
+})
+
+await initCustomBlock()
+
+// Call unsubscribe() when the view is removed to stop future callbacks.
 ```
 
+#### React hook
+
+In React, use context hooks inside `NotionCustomBlock`. The wrapper waits for initialization, and the hooks keep components current as values change. React handles subscription cleanup when the component unmounts.
+
+```tsx
+import { NotionCustomBlock, useTheme } from "@notionhq/custom-blocks/react"
+
+export function App() {
+  return (
+    <NotionCustomBlock>
+      <ThemeLabel />
+    </NotionCustomBlock>
+  )
+}
+
+function ThemeLabel() {
+  const theme = useTheme()
+  return <p>Current theme: {theme}</p>
+}
+```
+
+See [Block location and appearance](./block-location.md#reading-values-and-following-changes) for the available getters, subscriptions, and React hooks.
+
+### `customBlock.autoResize()`
+
 For non-React auto-resize, pass the element whose content height should drive the host iframe. The helper posts one initial measurement, observes later size changes when `ResizeObserver` is available, dedupes unchanged heights, and returns a cleanup function:
 
 ```ts
@@ -164,8 +205,7 @@ const stopAutoResize = customBlock.autoResize({
   target: document.getElementById("root"),
 });
 
-// Later, if your renderer unmounts:
-stopAutoResize();
+// Call stopAutoResize() when your renderer is removed.
 ```
 
 ### `NotInIframeError`

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.46",
+	"version": "0.1.47",
 	"license": "MIT",
 	"type": "module",
 	"publishConfig": {

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/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,
+	)
 }