@notionhq/custom-blocks 0.1.2 → 0.1.3

package/HOST.md

@@ -73,6 +73,8 @@ Initialization has three steps. A sandbox-generated `initializationId` identifie
 { type: "connect", initializationId, status: "success", bridgeProtocolVersion, sdkVersion, manifest: { /* ... */ } }
 ```
 
+The `manifest` property is optional for `connect` messages. If provided, hosts can ignore it and still return a different `manifest` in the `init` message. This sandbox-defined manifest option is included for locally-hosted custom blocks.
+
 If `connect.status` is `"error"`, reply with `init.error` using the same `initializationId` and forward its complete error payload unchanged.
 
 #### 2. Host sends `init`
@@ -181,18 +183,18 @@ Schemas:
 
 Messages sent from the sandbox to the host. Parse `window` `message` events with `sandboxToHostMessageSchema` (or per-message schemas). The type / schema column points to the payload shape.
 
-| Wire type            | Type / schema                                             | Behavior                                                                                                                                                                                                                                |
-| -------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `connect`            | `ConnectMessage` / `connectMessageSchema`                 | Starts the one-shot handshake with a sandbox-generated `initializationId`; carries `bridgeProtocolVersion`, `sdkVersion`, and the manifest.                                                                                 |
-| `initResult`         | `InitResultMessage` / `initResultMessageSchema`           | Echoes the handshake `initializationId` and reports whether the sandbox applied `init.success`.                                                                                                                             |
-| `queryDataSource`    | `QueryDataSourceMessage` / `queryDataSourceMessageSchema` | Starts or updates a `subscriptionId`-keyed subscription for rows in a raw `dataSourceId`. Later results for the same subscription replace its current value. |
-| `createPage`         | `CreatePageMessage` / `createPageMessageSchema`           | `requestId`-keyed page creation with properties and optional position; parent is `page_id` or `data_source_id`. Create-time icon and cover are not supported.                                                               |
-| `getPage`            | `GetPageMessage` / `getPageMessageSchema`                 | `requestId`-keyed page fetch by page id.                                                                                                                                                                                                |
-| `updatePage`         | `UpdatePageMessage` / `updatePageMessageSchema`           | `requestId`-keyed patch (properties, icon, cover, or `archived`).                                                                                                                                                                       |
-| `getUser`            | `GetUserMessage` / `getUserMessageSchema`                 | `requestId`-keyed user fetch by user id.                                                                                                                                                                                                |
-| `listUsers`          | `ListUsersMessage` / `listUsersMessageSchema`             | `requestId`-keyed user list with optional `startCursor` and `pageSize`.                                                                                                                                                                 |
-| `resize`             | `ResizeMessage` / `resizeMessageSchema`                   | Latest measured content height from auto-resize.                                                                                                                                                                                        |
-| `invalidHostMessage` | `InvalidHostMessage` / `invalidHostMessageSchema`         | Sandbox-side NACK for a host message it could not parse.                                                                                                                                                                                |
+| Wire type            | Type / schema                                             | Behavior                                                                                                                                                      |
+| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `connect`            | `ConnectMessage` / `connectMessageSchema`                 | Starts the one-shot handshake with a sandbox-generated `initializationId`; carries `bridgeProtocolVersion`, `sdkVersion`, and the manifest.                   |
+| `initResult`         | `InitResultMessage` / `initResultMessageSchema`           | Echoes the handshake `initializationId` and reports whether the sandbox applied `init.success`.                                                               |
+| `queryDataSource`    | `QueryDataSourceMessage` / `queryDataSourceMessageSchema` | Starts or updates a `subscriptionId`-keyed subscription for rows in a raw `dataSourceId`. Later results for the same subscription replace its current value.  |
+| `createPage`         | `CreatePageMessage` / `createPageMessageSchema`           | `requestId`-keyed page creation with properties and optional position; parent is `page_id` or `data_source_id`. Create-time icon and cover are not supported. |
+| `getPage`            | `GetPageMessage` / `getPageMessageSchema`                 | `requestId`-keyed page fetch by page id.                                                                                                                      |
+| `updatePage`         | `UpdatePageMessage` / `updatePageMessageSchema`           | `requestId`-keyed patch (properties, icon, cover, or `archived`).                                                                                             |
+| `getUser`            | `GetUserMessage` / `getUserMessageSchema`                 | `requestId`-keyed user fetch by user id.                                                                                                                      |
+| `listUsers`          | `ListUsersMessage` / `listUsersMessageSchema`             | `requestId`-keyed user list with optional `startCursor` and `pageSize`.                                                                                       |
+| `resize`             | `ResizeMessage` / `resizeMessageSchema`                   | Latest measured content height from auto-resize.                                                                                                              |
+| `invalidHostMessage` | `InvalidHostMessage` / `invalidHostMessageSchema`         | Sandbox-side NACK for a host message it could not parse.                                                                                                      |
 
 `SandboxToHostMessage` / `sandboxToHostMessageSchema` is the discriminated union over all of the above.
 
@@ -209,13 +211,13 @@ Messages sent from the host to the sandbox. Same `{ wire type, type / schema, be
 | `pageChanged`           | `PageChangedMessage` / `pageChangedMessageSchema`                     | Replaces the nearest page ancestor without disturbing theme, block ID, parent, user, or query state.                                                     |
 | `currentUserChanged`    | `CurrentUserChangedMessage` / `currentUserChangedMessageSchema`       | Replaces the current viewer record. Send when any viewer field changes (name, avatar, email).                                                            |
 | `dataSourcesChanged`    | `DataSourcesChangedMessage` / `dataSourcesChangedMessageSchema`       | Replaces data-source bindings; the sandbox preserves cached query state for keys that still exist and drops removed keys.                                |
-| `queryDataSourceResult` | `QueryDataSourceResultMessage` / `queryDataSourceResultMessageSchema` | `subscriptionId`-keyed update with `status: "success"`, `items`, and `hasMore`, or `status: "error"` and `error`.                                       |
+| `queryDataSourceResult` | `QueryDataSourceResultMessage` / `queryDataSourceResultMessageSchema` | `subscriptionId`-keyed update with `status: "success"`, `items`, and `hasMore`, or `status: "error"` and `error`.                                        |
 | `createPageResult`      | `CreatePageResultMessage` / `createPageResultMessageSchema`           | `requestId`-keyed page response with `status: "success"` or `status: "error"`.                                                                           |
 | `getPageResult`         | `GetPageResultMessage` / `getPageResultMessageSchema`                 | Same success/error shape as `createPageResult`.                                                                                                          |
 | `updatePageResult`      | `UpdatePageResultMessage` / `updatePageResultMessageSchema`           | Same success/error shape as `createPageResult`.                                                                                                          |
 | `getUserResult`         | `GetUserResultMessage` / `getUserResultMessageSchema`                 | `requestId`-keyed user response with `status: "success"` or `status: "error"`.                                                                           |
 | `listUsersResult`       | `ListUsersResultMessage` / `listUsersResultMessageSchema`             | Same success/error shape as `getUserResult`.                                                                                                             |
-| `invalidSandboxMessage` | `InvalidSandboxMessage` / `invalidSandboxMessageSchema`               | Host-side NACK for a sandbox message it could not parse.                                                                      |
+| `invalidSandboxMessage` | `InvalidSandboxMessage` / `invalidSandboxMessageSchema`               | Host-side NACK for a sandbox message it could not parse.                                                                                                 |
 
 `HostToSandboxMessage` / `hostToSandboxMessageSchema` is the discriminated union over all of the above.
 

package/README.md

@@ -1,18 +1,33 @@
 # @notionhq/custom-blocks
 
 > [!NOTE]
-> Nothing to see here. This is **extreme** alpha and currently only works for an unreleased product.
+> **Pre-release.** Custom blocks are in private alpha. Breaking changes may land at any time.
 
 SDK for building Notion custom blocks.
 
-A custom block runs as a sandboxed `<iframe>` inside a Notion block on iOS, Android, and desktop. The only channel between your block and Notion is a `postMessage` bridge — this SDK wraps it in typed React hooks plus a small framework-neutral runtime API for non-React renderers.
-
-> **Pre-release.** Breaking changes may land at any time before 1.0.
+A custom block runs as a sandboxed `<iframe>` inside the Notion app that has no direct access to the internet. The only channel between your block and Notion is a local `postMessage` bridge. This library implements the sandbox side of the bridge protocol and wraps it in a framework-neutral TypeScript API (`@notionhq/custom-blocks`) and typed React hooks (`@notionhq/custom-blocks/react`).
 
 ## Quick start
 
+Declare your custom block along with the rest of your worker definition:
+
+```ts
+// src/index.ts
+import { Worker } from "@notionhq/workers";
+
+const worker = new Worker();
+export default worker;
+
+worker.customBlock("hello", {
+  path: "./blocks/hello",
+  command: "npx vite build",
+});
+```
+
+In the block's entry point defined above, wrap your React code in `<NotionCustomBlock>` so the SDK connects with Notion before anything renders:
+
 ```tsx
-// src/index.tsx
+// blocks/hello/src/index.tsx
 import "@notionhq/custom-blocks/nds.css";
 import {
   NotionCustomBlock,
@@ -30,8 +45,10 @@ ReactDOM.createRoot(document.getElementById("root")!).render(
 );
 ```
 
+Hooks can then read live content directly from Notion:
+
 ```tsx
-// src/App.tsx
+// blocks/hello/src/App.tsx
 import { useBlockId } from "@notionhq/custom-blocks/react";
 
 export function App() {
@@ -72,9 +89,8 @@ API surface, one page per category. Import framework-neutral APIs from `@notionh
 - [`docs/pages.md`](./docs/pages.md) — `pages.create / get / update / delete`, parent variants (including the recommended `data_source_key`), property input shapes.
 - [`docs/users.md`](./docs/users.md) — `users.list / get`, the `NotionUser` shape, paging.
 - [`docs/errors.md`](./docs/errors.md) — request results, error format, error codes, retries, and initialization failures.
-- [`docs/vite-plugin.md`](./docs/vite-plugin.md) — the `notionCustomBlock()` Vite plugin and `custom_blocks.json`, the block's local-preview manifest.
-
-Declare the block source and data-source schema in the worker file with `worker.customBlock(...)`, then build and deploy it with `ntn workers deploy`. The worker definition is the source of truth; the iframe frontend uses semantic keys from that definition with APIs such as `useDataSource`. For local previews, the Vite plugin serves the block's `custom_blocks.json` — see [`docs/vite-plugin.md`](./docs/vite-plugin.md).
+- [`docs/deployment.md`](./docs/deployment.md) — worker-backed deploys, localhost self-hosted fallback, where the manifest comes from.
+- [`docs/vite-plugin.md`](./docs/vite-plugin.md) — the `notionCustomBlock()` Vite plugin.
 
 ## Forbidden APIs
 

package/dist/bridge/loadManifest.d.ts

@@ -1,7 +1,7 @@
 import type { CustomBlockErrorInfo } from "./errors.js";
 import { type CustomBlockManifest } from "./manifest.js";
-export type CustomBlockConnectErrorCode = "manifest_unavailable" | "manifest_invalid" | (string & {});
-export type CustomBlockConnectError = CustomBlockErrorInfo<CustomBlockConnectErrorCode>;
+type CustomBlockConnectErrorCode = "manifest_unavailable" | "manifest_invalid" | (string & {});
+type CustomBlockConnectError = CustomBlockErrorInfo<CustomBlockConnectErrorCode>;
 export type ManifestLoadResult = {
     manifest: CustomBlockManifest | null;
     error?: undefined;
@@ -10,11 +10,12 @@ export type ManifestLoadResult = {
     error: CustomBlockConnectError;
 };
 /**
- * Attempts to load a `custom_blocks.json` manifest co-located with the bundle.
- * A missing manifest means the block has no declared data requirements.
- * Other failures return a structured error so the host can reject the manifest.
- * The SDK validates the manifest locally for author feedback; the host still
- * validates the connect message as the iframe trust boundary.
+ * Attempts to load the custom block's optional self-hosted manifest, co-located with the bundle at
+ * `/custom_blocks.json`. This is to support local development where the block is served from a
+ * local dev server.
+ *
+ * It is up to the host to decide whether to use this manifest or provide its own persisted manifest.
  */
-export declare function loadManifest(): Promise<ManifestLoadResult>;
+export declare function attemptToLoadSelfHostedManifest(): Promise<ManifestLoadResult>;
+export {};
 //# sourceMappingURL=loadManifest.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"loadManifest.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/loadManifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,EAAE,KAAK,mBAAmB,EAAkB,MAAM,eAAe,CAAA;AAIxE,MAAM,MAAM,2BAA2B,GACpC,sBAAsB,GACtB,kBAAkB,GAClB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,MAAM,MAAM,uBAAuB,GAClC,oBAAoB,CAAC,2BAA2B,CAAC,CAAA;AAElD,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAA;IACpC,KAAK,CAAC,EAAE,SAAS,CAAA;CAChB,GACD;IACA,QAAQ,EAAE,IAAI,CAAA;IACd,KAAK,EAAE,uBAAuB,CAAA;CAC7B,CAAA;AAEJ;;;;;;GAMG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAkEhE"}
+{"version":3,"file":"loadManifest.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/loadManifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,EAAE,KAAK,mBAAmB,EAAkB,MAAM,eAAe,CAAA;AAIxE,KAAK,2BAA2B,GAC7B,sBAAsB,GACtB,kBAAkB,GAClB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,KAAK,uBAAuB,GAAG,oBAAoB,CAAC,2BAA2B,CAAC,CAAA;AAEhF,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAA;IACpC,KAAK,CAAC,EAAE,SAAS,CAAA;CAChB,GACD;IACA,QAAQ,EAAE,IAAI,CAAA;IACd,KAAK,EAAE,uBAAuB,CAAA;CAC7B,CAAA;AAEJ;;;;;;GAMG;AACH,wBAAsB,+BAA+B,IAAI,OAAO,CAAC,kBAAkB,CAAC,CA0DnF"}

package/dist/bridge/loadManifest.js

@@ -2,21 +2,13 @@ import * as v from "valibot";
 import { manifestSchema } from "./manifest.js";
 const MANIFEST_URL = "custom_blocks.json";
 /**
- * Attempts to load a `custom_blocks.json` manifest co-located with the bundle.
- * A missing manifest means the block has no declared data requirements.
- * Other failures return a structured error so the host can reject the manifest.
- * The SDK validates the manifest locally for author feedback; the host still
- * validates the connect message as the iframe trust boundary.
+ * Attempts to load the custom block's optional self-hosted manifest, co-located with the bundle at
+ * `/custom_blocks.json`. This is to support local development where the block is served from a
+ * local dev server.
+ *
+ * It is up to the host to decide whether to use this manifest or provide its own persisted manifest.
  */
-export async function loadManifest() {
-    if (typeof fetch !== "function") {
-        const message = `No fetch API available; cannot load ${MANIFEST_URL}.`;
-        console.warn(`[custom-blocks-sdk] ${message}`);
-        return {
-            manifest: null,
-            error: { code: "manifest_unavailable", message, isRetryable: true },
-        };
-    }
+export async function attemptToLoadSelfHostedManifest() {
     let response;
     try {
         response = await fetch(MANIFEST_URL, { credentials: "omit" });

package/dist/bridge/manifest.d.ts

@@ -1,12 +1,4 @@
 import * as v from "valibot";
-/**
- * User-authored manifest declaring the data sources the custom block expects.
- * Lives at `custom_blocks.json` in the project root. The sandbox may send it in
- * `connect`, and the host returns the authoritative manifest in `init`. The
- * `notionCustomBlock` Vite plugin from
- * `@notionhq/custom-blocks/vite` wires the JSON file into the dev server and
- * the build output.
- */
 /**
  * Decorative icon attached to a manifest data source. Mirrors the
  * `emoji` / `external` icon variants the public Notion API uses, so the host
@@ -62,5 +54,8 @@ export declare const manifestSchema: v.ObjectSchema<{
         }, undefined>, undefined>, {}>;
     }, undefined>, undefined>;
 }, undefined>;
+/**
+ * Manifest declaring the data sources required by a custom block.
+ */
 export type CustomBlockManifest = v.InferOutput<typeof manifestSchema>;
 //# sourceMappingURL=manifest.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAG5B;;;;;;;GAOG;AAEH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;0BAS7B,CAAA;AAEF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEnE,eAAO,MAAM,sBAAsB;;;;aAIjC,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;aAKnC,CAAA;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;aAGzB,CAAA;AAEF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,cAAc,CAAC,CAAA"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAG5B;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;0BAS7B,CAAA;AAEF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEnE,eAAO,MAAM,sBAAsB;;;;aAIjC,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;aAKnC,CAAA;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;aAGzB,CAAA;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,cAAc,CAAC,CAAA"}

package/dist/bridge/manifest.js

@@ -1,13 +1,5 @@
 import * as v from "valibot";
 import { notionPropertyTypeSchema } from "./dataSources/propertySchema.js";
-/**
- * User-authored manifest declaring the data sources the custom block expects.
- * Lives at `custom_blocks.json` in the project root. The sandbox may send it in
- * `connect`, and the host returns the authoritative manifest in `init`. The
- * `notionCustomBlock` Vite plugin from
- * `@notionhq/custom-blocks/vite` wires the JSON file into the dev server and
- * the build output.
- */
 /**
  * Decorative icon attached to a manifest data source. Mirrors the
  * `emoji` / `external` icon variants the public Notion API uses, so the host

package/dist/init.d.ts

@@ -41,15 +41,14 @@ export type InitCustomBlockOptions = {
     timeoutMs?: number;
 };
 /**
- * Performs the SDK <-> host handshake: loads `custom_blocks.json`, posts
- * `connect`, then awaits the host's `init` message. Resolves after the sandbox
- * applies the payload and returns `initResult.success`.
+ * Initializes the custom block by running the SDK <-> host handshake.
  *
- * Rejects with a `CustomBlockInitializationError` if initialization fails.
+ * Resolves with the block's initial context (theme, block location, current
+ * user, data sources) once the host has initialized the block. Rejects with a
+ * `CustomBlockInitializationError` if initialization fails.
  *
  * Idempotent: subsequent calls return the same promise as the first and ignore any new options.
- * Mount your React tree (or call any SDK hook / `customBlock.subscribe`) only after the
- * returned promise resolves.
+ * Mount your React tree (or call any SDK hook) only after the returned promise resolves.
  */
 export declare function initCustomBlock(opts?: InitCustomBlockOptions): Promise<CustomBlockInitPayload>;
 //# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAA;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAEpD,OAAO,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAA;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAGxD;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACpC,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;CAC/B,CAAA;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,8BAA8B;gBACvD,OAAO,GAAE,MAA8B;IAS3C,IAAI,EAAE,eAAe,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACpC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC9B,IAAI,GAAE,sBAA2B,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAKjC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAA;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAEpD,OAAO,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAA;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAGxD;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACpC,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;CAC/B,CAAA;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,8BAA8B;gBACvD,OAAO,GAAE,MAA8B;IAS3C,IAAI,EAAE,eAAe,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACpC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AASD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC9B,IAAI,GAAE,sBAA2B,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAKjC"}

package/dist/init.js

@@ -1,4 +1,4 @@
-import { loadManifest } from "./bridge/loadManifest.js";
+import { attemptToLoadSelfHostedManifest } from "./bridge/loadManifest.js";
 import { CustomBlockInitializationError } from "./bridge/messages/init.js";
 import { customBlockHost } from "./bridge/sandboxClient.js";
 import { unreachable } from "./utils.js";
@@ -22,23 +22,32 @@ const DEFAULT_INIT_TIMEOUT_MS = 15000;
 const NOT_IN_IFRAME_MESSAGE = "<NotionCustomBlock> only works inside an iframe — use the dev shell or deploy to Notion.";
 let initPromise;
 /**
- * Performs the SDK <-> host handshake: loads `custom_blocks.json`, posts
- * `connect`, then awaits the host's `init` message. Resolves after the sandbox
- * applies the payload and returns `initResult.success`.
+ * Initializes the custom block by running the SDK <-> host handshake.
  *
- * Rejects with a `CustomBlockInitializationError` if initialization fails.
+ * Resolves with the block's initial context (theme, block location, current
+ * user, data sources) once the host has initialized the block. Rejects with a
+ * `CustomBlockInitializationError` if initialization fails.
  *
  * Idempotent: subsequent calls return the same promise as the first and ignore any new options.
- * Mount your React tree (or call any SDK hook / `customBlock.subscribe`) only after the
- * returned promise resolves.
+ * Mount your React tree (or call any SDK hook) only after the returned promise resolves.
  */
 export function initCustomBlock(opts = {}) {
     if (initPromise === undefined) {
-        initPromise = initializeCustomBlock(opts);
+        initPromise = performHandshake(opts);
     }
     return initPromise;
 }
-async function initializeCustomBlock(opts) {
+/**
+ * Performs the host <-> sandbox SDK handshake:
+ * 1. Attempts to load an optional self-hosted `custom_blocks.json`
+ * 2. Sends `connect` with the manifest
+ * 3. Awaits the host's `init` message
+ * 4. Applies the `init` payload and acknowledges with `initResult` (fire-and-forget)
+ *
+ * Resolves with the `init` payload after the process above. Rejects with a
+ * `CustomBlockInitializationError` if any step fails.
+ */
+async function performHandshake(opts) {
     try {
         // Fail fast with a typed error when rendered as a standalone tab and not in a parent frame.
         // Otherwise, it would eventually hit the timeout, since `postMessage` to `window.parent`
@@ -47,7 +56,7 @@ async function initializeCustomBlock(opts) {
             throw new NotInIframeError();
         }
         // Load the manifest and send it to the host.
-        const manifestResult = await loadManifest();
+        const manifestResult = await attemptToLoadSelfHostedManifest();
         customBlockHost.sendConnect(manifestResult);
         const timeoutMs = opts.timeoutMs ?? DEFAULT_INIT_TIMEOUT_MS;
         await awaitHostInitWithTimeout(timeoutMs);

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.2"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.3"

package/docs/deployment.md

@@ -0,0 +1,41 @@
+# Deployment and manifests
+
+A custom block is a static web bundle — an `index.html` plus optional assets — that Notion loads into a sandboxed `<iframe>`, so the bundle needs to be hosted somewhere Notion can reach. Notion does that hosting: the block ships as part of a worker. Declare the block source and data-source schema with `worker.customBlock(...)` in the worker's `src/index.ts`, deploy with `ntn workers deploy`, and Notion serves the built bundle. Serving the bundle from your own dev server is provided as a local-development fallback, not an officially supported deployment target.
+
+The difference between the two paths is where the manifest lives:
+
+- **Worker-backed** — deploying persists the manifest on the block's definition record in Notion. The host reads it from there. The bundle carries no manifest.
+- **Self-hosted (localhost)** — there is no persisted record, so the block serves its manifest dynamically at `/custom_blocks.json` and passes the manifest to the host in the `connect` handshake.
+
+For a self-hosted block, the sandbox can propose the initial manifest in `connect`. The host decides whether to use it and sends the authoritative manifest back in `init`. The SDK always uses the host-provided manifest from `init` even if it differs from the one sent during `connect`.
+
+## Self-hosted blocks (localhost fallback)
+
+During development, a Notion host can point a custom block at a local dev server instead of a deployed worker. The block describes itself with an optional `custom_blocks.json` at the bundle root:
+
+```json
+{
+  "version": 1,
+  "dataSources": {
+    "tasks": {
+      "name": "Tasks",
+      "description": "The collection of tasks to render",
+      "properties": {
+        "title": { "name": "Title", "type": "title" },
+        "dueDate": { "name": "Due date", "type": "date" }
+      }
+    }
+  }
+}
+```
+
+At startup the SDK fetches this file from the bundle's origin and forwards it in `connect`. If the file is missing, the SDK omits `manifest` from `connect`. If it is present but unreadable or invalid, initialization fails.
+
+The [Vite plugin](./vite-plugin.md) keeps this file working in dev and emits it into `dist/` on build.
+
+## Types
+
+- `CustomBlockManifest` — the parsed shape of a block manifest.
+- `ManifestDataSource` — a single entry in `dataSources`.
+- `ManifestProperty` — a single property declaration inside a `ManifestDataSource`.
+- `ManifestIcon` — the icon variant accepted on a `ManifestDataSource`.

package/docs/vite-plugin.md

@@ -12,35 +12,11 @@ export default defineConfig({
 });
 ```
 
-In dev, the plugin serves `custom_blocks.json` from the project root so HMR and the SDK handshake see the same file. On `vite build`, it emits `custom_blocks.json` into `dist/` as a separate asset alongside the bundled HTML and JS. It also forces Vite's `base` to `"./"` (and rejects any other explicit value) — custom blocks are served from a content-addressed path, so asset URLs in the built bundle must be relative.
+It does two things:
 
-## `custom_blocks.json` and local previews
+- **Forces `base: "./"`** (and rejects any other explicit value). Custom blocks are served from a content-addressed path, so asset URLs in the built bundle must be relative.
+- **Passes through `custom_blocks.json`** when the optional file exists in the project root: served by middleware in dev so HMR and the SDK handshake see the same file, and emitted into `dist/` as a separate asset on `vite build`.
 
-`custom_blocks.json` is the block's local manifest — the data-source keys and property shapes the block expects:
+The `custom_blocks.json` manifest file only applies when a block is served from `localhost` during development instead of deployed as a worker. Worker-backed blocks declare their manifest with `worker.customBlock(...)` and should not maintain a `custom_blocks.json`, but they still use the plugin for the `base` enforcement. See [deployment.md](./deployment.md) for more information.
 
-```json
-{
-  "version": 1,
-  "dataSources": {
-    "tasks": {
-      "name": "Tasks",
-      "description": "The collection of tasks to render",
-      "properties": {
-        "title": { "name": "Title", "type": "title" },
-        "dueDate": { "name": "Due date", "type": "date" }
-      }
-    }
-  }
-}
-```
-
-For a worker-backed block, the `worker.customBlock(...)` declaration in the worker's `src/index.ts` is the source of truth at deploy time. But local previews (pasting the Vite dev URL into a live Notion block, or the dev shell) don't read the worker declaration — the SDK fetches `custom_blocks.json` from the plugin and forwards it on `connect`, and the host binds data sources against those keys. Keep the file mirroring the worker's `dataSources` schema so previews see the same slots the deployed block will; leave it as `{ "version": 1, "dataSources": {} }` if the block reads no host data.
-
-If the file is missing, the SDK omits `manifest` from `connect`. If it is unreadable or invalid, the SDK sends `connect` with `status: "error"` and an `error` payload. The host returns its authoritative manifest in `init`, and the SDK uses that one even when it differs from what was sent in `connect`.
-
-## Types
-
-- `CustomBlockManifest` — the parsed shape of `custom_blocks.json`.
-- `ManifestDataSource` — a single entry in `dataSources` (name, description, properties).
-- `ManifestProperty` — a single property declaration inside a `ManifestDataSource`.
-- `ManifestIcon` — the icon variant accepted on a `ManifestDataSource`.
+The plugin does not validate the manifest. The SDK validates it on receipt.

package/package.json

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

package/src/bridge/loadManifest.ts

@@ -4,13 +4,12 @@ import { type CustomBlockManifest, manifestSchema } from "./manifest.js"
 
 const MANIFEST_URL = "custom_blocks.json"
 
-export type CustomBlockConnectErrorCode =
+type CustomBlockConnectErrorCode =
 	| "manifest_unavailable"
 	| "manifest_invalid"
 	| (string & {})
 
-export type CustomBlockConnectError =
-	CustomBlockErrorInfo<CustomBlockConnectErrorCode>
+type CustomBlockConnectError = CustomBlockErrorInfo<CustomBlockConnectErrorCode>
 
 export type ManifestLoadResult =
 	| {
@@ -23,21 +22,13 @@ export type ManifestLoadResult =
 	  }
 
 /**
- * Attempts to load a `custom_blocks.json` manifest co-located with the bundle.
- * A missing manifest means the block has no declared data requirements.
- * Other failures return a structured error so the host can reject the manifest.
- * The SDK validates the manifest locally for author feedback; the host still
- * validates the connect message as the iframe trust boundary.
+ * Attempts to load the custom block's optional self-hosted manifest, co-located with the bundle at
+ * `/custom_blocks.json`. This is to support local development where the block is served from a
+ * local dev server.
+ *
+ * It is up to the host to decide whether to use this manifest or provide its own persisted manifest.
  */
-export async function loadManifest(): Promise<ManifestLoadResult> {
-	if (typeof fetch !== "function") {
-		const message = `No fetch API available; cannot load ${MANIFEST_URL}.`
-		console.warn(`[custom-blocks-sdk] ${message}`)
-		return {
-			manifest: null,
-			error: { code: "manifest_unavailable", message, isRetryable: true },
-		}
-	}
+export async function attemptToLoadSelfHostedManifest(): Promise<ManifestLoadResult> {
 	let response: Response
 	try {
 		response = await fetch(MANIFEST_URL, { credentials: "omit" })

package/src/bridge/manifest.ts

@@ -1,15 +1,6 @@
 import * as v from "valibot"
 import { notionPropertyTypeSchema } from "./dataSources/propertySchema.js"
 
-/**
- * User-authored manifest declaring the data sources the custom block expects.
- * Lives at `custom_blocks.json` in the project root. The sandbox may send it in
- * `connect`, and the host returns the authoritative manifest in `init`. The
- * `notionCustomBlock` Vite plugin from
- * `@notionhq/custom-blocks/vite` wires the JSON file into the dev server and
- * the build output.
- */
-
 /**
  * Decorative icon attached to a manifest data source. Mirrors the
  * `emoji` / `external` icon variants the public Notion API uses, so the host
@@ -50,4 +41,7 @@ export const manifestSchema = v.object({
 	dataSources: v.record(v.string(), manifestDataSourceSchema),
 })
 
+/**
+ * Manifest declaring the data sources required by a custom block.
+ */
 export type CustomBlockManifest = v.InferOutput<typeof manifestSchema>

package/src/init.ts

@@ -1,7 +1,7 @@
 import type { NotionContrastMode } from "./bridge/contrast.js"
 import type { NotionDataSource } from "./bridge/dataSources/dataSource.js"
 import type { NotionBlockId } from "./bridge/ids.js"
-import { loadManifest } from "./bridge/loadManifest.js"
+import { attemptToLoadSelfHostedManifest } from "./bridge/loadManifest.js"
 import { CustomBlockInitializationError } from "./bridge/messages/init.js"
 import type { CustomBlockPage } from "./bridge/pages/page.js"
 import type { NotionParent } from "./bridge/parent.js"
@@ -63,26 +63,35 @@ const NOT_IN_IFRAME_MESSAGE =
 let initPromise: Promise<CustomBlockInitPayload> | undefined
 
 /**
- * Performs the SDK <-> host handshake: loads `custom_blocks.json`, posts
- * `connect`, then awaits the host's `init` message. Resolves after the sandbox
- * applies the payload and returns `initResult.success`.
+ * Initializes the custom block by running the SDK <-> host handshake.
  *
- * Rejects with a `CustomBlockInitializationError` if initialization fails.
+ * Resolves with the block's initial context (theme, block location, current
+ * user, data sources) once the host has initialized the block. Rejects with a
+ * `CustomBlockInitializationError` if initialization fails.
  *
  * Idempotent: subsequent calls return the same promise as the first and ignore any new options.
- * Mount your React tree (or call any SDK hook / `customBlock.subscribe`) only after the
- * returned promise resolves.
+ * Mount your React tree (or call any SDK hook) only after the returned promise resolves.
  */
 export function initCustomBlock(
 	opts: InitCustomBlockOptions = {},
 ): Promise<CustomBlockInitPayload> {
 	if (initPromise === undefined) {
-		initPromise = initializeCustomBlock(opts)
+		initPromise = performHandshake(opts)
 	}
 	return initPromise
 }
 
-async function initializeCustomBlock(
+/**
+ * Performs the host <-> sandbox SDK handshake:
+ * 1. Attempts to load an optional self-hosted `custom_blocks.json`
+ * 2. Sends `connect` with the manifest
+ * 3. Awaits the host's `init` message
+ * 4. Applies the `init` payload and acknowledges with `initResult` (fire-and-forget)
+ *
+ * Resolves with the `init` payload after the process above. Rejects with a
+ * `CustomBlockInitializationError` if any step fails.
+ */
+async function performHandshake(
 	opts: InitCustomBlockOptions,
 ): Promise<CustomBlockInitPayload> {
 	try {
@@ -94,7 +103,7 @@ async function initializeCustomBlock(
 		}
 
 		// Load the manifest and send it to the host.
-		const manifestResult = await loadManifest()
+		const manifestResult = await attemptToLoadSelfHostedManifest()
 		customBlockHost.sendConnect(manifestResult)
 
 		const timeoutMs = opts.timeoutMs ?? DEFAULT_INIT_TIMEOUT_MS

package/vite-plugin/index.d.ts

@@ -40,7 +40,7 @@ export type NotionCustomBlockPlugin = {
 }
 
 /**
- * Vite plugin that serves the project's `custom_blocks.json` to the custom-block
- * bundle in dev and emits it as a separate asset on build.
+ * Vite plugin that serves an optional self-hosted `custom_blocks.json` to the custom block
+ * bundle during local development and emits it as a separate asset on build.
  */
 export function notionCustomBlock(): NotionCustomBlockPlugin

package/vite-plugin/index.js

@@ -1,7 +1,7 @@
 /**
- * Vite plugin half of `@notionhq/custom-blocks`. Exposes the project's
- * `custom_blocks.json` manifest to the custom-block bundle so the SDK's runtime
- * fetch can resolve.
+ * Vite plugin half of `@notionhq/custom-blocks`. Exposes an optional
+ * self-hosted `custom_blocks.json` manifest to the custom-block bundle so the
+ * SDK's runtime fetch can resolve.
  *
  * Authored as plain JS (with `index.d.ts` co-located for types) — the rest of
  * the SDK is `.ts` consumed directly via the workspace symlink, but Vite's
@@ -21,10 +21,11 @@
  * Vite's config loader uses Node's ESM resolver (not CommonJS `require`,
  * which fails for ESM-only deps).
  *
- * - **Dev (`vite`)** — middleware serves `/custom_blocks.json` from the project root.
- * - **Build (`vite build`)** — emits `custom_blocks.json` as an asset alongside the
- *   built `index.html` so `vite preview` and any local file server can serve
- *   it. In production, the custom-block CLI handles serving.
+ * - **Dev (`vite`)** — middleware serves `/custom_blocks.json` from the project root
+ *   when the optional file exists.
+ * - **Build (`vite build`)** — emits an existing `custom_blocks.json` as an asset
+ *   alongside the built `index.html` so `vite preview` and any local file server
+ *   can serve it.
  *
  * Validation is intentionally not performed here — the SDK validates on
  * receipt, and the CLI validates separately at deploy time.