@notionhq/custom-blocks 0.0.78 → 0.1.0

package/HOST.md

@@ -25,6 +25,7 @@ import { createCustomBlockHost } from "@notionhq/custom-blocks/host";
 
 const host = createCustomBlockHost({
   iframe,
+  minBridgeProtocolVersion: 3,
   initialState: {
     theme,
     blockId,
@@ -35,14 +36,20 @@ const host = createCustomBlockHost({
     dataSources: { bindings },
   },
   handlers: {
-    queryDataSource: async (message) => ({ status: "success", items: [], hasMore: false }),
+    queryDataSource: async (message) => ({
+      status: "success",
+      items: [],
+      hasMore: false,
+    }),
   },
 });
 ```
 
 Use it when the generic protocol loop is helpful. Hosts with more specialized runtime needs can keep using the schemas and message types directly.
 
-Related types: `CustomBlockHostOptions`, `CustomBlockHostInitialState`, `CustomBlockHostInitialDataSources`, `CustomBlockHostDataSourcesPayload`, `ConnectSuccessMessage`, `CustomBlockHostHandlers`, `CustomBlockHostHandle`, `CustomBlockHostLogDirection`, `CustomBlockHostQueryDataSourceResult`, `CustomBlockHostCreatePageResult`, `CustomBlockHostGetPageResult`, `CustomBlockHostUpdatePageResult`, `CustomBlockHostGetUserResult`, and `CustomBlockHostListUsersResult`.
+Responses return a `status`-discriminated result: `"success"` carries `items` and required `hasMore`; `"error"` carries the structured `error`. Set `hasMore` to `false` when no additional results are available.
+
+Related exports: `CustomBlockHostOptions`, `CustomBlockHostInitialState`, `CustomBlockHostInitialDataSources`, `CustomBlockHostDataSourcesPayload`, `ConnectSuccessMessage`, `CustomBlockHostHandlers`, `CustomBlockHostHandle`, `CustomBlockHostLogDirection`, `CustomBlockHostQueryDataSourceResult`, `CustomBlockHostCreatePageResult`, `CustomBlockHostGetPageResult`, `CustomBlockHostUpdatePageResult`, `CustomBlockHostGetUserResult`, and `CustomBlockHostListUsersResult`.
 
 ## Bridge protocol
 

package/README.md

@@ -35,7 +35,7 @@ export function App() {
 }
 ```
 
-`<NotionCustomBlock>` runs the SDK ↔ host handshake (sends `ready` with the manifest, awaits `init`) and only mounts `children` once it resolves. Inside the wrapper, every hook returns non-nullable values — there's no separate gating component to write. It also runs `useCustomBlockAutoResize` for you by default; pass `autoResize={false}` to opt out.
+`<NotionCustomBlock>` runs the SDK ↔ host handshake (`connect` → `init` → `initResult`) and only mounts `children` once it resolves. Inside the wrapper, every hook returns non-nullable values — there's no separate gating component to write. It also runs `useCustomBlockAutoResize` for you by default; pass `autoResize={false}` to opt out.
 
 ## Reference
 
@@ -47,7 +47,9 @@ 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/manifest.md`](./docs/manifest.md) — `custom_blocks.json`, the Vite plugin, manifest types.
+- [`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).
 
 ## Forbidden APIs
 

package/dist/bridge/SandboxBridge.d.ts

@@ -9,7 +9,7 @@ import { type InitMessage } from "./messages/init.js";
  * single host needs to support multiple custom blocks built with different versions of the bridge
  * protocol. Increment this number any time a breaking change is made to the bridge protocol.
  */
-export declare const CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION = 2;
+export declare const CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION = 3;
 /**
  * A single entry in the bridge message log. Kept intentionally plain so the log
  * is copy-pasteable to a local coding agent without needing extra context.

package/dist/bridge/SandboxBridge.js

@@ -13,7 +13,7 @@ import { PendingRequests } from "./pendingRequests.js";
  * single host needs to support multiple custom blocks built with different versions of the bridge
  * protocol. Increment this number any time a breaking change is made to the bridge protocol.
  */
-export const CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION = 2;
+export const CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION = 3;
 export class SandboxBridge {
     constructor() {
         this.hostState = {

package/dist/bridge/messages/connect.d.ts

@@ -41,7 +41,7 @@ export declare const connectMessageSchema: v.VariantSchema<"status", [v.ObjectSc
     readonly error: v.ObjectSchema<{
         readonly code: v.StringSchema<undefined>;
         readonly message: v.StringSchema<undefined>;
-        readonly isRetryable: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+        readonly isRetryable: v.BooleanSchema<undefined>;
     }, undefined>;
 }, undefined>], undefined>;
 export type ConnectMessage = v.InferOutput<typeof connectMessageSchema>;

package/dist/bridge/messages/connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/connect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AA2B5B;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;IAG/B;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BASH,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA"}
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/connect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAoB5B;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;IAG/B;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BASH,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA"}

package/dist/bridge/messages/connect.js

@@ -1,4 +1,5 @@
 import * as v from "valibot";
+import { customBlockErrorInfoSchema } from "../errors.js";
 import { manifestSchema } from "../manifest.js";
 const connectMessageCommonEntries = {
     type: v.literal("connect"),
@@ -15,13 +16,6 @@ const connectMessageCommonEntries = {
      */
     sdkVersion: v.string(),
 };
-// TODO(custom-blocks): Replace with `customBlockErrorInfoSchema` which makes `isRetryable` required
-// once min supported bridge protocol version is bumped to 3.
-const connectErrorSchema = v.object({
-    code: v.string(),
-    message: v.string(),
-    isRetryable: v.optional(v.boolean(), false),
-});
 /**
  * First message the sandbox sends after mount. It identifies the sandbox and starts the bridge
  * initialization exchange. The host echoes `initializationId` in its `init` response.
@@ -38,7 +32,7 @@ export const connectMessageSchema = v.variant("status", [
     }),
     v.object({
         status: v.literal("error"),
-        error: connectErrorSchema,
+        error: customBlockErrorInfoSchema,
         ...connectMessageCommonEntries,
     }),
 ]);

package/dist/bridge/messages/sandboxToHost.d.ts

@@ -37,7 +37,7 @@ export declare const sandboxToHostMessageSchema: v.UnionSchema<[v.VariantSchema<
     readonly error: v.ObjectSchema<{
         readonly code: v.StringSchema<undefined>;
         readonly message: v.StringSchema<undefined>;
-        readonly isRetryable: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+        readonly isRetryable: v.BooleanSchema<undefined>;
     }, undefined>;
 }, undefined>], undefined>, v.VariantSchema<"status", [v.ObjectSchema<{
     readonly type: v.LiteralSchema<"initResult", undefined>;

package/dist/host/createCustomBlockHost.d.ts

@@ -11,7 +11,7 @@ import type { CustomBlockHostQueryDataSourceResult } from "./queries/types.js";
 export type CustomBlockHostOptions = {
     iframe: HTMLIFrameElement;
     targetOrigin?: string;
-    minBridgeProtocolVersion?: number;
+    minBridgeProtocolVersion: number;
     noConnectTimeoutMs?: number;
     noInitResultTimeoutMs?: number;
     initialState: CustomBlockHostInitialState;

package/dist/host/createCustomBlockHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createCustomBlockHost.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/host/createCustomBlockHost.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAc1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAA;AAM/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAA;AAazE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAIzD,OAAO,KAAK,EACX,qBAAqB,EACrB,iCAAiC,EACjC,2BAA2B,EAE3B,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EACX,uBAAuB,EACvB,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,oBAAoB,CAAA;AAE9E,MAAM,MAAM,sBAAsB,GAAG;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,YAAY,EAAE,2BAA2B,CAAA;IACzC,QAAQ,EAAE,uBAAuB,CAAA;IACjC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACpD,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACnD,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,2BAA2B,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC1E,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,IAAI,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAC7C,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IACtC,SAAS,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAA;IACzC,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,cAAc,EAAE,CAAC,WAAW,EAAE,iCAAiC,KAAK,IAAI,CAAA;IACxE,cAAc,EAAE,CAAC,WAAW,EAAE,UAAU,KAAK,IAAI,CAAA;IACjD,YAAY,EAAE,CAAC,IAAI,EAAE;QACpB,YAAY,EAAE,kBAAkB,CAAA;QAChC,QAAQ,EAAE,oCAAoC,CAAA;KAC9C,KAAK,IAAI,CAAA;CACV,CAAA;AAMD,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CA8evB"}
+{"version":3,"file":"createCustomBlockHost.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/host/createCustomBlockHost.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAc1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAA;AAM/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAA;AAazE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAIzD,OAAO,KAAK,EACX,qBAAqB,EACrB,iCAAiC,EACjC,2BAA2B,EAE3B,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EACX,uBAAuB,EACvB,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,oBAAoB,CAAA;AAE9E,MAAM,MAAM,sBAAsB,GAAG;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,wBAAwB,EAAE,MAAM,CAAA;IAChC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,YAAY,EAAE,2BAA2B,CAAA;IACzC,QAAQ,EAAE,uBAAuB,CAAA;IACjC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACpD,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACnD,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,2BAA2B,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC1E,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,IAAI,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAC7C,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IACtC,SAAS,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAA;IACzC,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,cAAc,EAAE,CAAC,WAAW,EAAE,iCAAiC,KAAK,IAAI,CAAA;IACxE,cAAc,EAAE,CAAC,WAAW,EAAE,UAAU,KAAK,IAAI,CAAA;IACjD,YAAY,EAAE,CAAC,IAAI,EAAE;QACpB,YAAY,EAAE,kBAAkB,CAAA;QAChC,QAAQ,EAAE,oCAAoC,CAAA;KAC9C,KAAK,IAAI,CAAA;CACV,CAAA;AAQD,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CA+fvB"}

package/dist/host/createCustomBlockHost.js

@@ -1,15 +1,19 @@
 import * as v from "valibot";
 import { sandboxToHostMessageSchema } from "../bridge/messages/sandboxToHost.js";
+import { CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION } from "../bridge/SandboxBridge.js";
 import { unreachable } from "../utils.js";
 import { initErrorForFailureReason } from "./lifecycle/initErrors.js";
-import { isValidBridgeProtocolVersion } from "./lifecycle/ready.js";
+import { isValidBridgeProtocolVersion } from "./lifecycle/protocolVersion.js";
 import { getInvalidSandboxMessageResponse } from "./messages/invalidSandboxMessage.js";
 import { QuerySubscriptions } from "./queries/querySubscriptions.js";
 const DEFAULT_NO_CONNECT_TIMEOUT_MS = 5000;
 const DEFAULT_NO_INIT_RESULT_TIMEOUT_MS = 5000;
-const DEFAULT_MIN_BRIDGE_PROTOCOL_VERSION = 2;
+const initializationIdentitySchema = v.object({
+    initializationId: v.string(),
+});
 export function createCustomBlockHost(options) {
-    const { iframe, initialState, handlers, onConnect, onInitResult, onLog, targetOrigin = "*", minBridgeProtocolVersion = DEFAULT_MIN_BRIDGE_PROTOCOL_VERSION, noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS, noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS, } = options;
+    const { iframe, initialState, handlers, onConnect, onInitResult, onLog, targetOrigin = "*", minBridgeProtocolVersion: configuredMinBridgeProtocolVersion, noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS, noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS, } = options;
+    const minBridgeProtocolVersion = Math.max(configuredMinBridgeProtocolVersion ?? CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION, CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION);
     let theme = initialState.theme;
     let parent = initialState.parent;
     let page = initialState.page;
@@ -286,7 +290,16 @@ export function createCustomBlockHost(options) {
             issues,
         });
         const response = getInvalidSandboxMessageResponse(data);
-        if (response.nack !== undefined) {
+        const parsedIdentity = v.safeParse(initializationIdentitySchema, data);
+        const initializationId = parsedIdentity.success
+            ? parsedIdentity.output.initializationId
+            : undefined;
+        if (initStatus === "waitingForConnect" &&
+            response.incomingType === "connect" &&
+            initializationId !== undefined) {
+            sendInitError(initializationId, initErrorForFailureReason("invalid_connect"));
+        }
+        else if (response.nack !== undefined) {
             post(response.nack);
         }
     }

package/dist/host/lifecycle/{ready.d.ts → protocolVersion.d.ts}

@@ -1,2 +1,2 @@
 export declare function isValidBridgeProtocolVersion(version: number): boolean;
-//# sourceMappingURL=ready.d.ts.map
+//# sourceMappingURL=protocolVersion.d.ts.map

package/dist/host/lifecycle/protocolVersion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocolVersion.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/host/lifecycle/protocolVersion.ts"],"names":[],"mappings":"AAAA,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAErE"}

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.0.78"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.0"

package/docs/data-sources.md

@@ -1,8 +1,10 @@
 # Data sources
 
-A custom block declares its **data sources** — semantic keys like `people` or `tasks` — in `custom_blocks.json`.
+A custom block declares its **data sources** — semantic keys like `people` or `tasks` — in the worker's `worker.customBlock(...)` configuration.
 
-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.
+The mapping from those semantic keys to concrete Notion data sources is stored on each block instance and configured in Notion.
+
+Use `ManifestDataSource`, `ManifestProperty`, and `ManifestIcon` when code needs the corresponding definition metadata types.
 
 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.
 
@@ -115,8 +117,8 @@ export function ScoreList() {
   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) {
+  const displayItems = items.filter(isComplete);
+  if (displayItems.length === 0) {
     return (
       <div>
         Map a data source with key <code>{KEY}</code> exposing <code>name</code>{" "}
@@ -128,7 +130,7 @@ export function ScoreList() {
   return (
     <div>
       <ul>
-        {ready.map((item) => (
+        {displayItems.map((item) => (
           <li key={item.id}>
             {String(item.propertiesByKey.name)} —{" "}
             {Number(item.propertiesByKey.score)}

package/docs/vite-plugin.md

@@ -0,0 +1,46 @@
+# Vite plugin
+
+The `notionCustomBlock()` plugin from `@notionhq/custom-blocks/vite` wires a block's local dev server and build output to the SDK handshake.
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { notionCustomBlock } from "@notionhq/custom-blocks/vite";
+
+export default defineConfig({
+  plugins: [react(), notionCustomBlock()],
+});
+```
+
+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.
+
+## `custom_blocks.json` and local previews
+
+`custom_blocks.json` is the block's local manifest — the data-source keys and property shapes the block expects:
+
+```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`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/custom-blocks",
-	"version": "0.0.78",
+	"version": "0.1.0",
 	"license": "MIT",
 	"type": "module",
 	"publishConfig": {
@@ -32,7 +32,6 @@
 		}
 	},
 	"bin": {
-		"ncblock": "./bin/cli/cli.js",
 		"notion-custom-blocks": "./bin/notion-custom-blocks/cli.js"
 	},
 	"scripts": {

package/src/bridge/SandboxBridge.ts

@@ -63,7 +63,7 @@ import type { NotionUser } from "./users/user.js"
  * single host needs to support multiple custom blocks built with different versions of the bridge
  * protocol. Increment this number any time a breaking change is made to the bridge protocol.
  */
-export const CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION = 2
+export const CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION = 3
 
 /**
  * A single entry in the bridge message log. Kept intentionally plain so the log

package/src/bridge/messages/connect.ts

@@ -1,4 +1,5 @@
 import * as v from "valibot"
+import { customBlockErrorInfoSchema } from "../errors.js"
 import { manifestSchema } from "../manifest.js"
 
 const connectMessageCommonEntries = {
@@ -17,14 +18,6 @@ const connectMessageCommonEntries = {
 	sdkVersion: v.string(),
 }
 
-// TODO(custom-blocks): Replace with `customBlockErrorInfoSchema` which makes `isRetryable` required
-// once min supported bridge protocol version is bumped to 3.
-const connectErrorSchema = v.object({
-	code: v.string(),
-	message: v.string(),
-	isRetryable: v.optional(v.boolean(), false),
-})
-
 /**
  * First message the sandbox sends after mount. It identifies the sandbox and starts the bridge
  * initialization exchange. The host echoes `initializationId` in its `init` response.
@@ -41,7 +34,7 @@ export const connectMessageSchema = v.variant("status", [
 	}),
 	v.object({
 		status: v.literal("error"),
-		error: connectErrorSchema,
+		error: customBlockErrorInfoSchema,
 		...connectMessageCommonEntries,
 	}),
 ])

package/src/host/createCustomBlockHost.ts

@@ -34,11 +34,12 @@ import type { UpdatePageMessage } from "../bridge/messages/updatePage.js"
 import type { UpdatePageResultMessage } from "../bridge/messages/updatePageResult.js"
 import type { CustomBlockPage } from "../bridge/pages/page.js"
 import type { NotionParent } from "../bridge/parent.js"
+import { CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION } from "../bridge/SandboxBridge.js"
 import type { NotionTheme } from "../bridge/theme.js"
 import type { NotionUser } from "../bridge/users/user.js"
 import { unreachable } from "../utils.js"
 import { initErrorForFailureReason } from "./lifecycle/initErrors.js"
-import { isValidBridgeProtocolVersion } from "./lifecycle/ready.js"
+import { isValidBridgeProtocolVersion } from "./lifecycle/protocolVersion.js"
 import type {
 	ConnectSuccessMessage,
 	CustomBlockHostDataSourcesPayload,
@@ -56,7 +57,7 @@ import type { CustomBlockHostQueryDataSourceResult } from "./queries/types.js"
 export type CustomBlockHostOptions = {
 	iframe: HTMLIFrameElement
 	targetOrigin?: string
-	minBridgeProtocolVersion?: number
+	minBridgeProtocolVersion: number
 	noConnectTimeoutMs?: number
 	noInitResultTimeoutMs?: number
 	initialState: CustomBlockHostInitialState
@@ -82,7 +83,9 @@ export type CustomBlockHostHandle = {
 
 const DEFAULT_NO_CONNECT_TIMEOUT_MS = 5_000
 const DEFAULT_NO_INIT_RESULT_TIMEOUT_MS = 5_000
-const DEFAULT_MIN_BRIDGE_PROTOCOL_VERSION = 2
+const initializationIdentitySchema = v.object({
+	initializationId: v.string(),
+})
 
 export function createCustomBlockHost(
 	options: CustomBlockHostOptions,
@@ -95,10 +98,14 @@ export function createCustomBlockHost(
 		onInitResult,
 		onLog,
 		targetOrigin = "*",
-		minBridgeProtocolVersion = DEFAULT_MIN_BRIDGE_PROTOCOL_VERSION,
+		minBridgeProtocolVersion: configuredMinBridgeProtocolVersion,
 		noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS,
 		noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS,
 	} = options
+	const minBridgeProtocolVersion = Math.max(
+		configuredMinBridgeProtocolVersion ?? CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION,
+		CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION,
+	)
 
 	let theme = initialState.theme
 	let parent = initialState.parent
@@ -418,7 +425,20 @@ export function createCustomBlockHost(
 		})
 		const response = getInvalidSandboxMessageResponse(data)
 
-		if (response.nack !== undefined) {
+		const parsedIdentity = v.safeParse(initializationIdentitySchema, data)
+		const initializationId = parsedIdentity.success
+			? parsedIdentity.output.initializationId
+			: undefined
+		if (
+			initStatus === "waitingForConnect" &&
+			response.incomingType === "connect" &&
+			initializationId !== undefined
+		) {
+			sendInitError(
+				initializationId,
+				initErrorForFailureReason("invalid_connect"),
+			)
+		} else if (response.nack !== undefined) {
 			post(response.nack)
 		}
 	}

package/bin/cli/attach.js

@@ -1,180 +0,0 @@
-import { extractId, formatUuid } from "./ids.js";
-import { ntnApi, ntnApiPatch, ntnWorkersCapabilities } from "./ntn.js";
-// ── Capability resolution ───────────────────────────────────────
-function normalizeCapabilities(raw) {
-    if (Array.isArray(raw)) {
-        return raw;
-    }
-    if (raw && typeof raw === "object") {
-        const obj = raw;
-        for (const field of ["capabilities", "results", "data"]) {
-            if (Array.isArray(obj[field])) {
-                return obj[field];
-            }
-        }
-    }
-    return [];
-}
-function capabilityKey(cap) {
-    for (const field of ["key", "name", "id"]) {
-        const value = cap[field];
-        if (typeof value === "string" && value.length > 0) {
-            return value;
-        }
-    }
-    return undefined;
-}
-function capabilityType(cap) {
-    // `ntn` reports the capability kind under `_tag`; accept `type` too in case
-    // the wire shape shifts.
-    for (const field of ["_tag", "type"]) {
-        const value = cap[field];
-        if (typeof value === "string") {
-            return value;
-        }
-    }
-    return undefined;
-}
-function isCustomBlockCapability(cap) {
-    const type = capabilityType(cap);
-    // When no type field is present we can't filter — keep it and let the
-    // count-based selection below decide.
-    if (type === undefined) {
-        return true;
-    }
-    return type === "customBlock" || type === "custom_block";
-}
-function firstString(obj, fields) {
-    for (const field of fields) {
-        const value = obj[field];
-        if (typeof value === "string" && value.length > 0) {
-            return value;
-        }
-    }
-    return undefined;
-}
-function capabilityDefinitionId(cap) {
-    const top = firstString(cap, ["definition_id", "definitionId"]);
-    if (top) {
-        return top;
-    }
-    // The real `ntn` shape nests it under `state.definitionId`.
-    const state = cap.state;
-    if (state && typeof state === "object") {
-        const nested = firstString(state, [
-            "definitionId",
-            "definition_id",
-        ]);
-        if (nested) {
-            return nested;
-        }
-    }
-    // Some shapes nest the definition under a `definition` object.
-    const definition = cap.definition;
-    if (definition && typeof definition === "object") {
-        const id = definition.id;
-        if (typeof id === "string" && id.length > 0) {
-            return id;
-        }
-    }
-    return undefined;
-}
-/**
- * Resolve a worker's custom-block capability to a `definition_id`.
- *
- * - Filters `ntn workers capabilities list` down to customBlock capabilities.
- * - With `capability` set, picks the entry with that key.
- * - With exactly one candidate, uses it.
- * - With more than one and no `capability`, errors with the available keys.
- */
-export function resolveDefinitionId(capability) {
-    const raw = ntnWorkersCapabilities();
-    const all = normalizeCapabilities(raw);
-    if (all.length === 0) {
-        console.error("Error: no worker capabilities found. Deploy the worker first with `ntn workers deploy`.\n");
-        console.error("  Raw `ntn workers capabilities list --json` output:");
-        console.error(JSON.stringify(raw, null, "\t"));
-        process.exit(1);
-    }
-    const customBlocks = all.filter(isCustomBlockCapability);
-    if (customBlocks.length === 0) {
-        console.error("Error: this worker exposes no customBlock capability to attach.\n");
-        process.exit(1);
-    }
-    let selected;
-    if (capability) {
-        const match = customBlocks.find(c => capabilityKey(c) === capability);
-        if (!match) {
-            const keys = customBlocks.map(c => capabilityKey(c) ?? "(unnamed)");
-            console.error(`Error: no customBlock capability named '${capability}'.\n`);
-            console.error(`  Available: ${keys.join(", ")}`);
-            process.exit(1);
-        }
-        selected = match;
-    }
-    else if (customBlocks.length > 1) {
-        const keys = customBlocks.map(c => capabilityKey(c) ?? "(unnamed)");
-        console.error(`Error: this worker exposes ${customBlocks.length} customBlock capabilities. Pick one with --capability <key>.\n`);
-        console.error(`  Available: ${keys.join(", ")}`);
-        process.exit(1);
-    }
-    else {
-        selected = customBlocks[0];
-    }
-    const definitionId = capabilityDefinitionId(selected);
-    if (!definitionId) {
-        console.error("Error: could not read a definition_id from the selected capability.\n");
-        console.error("  Raw capability entry:");
-        console.error(JSON.stringify(selected, null, "\t"));
-        process.exit(1);
-    }
-    return { definitionId, capabilityKey: capabilityKey(selected) };
-}
-/**
- * Body for pointing a custom block at a worker's definition. The update-block
- * endpoint requires the payload be keyed by block type — a top-level
- * `definition_id` is rejected (`should be not present`). So it nests under
- * `custom_block`, matching how `patchBlock` (datasources.ts) sets data_sources.
- */
-function definitionPatchBody(definitionId) {
-    return { custom_block: { definition_id: definitionId } };
-}
-/**
- * Point an existing custom block at a worker's customBlock definition.
- *
- * Resolves the block, verifies it's a `custom_block`, resolves the worker's
- * definition_id (erroring on ambiguity), then PATCHes the block. Returns the
- * dashed block UUID so callers (e.g. `create`) can chain.
- */
-export function attach(options) {
-    const uuid = formatUuid(extractId(options.idOrUrl));
-    if (!options.jsonOutput) {
-        console.log(`\nFetching block ${uuid}…`);
-    }
-    const block = ntnApi(`/v1/blocks/${uuid}`);
-    if (block.type !== "custom_block") {
-        console.error(`Error: block ${uuid} is type "${block.type}", not "custom_block".\n`);
-        console.error("  Pass a custom block's ID/URL, or create one with `ncblock create`.");
-        process.exit(1);
-    }
-    const { definitionId, capabilityKey: key } = resolveDefinitionId(options.capability);
-    if (!options.jsonOutput) {
-        console.log(`Attaching definition ${definitionId}${key ? ` (capability "${key}")` : ""}…`);
-    }
-    ntnApiPatch(`/v1/blocks/${uuid}`, definitionPatchBody(definitionId));
-    const emitResult = options.emitResult ?? true;
-    if (options.jsonOutput) {
-        if (emitResult) {
-            console.log(JSON.stringify({
-                action: "attach",
-                block_id: uuid,
-                definition_id: definitionId,
-                capability: key,
-            }, null, "\t"));
-        }
-    }
-    else {
-        console.log(`\n✓ Attached block ${uuid} to definition ${definitionId}\n`);
-    }
-    return uuid;
-}