Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

53.0 KB
Raw Blame
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { useTranslation } from "react-i18next";
import { AlertCircle } from "./icons";
import { CompactAuthenticationFlow } from "./CompactAuthenticationFlow";
import UseCaseStep from "./onboarding/UseCaseStep";
import { hasUseCaseIntent } from "./onboarding/useCases";
import OnboardingShell, { OnboardingStepHeader } from "./onboarding/OnboardingShell";
import CompactPermissionsStep from "./onboarding/CompactPermissionsStep";
import LanguageSelectionStep from "./onboarding/LanguageSelectionStep";
import ShortcutSetupStep from "./onboarding/ShortcutSetupStep";
import AssistantHotkeyPreview from "./onboarding/AssistantHotkeyPreview";
import DemoStep from "./onboarding/DemoStep";
import CalendarConnectionsStep from "./onboarding/CalendarConnectionsStep";
import SetupChoiceStep from "./onboarding/SetupChoiceStep";
import { ByokProviderStep, LocalModelSetupStep } from "./onboarding/ProviderSetupStep";
import { RequiredModelDownloadStep } from "./onboarding/RequiredModelDownloadStep";
import { AlertDialog } from "./ui/dialog";
import { useAuth } from "../hooks/useAuth";
import { usePermissions } from "../hooks/usePermissions";
import { useClipboard } from "../hooks/useClipboard";
import { useScreenRecordingPermission } from "../hooks/useScreenRecordingPermission";
import { useSystemAudioPermission } from "../hooks/useSystemAudioPermission";
import { useSettings } from "../hooks/useSettings";
import { useLocalStorage } from "../hooks/useLocalStorage";
import { useHotkeyRegistration } from "../hooks/useHotkeyRegistration";
import { useHotkeyModeInfo } from "../hooks/useHotkeyModeInfo";
import { useWorkspace } from "../hooks/useWorkspace";
import { useRequiredLocalModels } from "../hooks/useRequiredLocalModels";
import { usePolicyStore } from "../stores/policyStore";
import { isAgentAllowed, isScreenContextAllowed } from "../stores/policyRules";
import { useSettingsStore } from "../stores/settingsStore";
import { getDefaultHotkey, parseHotkeyList, serializeHotkeyList } from "../utils/hotkeys";
import {
  DEFAULT_ASSISTANT_ONBOARDING_HOTKEY,
  formatHotkeyInstruction,
  getRecommendedDictationHotkeys,
  resolveOnboardingAssistantHotkey,
  resolveOnboardingDictationHotkey,
} from "./onboarding/hotkeyPresentation";
import { getValidationMessage } from "../utils/hotkeyValidator";
import { validateHotkeyForSlot } from "../utils/hotkeyValidation";
import { getPlatform } from "../utils/platform";
import { ACCESSIBILITY_SKIPPED_KEY, areRequiredPermissionsMet } from "../utils/permissions";
import { cloudPost } from "../services/cloudApi";
import { signOut } from "../lib/auth";
import logger from "../utils/logger";
import {
  COMPACT_STEPS,
  getNextOnboardingStep,
  getNotesFooterAction,
  getOnboardingProgress,
  getOnboardingRoute,
  isSetupDecisionStep,
  reconcileStepWithRoute,
  resetOnboardingProgress,
  resolveEnterpriseWorkspaceForOnboarding,
  shouldInitializeMacAccessibilityFeatures,
  shouldSkipOnboardingSetupChoice,
  type OnboardingAuthDraft,
  type OnboardingByokDraft,
  type OnboardingLocalModelDraft,
  type OnboardingResumeState,
  type OnboardingSetupMode,
  type OnboardingStepId,
} from "./onboarding/flow";
import { useOnboardingSession } from "./onboarding/useOnboardingSession";
import { usePermissionGuide } from "./onboarding/usePermissionGuide";
import {
  requestMicrophoneForGuide,
  type GuidePermission,
} from "./onboarding/permissionGuideController";
import { clearPendingLocalModels, hasPendingLocalModels } from "./onboarding/pendingLocalModels";
import { resolveAssistantDemoScenario } from "./onboarding/assistantDemoScenario";
import { ActivationModeSelector } from "./ui/ActivationModeSelector";
import LinuxPttSetupInfo from "./ui/LinuxPttSetupInfo";

interface OnboardingFlowProps {
  onComplete: (options?: { openSettings?: boolean }) => void;
}

type OnboardingCompletionMode = Exclude<OnboardingSetupMode, null> | "managed";

function DemoHotkeyDescription({ text, hotkey }: { text: string; hotkey: string }) {
  const hotkeyStart = text.indexOf(hotkey);
  if (hotkeyStart < 0) return text;

  return (
    <>
      {text.slice(0, hotkeyStart)}
      <kbd className="mx-0.5 inline-flex rounded-md bg-[color-mix(in_srgb,var(--onboarding-accent)_12%,transparent)] px-1.5 py-0.5 font-semibold text-[var(--onboarding-accent)]">
        {hotkey}
      </kbd>
      {text.slice(hotkeyStart + hotkey.length)}
    </>
  );
}

export default function OnboardingFlow({ onComplete }: OnboardingFlowProps) {
  const { t } = useTranslation();
  const platform = getPlatform();
  const { isSignedIn } = useAuth();
  const agentAllowed = usePolicyStore(isAgentAllowed);
  const screenContextAllowed = usePolicyStore(isScreenContextAllowed);
  const settings = useSettings();
  const settingsStore = useSettingsStore();
  const {
    session,
    setSession,
    goTo,
    goBack,
    setAuthPath,
    setSetupMode,
    setSelfHostedRequested,
    setScreenContextRequested,
    setPermissionGuide,
    clearSession,
  } = useOnboardingSession();

  const handleLogout = useCallback(async () => {
    await signOut();
    resetOnboardingProgress(localStorage);
    window.location.reload();
  }, []);
  // Set by Back on the permissions step: a signed-in user who asked to return to
  // the auth step gets the welcome screen (where Log out lives), not auto-advance.
  const [returnedToAuth, setReturnedToAuth] = useState(false);

  const { dictationHotkeyConfirmed, assistantHotkeyConfirmed } = session.resume;
  const [dictationHotkey, setDictationHotkey] = useState(() =>
    resolveOnboardingDictationHotkey({
      platform,
      savedHotkey: parseHotkeyList(settings.dictationKey)[0] ?? "",
      platformDefault: getDefaultHotkey(),
      confirmed: dictationHotkeyConfirmed,
    })
  );
  const [assistantHotkey, setAssistantHotkey] = useState(() =>
    resolveOnboardingAssistantHotkey(parseHotkeyList(settings.voiceAgentKey)[0] ?? "")
  );
  // Seeded from main rather than getDefaultHotkey(): main already knows when the
  // platform default can't bind (GNOME/X11 reject modifier-only combos) and
  // registered a fallback instead — recommending the unregistrable default would
  // make every confirm of it fail.
  const [recommendedDictationHotkey, setRecommendedDictationHotkey] = useState(getDefaultHotkey);
  const dictationDemoSuccess = session.resume.dictationDemoCompleted;
  const assistantDemoSuccess = session.resume.assistantDemoCompleted;
  const [stageReady, setStageReady] = useState(false);
  const [isFinishing, setIsFinishing] = useState(false);
  const [fatalError, setFatalError] = useState<string | null>(null);
  const [permissionAlert, setPermissionAlert] = useState<{
    title: string;
    description: string;
  } | null>(null);
  const [, setAccessibilitySkipped] = useLocalStorage(ACCESSIBILITY_SKIPPED_KEY, false);

  const updateResumeFlag = useCallback(
    (
      key: Extract<
        keyof OnboardingResumeState,
        | "dictationHotkeyConfirmed"
        | "assistantHotkeyConfirmed"
        | "dictationDemoCompleted"
        | "assistantDemoCompleted"
      >,
      value: boolean
    ) => {
      setSession((current) => ({
        ...current,
        resume: { ...current.resume, [key]: value },
      }));
    },
    [setSession]
  );
  const setDictationHotkeyConfirmed = useCallback(
    (confirmed: boolean) => updateResumeFlag("dictationHotkeyConfirmed", confirmed),
    [updateResumeFlag]
  );
  const setAssistantHotkeyConfirmed = useCallback(
    (confirmed: boolean) => updateResumeFlag("assistantHotkeyConfirmed", confirmed),
    [updateResumeFlag]
  );
  const setDictationDemoSuccess = useCallback(
    (successful: boolean) => updateResumeFlag("dictationDemoCompleted", successful),
    [updateResumeFlag]
  );
  const setAssistantDemoSuccess = useCallback(
    (successful: boolean) => updateResumeFlag("assistantDemoCompleted", successful),
    [updateResumeFlag]
  );
  const updateAuthResumeState = useCallback(
    (patch: Partial<OnboardingAuthDraft>) => {
      setSession((current) => ({
        ...current,
        resume: {
          ...current.resume,
          auth: { ...current.resume.auth, ...patch },
        },
      }));
    },
    [setSession]
  );

  useClipboard((dialog) =>
    setPermissionAlert({ title: dialog.title, description: dialog.description })
  );
  const systemAudio = useSystemAudioPermission();
  const {
    granted: screenRecordingGranted,
    needsRelaunch: screenRecordingNeedsRelaunch,
    loaded: screenRecordingLoaded,
    check: checkScreenRecording,
    request: requestScreenRecordingAccess,
  } = useScreenRecordingPermission();
  const {
    supportsPushToTalk,
    pushToTalkUnavailableReason,
    linuxInputAccessDenied,
    loaded: hotkeyModeLoaded,
  } = useHotkeyModeInfo("onboarding", dictationHotkey);
  const { activationMode, setActivationMode } = settings;
  // This hook also starts the membership fetch for already-authenticated users;
  // relying on the login transition alone would leave resumed onboarding stuck
  // waiting for workspace resolution after an app restart.
  const {
    active: activeWorkspace,
    workspaces,
    loaded: workspacesLoaded,
    setActive: setActiveWorkspace,
  } = useWorkspace();
  const enterpriseWorkspace = useMemo(
    () => resolveEnterpriseWorkspaceForOnboarding(activeWorkspace, workspaces),
    [activeWorkspace, workspaces]
  );
  const skipSetupChoiceForEnterprise = shouldSkipOnboardingSetupChoice({
    isSignedIn,
    authPath: session.authPath,
    setupMode: session.setupMode,
    activeWorkspace: enterpriseWorkspace,
  });

  useEffect(() => {
    if (
      workspacesLoaded &&
      !activeWorkspace &&
      skipSetupChoiceForEnterprise &&
      enterpriseWorkspace
    ) {
      setActiveWorkspace(enterpriseWorkspace.id);
    }
  }, [
    activeWorkspace,
    enterpriseWorkspace,
    setActiveWorkspace,
    skipSetupChoiceForEnterprise,
    workspacesLoaded,
  ]);

  const workspaceResolutionPending =
    isSignedIn &&
    session.authPath === "account" &&
    (!workspacesLoaded ||
      (!activeWorkspace && skipSetupChoiceForEnterprise && Boolean(enterpriseWorkspace)));
  const hasConnectedCalendar =
    settingsStore.gcalAccounts.length > 0 ||
    settingsStore.mcalAccounts.length > 0 ||
    (platform === "darwin" && settingsStore.appleCalendarConnected);

  // The setting turns on only once the permission is actually granted, so an
  // Enable click whose System Settings grant is abandoned can't leave screen
  // context armed to activate silently on some later grant. The latch lives in
  // the persisted session because macOS asks to quit and reopen the app after
  // the grant; it is cleared as soon as it is consumed.
  const screenContextRequested = session.screenContextRequested;

  const applyScreenContext = useCallback(() => {
    setScreenContextRequested(false);
    settingsStore.setVoiceAgentScreenContext(true);
    // Keeps the dictation overlay out of its own screenshots.
    void window.electronAPI?.setScreenContextEnabled?.(true);
  }, [setScreenContextRequested, settingsStore]);

  const enableScreenContext = useCallback(async () => {
    setScreenContextRequested(true);
    const granted = await requestScreenRecordingAccess();
    if (granted) applyScreenContext();
    return granted;
  }, [applyScreenContext, requestScreenRecordingAccess, setScreenContextRequested]);

  // macOS grants Screen Recording in System Settings, outside the app; the
  // permission hook re-checks on mount and window focus. When the grant lands,
  // complete the opt-in the Enable click started. A system grant alone must
  // not enable Screen Context without the user's explicit opt-in.
  useEffect(() => {
    if (!screenRecordingGranted || !agentAllowed || !screenContextAllowed) return;
    if (screenContextRequested) {
      applyScreenContext();
    }
  }, [
    agentAllowed,
    applyScreenContext,
    screenContextAllowed,
    screenContextRequested,
    screenRecordingGranted,
  ]);

  const requiredModels = useRequiredLocalModels();
  // Latched for the session once the step is entered (or resumed at), so a
  // mid-download policy refresh or the disk check settling can't rebuild the
  // route out from under the user. Seeded from the persisted session because
  // relaunching mid-download must resume on the step, not bounce off it while
  // the disk check is still pending.
  const requiredModelsLatchRef = useRef(session.currentStepId === "required-models");
  const requiredModelsPending = requiredModelsLatchRef.current || requiredModels.missing.length > 0;

  const route = useMemo(
    () =>
      getOnboardingRoute({
        authPath: session.authPath,
        setupMode: session.setupMode,
        agentAllowed,
        requiredModelsPending,
        skipSetupChoice: skipSetupChoiceForEnterprise,
      }),
    [
      agentAllowed,
      requiredModelsPending,
      session.authPath,
      session.setupMode,
      skipSetupChoiceForEnterprise,
    ]
  );
  const currentStepId = reconcileStepWithRoute(session.currentStepId, route);
  const compact = COMPACT_STEPS.has(currentStepId);
  const setupDecisionPending =
    workspaceResolutionPending && isSetupDecisionStep(currentStepId, route);
  const notesFooterAction = getNotesFooterAction({ setupDecisionPending, hasConnectedCalendar });
  // Screen context only reaches the model once macOS has been relaunched after
  // the grant; until then the demo must not promise the assistant can see the card.
  const screenContextActive =
    agentAllowed &&
    screenContextAllowed &&
    settingsStore.voiceAgentScreenContext &&
    screenRecordingGranted &&
    !screenRecordingNeedsRelaunch;
  const permissions = usePermissions(
    (dialog) => setPermissionAlert({ title: dialog.title, description: dialog.description }),
    {
      macAccessibilityChecksEnabled: shouldInitializeMacAccessibilityFeatures(currentStepId),
    }
  );
  const openSettings =
    (open: () => Promise<{ success: boolean; error?: string }>) => async (): Promise<void> => {
      const result = await open();
      if (!result.success) throw new Error(result.error);
    };
  const openMicrophoneSettings = openSettings(window.electronAPI.openMicrophoneSettings);
  const openAccessibilitySettings = openSettings(window.electronAPI.openAccessibilitySettings);
  const guideRows: GuidePermission[] = [
    {
      id: "microphone",
      request: async () => {
        const result = await requestMicrophoneForGuide({
          requestAccess: window.electronAPI.requestMicrophoneAccess,
          checkAccess: window.electronAPI.checkMicrophoneAccess,
          openSettings: openMicrophoneSettings,
        });
        permissions.setMicPermissionGranted(result.granted);
      },
      check: async () => {
        const result = await window.electronAPI.checkMicrophoneAccess();
        permissions.setMicPermissionGranted(result.granted);
        return result;
      },
      openSettings: openMicrophoneSettings,
    },
    {
      id: "accessibility",
      request: openAccessibilitySettings,
      check: async () => {
        const granted = await window.electronAPI.checkAccessibilityPermission(true);
        permissions.setAccessibilityPermissionGranted(granted);
        return { granted };
      },
      openSettings: openAccessibilitySettings,
    },
  ];
  if (systemAudio.mode === "native")
    guideRows.push({
      id: "system-audio",
      request: systemAudio.request,
      check: async () => {
        await systemAudio.check();
        return window.electronAPI.checkSystemAudioAccess();
      },
      verify: async () => {
        const result = await window.electronAPI.verifySystemAudioAccess();
        await systemAudio.check();
        return result;
      },
      openSettings: openSettings(window.electronAPI.openSystemAudioSettings),
    });
  if (agentAllowed && screenContextAllowed)
    guideRows.push({
      id: "screen-context",
      request: async () => {
        setScreenContextRequested(true);
        return requestScreenRecordingAccess();
      },
      onGranted: applyScreenContext,
      check: async () => {
        const result = await window.electronAPI.checkScreenRecordingAccess();
        await checkScreenRecording();
        return result;
      },
      openSettings: openSettings(window.electronAPI.openScreenRecordingSettings),
    });
  const guideReady = platform === "darwin" && systemAudio.loaded && screenRecordingLoaded;
  const permissionGuide = usePermissionGuide({
    enabled: currentStepId === "permissions" && guideReady,
    progress: session.permissionGuide,
    save: setPermissionGuide,
    // Dismissing the guide withdraws the Screen Context opt-in; enabling
    // another permission while it is still pending does not.
    dismissed: () => setScreenContextRequested(false),
    rows: guideRows,
  });

  useEffect(() => {
    if (currentStepId !== "permissions" && session.permissionGuide) setPermissionGuide(null);
  }, [currentStepId, session.permissionGuide, setPermissionGuide]);
  const updateCurrentByokDraft = useCallback(
    (state: OnboardingByokDraft) => {
      if (currentStepId !== "byok-dictation" && currentStepId !== "byok-assistant") return;
      setSession((current) => ({
        ...current,
        resume: {
          ...current.resume,
          byok: { ...current.resume.byok, [currentStepId]: state },
        },
      }));
    },
    [currentStepId, setSession]
  );
  const updateCurrentLocalModelDraft = useCallback(
    (state: OnboardingLocalModelDraft) => {
      if (currentStepId !== "local-dictation" && currentStepId !== "local-assistant") return;
      setSession((current) => ({
        ...current,
        resume: {
          ...current.resume,
          localModels: { ...current.resume.localModels, [currentStepId]: state },
        },
      }));
    },
    [currentStepId, setSession]
  );

  useEffect(() => {
    if (currentStepId === "required-models") requiredModelsLatchRef.current = true;
  }, [currentStepId]);

  // New users default to hold-to-talk, but only where no mode was ever chosen
  // (the store's "tap" is a fallback) and once main has confirmed this desktop
  // supports it — the hook's placeholder says yes on every platform.
  useEffect(() => {
    if (currentStepId !== "dictation-hotkey" || !hotkeyModeLoaded) return;
    if (supportsPushToTalk && localStorage.getItem("activationMode") === null) {
      setActivationMode("push");
    }
  }, [currentStepId, hotkeyModeLoaded, setActivationMode, supportsPushToTalk]);

  // The auth step lands on "permissions" before the policy and disk checks
  // settle (AppRouter's policy gate remounts this component mid-transition),
  // so a persisted session can sit one step past the gate when the pending
  // flag arrives. Pull the user back — only from permissions, the immediate
  // post-auth screen, and only before the step was entered this session.
  useEffect(() => {
    if (
      requiredModelsPending &&
      currentStepId === "permissions" &&
      !requiredModelsLatchRef.current &&
      route.includes("required-models")
    ) {
      goTo("required-models");
    }
  }, [currentStepId, goTo, requiredModelsPending, route]);

  useEffect(() => {
    if (session.currentStepId !== currentStepId) {
      setSession((current) => ({ ...current, currentStepId }));
    }
  }, [currentStepId, session.currentStepId, setSession]);

  // AppRouter releases this only after it has committed the normal app. Keeping
  // the gate active across this component's unmount prevents a one-frame flash
  // of the dictation pill or another normal-app overlay at completion/error.
  useEffect(() => {
    void window.electronAPI?.setOnboardingActive?.(true);
  }, []);

  useEffect(() => {
    void window.electronAPI?.setOnboardingWindowMode?.(compact ? "compact" : "expanded");
  }, [compact]);

  useEffect(() => {
    if (platform === "darwin" && shouldInitializeMacAccessibilityFeatures(currentStepId)) {
      window.electronAPI?.markMacAccessibilityFeaturesReady?.();
    }
  }, [currentStepId, platform]);

  useEffect(() => {
    setStageReady(false);
  }, [currentStepId]);

  // Track main's actual registration: the platform default may be unregistrable
  // (GNOME gsettings and X11 reject modifier-only combos like Control+Super), in
  // which case main silently registered FALLBACK_HOTKEYS instead. Recommend and
  // teach the key that really works, not the one that always errors.
  useEffect(() => {
    let cancelled = false;
    void window.electronAPI
      ?.getEffectiveDefaultHotkey?.()
      .then((key) => {
        const effective = key && parseHotkeyList(key)[0];
        if (cancelled || !effective) return;
        setRecommendedDictationHotkey(effective);
        // finalizeOnboarding registers dictationHotkey without further input on
        // routes that never show the hotkey step, so an unregistrable renderer
        // default has to be replaced here, not just in the recommendation.
        setDictationHotkey((current) => (current === getDefaultHotkey() ? effective : current));
      })
      .catch((error) =>
        logger.warn("Failed to read effective default hotkey", { error }, "onboarding")
      );
    const unsubscribe = window.electronAPI?.onHotkeyFallbackUsed?.((data) => {
      const fallback = parseHotkeyList(data?.fallback)[0];
      if (!fallback) return;
      setDictationHotkey(fallback);
      setRecommendedDictationHotkey(fallback);
    });
    return () => {
      cancelled = true;
      unsubscribe?.();
    };
  }, []);

  const withExtraDictationHotkeys = useCallback(
    (primary: string) =>
      serializeHotkeyList([primary, ...parseHotkeyList(settings.dictationKey).slice(1)]),
    [settings.dictationKey]
  );

  const hotkeyErrorRef = useRef<string | null>(null);
  const { registerHotkey, isRegistering } = useHotkeyRegistration({
    onSuccess: (registered) => {
      const primary = parseHotkeyList(registered)[0] || registered;
      setDictationHotkey(primary);
      settings.setDictationKey(registered);
    },
    onError: (message) => {
      hotkeyErrorRef.current = message;
    },
    showSuccessToast: false,
    showErrorToast: false,
  });

  const validateDictationHotkey = useCallback(
    (value: string) => getValidationMessage(value, platform),
    [platform]
  );
  const validateAssistantHotkey = useCallback(
    (value: string) =>
      validateHotkeyForSlot(
        value,
        { "settingsPage.general.hotkey.title": withExtraDictationHotkeys(dictationHotkey) },
        t
      ),
    [dictationHotkey, t, withExtraDictationHotkeys]
  );

  const confirmDictationHotkey = useCallback(
    async (value: string) => {
      // A key the OS cannot see released falls back to Tap rather than failing
      // the pick; the card below shows Hold disabled with the reason.
      if (activationMode === "push") {
        const info = await window.electronAPI?.getHotkeyModeInfo?.(value);
        if (info && !info.supportsPushToTalk) setActivationMode("tap");
      }
      hotkeyErrorRef.current = null;
      const registered = await registerHotkey(withExtraDictationHotkeys(value));
      return registered ? null : (hotkeyErrorRef.current ?? t("onboarding.rehaul.hotkey.inUse"));
    },
    [activationMode, registerHotkey, setActivationMode, t, withExtraDictationHotkeys]
  );

  const confirmAssistantHotkey = useCallback(
    async (value: string) => {
      const result = await settings.setVoiceAgentKey(
        serializeHotkeyList([value, ...parseHotkeyList(settings.voiceAgentKey).slice(1)])
      );
      return result.success ? null : result.message || t("onboarding.rehaul.hotkey.inUse");
    },
    [settings, t]
  );

  const syncUseCases = useCallback(() => {
    if (!isSignedIn || session.authPath === "guest") return;
    cloudPost("/api/onboarding-intent", {
      useCases: settings.onboardingUseCases,
      note: settings.onboardingUseCaseNote || undefined,
      spokenLanguages: settings.spokenLanguages,
    }).catch((error) => logger.warn("Failed to sync onboarding intent", { error }, "onboarding"));
  }, [
    isSignedIn,
    session.authPath,
    settings.onboardingUseCaseNote,
    settings.onboardingUseCases,
    settings.spokenLanguages,
  ]);

  const finalizeOnboarding = useCallback(
    async (mode: OnboardingCompletionMode) => {
      if (isFinishing) return;
      setIsFinishing(true);
      setFatalError(null);
      try {
        const registered = await registerHotkey(withExtraDictationHotkeys(dictationHotkey));
        if (!registered) {
          setFatalError(t("onboarding.hotkey.couldNotRegisterDescription"));
          return;
        }

        if (mode === "cloud") {
          const health = await window.electronAPI?.cloudHealthCheck?.();
          if (health && !health.ok && health.status === undefined) {
            setFatalError(t(health.messageKey || "streaming.errors.cloudUnreachable.generic"));
            return;
          }
        }

        await window.electronAPI?.saveAllKeysToEnv?.();
        await window.electronAPI?.markBundleMigrated?.();
        await window.electronAPI?.setOnboardingWindowMode?.("restore");

        // hasPendingLocalModels() covers leaving a still-running download, by
        // Proceed or Skip: the model was remembered when the download started,
        // and BackgroundModelDownloadTray only applies it (and then clears this
        // flag) while the flag is set.
        //
        // Only preserve a pending download when the completed route still uses
        // local models. A user who walks Back and finishes on Cloud/BYOK must not
        // be switched back to a stale local selection when it completes later.
        const routeKeepsLocalModels = mode === "local";
        if (routeKeepsLocalModels && hasPendingLocalModels()) {
          localStorage.setItem("localSetupPending", "true");
        } else {
          localStorage.removeItem("localSetupPending");
          clearPendingLocalModels();
        }

        const skippedAuth = session.authPath === "guest";
        localStorage.setItem("authenticationSkipped", String(skippedAuth));
        localStorage.setItem("skipAuth", String(skippedAuth));
        clearSession();
        localStorage.setItem("onboardingCompleted", "true");
        onComplete();
      } catch (error) {
        logger.error("Failed to finish onboarding", { error }, "onboarding");
        setFatalError(t("common.unknownError"));
      } finally {
        setIsFinishing(false);
      }
    },
    [
      clearSession,
      dictationHotkey,
      isFinishing,
      onComplete,
      registerHotkey,
      session.authPath,
      t,
      withExtraDictationHotkeys,
    ]
  );

  // Sessions saved on the old setup-choice step reconcile back to the last
  // guided step once an Enterprise workspace is confirmed. Finish them without
  // writing provider or model settings, just as if that had been their final
  // step originally.
  useEffect(() => {
    if (!skipSetupChoiceForEnterprise || session.currentStepId !== "setup-choice" || isFinishing) {
      return;
    }
    void finalizeOnboarding("managed");
  }, [finalizeOnboarding, isFinishing, session.currentStepId, skipSetupChoiceForEnterprise]);

  const applyReasoningSelectionToAllScopes = useCallback(
    (mode: "byok" | "local") => {
      // getState(), not the render-time snapshot: the provider steps write
      // chatAgentProvider/chatAgentModel via switchReasoningProvider and call
      // onProceed() in the same tick, so `settingsStore` here still holds the
      // values from before the pick. Reading it stale configured the other three
      // scopes to the defaults (groq / openai/gpt-oss-120b) with no key.
      const {
        chatAgentProvider,
        chatAgentModel,
        chatAgentCloudBaseUrl,
        chatAgentRemoteUrl,
        chatAgentCustomApiKey,
      } = useSettingsStore.getState();
      settingsStore.setCloudReasoningForAllScopes({
        cleanupCloudMode: mode,
        cleanupProvider: chatAgentProvider,
        cleanupModel: chatAgentModel,
        cleanupCloudBaseUrl: chatAgentCloudBaseUrl,
        cleanupRemoteUrl: chatAgentRemoteUrl,
        // Only a self-hosted or custom endpoint has one; an empty write would
        // just churn five secure-store entries.
        ...(chatAgentCustomApiKey ? { cleanupCustomApiKey: chatAgentCustomApiKey } : {}),
        useCleanupModel: true,
        useDictationAgent: true,
      });
    },
    [settingsStore]
  );

  const handleSetupSelection = useCallback(
    async (mode: Exclude<OnboardingSetupMode, null>, options?: { selfHosted?: boolean }) => {
      setSetupMode(mode);
      setSelfHostedRequested(!!options?.selfHosted);
      if (mode === "cloud") {
        settingsStore.setCloudTranscriptionForAllScopes({
          useLocalWhisper: false,
          cloudTranscriptionMode: "openwhispr",
          cloudTranscriptionProvider: "openwhispr",
        });
        if (agentAllowed) {
          settingsStore.setCloudReasoningForAllScopes({
            cleanupCloudMode: "openwhispr",
            cleanupProvider: "openwhispr",
          });
        } else {
          // The policy-shortened route has no assistant setup. Avoid persisting
          // a reasoning provider the workspace disallows, and keep dictation
          // from attempting cleanup through an unconfigured LLM.
          settingsStore.updateCleanupSettings({ useCleanupModel: false });
        }
        await finalizeOnboarding("cloud");
        return;
      }
      const nextRoute = getOnboardingRoute({
        authPath: session.authPath,
        setupMode: mode,
        agentAllowed,
        requiredModelsPending,
      });
      const next = getNextOnboardingStep("setup-choice", nextRoute);
      if (next) goTo(next);
    },
    [
      agentAllowed,
      finalizeOnboarding,
      goTo,
      requiredModelsPending,
      session.authPath,
      setSelfHostedRequested,
      setSetupMode,
      settingsStore,
    ]
  );

  const continueFromCurrentStep = useCallback(async () => {
    // A banner from an earlier failed attempt must not outlive the retry.
    setFatalError(null);
    if (setupDecisionPending) return;
    if (currentStepId === "permissions") {
      if (platform === "darwin" && !permissions.accessibilityPermissionGranted) {
        setAccessibilitySkipped(true);
      }
    } else if (currentStepId === "languages") {
      settings.setPreferredLanguage(
        settings.spokenLanguages.length === 1 ? settings.spokenLanguages[0] : "auto"
      );
    } else if (currentStepId === "use-cases") {
      syncUseCases();
    } else if (currentStepId === "dictation-hotkey") {
      const registered = await registerHotkey(withExtraDictationHotkeys(dictationHotkey));
      if (!registered) {
        setFatalError(t("onboarding.hotkey.couldNotRegisterDescription"));
        return;
      }
      setDictationHotkeyConfirmed(true);
    } else if (currentStepId === "assistant-hotkey") {
      if (parseHotkeyList(settings.voiceAgentKey)[0] !== assistantHotkey) {
        const result = await settings.setVoiceAgentKey(
          serializeHotkeyList([
            assistantHotkey,
            ...parseHotkeyList(settings.voiceAgentKey).slice(1),
          ])
        );
        if (!result.success) {
          setFatalError(result.message || t("onboarding.rehaul.hotkey.inUse"));
          return;
        }
      }
    } else if (currentStepId === "byok-dictation") {
      settingsStore.setCloudTranscriptionForAllScopes({
        useLocalWhisper: false,
        cloudTranscriptionMode: "byok",
      });
      // When policy disallows the assistant, its step is off-route and no
      // LLM gets configured. Turn cleanup off so dictations do not route to a
      // default provider with no credential behind it.
      if (!route.includes("byok-assistant")) {
        settingsStore.updateCleanupSettings({ useCleanupModel: false });
      }
    } else if (currentStepId === "byok-assistant") {
      applyReasoningSelectionToAllScopes("byok");
    } else if (currentStepId === "local-dictation") {
      settingsStore.setCloudTranscriptionForAllScopes({ useLocalWhisper: true });
      // Same policy-shortened-route case as BYOK: no local LLM was downloaded,
      // so cleanup must not silently fall back to a cloud default.
      if (!route.includes("local-assistant")) {
        settingsStore.updateCleanupSettings({ useCleanupModel: false });
      }
    } else if (currentStepId === "local-assistant") {
      applyReasoningSelectionToAllScopes("local");
    }

    const next = getNextOnboardingStep(currentStepId, route);
    if (next) {
      goTo(next);
      return;
    }

    if (skipSetupChoiceForEnterprise) {
      await finalizeOnboarding("managed");
      return;
    }
    if (session.setupMode) await finalizeOnboarding(session.setupMode);
  }, [
    applyReasoningSelectionToAllScopes,
    assistantHotkey,
    currentStepId,
    dictationHotkey,
    finalizeOnboarding,
    goTo,
    permissions.accessibilityPermissionGranted,
    platform,
    registerHotkey,
    route,
    session.setupMode,
    setAccessibilitySkipped,
    setDictationHotkeyConfirmed,
    settings,
    settingsStore,
    syncUseCases,
    t,
    withExtraDictationHotkeys,
    setupDecisionPending,
    skipSetupChoiceForEnterprise,
  ]);

  const skipLocalSetup = useCallback(async () => {
    if (currentStepId === "local-dictation") {
      await continueFromCurrentStep();
      return;
    }
    // The local assistant is optional. If the user skips it, prevent
    // dictation from falling back to an unconfigured cleanup provider.
    settingsStore.updateCleanupSettings({ useCleanupModel: false });
    await finalizeOnboarding("local");
  }, [continueFromCurrentStep, currentStepId, finalizeOnboarding, settingsStore]);

  const canContinue = (() => {
    switch (currentStepId) {
      case "required-models":
        return !requiredModels.loading && requiredModels.missing.length === 0;
      case "permissions":
        return areRequiredPermissionsMet(permissions.micPermissionGranted);
      case "languages":
        return settings.spokenLanguages.length > 0;
      case "use-cases":
        return hasUseCaseIntent(settings.onboardingUseCases, settings.onboardingUseCaseNote);
      case "dictation-hotkey":
        return dictationHotkeyConfirmed;
      case "dictation-demo":
        return dictationDemoSuccess;
      case "assistant-hotkey":
        return assistantHotkeyConfirmed;
      case "assistant-demo":
        return assistantDemoSuccess;
      case "notes":
        return notesFooterAction === "continue";
      case "byok-dictation":
      case "byok-assistant":
      case "local-dictation":
      case "local-assistant":
        return stageReady;
      default:
        return true;
    }
  })();

  const renderStep = () => {
    switch (currentStepId) {
      case "auth":
        return (
          <div className="min-h-full w-full">
            <CompactAuthenticationFlow
              resumeState={session.resume.auth}
              onResumeStateChange={updateAuthResumeState}
              autoContinue={!returnedToAuth}
              onSignOut={() => void handleLogout()}
              onContinueWithoutAccount={() => {
                // Guests continue onto their route's permissions step — jumping
                // straight to setup-choice would skip the permission grants and
                // hotkey the guest route exists to guarantee (see flow.ts).
                setReturnedToAuth(false);
                setAuthPath("guest");
                goTo("permissions");
              }}
              onAuthComplete={() => {
                setReturnedToAuth(false);
                setAuthPath("account");
                goTo(session.setupMode === "cloud" ? "setup-choice" : "permissions");
              }}
            />
          </div>
        );

      case "required-models":
        return (
          <div className="h-full w-full pt-2">
            <OnboardingStepHeader
              title={t("onboarding.requiredModels.title")}
              wideTitle
              description={t("onboarding.requiredModels.description", {
                organization:
                  activeWorkspace?.name ?? t("onboarding.requiredModels.genericOrganization"),
              })}
            />
            <RequiredModelDownloadStep
              required={requiredModels.required}
              missing={requiredModels.missing}
              loading={requiredModels.loading}
              refresh={requiredModels.refresh}
              onProceed={() => void continueFromCurrentStep()}
            />
          </div>
        );

      case "permissions":
        return (
          <CompactPermissionsStep
            permissions={permissions}
            guide={{ ...permissionGuide, ready: guideReady }}
            systemAudio={systemAudio}
            screenContext={
              agentAllowed && screenContextAllowed
                ? {
                    enabled: settingsStore.voiceAgentScreenContext,
                    granted: screenRecordingGranted,
                    needsRelaunch: screenRecordingNeedsRelaunch,
                    request: enableScreenContext,
                  }
                : undefined
            }
            onBack={
              session.history.length > 0
                ? () => {
                    setReturnedToAuth(true);
                    goBack();
                  }
                : undefined
            }
            onContinue={() => void continueFromCurrentStep()}
          />
        );

      case "languages":
        return (
          <div className="flex h-full min-h-0 w-full flex-col pt-1">
            <OnboardingStepHeader
              title={t("onboarding.rehaul.languages.title")}
              titleLines={[
                t("onboarding.rehaul.languages.titleLineOne"),
                t("onboarding.rehaul.languages.titleLineTwo"),
              ]}
              description={t("onboarding.rehaul.languages.description")}
            />
            <LanguageSelectionStep
              selected={settings.spokenLanguages}
              onChange={settings.setSpokenLanguages}
              searchPlaceholder={t("languageSelector.searchPlaceholder")}
              noResultsLabel={t("languageSelector.noLanguagesFound")}
              selectedLabel={t("onboarding.rehaul.languages.title")}
            />
          </div>
        );

      case "use-cases":
        return (
          <div className="h-full w-full pt-1">
            <UseCaseStep
              useCases={settings.onboardingUseCases}
              onUseCasesChange={settings.setOnboardingUseCases}
              note={settings.onboardingUseCaseNote}
              onNoteChange={settings.setOnboardingUseCaseNote}
            />
          </div>
        );

      case "dictation-hotkey":
      case "assistant-hotkey": {
        const assistant = currentStepId === "assistant-hotkey";
        return (
          <div className="flex h-full min-h-0 w-full flex-col pt-2">
            <OnboardingStepHeader
              title={t(
                assistant
                  ? "onboarding.rehaul.assistantHotkey.title"
                  : "onboarding.rehaul.dictationHotkey.title"
              )}
              // The assistant step's preview image needs the room a two-line header takes.
              titleLines={
                assistant
                  ? undefined
                  : [
                      t("onboarding.rehaul.dictationHotkey.titleLineOne"),
                      t("onboarding.rehaul.dictationHotkey.titleLineTwo"),
                    ]
              }
              wideTitle={assistant}
              wideDescription={assistant}
              description={t(
                assistant
                  ? "onboarding.rehaul.assistantHotkey.description"
                  : "onboarding.rehaul.dictationHotkey.description"
              )}
            />
            {assistant && <AssistantHotkeyPreview />}
            <ShortcutSetupStep
              value={assistant ? assistantHotkey : dictationHotkey}
              initiallyConfirmed={assistant ? assistantHotkeyConfirmed : dictationHotkeyConfirmed}
              onChange={(value) => {
                if (assistant) {
                  setAssistantHotkey(value);
                  setAssistantHotkeyConfirmed(true);
                } else {
                  setDictationHotkey(value);
                  setDictationHotkeyConfirmed(true);
                }
              }}
              onClearSelection={() => {
                if (assistant) {
                  setAssistantHotkey("");
                  setAssistantHotkeyConfirmed(false);
                } else {
                  setDictationHotkey("");
                  setDictationHotkeyConfirmed(false);
                }
              }}
              recommended={
                assistant
                  ? DEFAULT_ASSISTANT_ONBOARDING_HOTKEY
                  : getRecommendedDictationHotkeys(platform, recommendedDictationHotkey)
              }
              captureLabel={t("onboarding.rehaul.hotkey.capture")}
              recommendedLabel={t("common.recommended")}
              chooseAnotherLabel={t("onboarding.rehaul.hotkey.chooseAnother")}
              validate={assistant ? validateAssistantHotkey : validateDictationHotkey}
              onConfirm={assistant ? confirmAssistantHotkey : confirmDictationHotkey}
              dense={assistant}
            />
            {!assistant && (
              <div className="mx-auto mt-8 w-full max-w-md rounded-2xl border border-[var(--onboarding-control-border)] bg-[var(--onboarding-surface)] px-4 py-3">
                <div className="flex items-center justify-between gap-4">
                  <div className="min-w-0 text-start">
                    <p className="text-sm font-medium leading-5 text-[var(--onboarding-text-primary)]">
                      {t("onboarding.rehaul.dictationHotkey.activation")}
                    </p>
                    <p className="text-sm leading-5 text-[var(--onboarding-text-secondary)]">
                      {t(
                        activationMode === "push"
                          ? "onboarding.activation.holdDescription"
                          : "onboarding.activation.tapDescription"
                      )}
                    </p>
                  </div>
                  <ActivationModeSelector
                    variant="onboarding"
                    value={activationMode}
                    onChange={setActivationMode}
                    pushDisabledReason={pushToTalkUnavailableReason ?? undefined}
                  />
                </div>
                {/* Denied input access gets the setup box below instead. */}
                {pushToTalkUnavailableReason && !linuxInputAccessDenied && (
                  <p className="mt-2 text-start text-xs leading-[1.4] text-[var(--onboarding-text-secondary)]">
                    {pushToTalkUnavailableReason}
                  </p>
                )}
                {platform === "linux" && (activationMode === "push" || linuxInputAccessDenied) && (
                  <LinuxPttSetupInfo isAvailable={!linuxInputAccessDenied} />
                )}
              </div>
            )}
          </div>
        );
      }

      case "dictation-demo":
      case "assistant-demo": {
        const assistant = currentStepId === "assistant-demo";
        const scenario = resolveAssistantDemoScenario({
          calendarConnected: hasConnectedCalendar,
          screenContextActive,
        });
        const hotkeyInstruction = formatHotkeyInstruction(
          assistant ? assistantHotkey : dictationHotkey
        );
        const description = t(
          assistant
            ? `onboarding.rehaul.assistantDemo.scenarios.${scenario}.description`
            : activationMode === "push"
              ? "onboarding.activation.holdHotkey"
              : "onboarding.rehaul.dictationDemo.description",
          // Formatted for reading: the raw accelerator would show internal
          // syntax like "GLOBE" or "CommandOrControl+Shift+Space".
          { hotkey: hotkeyInstruction }
        );
        return (
          <div className="h-full w-full pt-2">
            <OnboardingStepHeader
              title={t(
                assistant
                  ? "onboarding.rehaul.assistantDemo.title"
                  : "onboarding.rehaul.dictationDemo.title"
              )}
              // The assistant demo's card is tall, so its title runs one line.
              titleLines={
                assistant
                  ? undefined
                  : [
                      t("onboarding.rehaul.dictationDemo.titleLineOne"),
                      t("onboarding.rehaul.dictationDemo.titleLineTwo"),
                    ]
              }
              wideTitle={assistant}
              description={<DemoHotkeyDescription text={description} hotkey={hotkeyInstruction} />}
            />
            <DemoStep
              kind={assistant ? "assistant" : "dictation"}
              initialSuccessful={assistant ? assistantDemoSuccess : dictationDemoSuccess}
              firstMessage={t(
                assistant
                  ? "onboarding.rehaul.assistantDemo.email.body"
                  : "onboarding.rehaul.dictationDemo.founder"
              )}
              secondMessage={t(
                assistant
                  ? `onboarding.rehaul.assistantDemo.scenarios.${scenario}.prompt`
                  : "onboarding.rehaul.dictationDemo.prompt"
              )}
              placeholder={t("onboarding.rehaul.dictationDemo.placeholder")}
              listeningLabel={t("onboarding.rehaul.demo.listening")}
              processingLabel={t("onboarding.rehaul.demo.processing")}
              stopLabel={t("onboarding.rehaul.demo.stop")}
              retryLabel={t("common.retry")}
              onSuccessChange={assistant ? setAssistantDemoSuccess : setDictationDemoSuccess}
            />
          </div>
        );
      }

      case "notes":
        return (
          // Compact centred column; the calendar body owns short-window scrolling.
          <div className="flex h-full min-h-0 w-full flex-col items-center gap-5 pt-1">
            <header className="flex w-full shrink-0 flex-col items-center gap-3 text-center">
              <h1 className="onboarding-display-title text-[var(--onboarding-text-primary)]">
                <span className="block">{t("onboarding.rehaul.notes.titleLineOne")}</span>
                <span className="block">
                  {t("onboarding.rehaul.notes.titleLineTwoPrefix")}{" "}
                  {/* Caveat sits at the same 40px as the Inter run, per the spec. */}
                  <span className="brand-script">
                    {t("onboarding.rehaul.notes.titleLineTwoBrand")}
                  </span>
                </span>
              </h1>
              <p className="w-full max-w-xs text-sm leading-[1.5] text-[var(--onboarding-text-secondary)]">
                {t("onboarding.rehaul.notes.description")}
              </p>
            </header>
            {/* The hero panel and the connector list are both fixed-height, so on
                a short window they run past the footer. The shell never scrolls,
                so the content scrolls here instead — px-1/pb-1 keeps focus rings
                off the clip edge. */}
            <div className="onboarding-shell-scroll min-h-0 w-full flex-1 overflow-y-auto px-1 pb-1">
              <CalendarConnectionsStep />
            </div>
          </div>
        );

      case "setup-choice":
        return (
          <div className="h-full w-full pt-2">
            <OnboardingStepHeader
              title={t("onboarding.rehaul.setupChoice.title")}
              titleLines={[
                t("onboarding.rehaul.setupChoice.titleLineOne"),
                t("onboarding.rehaul.setupChoice.titleLineTwo"),
              ]}
              description={t("onboarding.rehaul.setupChoice.description")}
            />
            <SetupChoiceStep
              isSignedIn={isSignedIn}
              agentAllowed={agentAllowed}
              onSelect={(mode, options) => void handleSetupSelection(mode, options)}
              onRequestAuthentication={() => {
                setSetupMode("cloud");
                setAuthPath(null);
                goTo("auth");
              }}
            />
          </div>
        );

      case "byok-dictation":
      case "byok-assistant":
        return (
          <div className="h-full w-full pt-2">
            <div>
              <OnboardingStepHeader
                title={t("onboarding.rehaul.provider.title")}
                description={t("onboarding.rehaul.provider.description")}
                descriptionLines={[
                  t("onboarding.rehaul.provider.descriptionLineOne"),
                  t("onboarding.rehaul.provider.descriptionLineTwo"),
                ]}
                wideTitle
              />
            </div>
            <ByokProviderStep
              key={currentStepId}
              stepId={currentStepId}
              selfHostedRequested={session.selfHostedRequested}
              onSelfHostedChange={setSelfHostedRequested}
              onConnectionChange={setStageReady}
              onProceed={() => void continueFromCurrentStep()}
              resumeState={session.resume.byok[currentStepId]}
              onResumeStateChange={updateCurrentByokDraft}
            />
          </div>
        );

      case "local-dictation":
      case "local-assistant":
        return (
          <div className="h-full w-full pt-2">
            <OnboardingStepHeader
              title={t("onboarding.rehaul.local.title")}
              // Without this the h1 is capped at max-w-xs (320px), which wraps
              // "Set up local models" onto a second line at 40px.
              wideTitle
              description={t("onboarding.rehaul.local.description")}
              descriptionLines={[
                t("onboarding.rehaul.local.descriptionLineOne"),
                t("onboarding.rehaul.local.descriptionLineTwo"),
              ]}
            />
            <LocalModelSetupStep
              key={currentStepId}
              stepId={currentStepId}
              onReadinessChange={setStageReady}
              onProceed={() => void continueFromCurrentStep()}
              onSkip={() => void skipLocalSetup()}
              resumeState={session.resume.localModels[currentStepId]}
              onResumeStateChange={updateCurrentLocalModelDraft}
            />
          </div>
        );
    }
  };

  const hasShellNavigation = !compact;
  const hotkeyStep = currentStepId === "dictation-hotkey" || currentStepId === "assistant-hotkey";
  const demoStep = currentStepId === "dictation-demo" || currentStepId === "assistant-demo";
  const notesStep = currentStepId === "notes";
  const inlineGatedStep = hotkeyStep || demoStep;
  const choiceStep = currentStepId === "setup-choice";
  const inlineProviderStep =
    currentStepId === "byok-dictation" ||
    currentStepId === "byok-assistant" ||
    currentStepId === "local-dictation" ||
    currentStepId === "local-assistant";
  // Choice/provider pages own their forward action. Hotkey/demo pages withhold
  // Continue until complete; Notes does the same until a calendar is connected.
  const showsContinue =
    hasShellNavigation &&
    !choiceStep &&
    !inlineProviderStep &&
    (!inlineGatedStep || canContinue || setupDecisionPending) &&
    (!notesStep || notesFooterAction !== "skip");
  // Practice remains skippable if it cannot complete. Calendar connections are
  // optional, so Notes starts with Skip and replaces it with Continue on connect.
  // While the setup decision is pending, a disabled Continue stands in for Skip.
  const showsSkip =
    !setupDecisionPending &&
    ((demoStep && !canContinue) || (notesStep && notesFooterAction === "skip"));

  return (
    <>
      <OnboardingShell
        compact={compact}
        stepKey={currentStepId}
        // History is the only Back gate. This preserves the branch's provider
        // escape path and also lets users return from setup choice/languages.
        // The required-models step is the exception: it is an org-mandated
        // blocker, so backing out of it (to auth) is suppressed.
        onBack={
          hasShellNavigation && session.history.length > 0 && currentStepId !== "required-models"
            ? goBack
            : undefined
        }
        onContinue={showsContinue ? () => void continueFromCurrentStep() : undefined}
        // Demos are optional practice, and calendar connections on Notes are
        // optional setup. Both advance through the same persisted route.
        onSkip={showsSkip ? () => void continueFromCurrentStep() : undefined}
        continueLabel={
          currentStepId === "use-cases"
            ? t("onboarding.useCase.proceedToSetup")
            : t("common.continue")
        }
        skipLabel={t("common.skip")}
        continueDisabled={!canContinue}
        continueLoading={isFinishing || isRegistering || setupDecisionPending}
        progress={getOnboardingProgress(currentStepId, route)}
        // Label Back only when it is the sole footer action. Unlike the source
        // commit, this branch also has demo Skip, so Back stays icon-only there.
        showBackLabel={!showsContinue && !showsSkip}
      >
        {fatalError && (
          <div
            role="alert"
            className="fixed left-1/2 top-14 z-40 flex -translate-x-1/2 items-center gap-2 rounded-full border border-destructive/20 bg-card px-4 py-2 text-sm text-destructive shadow-lg"
          >
            <AlertCircle className="size-4" />
            {fatalError}
          </div>
        )}
        {renderStep()}
      </OnboardingShell>

      <AlertDialog
        open={permissionAlert !== null}
        onOpenChange={(open) => !open && setPermissionAlert(null)}
        title={permissionAlert?.title ?? ""}
        description={permissionAlert?.description}
        onOk={() => setPermissionAlert(null)}
      />
    </>
  );
}