@notionhq/custom-blocks-host 0.3.8 → 0.4.0

package/dist/createCustomBlockHost.js

@@ -1,14 +1,15 @@
 import { notionDataSourceBindingsSchema } from "./protocol/dataSources/dataSource.js";
 import { notionDataSourceIdSchema } from "./protocol/ids.js";
 import { hostToSandboxMessageSchema, } from "./protocol/messages/hostToSandbox.js";
-import { initMessageSchema, } from "./protocol/messages/init.js";
+import { CustomBlockInitializationError, initMessageSchema, } from "./protocol/messages/init.js";
 import { LATEST_BRIDGE_PROTOCOL_VERSION } from "./protocol/protocolVersion.js";
 import * as v from "valibot";
-import { contextUnavailableError, invalidPropertyBindingError, missingDataSourceBindingError, missingPropertyBindingError, unknownInitializationError, } from "./lifecycle/initErrors.js";
+import { normalizeHostToSandboxMessage } from "./compatibility/normalizeHostToSandboxMessage.js";
+import { isAllowedLocalPreviewUrl } from "./isAllowedLocalPreviewUrl.js";
+import { contextUnavailableError, invalidLocalPreviewUrlError, invalidPropertyBindingError, missingDataSourceBindingError, missingPropertyBindingError, unknownInitializationError, } from "./lifecycle/initErrors.js";
 import { createInitializationController } from "./lifecycle/initializationController.js";
-import { loadCustomBlockManifest } from "./lifecycle/loadCustomBlockManifest.js";
-import { normalizeHostToSandboxMessage } from "./lifecycle/normalizeHostToSandboxMessage.js";
-import { customBlockHostInitialStateSchema } from "./lifecycle/types.js";
+import { resolveManifest } from "./lifecycle/resolveManifest.js";
+import { customBlockHostInitialStateSchema, customBlockHostManifestResultSchema, customBlockHostPreparedStateResultSchema, } from "./lifecycle/types.js";
 import { parseExternalUrl } from "./messages/parseExternalUrl.js";
 import { createSandboxMessageRouter } from "./messages/sandboxMessageRouter.js";
 import { MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION } from "./protocolVersion.js";
@@ -20,7 +21,9 @@ import { unreachable } from "./utils.js";
 // Earlier SDKs cannot represent this context, so the host reports context_unavailable.
 const BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE = 5;
 export function createCustomBlockHost(options) {
-    const { iframe, prepareInitialState: prepareAdapterState, handlers, onInitialized, onConnectionFailure, onLog, onQueryUnsubscribed, sandboxOrigin, minBridgeProtocolVersion: configuredMinBridgeProtocolVersion, noConnectTimeoutMs, initialStateTimeoutMs, noInitResultTimeoutMs, } = options;
+    const { iframe, prepareInitialState: prepareAdapterState, handlers, onStatusChange, onLog, onQueryUnsubscribed, minBridgeProtocolVersion: configuredMinBridgeProtocolVersion, noConnectTimeoutMs, initialStateTimeoutMs, noInitResultTimeoutMs, } = options;
+    const sandboxUrl = parseSandboxUrl(options.sandboxUrl, options.manifestSource);
+    const sandboxOrigin = sandboxUrl.origin;
     // Callers can retire older SDKs, but cannot restore support for protocols
     // the runtime no longer implements. Omission uses the runtime minimum.
     const minBridgeProtocolVersion = Math.max(configuredMinBridgeProtocolVersion ??
@@ -46,7 +49,7 @@ export function createCustomBlockHost(options) {
             case "preparingInit":
             case "waitingForInitResult":
             case "initialized":
-            case "error":
+            case "failed":
                 break;
             // A stopped host must not send messages, including pending responses.
             // Return from the function to skip delivery below.
@@ -75,7 +78,7 @@ export function createCustomBlockHost(options) {
             case "waitingForConnect":
             case "preparingInit":
             case "waitingForInitResult":
-            case "error":
+            case "failed":
             case "stopped":
                 return;
             default:
@@ -149,7 +152,7 @@ export function createCustomBlockHost(options) {
     }
     function updateHostState(update) {
         if (initializationController.status === "stopped" ||
-            initializationController.status === "error") {
+            initializationController.status === "failed") {
             return;
         }
         Object.assign(pendingState, update);
@@ -255,15 +258,29 @@ export function createCustomBlockHost(options) {
         }
     }
     const initializationController = createInitializationController({
+        manifestSource: options.manifestSource,
         async prepareInit(connect) {
+            const connectManifest = connect.status === "success" ? connect.manifest : undefined;
             sandboxBridgeProtocolVersion = connect.bridgeProtocolVersion;
-            const result = await preparation;
+            onStatusChange({
+                status: "preparingInit",
+                localManifest: isAllowedLocalPreviewUrl({
+                    url: sandboxUrl,
+                    hostOrigin: window.location.origin,
+                })
+                    ? connectManifest
+                    : undefined,
+                bridgeProtocolVersion: connect.bridgeProtocolVersion,
+                sdkVersion: connect.sdkVersion,
+            });
+            const result = await (preparation ?? prepare(connectManifest));
             if (initializationController.status !== "preparingInit") {
                 return result;
             }
             return finalizeInitialState(result);
         },
         sendInitMessage,
+        onInitSent: () => onStatusChange({ status: "waitingForInitResult" }),
         warn: payload => emit("warn", payload),
         flushPendingHostStateChanges,
         minBridgeProtocolVersion,
@@ -273,12 +290,16 @@ export function createCustomBlockHost(options) {
         stopHostWithFailure: stopWithFailure,
         onInitResult(message) {
             if (message.status === "success" && manifest !== undefined) {
-                onInitialized?.({ manifest, initialHeight: message.initialHeight });
+                onStatusChange({
+                    status: "initialized",
+                    resolvedManifest: manifest,
+                    initialHeight: message.initialHeight,
+                });
             }
         },
         onConnectionFailure: failure => {
             preparationController.abort();
-            onConnectionFailure?.(failure);
+            onStatusChange({ status: "failed", error: failure });
         },
     });
     function finalizeInitialState(result) {
@@ -310,8 +331,21 @@ export function createCustomBlockHost(options) {
         hasPreparedInitialState = true;
         return { status: "success", initialState };
     }
-    // Attach rejection handling immediately: preparation may finish before connect.
-    const preparation = prepare().catch((error) => {
+    // Neither manifest source waits for the other. Observe rejections immediately,
+    // including failures from a host manifest that is not selected.
+    const hostManifest = readHostManifest().catch(handlePreparationError);
+    const preparation = options.manifestSource === "host"
+        ? prepare(undefined).catch(handlePreparationError)
+        : undefined;
+    async function readHostManifest() {
+        preparationController.signal.throwIfAborted();
+        const result = await options.getPersistedManifest({
+            signal: preparationController.signal,
+        });
+        preparationController.signal.throwIfAborted();
+        return v.parse(customBlockHostManifestResultSchema, result);
+    }
+    function handlePreparationError(error) {
         if (!preparationController.signal.aborted) {
             emit("warn", {
                 message: "Failed to prepare custom block initialization",
@@ -319,34 +353,30 @@ export function createCustomBlockHost(options) {
             });
         }
         return { status: "error", error: unknownInitializationError() };
-    });
-    async function prepare() {
-        const loaded = await loadCustomBlockManifest({
-            ...options,
-            sandboxOrigin,
-            signal: preparationController.signal,
-            onError: error => {
-                emit("warn", {
-                    message: "Failed to load custom block manifest",
-                    error,
-                });
-            },
+    }
+    async function prepare(connectManifest) {
+        preparationController.signal.throwIfAborted();
+        const manifestResult = await resolveManifest({
+            manifestSource: options.manifestSource,
+            hostManifest,
+            connectManifest,
         });
-        if (loaded.status === "error") {
-            return loaded;
+        preparationController.signal.throwIfAborted();
+        if (manifestResult.status === "error") {
+            return manifestResult;
         }
-        if (preparationController.signal.aborted) {
-            return { status: "error", error: unknownInitializationError() };
-        }
-        const result = await prepareAdapterState({
-            manifest: loaded.manifest,
+        const result = v.parse(customBlockHostPreparedStateResultSchema, await prepareAdapterState({
+            manifest: manifestResult.manifest,
             signal: preparationController.signal,
-        });
+        }));
         return result.status === "error"
             ? result
             : {
                 status: "success",
-                initialState: { ...result.initialState, manifest: loaded.manifest },
+                initialState: {
+                    ...result.initialState,
+                    manifest: manifestResult.manifest,
+                },
             };
     }
     const onMessage = createSandboxMessageRouter({
@@ -372,7 +402,7 @@ export function createCustomBlockHost(options) {
     });
     window.addEventListener("message", onMessage);
     iframe.addEventListener("load", initializationController.onIframeLoad);
-    function stop() {
+    function releaseResources() {
         navigationAbortController.abort();
         preparationController.abort();
         window.removeEventListener("message", onMessage);
@@ -380,11 +410,26 @@ export function createCustomBlockHost(options) {
         initializationController.stop();
         querySubscriptions.unsubscribeAll();
     }
+    function stop() {
+        const previousStatus = initializationController.status;
+        releaseResources();
+        if (previousStatus !== "stopped" && previousStatus !== "failed") {
+            onStatusChange({ status: "stopped" });
+        }
+    }
     function stopWithFailure(error) {
-        stop();
+        if (initializationController.status === "stopped") {
+            return;
+        }
+        if (initializationController.status === "failed") {
+            releaseResources();
+            return;
+        }
+        releaseResources();
         emit("warn", error);
-        onConnectionFailure?.(error);
+        onStatusChange({ status: "failed", error });
     }
+    onStatusChange({ status: "waitingForConnect" });
     return {
         stop,
         setTheme(theme) {
@@ -448,6 +493,26 @@ export function createCustomBlockHost(options) {
         },
     };
 }
+function parseSandboxUrl(url, manifestSource) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch (error) {
+        if (manifestSource === "host") {
+            throw error;
+        }
+        throw new CustomBlockInitializationError(invalidLocalPreviewUrlError());
+    }
+    if (manifestSource === "sandbox" &&
+        !isAllowedLocalPreviewUrl({
+            url: parsed,
+            hostOrigin: window.location.origin,
+        })) {
+        throw new CustomBlockInitializationError(invalidLocalPreviewUrlError());
+    }
+    return parsed;
+}
 function getCollectionSchema(dataSources, dataSourceId) {
     return Object.values(dataSources?.bindings ?? {}).find(binding => binding.collectionPointer?.id === dataSourceId)?.collectionSchema;
 }

package/dist/index.d.ts

@@ -1,26 +1,9 @@
-export type { LegacyNotionDataSourcePageBridge } from "./protocol/dataSources/dataSourcePage.js";
-export type { NotionPropertySchemasById } from "./protocol/dataSources/propertySchema.js";
-export type { CustomBlockErrorInfo } from "./protocol/errors.js";
-export type { NotionPageId } from "./protocol/ids.js";
-export type { CustomBlockManifest } from "./protocol/manifest.js";
-export type { CreatePageMessage } from "./protocol/messages/createPage.js";
-export type { GetPageMessage } from "./protocol/messages/getPage.js";
-export type { GetUserMessage } from "./protocol/messages/getUser.js";
-export type { ListUsersMessage } from "./protocol/messages/listUsers.js";
-export type { OpenExternalUrlMessage } from "./protocol/messages/openExternalUrl.js";
-export type { OpenPageMessage } from "./protocol/messages/openPage.js";
-export type { CustomBlockCheckboxFilterOperator, CustomBlockContainsFilterOperator, CustomBlockCreatedByFilterOperator, CustomBlockDateFilterOperator, CustomBlockNumberFilterOperator, CustomBlockOptionFilterOperator, CustomBlockPeopleFilterOperator, CustomBlockPersonFilterValue, CustomBlockRelationFilterOperator, CustomBlockStatusFilterOperator, CustomBlockStatusGroupFilterOperator, CustomBlockStatusGroupName, CustomBlockTextFilterOperator, QueryDataSourceMessage, ResolvedCustomBlockDataSourceFilter, ResolvedCustomBlockDataSourcePropertyFilter, ResolvedCustomBlockDataSourceSort, } from "./protocol/messages/queryDataSource.js";
-export type { ResizeMessage } from "./protocol/messages/resize.js";
-export type { UpdatePageMessage } from "./protocol/messages/updatePage.js";
-export type { NotionDateInput, NotionFileInput, NotionPageCover, NotionPageData, NotionPageIcon, NotionPagePropertyReadMap, NotionPagePropertyValue, NotionPagePropertyWriteMap, NotionRichTextItem, NotionSelectOptionInput, } from "./protocol/pages/page.js";
-export { LATEST_BRIDGE_PROTOCOL_VERSION, LEGACY_PROPERTY_SHAPE_PROTOCOL_VERSION, } from "./protocol/protocolVersion.js";
 export { type AutoBindableProperty, getAutoBoundPropertyIdsByKey, } from "./autoBindProperties.js";
 export { type CustomBlockHostHandle, type CustomBlockHostOptions, createCustomBlockHost, } from "./createCustomBlockHost.js";
 export { type CustomBlockDateValue, InvalidNotionDateError, toNotionDateValue, } from "./dateValue.js";
 export { toNotionPageId } from "./ids.js";
-export type { CustomBlockHostManifestOptions } from "./lifecycle/manifestOptions.js";
-export type { ConnectSuccessMessage, CustomBlockHostDataSourcesPayload, CustomBlockHostInitialState, CustomBlockHostInitialStateResult, CustomBlockHostPreparedStateResult, CustomBlockHostPrepareInitialState, } from "./lifecycle/types.js";
-export { isLocalCustomBlockUrl } from "./localBlockUrl.js";
+export { isAllowedLocalPreviewUrl } from "./isAllowedLocalPreviewUrl.js";
+export type { CustomBlockHostDataSourcesPayload, CustomBlockHostInitialState, CustomBlockHostInitialStateResult, CustomBlockHostManifestResult, CustomBlockHostPreparedStateResult, CustomBlockHostPrepareInitialState, CustomBlockHostStatus, CustomBlockManifestSource, } from "./lifecycle/types.js";
 export type { CreatePageMessageInput, CustomBlockHostCreatePageResult, CustomBlockHostFailure, CustomBlockHostGetPageResult, CustomBlockHostGetUserResult, CustomBlockHostHandlers, CustomBlockHostListUsersResult, CustomBlockHostLogDirection, CustomBlockHostNavigationContext, CustomBlockHostOpenExternalUrlResult, CustomBlockHostOpenPageResult, CustomBlockHostUpdatePageResult, GetPageMessageInput, GetUserMessageInput, ListUsersMessageInput, OpenExternalUrlMessageInput, OpenPageMessageInput, QueryDataSourceMessageInput, ResizeMessageInput, UpdatePageMessageInput, } from "./messages/types.js";
 export type { CustomBlockHostQueryDataSourceResult } from "./queries/types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,gCAAgC,EAAE,MAAM,gEAAgE,CAAA;AACtH,YAAY,EAAE,yBAAyB,EAAE,MAAM,gEAAgE,CAAA;AAC/G,YAAY,EAAE,oBAAoB,EAAE,MAAM,4CAA4C,CAAA;AACtF,YAAY,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAA;AAC3E,YAAY,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AACvF,YAAY,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,YAAY,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,YAAY,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,YAAY,EAAE,gBAAgB,EAAE,MAAM,wDAAwD,CAAA;AAC9F,YAAY,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAA;AAC1G,YAAY,EAAE,eAAe,EAAE,MAAM,uDAAuD,CAAA;AAC5F,YAAY,EACX,iCAAiC,EACjC,iCAAiC,EACjC,kCAAkC,EAClC,6BAA6B,EAC7B,+BAA+B,EAC/B,+BAA+B,EAC/B,+BAA+B,EAC/B,4BAA4B,EAC5B,iCAAiC,EACjC,+BAA+B,EAC/B,oCAAoC,EACpC,0BAA0B,EAC1B,6BAA6B,EAC7B,sBAAsB,EACtB,mCAAmC,EACnC,2CAA2C,EAC3C,iCAAiC,GACjC,MAAM,8DAA8D,CAAA;AACrE,YAAY,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAA;AACxF,YAAY,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,YAAY,EACX,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,EACd,yBAAyB,EACzB,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,uBAAuB,GACvB,MAAM,gDAAgD,CAAA;AACvD,OAAO,EACN,8BAA8B,EAC9B,sCAAsC,GACtC,MAAM,qDAAqD,CAAA;AAC5D,OAAO,EACN,KAAK,oBAAoB,EACzB,4BAA4B,GAC5B,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,qBAAqB,GACrB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACN,KAAK,oBAAoB,EACzB,sBAAsB,EACtB,iBAAiB,GACjB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACzC,YAAY,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AACpF,YAAY,EACX,qBAAqB,EACrB,iCAAiC,EACjC,2BAA2B,EAC3B,iCAAiC,EACjC,kCAAkC,EAClC,kCAAkC,GAClC,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAC1D,YAAY,EACX,sBAAsB,EACtB,+BAA+B,EAC/B,sBAAsB,EACtB,4BAA4B,EAC5B,4BAA4B,EAC5B,uBAAuB,EACvB,8BAA8B,EAC9B,2BAA2B,EAC3B,gCAAgC,EAChC,oCAAoC,EACpC,6BAA6B,EAC7B,+BAA+B,EAC/B,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,2BAA2B,EAC3B,oBAAoB,EACpB,2BAA2B,EAC3B,kBAAkB,EAClB,sBAAsB,GACtB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,oCAAoC,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,oBAAoB,EACzB,4BAA4B,GAC5B,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,qBAAqB,GACrB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACN,KAAK,oBAAoB,EACzB,sBAAsB,EACtB,iBAAiB,GACjB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AACxE,YAAY,EACX,iCAAiC,EACjC,2BAA2B,EAC3B,iCAAiC,EACjC,6BAA6B,EAC7B,kCAAkC,EAClC,kCAAkC,EAClC,qBAAqB,EACrB,yBAAyB,GACzB,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACX,sBAAsB,EACtB,+BAA+B,EAC/B,sBAAsB,EACtB,4BAA4B,EAC5B,4BAA4B,EAC5B,uBAAuB,EACvB,8BAA8B,EAC9B,2BAA2B,EAC3B,gCAAgC,EAChC,oCAAoC,EACpC,6BAA6B,EAC7B,+BAA+B,EAC/B,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,2BAA2B,EAC3B,oBAAoB,EACpB,2BAA2B,EAC3B,kBAAkB,EAClB,sBAAsB,GACtB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,oCAAoC,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/index.js

@@ -1,6 +1,5 @@
-export { LATEST_BRIDGE_PROTOCOL_VERSION, LEGACY_PROPERTY_SHAPE_PROTOCOL_VERSION, } from "./protocol/protocolVersion.js";
 export { getAutoBoundPropertyIdsByKey, } from "./autoBindProperties.js";
 export { createCustomBlockHost, } from "./createCustomBlockHost.js";
 export { InvalidNotionDateError, toNotionDateValue, } from "./dateValue.js";
 export { toNotionPageId } from "./ids.js";
-export { isLocalCustomBlockUrl } from "./localBlockUrl.js";
+export { isAllowedLocalPreviewUrl } from "./isAllowedLocalPreviewUrl.js";

package/dist/{localBlockUrl.d.ts → isAllowedLocalPreviewUrl.d.ts}

@@ -4,8 +4,8 @@
  * Local refers to the block server, not the environment where the host runs.
  * Requires the embedding page's origin and rejects URLs that share that origin.
  */
-export declare function isLocalCustomBlockUrl({ url, hostOrigin, }: {
+export declare function isAllowedLocalPreviewUrl({ url, hostOrigin, }: {
     url: URL;
     hostOrigin: string;
 }): boolean;
-//# sourceMappingURL=localBlockUrl.d.ts.map
+//# sourceMappingURL=isAllowedLocalPreviewUrl.d.ts.map

package/dist/isAllowedLocalPreviewUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isAllowedLocalPreviewUrl.d.ts","sourceRoot":"","sources":["../src/isAllowedLocalPreviewUrl.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,EACxC,GAAG,EACH,UAAU,GACV,EAAE;IACF,GAAG,EAAE,GAAG,CAAA;IACR,UAAU,EAAE,MAAM,CAAA;CAClB,GAAG,OAAO,CAOV"}

package/dist/{localBlockUrl.js → isAllowedLocalPreviewUrl.js}

@@ -1,17 +1,13 @@
+import { isLocalBlockServerUrl } from "./protocol/isLocalBlockServerUrl.js";
 /**
  * Checks whether a URL can serve a local custom block over HTTP or HTTPS.
  * Accepts localhost, any .localhost subdomain, and 127.0.0.1 without credentials.
  * Local refers to the block server, not the environment where the host runs.
  * Requires the embedding page's origin and rejects URLs that share that origin.
  */
-export function isLocalCustomBlockUrl({ url, hostOrigin, }) {
+export function isAllowedLocalPreviewUrl({ url, hostOrigin, }) {
     return (typeof hostOrigin === "string" &&
         hostOrigin !== "" &&
         url.origin !== hostOrigin &&
-        (url.protocol === "http:" || url.protocol === "https:") &&
-        (url.hostname === "localhost" ||
-            url.hostname === "127.0.0.1" ||
-            url.hostname.endsWith(".localhost")) &&
-        url.username === "" &&
-        url.password === "");
+        isLocalBlockServerUrl(url));
 }

package/dist/lifecycle/initErrors.d.ts

@@ -21,4 +21,5 @@ export declare function invalidPropertyBindingError(): CustomBlockErrorInfo<"inv
 export declare function noInitResultError(): CustomBlockErrorInfo<"no_init_result">;
 export declare function invalidInitResultPayloadError(): CustomBlockErrorInfo<"invalid_init_result_payload">;
 export declare function unknownInitializationError(): CustomBlockErrorInfo<"unknown_error">;
+export declare function invalidLocalPreviewUrlError(): CustomBlockErrorInfo<"invalid_local_preview_url">;
 //# sourceMappingURL=initErrors.d.ts.map

package/dist/lifecycle/initErrors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initErrors.d.ts","sourceRoot":"","sources":["../../src/lifecycle/initErrors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4CAA4C,CAAA;AAEtF;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,oBAAoB,CAAC,YAAY,CAAC,CAOnE;AAED,wBAAgB,0BAA0B,IAAI,oBAAoB,CAAC,yBAAyB,CAAC,CAO5F;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IACjD,4BAA4B,EAAE,MAAM,GAAG,SAAS,CAAA;CAChD,GAAG,oBAAoB,CAAC,0BAA0B,CAAC,CAQnD;AAED,wBAAgB,+BAA+B,CAAC,IAAI,EAAE;IACrD,4BAA4B,EAAE,MAAM,CAAA;IACpC,wBAAwB,EAAE,MAAM,CAAA;CAChC,GAAG,oBAAoB,CAAC,8BAA8B,CAAC,CAQvD;AAED,wBAAgB,uBAAuB,IAAI,oBAAoB,CAAC,qBAAqB,CAAC,CAOrF;AAED,wBAAgB,wBAAwB,IAAI,oBAAoB,CAAC,uBAAuB,CAAC,CAOxF;AAED,wBAAgB,6BAA6B,IAAI,oBAAoB,CAAC,6BAA6B,CAAC,CAOnG;AAED,wBAAgB,2BAA2B,IAAI,oBAAoB,CAAC,0BAA0B,CAAC,CAO9F;AAED,wBAAgB,2BAA2B,IAAI,oBAAoB,CAAC,0BAA0B,CAAC,CAQ9F;AAED,wBAAgB,iBAAiB,IAAI,oBAAoB,CAAC,gBAAgB,CAAC,CAO1E;AAED,wBAAgB,6BAA6B,IAAI,oBAAoB,CAAC,6BAA6B,CAAC,CAOnG;AAED,wBAAgB,0BAA0B,IAAI,oBAAoB,CAAC,eAAe,CAAC,CAOlF"}
+{"version":3,"file":"initErrors.d.ts","sourceRoot":"","sources":["../../src/lifecycle/initErrors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4CAA4C,CAAA;AAEtF;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,oBAAoB,CAAC,YAAY,CAAC,CAOnE;AAED,wBAAgB,0BAA0B,IAAI,oBAAoB,CAAC,yBAAyB,CAAC,CAO5F;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IACjD,4BAA4B,EAAE,MAAM,GAAG,SAAS,CAAA;CAChD,GAAG,oBAAoB,CAAC,0BAA0B,CAAC,CAQnD;AAED,wBAAgB,+BAA+B,CAAC,IAAI,EAAE;IACrD,4BAA4B,EAAE,MAAM,CAAA;IACpC,wBAAwB,EAAE,MAAM,CAAA;CAChC,GAAG,oBAAoB,CAAC,8BAA8B,CAAC,CAQvD;AAED,wBAAgB,uBAAuB,IAAI,oBAAoB,CAAC,qBAAqB,CAAC,CAOrF;AAED,wBAAgB,wBAAwB,IAAI,oBAAoB,CAAC,uBAAuB,CAAC,CAOxF;AAED,wBAAgB,6BAA6B,IAAI,oBAAoB,CAAC,6BAA6B,CAAC,CAOnG;AAED,wBAAgB,2BAA2B,IAAI,oBAAoB,CAAC,0BAA0B,CAAC,CAO9F;AAED,wBAAgB,2BAA2B,IAAI,oBAAoB,CAAC,0BAA0B,CAAC,CAQ9F;AAED,wBAAgB,iBAAiB,IAAI,oBAAoB,CAAC,gBAAgB,CAAC,CAO1E;AAED,wBAAgB,6BAA6B,IAAI,oBAAoB,CAAC,6BAA6B,CAAC,CAOnG;AAED,wBAAgB,0BAA0B,IAAI,oBAAoB,CAAC,eAAe,CAAC,CAOlF;AAED,wBAAgB,2BAA2B,IAAI,oBAAoB,CAAC,2BAA2B,CAAC,CAO/F"}

package/dist/lifecycle/initErrors.js

@@ -102,3 +102,10 @@ export function unknownInitializationError() {
         isRetryable: false,
     };
 }
+export function invalidLocalPreviewUrlError() {
+    return {
+        code: "invalid_local_preview_url",
+        message: "Local custom blocks require an HTTP(S) URL on localhost, a .localhost subdomain, or 127.0.0.1, without credentials and on a different origin from the host.",
+        isRetryable: false,
+    };
+}

package/dist/lifecycle/initializationController.d.ts

@@ -3,9 +3,10 @@ import type { CustomBlockInitErrorInfo, initMessageSchema } from "../protocol/me
 import type { InitResultMessage } from "../protocol/messages/initResult.js";
 import type { InferInput } from "valibot";
 import type { CustomBlockHostFailure } from "../messages/types.js";
-import type { ConnectSuccessMessage, CustomBlockHostInitialStateResult, InitStatus } from "./types.js";
+import type { CustomBlockHostInitialStateResult, CustomBlockManifestSource, InitStatus } from "./types.js";
 export type InitializationControllerOptions = {
-    prepareInit: (connect: ConnectSuccessMessage) => Promise<CustomBlockHostInitialStateResult>;
+    manifestSource: CustomBlockManifestSource;
+    prepareInit: (connect: ConnectMessage) => Promise<CustomBlockHostInitialStateResult>;
     sendInitMessage: (message: InferInput<typeof initMessageSchema>) => void;
     warn: (payload: unknown) => void;
     flushPendingHostStateChanges: () => void;
@@ -14,8 +15,9 @@ export type InitializationControllerOptions = {
     initialStateTimeoutMs?: number;
     noInitResultTimeoutMs?: number;
     stopHostWithFailure: (error: CustomBlockHostFailure) => void;
-    onInitResult?: (message: InitResultMessage) => void;
-    onConnectionFailure: ((error: CustomBlockHostFailure) => void) | undefined;
+    onInitResult: (message: InitResultMessage) => void;
+    onInitSent: () => void;
+    onConnectionFailure: (error: CustomBlockHostFailure) => void;
 };
 export type InitializationController = {
     readonly status: InitStatus;

package/dist/lifecycle/initializationController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initializationController.d.ts","sourceRoot":"","sources":["../../src/lifecycle/initializationController.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EACX,wBAAwB,EACxB,iBAAiB,EACjB,MAAM,mDAAmD,CAAA;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAWlE,OAAO,KAAK,EACX,qBAAqB,EACrB,iCAAiC,EACjC,UAAU,EACV,MAAM,YAAY,CAAA;AAMnB,MAAM,MAAM,+BAA+B,GAAG;IAC7C,WAAW,EAAE,CACZ,OAAO,EAAE,qBAAqB,KAC1B,OAAO,CAAC,iCAAiC,CAAC,CAAA;IAC/C,eAAe,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,KAAK,IAAI,CAAA;IACxE,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IAChC,4BAA4B,EAAE,MAAM,IAAI,CAAA;IACxC,wBAAwB,EAAE,MAAM,CAAA;IAChC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,mBAAmB,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAA;IAC5D,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACnD,mBAAmB,EAAE,CAAC,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;CAC1E,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACtC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAA;IACrC,aAAa,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IAChD,gBAAgB,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACtD,oBAAoB,EAAE,CAAC,IAAI,EAAE;QAC5B,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;QACpC,KAAK,EAAE,wBAAwB,CAAA;QAC/B,qBAAqB,EAAE,MAAM,GAAG,SAAS,CAAA;KACzC,KAAK,SAAS,GAAG,MAAM,CAAA;IACxB,uBAAuB,EAAE,CAAC,IAAI,EAAE;QAC/B,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;QACpC,KAAK,EAAE,wBAAwB,CAAA;KAC/B,KAAK,IAAI,CAAA;IACV,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,IAAI,EAAE,MAAM,IAAI,CAAA;CAChB,CAAA;AAED,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,+BAA+B,GACtC,wBAAwB,CAuV1B"}
+{"version":3,"file":"initializationController.d.ts","sourceRoot":"","sources":["../../src/lifecycle/initializationController.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EACX,wBAAwB,EACxB,iBAAiB,EACjB,MAAM,mDAAmD,CAAA;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAWlE,OAAO,KAAK,EACX,iCAAiC,EACjC,yBAAyB,EACzB,UAAU,EACV,MAAM,YAAY,CAAA;AAMnB,MAAM,MAAM,+BAA+B,GAAG;IAC7C,cAAc,EAAE,yBAAyB,CAAA;IACzC,WAAW,EAAE,CACZ,OAAO,EAAE,cAAc,KACnB,OAAO,CAAC,iCAAiC,CAAC,CAAA;IAC/C,eAAe,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,KAAK,IAAI,CAAA;IACxE,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IAChC,4BAA4B,EAAE,MAAM,IAAI,CAAA;IACxC,wBAAwB,EAAE,MAAM,CAAA;IAChC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,mBAAmB,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAA;IAC5D,YAAY,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IAClD,UAAU,EAAE,MAAM,IAAI,CAAA;IACtB,mBAAmB,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAA;CAC5D,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACtC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAA;IACrC,aAAa,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IAChD,gBAAgB,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACtD,oBAAoB,EAAE,CAAC,IAAI,EAAE;QAC5B,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;QACpC,KAAK,EAAE,wBAAwB,CAAA;QAC/B,qBAAqB,EAAE,MAAM,GAAG,SAAS,CAAA;KACzC,KAAK,SAAS,GAAG,MAAM,CAAA;IACxB,uBAAuB,EAAE,CAAC,IAAI,EAAE;QAC/B,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;QACpC,KAAK,EAAE,wBAAwB,CAAA;KAC/B,KAAK,IAAI,CAAA;IACV,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,IAAI,EAAE,MAAM,IAAI,CAAA;CAChB,CAAA;AAED,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,+BAA+B,GACtC,wBAAwB,CAoW1B"}

package/dist/lifecycle/initializationController.js

@@ -6,7 +6,7 @@ const DEFAULT_NO_CONNECT_TIMEOUT_MS = 5_000;
 const DEFAULT_INITIAL_STATE_TIMEOUT_MS = 5_000;
 const DEFAULT_NO_INIT_RESULT_TIMEOUT_MS = 5_000;
 export function createInitializationController(options) {
-    const { prepareInit, sendInitMessage, warn, flushPendingHostStateChanges, minBridgeProtocolVersion, noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS, initialStateTimeoutMs = DEFAULT_INITIAL_STATE_TIMEOUT_MS, noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS, stopHostWithFailure, onInitResult, onConnectionFailure, } = options;
+    const { manifestSource, prepareInit, sendInitMessage, warn, flushPendingHostStateChanges, minBridgeProtocolVersion, noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS, initialStateTimeoutMs = DEFAULT_INITIAL_STATE_TIMEOUT_MS, noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS, stopHostWithFailure, onInitResult, onInitSent, onConnectionFailure, } = options;
     let initStatus = "waitingForConnect";
     let noConnectTimeoutId;
     let initialStateTimeoutId;
@@ -40,13 +40,13 @@ export function createInitializationController(options) {
                 break;
             case "waitingForInitResult":
             case "initialized":
-            case "error":
+            case "failed":
             case "stopped":
                 return;
             default:
                 return unreachable(initStatus);
         }
-        initStatus = "error";
+        initStatus = "failed";
         activeInitializationId = initializationId;
         clearNoConnectTimeout();
         clearInitialStateTimeout();
@@ -56,7 +56,7 @@ export function createInitializationController(options) {
             status: "error",
             error,
         });
-        onConnectionFailure?.({ ...error, phase, source });
+        onConnectionFailure({ ...error, phase, source });
     }
     async function prepareAndSendInit(connect) {
         if (initStatus !== "waitingForConnect") {
@@ -111,13 +111,20 @@ export function createInitializationController(options) {
                 dataSources: preparation.initialState.dataSources,
             };
             sendInitMessage(message);
+            if (initStatus !== "waitingForInitResult") {
+                return;
+            }
+            onInitSent();
+            if (initStatus !== "waitingForInitResult") {
+                return;
+            }
             noInitResultTimeoutId = window.setTimeout(() => {
                 if (initStatus !== "waitingForInitResult") {
                     return;
                 }
-                initStatus = "error";
+                initStatus = "failed";
                 const error = noInitResultError();
-                onConnectionFailure?.({ ...error, phase: "initResult", source: "host" });
+                onConnectionFailure({ ...error, phase: "initResult", source: "host" });
                 warn({
                     ...error,
                     initializationId: connect.initializationId,
@@ -173,8 +180,10 @@ export function createInitializationController(options) {
             });
             return;
         }
-        // If the sandbox reported an error during `connect`, return it as an `init` error.
-        if (message.status === "error") {
+        // Invalid sandbox metadata does not prevent initialization from a host manifest.
+        if (message.status === "error" &&
+            (manifestSource === "sandbox" ||
+                message.error.code !== "manifest_invalid")) {
             sendInitError({
                 initializationId: message.initializationId,
                 error: message.error,
@@ -225,9 +234,9 @@ export function createInitializationController(options) {
         }
         clearNoConnectTimeout();
         clearNoInitResultTimeout();
-        initStatus = "error";
+        initStatus = "failed";
         warn(error);
-        onConnectionFailure?.({ ...error, phase: "initResult", source: "host" });
+        onConnectionFailure({ ...error, phase: "initResult", source: "host" });
     }
     function onIframeLoad() {
         if (initStatus === "stopped") {
@@ -254,10 +263,10 @@ export function createInitializationController(options) {
                 // Only do anything if the iframe loaded before the `connect` message was sent.
                 return;
             }
-            initStatus = "error";
+            initStatus = "failed";
             const error = noConnectError();
             warn(error);
-            onConnectionFailure?.({ ...error, phase: "connect", source: "host" });
+            onConnectionFailure({ ...error, phase: "connect", source: "host" });
         }, noConnectTimeoutMs);
     }
     function handleInitResult(message) {
@@ -270,18 +279,18 @@ export function createInitializationController(options) {
             return;
         }
         clearNoInitResultTimeout();
-        initStatus = message.status === "success" ? "initialized" : "error";
+        initStatus = message.status === "success" ? "initialized" : "failed";
         if (message.status === "success") {
             flushPendingHostStateChanges();
         }
         else {
-            onConnectionFailure?.({
+            onConnectionFailure({
                 ...message.error,
                 phase: "initResult",
                 source: "sandbox",
             });
         }
-        onInitResult?.(message);
+        onInitResult(message);
     }
     function stop() {
         initStatus = "stopped";

package/dist/lifecycle/resolveManifest.d.ts

@@ -0,0 +1,13 @@
+import type { CustomBlockManifest } from "../protocol/manifest.js";
+import type { CustomBlockHostNormalizedManifestResult, CustomBlockManifestSource } from "./types.js";
+/**
+ * Select the host's manifest result or the sandbox's connect declaration. Both
+ * sources are already validated. Forward host errors unchanged, and report
+ * manifest_unavailable if the sandbox omits its declaration.
+ */
+export declare function resolveManifest(args: {
+    manifestSource: CustomBlockManifestSource;
+    hostManifest: Promise<CustomBlockHostNormalizedManifestResult>;
+    connectManifest: CustomBlockManifest | undefined;
+}): Promise<CustomBlockHostNormalizedManifestResult>;
+//# sourceMappingURL=resolveManifest.d.ts.map

package/dist/lifecycle/resolveManifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveManifest.d.ts","sourceRoot":"","sources":["../../src/lifecycle/resolveManifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AACvF,OAAO,KAAK,EACX,uCAAuC,EACvC,yBAAyB,EACzB,MAAM,YAAY,CAAA;AAEnB;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC3C,cAAc,EAAE,yBAAyB,CAAA;IACzC,YAAY,EAAE,OAAO,CAAC,uCAAuC,CAAC,CAAA;IAC9D,eAAe,EAAE,mBAAmB,GAAG,SAAS,CAAA;CAChD,GAAG,OAAO,CAAC,uCAAuC,CAAC,CAenD"}

package/dist/lifecycle/resolveManifest.js

@@ -0,0 +1,21 @@
+/**
+ * Select the host's manifest result or the sandbox's connect declaration. Both
+ * sources are already validated. Forward host errors unchanged, and report
+ * manifest_unavailable if the sandbox omits its declaration.
+ */
+export async function resolveManifest(args) {
+    if (args.manifestSource === "host") {
+        return args.hostManifest;
+    }
+    if (args.connectManifest !== undefined) {
+        return { status: "success", manifest: args.connectManifest };
+    }
+    return {
+        status: "error",
+        error: {
+            code: "manifest_unavailable",
+            message: "The sandbox did not provide a manifest in connect.",
+            isRetryable: false,
+        },
+    };
+}