@notionhq/custom-blocks 0.0.58

package/dist/types.d.ts

@@ -0,0 +1,154 @@
+import type { NotionCollectionSchema } from "./bridge/dataSources/dataSource.js";
+import type { NotionDataSourcePage, NotionDataSourcePageUpdateInput, NotionDataSourcePageUpdateResult } from "./bridge/dataSources/dataSourcePage.js";
+import type { NotionPropertySchema } from "./bridge/dataSources/propertySchema.js";
+import type { CustomBlockErrorInfo } from "./bridge/errors.js";
+import type { NotionDataSourceId } from "./bridge/ids.js";
+import type { NotionCreatePagePosition } from "./bridge/messages/createPage.js";
+import type { CustomBlockCreatePageErrorInfo } from "./bridge/messages/createPageResult.js";
+import type { CustomBlockGetPageErrorInfo } from "./bridge/messages/getPage.js";
+import type { CustomBlockGetUserErrorInfo } from "./bridge/messages/getUser.js";
+import type { CustomBlockListUsersErrorInfo } from "./bridge/messages/listUsers.js";
+import type { CustomBlockQueryDataSourceErrorInfo } from "./bridge/messages/queryDataSourceResult.js";
+import type { CustomBlockUpdatePageErrorInfo } from "./bridge/messages/updatePageResult.js";
+import type { NotionPage, NotionPageCover, NotionPageIcon, NotionPageId, NotionPagePropertyInputMap, NotionPagePropertyWriteMap } from "./bridge/pages/page.js";
+import type { NotionUser, NotionUserList } from "./bridge/users/user.js";
+export type { NotionDataSourceId, NotionSpaceId } from "./bridge/ids.js";
+export type { NotionPageId } from "./bridge/pages/page.js";
+export type { NotionUser, NotionUserId, NotionUserList, } from "./bridge/users/user.js";
+export type { CustomBlockCreatePageErrorInfo, CustomBlockErrorInfo, CustomBlockGetPageErrorInfo, CustomBlockGetUserErrorInfo, CustomBlockListUsersErrorInfo, CustomBlockQueryDataSourceErrorInfo, CustomBlockUpdatePageErrorInfo, NotionDataSourcePageUpdateInput, NotionDataSourcePageUpdateResult, };
+/**
+ * Return shape of `useDataSource`.
+ *
+ * - `items` — the rows the host has returned so far. Empty until the first response arrives.
+ * - `isLoading` — `true` while a query is in flight.
+ * - `hasMore` — `true` if the host indicated more rows are available beyond the current page.
+ * - `error` — structured error information if the most recent query failed.
+ */
+export type UseDataSourceResult = {
+    items: NotionDataSourcePage[];
+    /**
+     * Collection/data-source schema for the bound Notion data source, including raw property
+     * schemas. Undefined when the semantic data-source key has not been bound.
+     */
+    collectionSchema?: NotionCollectionSchema;
+    /**
+     * Per-property schemas keyed by raw property ID, including the four synthetic built-ins
+     * (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`).
+     */
+    propertySchemasById: {
+        [propertyId: string]: NotionPropertySchema;
+    };
+    /**
+     * Per-property schemas keyed by user-defined keys from the data source's `propertyIdsByKey`.
+     * Built-ins are NOT included here. Keys mapped to `undefined` indicate a declared-but-unbound
+     * slot.
+     */
+    propertySchemasByKey: {
+        [key: string]: NotionPropertySchema | undefined;
+    };
+    isLoading: boolean;
+    hasMore: boolean;
+    error?: CustomBlockQueryDataSourceErrorInfo;
+};
+export type UseDataSourceOptions = {
+    /**
+     * Maximum number of rows to request from the host. Defaults to 20.
+     */
+    limit?: number;
+};
+/**
+ * Parent reference accepted by `sdk.pages.create`. Mirrors Notion's public `POST /v1/pages`
+ * parent shape; see https://developers.notion.com/reference/data-source.
+ *
+ * - `page_id`: Create a child page under the given Notion page.
+ * - `data_source_id`: Create a row inside the given Notion data source (aka the internal
+ *   collection). The public API's `data_source_id` is the same UUID as the `collectionPointer.id`
+ *   exposed in `dataSources`, so either value works here.
+ * - `data_source_key`: Create a row inside the data source that the custom block was configured with
+ *   under this semantic key. The SDK resolves the key to a `data_source_id` locally before
+ *   sending the request to the host.
+ */
+export type CreatePageParent = {
+    type: "page_id";
+    page_id: NotionPageId;
+} | {
+    type: "data_source_id";
+    data_source_id: NotionDataSourceId;
+} | {
+    type: "data_source_key";
+    key: string;
+};
+/**
+ * Input accepted by `sdk.pages.create`. Mirrors the Notion public API `POST /v1/pages` API.
+ */
+export type CreatePageInput = {
+    parent: CreatePageParent;
+    properties: NotionPagePropertyInputMap;
+    icon?: NotionPageIcon;
+    cover?: NotionPageCover;
+    position?: NotionCreatePagePosition;
+};
+/**
+ * The result of a `sdk.pages.create` API call.
+ */
+export type CreatePageResult = {
+    status: "success";
+    /** The newly created page. */
+    page: NotionPage;
+} | {
+    status: "error";
+    error: CustomBlockCreatePageErrorInfo;
+};
+/**
+ * Input accepted by `sdk.pages.update`.
+ *
+ * `properties` is keyed by raw Notion property ID. To update a row with configured
+ * custom-block property keys, use the `update` helper on pages returned from
+ * `useDataSource`.
+ */
+export type UpdatePageInput = {
+    pageId: NotionPageId;
+    properties?: NotionPagePropertyWriteMap;
+    icon?: NotionPageIcon;
+    cover?: NotionPageCover;
+    archived?: boolean;
+};
+/**
+ * Result of `sdk.pages.get`.
+ */
+export type GetPageResult = {
+    status: "success";
+    page: NotionPage;
+} | {
+    status: "error";
+    error: CustomBlockGetPageErrorInfo;
+};
+/**
+ * Result of `sdk.pages.update` / `sdk.pages.delete`.
+ */
+export type UpdatePageResult = {
+    status: "success";
+    page: NotionPage;
+} | {
+    status: "error";
+    error: CustomBlockUpdatePageErrorInfo;
+};
+export type ListUsersInput = {
+    startCursor?: string;
+    pageSize?: number;
+};
+export type ListUsersResult = {
+    status: "success";
+    list: NotionUserList;
+} | {
+    status: "error";
+    error: CustomBlockListUsersErrorInfo;
+};
+export type GetUserResult = {
+    status: "success";
+    user: NotionUser;
+} | {
+    status: "error";
+    error: CustomBlockGetUserErrorInfo;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Internal helpers shared across the SDK.
+ */
+/**
+ * Throws an error when an unexpected value is encountered. This is used to ensure all code paths
+ * are covered when using discriminated unions.
+ */
+export declare function unreachable(value: never): never;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../../../../Users/nsarkar/work/custom-blocks/sdk/src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAI/C"}

package/dist/utils.js

@@ -0,0 +1,10 @@
+/**
+ * Internal helpers shared across the SDK.
+ */
+/**
+ * Throws an error when an unexpected value is encountered. This is used to ensure all code paths
+ * are covered when using discriminated unions.
+ */
+export function unreachable(value) {
+    throw new Error(`[notion-custom-sdk] Unexpected value encountered: ${JSON.stringify(value)}`);
+}

package/dist/version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Runtime SDK package version. Sent over the bridge for host-side analytics only. Business logic
+ * should compare against the bridge protocol version instead of this value.
+ *
+ * This checked-in value intentionally stays generic for local development. The SDK publish build
+ * overwrites the compiled runtime module with package.json's semver before publishing.
+ */
+export declare const NCBLOCK_SDK_VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../../../../../../Users/nsarkar/work/custom-blocks/sdk/src/version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAgB,CAAA"}

package/dist/version.js

@@ -0,0 +1,7 @@
+/**
+ * Runtime SDK package version. Sent over the bridge for host-side analytics only.
+ * Business logic should compare against the bridge protocol version instead of this value.
+ *
+ * WARNING: Generated during SDK publish. Do not edit in the published package.
+ */
+export const NCBLOCK_SDK_VERSION = "0.0.58"

package/docs/block-location.md

@@ -0,0 +1,83 @@
+# Block Location & Theme
+
+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 how the surrounding Notion app is currently presented (e.g. light vs. dark theme).
+
+## API
+
+The host bridge carries these values as explicit `blockId`, `parent`, and `page` fields.
+
+### `useBlockId()`
+
+Returns the custom block's own ID.
+
+Re-renders when the host sends a block location update.
+
+```ts
+function useBlockId(): NotionBlockId;
+```
+
+For non-React renderers, use `customBlock.getBlockId()` after `initCustomBlock()` resolves:
+
+```ts
+await initCustomBlock();
+
+const blockId = customBlock.getBlockId();
+```
+
+### `useParent()`
+
+Returns the block's parent in the document tree.
+
+Re-renders when the host sends a block location update.
+
+```ts
+function useParent(): NotionParent;
+
+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/...
+  | { type: "data_source_id"; data_source_id: string } // custom block backing a custom collection view
+  | { type: "workspace"; workspace: true }; // top-level block parented by a team / workspace
+```
+
+For non-React renderers, use `customBlock.getParent()` after `initCustomBlock()` resolves.
+
+### `usePage()`
+
+Returns the nearest enclosing `page` / `collection_view_page` ancestor.
+
+Re-renders when the host sends a block location update.
+
+```ts
+function usePage(): { id: NotionPageId };
+```
+
+For non-React renderers, use `customBlock.getPage()` after `initCustomBlock()` resolves.
+
+### `useTheme()`
+
+Returns the host's current theme.
+
+Re-renders on every `themeChanged` message.
+
+```ts
+function useTheme(): NotionTheme; // "light" | "dark"
+```
+
+For non-React renderers, use `customBlock.getTheme()`:
+
+```ts
+await initCustomBlock();
+
+const theme = customBlock.getTheme();
+```
+
+```tsx
+import { usePage, useTheme } from "@notionhq/custom-blocks";
+
+export function Header() {
+  const page = usePage();
+  const theme = useTheme();
+  return <header data-theme={theme}>Page: {page.id}</header>;
+}
+```

package/docs/data-sources.md

@@ -0,0 +1,186 @@
+# Data sources
+
+A custom block declares its **data sources** — semantic keys like `people` or `tasks` — in `custom_blocks.json`.
+
+Data source mapping - resolving keys to ids - is stored on the block itself. This can be read/written programmatically using the `ncblock` CLI (try `npx ncblock --help`) or in the Notion UI.
+
+At runtime, your code references the semantic key and the SDK handles the lookup for you. Use `useDataSource(key)` for the rows themselves (it also exposes the resolved schema), and `useManifest()` when you need the declared data-source keys and their declarations (e.g. picking a default key, or rendering a key switcher). For non-React renderers, `customBlock.getManifest()` exposes the same manifest, but row querying is currently only exposed through the React `useDataSource` hook.
+
+## Pages within a data source
+
+Each row returned by `useDataSource` is a `NotionDataSourcePage` — `{ id, propertiesById, propertiesByKey, update }`. Read property values through either of the two views:
+
+- `propertiesByKey[key]` — keyed by the semantic property keys you declared in the manifest.
+- `propertiesById[propertyId]` — keyed by the raw Notion property ID.
+
+The four built-ins (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`) are always present in `propertiesById` (and `collectionSchema.propertiesById`), never in the `*ByKey` views — they don't have semantic keys.
+
+### Updating a row
+
+Each page carries its own `update` helper:
+
+```ts
+await row.update({
+  properties: {
+    score: { type: "number", number: 8 }, // semantic key
+  },
+  icon: { type: "emoji", emoji: "✅" },
+});
+```
+
+Because the helper is bound to its data source, you can write property values keyed by **either** semantic keys or raw IDs — the SDK resolves them before sending the request. The input and result shapes are `NotionDataSourcePageUpdateInput` and `NotionDataSourcePageUpdateResult`.
+
+Use `row.update(...)` whenever you already have a row in hand. For pages you don't have a row for (e.g. you only have a `pageId`), drop down to the top-level [`pages` API](./pages.md) — it covers create / get / update / delete and accepts raw property IDs only.
+
+## API
+
+### `useDataSource(key, options?)`
+
+```ts
+function useDataSource(key: string, options?: { limit?: number }): UseDataSourceResult;
+
+type UseDataSourceResult = {
+  items: NotionDataSourcePage[];
+  collectionSchema?: NotionCollectionSchema;
+  propertySchemasById: { [propertyId: string]: NotionPropertySchema };
+  propertySchemasByKey: { [key: string]: NotionPropertySchema | undefined };
+  isLoading: boolean;
+  hasMore: boolean;
+  error?: CustomBlockQueryDataSourceErrorInfo;
+};
+```
+
+Reads the data source mapped to `key`. `limit` defaults to 20 and is capped at 999. To show more rows, keep the desired limit in your own component state and pass the larger value back into `useDataSource(key, { limit })`. `propertySchemasByKey` is `undefined` for declared-but-unbound slots. When the host reports a query failure, `error` is `{ code, message, isRetryable }` with `code` narrowed to `CustomBlockQueryDataSourceErrorCode`.
+
+### `useManifest()`
+
+```ts
+function useManifest(): CustomBlockManifest | null;
+```
+
+Returns the author-declared manifest loaded from `custom_blocks.json` — the semantic data-source keys plus their declared `name`, `description`, and property declarations. `null` when the block ships no manifest. This is the configuration the block _declared_, not host-resolved bindings; use `useDataSource(key)` for rows and resolved schema. Handy for enumerating declared keys:
+
+```tsx
+const manifest = useManifest();
+const keys = Object.keys(manifest?.dataSources ?? {});
+const activeKey = keys[0] ?? "default";
+```
+
+### `customBlock.getManifest()`
+
+```ts
+function customBlock.getManifest(): CustomBlockManifest | null;
+```
+
+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.
+
+```ts
+await initCustomBlock();
+
+renderManifest(customBlock.getManifest());
+```
+
+`customBlock` does not yet expose a non-React equivalent of `useDataSource(key)`: querying rows, tracking `isLoading` / `hasMore`, and using row-level `update` helpers still require the React hook.
+
+## Example: querying a data source
+
+A typical data-driven view picks a key, calls `useDataSource`, schema-checks the rows, and surfaces a setup hint when the mapped collection is missing the expected fields. Trimmed from `templates/radar-chart`:
+
+```tsx
+import type { NotionDataSourcePage } from "@notionhq/custom-blocks";
+import { useDataSource } from "@notionhq/custom-blocks/react";
+
+const KEY = "people";
+
+function isComplete(item: NotionDataSourcePage): boolean {
+  return (
+    typeof item.propertiesByKey.name === "string" &&
+    typeof item.propertiesByKey.score === "number" &&
+    Number.isFinite(item.propertiesByKey.score)
+  );
+}
+
+export function ScoreList() {
+  const [limit, setLimit] = useState(20);
+  const { items, isLoading, hasMore, error } = useDataSource(KEY, { limit });
+
+  if (error) return <div role="alert">Couldn't load: {error.message}</div>;
+  if (isLoading && items.length === 0) return <div>Loading…</div>;
+
+  const ready = items.filter(isComplete);
+  if (ready.length === 0) {
+    return (
+      <div>
+        Map a data source with key <code>{KEY}</code> exposing <code>name</code>{" "}
+        (text) and <code>score</code> (number).
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      <ul>
+        {ready.map((item) => (
+          <li key={item.id}>
+            {String(item.propertiesByKey.name)} —{" "}
+            {Number(item.propertiesByKey.score)}
+          </li>
+        ))}
+      </ul>
+      {hasMore ? (
+        <button type="button" onClick={() => setLimit(limit + 20)} disabled={isLoading}>
+          {isLoading ? "Loading…" : "Load more"}
+        </button>
+      ) : null}
+    </div>
+  );
+}
+```
+
+## Types
+
+### Rows & values
+
+- `NotionDataSource` — a resolved data source: semantic key, `collectionSchema`, `propertyIdsByKey`, `propertySchemasById`.
+- `NotionDataSourcePage` — a single row exposed to app code: `{ id, propertiesById, propertiesByKey, update }`.
+- `NotionDataSourceValue` — the discriminated union of values that can appear inside `propertiesById[propertyId]`. Date values branch into the `NotionDateValue` union below.
+- `NotionDataSourcePageUpdateInput` / `NotionDataSourcePageUpdateResult` — input and result for the per-page `update` helper.
+- `UseDataSourceOptions` — options accepted by `useDataSource`, currently `{ limit?: number }`.
+
+### Property schemas
+
+- `NotionPropertySchema` — schema for a single property (type plus type-specific config like `select` options).
+- `NotionPropertyType` — string-literal union of every supported property type.
+- `NOTION_PROPERTY_TYPES` — runtime list of those literals (handy for switch coverage and validation).
+- `NotionPropertyOption` — a single `select` / `multi_select` / `status` option (`{ id, name, color }`).
+- `NotionPropertyColor` — the color literal used by options and groups.
+- `NotionStatusGroup` — the `status` property's "To do / In progress / Done" grouping.
+- `NotionDualProperty` — properties that have both a primary and a secondary axis (e.g. `unique_id` prefix + number).
+- `NotionBuiltinPropertyId` — string-literal union of the four synthetic property IDs (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`).
+- `NOTION_BUILTIN_PROPERTY_IDS` — runtime list of the four built-in IDs.
+
+### Collection schema & pointers
+
+- `NotionCollectionSchema` — host-supplied schema for the bound collection, including raw property schemas.
+- `NotionRecordPointer` — `{ id, table }`. Generic reference to any Notion record (page, block, collection row). Exported for convenience; `useDataSource` and the `pages` API don't take one as input.
+
+### IDs
+
+Branded string types — they're plain strings at runtime but TypeScript distinguishes them.
+
+- `NotionDataSourceId`
+- `NotionSpaceId`
+
+### Date values
+
+Returned wherever a date / date-range value appears (e.g. inside `propertiesByKey` for a `date` property). All-day values use `NotionDate*` shapes; values with a time component use `NotionDateTime*`.
+
+- `NotionDateValue` — discriminated union covering every date-shaped value below.
+- `NotionDate`
+- `NotionDateRange`
+- `NotionDateTime`
+- `NotionDateTimeRange`
+- `NotionDateReminder`
+- `NotionDateTimeReminder`
+- `NotionTimeReminder`
+- `NotionNoReminder`

package/docs/lifecycle.md

@@ -0,0 +1,172 @@
+# Lifecycle
+
+The SDK ↔ host handshake, the React wrapper that runs it, and the auto-resize hook that keeps the iframe in sync with your content.
+
+## Handshake
+
+`initCustomBlock()` posts `ready` to `window.parent` and awaits the host's `init` (theme, block ID/parent/page ID, current user, and `dataSources: { bindings }` keyed by semantic data-source key, which the SDK resolves against the manifest). The promise resolves with the normalized initial state, captured in `CustomBlockInitial` — `await` it before mounting React so hooks always see populated state.
+
+- Default `timeoutMs` is 15000; rejects with `CustomBlockInitError` code `init_timeout` if the host doesn't respond.
+- In a top-level browser tab (no parent frame), rejects with `NotInIframeError` code `not_in_iframe`. `<NotionCustomBlock>` catches this, seeds placeholders, and renders `children` behind a warning banner so dev-time previews still work.
+- After init, `*Changed` events (e.g. `themeChanged`, `parentChanged`, `dataSourcesChanged`) push updates and the relevant hooks re-render.
+- `initCustomBlock` is idempotent; subsequent calls return the same promise.
+
+## Sizing
+
+The host owns width and height. Inside the iframe, `100vh` ≠ a screen and there's no meaningful "device width" — only iframe width. Layouts must reflow from a phone column to a desktop block.
+
+- **Self-sizing content** is the default — `<NotionCustomBlock>` measures `#root` and posts `resize` messages so the iframe tracks your content. Pass `autoResize={false}` for full-bleed views, or to drive `useCustomBlockAutoResize` yourself.
+- Prefer container queries (`@container`) over viewport queries.
+
+## API
+
+Import framework-neutral APIs from `@notionhq/custom-blocks`; import React hooks and components from `@notionhq/custom-blocks/react`. The runtime APIs below assume `initCustomBlock()` has resolved — initialized-only hooks and `customBlock` getters throw if called before that. Inside `<NotionCustomBlock>` (or past the `isLoaded` gate of `useCustomBlockInit`), single-value hooks return non-nullable values.
+
+### `<NotionCustomBlock>`
+
+```ts
+type NotionCustomBlockProps = InitCustomBlockOptions & {
+  children: ReactNode;
+  fallback?: ReactNode;
+  errorFallback?: ReactNode | ((error: Error) => ReactNode);
+  autoResize?: boolean; // defaults to true
+};
+```
+
+Top-level wrapper. Runs the handshake, gates `children`, and (by default) drives auto-resize. `fallback` replaces the loading view (default `null`); `errorFallback` replaces the inline `<p role="alert">` shown if init rejects. `timeoutMs` flows through to `initCustomBlock`. Pass `autoResize={false}` for full-bleed views or to call `useCustomBlockAutoResize` yourself.
+
+### `useCustomBlockInit(opts?)`
+
+```ts
+function useCustomBlockInit(
+  opts?: InitCustomBlockOptions,
+): UseCustomBlockInitResult;
+
+type UseCustomBlockInitResult =
+  | { isLoaded: false; error: undefined }
+  | { isLoaded: false; error: CustomBlockInitFailure }
+  | { isLoaded: true; error: undefined; initial: CustomBlockInitial };
+```
+
+React wrapper around `initCustomBlock` for templates that prefer not to use top-level `await`. Multiple components calling it share the same handshake.
+
+```tsx
+function Root() {
+  const init = useCustomBlockInit();
+  if (init.error) return <p role="alert">Init failed: {init.error.message}</p>;
+  if (!init.isLoaded) return null;
+  return <App />;
+}
+```
+
+### `initCustomBlock(opts?)`
+
+```ts
+function initCustomBlock(
+  opts?: InitCustomBlockOptions,
+): Promise<CustomBlockInitial>;
+
+type InitCustomBlockOptions = { timeoutMs?: number };
+```
+
+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`). If the host replies with an init error, the promise rejects with `CustomBlockInitError`.
+
+### `CustomBlockInitError`
+
+```ts
+class CustomBlockInitError extends Error {
+  code: CustomBlockInitErrorCode;
+  isRetryable: boolean;
+}
+
+type CustomBlockErrorInfo<TCode extends string = string> = {
+  code: TCode;
+  message: string;
+  isRetryable: boolean;
+};
+
+type CustomBlockInitErrorInfo = CustomBlockErrorInfo<CustomBlockInitErrorCode>;
+
+type CustomBlockInitErrorCode =
+  | "no_ready"
+  | "invalid_ready"
+  | "manifest_unavailable"
+  | "manifest_invalid"
+  | "invalid_protocol_version"
+  | "unsupported_protocol_version"
+  | "context_unavailable"
+  | "current_user_unavailable"
+  | "missing_data_source_binding"
+  | "data_source_unavailable"
+  | "missing_property_binding"
+  | "invalid_property_binding"
+  | "not_in_iframe"
+  | "init_timeout"
+  | "unknown_error";
+```
+
+Thrown when the host rejects initialization instead of returning the initial theme, block location, current user, and data sources. `CustomBlockInitErrorInfo` uses the same structured error payload as every other API, with `code` narrowed to `CustomBlockInitErrorCode`. Use `error instanceof CustomBlockInitError`, `error.code`, and `error.isRetryable` to branch on host-reported setup failures.
+
+Runtime APIs use the same `CustomBlockErrorInfo<TCode>` envelope with their own code unions, such as `CustomBlockCreatePageErrorCode`, `CustomBlockUpdatePageErrorCode`, and `CustomBlockQueryDataSourceErrorCode`.
+
+The public API-specific runtime aliases are `CustomBlockCreatePageErrorInfo`, `CustomBlockGetPageErrorInfo`, `CustomBlockGetUserErrorInfo`, `CustomBlockListUsersErrorInfo`, `CustomBlockQueryDataSourceErrorInfo`, and `CustomBlockUpdatePageErrorInfo`. Their `code` fields are narrowed by `CustomBlockCreatePageErrorCode`, `CustomBlockGetPageErrorCode`, `CustomBlockGetUserErrorCode`, `CustomBlockListUsersErrorCode`, `CustomBlockQueryDataSourceErrorCode`, and `CustomBlockUpdatePageErrorCode`. Shared categories include `CustomBlockPropertyErrorCode` / `CustomBlockPropertyErrorInfo` and `CustomBlockDataSourceResolutionErrorCode` / `CustomBlockDataSourceResolutionErrorInfo`.
+
+### `customBlock`
+
+Framework-neutral runtime APIs for renderers that do not use React hooks. `customBlock.getState()` returns a `CustomBlockState` snapshot that hides internal query cache details. Initialized-only getters (`getTheme`, `getBlockId`, `getParent`, `getPage`, and `getCurrentUser`) throw until `initCustomBlock()` resolves. `getManifest()` is not gated on init — it returns the declared manifest (or `null`) regardless.
+
+`customBlock` covers runtime state and sizing. Row querying still goes through `useDataSource`, while imperative APIs such as `pages.*` and `users.*` are already framework-neutral functions.
+
+```ts
+await initCustomBlock();
+
+const theme = customBlock.getTheme();
+const unsubscribe = customBlock.subscribe(() => {
+  render(customBlock.getState());
+});
+```
+
+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
+const stopAutoResize = customBlock.autoResize({
+  target: document.getElementById("root"),
+});
+
+// Later, if your renderer unmounts:
+stopAutoResize();
+```
+
+### `NotInIframeError`
+
+Thrown when `initCustomBlock` is called in a top-level tab (no parent frame). It has `code: "not_in_iframe"` and `isRetryable: false`. `<NotionCustomBlock>` catches it and falls back to a standalone preview with a warning banner; direct callers can `instanceof NotInIframeError` to apply their own policy.
+
+### `useCustomBlockAutoResize({ enabled? })`
+
+```ts
+function useCustomBlockAutoResize(args?: { enabled?: boolean }): void;
+```
+
+React wrapper around `customBlock.autoResize({ target: document.getElementById("root") })`. Measures `#root`'s height and posts `resize` messages, deduping unchanged values. `<NotionCustomBlock>` runs this for you — only call it directly when you want to drive `enabled` yourself (e.g. a debug toggle), and pair with `autoResize={false}` so it doesn't run twice. The target must have intrinsic height; do not give it `height: 100%` or `100vh`.
+
+```tsx
+<NotionCustomBlock autoResize={false}>
+  <App />
+</NotionCustomBlock>;
+
+function App() {
+  const [enabled, setEnabled] = useState(true);
+  useCustomBlockAutoResize({ enabled });
+  return <div>…</div>;
+}
+```
+
+## Debug console
+
+Press `\` while focused in a custom block to toggle a debug overlay that replaces the block's children with a `<pre>` log of every `postMessage` sent and received over the bridge. Each line is formatted as:
+
+```
+[ISO timestamp] sent/received: {"type":"ready", …}
+```
+
+The log is intentionally plain — no filtering or decoration — so it can be copied and pasted directly to a local coding agent for debugging.