@notionhq/custom-blocks-host 0.3.8 → 0.4.0

package/docs/bridge/protocol.md

@@ -0,0 +1,182 @@
+# Bridge wire protocol
+
+The bridge carries initialization, data requests, results, and live updates between a custom block's
+SDK and its host. This reference defines the handshake, message identity, validation, and payload
+semantics for host integrators and bridge maintainers. Block authors use the SDK's public APIs.
+
+Messages are `postMessage` payloads defined by shared Valibot schemas, exposed through
+`@notionhq/custom-blocks-host/protocol`. The embedding application enforces permissions and record
+access. Version-specific formats and conversions are described in
+[Versioning and compatibility](versioning.md).
+
+## Initialization
+
+The handshake is:
+
+```text
+sandbox connect → host init → sandbox initResult
+```
+
+All three messages carry the sandbox-generated `initializationId`. A sandbox document sends
+`connect` once. The host sends one `init` for the accepted connection and ignores subsequent
+`connect` messages, including malformed ones. Live updates wait for `initResult.success`.
+`init.error` and `initResult.error` are terminal.
+
+The sandbox waits for `init` without a timeout. If host state preparation times out, the host sends
+`init.error` with `initial_state_timeout` to end that wait.
+
+`connect` carries connection identity, version metadata, and an optional local manifest declaration.
+The SDK reads that declaration from the `application/json` script with ID
+`notion-custom-block-manifest`, injected into the block HTML by dev tooling. It reads metadata only
+from supported local block server URLs. Missing metadata omits `connect.manifest`; invalid metadata
+sends `connect.error` with `manifest_invalid`.
+
+The embedding application selects the manifest source. In host mode, the host uses its persisted
+manifest and ignores the sandbox declaration. In sandbox mode, the host uses `connect.manifest` from
+a permitted local sandbox; a missing declaration produces `manifest_unavailable`. The selected
+manifest is authoritative and is returned in `init` with context and data-source bindings. Errors
+from the selected manifest source pass through unchanged. Host mode can initialize after a sandbox
+`manifest_invalid` error using its own manifest; other connect errors remain fatal. The connect
+parser discards unknown properties.
+
+`initResult.success` may include `initialHeight`, the height of the sandbox's rendered content in
+CSS pixels. The host's [lifecycle guide](../lifecycle.md) describes iframe sizing,
+reveal, and retry behavior.
+
+`connect.bridgeProtocolVersion` declares the sandbox's wire contract. `sdkVersion` is analytics
+metadata. See [versioning and compatibility](versioning.md) for supported formats and
+[Validation and errors](#validation-and-errors) for malformed handshake behavior.
+
+## Manifests
+
+A manifest declares a block's data sources and display metadata. `manifestSchema` defines its fields
+and defaults omitted `dataSources` and each data source's omitted `properties` to `{}`.
+
+`isLocalBlockServerUrl(url)` accepts HTTP(S) URLs on `localhost`, `*.localhost`, or `127.0.0.1`
+without credentials. It checks the address only. The host also requires a sandbox-mode block to use
+a different origin from its embedding page.
+
+## Message identity
+
+- One-shot request/result pairs use `requestId`.
+- `queryDataSource` is a long-lived subscription; requests and every update use its stable
+  `subscriptionId`.
+- The initialization lifecycle uses `initializationId`, not `requestId` or `subscriptionId`.
+- One-way messages, such as `resize` and bridge NACKs, have no correlation ID.
+
+Hosts key query state by `subscriptionId`, replace state when a request reuses one, and suppress
+stale asynchronous results.
+
+The sandbox can send `unsubscribeDataSourceQuery` with the same `subscriptionId` when it no longer
+needs the subscription. An unknown or repeated unsubscribe is a no-op. Hosts stop future refreshes
+and suppress results from work already in progress.
+
+## Validation and errors
+
+Each direction has a validation schema:
+
+- Sandbox to host: `sandboxToHostMessageSchema`
+- Host to sandbox: `hostToSandboxMessageSchema`
+
+On parse failure, the host replies with `invalidSandboxMessage` and the sandbox replies with
+`invalidHostMessage`, except for the handshake cases below. These replies are negative
+acknowledgments (NACKs). Receivers do not NACK another NACK.
+
+Malformed sandbox messages do not change the host's initialization state or timeout, except as
+follows:
+
+- 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`.
+
+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.
+
+The sandbox handles a malformed `init` differently if it can verify the `initializationId`. In that
+case, it sends `initResult.error` with `invalid_init_payload` instead of a NACK. Otherwise, it sends
+`invalidHostMessage`.
+
+`CustomBlockErrorInfo` carries `code`, `message`, and `isRetryable`. Error schemas accept any string
+for `code`, including unknown codes. TypeScript aliases list known codes for autocomplete.
+
+## Data sources
+
+### Bindings and IDs
+
+Hosts send `NotionDataSourceBindings` as `dataSources: { bindings }`, keyed by the semantic data
+source key declared in the manifest. `collectionSchema` contains only actual database properties.
+
+Sandbox-to-host object references are raw IDs. The SDK resolves semantic data-source and property
+keys before sending query or page-operation requests. Get and update requests can carry an optional
+resolved `dataSourceId`.
+
+### Query requests
+
+`queryDataSource` may include a resolved `filter` and an ordered `sorts` list. Each sort contains a
+raw `propertyId` and an `ascending` or `descending` direction. Hosts apply sorts in array order. The
+SDK and host validate that the list contains at most ten unique properties. The host rejects
+property types without a supported sort value.
+
+Every filter and sort property ID must exist in `collectionSchema.propertiesById`. Queries with
+filters or sorts return `data_source_schema_unavailable` when the schema is unavailable. Filter
+branches, operators, person references, and sort objects reject extra fields.
+
+#### Creator and status filters
+
+Creator filters require `propertyId` to identify an actual database property of type `created_by`.
+The `created_by` filter branch selects the property type, while `propertyId` addresses the column.
+
+The `created_by` filter supports human user targets with `contains` and `does_not_contain`, plus
+`is_empty` and `is_not_empty`. Hosts use row creator metadata, including non-human and missing
+creators in exclusion results.
+
+Status filters support option operators and stored group names. Group operators accept one name or
+an array of 1–5 names. Hosts must validate each name against the bound Status property.
+
+#### Date filters
+
+Date comparisons accept ISO values and relative values such as `today`. The query schema defines the
+accepted values and range operators. Range operators require an empty object.
+
+Date comparisons accept `target` inside `date`, beside the operator. The target is `start_date` by
+default. For ranges, `end_date` compares the range end. For individual dates, it compares the date.
+Empty checks accept either target, but they test the whole property.
+
+```ts
+filter: {
+	propertyId: "schedule-id",
+	date: { target: "end_date", on_or_after: "2026-10-08" },
+}
+```
+
+## Page context
+
+Containing-page context uses `CustomBlockPage`. The `init.page` and `pageChanged.page` fields
+contain `{ type: "page", id, parent }` for an accessible page, or `{ type: "unavailable" }` when the
+containing page itself is inaccessible. The unavailable shape never carries a page ID. This is
+distinct from an accessible page with an inaccessible parent
+(`page.parent: { type: "unavailable" }`).
+
+## Page writes
+
+The `createPage` and `updatePage` messages use raw property IDs from Notion as map keys. Each value
+must carry the same raw property ID in its `id` field.
+
+## Page responses
+
+Host handlers return unified `NotionPageData` for queries and page operations. Properties use
+display names as keys and typed values that include their raw property IDs. Only actual schema
+properties are returned. Query results contain `items` and `hasMore`. `notionPageDataSchema` defines
+the page fields, including archive state and creation, edit, and visit metadata.
+
+Page reads return string values for `unique_id`, `formula`, `rollup`, `button`, `verification`, and
+`location`, preserving each property's type. These properties are read-only. Values use stored text,
+or `""` when absent. Hosts do not evaluate formulas or rollups.
+
+The host converts responses to the sandbox's declared protocol. See
+[versioning and compatibility](versioning.md) for protocol version rules. The host's
+[compatibility reference](../compatibility.md) describes older response formats.

package/docs/bridge/versioning.md

@@ -0,0 +1,38 @@
+# Bridge protocol versioning
+
+The SDK inside a block and the host in its embedding application release independently. A bridge
+protocol version identifies the wire contract they use, independently of their package versions.
+This reference defines the version identifiers, protocol format names, and rules for contract
+changes. Release boundaries and exceptions are recorded in the [changelog](changelog.md). The host's
+[compatibility reference](../compatibility.md) describes runtime support and response
+conversions.
+
+## Version identifiers
+
+- **Bridge protocol:** `connect.bridgeProtocolVersion` declares the sandbox's wire contract.
+- **SDK package:** identifies the SDK's public API and implementation. It can change without a wire
+  change.
+- **Host package:** identifies the runtime implementation. Publishing it does not deploy it to
+  Notion.
+
+`connect.bridgeProtocolVersion` selects the wire contract. `sdkVersion` is analytics metadata.
+`LATEST_BRIDGE_PROTOCOL_VERSION` identifies the latest contract defined by the package.
+
+## Protocol export names
+
+The `@notionhq/custom-blocks-host/protocol` entrypoint exports wire definitions. Page formats used
+by protocols 3–5 are named `NotionPageForProtocol3To5` and `NotionDataSourcePageForProtocol3To5`,
+with matching `notionPageForProtocol3To5Schema` and `notionDataSourcePageForProtocol3To5Schema`
+validators. Message types and schemas containing `WithProtocol3To5Compatibility` accept both current
+page formats and protocol 3–5 page formats. `UNIFIED_PAGE_PROTOCOL_VERSION` is 6, the minimum
+protocol version that uses unified pages.
+
+## Version changes
+
+A breaking wire change increases the bridge protocol version. This includes changed meanings,
+required fields, and new response variants an older receiver rejects. Optional fields and new
+messages need no bump only when older receivers can safely ignore or NACK them. Parsing success
+alone does not prove compatible SDK behavior.
+
+An SDK that requires a newer protocol needs a host that supports that contract. Updating the SDK
+package does not update the host in the embedding application.

package/docs/compatibility.md

@@ -0,0 +1,68 @@
+# Host compatibility
+
+A host can update while deployed blocks keep older SDKs. The runtime accepts supported protocol
+versions and converts current handler results to each block's declared contract. This reference
+covers version admission, normalization, and the formats sent to older blocks. Protocol version
+rules and release history are in the [versioning guide](bridge/versioning.md) and
+[changelog](bridge/changelog.md).
+
+## Supported versions
+
+The protocol subpath exports `LATEST_BRIDGE_PROTOCOL_VERSION` and
+`MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION`. These constants define the package's latest known
+protocol and runtime minimum. Embedders can raise the minimum but cannot enable retired versions.
+The host admits future positive integer versions and validates them against known schemas. Admission
+does not guarantee that future features work.
+
+`sdkVersion` is analytics metadata. Compatibility behavior depends on the protocol version.
+
+The current SDK declares protocol 8. The shared runtime minimum is 3. The dev shell uses the Worker
+manifest in host mode and accepts the shared runtime's supported protocol versions. Protocols 7 and
+8 use the same page and query response formats. Protocol 8's local manifest declaration is selected
+only in sandbox mode; host mode uses the persisted manifest. See the
+[protocol 8 release entry](bridge/changelog.md#protocol-8-local-manifest-declarations).
+
+The `minBridgeProtocolVersion` option defaults to the runtime minimum. Raising the option rejects
+older SDKs for this embedding application. Lowering it cannot restore retired versions. Raising
+`MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION` retires those versions across the runtime.
+
+## Host normalization
+
+The host validates sandbox requests before dispatching them to handlers. Handlers use current data
+shapes, and the host converts responses to the sandbox's declared protocol. Setters, query
+refreshes, and handler responses use the same conversion. Unchanged messages and errors pass
+through.
+
+## Current compatibility behavior
+
+| Target | Query results                                                               | Page operation results                                        | Binding schemas                                                          |
+| ------ | --------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| 3–4    | Flat ID-keyed values, including synthetic metadata entries                  | ID-keyed properties with unsupported property objects omitted | Synthetic metadata read schemas restored in outgoing copies              |
+| 5      | Same query values as protocols 3–4                                          | Same page format as protocols 3–4                             | Actual database schemas. The SDK supplies synthetic read schemas locally |
+| 6      | Unified name-keyed properties. Text fallback property objects become `null` | Same unified page format                                      | Actual database schemas                                                  |
+| 7+     | Unified pages with typed text fallback properties                           | Same unified page format                                      | Actual database schemas                                                  |
+
+The synthetic metadata IDs are `created_time`, `last_edited_time`, `created_by`, and
+`last_edited_by`. They retain metadata meaning if an actual property uses the same raw ID. This
+matches the protocol 3–4 binding schema precedence. Host validation always uses the unmodified
+actual database schema.
+
+Release-specific compatibility limits are documented in the changelog entries for
+[protocol 5 page context](bridge/changelog.md#protocol-5-unavailable-containing-page-context)
+and
+[protocol 6 text fallback properties](bridge/changelog.md#protocol-6-richer-fallback-properties).
+
+### Unavailable containing-page context
+
+Protocols 3–4 receive `context_unavailable` during initialization or stop when containing-page
+context becomes unavailable. This concerns `init.page` and `pageChanged.page`, not a page
+operation's `page_unavailable` error.
+
+### Protocol 3–5 metadata query semantics
+
+Page creation and edit metadata is readable without corresponding database columns. Current page
+objects carry these fields at the top level. Protocol 3–5 query adapters copy them into
+`propertiesById` for older SDKs.
+
+Filters and sorts require actual database properties in the bound schema. The host does not support
+queries against synthetic metadata IDs without corresponding database properties.

package/docs/handlers.md

@@ -0,0 +1,199 @@
+# Host handlers and data
+
+Handlers connect block requests to your application's data access, persistence, and navigation. The
+runtime validates bridge messages and manages subscriptions. Your application enforces viewer
+permissions and implements the requested operations. This guide covers handler contracts, a
+data-source example, refreshes, and external navigation.
+
+The [dev shell](https://www.npmjs.com/package/@notionhq/custom-blocks-dev-shell) is a working host
+implementation with local sample data. Use it as a reference for a larger integration. Production
+hosts must provide their own permissions, data access, and persistence.
+
+## Handler contracts
+
+`queryDataSource` is required. Other handlers are optional. Omitting a one-shot request handler
+sends no response to that request. A handler returns a result synchronously or as a promise. Errors
+carry `{ code, message, isRetryable }`, with open string codes.
+
+Handler requests are validated messages with branded IDs. Initial state, setters, handler results,
+and `*MessageInput` types accept plain string IDs. The runtime validates these inputs and applies
+schema defaults. ID brands do not check record existence or access.
+
+Query filters and sorts are validated against the actual bound database schema before
+`queryDataSource` runs. See the [wire reference](bridge/protocol.md#data-sources) for
+query semantics.
+
+## Connect a data source
+
+Connect an embedded block to an in-memory Tasks data source with one numeric Estimate property. This
+walkthrough extends the [README's embed example](../README.md#create-a-host): declare the data
+source, bind its keys to IDs, return a query result, and refresh that result after a value changes.
+
+Keep the iframe, context, and lifecycle callbacks from the embed example. The block must declare the
+same manifest and query `tasks` through the SDK's public APIs.
+
+### Declare and bind the data source
+
+The manifest uses block-defined keys. Bindings connect those keys to actual data-source and property
+IDs. Add these definitions before creating the host:
+
+```ts
+import type {
+  CustomBlockHostDataSourcesPayload,
+  CustomBlockHostHandlers,
+} from "@notionhq/custom-blocks-host"
+import type { CustomBlockManifest, NotionPageData } from "@notionhq/custom-blocks-host/protocol"
+
+const tasksId = "44444444-4444-4444-8444-444444444444"
+
+const manifest: CustomBlockManifest = {
+  version: 1,
+  dataSources: {
+    tasks: {
+      name: "Tasks",
+      properties: {
+        estimate: { name: "Estimate", type: "number" },
+      },
+    },
+  },
+}
+
+const taskBindings: CustomBlockHostDataSourcesPayload = {
+  bindings: {
+    tasks: {
+      collectionPointer: { table: "collection", id: tasksId },
+      collectionSchema: {
+        propertiesById: {
+          "estimate-id": { name: "Estimate", type: "number" },
+        },
+      },
+      propertyIdsByKey: { estimate: "estimate-id" },
+    },
+  },
+}
+```
+
+In the embed example, return `{ status: "success", manifest }` from `getPersistedManifest` and
+replace `initialState.dataSources` with `taskBindings`. Here, `tasks` and `estimate` are semantic
+keys; `tasksId` and `estimate-id` identify the bound data source and property.
+
+### Return query results
+
+Add this handler and use it as the embed example's `handlers.queryDataSource`. Keep its existing
+`resize` handler.
+
+```ts
+let estimate = 3
+
+const handlers: CustomBlockHostHandlers = {
+  queryDataSource: message => {
+    if (message.dataSourceId !== tasksId) {
+      return {
+        status: "error",
+        error: {
+          code: "unmapped_data_source",
+          message: "This data source is not available.",
+          isRetryable: false,
+        },
+      }
+    }
+
+    if (message.filter || message.sorts?.length) {
+      return {
+        status: "error",
+        error: {
+          code: "invalid_data_source_query",
+          message: "This demo supports only unfiltered, unsorted queries.",
+          isRetryable: false,
+        },
+      }
+    }
+
+    const items: NotionPageData[] = [
+      {
+        object: "page",
+        id: "55555555-5555-4555-8555-555555555555",
+        parent: { type: "data_source_id", data_source_id: tasksId },
+        is_archived: false,
+        in_trash: false,
+        properties: {
+          Estimate: { id: "estimate-id", type: "number", number: estimate },
+        },
+      },
+    ]
+
+    return {
+      status: "success",
+      items: items.slice(0, message.limit),
+      hasMore: items.length > message.limit,
+    }
+  },
+}
+```
+
+The SDK resolves `tasks` to `tasksId` before the host receives the request. Result properties use
+display names as keys (`Estimate`) and include their raw property IDs (`estimate-id`). The runtime
+handles subscription IDs, validates results, and converts them for supported older SDKs.
+
+This demo rejects filters and sorts rather than silently ignoring them. A production adapter must
+enforce record access, execute the requested filter and sorts, and honor the result limit. See
+[query semantics](bridge/protocol.md#data-sources).
+
+## Refresh active queries
+
+After creating the host, update the in-memory value and notify active subscriptions:
+
+```ts
+estimate = 5
+host.refreshQuery({ dataSourceId: tasksId })
+```
+
+If the block has an active query for Tasks, its next result contains an estimate of `5`. A query
+started later also reads the updated value. The application triggers refreshes when its underlying
+data changes; the runtime re-runs matching subscriptions. Call `host.stop()` when removing the
+embed.
+
+`refreshQuery()` re-runs active subscriptions for the supplied data-source ID with their existing
+filter, sorts, and limit. Overlapping refreshes queue one follow-up query. The running query
+delivers its result first. Unsubscribe, replacement, and stop discard queued work and suppress late
+results. Non-retryable query errors end subscriptions. Retryable errors retain them.
+
+## Page and user operations
+
+`createPage`, `getPage`, and `updatePage` connect page requests to your application's data access
+and persistence. `getUser` and `listUsers` supply user data. Each handler returns a success payload
+or an error. The runtime adds the request's correlation ID and sends the response. The application
+enforces record access before reading or writing data.
+
+`openPage` handles navigation to a Notion page. `resize` receives the block's requested height in
+CSS pixels. The application owns navigation and iframe sizing.
+
+## External navigation
+
+`openExternalUrl` receives an `AbortSignal` and an absolute HTTP or HTTPS URL without credentials.
+The URL is limited to 2,048 JavaScript code units before and after normalization. The adapter
+displays the exact URL, obtains approval, and navigates only after approval. It may apply further
+restrictions. Dismiss pending confirmation UI when the signal aborts.
+
+Each iframe permits one pending navigation. A different request receives `pending_navigation`. A
+duplicate of the active request is ignored. Completed requests are forgotten, so later requests
+require fresh approval. The runtime redacts the URL from `onLog` payloads and suppresses results
+after stop.
+
+## Property binding
+
+`getAutoBoundPropertyIdsByKey({ manifestProperties, propertySchemasById })` requires matching
+property types and either an exact raw ID match or a display-name match after trimming and
+lowercasing. IDs are not trimmed or case-folded. Exactly one candidate creates a binding. Zero or
+multiple candidates leave the property unmapped. The result maps manifest property keys to database
+property IDs. An ID match has no priority over a name match: if they identify different compatible
+properties, the manifest property stays unmapped.
+
+## Date conversion and types
+
+`toNotionDateValue()` converts `NotionDateInput` into the four `CustomBlockDateValue` variants,
+including reminders. Invalid input throws `InvalidNotionDateError`.
+
+The root exports host configuration, handlers, results, and `*MessageInput` types. Wire schemas,
+message and page types, and constants such as `LATEST_BRIDGE_PROTOCOL_VERSION` use the
+[protocol subpath](../README.md#protocol-schemas-and-types).

package/docs/lifecycle.md

@@ -0,0 +1,117 @@
+# Host initialization and lifecycle
+
+The host prepares a block's manifest and context, completes initialization, and manages the
+connection until the iframe is removed. This reference covers state preparation, timeouts,
+callbacks, live state, and cleanup. Start with the [embed example](../README.md#create-a-host).
+
+## Manifest and initial state
+
+Pass the full block URL as `sandboxUrl`. The host derives the origin used to authenticate incoming
+messages and target outgoing messages. `CustomBlockManifestSource` selects the manifest:
+
+| `manifestSource` | Manifest source                                                                                            |
+| ---------------- | ---------------------------------------------------------------------------------------------------------- |
+| `"host"`         | The manifest returned by `getPersistedManifest({ signal })`                                                |
+| `"sandbox"`      | The local declaration supplied in `connect.manifest`, subject to the [local URL policy](#local-block-urls) |
+
+`getPersistedManifest` is required in both modes and starts when the host is created. It returns
+`CustomBlockHostManifestResult`: either `{ status: "success", manifest }` or
+`{ status: "error", error }`. It must not resolve to `null` or `undefined`. A definition that is
+still loading keeps the promise pending; a failed load returns an error result. The host validates
+the result and normalizes the manifest before calling `prepareInitialState`. Omitted `dataSources`
+and each source's omitted `properties` default to `{}`.
+
+The sandbox loads independently and sends `connect`. In sandbox mode, the SDK reads the manifest
+from JSON metadata injected into the local block HTML by dev tooling. The host validates the
+declaration in `connect`. The two sources do not wait for each other; only the selected result
+determines initialization. Sandbox mode has no persisted fallback. The
+[wire reference](bridge/protocol.md#initialization) describes the declaration and its
+validation errors.
+
+Once the selected manifest is ready, the host calls `prepareInitialState({ manifest, signal })`
+once. Return `{ status: "success", initialState }` with context and data-source bindings, or
+`{ status: "error", error }`. This callback also must not resolve to `null` or `undefined`. The host
+validates its result. The prepared state omits the manifest; the host adds the selected manifest to
+`init`. Host-mode preparation runs concurrently with connection setup. Sandbox-mode preparation
+starts after `connect` supplies the declaration. The host sends `init` after preparation and a valid
+connection succeed. A preparation failure is retained until the sandbox connects.
+
+Errors from the selected manifest source retain their `code`, `message`, and `isRetryable`. A
+missing sandbox declaration produces `manifest_unavailable`. A sandbox `manifest_invalid` error is
+ignored in host mode because that mode uses the persisted manifest; other connect errors remain
+fatal. Unexpected exceptions or invalid results from either callback produce `unknown_error`.
+Diagnostics go to `onLog("warn", payload)`. Stopping aborts preparation and suppresses late results
+without a cancellation warning.
+
+## Timeouts
+
+| Option                  | Waits for                             | Default   | Failure code            |
+| ----------------------- | ------------------------------------- | --------- | ----------------------- |
+| `noConnectTimeoutMs`    | `connect` after the first iframe load | 5 seconds | `no_connect`            |
+| `initialStateTimeoutMs` | State preparation after `connect`     | 5 seconds | `initial_state_timeout` |
+| `noInitResultTimeoutMs` | `initResult` after `init`             | 5 seconds | `no_init_result`        |
+
+The SDK waits for `init` without its own timeout. Handshake failures abort preparation and suppress
+late results. Manifest and state preparation providers must respect their `signal`.
+
+## Live state
+
+`setTheme()`, `setContrastMode()`, `setParent()`, `setPage()`, `setDataSources()`, and
+`setCurrentUser()` hold updates during initialization and send them after `initResult.success`. For
+data-source query refreshes, see [Handlers and data](handlers.md#refresh-active-queries).
+
+## Callbacks
+
+The required `onStatusChange(state)` callback receives the `CustomBlockHostStatus` union:
+
+| Status                 | Behavior                                                       | Payload                                                |
+| ---------------------- | -------------------------------------------------------------- | ------------------------------------------------------ |
+| `waitingForConnect`    | The host is listening; reported synchronously during creation  | None                                                   |
+| `preparingInit`        | The host accepted a connection and is preparing initialization | `localManifest`, `sdkVersion`, `bridgeProtocolVersion` |
+| `waitingForInitResult` | Successful `init` was sent; acknowledgment is pending          | None                                                   |
+| `initialized`          | The sandbox accepted initialization                            | `resolvedManifest`, optional `initialHeight`           |
+| `failed`               | Initialization or runtime failed                               | `error`                                                |
+| `stopped`              | The application explicitly disposed of the host                | None                                                   |
+
+`localManifest` is optional and comes only from a permitted local sandbox. It is available before
+initialization completes, so an adapter can use its requirements to prepare bindings.
+`resolvedManifest` is the selected declaration sent in `init`. Rejected connections can skip
+intermediate statuses. Both `failed` and `stopped` are terminal; stopping a failed host releases
+resources without replacing its failure status.
+
+Connection failures contain `{ phase, source, code, message, isRetryable }`. The phase is `connect`,
+`init`, `initResult`, or `runtime`. The source identifies who reported the failure. Failures can
+occur after initialization succeeds.
+
+At `initialized`, apply a supplied `initialHeight` in CSS pixels before revealing the iframe. If the
+height is absent, use your application's default size. The `resize` handler applies later height
+changes. Reveal, sizing, and failure UI belong to the embedding application.
+
+| Other callback                        | Behavior                                                                                     |
+| ------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `onQueryUnsubscribed(subscriptionId)` | Runs once when a subscription ends through unsubscribe, replacement, terminal error, or stop |
+| `onLog(direction, payload)`           | Receives bridge messages and warnings                                                        |
+
+## Iframe lifetime
+
+Each host handles one handshake. Create a new host and iframe to retry or replace the block URL. The
+[wire reference](bridge/protocol.md#initialization) defines handshake and
+malformed-message behavior.
+
+The first observed iframe `load` is allowed. A second load stops the host and reports retryable
+`iframe_reloaded`. 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.
+
+`stop()` removes listeners, cancels preparation, clears timers, ends subscriptions, and suppresses
+pending responses. Call it when removing the iframe.
+
+## Local block URLs
+
+`isAllowedLocalPreviewUrl({ url, hostOrigin })` accepts HTTP or HTTPS URLs on `localhost`,
+`*.localhost`, or `127.0.0.1` without credentials. It rejects the embedding page's origin.
+`hostOrigin` must be nonempty. Pass the embedding page's serialized origin.
+
+The protocol helper `isLocalBlockServerUrl(url)` checks the server URL without requiring origin
+isolation. The host adds the embedding-origin restriction. `manifestSource: "sandbox"` enforces this
+policy before the host starts. An invalid sandbox-mode URL throws `CustomBlockInitializationError`
+with code `invalid_local_preview_url`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notionhq/custom-blocks-host",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "description": "Reusable host runtime for Notion custom blocks.",
   "license": "MIT",
   "type": "module",
@@ -14,14 +14,22 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js",
+      "default": "./dist/protocol.js"
     }
   },
   "dependencies": {
-    "valibot": "^1.4.2"
+    "valibot": "^1.5.0"
   },
   "files": [
     "src",
     "dist",
-    "README.md"
+    "docs",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_LICENSES.md"
   ]
 }

package/src/autoBindProperties.ts

@@ -6,8 +6,8 @@ export type AutoBindableProperty = {
 }
 
 /**
- * Finds property IDs for a manifest's properties without changing the
- * manifest's semantic keys.
+ * Returns a map from manifest property keys to database property IDs.
+ * Unmapped keys are omitted.
  *
  * For each manifest property:
  * 1. Consider only schema properties of the same type.
@@ -15,6 +15,9 @@ export type AutoBindableProperty = {
  *    (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.
+ *
+ * An ID match has no priority over a display name match. If they identify two
+ * different properties of the same type, the manifest property stays unmapped.
  */
 export function getAutoBoundPropertyIdsByKey(args: {
 	manifestProperties: Readonly<Record<string, AutoBindableProperty>>