@adobe/aio-commerce-lib-admin-ui 0.1.0 → 0.2.0-alpha-20260722091448

package/dist/es/web/index.mjs

@@ -0,0 +1,861 @@
+/**
+ * @license
+ *
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { StrictMode, Suspense, createContext, use, useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import Runtime, { init } from "@adobe/exc-app";
+import page from "@adobe/exc-app/page.js";
+import { Outlet, RouterProvider, createHashHistory, createRootRoute, createRoute, createRouter, useCanGoBack, useRouter, useRouterState } from "@tanstack/react-router";
+import { createRoot } from "react-dom/client";
+import { attach, register } from "@adobe/uix-guest";
+import { Provider } from "@react-spectrum/s2/Provider";
+import { ProgressCircle } from "@react-spectrum/s2/ProgressCircle";
+import { Button, ButtonGroup } from "@react-spectrum/s2/ButtonGroup";
+import { Content, Heading, IllustratedMessage } from "@react-spectrum/s2/IllustratedMessage";
+import ErrorIllustration from "@react-spectrum/s2/illustrations/linear/Error";
+import { ErrorBoundary } from "react-error-boundary";
+
+//#region source/web/react/commerce/lib.ts
+/**
+* Extracts the order ID from the given URL (must be absolute).
+* @param href - The URL to read the order ID from (typically `window.location.href`).
+*/
+function parseOrderId(href) {
+	const urlObj = new URL(href);
+	return urlObj.searchParams.get("orderId") ?? new URLSearchParams(urlObj.hash.split("?")[1]).get("orderId");
+}
+/** Whether the app is embedded in a host frame (the Commerce Admin or the Experience Cloud shell). */
+function isEmbeddedInHost() {
+	return globalThis.window.parent !== globalThis.window;
+}
+/** Whether this window is a Commerce UIX guest UI frame, as opposed to a control frame or standalone. */
+function isUiFrame() {
+	return isEmbeddedInHost() && window.name.startsWith("uix-guest-");
+}
+/** Whether this window is a Commerce UIX guest control frame, which registers instead of attaching. */
+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 = createContext(void 0);
+/**
+* Returns the IMS credentials provided by the host. Works inside the Commerce Admin and the
+* Experience Cloud shell.
+*
+* Returns an error when no host provides credentials.
+*/
+function useIms() {
+	const credentials = use(ImsContextValue);
+	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.
+* @param props - The resolved credentials (or null while unavailable) and the children to render.
+*/
+function ImsContextProvider(props) {
+	const { children, credentials } = props;
+	if (isEmbeddedInHost() && !credentials) return null;
+	return /* @__PURE__ */ jsx(ImsContextValue.Provider, {
+		value: credentials,
+		children
+	});
+}
+
+//#endregion
+//#region source/web/react/commerce/context/shared-context.tsx
+const SharedContextValue = createContext(void 0);
+/**
+* Returns the current Commerce shared context provider state.
+*/
+function useInternalSharedContext() {
+	return use(SharedContextValue);
+}
+/**
+* Returns the current Commerce shared context. The guest connection is already established by
+* the time this can be called (see {@link SharedContextProvider}).
+*
+* This is a low-level escape hatch that exposes the raw `sharedContext` and `host` objects.
+* Prefer a purpose-built hook ({@link useCommerce}, {@link useMassActionContext},
+* {@link useOrderViewButtonContext}) when one covers what you need.
+*
+* @example
+* ```tsx
+* import { useSharedContext } from "@adobe/aio-commerce-lib-admin-ui/web";
+*
+* function ImsTokenLabel() {
+*   const { data, error } = useSharedContext();
+*   if (error) return null;
+*   return <span>{data.sharedContext.get("imsToken")}</span>;
+* }
+* ```
+*/
+function useSharedContext() {
+	const context = useInternalSharedContext();
+	const sharedContext = useLiveSharedContext(context?.guestConnection);
+	return 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.
+*
+* The host shares `sharedContext` on connect and may reassign it on later `contextchange`
+* events. `useSyncExternalStore` subscribes to those events and surfaces the current instance
+* (whose reference changes on each update), so consumers re-render when the host updates it.
+*
+* @param guestConnection - The established guest connection.
+*/
+function useLiveSharedContext(guestConnection) {
+	return useSyncExternalStore(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.
+* @param props - The props needed to initialize the shared context, including the already
+* established guest connection.
+*/
+function SharedContextProvider(props) {
+	const { children, guestConnection, extensionId } = props;
+	const value = useMemo(() => ({
+		extensionId,
+		guestConnection
+	}), [extensionId, guestConnection]);
+	return /* @__PURE__ */ jsx(SharedContextValue.Provider, {
+		value,
+		children
+	});
+}
+
+//#endregion
+//#region source/web/react/promise-cache.ts
+/**
+* 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.
+*
+* 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(isFailure = () => false) {
+	const cache = /* @__PURE__ */ new Map();
+	return {
+		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 = {
+				failed: false,
+				promise: create()
+			};
+			entry.promise.then((value) => {
+				entry.failed = isFailure(value);
+			}).catch(() => {
+				entry.failed = true;
+			});
+			cache.set(key, entry);
+			return entry.promise;
+		}
+	};
+}
+
+//#endregion
+//#region source/web/react/commerce/hooks/use-commerce.ts
+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.
+*
+* @param extensionId - The unique identifier for the extension app.
+* @param connection - The established guest connection.
+*/
+function getCommerceHostPromise(extensionId, connection) {
+	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.evictIfFailed(extensionId);
+}
+/**
+* Returns the host (domain) of the Commerce Admin the extension is embedded in, resolving it over
+* the guest connection.
+*
+* 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 context = useInternalSharedContext();
+	if (!context) return error("useCommerce requires running inside the Commerce Admin.");
+	return use(getCommerceHostPromise(context.extensionId, context.guestConnection));
+}
+
+//#endregion
+//#region source/web/react/commerce/hooks/use-extension-context.ts
+/**
+* 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.
+*
+* 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 { data, error: contextError } = useSharedContext();
+	return useMemo(() => {
+		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.
+*
+* Returns an error when no order ID is present in the page URL.
+*/
+function useOrderViewButtonContext() {
+	return useMemo(() => {
+		const orderId = parseOrderId(globalThis.location.href);
+		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 });
+	}, []);
+}
+
+//#endregion
+//#region source/web/react/commerce/hooks/use-host-connection.ts
+/**
+* Returns typed helpers for interacting with the Commerce Admin host.
+*
+* @example
+* ```tsx
+* import { useHostConnection } from "@adobe/aio-commerce-lib-admin-ui/web";
+*
+* function DoneButton() {
+*   const { actions, error } = useHostConnection();
+*   if (error) return null;
+*   return <button onClick={actions.close}>Done</button>;
+* }
+* ```
+*/
+function useHostConnection() {
+	const { data, error: contextError } = useSharedContext();
+	return useMemo(() => {
+		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;
+/**
+* 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) {
+	return route.path.replace(HASH_ROUTE_PREFIX_PATTERN, "") || "/";
+}
+/**
+* Returns the "to" path for a given route, removing any leading hash or slash characters.
+* @param path The path to convert to a "to" path.
+*/
+function getRouteTo(path) {
+	const routePath = path.replace(HASH_ROUTE_PREFIX_PATTERN, "");
+	return routePath ? `/${routePath}` : "/";
+}
+/**
+* Returns a router instance for an extension app, given the root component and route entries.
+*
+* @param rootComponent The root component of the extension app.
+* @param routeEntries The route entries for the extension app.
+* @param history The history implementation to use. Defaults to hash history; pass a memory
+*   history to get deterministic, seedable navigation (e.g. in tests).
+*/
+function createExtensionRouter(rootComponent, routeEntries, history = createHashHistory()) {
+	const rootRoute = createRootRoute({ component: () => rootComponent });
+	const routes = routeEntries.map((route) => createRoute({
+		component: () => route.element,
+		getParentRoute: () => rootRoute,
+		path: getRoutePath(route)
+	}));
+	return createRouter({
+		history,
+		routeTree: rootRoute.addChildren(routes)
+	});
+}
+
+//#endregion
+//#region source/web/runtime-loader.ts
+const EXPERIENCE_CLOUD_RUNTIME_HOST_PATTERN = /^(exc-unifiedcontent\.)?experience(-qa|-stage|-cdn|-cdn-stage)?\.adobe\.(com|net)$/u;
+/** Convenience no-operation function */
+const noop = () => void 0;
+/** Creates a mock implementation of the Experience Cloud runtime to be used when the real runtime is not available. */
+function createMockRuntime() {
+	return {
+		configured: false,
+		emit: noop,
+		lastConfigurationPayload: null,
+		off: noop,
+		on: noop
+	};
+}
+/** Retrieve the URL of the Experience Cloud runtime script from the current page's query parameters or session storage. */
+function getRuntimeScriptUrl() {
+	return new URL(globalThis.location.href).searchParams.get("_mr") || globalThis.sessionStorage.getItem("unifiedShellMRScript");
+}
+/**
+* Loads the Experience Cloud runtime script into the current document.
+* @throws {Error} If the runtime script cannot be loaded due to a missing or invalid script URL.
+*/
+function loadExperienceCloudRuntime() {
+	const runtimeScriptUrl = getRuntimeScriptUrl();
+	if (!runtimeScriptUrl) throw new Error("Module Runtime: Missing script.");
+	const url = new URL(decodeURIComponent(runtimeScriptUrl));
+	if (url.protocol !== "https:") throw new Error("Module Runtime: Must be HTTPS.");
+	if (!(EXPERIENCE_CLOUD_RUNTIME_HOST_PATTERN.test(url.hostname) || url.hostname === "localhost.corp.adobe.com" || url.hostname.endsWith(".localhost.corp.adobe.com"))) throw new Error("Module Runtime: Invalid domain.");
+	if (!url.pathname.endsWith(".js")) throw new Error("Module Runtime: Must be a JavaScript file.");
+	globalThis.sessionStorage.setItem("unifiedShellMRScript", url.toString());
+	const script = document.createElement("script");
+	script.async = true;
+	script.src = url.toString();
+	script.onload = () => {
+		if ("EXC_MR_READY" in globalThis && typeof globalThis.EXC_MR_READY === "function") globalThis.EXC_MR_READY();
+	};
+	document.head.append(script);
+}
+
+//#endregion
+//#region source/web/react/auth/lib.ts
+/**
+* Resolves IMS credentials from the Commerce shared context.
+* @param sharedContext - The Commerce shared context, established over the guest connection.
+*/
+function resolveCommerceImsCredentials(sharedContext) {
+	const imsToken = sharedContext.get("imsToken");
+	const imsOrgId = sharedContext.get("imsOrgId");
+	if (!(imsToken && imsOrgId)) return null;
+	return {
+		imsOrgId,
+		imsToken
+	};
+}
+/**
+* Resolves IMS credentials from the Experience Cloud shell configuration.
+* @param shellConfiguration - The Experience Cloud shell configuration, if available.
+*/
+function resolveShellImsCredentials(shellConfiguration) {
+	if (!shellConfiguration) return null;
+	const { imsToken, imsOrg: imsOrgId } = shellConfiguration;
+	return {
+		imsOrgId,
+		imsToken
+	};
+}
+
+//#endregion
+//#region source/web/react/centered-progress.tsx
+/**
+* A centered, indeterminate progress indicator used as a Suspense fallback.
+* @param props - The props needed to render the progress indicator.
+*/
+function CenteredProgress(props) {
+	return /* @__PURE__ */ jsx("div", {
+		style: {
+			alignItems: "center",
+			display: "flex",
+			justifyContent: "center",
+			minHeight: "calc(100dvh - 48px)",
+			padding: 24
+		},
+		children: /* @__PURE__ */ jsx(ProgressCircle, {
+			"aria-label": props["aria-label"],
+			isIndeterminate: true
+		})
+	});
+}
+
+//#endregion
+//#region source/web/react/commerce/hooks/use-guest-connection.ts
+const guestConnections = createRetryablePromiseCache();
+function getGuestConnectionPromise(extensionId) {
+	return guestConnections.get(extensionId, () => {
+		const promise = attach({ id: extensionId });
+		promise.catch((err) => {
+			console.error("UIX guest attach failed:", err);
+		});
+		return promise;
+	});
+}
+/**
+* Suspends until the guest connection for the given extension is established.
+* @param extensionId - The unique identifier for the extension app.
+*/
+function useGuestConnection(extensionId) {
+	return use(getGuestConnectionPromise(extensionId));
+}
+/** Drops a failed connection for `extensionId`, so a later render re-attaches. */
+function retryGuestConnection(extensionId) {
+	guestConnections.evictIfFailed(extensionId);
+}
+
+//#endregion
+//#region source/web/react/routing/hooks/use-spectrum-router.ts
+/**
+* Sets up a router instance for an extension app, based on the TanStack React Router example of React Spectrum.
+* @see https://react-spectrum.adobe.com/getting-started
+*/
+function useSpectrumRouter() {
+	const router = useRouter();
+	return useMemo(() => ({
+		navigate: (href, options) => {
+			if (typeof href === "string") return router.navigate({
+				to: getRouteTo(href),
+				...options
+			});
+			return router.navigate({
+				...href,
+				...options
+			});
+		},
+		useHref: (href) => {
+			const toOptions = typeof href === "string" ? { to: getRouteTo(href) } : href;
+			return router.buildLocation(toOptions).href;
+		}
+	}), [router]);
+}
+
+//#endregion
+//#region source/web/react/theme.ts
+/**
+* Maps host theme values to Spectrum S2 color schemes.
+* @param theme - The theme value provided by the host runtime.
+*/
+function getShellColorScheme(theme) {
+	switch (theme) {
+		case "dark":
+		case "spectrum--darkest": return "dark";
+		case "light":
+		case "spectrum--lightest": return "light";
+		default: return;
+	}
+}
+/**
+* Syncs the root `data-color-scheme` attribute used by Spectrum S2 page styles.
+*
+* @param colorScheme - The Spectrum S2 color scheme to apply.
+*/
+function syncRootColorScheme(colorScheme) {
+	if (!colorScheme) {
+		delete document.documentElement.dataset.colorScheme;
+		return;
+	}
+	document.documentElement.dataset.colorScheme = colorScheme;
+}
+
+//#endregion
+//#region source/web/react/extension/error-boundary.tsx
+function getErrorMessage(error) {
+	if (error instanceof Error) return error.message;
+	return typeof error === "string" ? error : "An unexpected error occurred.";
+}
+function ErrorFallback({ error, resetErrorBoundary }) {
+	const router = useRouter();
+	const canGoBack = useCanGoBack();
+	const goBack = useCallback(() => {
+		router.history.back();
+	}, [router]);
+	return /* @__PURE__ */ jsx("div", {
+		style: {
+			alignItems: "center",
+			display: "flex",
+			justifyContent: "center",
+			minHeight: "calc(100dvh - 48px)",
+			padding: 24
+		},
+		children: /* @__PURE__ */ jsxs(IllustratedMessage, { children: [
+			/* @__PURE__ */ jsx(ErrorIllustration, {}),
+			/* @__PURE__ */ jsx(Heading, { children: "Something went wrong" }),
+			/* @__PURE__ */ jsx(Content, { children: getErrorMessage(error) }),
+			/* @__PURE__ */ jsxs(ButtonGroup, { children: [canGoBack && /* @__PURE__ */ jsx(Button, {
+				onPress: goBack,
+				variant: "secondary",
+				children: "Go back"
+			}), /* @__PURE__ */ jsx(Button, {
+				onPress: resetErrorBoundary,
+				variant: "accent",
+				children: "Try again"
+			})] })
+		] })
+	});
+}
+/**
+* A wrapper component that provides an error boundary for extension apps.
+* It catches JavaScript errors anywhere in its child component tree, logs those errors, and displays a fallback UI.
+*
+* @param props - The props for the component, including children elements and an optional
+* `onReset` callback run before the boundary re-renders its children (via "Try again" or a
+* route change), e.g. to drop cached failures so a retry starts fresh.
+*/
+function ExtensionErrorBoundary(props) {
+	const routeKey = useRouterState({ select: (state) => state.matches.at(-1)?.pathname });
+	return /* @__PURE__ */ jsx(ErrorBoundary, {
+		FallbackComponent: ErrorFallback,
+		onReset: props.onReset,
+		resetKeys: [routeKey],
+		children: props.children
+	});
+}
+
+//#endregion
+//#region source/web/react/extension/commerce-app.tsx
+const controlFrameRegistrations = createRetryablePromiseCache();
+/**
+* Registers a Commerce Admin control frame with the UIX host, once per extension. `register`
+* has no teardown, so this is memoized rather than run inside an effect body every mount.
+*
+* @param extensionId - The unique identifier for the extension app.
+*/
+function registerControlFrame(extensionId) {
+	return controlFrameRegistrations.get(extensionId, () => {
+		const promise = register({
+			id: extensionId,
+			methods: {}
+		});
+		promise.catch((err) => {
+			console.error("UIX guest register failed:", err);
+		});
+		return promise;
+	});
+}
+/** The fallback UI shown when connecting to the Commerce host. */
+function ConnectionFallback() {
+	return /* @__PURE__ */ jsx(CenteredProgress, { "aria-label": "Connecting to Commerce Admin" });
+}
+/**
+* Renders the Commerce Admin flow: a control frame only needs to register itself with the UIX
+* host (no visible content), while a UI frame renders the routed extension-point content once
+* its guest connection is established.
+*
+* @param props - The props needed to initialize the extension app.
+*/
+function CommerceExtensionApp(props) {
+	const { extensionId } = props;
+	const spectrumRouter = useSpectrumRouter();
+	const resetConnections = useCallback(() => {
+		retryGuestConnection(extensionId);
+		retryCommerceHost(extensionId);
+	}, [extensionId]);
+	useEffect(() => {
+		syncRootColorScheme("light");
+	}, []);
+	if (isControlFrame()) return /* @__PURE__ */ jsx(ControlFrameRegistration, { extensionId });
+	return /* @__PURE__ */ jsx(Provider, {
+		colorScheme: "light",
+		router: spectrumRouter,
+		children: /* @__PURE__ */ jsx(ExtensionErrorBoundary, {
+			onReset: resetConnections,
+			children: /* @__PURE__ */ jsx(Suspense, {
+				fallback: /* @__PURE__ */ jsx(ConnectionFallback, {}),
+				children: /* @__PURE__ */ jsx(CommerceGuestConnection, { extensionId })
+			})
+		})
+	});
+}
+/**
+* Registers a Commerce Admin control frame with the UIX host. Renders no visible content.
+* @param props - The props needed to initialize the extension app.
+*/
+function ControlFrameRegistration(props) {
+	const { extensionId } = props;
+	useEffect(() => {
+		registerControlFrame(extensionId);
+	}, [extensionId]);
+	return null;
+}
+/**
+* Suspends until the guest connection is established, then provides the Commerce shared context.
+* @param props - The props needed to initialize the extension app.
+*/
+function CommerceGuestConnection(props) {
+	const { extensionId } = props;
+	return /* @__PURE__ */ jsx(SharedContextProvider, {
+		extensionId,
+		guestConnection: useGuestConnection(extensionId),
+		children: /* @__PURE__ */ jsx(CommerceExtensionContent, {})
+	});
+}
+/** Renders IMS-gated route content for a Commerce Admin UI frame. */
+function CommerceExtensionContent() {
+	const { data, error } = useSharedContext();
+	if (error) throw error;
+	return /* @__PURE__ */ jsx(ImsContextProvider, {
+		credentials: resolveCommerceImsCredentials(data.sharedContext),
+		children: /* @__PURE__ */ jsx(Outlet, {})
+	});
+}
+
+//#endregion
+//#region source/web/react/shell/hooks/use-extension-color-scheme.ts
+/**
+* Keeps the Spectrum S2 color scheme aligned with Experience Shell or browser defaults.
+* @param shellConfiguration - The Experience Shell configuration, if available.
+*/
+function useExtensionColorScheme(shellConfiguration) {
+	const colorScheme = getShellColorScheme(shellConfiguration?.theme);
+	useEffect(() => {
+		syncRootColorScheme(colorScheme);
+	}, [colorScheme]);
+	return colorScheme;
+}
+
+//#endregion
+//#region source/web/react/shell/hooks/use-shell-configuration.ts
+/**
+* Extracts the shell configuration from the runtime configuration (only the components we want to expose).
+* @param config The runtime configuration object.
+*/
+function extractShellConfiguration(config) {
+	const { imsOrg, imsToken, theme } = config;
+	return {
+		imsOrg,
+		imsToken,
+		theme
+	};
+}
+/**
+* Derives the exposed shell configuration from the given runtime instance.
+* @param runtime The runtime instance.
+*/
+function useShellConfiguration(runtime, initialConfiguration) {
+	const router = useRouter();
+	const [shellConfiguration, setShellConfiguration] = useState(() => initialConfiguration ? extractShellConfiguration(initialConfiguration) : null);
+	useEffect(() => {
+		const onConfiguration = (event) => {
+			if (event) setShellConfiguration(extractShellConfiguration(event));
+		};
+		const onHistory = (event) => {
+			if (event?.type === "external" && typeof event.path === "string") {
+				const to = getRouteTo(event.path);
+				if (to !== router.state.location.pathname) router.navigate({ to });
+			}
+		};
+		runtime.on("configuration", onConfiguration);
+		runtime.on("history", onHistory);
+		return () => {
+			runtime.off("configuration", onConfiguration);
+			runtime.off("history", onHistory);
+		};
+	}, [router, runtime]);
+	return shellConfiguration;
+}
+
+//#endregion
+//#region source/web/react/extension/experience-shell-app.tsx
+/** The fallback UI shown while waiting for the Experience Cloud shell to become ready. */
+function ShellFallback() {
+	return /* @__PURE__ */ jsx(CenteredProgress, { "aria-label": "Loading experience cloud runtime" });
+}
+/**
+* Renders the Experience Cloud shell flow, waiting for the shell's runtime configuration.
+* @param props - The props needed to initialize the extension app.
+*/
+function ExperienceShellExtensionApp(props) {
+	const { initialConfigurationPromise, runtime } = props;
+	return /* @__PURE__ */ jsx(Provider, {
+		colorScheme: void 0,
+		children: /* @__PURE__ */ jsx(Suspense, {
+			fallback: /* @__PURE__ */ jsx(ShellFallback, {}),
+			children: /* @__PURE__ */ jsx(ShellExtensionContent, {
+				initialConfigurationPromise,
+				runtime
+			})
+		})
+	});
+}
+/**
+* Renders IMS-gated route content once the shell/runtime configuration is known.
+* @param props - The props needed to initialize the extension app.
+*/
+function ShellExtensionContent(props) {
+	const { initialConfigurationPromise, runtime } = props;
+	const shellConfiguration = useShellConfiguration(runtime, use(initialConfigurationPromise));
+	const spectrumRouter = useSpectrumRouter();
+	return /* @__PURE__ */ jsx(Provider, {
+		colorScheme: useExtensionColorScheme(shellConfiguration),
+		router: spectrumRouter,
+		children: /* @__PURE__ */ jsx(ExtensionErrorBoundary, { children: /* @__PURE__ */ jsx(ImsContextProvider, {
+			credentials: resolveShellImsCredentials(shellConfiguration),
+			children: /* @__PURE__ */ jsx(Outlet, {})
+		}) })
+	});
+}
+
+//#endregion
+//#region source/web/react/extension/standalone-app.tsx
+/** Renders the raw HTML page running standalone, with no host frame at all. Nothing to wait on. */
+function StandaloneExtensionApp() {
+	const spectrumRouter = useSpectrumRouter();
+	useEffect(() => {
+		syncRootColorScheme(void 0);
+	}, []);
+	return /* @__PURE__ */ jsx(Provider, {
+		colorScheme: void 0,
+		router: spectrumRouter,
+		children: /* @__PURE__ */ jsx(ExtensionErrorBoundary, { children: /* @__PURE__ */ jsx(ImsContextProvider, {
+			credentials: null,
+			children: /* @__PURE__ */ jsx(Outlet, {})
+		}) })
+	});
+}
+
+//#endregion
+//#region source/web/react/extension/entrypoint.tsx
+/**
+* The Entrypoint component is the main entry point for an extension app.
+* It picks between the Commerce Admin, Experience Cloud shell, and standalone flows.
+*
+* @param props - The props needed to initialize the extension app.
+*/
+function Entrypoint(props) {
+	const { extensionId, initialConfigurationPromise, runtime } = props;
+	if (isUiFrame() || isControlFrame()) return /* @__PURE__ */ jsx(CommerceExtensionApp, { extensionId });
+	if (isEmbeddedInHost() && initialConfigurationPromise !== null) return /* @__PURE__ */ jsx(ExperienceShellExtensionApp, {
+		initialConfigurationPromise,
+		runtime
+	});
+	return /* @__PURE__ */ jsx(StandaloneExtensionApp, {});
+}
+
+//#endregion
+//#region source/web/react/extension/create-app.tsx
+/**
+* Mounts a Commerce Admin UI iframe app and handles Experience Cloud Shell, UIX
+* registration, shared-context attachment, routing, and Spectrum setup.
+*
+* The app is wrapped in React's `<StrictMode>`, so in development builds (e.g. when
+* served via `aio app dev` or `aio app run`) components render twice and effects run
+* an extra setup + cleanup cycle on mount. Production builds are unaffected.
+*
+* @param options - App bootstrap options.
+*
+* @example
+* ```tsx
+* import { createExtensionApp } from "@adobe/aio-commerce-lib-admin-ui/web";
+* import { MainPage } from "./pages/main-page.jsx";
+*
+* createExtensionApp({
+*   metadata: { extensionId: "my-extension-id" },
+*   menu: <MainPage />,
+* });
+* ```
+*/
+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 = createRoot(rootElement);
+	const render = (runtime, initialConfigurationPromise) => {
+		const router = createExtensionRouter(/* @__PURE__ */ jsx(Entrypoint, {
+			extensionId: metadata.extensionId,
+			initialConfigurationPromise,
+			runtime
+		}), menu === void 0 ? routes : [{
+			element: menu,
+			path: "/"
+		}, ...routes]);
+		root.render(/* @__PURE__ */ jsx(StrictMode, { children: /* @__PURE__ */ jsx(RouterProvider, { router }) }));
+	};
+	try {
+		loadExperienceCloudRuntime();
+		init(() => {
+			const runtime = Runtime();
+			const { promise, resolve } = Promise.withResolvers();
+			page.title = document.title;
+			runtime.on("ready", (configuration) => {
+				resolve(configuration ?? runtime.lastConfigurationPayload);
+				page.done().catch(() => {
+					console.warn("Failed to mark page as done in Experience Cloud Shell.");
+				});
+			});
+			render(runtime, promise);
+		});
+	} catch {
+		render(createMockRuntime(), null);
+	}
+}
+
+//#endregion
+export { createExtensionApp, useCommerce, useHostConnection, useIms, useMassActionContext, useOrderViewButtonContext, useSharedContext };