@vertesia/ui 1.5.0 → 1.6.0-dev.20260918.061604Z

package/src/session/auth/firebase.ts

@@ -37,11 +37,21 @@ export function getFirebaseAnalytics(): Analytics {
 export function getFirebaseAuth(): Auth {
     if (!_firebaseAuth) {
         _firebaseAuth = getAuth(getFirebaseApp());
+        _firebaseAuth.tenantId = Env.firebase?.tenantId ?? null;
     }
     return _firebaseAuth;
 }
 
 export async function setFirebaseTenant(tenantEmail?: string) {
+    if (Env.firebase?.tenantId) {
+        getFirebaseAuth().tenantId = Env.firebase.tenantId;
+        return {
+            firebaseTenantId: Env.firebase.tenantId,
+            provider: Env.firebase.providerType ?? 'oidc',
+            name: '',
+            label: '',
+        };
+    }
     if (!tenantEmail) {
         console.log('No tenant name or email specified, skipping tenant setup');
         return;

package/src/session/auth/useAuthState.ts

@@ -1,10 +1,17 @@
-/** React wrappers for the state record shared with boot-time Central Auth redirects. */
+/**
+ * This hook is used to generate and verify state for OAuth2 authorization requests.
+ *
+ * The implementation lives in ./authState so the token layer can start the same round-trip when it
+ * renews an expired Central Auth session, where no component is available to call a hook.
+ */
+
 import { useCallback } from 'react';
 import { clearAuthState, generateAuthState, verifyAuthState } from './authState';
 
 export function useAuthState() {
-    const generateState = useCallback(generateAuthState, []);
-    const verifyState = useCallback(verifyAuthState, []);
-    const clearState = useCallback(clearAuthState, []);
+    const generateState = useCallback(() => generateAuthState(), []);
+    const verifyState = useCallback((returnedState: string | null) => verifyAuthState(returnedState), []);
+    const clearState = useCallback(() => clearAuthState(), []);
+
     return { generateState, verifyState, clearState };
 }

package/src/session/index.ts

@@ -1,5 +1,7 @@
 export * from './auth/composable';
-// Publish the boot-time auth entry points.
+// Explicit, not `export *`: domainRouting also holds buildCentralAuthRedirectUrl, which
+// UserSessionProvider already re-exports below, and two star exports of one name resolve to
+// nothing. Only the boot-time entry points an app needs are published here.
 export {
     clearCentralAuthRoundTripMarker,
     isCentralAuthRedirectPending,

package/src/shell/AuthScreenPreview.test.tsx

@@ -0,0 +1,44 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import * as session from '@vertesia/ui/session';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { AUTH_PREVIEW_SCREENS, AuthScreenPreview, mountAuthScreenPreview } from './AuthScreenPreview';
+import * as signin from './login/signInUtils';
+
+afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+});
+
+describe('shared auth visual previews', () => {
+    it.each(AUTH_PREVIEW_SCREENS.filter((name) => name !== 'boot'))(
+        'renders %s without initializing or changing authentication',
+        (name) => {
+            const firebase = vi.spyOn(session, 'getFirebaseAuth');
+            const reset = vi.spyOn(signin, 'resetSignInState');
+            const { container } = render(<AuthScreenPreview screen={name} branding={{ name: 'Example' }} />);
+            expect(container.querySelector('[inert]')?.textContent?.trim()).not.toBe('');
+            expect(screen.getByText(`Auth preview: ${name}`)).toBeTruthy();
+            expect(firebase).not.toHaveBeenCalled();
+            expect(reset).not.toHaveBeenCalled();
+        },
+    );
+
+    it('retains branding and full screen overrides, with links to the shared boot URL', () => {
+        render(
+            <AuthScreenPreview
+                screen="loading"
+                branding={{ name: 'Example' }}
+                screens={{ Loading: () => <p>Custom loader fixture</p> }}
+            />,
+        );
+        expect(screen.getByText('Custom loader fixture')).toBeTruthy();
+        expect(screen.getByText('boot').getAttribute('href')).toContain('__vertesia_boot=slow');
+        expect(screen.getByText('pending').getAttribute('href')).toContain('__vertesia_auth=pending');
+    });
+
+    it('keeps the React root empty for boot previews', async () => {
+        const container = document.createElement('div');
+        await mountAuthScreenPreview(container, 'boot');
+        expect(container.childNodes).toHaveLength(0);
+    });
+});

package/src/shell/AuthScreenPreview.tsx

@@ -0,0 +1,228 @@
+/** Developer-only visual fixtures. Mount outside the authenticated application tree. */
+import { I18nProvider, useUITranslation } from '@vertesia/ui/i18n';
+import type { ReactNode } from 'react';
+import type { AppBranding } from '../boot/branding.js';
+import {
+    AppBrandingProvider,
+    BrandedAuthLoadingScreen,
+    BrandedPermissionLoadingScreen,
+    BrandedSignInScreen,
+} from './BrandedAuthScreens';
+import { type SignInFlowController, SignInFlowSteps } from './login/SignInFlow';
+import SignInRecoveryStep, { type SignInRecoveryKind } from './login/SignInRecoveryStep';
+import { SignInRestrictedEnvView } from './login/SignInRestrictedEnvStep';
+import SignInTenantBlockedStep from './login/SignInTenantBlockedStep';
+import { SignInErrorNotice, type SignInRecoveryMode } from './login/SigninScreen';
+import SignupForm from './login/SignupForm';
+import type { AuthScreens } from './VertesiaShell';
+
+export const AUTH_PREVIEW_SCREENS = [
+    'email',
+    'providers',
+    'tenant',
+    'returning',
+    'pending',
+    'blocked',
+    'signup',
+    'restricted',
+    'scope-project',
+    'scope-account',
+    'no-account',
+    'credentials',
+    'service',
+    'auth-error',
+    'loading',
+    'permissions',
+    'permission-retry',
+    'permission-error',
+    'permission-denied',
+    'permission-session-expired',
+    'boot',
+] as const;
+export type AuthPreviewScreen = (typeof AUTH_PREVIEW_SCREENS)[number];
+
+const noop = () => {};
+const identity = { email: 'alex@example.com', name: 'Alex Example' };
+const signupIdentity = { email: identity.email, displayName: identity.name };
+const recoveryKinds: Partial<Record<AuthPreviewScreen, SignInRecoveryKind>> = {
+    'scope-project': 'scopeProject',
+    'scope-account': 'scopeAccount',
+    'no-account': 'noAccessibleAccount',
+    credentials: 'credential',
+    service: 'service',
+};
+
+export function AuthScreenPreview({
+    screen,
+    branding,
+    screens = {},
+}: {
+    screen: string;
+    branding: AppBranding;
+    screens?: AuthScreens;
+}) {
+    const { t } = useUITranslation();
+    const selected = AUTH_PREVIEW_SCREENS.find((value) => value === screen) ?? 'email';
+    const SignIn = screens.SignIn ?? BrandedSignInScreen;
+    const Loading = screens.Loading ?? BrandedAuthLoadingScreen;
+    const Permissions = screens.Permissions ?? BrandedPermissionLoadingScreen;
+    const recovery = recoveryKinds[selected];
+    const flow: SignInFlowController<SignInRecoveryMode> = {
+        mode:
+            selected === 'providers' ||
+            selected === 'tenant' ||
+            selected === 'returning' ||
+            selected === 'pending' ||
+            selected === 'blocked' ||
+            selected === 'signup' ||
+            selected === 'restricted'
+                ? selected
+                : selected === 'scope-project' || selected === 'scope-account'
+                  ? 'scopeUnavailable'
+                  : selected === 'no-account'
+                    ? 'noAccessibleAccount'
+                    : selected === 'credentials'
+                      ? 'credentialFailure'
+                      : selected === 'service'
+                        ? 'serviceFailure'
+                        : 'email',
+        email: identity.email,
+        tenant: { firebaseTenantId: 'preview', name: branding.name, provider: 'oidc' },
+        storedSession: { ...identity, lastProvider: 'oidc', tenantName: branding.name },
+        pendingProvider: 'oidc',
+        setMode: noop,
+        setEmail: noop,
+        setTenant: noop,
+        setStoredSession: noop,
+        onProceedFromEmail: noop,
+        onBack: noop,
+        onNotYou: noop,
+        onProviderClicked: noop,
+        startOver: noop,
+    };
+    let content: ReactNode = <SignInFlowSteps flow={flow} />;
+    if (selected === 'blocked')
+        content = <SignInTenantBlockedStep email={identity.email} tenantName={branding.name} onBack={noop} />;
+    if (selected === 'restricted') content = <SignInRestrictedEnvView onUseDifferentEmail={noop} onRedirect={noop} />;
+    if (selected === 'signup') content = <SignupForm identity={signupIdentity} onSignup={noop} goBack={noop} />;
+    if (recovery)
+        content = (
+            <SignInRecoveryStep
+                kind={recovery}
+                identity={identity}
+                details={{ message: 'Preview error details', status: 403 }}
+                onContinue={
+                    recovery === 'scopeProject' || recovery === 'scopeAccount' || recovery === 'service'
+                        ? noop
+                        : undefined
+                }
+                onUseDifferentAccount={noop}
+            />
+        );
+    let page: ReactNode = (
+        <SignIn
+            flow={flow}
+            isNested={false}
+            notice={selected === 'auth-error' ? <SignInErrorNotice /> : null}
+            onUseDifferentAccount={noop}
+            onContinueWithSanitizedScope={noop}
+            onRetry={noop}
+            onSignup={noop}
+        >
+            {content}
+        </SignIn>
+    );
+    if (selected === 'loading') page = <Loading />;
+    if (
+        selected === 'permissions' ||
+        selected === 'permission-retry' ||
+        selected === 'permission-error' ||
+        selected === 'permission-denied' ||
+        selected === 'permission-session-expired'
+    ) {
+        const denied = selected === 'permission-denied';
+        const expired = selected === 'permission-session-expired';
+        const failed = selected === 'permission-error' || denied || expired;
+        page = (
+            <Permissions
+                status={failed ? 'error' : selected === 'permission-retry' ? 'retrying' : 'loading'}
+                title={
+                    expired
+                        ? t('auth.recovery.credential.title')
+                        : denied
+                          ? t('shell.accessDenied')
+                          : failed
+                            ? t('permissions.connectionFailed')
+                            : t('permissions.connecting')
+                }
+                description={
+                    expired
+                        ? t('auth.recovery.credential.body')
+                        : denied
+                          ? t('permissions.accessDenied')
+                          : failed
+                            ? t('permissions.tryAgainLater')
+                            : selected === 'permission-retry'
+                              ? t('permissions.retrying')
+                              : t('permissions.loadingPermissions')
+                }
+                error={failed ? new Error('Preview permission error') : undefined}
+                actionLabel={t(denied || expired ? 'auth.recovery.useDifferentAccount' : 'auth.recovery.tryAgain')}
+                onAction={noop}
+            />
+        );
+    }
+    return (
+        <I18nProvider>
+            <AppBrandingProvider branding={branding}>
+                {/* Inert fixtures cannot submit forms, redirect, or change the real session. */}
+                <div inert style={{ display: 'contents' }}>
+                    {page}
+                </div>
+                <details
+                    className="fixed top-2 start-2 max-h-80 overflow-auto rounded border bg-background text-foreground p-3 text-sm"
+                    style={{ zIndex: 2147483647 }}
+                >
+                    <summary>Auth preview: {selected}</summary>
+                    <nav aria-label="Auth preview screens" className="flex flex-col gap-1 mt-2">
+                        {AUTH_PREVIEW_SCREENS.map((value) => {
+                            const params = new URLSearchParams(window.location.search);
+                            params.delete('__vertesia_boot');
+                            params.delete('__vertesia_auth');
+                            params.set(
+                                value === 'boot' ? '__vertesia_boot' : '__vertesia_auth',
+                                value === 'boot' ? 'slow' : value,
+                            );
+                            return (
+                                <a
+                                    key={value}
+                                    href={`?${params}`}
+                                    aria-current={value === selected ? 'page' : undefined}
+                                >
+                                    {value}
+                                </a>
+                            );
+                        })}
+                        <a href={window.location.pathname}>Exit preview</a>
+                    </nav>
+                </details>
+            </AppBrandingProvider>
+        </I18nProvider>
+    );
+}
+
+/** Hosts call this only from their import.meta.env.DEV branch, before mounting auth/session providers. */
+export async function mountAuthScreenPreview(
+    container: HTMLElement,
+    screen: string,
+    branding: AppBranding = {
+        name: 'Vertesia',
+        logo: { light: '/logo-light.png', dark: '/logo-dark.png' },
+        loadingIcon: { light: '/icon.svg' },
+    },
+    screens: AuthScreens = {},
+): Promise<void> {
+    if (screen === 'boot') return;
+    const { createRoot } = await import('react-dom/client');
+    createRoot(container).render(<AuthScreenPreview screen={screen} branding={branding} screens={screens} />);
+}

package/src/shell/BrandedAuthScreens.test.tsx

@@ -0,0 +1,181 @@
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { DefaultPermissionLoadingScreen } from '@vertesia/ui/features';
+import { i18nInstance, NAMESPACE, useUITranslation } from '@vertesia/ui/i18n';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+    AppBrandingProvider,
+    BrandedAuthLoadingScreen,
+    BrandedLoadingIndicator,
+    BrandedPermissionLoadingScreen,
+    BrandedSignInScreen,
+} from './BrandedAuthScreens';
+import { SignInFlowSteps, useSignInFlow } from './login/SignInFlow';
+import { DefaultSignInScreen, type SignInRecoveryMode } from './login/SigninScreen';
+import { DefaultAuthLoadingScreen } from './SplashScreen';
+
+afterEach(() => {
+    cleanup();
+    localStorage.clear();
+});
+
+function CopyProbe() {
+    const { t } = useUITranslation();
+    return <span>{t('auth.email.title')}</span>;
+}
+
+function SignInPreview() {
+    const flow = useSignInFlow<SignInRecoveryMode>();
+    return (
+        <BrandedSignInScreen
+            flow={flow}
+            notice={null}
+            isNested={false}
+            onRetry={vi.fn()}
+            onUseDifferentAccount={vi.fn()}
+            onContinueWithSanitizedScope={vi.fn()}
+            onSignup={vi.fn()}
+        >
+            <SignInFlowSteps flow={flow} />
+        </BrandedSignInScreen>
+    );
+}
+
+describe('configuration-driven auth screens', () => {
+    it('keeps brand copy local to each shell and preserves the shared translations', () => {
+        const original = i18nInstance.t('auth.email.title', { ns: NAMESPACE });
+        render(
+            <>
+                <AppBrandingProvider branding={{ name: 'One', copy: { welcome: 'Welcome to One' } }}>
+                    <CopyProbe />
+                </AppBrandingProvider>
+                <AppBrandingProvider branding={{ name: 'Two', copy: { welcome: 'Welcome to Two' } }}>
+                    <CopyProbe />
+                </AppBrandingProvider>
+                <CopyProbe />
+            </>,
+        );
+        expect(screen.getByText('Welcome to One')).toBeTruthy();
+        expect(screen.getByText('Welcome to Two')).toBeTruthy();
+        expect(screen.getByText(original)).toBeTruthy();
+        expect(i18nInstance.t('auth.email.title', { ns: NAMESPACE })).toBe(original);
+    });
+
+    it('brands the existing email form without replacing its validation', () => {
+        render(
+            <AppBrandingProvider
+                branding={{
+                    name: 'Workspace',
+                    copy: { welcome: 'Welcome here', emailPlaceholder: 'you@example.test' },
+                }}
+            >
+                <SignInPreview />
+            </AppBrandingProvider>,
+        );
+        expect(screen.getByRole('heading', { name: 'Welcome here' })).toBeTruthy();
+        expect(screen.getByPlaceholderText('you@example.test')).toBeTruthy();
+        fireEvent.click(screen.getByRole('button', { name: 'Continue' }));
+        expect(screen.getByRole('textbox').getAttribute('aria-invalid')).toBe('true');
+    });
+
+    it('uses shared branding for loading and preserves permission recovery actions', () => {
+        const retry = vi.fn();
+        const brand = { name: 'Workspace', copy: { loading: 'Preparing Workspace' } };
+        const view = render(
+            <AppBrandingProvider branding={brand}>
+                <BrandedAuthLoadingScreen />
+            </AppBrandingProvider>,
+        );
+        expect(screen.getByRole('status').getAttribute('aria-label')).toBe('Preparing Workspace');
+        view.rerender(
+            <AppBrandingProvider branding={brand}>
+                <BrandedPermissionLoadingScreen
+                    status="error"
+                    title="Access failed"
+                    description="Try again"
+                    actionLabel="Retry"
+                    onAction={retry}
+                />
+            </AppBrandingProvider>,
+        );
+        expect(screen.getByRole('alert').textContent).toContain('Access failed');
+        fireEvent.click(screen.getByRole('button', { name: 'Retry' }));
+        expect(retry).toHaveBeenCalledOnce();
+    });
+});
+
+describe('default layout parity', () => {
+    it('retains the default sign-in chrome and legal footer with empty branding', () => {
+        const view = render(
+            <DefaultSignInScreen>
+                <p>Form</p>
+            </DefaultSignInScreen>,
+        );
+        const expected = view.container.innerHTML;
+        view.rerender(
+            <AppBrandingProvider branding={{ name: 'Test' }}>
+                <BrandedSignInScreen
+                    {...({ isNested: false, children: <p>Form</p> } as Parameters<typeof BrandedSignInScreen>[0])}
+                />
+            </AppBrandingProvider>,
+        );
+        expect(view.container.querySelector('[data-vbrand] > div')?.outerHTML).toBe(expected);
+    });
+    it('uses the same loading markup with no branding assets or copy', () => {
+        const view = render(<DefaultAuthLoadingScreen />);
+        const expected = view.container.innerHTML;
+        view.rerender(
+            <AppBrandingProvider branding={{ name: 'Test' }}>
+                <BrandedAuthLoadingScreen />
+            </AppBrandingProvider>,
+        );
+        expect(view.container.querySelector('[role="status"]')?.outerHTML).toBe(expected);
+    });
+    it('preserves permission error details and the outline recovery button', () => {
+        const props = {
+            status: 'error' as const,
+            title: 'Failed',
+            description: 'Retry',
+            actionLabel: 'Retry',
+            onAction: vi.fn(),
+            error: new Error('Details'),
+        };
+        const view = render(<DefaultPermissionLoadingScreen {...props} />);
+        const expected = view.container.innerHTML;
+        view.rerender(
+            <AppBrandingProvider branding={{ name: 'Test' }}>
+                <BrandedPermissionLoadingScreen {...props} />
+            </AppBrandingProvider>,
+        );
+        expect(view.container.querySelector('[data-vbrand] > div')?.outerHTML).toBe(expected);
+    });
+});
+
+describe('delayed resource loading indicator', () => {
+    it('avoids flashing on fast loads and cancels its timer on handoff', () => {
+        vi.useFakeTimers();
+        try {
+            const view = render(<BrandedLoadingIndicator delayMs={200} />);
+            expect(screen.queryByRole('status')).toBeNull();
+            act(() => vi.advanceTimersByTime(100));
+            view.unmount();
+            act(() => vi.advanceTimersByTime(200));
+            expect(screen.queryByRole('status')).toBeNull();
+        } finally {
+            vi.useRealTimers();
+        }
+    });
+
+    it('shows a slow load and disappears immediately when replaced by the view', () => {
+        vi.useFakeTimers();
+        try {
+            const view = render(<BrandedLoadingIndicator delayMs={200} />);
+            act(() => vi.advanceTimersByTime(200));
+            expect(screen.getByRole('status')).toBeTruthy();
+            view.rerender(<main>Resource view</main>);
+            expect(screen.queryByRole('status')).toBeNull();
+            expect(screen.getByText('Resource view')).toBeTruthy();
+        } finally {
+            vi.useRealTimers();
+        }
+    });
+});

package/src/shell/BrandedAuthScreens.tsx

@@ -0,0 +1,117 @@
+import { DefaultPermissionLoadingScreen, type PermissionLoadingScreenProps } from '@vertesia/ui/features';
+import { UITranslationOverrides } from '@vertesia/ui/i18n';
+import { createContext, type ReactNode, useContext, useEffect, useId, useMemo, useState } from 'react';
+import { type AppBranding, renderBrandStyles } from '../boot/branding.js';
+import { DefaultSignInScreen, type SignInScreenViewProps } from './login/SigninScreen';
+import { type AuthLoadingScreenProps, DefaultAuthLoadingScreen, LoadingAnimation } from './SplashScreen';
+import type { AuthScreens } from './VertesiaShell';
+
+const BrandingContext = createContext<AppBranding>({ name: '' });
+
+export function AppBrandingProvider({ branding, children }: { branding: AppBranding; children: ReactNode }) {
+    const id = useId().replace(/[^a-zA-Z0-9_-]/g, '');
+    const overrides = useMemo(() => {
+        const result: Record<string, string> = {};
+        for (const [key, value] of Object.entries(branding.copy?.translations ?? {})) {
+            if (key.startsWith('auth.') || key.startsWith('signup.')) result[key] = value;
+        }
+        if (branding.copy?.welcome !== undefined) result['auth.email.title'] = branding.copy.welcome;
+        if (branding.copy?.emailPlaceholder !== undefined)
+            result['auth.email.placeholder'] = branding.copy.emailPlaceholder;
+        return result;
+    }, [branding]);
+    return (
+        <BrandingContext.Provider value={branding}>
+            <div data-vbrand={id} style={{ display: 'contents' }}>
+                <style>{renderBrandStyles(branding, `[data-vbrand="${id}"]`)}</style>
+                <UITranslationOverrides overrides={overrides}>{children}</UITranslationOverrides>
+            </div>
+        </BrandingContext.Provider>
+    );
+}
+
+function BrandLoadingIcon({ brand }: { brand: AppBranding }) {
+    if (!brand.loadingIcon) return null;
+    return (
+        <>
+            <img src={brand.loadingIcon.light} alt="" className="w-10 h-auto rounded-full block dark:hidden" />
+            <img
+                src={brand.loadingIcon.dark ?? brand.loadingIcon.light}
+                alt=""
+                className="w-10 h-auto rounded-full hidden dark:block"
+            />
+        </>
+    );
+}
+
+export function BrandedAuthLoadingScreen({ loadingIcon }: AuthLoadingScreenProps) {
+    const brand = useContext(BrandingContext);
+    return (
+        <DefaultAuthLoadingScreen
+            loadingIcon={loadingIcon ?? (brand.loadingIcon ? <BrandLoadingIcon brand={brand} /> : undefined)}
+            loadingLabel={brand.copy?.loading}
+        />
+    );
+}
+
+export function BrandedSignInScreen({ children, notice, isNested, lightLogo, darkLogo }: SignInScreenViewProps) {
+    const brand = useContext(BrandingContext);
+    return (
+        <DefaultSignInScreen
+            isNested={isNested}
+            lightLogo={brand.logo?.light ?? lightLogo}
+            darkLogo={brand.logo?.dark ?? brand.logo?.light ?? darkLogo}
+            logoAlt={brand.logo?.alt ?? brand.name}
+            footer={brand.copy?.footer}
+            notice={notice}
+        >
+            {children}
+        </DefaultSignInScreen>
+    );
+}
+
+export function BrandedPermissionLoadingScreen(props: PermissionLoadingScreenProps) {
+    const brand = useContext(BrandingContext);
+    return (
+        <DefaultPermissionLoadingScreen
+            {...props}
+            description={props.status === 'error' ? props.description : (brand.copy?.loading ?? props.description)}
+            loadingIcon={
+                props.status === 'error' ? (
+                    (props.loadingIcon ?? (brand.loadingIcon ? <BrandLoadingIcon brand={brand} /> : undefined))
+                ) : (
+                    <BrandedLoadingIndicator loadingIcon={props.loadingIcon} />
+                )
+            }
+        />
+    );
+}
+
+export const brandedAuthScreens: AuthScreens = {
+    SignIn: BrandedSignInScreen,
+    Loading: BrandedAuthLoadingScreen,
+    Permissions: BrandedPermissionLoadingScreen,
+};
+
+/** Brand-aware loading indicator that stays inside its container instead of covering the app shell. */
+export function BrandedLoadingIndicator({ loadingIcon, delayMs = 0 }: AuthLoadingScreenProps & { delayMs?: number }) {
+    const brand = useContext(BrandingContext);
+    const [visible, setVisible] = useState(delayMs <= 0);
+    useEffect(() => {
+        if (delayMs <= 0) {
+            setVisible(true);
+            return;
+        }
+        setVisible(false);
+        const timer = setTimeout(() => setVisible(true), delayMs);
+        return () => clearTimeout(timer);
+    }, [delayMs]);
+    if (!visible) return null;
+    return (
+        <div role="status" aria-label={brand.copy?.loading ?? 'Loading'}>
+            <LoadingAnimation
+                loadingIcon={loadingIcon ?? (brand.loadingIcon ? <BrandLoadingIcon brand={brand} /> : undefined)}
+            />
+        </div>
+    );
+}

package/src/shell/SplashScreen.test.tsx

@@ -7,6 +7,22 @@ const session = { isLoading: true, authToken: undefined as AuthTokenPayload | un
 vi.mock('@vertesia/ui/session', () => ({ useUserSession: () => session }));
 
 describe('SplashScreen handoff', () => {
+    it('never mounts a splash over an already ready sign-in view', () => {
+        session.isLoading = false;
+        session.authToken = undefined;
+        render(<SplashScreen icon={<span>Startup indicator</span>} />);
+        expect(screen.queryByText('Startup indicator')).toBeNull();
+    });
+
+    it('removes the default splash immediately when loading completes without a token', () => {
+        session.isLoading = true;
+        session.authToken = undefined;
+        const view = render(<SplashScreen icon={<span>Startup indicator</span>} />);
+        session.isLoading = false;
+        view.rerender(<SplashScreen icon={<span>Startup indicator</span>} />);
+        expect(screen.queryByText('Startup indicator')).toBeNull();
+    });
+
     it.each([true, false])('removes the splash immediately when a token arrives with isLoading=%s', (isLoading) => {
         session.isLoading = true;
         session.authToken = undefined;
@@ -19,4 +35,25 @@ describe('SplashScreen handoff', () => {
         // No fading splash remains over the permission gate's connection screen.
         expect(screen.queryByText('Startup indicator')).toBeNull();
     });
+    it('gives a custom screen the whole page without the default animation and unmounts it on completion', () => {
+        session.isLoading = true;
+        session.authToken = undefined;
+        const CustomScreen = () => <main>Branded authentication</main>;
+        const view = render(<SplashScreen Screen={CustomScreen} icon={<span>Old spinner</span>} />);
+        expect(view.container.firstElementChild?.tagName).toBe('MAIN');
+        expect(screen.queryByText('Old spinner')).toBeNull();
+        session.isLoading = false;
+        view.rerender(<SplashScreen Screen={CustomScreen} />);
+        expect(screen.queryByText('Branded authentication')).toBeNull();
+    });
+
+    it('hands a custom screen off to permissions as soon as the token arrives', () => {
+        session.isLoading = true;
+        session.authToken = undefined;
+        const CustomScreen = () => <main>Branded authentication</main>;
+        const view = render(<SplashScreen Screen={CustomScreen} />);
+        session.authToken = {} as AuthTokenPayload;
+        view.rerender(<SplashScreen Screen={CustomScreen} />);
+        expect(screen.queryByText('Branded authentication')).toBeNull();
+    });
 });