@notionhq/custom-blocks 0.1.45 → 0.1.47

package/dist/react/NotionCustomBlock.d.ts

@@ -1,10 +1,9 @@
 import { type ReactNode } from "react";
-import { type InitCustomBlockOptions } from "../init.js";
 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
@@ -28,8 +27,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:
@@ -45,5 +43,5 @@ export type NotionCustomBlockProps = InitCustomBlockOptions & {
  * Inside `children`, every SDK hook is guaranteed to return a populated
  * value. Outside the provider (or during the loading window), they throw.
  */
-export declare function NotionCustomBlock({ children, timeoutMs, fallback, errorFallback, autoResize, }: NotionCustomBlockProps): import("react").JSX.Element;
+export declare function NotionCustomBlock({ children, fallback, errorFallback, autoResize, }: NotionCustomBlockProps): import("react").JSX.Element;
 //# sourceMappingURL=NotionCustomBlock.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"NotionCustomBlock.d.ts","sourceRoot":"","sources":["../../src/react/NotionCustomBlock.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,SAAS,EAAwC,MAAM,OAAO,CAAA;AAE5E,OAAO,EAAE,KAAK,sBAAsB,EAAoB,MAAM,YAAY,CAAA;AAM1E,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,+BAsExB"}
+{"version":3,"file":"NotionCustomBlock.d.ts","sourceRoot":"","sources":["../../src/react/NotionCustomBlock.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,SAAS,EAAwC,MAAM,OAAO,CAAA;AAQ5E,OAAO,yBAAyB,CAAA;AAEhC;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACpC,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;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,EACjC,QAAQ,EACR,QAAe,EACf,aAAa,EACb,UAAiB,GACjB,EAAE,sBAAsB,+BAsExB"}

package/dist/react/NotionCustomBlock.js

@@ -10,8 +10,7 @@ import { useCustomBlockHost } from "./useHostState.js";
 import "./NotionCustomBlock.css";
 /**
  * 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:
@@ -27,8 +26,8 @@ import "./NotionCustomBlock.css";
  * Inside `children`, every SDK hook is guaranteed to return a populated
  * value. Outside the provider (or during the loading window), they throw.
  */
-export function NotionCustomBlock({ children, timeoutMs, fallback = null, errorFallback, autoResize = true, }) {
-    const init = useCustomBlockInit({ timeoutMs });
+export function NotionCustomBlock({ children, fallback = null, errorFallback, autoResize = true, }) {
+    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/dist/react/useCustomBlockInit.d.ts

@@ -1,12 +1,12 @@
 import type { CustomBlockInitializationError } from "../protocol/messages/init.js";
-import { type CustomBlockInitPayload, type InitCustomBlockOptions } from "../init.js";
+import { type CustomBlockInitPayload } 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,5 +38,5 @@ export type UseCustomBlockInitResult = {
  *   return <App />
  * }
  */
-export declare function useCustomBlockInit(opts?: InitCustomBlockOptions): UseCustomBlockInitResult;
+export declare function useCustomBlockInit(): UseCustomBlockInitResult;
 //# sourceMappingURL=useCustomBlockInit.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useCustomBlockInit.d.ts","sourceRoot":"","sources":["../../src/react/useCustomBlockInit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,mDAAmD,CAAA;AAEvG,OAAO,EACN,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAE3B,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;GASG;AACH,MAAM,MAAM,wBAAwB,GACjC;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GACrC;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,8BAA8B,CAAA;CAAE,GAC1D;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE,CAAA;AAExE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,CAAC,EAAE,sBAAsB,GAC3B,wBAAwB,CAyB1B"}
+{"version":3,"file":"useCustomBlockInit.d.ts","sourceRoot":"","sources":["../../src/react/useCustomBlockInit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,mDAAmD,CAAA;AAEvG,OAAO,EAAE,KAAK,sBAAsB,EAAmB,MAAM,YAAY,CAAA;AAEzE;;;;;;;;;GASG;AACH,MAAM,MAAM,wBAAwB,GACjC;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GACrC;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,8BAA8B,CAAA;CAAE,GAC1D;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE,CAAA;AAExE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,IAAI,wBAAwB,CAwB7D"}

package/dist/react/useCustomBlockInit.js

@@ -1,5 +1,5 @@
 import { useEffect, useState } from "react";
-import { initCustomBlock, } from "../init.js";
+import { initCustomBlock } from "../init.js";
 /**
  * React wrapper around {@link initCustomBlock}. Kicks off the SDK ↔ host
  * handshake on mount and returns a discriminated state object so the rest of
@@ -17,15 +17,14 @@ import { initCustomBlock, } from "../init.js";
  *   return <App />
  * }
  */
-export function useCustomBlockInit(opts) {
+export function useCustomBlockInit() {
     const [state, setState] = useState({
         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(initial => {
+        initCustomBlock().then(initial => {
             if (!cancelled) {
                 setState({ isLoaded: true, error: undefined, initial });
             }

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/types.d.ts

@@ -2,12 +2,12 @@ import type { NotionCollectionSchema } from "./protocol/dataSources/dataSource.j
 import type { NotionDataSourceValue } from "./protocol/dataSources/dataSourceValue.js";
 import type { NotionPropertySchema } from "./protocol/dataSources/propertySchema.js";
 import type { NotionDataSourceId, NotionPageId } from "./protocol/ids.js";
-import type { BridgeMessagePayload } from "./protocol/messagePayload.js";
 import type { NotionCreatePagePosition } from "./protocol/messages/createPage.js";
 import type { CreatePageResultMessage, CustomBlockCreatePageErrorInfo } from "./protocol/messages/createPageResult.js";
 import type { CustomBlockGetPageErrorInfo, GetPageResultMessage } from "./protocol/messages/getPage.js";
 import type { CustomBlockGetUserErrorInfo, GetUserResultMessage } from "./protocol/messages/getUser.js";
 import type { CustomBlockListUsersErrorInfo, ListUsersMessage, ListUsersResultMessage } from "./protocol/messages/listUsers.js";
+import type { BridgeMessagePayload } from "./protocol/messages/messagePayload.js";
 import type { CustomBlockCheckboxFilterOperator, CustomBlockContainsFilterOperator, CustomBlockDateFilterOperator, CustomBlockNumberFilterOperator, CustomBlockOptionFilterOperator, CustomBlockTextFilterOperator } from "./protocol/messages/queryDataSource.js";
 import type { CustomBlockQueryDataSourceErrorInfo } from "./protocol/messages/queryDataSourceResult.js";
 import type { UpdatePageMessage } from "./protocol/messages/updatePage.js";

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

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.45"
+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/errors.md

@@ -35,7 +35,7 @@ Each API narrows `code` to its own open string union. The known literals provide
 
 ## Initialization errors
 
-Unlike request helpers, `initCustomBlock` rejects with `CustomBlockInitializationError`. Its `code` type is `CustomBlockInitializationErrorCode`, which covers failures reported by either side of the handshake plus SDK-local timeout and iframe errors.
+Unlike request helpers, `initCustomBlock` rejects with `CustomBlockInitializationError`. Its `code` type is `CustomBlockInitializationErrorCode`, which covers failures reported by either side of the handshake plus SDK-local iframe errors. For example, hosts can report `init_timeout` when Notion did not finish loading host dependencies in time.
 
 `CustomBlockInitializationErrorInfo` is the matching `{ code, message, isRetryable }` object type.
 

package/docs/lifecycle.md

@@ -34,8 +34,9 @@ The initialization promise resolves after the SDK applies the host state.
 Await it before rendering code that reads initialized state. The SDK sends
 `initResult` after the initial render.
 
-- The promise rejects with `CustomBlockInitializationError` code
-  `init_timeout` if the host does not send a usable `init`.
+- The SDK waits for the host to respond with `init` or `init.error`, without
+  an SDK-local timeout. Host-owned timeout errors such as `init_timeout` reject
+  the promise with `CustomBlockInitializationError`.
 - If a matching `init` is malformed, the SDK sends `initResult.error` with code
   `invalid_init_payload` and rejects with the same structured error.
 - If the host sends incomplete or invalid data source bindings, the SDK sends
@@ -91,21 +92,19 @@ values.
 ### `<NotionCustomBlock>`
 
 ```ts
-type NotionCustomBlockProps = InitCustomBlockOptions & {
+type NotionCustomBlockProps = {
   children: ReactNode;
   fallback?: ReactNode;
   errorFallback?: ReactNode | ((error: Error) => ReactNode);
 };
 ```
 
-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`.
+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.
 
-### `useCustomBlockInit(opts?)`
+### `useCustomBlockInit()`
 
 ```ts
-function useCustomBlockInit(
-  opts?: InitCustomBlockOptions,
-): UseCustomBlockInitResult;
+function useCustomBlockInit(): UseCustomBlockInitResult;
 
 type UseCustomBlockInitResult =
   | { isLoaded: false; error: undefined }
@@ -124,14 +123,10 @@ function Root() {
 }
 ```
 
-### `initCustomBlock(opts?)`
+### `initCustomBlock()`
 
 ```ts
-function initCustomBlock(
-  opts?: InitCustomBlockOptions,
-): Promise<CustomBlockInitPayload>;
-
-type InitCustomBlockOptions = { timeoutMs?: number };
+function initCustomBlock(): Promise<CustomBlockInitPayload>;
 ```
 
 The lower-level promise API. `<NotionCustomBlock>` and `useCustomBlockInit` both call it for you. Reach for it directly only when you want to `await` init at module scope (e.g. before `ReactDOM.createRoot`). Expected failures reject with `CustomBlockInitializationError`.
@@ -142,26 +137,67 @@ The `CustomBlockInitializationErrorCode` tells you where initialization failed:
 
 - The host rejected initialization.
 - The SDK could not apply the host's state.
-- The SDK failed before the handshake completed, such as `not_in_iframe` or `init_timeout`.
+- The SDK failed before the handshake completed, such as `not_in_iframe`.
 
 All code types are open string unions, so keep a default branch. Use `isRetryable` to decide whether offering a retry makes sense, and treat `message` as display text rather than a stable identifier. See [Error handling](./errors.md) for the shared error contract.
 
 ### `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.
+
+#### Getter
 
-`customBlock` covers runtime state, live data source snapshots, and sizing. Imperative APIs such as `pages.*` and `users.*` are also framework-neutral functions.
+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
@@ -169,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`