@notionhq/custom-blocks-host 0.4.1 → 0.4.3

package/dist/protocol/users/makeBridgeUser.d.ts

@@ -0,0 +1,4 @@
+import type { BridgeUser } from "./bridgeUser.js";
+export type MakeBridgeUserArgs = Pick<BridgeUser, "id" | "person"> & Partial<Omit<BridgeUser, "object" | "type" | "id" | "person">>;
+/** Builds the shared person-user payload; callers supply identity and profile data. */
+export declare function makeBridgeUser(args: MakeBridgeUserArgs): BridgeUser;

package/dist/protocol/users/makeBridgeUser.js

@@ -0,0 +1,11 @@
+import * as v from "valibot";
+import { bridgeUserSchema } from "./bridgeUser.js";
+/** Builds the shared person-user payload; callers supply identity and profile data. */
+export function makeBridgeUser(args) {
+    return v.parse(bridgeUserSchema, {
+        ...args,
+        object: "user",
+        type: "person",
+        avatar_url: args.avatar_url ?? null,
+    });
+}

package/dist/protocol/{messages → users/messages}/currentUserChanged.js

@@ -1,9 +1,9 @@
 import * as v from "valibot";
-import { notionUserSchema } from "../users/user.js";
+import { bridgeUserSchema } from "../bridgeUser.js";
 /**
  * Sent by the host when the viewing user's profile changes while the block is mounted.
  */
 export const currentUserChangedMessageSchema = v.object({
     type: v.literal("currentUserChanged"),
-    currentUser: notionUserSchema,
+    currentUser: bridgeUserSchema,
 });

package/dist/protocol/{messages → users/messages}/getUser.d.ts

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

package/dist/protocol/{messages → users/messages}/getUser.js

@@ -1,5 +1,6 @@
 import * as v from "valibot";
-import { notionUserIdSchema, notionUserSchema } from "../users/user.js";
+import { bridgeUserSchema } from "../bridgeUser.js";
+import { notionUserIdSchema } from "../userId.js";
 // The schema accepts any string code. The type lists known codes for
 // autocomplete, with an open string fallback for newer senders.
 export const customBlockGetUserErrorCodeSchema = v.string();
@@ -21,7 +22,7 @@ export const getUserResultMessageSchema = v.variant("status", [
         type: v.literal("getUserResult"),
         requestId: v.string(),
         status: v.literal("success"),
-        user: notionUserSchema,
+        user: bridgeUserSchema,
     }),
     v.object({
         type: v.literal("getUserResult"),

package/dist/protocol/{messages → users/messages}/listUsers.d.ts

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

package/dist/protocol/{messages → users/messages}/listUsers.js

@@ -1,5 +1,5 @@
 import * as v from "valibot";
-import { notionUserListSchema } from "../users/user.js";
+import { bridgeUserListSchema } from "../bridgeUserList.js";
 // The schema accepts any string code. The type lists known codes for
 // autocomplete, with an open string fallback for newer senders.
 export const customBlockListUsersErrorCodeSchema = v.string();
@@ -22,7 +22,7 @@ export const listUsersResultMessageSchema = v.variant("status", [
         type: v.literal("listUsersResult"),
         requestId: v.string(),
         status: v.literal("success"),
-        list: notionUserListSchema,
+        list: bridgeUserListSchema,
     }),
     v.object({
         type: v.literal("listUsersResult"),

package/dist/protocol/users/userId.d.ts

@@ -0,0 +1,3 @@
+import * as v from "valibot";
+export declare const notionUserIdSchema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionUserId">]>;
+export type NotionUserId = v.InferOutput<typeof notionUserIdSchema>;

package/dist/protocol/users/userId.js

@@ -0,0 +1,2 @@
+import * as v from "valibot";
+export const notionUserIdSchema = v.pipe(v.string(), v.brand("NotionUserId"));

package/dist/protocol/{errors.d.ts → utils/errors.d.ts}

@@ -1,5 +1,11 @@
 import * as v from "valibot";
 export type CustomBlockErrorCode<KnownCode extends string> = KnownCode | "unknown_error" | (string & {});
+/**
+ * Reserved for a request that needs a capability the block did not declare or
+ * the viewer did not grant. No host sends it yet.
+ */
+export declare const CAPABILITY_NOT_GRANTED_ERROR_CODE = "capability_not_granted";
+export type CustomBlockCapabilityErrorCode = typeof CAPABILITY_NOT_GRANTED_ERROR_CODE;
 export type CustomBlockErrorInfo<TCode extends string = string> = {
     code: TCode;
     message: string;

package/dist/protocol/utils/errors.js

@@ -0,0 +1,11 @@
+import * as v from "valibot";
+/**
+ * Reserved for a request that needs a capability the block did not declare or
+ * the viewer did not grant. No host sends it yet.
+ */
+export const CAPABILITY_NOT_GRANTED_ERROR_CODE = "capability_not_granted";
+export const customBlockErrorInfoSchema = v.object({
+    code: v.string(),
+    message: v.string(),
+    isRetryable: v.boolean(),
+});

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

@@ -0,0 +1,2 @@
+import * as v from "valibot";
+export declare const nullableStringSchema: v.NullableSchema<v.StringSchema<undefined>, undefined>;

package/dist/protocol/utils/nullableStringSchema.js

@@ -0,0 +1,2 @@
+import * as v from "valibot";
+export const nullableStringSchema = v.nullable(v.string());

package/dist/users/types.d.ts

@@ -0,0 +1,9 @@
+import type { BridgeMessagePayload } from "../protocol/messages/messagePayload.js";
+import type { CustomBlockGetUserErrorInfo, getUserMessageSchema, getUserResultMessageSchema } from "../protocol/users/messages/getUser.js";
+import type { CustomBlockListUsersErrorInfo, listUsersMessageSchema, listUsersResultMessageSchema } from "../protocol/users/messages/listUsers.js";
+import type { InferInput } from "valibot";
+export type CustomBlockHostGetUserResult = BridgeMessagePayload<InferInput<typeof getUserResultMessageSchema>, CustomBlockGetUserErrorInfo>;
+export type CustomBlockHostListUsersResult = BridgeMessagePayload<InferInput<typeof listUsersResultMessageSchema>, CustomBlockListUsersErrorInfo>;
+export type GetUserMessageInput = InferInput<typeof getUserMessageSchema>;
+export type ListUsersMessageInput = InferInput<typeof listUsersMessageSchema>;
+//# sourceMappingURL=types.d.ts.map

package/dist/users/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/users/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6DAA6D,CAAA;AACvG,OAAO,KAAK,EACX,2BAA2B,EAC3B,oBAAoB,EACpB,0BAA0B,EAC1B,MAAM,4DAA4D,CAAA;AACnE,OAAO,KAAK,EACX,6BAA6B,EAC7B,sBAAsB,EACtB,4BAA4B,EAC5B,MAAM,8DAA8D,CAAA;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,CAC9D,UAAU,CAAC,OAAO,0BAA0B,CAAC,EAC7C,2BAA2B,CAC3B,CAAA;AAED,MAAM,MAAM,8BAA8B,GAAG,oBAAoB,CAChE,UAAU,CAAC,OAAO,4BAA4B,CAAC,EAC/C,6BAA6B,CAC7B,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEzE,MAAM,MAAM,qBAAqB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAA"}

package/dist/users/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/maybePromise.d.ts

@@ -0,0 +1,2 @@
+export type MaybePromise<T> = T | Promise<T>;
+//# sourceMappingURL=maybePromise.d.ts.map

package/dist/utils/maybePromise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maybePromise.d.ts","sourceRoot":"","sources":["../../src/utils/maybePromise.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA"}

package/dist/utils/maybePromise.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+{"version":3,"file":"protocolVersion.d.ts","sourceRoot":"","sources":["../../src/utils/protocolVersion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,0CAA0C,IAAI,CAAA"}

package/dist/utils/toNotionPageId.d.ts

@@ -0,0 +1,3 @@
+import type { NotionPageId } from "../protocol/utils/ids.js";
+export declare function toNotionPageId(id: string): NotionPageId;
+//# sourceMappingURL=toNotionPageId.d.ts.map

package/dist/utils/toNotionPageId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toNotionPageId.d.ts","sourceRoot":"","sources":["../../src/utils/toNotionPageId.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+CAA+C,CAAA;AAIjF,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,CAEvD"}

package/dist/{ids.js → utils/toNotionPageId.js}

@@ -1,4 +1,4 @@
-import { notionPageIdSchema, } from "./protocol/ids.js";
+import { notionPageIdSchema } from "../protocol/utils/ids.js";
 import * as v from "valibot";
 export function toNotionPageId(id) {
     return v.parse(notionPageIdSchema, id);

package/dist/{utils.d.ts → utils/unreachable.d.ts}

@@ -2,4 +2,4 @@
  * Throws when a discriminated union has an unexpected member.
  */
 export declare function unreachable(value: never): never;
-//# sourceMappingURL=utils.d.ts.map
+//# sourceMappingURL=unreachable.d.ts.map

package/dist/utils/unreachable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unreachable.d.ts","sourceRoot":"","sources":["../../src/utils/unreachable.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAI/C"}

package/docs/bridge/protocol.md

@@ -107,13 +107,18 @@ for `code`, including unknown codes. TypeScript aliases list known codes for aut
 
 ### Bindings and IDs
 
-Hosts send `NotionDataSourceBindings` as `dataSources: { bindings }`, keyed by the semantic data
+Hosts send `BridgeDataSourceBindings` 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`.
 
+A binding with `inaccessible: true` marks a bound data source that the viewer can't read. The host
+omits its pointer, schema, and property mappings. The SDK and host still initialize the block. The
+SDK fails queries and page creation that use the data source with `data_source_inaccessible`,
+without sending a message.
+
 ### Query requests
 
 `queryDataSource` may include a resolved `filter` and an ordered `sorts` list. Each sort contains a
@@ -160,6 +165,16 @@ filter: {
 }
 ```
 
+## Capabilities
+
+`manifest.capabilities` lists `{ capability, resource }` declarations. Both fields are open strings,
+so a newer vocabulary never makes an older receiver reject a manifest. An omitted `capabilities`
+marks a block that predates approval.
+
+The `capability_not_granted` error code is reserved for a request that the viewer's grants do not
+cover, with `isRetryable: false`. No adapter sends it yet, and no receiver restricts requests by
+capability. The SDK's capabilities guide documents the vocabulary.
+
 ## Page context
 
 Containing-page context uses `CustomBlockPage`. The `init.page` and `pageChanged.page` fields
@@ -175,10 +190,10 @@ 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.
+Host handlers return unified `BridgePage` 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`. `bridgePageSchema` 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,

package/docs/bridge/versioning.md

@@ -21,8 +21,8 @@ conversions.
 ## 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`
+by protocols 3–5 are named `BridgePageForProtocol3To5` and `NotionDataSourcePageForProtocol3To5`,
+with matching `bridgePageForProtocol3To5Schema` 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.

package/docs/handlers.md

@@ -42,11 +42,11 @@ import type {
   CustomBlockHostDataSourcesPayload,
   CustomBlockHostHandlers,
 } from "@notionhq/custom-blocks-host"
-import type { CustomBlockManifest, NotionPageData } from "@notionhq/custom-blocks-host/protocol"
+import type { BridgeCustomBlockManifest, BridgePage } from "@notionhq/custom-blocks-host/protocol"
 
 const tasksId = "44444444-4444-4444-8444-444444444444"
 
-const manifest: CustomBlockManifest = {
+const manifest: BridgeCustomBlockManifest = {
   version: 1,
   dataSources: {
     tasks: {
@@ -109,7 +109,7 @@ const handlers: CustomBlockHostHandlers = {
       }
     }
 
-    const items: NotionPageData[] = [
+    const items: BridgePage[] = [
       {
         object: "page",
         id: "55555555-5555-4555-8555-555555555555",

package/package.json

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

package/src/compatibility/normalizeHostToSandboxMessage.ts

@@ -5,10 +5,10 @@ import type {
 import {
 	TEXT_FALLBACK_PROPERTY_PROTOCOL_VERSION,
 	UNIFIED_PAGE_PROTOCOL_VERSION,
-} from "@notionhq/custom-blocks-protocol/protocolVersion.js"
-import { addMetadataReadSchemasForProtocol3To4 } from "./addMetadataReadSchemasForProtocol3To4.js"
-import { normalizePageResultsForProtocol3To5 } from "./normalizePageResultsForProtocol3To5.js"
-import { normalizePageResultsForProtocol6 } from "./normalizePageResultsForProtocol6.js"
+} 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"
 
 /**
  * Encodes current host messages for the sandbox's declared protocol. Handlers use

package/src/compatibility/{pageWithNullTextFallbackProperties.ts → pages/toPageWithNullTextFallbackProperties.ts}

@@ -1,6 +1,6 @@
-import type { notionPageDataSchema } from "@notionhq/custom-blocks-protocol/pages/page.js"
+import type { bridgePageSchema } from "@notionhq/custom-blocks-protocol/pages/bridgePage.js"
 import type { InferOutput } from "valibot"
-import { unreachable } from "../utils.js"
+import { unreachable } from "../../utils/unreachable.js"
 
 /**
  * Shared field conversion for receivers that cannot decode text fallback objects.
@@ -8,8 +8,8 @@ import { unreachable } from "../utils.js"
  * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 7.
  */
 export function toPageWithNullTextFallbackProperties(
-	page: InferOutput<typeof notionPageDataSchema>,
-): InferOutput<typeof notionPageDataSchema> {
+	page: InferOutput<typeof bridgePageSchema>,
+): InferOutput<typeof bridgePageSchema> {
 	return {
 		...page,
 		properties: Object.fromEntries(

package/src/compatibility/{addMetadataReadSchemasForProtocol3To4.ts → protocol3To4/addMetadataReadSchemasForProtocol3To4.ts}

@@ -1,4 +1,4 @@
-import { NOTION_BUILTIN_PROPERTY_SCHEMAS } from "@notionhq/custom-blocks-protocol/dataSources/propertySchema.js"
+import { NOTION_BUILTIN_PROPERTY_SCHEMAS } from "@notionhq/custom-blocks-protocol/dataSources/properties/propertySchema.js"
 import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
 
 /**

package/src/compatibility/{normalizePageResultsForProtocol3To5.ts → protocol3To5/normalizePageResultsForProtocol3To5.ts}

@@ -1,10 +1,8 @@
 import type { HostToSandboxMessageWithProtocol3To5Compatibility } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
-import {
-	toPageForProtocol3To5,
-	toQueryPageForProtocol3To5,
-} from "./pageForProtocol3To5.js"
-import type { SuccessfulPageResult } from "./pageResult.js"
-import { toPageWithNullTextFallbackProperties } from "./pageWithNullTextFallbackProperties.js"
+import type { SuccessfulPageResult } from "../pages/pageResult.js"
+import { toPageWithNullTextFallbackProperties } from "../pages/toPageWithNullTextFallbackProperties.js"
+import { toPageForProtocol3To5 } from "./toPageForProtocol3To5.js"
+import { toQueryPageForProtocol3To5 } from "./toQueryPageForProtocol3To5.js"
 
 /**
  * Encodes current pages for protocols 3–5. Query values are flat and ID-keyed.

package/src/compatibility/protocol3To5/toDateTimeValueForProtocol3To5.ts

@@ -0,0 +1,25 @@
+import type { NotionDataSourceValue } from "@notionhq/custom-blocks-protocol/compatibility/protocol3To5/dataSourceValue.js"
+
+/**
+ * Converts a timestamp to the UTC date/time object used by protocol 3–5 queries.
+ * Missing or invalid timestamps produce undefined; time is stored to the minute.
+ *
+ * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 6.
+ */
+export function toDateTimeValueForProtocol3To5(
+	value: string | number | null | undefined,
+): NotionDataSourceValue | undefined {
+	if (value === undefined || value === null || value === "") {
+		return undefined
+	}
+	const date = new Date(value)
+	if (!Number.isFinite(date.getTime())) {
+		return undefined
+	}
+	return {
+		type: "datetime",
+		start_date: date.toISOString().slice(0, 10),
+		start_time: date.toISOString().slice(11, 16),
+		time_zone: "UTC",
+	}
+}

package/src/compatibility/protocol3To5/toPageForProtocol3To5.ts

@@ -0,0 +1,29 @@
+import type { BridgePageForProtocol3To5 } from "@notionhq/custom-blocks-protocol/compatibility/protocol3To5/bridgePage.js"
+import type { BridgePage } from "@notionhq/custom-blocks-protocol/pages/bridgePage.js"
+
+/**
+ * Converts current page data to the page-operation format used by protocols 3–5.
+ * Keys property objects by raw ID and omits null properties. Optional icons,
+ * covers, timestamps, and URLs use undefined instead of null in this format.
+ * Call after clearing property objects unsupported by these protocols.
+ *
+ * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 6.
+ */
+export function toPageForProtocol3To5(
+	page: BridgePage,
+): BridgePageForProtocol3To5 {
+	return {
+		...page,
+		properties: Object.fromEntries(
+			Object.values(page.properties).flatMap(property =>
+				property ? [[property.id, property]] : [],
+			),
+		),
+		icon: page.icon ?? undefined,
+		cover: page.cover ?? undefined,
+		created_time: page.created_time ?? undefined,
+		last_edited_time: page.last_edited_time ?? undefined,
+		url: page.url ?? undefined,
+		public_url: page.public_url ?? undefined,
+	}
+}

package/src/compatibility/protocol3To5/toPropertyValueForProtocol3To5.ts

@@ -0,0 +1,102 @@
+import type { NotionDataSourceValue } from "@notionhq/custom-blocks-protocol/compatibility/protocol3To5/dataSourceValue.js"
+import type { BridgePagePropertyValue } from "@notionhq/custom-blocks-protocol/pages/properties/bridgePagePropertyValue.js"
+import { toNotionDateValue } from "../../dataSources/properties/toNotionDateValue.js"
+import { unreachable } from "../../utils/unreachable.js"
+import { toDateTimeValueForProtocol3To5 } from "./toDateTimeValueForProtocol3To5.js"
+
+/**
+ * Converts a typed page property to the scalar, list, record-reference, or
+ * date/time value used by protocol 3–5 query results.
+ *
+ * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 6.
+ */
+export function toPropertyValueForProtocol3To5(
+	property: BridgePagePropertyValue,
+): NotionDataSourceValue | undefined {
+	switch (property.type) {
+		case "title":
+			return plainText(property.title)
+		case "rich_text":
+			return plainText(property.rich_text)
+		case "number":
+			return property.number ?? undefined
+		case "checkbox":
+			return property.checkbox
+		case "url":
+			return property.url ?? ""
+		case "email":
+			return property.email ?? ""
+		case "phone_number":
+			return property.phone_number ?? ""
+		case "select":
+			return property.select?.name
+		case "status":
+			return property.status?.name
+		case "multi_select":
+			return property.multi_select.flatMap(option => option.name ?? [])
+		case "date":
+			return property.date ? toNotionDateValue(property.date) : undefined
+		case "people":
+			return property.people.map(person =>
+				person.object === "group"
+					? {
+							id: person.id,
+							table: "space_permission_group",
+							spaceId: person.id.split("|")[1],
+						}
+					: { id: person.id, table: "notion_user" },
+			)
+		case "relation":
+			return property.relation.map(page => ({ id: page.id, table: "block" }))
+		case "files":
+			return property.files.map(file => file.name).join(",")
+		case "unique_id":
+			return property.unique_id
+		case "button":
+			return property.button
+		case "formula":
+			return property.formula
+		case "location":
+			return property.location
+		case "rollup":
+			return property.rollup
+		case "verification":
+			return property.verification
+		case "place":
+			return ""
+		case "created_time":
+			return toDateTimeValueForProtocol3To5(property.created_time)
+		case "last_edited_time":
+			return toDateTimeValueForProtocol3To5(property.last_edited_time)
+		case "last_visited_time":
+			return toDateTimeValueForProtocol3To5(property.last_visited_time)
+		case "created_by":
+			return property.created_by ? [property.created_by] : undefined
+		case "last_edited_by":
+			return property.last_edited_by ? [property.last_edited_by] : undefined
+		default:
+			return unreachable(property)
+	}
+}
+
+/**
+ * Flattens rich-text items to the string used by protocol 3–5 query values.
+ *
+ * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 6.
+ */
+function plainText(items: Record<string, unknown>[]): string {
+	return items
+		.map(item => {
+			if (typeof item.plain_text === "string") {
+				return item.plain_text
+			}
+			const text = item.text
+			return text &&
+				typeof text === "object" &&
+				"content" in text &&
+				typeof text.content === "string"
+				? text.content
+				: ""
+		})
+		.join("")
+}

package/src/compatibility/protocol3To5/toQueryPageForProtocol3To5.ts

@@ -0,0 +1,35 @@
+import type { NotionDataSourceValue } from "@notionhq/custom-blocks-protocol/compatibility/protocol3To5/dataSourceValue.js"
+import type { BridgePage } from "@notionhq/custom-blocks-protocol/pages/bridgePage.js"
+import { toDateTimeValueForProtocol3To5 } from "./toDateTimeValueForProtocol3To5.js"
+import { toPropertyValueForProtocol3To5 } from "./toPropertyValueForProtocol3To5.js"
+
+/**
+ * Converts a current page to a protocol 3–5 query row, keeping its ID and archive
+ * flags while flattening typed property objects into raw-ID-keyed values.
+ * Copies page creation and edit metadata into the reserved property IDs that
+ * these query readers expect.
+ *
+ * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 6.
+ */
+export function toQueryPageForProtocol3To5(page: BridgePage) {
+	const propertiesById: Record<string, NotionDataSourceValue | undefined> = {}
+	for (const property of Object.values(page.properties)) {
+		if (property) {
+			propertiesById[property.id] = toPropertyValueForProtocol3To5(property)
+		}
+	}
+	return {
+		id: page.id,
+		is_archived: page.is_archived,
+		in_trash: page.in_trash,
+		// Reserved metadata IDs retain their historical meaning even if an actual
+		// property uses the same ID. Binding schemas use the same precedence.
+		propertiesById: {
+			...propertiesById,
+			created_time: toDateTimeValueForProtocol3To5(page.created_time),
+			last_edited_time: toDateTimeValueForProtocol3To5(page.last_edited_time),
+			created_by: page.created_by ? [page.created_by] : undefined,
+			last_edited_by: page.last_edited_by ? [page.last_edited_by] : undefined,
+		},
+	}
+}

package/src/compatibility/{normalizePageResultsForProtocol6.ts → protocol6/normalizePageResultsForProtocol6.ts}

@@ -1,6 +1,6 @@
 import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
-import type { SuccessfulPageResult } from "./pageResult.js"
-import { toPageWithNullTextFallbackProperties } from "./pageWithNullTextFallbackProperties.js"
+import type { SuccessfulPageResult } from "../pages/pageResult.js"
+import { toPageWithNullTextFallbackProperties } from "../pages/toPageWithNullTextFallbackProperties.js"
 
 /**
  * Encodes protocol 6 pages, whose receivers require null for text fallback properties.

package/src/context/initialState.ts

@@ -0,0 +1,65 @@
+import { customBlockPageSchema } from "@notionhq/custom-blocks-protocol/context/containingPage.js"
+import { notionContrastModeSchema } from "@notionhq/custom-blocks-protocol/context/contrast.js"
+import { notionParentSchema } from "@notionhq/custom-blocks-protocol/context/parent.js"
+import { notionThemeSchema } from "@notionhq/custom-blocks-protocol/context/theme.js"
+import { bridgeDataSourceBindingsSchema } from "@notionhq/custom-blocks-protocol/dataSources/bridgeDataSourceBindings.js"
+import type { CustomBlockInitErrorInfo } from "@notionhq/custom-blocks-protocol/handshake/init.js"
+import { customBlockInitErrorInfoSchema } from "@notionhq/custom-blocks-protocol/handshake/init.js"
+import type { BridgeCustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest/manifest.js"
+import { manifestSchema } from "@notionhq/custom-blocks-protocol/manifest/manifest.js"
+import { bridgeUserSchema } from "@notionhq/custom-blocks-protocol/users/bridgeUser.js"
+import { notionBlockIdSchema } from "@notionhq/custom-blocks-protocol/utils/ids.js"
+import * as v from "valibot"
+
+export const customBlockHostInitialStateSchema = v.object({
+	theme: notionThemeSchema,
+	/**
+	 * Defaults to standard for existing host integrations.
+	 * TODO(custom-blocks): Make this required when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION increases to 4.
+	 */
+	contrastMode: v.optional(notionContrastModeSchema),
+	blockId: notionBlockIdSchema,
+	parent: notionParentSchema,
+	page: customBlockPageSchema,
+	manifest: manifestSchema,
+	dataSources: v.object({ bindings: bridgeDataSourceBindingsSchema }),
+	currentUser: bridgeUserSchema,
+})
+
+export type CustomBlockHostInitialState = v.InferInput<
+	typeof customBlockHostInitialStateSchema
+>
+
+export type CustomBlockHostInitialStateResult =
+	| {
+			status: "success"
+			initialState: CustomBlockHostInitialState
+	  }
+	| {
+			status: "error"
+			error: CustomBlockInitErrorInfo
+	  }
+
+export const customBlockHostPreparedStateResultSchema = v.variant("status", [
+	v.object({
+		status: v.literal("success"),
+		initialState: v.omit(customBlockHostInitialStateSchema, ["manifest"]),
+	}),
+	v.object({
+		status: v.literal("error"),
+		error: customBlockInitErrorInfoSchema,
+	}),
+])
+
+/** Adapter-owned state or an explicit preparation error. The host adds the manifest to init. */
+export type CustomBlockHostPreparedStateResult =
+	| {
+			status: "success"
+			initialState: Omit<CustomBlockHostInitialState, "manifest">
+	  }
+	| { status: "error"; error: CustomBlockInitErrorInfo }
+
+export type CustomBlockHostPrepareInitialState = (args: {
+	manifest: BridgeCustomBlockManifest
+	signal: AbortSignal
+}) => Promise<CustomBlockHostPreparedStateResult>

package/src/context/resize.ts

@@ -0,0 +1,4 @@
+import type { resizeMessageSchema } from "@notionhq/custom-blocks-protocol/context/messages/resize.js"
+import type { InferInput } from "valibot"
+
+export type ResizeMessageInput = InferInput<typeof resizeMessageSchema>