@adobe/aio-commerce-lib-admin-ui 0.2.0-beta-20260714082406 → 0.2.0

package/CHANGELOG.md

@@ -1,50 +1,32 @@
 # @adobe/aio-commerce-lib-admin-ui
 
-## 0.2.0-beta-20260714082406
-### Minor Changes
-
+## 0.2.0
 
+### Minor Changes
 
 - [#528](https://github.com/adobe/aio-commerce-sdk/pull/528) [`0bb7d15`](https://github.com/adobe/aio-commerce-sdk/commit/0bb7d150961f631116b1ac421124960b5b857896) Thanks [@oshmyheliuk](https://github.com/oshmyheliuk)! - Add `getGridColumnAclResourceId`, `getMassActionAclResourceId`, and `getOrderViewButtonAclResourceId` helpers to derive the Commerce ACL resource id for protected grid columns, mass actions, and order view buttons, mirroring `getMenuAclResourceId`.
 
-
-
 - [#522](https://github.com/adobe/aio-commerce-sdk/pull/522) [`4396a64`](https://github.com/adobe/aio-commerce-sdk/commit/4396a647ad22dba063cdf03a16e04aef9387212f) Thanks [@oshmyheliuk](https://github.com/oshmyheliuk)! - Add `getAdminUiPermissionClient` for checking ACL permissions at runtime (SPA bootstrap and runtime action entry). Includes in-process TTL cache, in-flight request deduplication, and deny-by-default on errors. Also exports `getAclResourceId` for deterministic ACL resource id derivation from `metadata.id`.
 
-
-
 - [#542](https://github.com/adobe/aio-commerce-sdk/pull/542) [`c15b50f`](https://github.com/adobe/aio-commerce-sdk/commit/c15b50f667e6d1288270dbd4192c150db0ff0914) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Add browser helpers for Admin UI iframe extensions.
 
-
-
 - [#508](https://github.com/adobe/aio-commerce-sdk/pull/508) [`c36f825`](https://github.com/adobe/aio-commerce-sdk/commit/c36f825aff7329fc2831d8aaca032d17bbee373a) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Add `@adobe/aio-commerce-lib-admin-ui/menu` entrypoint with named constants for Commerce Admin menu IDs (`MENU_SALES`, `MENU_CATALOG`, etc.), a `COMMERCE_MENUS` collection, a `CommerceMenu` type, and an `isCommerceMenu` type guard.
 
-
-
 - [#516](https://github.com/adobe/aio-commerce-sdk/pull/516) [`bdcced9`](https://github.com/adobe/aio-commerce-sdk/commit/bdcced9297ae5e1b87ce86490a2b6fad76b2e341) Thanks [@obarcelonap](https://github.com/obarcelonap)! - Add `order-view-buttons` entrypoint with request parsing and response builders for `commerce/backend-ui/2` order view button handlers.
 
-
-
 - [#551](https://github.com/adobe/aio-commerce-sdk/pull/551) [`a66f389`](https://github.com/adobe/aio-commerce-sdk/commit/a66f3892622584d27cd6b5d2fc633e15bf9942a8) Thanks [@asalloum5](https://github.com/asalloum5)! - Add `enableAdminUiSdk` to the Admin UI API client, which enables the Admin UI SDK in Commerce via `PUT /V1/adminuisdk/config`.
 
-
-
 - [#486](https://github.com/adobe/aio-commerce-sdk/pull/486) [`413da36`](https://github.com/adobe/aio-commerce-sdk/commit/413da36dcd83e5a41c194f5af50611097659e725) Thanks [@obarcelonap](https://github.com/obarcelonap)! - Add request and response builders for the `commerce/backend-ui/2` grid column wire contract.
 
-
-
 - [#546](https://github.com/adobe/aio-commerce-sdk/pull/546) [`ca2c4fe`](https://github.com/adobe/aio-commerce-sdk/commit/ca2c4febcdfbe52b933775f08e9a53765fc306ab) Thanks [@obarcelonap](https://github.com/obarcelonap)! - Remove `extensionUrl` from extension registration params. The Commerce backend now derives the view URL from the App Registry, so the field has no effect for v2 installed apps.
 
-
-
-- [#492](https://github.com/adobe/aio-commerce-sdk/pull/492) [`ce63b2b`](https://github.com/adobe/aio-commerce-sdk/commit/ce63b2b46f7ef1f2f68780b13e52d1c13fd5fe6e) Thanks [@jcuerdo](https://github.com/jcuerdo)! - Add `mass-actions` entrypoint with wire contract helpers for `commerce/backend-ui/2` mass actions. Parse worker action requests with `parseMassActionRequest`, build success/error responses with `okMassActionResponse`/`errorMassActionResponse`, and parse iframe selection parameters with `parseMassActionSelection`.
-
+- [#492](https://github.com/adobe/aio-commerce-sdk/pull/492) [`ce63b2b`](https://github.com/adobe/aio-commerce-sdk/commit/ce63b2b46f7ef1f2f68780b13e52d1c13fd5fe6e) Thanks [@jcuerdo](https://github.com/jcuerdo)! - Add `mass-actions` entrypoint with wire contract helpers for `commerce/backend-ui/2` mass actions. Parse worker action requests with `parseMassActionRequest`, and build success/error responses with `okMassActionResponse`/`errorMassActionResponse`.
 
 ### Patch Changes
 
 - Updated dependencies [[`19400fb`](https://github.com/adobe/aio-commerce-sdk/commit/19400fbdfc03c5bbfc30f995a2acdd4272c5e032), [`ce7768e`](https://github.com/adobe/aio-commerce-sdk/commit/ce7768e0ddc6ca35ad6ccec60f584c8bb5a743f0), [`4396a64`](https://github.com/adobe/aio-commerce-sdk/commit/4396a647ad22dba063cdf03a16e04aef9387212f), [`e85bec4`](https://github.com/adobe/aio-commerce-sdk/commit/e85bec40f1eaa91dd6bb7bc6954b2ecfc3ea4029), [`413da36`](https://github.com/adobe/aio-commerce-sdk/commit/413da36dcd83e5a41c194f5af50611097659e725)]:
-  - @adobe/aio-commerce-lib-core@1.2.0-beta-20260714082406
-  - @adobe/aio-commerce-lib-api@1.3.0-beta-20260714082406
+  - @adobe/aio-commerce-lib-core@1.2.0
+  - @adobe/aio-commerce-lib-api@1.3.0
 
 ## 0.1.0
 

package/dist/cjs/mass-actions/index.cjs

@@ -51,58 +51,6 @@ function getMassActionAclResourceId(metadataId, entity, actionId) {
 	return `${appRoot}_${entity}_massactions_${require_acl_resource_id.sanitizeSegment(actionId)}`;
 }
 
-//#endregion
-//#region source/mass-actions/view/schema.ts
-/**
-* Schema for the `selection` query parameter Commerce appends to the iframe URL
-* of a view mass action.
-*
-* Commerce serializes the selection as a JSON-encoded string:
-* `?selection={"ids":["000000001"],"gridType":"customer"}`
-*/
-const MassActionSelectionSchema = valibot.object({
-	gridType: valibot.picklist([
-		"order",
-		"product",
-		"customer"
-	]),
-	ids: valibot.pipe(valibot.array(require_schemas.nonEmptyStringValueSchema("id")), valibot.minLength(1, "The value of \"ids\" must contain at least one entry"))
-});
-
-//#endregion
-//#region source/mass-actions/view/presets.ts
-/**
-* Parses the `selection` query parameter Commerce appends to the iframe URL of
-* a view mass action.
-*
-* Commerce serializes the selection as a JSON string:
-* `?selection={"ids":["000000001","000000002"],"gridType":"customer"}`
-*
-* Throws a `CommerceSdkValidationError` if the input is missing, not valid
-* JSON, or does not match the expected shape.
-*
-* @param rawSelection - The raw string value of the `selection` query parameter.
-*
-* @example
-* ```ts
-* import { parseMassActionSelection } from "@adobe/aio-commerce-lib-admin-ui/mass-actions";
-*
-* // In your SPA route handler:
-* const raw = new URLSearchParams(window.location.search).get("selection");
-* const { ids, gridType } = parseMassActionSelection(raw);
-* ```
-*/
-function parseMassActionSelection(rawSelection) {
-	if (rawSelection === null || rawSelection === void 0) throw new Error("Invalid mass action selection: the selection query parameter is missing.");
-	let parsed;
-	try {
-		parsed = JSON.parse(String(rawSelection));
-	} catch (error) {
-		throw new Error(`Invalid mass action selection: expected a JSON string, got: ${String(rawSelection)}`, { cause: error });
-	}
-	return require_utils.parseOrThrow(MassActionSelectionSchema, parsed, "Invalid mass action selection");
-}
-
 //#endregion
 //#region source/mass-actions/worker/schema.ts
 /**
@@ -180,9 +128,7 @@ function massActionErrorResponse(statusCode, errorMessage) {
 //#endregion
 exports.MassActionGridTypeSchema = MassActionGridTypeSchema;
 exports.MassActionRequestSchema = MassActionRequestSchema;
-exports.MassActionSelectionSchema = MassActionSelectionSchema;
 exports.getMassActionAclResourceId = getMassActionAclResourceId;
 exports.massActionErrorResponse = massActionErrorResponse;
 exports.okMassActionResponse = okMassActionResponse;
-exports.parseMassActionRequest = parseMassActionRequest;
-exports.parseMassActionSelection = parseMassActionSelection;
+exports.parseMassActionRequest = parseMassActionRequest;

package/dist/cjs/mass-actions/index.d.cts

@@ -42,47 +42,6 @@ import { ErrorResponse, SuccessResponse } from "@adobe/aio-commerce-lib-core/res
  */
 declare function getMassActionAclResourceId(metadataId: string, entity: AdminUiEntity, actionId: string): string;
 //#endregion
-//#region source/mass-actions/view/schema.d.ts
-/**
- * Schema for the `selection` query parameter Commerce appends to the iframe URL
- * of a view mass action.
- *
- * Commerce serializes the selection as a JSON-encoded string:
- * `?selection={"ids":["000000001"],"gridType":"customer"}`
- */
-declare const MassActionSelectionSchema: v.ObjectSchema<{
-  readonly gridType: v.PicklistSchema<["order", "product", "customer"], undefined>;
-  readonly ids: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>, undefined>, v.MinLengthAction<string[], 1, "The value of \"ids\" must contain at least one entry">]>;
-}, undefined>;
-//#endregion
-//#region source/mass-actions/view/types.d.ts
-/** Parsed `selection` query parameter appended by Commerce to the iframe URL. */
-type MassActionSelection = v.InferOutput<typeof MassActionSelectionSchema>;
-//#endregion
-//#region source/mass-actions/view/presets.d.ts
-/**
- * Parses the `selection` query parameter Commerce appends to the iframe URL of
- * a view mass action.
- *
- * Commerce serializes the selection as a JSON string:
- * `?selection={"ids":["000000001","000000002"],"gridType":"customer"}`
- *
- * Throws a `CommerceSdkValidationError` if the input is missing, not valid
- * JSON, or does not match the expected shape.
- *
- * @param rawSelection - The raw string value of the `selection` query parameter.
- *
- * @example
- * ```ts
- * import { parseMassActionSelection } from "@adobe/aio-commerce-lib-admin-ui/mass-actions";
- *
- * // In your SPA route handler:
- * const raw = new URLSearchParams(window.location.search).get("selection");
- * const { ids, gridType } = parseMassActionSelection(raw);
- * ```
- */
-declare function parseMassActionSelection(rawSelection: unknown): MassActionSelection;
-//#endregion
 //#region source/mass-actions/worker/schema.d.ts
 /**
  * Grid identifier sent by Commerce on the `commerce/backend-ui/2` wire contract
@@ -157,4 +116,4 @@ declare function okMassActionResponse(body?: MassActionResponseBody): SuccessRes
  */
 declare function massActionErrorResponse(statusCode: number, errorMessage: string): ErrorResponse<MassActionErrorBody>;
 //#endregion
-export { type AdminUiEntity, type MassActionErrorBody, type MassActionGridType, MassActionGridTypeSchema, type MassActionRequest, MassActionRequestSchema, type MassActionResponseBody, type MassActionSelection, MassActionSelectionSchema, getMassActionAclResourceId, massActionErrorResponse, okMassActionResponse, parseMassActionRequest, parseMassActionSelection };
+export { type AdminUiEntity, type MassActionErrorBody, type MassActionGridType, MassActionGridTypeSchema, type MassActionRequest, MassActionRequestSchema, type MassActionResponseBody, getMassActionAclResourceId, massActionErrorResponse, okMassActionResponse, parseMassActionRequest };

package/dist/cjs/web/index.cjs

@@ -53,6 +53,37 @@ function isControlFrame() {
 	return isEmbeddedInHost() && !window.name;
 }
 
+//#endregion
+//#region source/web/react/result.ts
+/** Creates a successful data result. */
+function ok(data) {
+	return {
+		data,
+		error: null
+	};
+}
+/** Creates a failed data result. */
+function error(message, options) {
+	return {
+		data: null,
+		error: new Error(message, options)
+	};
+}
+/** Creates a successful actions result. */
+function okActions(actions) {
+	return {
+		actions,
+		error: null
+	};
+}
+/** Creates a failed actions result. */
+function actionsError(message, options) {
+	return {
+		actions: null,
+		error: new Error(message, options)
+	};
+}
+
 //#endregion
 //#region source/web/react/auth/context/ims-context.tsx
 const ImsContextValue = (0, react.createContext)(void 0);
@@ -60,14 +91,13 @@ const ImsContextValue = (0, react.createContext)(void 0);
 * Returns the IMS credentials provided by the host. Works inside the Commerce Admin and the
 * Experience Cloud shell.
 *
-* @throws If no host provides credentials (e.g. the app is running standalone, outside both the
-* Commerce Admin and the Experience Cloud shell).
+* Returns an error when no host provides credentials.
 */
 function useIms() {
 	const credentials = (0, react.use)(ImsContextValue);
-	if (credentials === void 0) throw new Error("useIms must be used inside an ImsContextProvider.");
-	if (!credentials) throw new Error("useIms requires running inside the Commerce Admin or the Experience Cloud shell, which provide the IMS credentials.");
-	return credentials;
+	if (credentials === void 0) return error("useIms must be used inside an ImsContextProvider.");
+	if (!credentials) return error("useIms requires running inside the Commerce Admin or the Experience Cloud shell, which provide the IMS credentials.");
+	return ok(credentials);
 }
 /**
 * Provides the IMS credentials for a mounted Admin UI iframe app.
@@ -89,9 +119,7 @@ const SharedContextValue = (0, react.createContext)(void 0);
 * Returns the current Commerce shared context provider state.
 */
 function useInternalSharedContext() {
-	const context = (0, react.use)(SharedContextValue);
-	if (context === void 0) throw new Error("useSharedContext must be used inside a SharedContextProvider, which is only available in the Commerce Admin.");
-	return context;
+	return (0, react.use)(SharedContextValue);
 }
 /**
 * Returns the current Commerce shared context. The guest connection is already established by
@@ -101,26 +129,29 @@ function useInternalSharedContext() {
 * Prefer a purpose-built hook ({@link useCommerce}, {@link useMassActionContext},
 * {@link useOrderViewButtonContext}) when one covers what you need.
 *
-* @throws If used outside a {@link SharedContextProvider}.
-*
 * @example
 * ```tsx
 * import { useSharedContext } from "@adobe/aio-commerce-lib-admin-ui/web";
 *
 * function ImsTokenLabel() {
-*   const { sharedContext } = useSharedContext();
-*   return <span>{sharedContext.get("imsToken")}</span>;
+*   const { data, error } = useSharedContext();
+*   if (error) return null;
+*   return <span>{data.sharedContext.get("imsToken")}</span>;
 * }
 * ```
 */
 function useSharedContext() {
-	const { extensionId, guestConnection } = useInternalSharedContext();
-	const sharedContext = useLiveSharedContext(guestConnection);
-	return {
-		extensionId,
-		host: guestConnection.host,
-		sharedContext
-	};
+	const context = useInternalSharedContext();
+	const sharedContext = useLiveSharedContext(context?.guestConnection);
+	return (0, react.useMemo)(() => {
+		if (!context) return error("useSharedContext must be used inside a SharedContextProvider, which is only available in the Commerce Admin.");
+		if (!sharedContext) return error("The Commerce host did not provide a shared context for this extension.");
+		return ok({
+			extensionId: context.extensionId,
+			host: context.guestConnection.host,
+			sharedContext
+		});
+	}, [context, sharedContext]);
 }
 /**
 * Tracks the live UIX `sharedContext` for a connection.
@@ -132,7 +163,10 @@ function useSharedContext() {
 * @param guestConnection - The established guest connection.
 */
 function useLiveSharedContext(guestConnection) {
-	return (0, react.useSyncExternalStore)((0, react.useCallback)((onContextChange) => guestConnection.addEventListener("contextchange", onContextChange), [guestConnection]), () => guestConnection.sharedContext);
+	return (0, react.useSyncExternalStore)((0, react.useCallback)((onContextChange) => {
+		if (!guestConnection) return () => void 0;
+		return guestConnection.addEventListener("contextchange", onContextChange);
+	}, [guestConnection]), () => guestConnection?.sharedContext ?? null);
 }
 /**
 * Provides the Commerce shared context for a mounted Admin UI iframe app.
@@ -154,28 +188,33 @@ function SharedContextProvider(props) {
 //#endregion
 //#region source/web/react/promise-cache.ts
 /**
-* Creates a keyed cache that memoizes in-flight, resolved, and rejected promises, giving `use()`
+* Creates a keyed cache that memoizes in-flight, successful, and failed promises, giving `use()`
 * the reference-stable promise it needs while suspended and single-flighting side-effecting
 * establishment calls across re-renders, remounts, and StrictMode double-invocation.
 *
-* Rejections are retained (not evicted) so `use()` replays them to an error boundary instead of
-* suspending forever on a fresh pending promise. Retry a failed key via {@link RetryablePromiseCache.evict}.
+* Promise rejections are failures by default. Pass `isFailure` when a fulfilled value, such as an
+* error result, must also be retryable. Failed entries remain cached until `evictIfFailed` is
+* called, so retries never replace a stable promise during render.
+*
+* @param isFailure - Determines whether a fulfilled value represents a failure.
 */
-function createRetryablePromiseCache() {
+function createRetryablePromiseCache(isFailure = () => false) {
 	const cache = /* @__PURE__ */ new Map();
 	return {
-		evictIfRejected(key) {
-			if (cache.get(key)?.rejected) cache.delete(key);
+		evictIfFailed(key) {
+			if (cache.get(key)?.failed) cache.delete(key);
 		},
 		get(key, create) {
 			const cached = cache.get(key);
 			if (cached) return cached.promise;
 			const entry = {
-				promise: create(),
-				rejected: false
+				failed: false,
+				promise: create()
 			};
-			entry.promise.catch(() => {
-				entry.rejected = true;
+			entry.promise.then((value) => {
+				entry.failed = isFailure(value);
+			}).catch(() => {
+				entry.failed = true;
 			});
 			cache.set(key, entry);
 			return entry.promise;
@@ -185,7 +224,7 @@ function createRetryablePromiseCache() {
 
 //#endregion
 //#region source/web/react/commerce/hooks/use-commerce.ts
-const commerceHosts = createRetryablePromiseCache();
+const commerceHosts = createRetryablePromiseCache((result) => result.error !== null);
 /**
 * Returns the cached Commerce Admin host promise for an extension, resolving it once over the
 * given guest connection. The value is static for the lifetime of the connection.
@@ -194,24 +233,31 @@ const commerceHosts = createRetryablePromiseCache();
 * @param connection - The established guest connection.
 */
 function getCommerceHostPromise(extensionId, connection) {
-	const { integration } = connection.host;
-	if (!integration) throw new Error("The host does not provide the integration API needed to resolve the Commerce host.");
-	return commerceHosts.get(extensionId, () => integration.getCommerceHost());
+	return commerceHosts.get(extensionId, async () => {
+		const { integration } = connection.host;
+		if (!integration) return error("The host does not provide the integration API needed to resolve the Commerce host.");
+		try {
+			return ok({ commerceHost: await integration.getCommerceHost() });
+		} catch (cause) {
+			return error("Failed to resolve the Commerce host.", { cause });
+		}
+	});
 }
 /** Drops a failed Commerce host resolution for `extensionId`, so a later render retries it. */
 function retryCommerceHost(extensionId) {
-	commerceHosts.evictIfRejected(extensionId);
+	commerceHosts.evictIfFailed(extensionId);
 }
 /**
 * Returns the host (domain) of the Commerce Admin the extension is embedded in, resolving it over
 * the guest connection.
 *
-* @throws If used outside a Commerce Admin UI frame, or when the host does not expose the
-* Commerce integration API.
+* Returns an error when used outside a Commerce Admin UI frame, when the host does not expose the
+* Commerce integration API, or when resolving the host fails.
 */
 function useCommerce() {
-	const { extensionId, guestConnection } = useInternalSharedContext();
-	return { commerceHost: (0, react.use)(getCommerceHostPromise(extensionId, guestConnection)) };
+	const context = useInternalSharedContext();
+	if (!context) return error("useCommerce requires running inside the Commerce Admin.");
+	return (0, react.use)(getCommerceHostPromise(context.extensionId, context.guestConnection));
 }
 
 //#endregion
@@ -220,28 +266,31 @@ function useCommerce() {
 * Returns the context for a mass-action extension point: the selected row IDs the action was
 * triggered with. The value is read from the host-provided Commerce context.
 *
-* @throws If used outside the Commerce shared context, or when that context does not include a
-* mass-action selection.
+* Returns an error outside the Commerce shared context, or when the mass-action selection is
+* missing, empty, or contains a non-string row ID.
 */
 function useMassActionContext() {
-	const { sharedContext } = useSharedContext();
+	const { data, error: contextError } = useSharedContext();
 	return (0, react.useMemo)(() => {
-		const selectedIds = sharedContext.get("selectedIds");
-		if (!Array.isArray(selectedIds)) throw new Error("Could not find `selectedIds` in the Commerce shared context. Is this frame running as a mass-action extension point?");
-		return { selectedIds };
-	}, [sharedContext]);
+		if (contextError) return error(contextError.message, { cause: contextError });
+		const selectedIds = data.sharedContext.get("selectedIds");
+		if (!Array.isArray(selectedIds)) return error("Could not find `selectedIds` in the Commerce shared context. Is this frame running as a mass-action extension point?");
+		if (selectedIds.length === 0) return error("No rows selected. A mass-action extension point must be triggered with at least one selected row.");
+		if (selectedIds.some((id) => typeof id !== "string")) return error("Some of the `selectedIds` in the Commerce shared context are not strings. All selected row IDs must be strings.");
+		return ok({ selectedIds });
+	}, [data, contextError]);
 }
 /**
 * Returns the context for an order view-button extension point: the order ID the button was
 * triggered from.
 *
-* @throws If no order ID is present in the page URL.
+* Returns an error when no order ID is present in the page URL.
 */
 function useOrderViewButtonContext() {
 	return (0, react.useMemo)(() => {
 		const orderId = parseOrderId(globalThis.location.href);
-		if (orderId === null) throw new Error("Could not find an order ID. Is this frame running as an order view-button extension point?");
-		return { orderId };
+		if (orderId === null) return error("Could not find an order ID. Is this frame running as an order view-button extension point?");
+		return ok({ orderId });
 	}, []);
 }
 
@@ -250,51 +299,39 @@ function useOrderViewButtonContext() {
 /**
 * Returns typed helpers for interacting with the Commerce Admin host.
 *
-* @throws If called before the guest connection is established, or when the host frame actions
-* are unavailable.
-*
 * @example
 * ```tsx
 * import { useHostConnection } from "@adobe/aio-commerce-lib-admin-ui/web";
 *
 * function DoneButton() {
-*   const { close } = useHostConnection();
-*   return <button onClick={() => void close()}>Done</button>;
+*   const { actions, error } = useHostConnection();
+*   if (error) return null;
+*   return <button onClick={actions.close}>Done</button>;
 * }
 * ```
 */
 function useHostConnection() {
-	const { host } = useSharedContext();
+	const { data, error: contextError } = useSharedContext();
 	return (0, react.useMemo)(() => {
-		const { field } = host;
-		const requireField = () => {
-			if (!field) throw new Error("Host frame actions are unavailable. They require an established guest connection with a host that exposes frame actions.");
-			return field;
-		};
-		return {
-			close: () => requireField().close(),
-			closeWithError: () => requireField().onError()
-		};
-	}, [host]);
+		if (contextError) return actionsError(contextError.message, { cause: contextError });
+		const { field } = data.host;
+		if (!field) return actionsError("Host frame actions are unavailable. They require an established guest connection with a host that exposes frame actions.");
+		return okActions({
+			close: () => field.close(),
+			closeWithError: () => field.onError()
+		});
+	}, [data, contextError]);
 }
 
 //#endregion
 //#region source/web/react/routing/lib.ts
 const HASH_ROUTE_PREFIX_PATTERN = /^[#/]+/u;
 /**
-* Determines if a given route is an index route.
-* @param route The route to check.
-*/
-function isIndexRoute(route) {
-	return "index" in route && route.index;
-}
-/**
 * Returns the path for a given route, removing any leading hash or slash characters.
 * @param route The route to get the path for.
 */
 function getRoutePath(route) {
-	if (isIndexRoute(route)) return "/";
-	return route.path.replace(HASH_ROUTE_PREFIX_PATTERN, "");
+	return route.path.replace(HASH_ROUTE_PREFIX_PATTERN, "") || "/";
 }
 /**
 * Returns the "to" path for a given route, removing any leading hash or slash characters.
@@ -436,7 +473,7 @@ function useGuestConnection(extensionId) {
 }
 /** Drops a failed connection for `extensionId`, so a later render re-attaches. */
 function retryGuestConnection(extensionId) {
-	guestConnections.evictIfRejected(extensionId);
+	guestConnections.evictIfFailed(extensionId);
 }
 
 //#endregion
@@ -627,9 +664,10 @@ function CommerceGuestConnection(props) {
 }
 /** Renders IMS-gated route content for a Commerce Admin UI frame. */
 function CommerceExtensionContent() {
-	const { sharedContext } = useSharedContext();
+	const { data, error } = useSharedContext();
+	if (error) throw error;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ImsContextProvider, {
-		credentials: resolveCommerceImsCredentials(sharedContext),
+		credentials: resolveCommerceImsCredentials(data.sharedContext),
 		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_tanstack_react_router.Outlet, {})
 	});
 }
@@ -785,11 +823,12 @@ function Entrypoint(props) {
 *
 * createExtensionApp({
 *   metadata: { extensionId: "my-extension-id" },
-*   routes: [{ index: true, element: <MainPage /> }],
+*   menu: <MainPage />,
 * });
 * ```
 */
-function createExtensionApp({ metadata, routes, root: customRoot }) {
+function createExtensionApp({ menu, metadata, routes = [], root: customRoot }) {
+	if (menu !== void 0 && routes.some((route) => getRouteTo(route.path) === "/")) throw new Error("The \"/\" route is reserved for the menu. Pass its element through the menu option instead.");
 	const rootElement = customRoot ?? document.getElementById("root");
 	if (!rootElement) throw new Error("Could not find an element with id \"root\".");
 	const root = (0, react_dom_client.createRoot)(rootElement);
@@ -798,7 +837,10 @@ function createExtensionApp({ metadata, routes, root: customRoot }) {
 			extensionId: metadata.extensionId,
 			initialConfigurationPromise,
 			runtime
-		}), routes);
+		}), menu === void 0 ? routes : [{
+			element: menu,
+			path: "/"
+		}, ...routes]);
 		root.render(/* @__PURE__ */ (0, react_jsx_runtime.jsx)(react.StrictMode, { children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_tanstack_react_router.RouterProvider, { router }) }));
 	};
 	try {