@notionhq/custom-blocks-host 0.3.11 → 0.4.1

package/docs/bridge/changelog.md

@@ -0,0 +1,67 @@
+# Bridge protocol changelog
+
+The bridge protocol defines the messages exchanged by a custom block's SDK and its host. This
+changelog records breaking contract changes and the SDK releases that introduced them. It also
+describes compatibility exceptions within a declared protocol version and their effects on blocks.
+Protocol version rules are in [Bridge protocol versioning](versioning.md). The host's
+[compatibility reference](../compatibility.md) describes current support and response
+conversions.
+
+Publication dates refer to npm releases in Pacific time, not deployment in Notion. Unqualified SDK
+versions refer to `@notionhq/custom-blocks`.
+
+| Protocol                                               | SDK release      | Published          | Breaking contract changes                                                                                                                                  |
+| ------------------------------------------------------ | ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1                                                      | `ncblock@0.0.1`  | May 11, 2026       | Initial `ready` / `init` handshake and block APIs                                                                                                          |
+| 2                                                      | `ncblock@0.0.36` | June 18, 2026      | Structured errors, handshake changes, and raw data-source IDs instead of manifest keys                                                                     |
+| 3                                                      | `0.1.0`          | July 22, 2026      | Accumulated contract changes include `connect → init → initResult`, initialization identity, subscription identity, and required structured connect errors |
+| 4                                                      | `0.2.0`          | September 17, 2026 | Required `init.contrastMode` and page/query `is_archived` and `in_trash` fields                                                                            |
+| 5 [†](#protocol-5-unavailable-containing-page-context) | `0.2.16`         | September 30, 2026 | Query filters and sorts must address actual database properties. Filter and sort payloads reject extra fields                                              |
+| 6 [‡](#protocol-6-richer-fallback-properties)          | `0.3.0`          | October 26, 2026   | Typed, display-name-keyed query properties and unified page responses replace the older query representation                                               |
+| 7                                                      | `0.3.3`          | October 30, 2026   | Typed text fallback properties for unique ID, button, formula, location, rollup, and verification                                                          |
+| 8                                                      | `0.4.0`          | November 2, 2026   | Local manifests move from `/manifest` to HTML metadata sent in `connect`; `manifestSource` selects the initialization manifest                             |
+
+The table lists SDK release boundaries, not complete supported version ranges. Host compatibility
+depends on `connect.bridgeProtocolVersion`, not the SDK package version.
+
+## Protocol 8: local manifest declarations
+
+The dev shell removes the `/manifest` route and embeds the local manifest in block HTML. The SDK
+reads that metadata and sends the declaration in `connect.manifest`; initialization no longer
+fetches `/manifest`.
+
+The host option `manifestSource` selects the initialization manifest: `"sandbox"` uses the
+declaration from `connect`, and `"host"` uses the persisted manifest returned by
+`getPersistedManifest`. Only the selected source determines initialization. Deployed blocks using
+supported earlier protocols retain their existing response formats.
+
+The shared host runtime minimum remains 3. The dev shell uses the Worker manifest in host mode and
+accepts supported earlier protocols. Sandbox-mode initialization uses the protocol 8 declaration
+from `connect`.
+
+## Changes within a declared version
+
+### Protocol 5: unavailable containing-page context
+
+On October 2, 2026, SDK 0.2.17 added `{ type: "unavailable" }` to containing-page context while
+retaining protocol 5. SDK 0.2.16 rejects that shape. The host preserves later protocol 5 behavior
+and accepts the limitation for the older SDK, as decided on October 31, 2026. Affected blocks must
+upgrade and rebuild. The host's [compatibility reference](../compatibility.md)
+describes current compatibility behavior.
+
+### Protocol 6: richer fallback properties
+
+The protocol version changed in code on October 22, 2026. On October 26, the `pages` and
+`dataSources` APIs adopted a shared page representation: data-source query rows and page operation
+results use the same page shape, with typed properties keyed by display name.
+
+Some SDKs added text fallback property objects for unique ID, button, formula, location, rollup, and
+verification while still reporting protocol 6. Earlier protocol 6 SDKs reject those property
+objects. Because both groups declare the same protocol version, updated hosts send `null` for these
+properties to every protocol 6 block.
+
+Blocks built with the later protocol 6 SDKs therefore lose those property values when their host
+updates. UI that displays the values can become empty, and code that assumes a property object is
+present can fail. Upgrade the SDK to protocol 7 or later and rebuild the block to receive the text
+fallback property objects. Host adapters continue returning the current page shape; the host runtime
+applies the protocol-specific conversion.

package/docs/bridge/protocol.md

@@ -0,0 +1,189 @@
+# 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.
+
+#### Relation filters
+
+Relation filters require an actual `relation` property in the bound schema. `contains` and
+`does_not_contain` accept one page ID. `is_empty` and `is_not_empty` accept only `true` and require
+no page ID. Each relation filter accepts exactly one operator. Adapters must evaluate empty checks
+against relation values, including XLDB row IDs where supported.
+
+#### 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).