@notionhq/custom-blocks-host 0.5.1 → 0.6.0

package/dist/protocol/pages/messages/updatePage.d.ts

@@ -1,7 +1,7 @@
 import * as v from "valibot";
-import type { CustomBlockCapabilityErrorCode, CustomBlockErrorCode, CustomBlockErrorInfo } from "../../utils/errors.js";
+import type { CustomBlockCapabilityErrorCode, CustomBlockErrorCode, CustomBlockErrorInfo, CustomBlockRequestErrorCode } from "../../utils/errors.js";
 export declare const customBlockUpdatePageErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockUpdatePageErrorCode = CustomBlockErrorCode<"update_page_failed" | "invalid_page_update" | "page_unavailable" | "data_source_access_failed" | "unmapped_property" | "property_id_mismatch" | "duplicate_property" | "invalid_property_value" | CustomBlockCapabilityErrorCode>;
+export type CustomBlockUpdatePageErrorCode = CustomBlockErrorCode<CustomBlockRequestErrorCode | "update_page_failed" | "previous_write_incomplete" | "invalid_page_update" | "invalid_icon_name" | "invalid_icon_color" | "page_unavailable" | "data_source_access_failed" | "unmapped_property" | "property_id_mismatch" | "duplicate_property" | "invalid_property_value" | CustomBlockCapabilityErrorCode>;
 export type CustomBlockUpdatePageErrorInfo = CustomBlockErrorInfo<CustomBlockUpdatePageErrorCode>;
 export declare const customBlockUpdatePageErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;
@@ -264,7 +264,13 @@ export declare const updatePageResultMessageSchema: v.VariantSchema<"status", [v
         readonly last_visited_time: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, null>;
         readonly created_time: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, null>;
         readonly last_edited_time: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, null>;
-        readonly icon: v.OptionalSchema<v.NullableSchema<v.VariantSchema<"type", [v.ObjectSchema<{
+        readonly icon: v.OptionalSchema<v.NullableSchema<v.VariantSchema<"type", [v.LooseObjectSchema<{
+            readonly type: v.LiteralSchema<"icon", undefined>;
+            readonly icon: v.LooseObjectSchema<{
+                readonly name: v.StringSchema<undefined>;
+                readonly color: v.OptionalSchema<v.GenericSchema<import("../../icons.js").NotionIconColor>, undefined>;
+            }, undefined>;
+        }, undefined>, v.ObjectSchema<{
             readonly type: v.LiteralSchema<"emoji", undefined>;
             readonly emoji: v.StringSchema<undefined>;
         }, undefined>, v.ObjectSchema<{
@@ -566,7 +572,13 @@ export declare const updatePageResultMessageWithProtocol3To5CompatibilitySchema:
         readonly last_visited_time: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, null>;
         readonly created_time: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, null>;
         readonly last_edited_time: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, null>;
-        readonly icon: v.OptionalSchema<v.NullableSchema<v.VariantSchema<"type", [v.ObjectSchema<{
+        readonly icon: v.OptionalSchema<v.NullableSchema<v.VariantSchema<"type", [v.LooseObjectSchema<{
+            readonly type: v.LiteralSchema<"icon", undefined>;
+            readonly icon: v.LooseObjectSchema<{
+                readonly name: v.StringSchema<undefined>;
+                readonly color: v.OptionalSchema<v.GenericSchema<import("../../icons.js").NotionIconColor>, undefined>;
+            }, undefined>;
+        }, undefined>, v.ObjectSchema<{
             readonly type: v.LiteralSchema<"emoji", undefined>;
             readonly emoji: v.StringSchema<undefined>;
         }, undefined>, v.ObjectSchema<{
@@ -842,7 +854,13 @@ export declare const updatePageResultMessageWithProtocol3To5CompatibilitySchema:
         }, undefined>], undefined>, undefined>;
         readonly created_time: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly last_edited_time: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-        readonly icon: v.OptionalSchema<v.VariantSchema<"type", [v.ObjectSchema<{
+        readonly icon: v.OptionalSchema<v.VariantSchema<"type", [v.LooseObjectSchema<{
+            readonly type: v.LiteralSchema<"icon", undefined>;
+            readonly icon: v.LooseObjectSchema<{
+                readonly name: v.StringSchema<undefined>;
+                readonly color: v.OptionalSchema<v.GenericSchema<import("../../icons.js").NotionIconColor>, undefined>;
+            }, undefined>;
+        }, undefined>, v.ObjectSchema<{
             readonly type: v.LiteralSchema<"emoji", undefined>;
             readonly emoji: v.StringSchema<undefined>;
         }, undefined>, v.ObjectSchema<{
@@ -1123,7 +1141,13 @@ export declare const updatePageMessageSchema: v.ObjectSchema<{
         readonly type: v.LiteralSchema<"verification", undefined>;
         readonly verification: v.StringSchema<undefined>;
     }, undefined>], undefined>, undefined>, undefined>;
-    readonly icon: v.OptionalSchema<v.VariantSchema<"type", [v.ObjectSchema<{
+    readonly icon: v.OptionalSchema<v.VariantSchema<"type", [v.LooseObjectSchema<{
+        readonly type: v.LiteralSchema<"icon", undefined>;
+        readonly icon: v.LooseObjectSchema<{
+            readonly name: v.StringSchema<undefined>;
+            readonly color: v.OptionalSchema<v.GenericSchema<import("../../icons.js").NotionIconColor>, undefined>;
+        }, undefined>;
+    }, undefined>, v.ObjectSchema<{
         readonly type: v.LiteralSchema<"emoji", undefined>;
         readonly emoji: v.StringSchema<undefined>;
     }, undefined>, v.ObjectSchema<{

package/dist/protocol/pages/pageAppearance.d.ts

@@ -24,7 +24,13 @@ export declare const notionHostedFileSchema: v.ObjectSchema<{
         readonly expiry_time: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     }, undefined>;
 }, undefined>;
-export declare const notionPageIconSchema: v.VariantSchema<"type", [v.ObjectSchema<{
+export declare const notionPageIconSchema: v.VariantSchema<"type", [v.LooseObjectSchema<{
+    readonly type: v.LiteralSchema<"icon", undefined>;
+    readonly icon: v.LooseObjectSchema<{
+        readonly name: v.StringSchema<undefined>;
+        readonly color: v.OptionalSchema<v.GenericSchema<import("../icons.js").NotionIconColor>, undefined>;
+    }, undefined>;
+}, undefined>, v.ObjectSchema<{
     readonly type: v.LiteralSchema<"emoji", undefined>;
     readonly emoji: v.StringSchema<undefined>;
 }, undefined>, v.ObjectSchema<{
@@ -60,3 +66,32 @@ export declare const notionPageCoverSchema: v.VariantSchema<"type", [v.ObjectSch
     }, undefined>;
 }, undefined>], undefined>;
 export type NotionPageCover = v.InferOutput<typeof notionPageCoverSchema>;
+export declare const notionCreatePageIconSchema: v.VariantSchema<"type", [v.LooseObjectSchema<{
+    readonly type: v.LiteralSchema<"icon", undefined>;
+    readonly icon: v.LooseObjectSchema<{
+        readonly name: v.StringSchema<undefined>;
+        readonly color: v.OptionalSchema<v.GenericSchema<import("../icons.js").NotionIconColor>, undefined>;
+    }, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"emoji", undefined>;
+    readonly emoji: v.StringSchema<undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"custom_emoji", undefined>;
+    readonly custom_emoji: v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly url: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"external", undefined>;
+    readonly external: v.ObjectSchema<{
+        readonly url: v.StringSchema<undefined>;
+    }, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"file", undefined>;
+    readonly file: v.ObjectSchema<{
+        readonly url: v.StringSchema<undefined>;
+        readonly expiry_time: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>;
+}, undefined>], undefined>;
+export type NotionCreatePageIcon = v.InferOutput<typeof notionCreatePageIconSchema>;

package/dist/protocol/pages/pageAppearance.js

@@ -1,4 +1,5 @@
 import * as v from "valibot";
+import { notionNativeIconSchema } from "../icons.js";
 export const notionEmojiIconSchema = v.object({
     type: v.literal("emoji"),
     emoji: v.string(),
@@ -23,6 +24,7 @@ export const notionHostedFileSchema = v.object({
     }),
 });
 export const notionPageIconSchema = v.variant("type", [
+    notionNativeIconSchema,
     notionEmojiIconSchema,
     notionCustomEmojiIconSchema,
     notionExternalFileSchema,
@@ -32,3 +34,10 @@ export const notionPageCoverSchema = v.variant("type", [
     notionExternalFileSchema,
     notionHostedFileSchema,
 ]);
+export const notionCreatePageIconSchema = v.variant("type", [
+    notionNativeIconSchema,
+    notionEmojiIconSchema,
+    notionCustomEmojiIconSchema,
+    notionExternalFileSchema,
+    notionHostedFileSchema,
+]);

package/dist/protocol/users/messages/getUser.d.ts

@@ -1,7 +1,7 @@
 import * as v from "valibot";
-import type { CustomBlockCapabilityErrorCode, CustomBlockErrorCode, CustomBlockErrorInfo } from "../../utils/errors.js";
+import type { CustomBlockCapabilityErrorCode, CustomBlockErrorCode, CustomBlockErrorInfo, CustomBlockRequestErrorCode } from "../../utils/errors.js";
 export declare const customBlockGetUserErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockGetUserErrorCode = CustomBlockErrorCode<"get_user_failed" | CustomBlockCapabilityErrorCode>;
+export type CustomBlockGetUserErrorCode = CustomBlockErrorCode<CustomBlockRequestErrorCode | "get_user_failed" | CustomBlockCapabilityErrorCode>;
 export type CustomBlockGetUserErrorInfo = CustomBlockErrorInfo<CustomBlockGetUserErrorCode>;
 export declare const customBlockGetUserErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;

package/dist/protocol/users/messages/listUsers.d.ts

@@ -1,7 +1,7 @@
 import * as v from "valibot";
-import type { CustomBlockCapabilityErrorCode, CustomBlockErrorCode, CustomBlockErrorInfo } from "../../utils/errors.js";
+import type { CustomBlockCapabilityErrorCode, CustomBlockErrorCode, CustomBlockErrorInfo, CustomBlockRequestErrorCode } from "../../utils/errors.js";
 export declare const customBlockListUsersErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockListUsersErrorCode = CustomBlockErrorCode<"list_users_failed" | CustomBlockCapabilityErrorCode>;
+export type CustomBlockListUsersErrorCode = CustomBlockErrorCode<CustomBlockRequestErrorCode | "list_users_failed" | CustomBlockCapabilityErrorCode>;
 export type CustomBlockListUsersErrorInfo = CustomBlockErrorInfo<CustomBlockListUsersErrorCode>;
 export declare const customBlockListUsersErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;

package/dist/protocol/utils/errors.d.ts

@@ -16,3 +16,5 @@ export declare const customBlockErrorInfoSchema: v.ObjectSchema<{
     readonly message: v.StringSchema<undefined>;
     readonly isRetryable: v.BooleanSchema<undefined>;
 }, undefined>;
+/** Failures shared by one-shot requests. */
+export type CustomBlockRequestErrorCode = CustomBlockErrorCode<"request_timeout" | "request_send_failed" | "request_disposed" | "invalid_host_message" | "invalid_sandbox_message" | "unsupported_operation">;

package/dist/protocol/utils/protocolVersion.d.ts

@@ -3,6 +3,7 @@
  * Increase this value for breaking wire changes. Hosts can continue to accept
  * older versions, so this value does not set the minimum or maximum they accept.
  */
-export declare const LATEST_BRIDGE_PROTOCOL_VERSION = 8;
+export declare const LATEST_BRIDGE_PROTOCOL_VERSION = 9;
 export declare const UNIFIED_PAGE_PROTOCOL_VERSION = 6;
 export declare const TEXT_FALLBACK_PROPERTY_PROTOCOL_VERSION = 7;
+export declare const NATIVE_ICON_PROTOCOL_VERSION = 9;

package/dist/protocol/utils/protocolVersion.js

@@ -3,9 +3,11 @@
  * Increase this value for breaking wire changes. Hosts can continue to accept
  * older versions, so this value does not set the minimum or maximum they accept.
  */
-export const LATEST_BRIDGE_PROTOCOL_VERSION = 8;
+export const LATEST_BRIDGE_PROTOCOL_VERSION = 9;
 // Protocol 6 introduces unified pages with name-keyed property objects.
 // Keep this cutoff fixed when the latest protocol version increases.
 export const UNIFIED_PAGE_PROTOCOL_VERSION = 6;
 // Protocol 7 adds typed text fallbacks for previously unsupported page properties.
 export const TEXT_FALLBACK_PROPERTY_PROTOCOL_VERSION = 7;
+// Protocol 9 adds native icon responses and writes throughout the page API.
+export const NATIVE_ICON_PROTOCOL_VERSION = 9;

package/dist/protocol/utils/readRequestId.d.ts

@@ -0,0 +1,2 @@
+/** Reads correlation without accepting the rest of an invalid message. */
+export declare function readRequestId(data: unknown): string | undefined;

package/dist/protocol/utils/readRequestId.js

@@ -0,0 +1,7 @@
+import * as v from "valibot";
+const requestIdentitySchema = v.object({ requestId: v.string() });
+/** Reads correlation without accepting the rest of an invalid message. */
+export function readRequestId(data) {
+    const result = v.safeParse(requestIdentitySchema, data);
+    return result.success ? result.output.requestId : undefined;
+}

package/docs/bridge/changelog.md

@@ -20,10 +20,22 @@ versions refer to `@notionhq/custom-blocks`.
 | 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                             |
+| 9                                                      | Unreleased       | —                  | Native page icons; older protocols receive external SVG URLs                                                                                               |
 
 The table lists SDK release boundaries, not complete supported version ranges. Host compatibility
 depends on `connect.bridgeProtocolVersion`, not the SDK package version.
 
+## Protocol 9: native page icons
+
+Page operations and query results can return `{ type: "icon", icon: { name, color } }`. Reads and
+writes share a loose shape: names and colors accept strings, color is optional, and additional
+native icon fields are retained. Hosts resolve names and default omitted colors to gray.
+
+Protocols 3–8 receive external SVG URLs in page operation results. Protocols 6–8 receive the same
+fallback in query results; protocols 3–5 keep their flat query format without appearance fields. The
+released-SDK compatibility corpus exercises these conversions. Add a frozen protocol-9 reader after
+the SDK release is published.
+
 ## Protocol 8: local manifest declarations
 
 The dev shell removes the `/manifest` route and embeds the local manifest in block HTML. The SDK
@@ -41,6 +53,13 @@ from `connect`.
 
 ## Changes within a declared version
 
+### Protocol 8: correlated request rejections
+
+Bridge NACKs (`invalidHostMessage` and `invalidSandboxMessage`) gain an optional string `requestId`.
+Updated SDKs complete the matching request immediately when a rejection can be correlated. Older
+readers ignore the additional field; updated readers continue to accept NACKs without an ID.
+Uncorrelated requests use the SDK's 60-second timeout. This additive change retains protocol 8.
+
 ### Protocol 5: unavailable containing-page context
 
 On October 2, 2026, SDK 0.2.17 added `{ type: "unavailable" }` to containing-page context while

package/docs/bridge/protocol.md

@@ -62,7 +62,9 @@ a different origin from its embedding page.
 - `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.
+- One-way messages, such as `resize`, have no correlation ID.
+- Bridge NACKs include the rejected message's `requestId` when it is a string. The ID identifies the
+  original request, including when the rejected message is its response.
 
 Hosts key query state by `subscriptionId`, replace state when a request reuses one, and suppress
 stale asynchronous results.
@@ -82,6 +84,22 @@ On parse failure, the host replies with `invalidSandboxMessage` and the sandbox
 `invalidHostMessage`, except for the handshake cases below. These replies are negative
 acknowledgments (NACKs). Receivers do not NACK another NACK.
 
+A sandbox request with a `requestId` expects a terminal result or correlated rejection. On parse
+failure, read `requestId` separately from the invalid payload. The host includes a readable string
+ID in `invalidSandboxMessage`, even for an unknown request type. The SDK completes the matching
+request with `invalid_sandbox_message`. When the SDK rejects a host response, it completes the
+matching request locally with `invalid_host_message` and includes the ID in `invalidHostMessage`.
+Both errors have `isRetryable: false`.
+
+One-shot SDK requests time out after 60 seconds. Missing, unreadable, or unknown IDs do not fail
+unrelated requests. NACK IDs are optional: older readers ignore them, and newer readers accept
+legacy NACKs without IDs. Those requests retain the timeout fallback.
+
+Request completion clears its timer, removes the pending entry, and ignores duplicate or late
+results. Disposing the SDK completes pending calls locally with `request_disposed` and clears their
+timers. The SDK does not retry or cancel host work. A timed-out write may still complete; check its
+resulting state before repeating it. Data source subscriptions use a separate lifecycle.
+
 Malformed sandbox messages do not change the host's initialization state or timeout, except as
 follows:
 
@@ -202,3 +220,14 @@ 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.
+
+### Native page icon compatibility
+
+Protocol 9 and later use native icon objects. Protocols 3–8 receive external SVG URLs in page
+operation results. Unified query results in protocols 6–8 also use external SVG URLs; flat query
+results in protocols 3–5 omit icon fields. Native colors accept any string in responses and write
+inputs, so newer host colors do not require an SDK update.
+
+`createPage` accepts native icons, emoji, custom emoji, and URL-backed icons and covers. The
+application adapter checks submitted image URLs against the block's network permissions before
+creating a page.

package/docs/bridge/versioning.md

@@ -17,6 +17,7 @@ conversions.
 
 `connect.bridgeProtocolVersion` selects the wire contract. `sdkVersion` is analytics metadata.
 `LATEST_BRIDGE_PROTOCOL_VERSION` identifies the latest contract defined by the package.
+`NATIVE_ICON_PROTOCOL_VERSION` is 9, the first protocol with native icon responses and writes.
 
 ## Protocol export names
 

package/docs/compatibility.md

@@ -16,7 +16,7 @@ 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
+The current SDK declares protocol 9. 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
@@ -35,12 +35,13 @@ 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                                                  |
+| Target | Query results                                                               | Page operation results                                        | Binding schemas                                                          | Native icons                                                                |
+| ------ | --------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| 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              | External SVG URLs in page operations; icons omitted from flat query results |
+| 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 | Same as protocols 3–4                                                       |
+| 6      | Unified name-keyed properties. Text fallback property objects become `null` | Same unified page format                                      | Actual database schemas                                                  | External SVG URLs                                                           |
+| 7–8    | Unified pages with typed text fallback properties                           | Same unified page format                                      | Actual database schemas                                                  | External SVG URLs                                                           |
+| 9+     | Unified pages with typed text fallback properties                           | Same unified page format                                      | Actual database schemas                                                  | Native icon objects                                                         |
 
 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
@@ -52,6 +53,13 @@ Release-specific compatibility limits are documented in the changelog entries fo
 and
 [protocol 6 text fallback properties](bridge/changelog.md#protocol-6-richer-fallback-properties).
 
+### Native page icons
+
+Protocol 9 and later receive native icon objects. Protocols 3–8 receive external SVG URLs in page
+operation results, and protocols 6–8 also receive them in query results. Protocols 3–5 use flat
+query results without page appearance fields. Omitted native colors default to gray when producing
+SVG URLs.
+
 ### Unavailable containing-page context
 
 Protocols 3–4 receive `context_unavailable` during initialization or stop when containing-page

package/docs/handlers.md

@@ -11,9 +11,8 @@ 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.
+`queryDataSource` is required. Other handlers are optional. A handler returns a result synchronously
+or as a promise. Errors carry `{ code, message, isRetryable }`, with open string codes.
 
 ### Return bridge data
 
@@ -28,6 +27,10 @@ Query filters and sorts are validated against the actual bound database schema b
 `queryDataSource` runs. See the [wire reference](bridge/protocol.md#data-sources) for
 query semantics.
 
+For one-shot requests, a missing handler returns `unsupported_operation`. A handler that throws,
+rejects, or returns a malformed result produces `unknown_error`. Exception details go to `onLog`;
+the sandbox receives a generic error. Specific errors returned by handlers pass through unchanged.
+
 ## Connect a data source
 
 Connect an embedded block to an in-memory Tasks data source with one numeric Estimate property. This

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notionhq/custom-blocks-host",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Reusable host runtime for Notion custom blocks.",
   "license": "MIT",
   "type": "module",

package/src/compatibility/normalizeHostToSandboxMessage.ts

@@ -3,12 +3,14 @@ import type {
 	HostToSandboxMessageWithProtocol3To5Compatibility,
 } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
 import {
+	NATIVE_ICON_PROTOCOL_VERSION,
 	TEXT_FALLBACK_PROPERTY_PROTOCOL_VERSION,
 	UNIFIED_PAGE_PROTOCOL_VERSION,
 } from "@notionhq/custom-blocks-protocol/utils/protocolVersion.js"
 import { addMetadataReadSchemasForProtocol3To4 } from "./protocol3To4/addMetadataReadSchemasForProtocol3To4.js"
 import { normalizePageResultsForProtocol3To5 } from "./protocol3To5/normalizePageResultsForProtocol3To5.js"
 import { normalizePageResultsForProtocol6 } from "./protocol6/normalizePageResultsForProtocol6.js"
+import { normalizePageResultsForProtocol7To8 } from "./protocol7To8/normalizePageResultsForProtocol7To8.js"
 
 /**
  * Encodes current host messages for the sandbox's declared protocol. Handlers use
@@ -50,5 +52,8 @@ export function normalizeHostToSandboxMessage(
 	if (bridgeProtocolVersion < TEXT_FALLBACK_PROPERTY_PROTOCOL_VERSION) {
 		return normalizePageResultsForProtocol6(message)
 	}
+	if (bridgeProtocolVersion < NATIVE_ICON_PROTOCOL_VERSION) {
+		return normalizePageResultsForProtocol7To8(message)
+	}
 	return message
 }

package/src/compatibility/pages/toIconForProtocol3To8.ts

@@ -0,0 +1,17 @@
+import type { NotionPageIcon } from "@notionhq/custom-blocks-protocol/pages/pageAppearance.js"
+
+/** Converts native icons for legacy receivers. Delete when the runtime minimum reaches 9. */
+export function toIconForProtocol3To8(
+	icon: NotionPageIcon | null,
+): NotionPageIcon | null {
+	if (icon?.type !== "icon") {
+		return icon
+	}
+	const { name, color } = icon.icon
+	return {
+		type: "external",
+		external: {
+			url: `https://www.notion.so/icons/${name}_${color ?? "gray"}.svg`,
+		},
+	}
+}

package/src/compatibility/protocol3To5/toPageForProtocol3To5.ts

@@ -1,5 +1,6 @@
 import type { BridgePageForProtocol3To5 } from "@notionhq/custom-blocks-protocol/compatibility/protocol3To5/bridgePage.js"
 import type { BridgePage } from "@notionhq/custom-blocks-protocol/pages/bridgePage.js"
+import { toIconForProtocol3To8 } from "../pages/toIconForProtocol3To8.js"
 
 /**
  * Converts current page data to the page-operation format used by protocols 3–5.
@@ -19,7 +20,7 @@ export function toPageForProtocol3To5(
 				property ? [[property.id, property]] : [],
 			),
 		),
-		icon: page.icon ?? undefined,
+		icon: toIconForProtocol3To8(page.icon) ?? undefined,
 		cover: page.cover ?? undefined,
 		created_time: page.created_time ?? undefined,
 		last_edited_time: page.last_edited_time ?? undefined,

package/src/compatibility/protocol6/normalizePageResultsForProtocol6.ts

@@ -1,5 +1,7 @@
 import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
+import type { BridgePage } from "@notionhq/custom-blocks-protocol/pages/bridgePage.js"
 import type { SuccessfulPageResult } from "../pages/pageResult.js"
+import { toIconForProtocol3To8 } from "../pages/toIconForProtocol3To8.js"
 import { toPageWithNullTextFallbackProperties } from "../pages/toPageWithNullTextFallbackProperties.js"
 
 /**
@@ -13,11 +15,18 @@ export function normalizePageResultsForProtocol6(
 	if (message.type === "queryDataSourceResult") {
 		return {
 			...message,
-			items: message.items.map(toPageWithNullTextFallbackProperties),
+			items: message.items.map(toPageForProtocol6),
 		}
 	}
 	return {
 		...message,
-		page: toPageWithNullTextFallbackProperties(message.page),
+		page: toPageForProtocol6(message.page),
+	}
+}
+
+function toPageForProtocol6(page: BridgePage): BridgePage {
+	return {
+		...toPageWithNullTextFallbackProperties(page),
+		icon: toIconForProtocol3To8(page.icon),
 	}
 }

package/src/compatibility/protocol7To8/normalizePageResultsForProtocol7To8.ts

@@ -0,0 +1,22 @@
+import type { BridgePage } from "@notionhq/custom-blocks-protocol/pages/bridgePage.js"
+import type { SuccessfulPageResult } from "../pages/pageResult.js"
+import { toIconForProtocol3To8 } from "../pages/toIconForProtocol3To8.js"
+
+/** Encodes icons for protocols 7–8. Delete when the runtime minimum reaches 9. */
+export function normalizePageResultsForProtocol7To8(
+	message: SuccessfulPageResult,
+): SuccessfulPageResult {
+	if (message.type === "queryDataSourceResult") {
+		if (!message.items.some(page => page.icon?.type === "icon")) {
+			return message
+		}
+		return { ...message, items: message.items.map(toPageWithoutNativeIcon) }
+	}
+	const page = toPageWithoutNativeIcon(message.page)
+	return page === message.page ? message : { ...message, page }
+}
+
+function toPageWithoutNativeIcon(page: BridgePage): BridgePage {
+	const icon = toIconForProtocol3To8(page.icon)
+	return icon === page.icon ? page : { ...page, icon }
+}