@notionhq/custom-blocks-host 0.2.20 → 0.3.0

package/README.md

@@ -1,51 +1,17 @@
 # @notionhq/custom-blocks-host
 
-Host runtime for the custom block bridge. This package owns the generic `postMessage` protocol loop
-used by hosts such as the local dev shell. It does not own iframe policy, permissions, persistence,
-analytics, or host UI state. Host implementations such as the dev shell and `notion-next` depend on
-this package.
+The shared host connects an embedding application to a custom block sandbox. It loads the manifest,
+prepares initialization, validates messages, routes requests, manages query subscriptions, and
+cleans up the connection.
 
-## Standalone browser module
-
-The published package includes `dist/browser.js`, a single ES module containing the host runtime  
-and all dependencies. Load this file directly when a browser  
-must not fetch additional modules, such as under an exact-URL Content Security Policy.
-
-## `getAutoBoundPropertyIdsByKey()`
-
-`getAutoBoundPropertyIdsByKey()` matches manifest properties to schema properties for initial
-property binding. For each manifest property:
-
-1. Consider only schema properties of the same type.
-2. A schema property is a candidate if its ID equals the manifest key (exact string: no trim, no
-   case folding) or its display name equals the manifest display name after `trim()` and
-   lowercasing.
-3. Bind when there is exactly one candidate. Otherwise leave it unmapped.
-
-Wrong-type properties never enter the candidate set.
-
-```ts
-import { getAutoBoundPropertyIdsByKey } from "@notionhq/custom-blocks-host"
-
-const propertyIdsByKey = getAutoBoundPropertyIdsByKey({
-  manifestProperties: {
-    title: { name: "Task", type: "title" },
-    estimate: { name: "Estimate", type: "number" },
-  },
-  propertySchemasById: {
-    title: { name: "Different label", type: "title" },
-    "property-1": { name: " estimate ", type: "number" },
-  },
-})
-
-// { title: "title", estimate: "property-1" }
-```
+The embedding application creates the iframe and supplies permissions, record access, bindings,
+persistence, analytics, and UI. Both Notion and the dev shell use this package.
 
 ## `createCustomBlockHost()`
 
-`createCustomBlockHost()` attaches a message listener, performs the `connect` / `init` /
-`initResult` handshake, validates sandbox messages, routes requests to handlers, manages query
-subscriptions, and emits live state updates.
+Create a host before navigating its iframe to the block URL. Set `sandboxOrigin` to that URL's exact
+origin. The host accepts messages only from that iframe and origin, and targets outbound messages to
+the same origin.
 
 ```ts
 import { createCustomBlockHost } from "@notionhq/custom-blocks-host"
@@ -53,8 +19,9 @@ import { createCustomBlockHost } from "@notionhq/custom-blocks-host"
 const host = createCustomBlockHost({
   iframe,
   sandboxOrigin: "https://example.com",
-  minBridgeProtocolVersion: 3,
-  getInitialState: async () => ({
+  manifestSource: "persisted",
+  getPersistedManifest: async ({ signal }) => loadSavedManifest(signal),
+  prepareInitialState: async ({ manifest, signal }) => ({
     status: "success",
     initialState: {
       theme,
@@ -63,8 +30,9 @@ const host = createCustomBlockHost({
       parent,
       page,
       currentUser,
-      manifest,
-      dataSources: { bindings },
+      dataSources: {
+        bindings: await loadBindings(manifest, signal),
+      },
     },
   }),
   handlers: {
@@ -73,232 +41,195 @@ const host = createCustomBlockHost({
       items: await queryRows(message),
       hasMore: false,
     }),
-    createPage: async message => createPage(message),
-    getPage: async message => getPage(message),
-    openPage: async message => openPage(message),
-    updatePage: async message => updatePage(message),
-    getUser: async message => getUser(message),
-    listUsers: async message => listUsers(message),
     resize: message => resizeIframe(message.height),
   },
-  onManifest: manifest => {
-    console.log("Selected manifest", manifest)
-  },
-  onInitialized: state => {
-    console.log("Initialized manifest", state.manifest)
-  },
-  onConnectionFailure: error => {
-    showHostError(error)
-  },
+  onInitialized: state => showBlock(state),
+  onConnectionFailure: error => showHostError(error),
   onQueryUnsubscribed: undefined,
-  onLog: (direction, payload) => {
-    console.log(direction, payload)
-  },
+  onLog: (direction, payload) => console.log(direction, payload),
 })
 ```
 
-`minBridgeProtocolVersion` is optional and defaults to the oldest protocol version the host runtime
-supports. Set a higher value to retire older SDKs. Lower values cannot enable versions the runtime
-no longer supports. The host does not enforce a maximum protocol version.
-
-Each host handles one initialization handshake with one sandbox iframe:
-
-- Create the host before navigating the iframe to the sandbox URL.
-- The host accepts the first `connect` attempt and ignores subsequent `connect` messages, including
-  malformed ones. A connection after an initialization timeout does not restart it.
-- The first observed iframe `load` is allowed, including when initialization completes before it.
-- A second observed `load` stops the host and reports retryable `iframe_reloaded` through
-  `onConnectionFailure`. A reload or navigation can replace the sandbox document, so the host ends
-  the connection instead of continuing to serve the replacement.
-- Stopping removes message and load listeners, clears initialization timers, ends query
-  subscriptions, and prevents further outbound messages, including pending responses.
-- To retry or apply a deployment or configuration change, the embedder creates a new host and
-  iframe. The host does not restart automatically.
-
-The stop takes effect at the second observed load. It does not prevent navigation or isolate the
-original document before that event: a replacement document at the same origin can receive messages
-and invoke handlers until the host stops.
-
-SDKs using protocol 5 or later support unavailable page context. For older SDKs, an unavailable
-initial page fails initialization with `context_unavailable`. If page context becomes unavailable
-after initialization, the host stops and reports the same error instead of sending an unsupported
-`pageChanged` message.
-
-`getInitialState` runs after the sandbox sends `connect`. It returns a promise for the initial state
-result. The host listens immediately and sends `init` only after `getInitialState` resolves. Await
-record and binding loads inside `getInitialState`.
-
-`getInitialState` selects the manifest that the host uses. The host uses this manifest even when
-`connect` supplies another. Production hosts can select persisted definitions. Preview hosts can
-select sandbox manifests. A successful result must include a manifest. If no manifest is available,
-return `manifest_unavailable`.
-
-`getInitialState` can return `{ status: "error", error }` to stop initialization. The host converts
-a thrown error or rejected promise to `unknown_error`. If preparation exceeds
-`initialStateTimeoutMs`, the host reports `initial_state_timeout` and stops the handshake.
-
-`no_connect` means the host did not receive `connect`. `no_init_result` means the sandbox did not
-acknowledge `init`. The SDK waits for the host without its own timeout.
-
-The host discards `getInitialState` results after a timeout or stop, including a stop caused by an
-iframe reload.
-
-- `onManifest` provides the selected manifest when `getInitialState` resolves successfully, before
-  binding validation and `onInitialized`. Use it to configure bindings even when initialization
-  cannot yet succeed.
-
-- `onInitialized` reports success after the sandbox accepts initialization. It provides the selected
-  `manifest` and the sandbox's optional `initialHeight`.
-- `onConnectionFailure` reports a handshake failure, timeout, unavailable page context, or iframe
-  reload. It receives `{ phase, source, code, message, isRetryable }`. The phase identifies
-  `connect`, `init`, `initResult`, or `runtime`; the source identifies whether the host detected the
-  failure or the sandbox reported it. It can run after initialization succeeds.
-
-- `onQueryUnsubscribed` reports when a query subscription ends. Use it to release per-query
-  resources, such as listeners or timers. The host removes the subscription itself. A query failure
-  can end one subscription while the connection remains active.
-
-`queryDataSource` is required. Other request handlers are optional. Every request handler may return
-its result synchronously or as a promise. Results use a `status` discriminator: successful results
-carry their response payload, while errors carry `{ code, message, isRetryable }`.
+### Manifest and initial state
 
-### Request types
+The host starts loading the manifest when it is created. `manifestSource` determines where the
+manifest comes from:
 
-TypeScript infers request types for handlers passed to `createCustomBlockHost()`. For separately
-defined handlers and helpers, import the corresponding request and page-property types directly from
-`@notionhq/custom-blocks-host`.
+- `"persisted"` requires `getPersistedManifest({ signal })`. The callback supplies a saved block
+  definition or a dev-shell worker registry manifest.
+- `"local"` fetches `/manifest` from `sandboxOrigin`. The URL must pass
+  [`isLocalCustomBlockUrl()`](#local-block-urls) and differ from the embedding page's origin.
+  Requests omit credentials, reject redirects, bypass caches, and time out after five seconds. This
+  source has no callback or persisted fallback. Local refers to the block server, not the host's
+  environment.
 
-Adapters can pass plain string IDs in initial state, live-state setters, and handler results such as
-`CustomBlockHostGetPageResult`. The host validates these values before using or sending them.
-Parsing assigns protocol ID brands for internal type checking and applies schema defaults, such as
-an empty manifest data source `properties` map. Brands distinguish ID kinds in TypeScript. They do
-not check record existence or access.
+Hosts and SDKs use one [manifest schema](../protocol/README.md#manifests), including optional block
+metadata. The host validates and normalizes the manifest, then calls
+`prepareInitialState({ manifest, signal })` once. The embedding application uses that manifest to
+prepare context and bindings, and returns them in `initialState`. The host includes the manifest
+with that state in `init`.
 
-Request types such as `GetPageMessage` describe validated messages that handlers receive. The
-corresponding `*MessageInput` types accept plain string IDs for adapters and test fixtures that
-construct requests. These types do not validate values at runtime. The host runtime validates
-incoming messages before it calls handlers. Your implementation remains responsible for permissions
-and record access.
+Manifest loading and state preparation do not wait for `connect`. The host listens concurrently and
+sends `init` after both preparation and connection succeed. If preparation fails before `connect`,
+the host retains the failure and sends `init.error` when the sandbox connects.
 
-### Query requests
+Manifest failures produce `manifest_unavailable`. Exceptions during state preparation produce
+`unknown_error`. `onLog("warn", payload)` receives diagnostic details. User-facing manifest errors
+remain generic. Stopping the host cancels preparation without logging a cancellation warning.
 
-The `queryDataSource` handler receives raw data source and property IDs. The SDK resolves semantic
-keys before it sends a request. The runtime requires every filter and sort property ID to exist in
-`collectionSchema.propertiesById`. This map must contain only actual database properties. The SDK
-adds synthetic metadata to its separate read map, `propertySchemasById`.
+The embedding application can load saved definitions separately during local preview, for example to
+restore saved bindings after preview ends. Local initialization does not wait for those reads.
 
-For SDKs using protocol 3 or 4, the runtime adds synthetic metadata schemas to outgoing
-`collectionSchema` payloads during initialization and binding updates. Query validation still uses
-the actual database schema supplied by the host. Protocol 5 SDKs receive that schema directly and
-add the metadata read schemas themselves.
+### Connection lifecycle
 
-The runtime validates option names, Status group names, supported sort types, and ten unique sort
-properties before it invokes the handler. It checks group names against the current bound schema.
-Sorts retain their array order. Extra fields and mixed filter types fail protocol validation.
+Each host handles one handshake with one iframe:
 
-Derive bindings from the successful `connect` message inside `getInitialState` and return them in
-`initialState.dataSources`.
+```text
+sandbox connect → host init → sandbox initResult
+```
 
-Set `sandboxOrigin` to the iframe's exact origin. The runtime targets outbound messages to that
-origin and accepts inbound messages only from that iframe and origin. The runtime accepts
-`noConnectTimeoutMs`, `initialStateTimeoutMs`, and `noInitResultTimeoutMs`. All default to five
-seconds.
+The host accepts the first `connect` attempt. Later attempts do not restart initialization. Live
+updates wait for a matching `initResult.success`.
 
-### Initialization and malformed messages
+The first observed iframe `load` is allowed. A second load stops the host and reports retryable
+`iframe_reloaded`. Create a new host and iframe to retry initialization or replace the block URL.
 
-`createCustomBlockHost()` performs one handshake for each host and iframe pair:
+Stopping removes listeners, cancels preparation, clears timers, ends query subscriptions, and
+prevents further outbound messages, including pending responses. Call `stop()` when the iframe is
+removed.
 
-```text
-sandbox connect → host init → sandbox initResult
-```
+Load-event cleanup does not isolate documents before that event. A replacement document at the same
+origin can receive messages and invoke handlers until the host stops.
 
-The sandbox creates the `initializationId`. The host copies that ID into `init`. The sandbox copies
-it into `initResult`. The host sends live state changes only after it receives a matching
-`initResult.success`.
+All handshake timeouts default to five seconds:
 
-The host must check that the `initializationId` in `initResult` exactly matches the ID in the `init`
-message. The host ignores a result with a different ID. If no result arrives, or only a stale valid
-result arrives, before the timeout, initialization ends with `no_init_result`.
+| Option                  | Waits for                               | Failure code            |
+| ----------------------- | --------------------------------------- | ----------------------- |
+| `noConnectTimeoutMs`    | `connect` after the iframe's first load | `no_connect`            |
+| `initialStateTimeoutMs` | State preparation after `connect`       | `initial_state_timeout` |
+| `noInitResultTimeoutMs` | `initResult` after `init`               | `no_init_result`        |
 
-The host validates each inbound sandbox message with `sandboxToHostMessageSchema` before it handles
-the message. If parsing fails, the host uses `readIncomingType()` to identify the attempted message.
-It replies with `invalidSandboxMessage`, a negative acknowledgment (NACK). The host never sends a
-NACK in response to a NACK.
+The local manifest fetch has its own five-second timeout, starting when the host is created. The SDK
+waits for `init` without its own timeout. Handshake failures abort preparation and suppress late
+results. Asynchronous callbacks must respect their `signal`.
 
-Malformed sandbox messages do not change the host's initialization state or timeout, except in these
-two cases:
+`minBridgeProtocolVersion` defaults to the runtime's minimum supported version. A higher value
+rejects SDKs below that minimum. A lower value cannot enable unsupported versions. The host does not
+enforce a maximum protocol version.
 
-- The host expects `connect` and receives a malformed `connect` with a readable `initializationId`.
-  The host sends `init.error` instead of a NACK, then fails initialization. An invalid or
-  unsupported numeric protocol version takes precedence over `invalid_connect_payload`.
-- The host expects `initResult` and receives a malformed `initResult` with the active
-  `initializationId`. The host sends a NACK and fails initialization with
-  `invalid_init_result_payload`. This error code describes a local host failure. The host does not
-  send it in `initResult.error`.
+Unavailable page context requires protocol 5. With protocols 3 and 4, an unavailable page produces
+`context_unavailable` during initialization or ends an active connection.
 
-A malformed `initResult` with a missing or stale ID does not end initialization or reset its
-timeout. Malformed messages do not restart initialization after it succeeds or fails.
+### Callbacks
 
-The host accepts a valid `initResult.error` as a terminal initialization failure. It logs and
-ignores a valid `initResult` with a stale `initializationId` or an unexpected state.
+- `onInitialized({ manifest, initialHeight })` runs after the sandbox accepts initialization. The
+  height is optional.
+- `onConnectionFailure(error)` reports a handshake failure, timeout, unavailable page context, or
+  iframe reload. The error contains `{ phase, source, code, message, isRetryable }`. `phase` is
+  `connect`, `init`, `initResult`, or `runtime`. `source` identifies the host or sandbox that
+  reported the failure. This callback can run after initialization succeeds.
+- `onQueryUnsubscribed(subscriptionId)` releases application resources when a subscription ends. The
+  host removes the subscription itself. The callback runs for unsubscribe, replacement, terminal
+  error, or host stop, once per ended subscription.
+- `onLog(direction, payload)` receives bridge messages and warnings. The embedding application
+  chooses where to record them.
+
+### Request types
 
-The host does not retry malformed messages.
+`queryDataSource` is required. Other request handlers are optional. Handlers return a result
+synchronously or as a promise. Successful results carry their response payload. Errors carry
+`{ code, message, isRetryable }`; error codes are open strings.
+
+TypeScript infers handler request types. Separately defined handlers can import request and
+page-property types from `@notionhq/custom-blocks-host`.
+
+Request types such as `GetPageMessage` describe validated messages. Corresponding `*MessageInput`
+types accept plain string IDs for callers that construct requests. Initial state, live setters, and
+handler results also accept plain string IDs. The runtime validates these values and applies schema
+defaults. ID brands distinguish ID kinds in TypeScript; they do not check record existence or
+access. The embedding application enforces permissions and record access.
+
+### Query requests
+
+The SDK resolves semantic data-source and property keys to raw IDs before sending requests. The host
+validates filters and sorts against actual database properties in `collectionSchema.propertiesById`
+before invoking `queryDataSource`. Status group names and option names must match the bound schema.
+Sorts retain their order and contain at most ten unique properties.
+
+The SDK exposes synthetic metadata through its separate `propertySchemasById` read map. For
+protocols 3 and 4, the host adds synthetic metadata to outgoing `collectionSchema` payloads.
+Protocol 5 SDKs add those read schemas themselves. Host query validation always uses the actual
+database schema.
+
+### Initialization and malformed messages
+
+The host validates inbound messages, correlates handshake IDs, and rejects malformed requests.
+Malformed messages do not restart initialization. The host logs and ignores stale valid `initResult`
+messages.
+
+See the protocol's [initialization contract](../protocol/README.md#initialization) and
+[validation and error rules](../protocol/README.md#validation-and-errors) for message shapes and
+failure behavior.
 
 ## Updating live state
 
-The returned handle exposes:
-
-- `setTheme()`
-- `setContrastMode()`
-- `setParent()`
-- `setPage()`
-- `setDataSources()`
-- `setCurrentUser()`
-- `refreshQuery()`
-- `stop()`
-
-State updates are sent after `initResult.success`. Updates made earlier are held until
-initialization completes. `refreshQuery()` re-runs `queryDataSource` for every active subscription
-with the supplied data source ID, preserving each subscription's filter, sorts, and limit. If that
-query is already running, refresh requests coalesce into one follow-up query. The running query
-delivers its snapshot before the follow-up starts, so continuous changes do not starve updates.
-Unsubscribing, replacing the query, or stopping the host discards its queued refresh.
-
-After `stop()`, the host drops outbound messages, including pending request responses. The runtime
-removes a subscription when it receives `unsubscribeDataSourceQuery`. Repeated unsubscribe messages
-are safe. The runtime also ignores results from a query that was unsubscribed while its handler was
-running.
-
-A non-retryable query error ends the subscription and discards any queued refresh. This includes
-validation errors before the query handler runs. Retryable errors retain the subscription.
-
-Use `onQueryUnsubscribed(subscriptionId)` to release adapter resources such as collection listeners.
-The callback runs when a subscription ends through an explicit unsubscribe, replacement, terminal
-error, or host stop. Repeated removal of the same subscription does not repeat the callback. A late
-result from a replaced query cannot remove its replacement. The sandbox still receives the terminal
-error result.
-
-Call `stop()` when the iframe is removed. It detaches listeners, clears timeouts, and discards
-active query subscriptions.
+The returned handle exposes `setTheme()`, `setContrastMode()`, `setParent()`, `setPage()`,
+`setDataSources()`, `setCurrentUser()`, `refreshQuery()`, and `stop()`.
 
-## Wire protocol
+State updates made during initialization are held until `initResult.success`. Updates after that
+point are sent to the sandbox.
+
+`refreshQuery()` re-runs `queryDataSource` for each active subscription with the supplied data
+source ID, preserving its filter, sorts, and limit. Overlapping refreshes queue one follow-up query.
+The running query delivers its result before the follow-up starts.
+
+Unsubscribe, replacement, and host stop discard queued refreshes and suppress late results.
+Non-retryable query errors also end the subscription. Retryable errors retain it. A failed query can
+end its subscription while the connection stays active.
+
+## Local block URLs
+
+`isLocalCustomBlockUrl(url: URL)` accepts HTTP(S) URLs on `localhost`, any `.localhost` subdomain,
+or `127.0.0.1`, without a username or password. Both the shared host and the dev shell use this
+policy. The helper does not enforce origin isolation. Local manifest fetching separately rejects the
+embedding page's own origin.
+
+## `getAutoBoundPropertyIdsByKey()`
+
+`getAutoBoundPropertyIdsByKey()` matches manifest properties to database properties for initial
+bindings. A candidate must have the same property type and either:
+
+- An ID that exactly equals the manifest key, without trimming or case folding.
+- A display name that equals the manifest display name after trimming and lowercasing.
 
-`createCustomBlockHost()` implements the protocol: it validates inbound messages, runs the
-initialization handshake, correlates requests, manages query subscriptions, and emits bridge NACKs.
-Use its state-update methods and handlers instead of posting bridge messages directly.
+Exactly one candidate produces a binding. Zero or multiple candidates leave the property unmapped.
 
-The bridge protocol is maintained in this repository's `protocol/` package. The published host
-package includes a compiled copy of that protocol and does not expose it as a public subpath.
-Consumers should use the host APIs above instead of importing protocol implementation files.
+```ts
+import { getAutoBoundPropertyIdsByKey } from "@notionhq/custom-blocks-host"
 
-Host source in this repository imports protocol schemas and types from the workspace package. The
-publish build rewrites those imports to the bundled copy.
+const propertyIdsByKey = getAutoBoundPropertyIdsByKey({
+  manifestProperties: {
+    title: { name: "Task", type: "title" },
+    estimate: { name: "Estimate", type: "number" },
+  },
+  propertySchemasById: {
+    title: { name: "Different label", type: "title" },
+    "property-1": { name: " estimate ", type: "number" },
+  },
+})
+
+// { title: "title", estimate: "property-1" }
+```
 
-Handler implementations must preserve message identity: one-shot operations return one result with
-the request's `requestId`, while `queryDataSource` is a long-lived subscription keyed by
-`subscriptionId`. The runtime handles the `connect` → `init` → `initResult` lifecycle, including
-waiting for `initResult.success` before live updates.
+## Standalone browser module
+
+The published package includes `dist/browser.js`, a single ES module with all dependencies. Load
+this file directly when the browser must not fetch additional modules, such as under an exact-URL
+Content Security Policy.
+
+## Wire protocol
 
-Error payloads use `{ code, message, isRetryable }`. The runtime accepts any string for `code`,
-including codes that this package does not know yet. Host code should preserve unknown codes and use
-`isRetryable` to decide whether a retry is appropriate.
+The host package bundles the shared [protocol](../protocol/README.md) and exposes its public types.
+Use the host APIs instead of posting bridge messages directly or importing protocol implementation
+files. Runtime source imports schemas from the workspace protocol package; the publish build bundles
+that dependency into the host package.