feat(ui): add composed profile shell, providers infra and stub router

packages/ui/src/composed/APIKeysSection.tsx

@@ -0,0 +1,15 @@
+'use client';
+
+import { Suspense, type ComponentType, type ReactNode } from 'react';
+
+import { CardStateProvider } from '../elements/contexts';
+
+export function APIKeysSection({ page: Page }: { page: ComponentType }): ReactNode {
+  return (
+    <CardStateProvider>
+      <Suspense fallback={null}>
+        <Page />
+      </Suspense>
+    </CardStateProvider>
+  );
+}

packages/ui/src/composed/BillingSection.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import { Suspense, type ComponentType, type ReactNode } from 'react';
+
+import { RouteContext } from '../router/RouteContext';
+import { useBillingRouter } from './useBillingRouter';
+
+type BillingSectionProps = {
+  billing: ComponentType;
+  plans: ComponentType;
+  statement: ComponentType;
+  paymentAttempt: ComponentType;
+};
+
+export function BillingSection({
+  billing: Billing,
+  plans: Plans,
+  statement: Statement,
+  paymentAttempt: PaymentAttempt,
+}: BillingSectionProps): ReactNode {
+  const { router, route } = useBillingRouter();
+
+  let content: ReactNode;
+  switch (route.page) {
+    case 'plans':
+      content = <Plans />;
+      break;
+    case 'statement':
+      content = <Statement />;
+      break;
+    case 'payment-attempt':
+      content = <PaymentAttempt />;
+      break;
+    default:
+      content = <Billing />;
+  }
+
+  return (
+    <RouteContext.Provider value={router}>
+      <Suspense fallback={null}>{content}</Suspense>
+    </RouteContext.Provider>
+  );
+}

packages/ui/src/composed/PageContext.tsx

@@ -0,0 +1,5 @@
+import { createContext } from 'react';
+
+type PageId = 'account' | 'security' | 'general';
+
+export const PageContext = createContext<PageId | null>(null);

packages/ui/src/composed/ProfileProviderShell.tsx

@@ -0,0 +1,190 @@
+'use client';
+
+// Composed UserProfile / OrganizationProfile mount outside the clerk-js portal
+// tree, so this shell rebuilds the providers normally split between
+// `LazyProviders` and `LazyComponentRenderer` / `LazyModalRenderer` in
+// `packages/ui/src/lazyModules/providers.tsx`. `ClerkContextProvider` is
+// intentionally omitted — the consumer's `<ClerkProvider>` supplies `clerk` via
+// `useClerk()`. The emotion cache is keyed per clerk instance in
+// `styleCacheStore` so sibling composed roots don't duplicate style insertions.
+
+import { ClerkRuntimeError } from '@clerk/shared/error';
+import { logger } from '@clerk/shared/logger';
+import type { ModuleManager } from '@clerk/shared/moduleManager';
+import type { EnvironmentResource, LoadedClerk } from '@clerk/shared/types';
+// eslint-disable-next-line no-restricted-imports
+import { CacheProvider } from '@emotion/react';
+import type { PropsWithChildren, ReactNode } from 'react';
+import { useMemo } from 'react';
+
+import { AppearanceProvider } from '@/ui/customizables/AppearanceContext';
+import { FlowMetadataProvider } from '@/ui/elements/contexts';
+import type { Appearance, Elements } from '@/ui/internal/appearance';
+import { getStyleCacheEntry, setStyleCache } from '@/ui/internal/styleCacheStore';
+import { RouteContext } from '@/ui/router/RouteContext';
+import { InternalThemeProvider } from '@/ui/styledSystem';
+import { createEmotionCache } from '@/ui/styledSystem/createEmotionCache';
+import { extractCssLayerNameFromAppearance } from '@/ui/utils/extractCssLayerNameFromAppearance';
+
+import { EnvironmentProvider } from '../contexts/EnvironmentContext';
+import { ModuleManagerProvider } from '../contexts/ModuleManagerContext';
+import { OptionsProvider } from '../contexts/OptionsContext';
+import { AppearanceOverrides } from '../elements/AppearanceOverrides';
+import { createComposedRouter } from './stubRouter';
+
+// Used when `clerk.__internal_moduleManager` is `undefined`. In a correctly wired app clerk-js
+// exposes its ModuleManager through that getter, so reaching this means the loaded clerk-js is too
+// old to expose it (an older clerk-js also predates composed profiles entirely). Fail loudly on the
+// first dynamic import (Web3, billing, password strength) instead of silently resolving `undefined`
+// and surfacing later as an opaque access on the missing module.
+export const fallbackModuleManager: ModuleManager = {
+  import: () =>
+    Promise.reject(
+      new ClerkRuntimeError(
+        'Composed profile components could not resolve a Clerk module manager: this Clerk instance does not expose one. This usually means the loaded @clerk/clerk-js is too old to support composed profiles.',
+        { code: 'composed_module_manager_unavailable' },
+      ),
+    ),
+};
+
+type ClerkWithInternalEnvironment = {
+  __internal_environment?: EnvironmentResource | null;
+};
+
+/**
+ * Resolves the clerk-js runtime state (environment + module manager) that the
+ * composed profile shell needs. Composed UI is bundled into the consumer app but
+ * clerk-js is hotloaded separately, so an app can bundle composed components that
+ * are newer than the loaded clerk-js. `moduleManager` falls back to a loud stub;
+ * `environment` can only be absent, so once clerk has finished loading a missing
+ * runtime is a real version mismatch and gets a one-time warning instead of a
+ * silent blank render.
+ */
+export function resolveComposedClerkRuntime(
+  clerk: LoadedClerk,
+  clerkLoaded: boolean,
+): { environment: EnvironmentResource | null | undefined; moduleManager: ModuleManager } {
+  // SAFETY: __internal_environment is a real clerk-js getter absent from the shared LoadedClerk type; narrowing (not `any`) keeps it typed.
+  const environment = (clerk as LoadedClerk & ClerkWithInternalEnvironment).__internal_environment;
+  const moduleManager = clerk.__internal_moduleManager ?? fallbackModuleManager;
+
+  if (clerkLoaded && (!environment || clerk.__internal_moduleManager === undefined)) {
+    logger.warnOnce(
+      'Clerk: Composed profile components could not read the runtime state (environment/module manager) from the loaded @clerk/clerk-js, so nothing will render. This usually means the loaded clerk-js is older than the composed components bundled in your app. Upgrade @clerk/clerk-js (or your framework SDK) to a version that supports composed profiles.',
+    );
+  }
+
+  return { environment, moduleManager };
+}
+
+type ClerkWithNonceOption = { __internal_getOption(key: string): string | undefined };
+
+function readNonceOption(clerk: LoadedClerk): string | undefined {
+  // SAFETY: nonce is a runtime clerk-js option whose key is absent from the typed ClerkOptions; narrowing (not `any`) keeps the return typed. Called as a method to preserve `this`.
+  return (clerk as unknown as ClerkWithNonceOption).__internal_getOption('nonce');
+}
+
+const composedOverrides: Elements = {
+  profilePageContent: { padding: 0 },
+};
+
+type ProfileProviderShellProps = PropsWithChildren<{
+  clerk: LoadedClerk;
+  environment: EnvironmentResource;
+  moduleManager: ModuleManager;
+  appearanceKey: 'userProfile' | 'organizationProfile';
+  flow: 'userProfile' | 'organizationProfile';
+  globalAppearance: Appearance | undefined;
+  appearance?: Appearance;
+}>;
+
+type SharedStyleCacheProviderProps = PropsWithChildren<{
+  clerk: LoadedClerk;
+  nonce?: string;
+  cssLayerName?: string;
+}>;
+
+// One emotion cache per clerk instance, so sibling composed roots share inserts.
+// Reuse the stored cache only when it was built from the same nonce/cssLayerName;
+// a change to either rebuilds it (mirroring the AIO StyleCacheProvider) instead of
+// pinning whatever the first-mounted sibling saw.
+function SharedStyleCacheProvider({ clerk, nonce, cssLayerName, children }: SharedStyleCacheProviderProps): ReactNode {
+  const cache = useMemo(() => {
+    const existing = getStyleCacheEntry(clerk);
+    if (existing && existing.nonce === nonce && existing.cssLayerName === cssLayerName) {
+      return existing.cache;
+    }
+    const next = createEmotionCache({ nonce, cssLayerName });
+    setStyleCache(clerk, { cache: next, nonce, cssLayerName });
+    return next;
+  }, [clerk, nonce, cssLayerName]);
+
+  return <CacheProvider value={cache}>{children}</CacheProvider>;
+}
+
+export function ProfileProviderShell({
+  children,
+  clerk,
+  environment,
+  moduleManager,
+  appearanceKey,
+  flow,
+  globalAppearance,
+  appearance,
+}: ProfileProviderShellProps): ReactNode {
+  // currentPath is left empty: composed has no Clerk-internal navigation. Each
+  // section owns its own CardStateProvider, so errors clear on section unmount
+  // (single-section mounting). Side-by-side sections keep independent error
+  // state — a consumer URL change wouldn't be a meaningful signal to clear
+  // either, so observing it would only cause spurious clears.
+  const router = useMemo(() => createComposedRouter(clerk.navigate), [clerk]);
+  // Match the portal path's appearance normalization so a cssLayerName nested inside
+  // appearance.theme gets hoisted to top-level for @layer wrapping.
+  const normalizedGlobalAppearance = useMemo(
+    () => extractCssLayerNameFromAppearance(globalAppearance),
+    [globalAppearance],
+  );
+  const options = useMemo(
+    () => ({
+      localization: clerk.__internal_getOption('localization'),
+      supportEmail: clerk.__internal_getOption('supportEmail'),
+    }),
+    [clerk],
+  );
+
+  return (
+    <SharedStyleCacheProvider
+      clerk={clerk}
+      nonce={readNonceOption(clerk)}
+      cssLayerName={normalizedGlobalAppearance?.cssLayerName}
+    >
+      {/* parsed appearance for cl-* styled components */}
+      <AppearanceProvider
+        appearanceKey={appearanceKey}
+        globalAppearance={normalizedGlobalAppearance}
+        appearance={appearance}
+      >
+        {/* flow= for Flow.Root/Part data-clerk-* selectors */}
+        <FlowMetadataProvider flow={flow}>
+          {/* Emotion ThemeProvider over parsed theme */}
+          <InternalThemeProvider>
+            {/* dynamic-import bridge (Web3) */}
+            <ModuleManagerProvider moduleManager={moduleManager}>
+              {/* threads localization + supportEmail from the consumer's <ClerkProvider> */}
+              <OptionsProvider value={options}>
+                {/* read by useEnvironment() across MFA/account sections */}
+                <EnvironmentProvider value={environment}>
+                  {/* router stub: navigate→clerk.navigate, matches/refresh no-op */}
+                  <RouteContext.Provider value={router}>
+                    {/* zero out profilePageContent padding when embedded */}
+                    <AppearanceOverrides elements={composedOverrides}>{children}</AppearanceOverrides>
+                  </RouteContext.Provider>
+                </EnvironmentProvider>
+              </OptionsProvider>
+            </ModuleManagerProvider>
+          </InternalThemeProvider>
+        </FlowMetadataProvider>
+      </AppearanceProvider>
+    </SharedStyleCacheProvider>
+  );
+}

packages/ui/src/composed/__tests__/stub-limitations.test.ts

@@ -0,0 +1,131 @@
+import { renderHook, act } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createComposedRouter, stubRouter } from '../stubRouter';
+import { useBillingRouter } from '../useBillingRouter';
+
+describe('createComposedRouter', () => {
+  it('navigate delegates to clerkNavigate for same-origin paths', async () => {
+    const clerkNavigate = vi.fn().mockResolvedValue(undefined);
+    const router = createComposedRouter(clerkNavigate);
+
+    await router.navigate('/dashboard');
+
+    expect(clerkNavigate).toHaveBeenCalledWith('/dashboard');
+  });
+
+  it('navigate delegates to clerkNavigate for relative paths', async () => {
+    const clerkNavigate = vi.fn().mockResolvedValue(undefined);
+    const router = createComposedRouter(clerkNavigate);
+
+    await router.navigate('../');
+
+    expect(clerkNavigate).toHaveBeenCalledWith('../');
+  });
+
+  it('navigate delegates to clerkNavigate for external URLs', async () => {
+    const clerkNavigate = vi.fn().mockResolvedValue(undefined);
+    const router = createComposedRouter(clerkNavigate);
+
+    await router.navigate('https://external.example.com/callback');
+
+    expect(clerkNavigate).toHaveBeenCalledWith('https://external.example.com/callback');
+  });
+
+  it('baseNavigate delegates to clerkNavigate with URL href', async () => {
+    const clerkNavigate = vi.fn().mockResolvedValue(undefined);
+    const router = createComposedRouter(clerkNavigate);
+
+    await router.baseNavigate(new URL('https://example.com/path'));
+
+    expect(clerkNavigate).toHaveBeenCalledWith('https://example.com/path');
+  });
+
+  it('resolve produces URLs relative to current location', () => {
+    const router = createComposedRouter(vi.fn());
+
+    const resolved = router.resolve('/some-path');
+    expect(resolved.pathname).toBe('/some-path');
+  });
+});
+
+describe('createComposedRouter — AIO-only APIs throw in dev', () => {
+  it('matches() throws', () => {
+    const router = createComposedRouter(vi.fn());
+    expect(() => router.matches('/foo')).toThrow(/not supported inside composed sections/);
+  });
+
+  it('refresh() throws', () => {
+    const router = createComposedRouter(vi.fn());
+    expect(() => router.refresh()).toThrow(/not supported inside composed sections/);
+  });
+
+  it('getMatchData() throws', () => {
+    const router = createComposedRouter(vi.fn());
+    expect(() => router.getMatchData('/foo')).toThrow(/not supported inside composed sections/);
+  });
+});
+
+describe('stubRouter fallback', () => {
+  it('is created with window.location.assign as navigator', () => {
+    // stubRouter is a pre-built instance that delegates to window.location.assign.
+    // We can't spy on window.location.assign in jsdom, but we verify it's a valid router.
+    expect(stubRouter.navigate).toBeDefined();
+    expect(stubRouter.baseNavigate).toBeDefined();
+  });
+});
+
+describe('useBillingRouter — in-memory by design', () => {
+  // Composed billing routing is purely React state — the consumer owns the
+  // page URL. Trade-off: back/forward, refresh, and deep-links do not preserve
+  // sub-route or tab state. These tests pin that decision.
+
+  let originalHash: string;
+
+  afterEach(() => {
+    window.location.hash = originalHash ?? '';
+  });
+
+  it('navigate() does not touch window.location.hash', async () => {
+    originalHash = window.location.hash;
+    const { result } = renderHook(() => useBillingRouter());
+
+    await act(async () => {
+      await result.current.router.navigate('plans');
+    });
+
+    expect(window.location.hash).toBe(originalHash);
+    expect(result.current.route.page).toBe('plans');
+  });
+
+  it('navigate() does not push a history entry', async () => {
+    const before = window.history.length;
+    const { result } = renderHook(() => useBillingRouter());
+
+    await act(async () => {
+      await result.current.router.navigate('statement/abc');
+    });
+
+    expect(window.history.length).toBe(before);
+  });
+});
+
+describe('createComposedRouter — SSR safety', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('resolve() does not throw when window is undefined', () => {
+    vi.stubGlobal('window', undefined);
+
+    const router = createComposedRouter(vi.fn());
+    expect(() => router.resolve('/some-path')).not.toThrow();
+    expect(router.resolve('/some-path').pathname).toBe('/some-path');
+  });
+
+  it('stubRouter.navigate is a no-op (does not throw) when window is undefined', async () => {
+    vi.stubGlobal('window', undefined);
+
+    await expect(stubRouter.navigate('/foo')).resolves.toBeUndefined();
+  });
+});