Shorten onbaording (#5198)

Also added `enableDesktopInstallSlide` flag in `settings.yml` to hide the download for desktop page in the onboarding. --------- Co-authored-by: James Brunton <[email protected]>
2026-07-16 19:33:11 +02:00 · 2025-12-15 09:31:41 +00:00
parent 371d816ce7
commit 0064c1866e
33 changed files with 948 additions and 475 deletions
@@ -47,11 +47,11 @@ export function SlideButtons({ slideDefinition, licenseNotice, flowState, onActi
    ) {
      return t('onboarding.serverLicense.upgrade', 'Upgrade now →');
    }
-    
+
    // Translate the label (it's a translation key)
    const label = button.label ?? '';
    if (!label) return '';
-    
+
    // Extract fallback text from translation key (e.g., 'onboarding.buttons.next' -> 'Next')
    const fallback = label.split('.').pop() || label;
    return t(label, fallback);
@@ -105,4 +105,4 @@ export function SlideButtons({ slideDefinition, licenseNotice, flowState, onActi
      <Group gap={12}>{rightButtons.map(renderButton)}</Group>
    </Group>
  );
-}
+}
@@ -5,7 +5,6 @@ import { useNavigate, useLocation } from 'react-router-dom';
 import { isAuthRoute } from '@app/constants/routes';
 import { dispatchTourState } from '@app/constants/events';
 import { useOnboardingOrchestrator } from '@app/components/onboarding/orchestrator/useOnboardingOrchestrator';
-import { markStepSeen } from '@app/components/onboarding/orchestrator/onboardingStorage';
 import { useBypassOnboarding } from '@app/components/onboarding/useBypassOnboarding';
 import OnboardingTour, { type AdvanceArgs, type CloseArgs } from '@app/components/onboarding/OnboardingTour';
 import OnboardingModalSlide from '@app/components/onboarding/OnboardingModalSlide';
@@ -20,10 +19,12 @@ import { useTourOrchestration } from '@app/contexts/TourOrchestrationContext';
 import { useAdminTourOrchestration } from '@app/contexts/AdminTourOrchestrationContext';
 import { createUserStepsConfig } from '@app/components/onboarding/userStepsConfig';
 import { createAdminStepsConfig } from '@app/components/onboarding/adminStepsConfig';
+import { createWhatsNewStepsConfig } from '@app/components/onboarding/whatsNewStepsConfig';
 import { removeAllGlows } from '@app/components/onboarding/tourGlow';
 import { useFilesModalContext } from '@app/contexts/FilesModalContext';
 import { useServerExperience } from '@app/hooks/useServerExperience';
-import AdminAnalyticsChoiceModal from '@app/components/shared/AdminAnalyticsChoiceModal';
+import { useAppConfig } from '@app/contexts/AppConfigContext';
+import apiClient from '@app/services/apiClient';
 import '@app/components/onboarding/OnboardingTour.css';

 export default function Onboarding() {
@@ -39,6 +40,11 @@ export default function Onboarding() {
  const { osInfo, osOptions, setSelectedDownloadUrl, handleDownloadSelected } = useOnboardingDownload();
  const { showLicenseSlide, licenseNotice: externalLicenseNotice, closeLicenseSlide } = useServerLicenseRequest();
  const { tourRequested: externalTourRequested, requestedTourType, clearTourRequest } = useTourRequest();
+  const { config, refetch: refetchConfig } = useAppConfig();
+  const [analyticsError, setAnalyticsError] = useState<string | null>(null);
+  const [analyticsLoading, setAnalyticsLoading] = useState(false);
+  const [showAnalyticsModal, setShowAnalyticsModal] = useState(false);
+  const [analyticsModalDismissed, setAnalyticsModalDismissed] = useState(false);

  const handleRoleSelect = useCallback((role: 'admin' | 'user' | null) => {
    actions.updateRuntimeState({ selectedRole: role });
@@ -50,7 +56,34 @@ export default function Onboarding() {
    window.location.href = '/login';
  }, [actions]);

-  const handleButtonAction = useCallback((action: ButtonAction) => {
+  // Check if we should show analytics modal before onboarding
+  useEffect(() => {
+    if (!isLoading && !analyticsModalDismissed && serverExperience.effectiveIsAdmin && config?.enableAnalytics == null) {
+      setShowAnalyticsModal(true);
+    }
+  }, [isLoading, analyticsModalDismissed, serverExperience.effectiveIsAdmin, config?.enableAnalytics]);
+
+  const handleAnalyticsChoice = useCallback(async (enableAnalytics: boolean) => {
+    if (analyticsLoading) return;
+    setAnalyticsLoading(true);
+    setAnalyticsError(null);
+
+    try {
+      const formData = new FormData();
+      formData.append('enabled', enableAnalytics.toString());
+
+      await apiClient.post('/api/v1/settings/update-enable-analytics', formData);
+      await refetchConfig();
+      setShowAnalyticsModal(false);
+      setAnalyticsModalDismissed(true);
+      setAnalyticsLoading(false);
+    } catch (error) {
+      setAnalyticsError(error instanceof Error ? error.message : 'Unknown error');
+      setAnalyticsLoading(false);
+    }
+  }, [analyticsLoading, refetchConfig]);
+
+  const handleButtonAction = useCallback(async (action: ButtonAction) => {
    switch (action) {
      case 'next':
      case 'complete-close':
@@ -69,35 +102,43 @@ export default function Onboarding() {
      case 'security-next':
        if (!runtimeState.selectedRole) return;
        if (runtimeState.selectedRole !== 'admin') {
-          actions.updateRuntimeState({ tourRequested: true, tourType: 'tools' });
+          actions.updateRuntimeState({ tourType: 'whatsnew' });
+          setIsTourOpen(true);
        }
        actions.complete();
        break;
      case 'launch-admin':
-        actions.updateRuntimeState({ tourRequested: true, tourType: 'admin' });
-        actions.complete();
+        actions.updateRuntimeState({ tourType: 'admin' });
+        setIsTourOpen(true);
        break;
      case 'launch-tools':
-        actions.updateRuntimeState({ tourRequested: true, tourType: 'tools' });
-        actions.complete();
+        actions.updateRuntimeState({ tourType: 'whatsnew' });
+        setIsTourOpen(true);
        break;
      case 'launch-auto': {
-        const tourType = serverExperience.effectiveIsAdmin || runtimeState.selectedRole === 'admin' ? 'admin' : 'tools';
-        actions.updateRuntimeState({ tourRequested: true, tourType });
-        actions.complete();
+        const tourType = serverExperience.effectiveIsAdmin || runtimeState.selectedRole === 'admin' ? 'admin' : 'whatsnew';
+        actions.updateRuntimeState({ tourType });
+        setIsTourOpen(true);
        break;
      }
      case 'skip-to-license':
-        markStepSeen('tour');
-        actions.updateRuntimeState({ tourRequested: false });
+        actions.complete();
+        break;
+      case 'skip-tour':
        actions.complete();
        break;
      case 'see-plans':
        actions.complete();
        navigate('/settings/adminPlan');
        break;
+      case 'enable-analytics':
+        await handleAnalyticsChoice(true);
+        break;
+      case 'disable-analytics':
+        await handleAnalyticsChoice(false);
+        break;
    }
-  }, [actions, handleDownloadSelected, navigate, runtimeState.selectedRole, serverExperience.effectiveIsAdmin]);
+  }, [actions, handleAnalyticsChoice, handleDownloadSelected, navigate, runtimeState.selectedRole, serverExperience.effectiveIsAdmin]);

  const isRTL = typeof document !== 'undefined' ? document.documentElement.dir === 'rtl' : false;
  const [isTourOpen, setIsTourOpen] = useState(false);
@@ -117,10 +158,7 @@ export default function Onboarding() {
        backToAllTools: tourOrch.backToAllTools,
        selectCropTool: tourOrch.selectCropTool,
        loadSampleFile: tourOrch.loadSampleFile,
-        switchToViewer: tourOrch.switchToViewer,
-        switchToPageEditor: tourOrch.switchToPageEditor,
        switchToActiveFiles: tourOrch.switchToActiveFiles,
-        selectFirstFile: tourOrch.selectFirstFile,
        pinFile: tourOrch.pinFile,
        modifyCropSettings: tourOrch.modifyCropSettings,
        executeTool: tourOrch.executeTool,
@@ -130,6 +168,24 @@ export default function Onboarding() {
    [t, tourOrch, closeFilesModal, openFilesModal]
  );

+  const whatsNewStepsConfig = useMemo(
+    () => createWhatsNewStepsConfig({
+      t,
+      actions: {
+        saveWorkbenchState: tourOrch.saveWorkbenchState,
+        closeFilesModal,
+        backToAllTools: tourOrch.backToAllTools,
+        openFilesModal,
+        loadSampleFile: tourOrch.loadSampleFile,
+        switchToViewer: tourOrch.switchToViewer,
+        switchToPageEditor: tourOrch.switchToPageEditor,
+        switchToActiveFiles: tourOrch.switchToActiveFiles,
+        selectFirstFile: tourOrch.selectFirstFile,
+      },
+    }),
+    [t, tourOrch, closeFilesModal, openFilesModal]
+  );
+
  const adminStepsConfig = useMemo(
    () => createAdminStepsConfig({
      t,
@@ -144,21 +200,19 @@ export default function Onboarding() {
  );

  const tourSteps = useMemo<StepType[]>(() => {
-    const config = runtimeState.tourType === 'admin' ? adminStepsConfig : userStepsConfig;
-    return Object.values(config);
-  }, [adminStepsConfig, runtimeState.tourType, userStepsConfig]);
-
-  useEffect(() => {
-    if (currentStep?.id === 'tour' && !isTourOpen) {
-      markStepSeen('tour');
-      setIsTourOpen(true);
+    switch (runtimeState.tourType) {
+      case 'admin':
+        return Object.values(adminStepsConfig);
+      case 'whatsnew':
+        return Object.values(whatsNewStepsConfig);
+      default:
+        return Object.values(userStepsConfig);
    }
-  }, [currentStep, isTourOpen, activeFlow]);
+  }, [adminStepsConfig, runtimeState.tourType, userStepsConfig, whatsNewStepsConfig]);

  useEffect(() => {
    if (externalTourRequested) {
-      actions.updateRuntimeState({ tourRequested: true, tourType: requestedTourType });
-      markStepSeen('tour');
+      actions.updateRuntimeState({ tourType: requestedTourType });
      setIsTourOpen(true);
      clearTourRequest();
    }
@@ -176,9 +230,9 @@ export default function Onboarding() {
    } else {
      tourOrch.restoreWorkbenchState();
    }
-    markStepSeen('tour');
-    if (currentStep?.id === 'tour') actions.complete();
-  }, [actions, adminTourOrch, currentStep?.id, runtimeState.tourType, tourOrch]);
+    // Advance to next onboarding step after tour completes
+    actions.complete();
+  }, [actions, adminTourOrch, runtimeState.tourType, tourOrch]);

  const handleAdvanceTour = useCallback((args: AdvanceArgs) => {
    const { setCurrentStep, currentStep: tourCurrentStep, steps, setIsOpen } = args;
@@ -216,8 +270,10 @@ export default function Onboarding() {
      firstLoginUsername: runtimeState.firstLoginUsername,
      onPasswordChanged: handlePasswordChanged,
      usingDefaultCredentials: runtimeState.usingDefaultCredentials,
+      analyticsError,
+      analyticsLoading,
    });
-  }, [currentSlideDefinition, osInfo, osOptions, runtimeState.selectedRole, runtimeState.licenseNotice, handleRoleSelect, serverExperience.loginEnabled, setSelectedDownloadUrl, runtimeState.firstLoginUsername, handlePasswordChanged]);
+  }, [analyticsError, analyticsLoading, currentSlideDefinition, osInfo, osOptions, runtimeState.selectedRole, runtimeState.licenseNotice, handleRoleSelect, serverExperience.loginEnabled, setSelectedDownloadUrl, runtimeState.firstLoginUsername, handlePasswordChanged]);

  const modalSlideCount = useMemo(() => {
    return activeFlow.filter((step) => step.type === 'modal-slide').length;
@@ -237,8 +293,45 @@ export default function Onboarding() {
    return null;
  }

+  // Show analytics modal before onboarding if needed
+  if (showAnalyticsModal) {
+    const slideDefinition = SLIDE_DEFINITIONS['analytics-choice'];
+    const slideContent = slideDefinition.createSlide({
+      osLabel: '',
+      osUrl: '',
+      selectedRole: null,
+      onRoleSelect: () => {},
+      analyticsError,
+      analyticsLoading,
+    });
+
+    return (
+      <OnboardingModalSlide
+        slideDefinition={slideDefinition}
+        slideContent={slideContent}
+        runtimeState={runtimeState}
+        modalSlideCount={1}
+        currentModalSlideIndex={0}
+        onSkip={() => {}} // No skip allowed
+        onAction={async (action) => {
+          if (action === 'enable-analytics') {
+            await handleAnalyticsChoice(true);
+          } else if (action === 'disable-analytics') {
+            await handleAnalyticsChoice(false);
+          }
+        }}
+        allowDismiss={false}
+      />
+    );
+  }
+
  if (showLicenseSlide) {
-    const slideDefinition = SLIDE_DEFINITIONS['server-license'];
+    const baseSlideDefinition = SLIDE_DEFINITIONS['server-license'];
+    // Remove back button for external license notice
+    const slideDefinition = {
+      ...baseSlideDefinition,
+      buttons: baseSlideDefinition.buttons.filter(btn => btn.key !== 'license-back')
+    };
    const effectiveLicenseNotice = externalLicenseNotice || runtimeState.licenseNotice;
    const slideContent = slideDefinition.createSlide({
      osLabel: '',
@@ -250,7 +343,7 @@ export default function Onboarding() {
      licenseNotice: effectiveLicenseNotice,
      loginEnabled: serverExperience.loginEnabled,
    });
-    
+
    return (
      <OnboardingModalSlide
        slideDefinition={slideDefinition}
@@ -271,40 +364,34 @@ export default function Onboarding() {
    );
  }

+  // Always render the tour component (it controls its own visibility with isOpen)
+  const tourComponent = (
+    <OnboardingTour
+      isOpen={isTourOpen}
+      tourSteps={tourSteps}
+      tourType={runtimeState.tourType}
+      isRTL={isRTL}
+      t={t}
+      onAdvance={handleAdvanceTour}
+      onClose={handleCloseTour}
+    />
+  );
+
+  // If no active onboarding, just show the tour (which may or may not be open)
  if (isLoading || !isActive || !currentStep) {
-    return (
-      <OnboardingTour
-        isOpen={isTourOpen}
-        tourSteps={tourSteps}
-        tourType={runtimeState.tourType}
-        isRTL={isRTL}
-        t={t}
-        onAdvance={handleAdvanceTour}
-        onClose={handleCloseTour}
-      />
-    );
+    return tourComponent;
  }

+  // If tour is open, hide the onboarding modal and just show the tour
+  if (isTourOpen) {
+    return tourComponent;
+  }
+
+  // Render the current onboarding step
  switch (currentStep.type) {
    case 'tool-prompt':
      return <ToolPanelModePrompt forceOpen={true} onComplete={actions.complete} />;

-    case 'tour':
-      return (
-        <OnboardingTour
-          isOpen={true}
-          tourSteps={tourSteps}
-          tourType={runtimeState.tourType}
-          isRTL={isRTL}
-          t={t}
-          onAdvance={handleAdvanceTour}
-          onClose={handleCloseTour}
-        />
-      );
-
-    case 'analytics-modal':
-      return <AdminAnalyticsChoiceModal opened={true} onClose={actions.complete} />;
-
    case 'modal-slide':
      if (!currentSlideDefinition || !currentSlideContent) return null;
      return (
@@ -6,8 +6,9 @@
 */

 import React from 'react';
-import { Modal, Stack } from '@mantine/core';
+import { Modal, Stack, ActionIcon } from '@mantine/core';
 import DiamondOutlinedIcon from '@mui/icons-material/DiamondOutlined';
+import CloseIcon from '@mui/icons-material/Close';

 import type { SlideDefinition, ButtonAction } from '@app/components/onboarding/onboardingFlowConfig';
 import type { OnboardingRuntimeState } from '@app/components/onboarding/orchestrator/onboardingConfig';
@@ -28,6 +29,7 @@ interface OnboardingModalSlideProps {
  currentModalSlideIndex: number;
  onSkip: () => void;
  onAction: (action: ButtonAction) => void;
+  allowDismiss?: boolean;
 }

 export default function OnboardingModalSlide({
@@ -38,6 +40,7 @@ export default function OnboardingModalSlide({
  currentModalSlideIndex,
  onSkip,
  onAction,
+  allowDismiss = true,
 }: OnboardingModalSlideProps) {

  const renderHero = () => {
@@ -62,6 +65,9 @@ export default function OnboardingModalSlide({
        {slideDefinition.hero.type === 'lock' && (
          <LocalIcon icon="lock-outline" width={64} height={64} className={styles.heroIcon} />
        )}
+        {slideDefinition.hero.type === 'analytics' && (
+          <LocalIcon icon="analytics" width={64} height={64} className={styles.heroIcon} />
+        )}
        {slideDefinition.hero.type === 'diamond' && <DiamondOutlinedIcon sx={{ fontSize: 64, color: '#000000' }} />}
        {slideDefinition.hero.type === 'logo' && (
          <img src={`${BASE_PATH}/branding/StirlingPDFLogoNoTextLightHC.svg`} alt="Stirling logo" />
@@ -75,6 +81,7 @@ export default function OnboardingModalSlide({
      opened={true}
      onClose={onSkip}
      closeOnClickOutside={false}
+      closeOnEscape={allowDismiss}
      centered
      size="lg"
      radius="lg"
@@ -93,6 +100,31 @@ export default function OnboardingModalSlide({
            isActive
            slideKey={slideContent.key}
          />
+          {allowDismiss && (
+            <ActionIcon
+              onClick={onSkip}
+              radius="md"
+              size={36}
+              style={{
+                position: 'absolute',
+                top: 16,
+                right: 16,
+                backgroundColor: 'rgba(255, 255, 255, 0.2)',
+                color: 'white',
+                backdropFilter: 'blur(4px)',
+                zIndex: 10,
+              }}
+              styles={{
+                root: {
+                  '&:hover': {
+                    backgroundColor: 'rgba(255, 255, 255, 0.3)',
+                  },
+                },
+              }}
+            >
+              <CloseIcon fontSize="small" />
+            </ActionIcon>
+          )}
          <div className={styles.heroLogo} key={`logo-${slideContent.key}`}>
            {renderHero()}
          </div>
@@ -114,7 +146,9 @@ export default function OnboardingModalSlide({
              <style>{`div strong{color: var(--onboarding-title); font-weight: 600;}`}</style>
            </div>

-            <OnboardingStepper totalSteps={modalSlideCount} activeStep={currentModalSlideIndex} />
+            {modalSlideCount > 1 && (
+              <OnboardingStepper totalSteps={modalSlideCount} activeStep={currentModalSlideIndex} />
+            )}

            <div className={styles.buttonContainer}>
              <SlideButtons
@@ -49,7 +49,7 @@ interface CloseArgs {

 interface OnboardingTourProps {
  tourSteps: StepType[];
-  tourType: 'admin' | 'tools';
+  tourType: 'admin' | 'tools' | 'whatsnew';
  isRTL: boolean;
  t: TFunction;
  isOpen: boolean;
@@ -4,6 +4,8 @@ import SecurityCheckSlide from '@app/components/onboarding/slides/SecurityCheckS
 import PlanOverviewSlide from '@app/components/onboarding/slides/PlanOverviewSlide';
 import ServerLicenseSlide from '@app/components/onboarding/slides/ServerLicenseSlide';
 import FirstLoginSlide from '@app/components/onboarding/slides/FirstLoginSlide';
+import TourOverviewSlide from '@app/components/onboarding/slides/TourOverviewSlide';
+import AnalyticsChoiceSlide from '@app/components/onboarding/slides/AnalyticsChoiceSlide';
 import { SlideConfig, LicenseNotice } from '@app/types/types';

 export type SlideId =
@@ -12,9 +14,11 @@ export type SlideId =
  | 'desktop-install'
  | 'security-check'
  | 'admin-overview'
-  | 'server-license';
+  | 'server-license'
+  | 'tour-overview'
+  | 'analytics-choice';

-export type HeroType = 'rocket' | 'dual-icon' | 'shield' | 'diamond' | 'logo' | 'lock';
+export type HeroType = 'rocket' | 'dual-icon' | 'shield' | 'diamond' | 'logo' | 'lock' | 'analytics';

 export type ButtonAction =
  | 'next'
@@ -27,7 +31,10 @@ export type ButtonAction =
  | 'launch-tools'
  | 'launch-auto'
  | 'see-plans'
-  | 'skip-to-license';
+  | 'skip-to-license'
+  | 'skip-tour'
+  | 'enable-analytics'
+  | 'disable-analytics';

 export interface FlowState {
  selectedRole: 'admin' | 'user' | null;
@@ -52,6 +59,8 @@ export interface SlideFactoryParams {
  firstLoginUsername?: string;
  onPasswordChanged?: () => void;
  usingDefaultCredentials?: boolean;
+  analyticsError?: string | null;
+  analyticsLoading?: boolean;
 }

 export interface HeroDefinition {
@@ -79,9 +88,9 @@ export interface SlideDefinition {
 export const SLIDE_DEFINITIONS: Record<SlideId, SlideDefinition> = {
  'first-login': {
    id: 'first-login',
-    createSlide: ({ firstLoginUsername, onPasswordChanged, usingDefaultCredentials }) => 
-      FirstLoginSlide({ 
-        username: firstLoginUsername || '', 
+    createSlide: ({ firstLoginUsername, onPasswordChanged, usingDefaultCredentials }) =>
+      FirstLoginSlide({
+        username: firstLoginUsername || '',
        onPasswordChanged: onPasswordChanged || (() => {}),
        usingDefaultCredentials: usingDefaultCredentials || false,
      }),
@@ -194,6 +203,13 @@ export const SLIDE_DEFINITIONS: Record<SlideId, SlideDefinition> = {
    createSlide: ({ licenseNotice }) => ServerLicenseSlide({ licenseNotice }),
    hero: { type: 'dual-icon' },
    buttons: [
+      {
+        key: 'license-back',
+        type: 'icon',
+        icon: 'chevron-left',
+        group: 'left',
+        action: 'prev',
+      },
      {
        key: 'license-close',
        type: 'button',
@@ -212,5 +228,58 @@ export const SLIDE_DEFINITIONS: Record<SlideId, SlideDefinition> = {
      },
    ],
  },
+  'tour-overview': {
+    id: 'tour-overview',
+    createSlide: () => TourOverviewSlide(),
+    hero: { type: 'rocket' },
+    buttons: [
+      {
+        key: 'tour-overview-back',
+        type: 'icon',
+        icon: 'chevron-left',
+        group: 'left',
+        action: 'prev',
+      },
+      {
+        key: 'tour-overview-skip',
+        type: 'button',
+        label: 'onboarding.buttons.skipForNow',
+        variant: 'secondary',
+        group: 'left',
+        action: 'skip-tour',
+      },
+      {
+        key: 'tour-overview-show',
+        type: 'button',
+        label: 'onboarding.buttons.showMeAround',
+        variant: 'primary',
+        group: 'right',
+        action: 'launch-tools',
+      },
+    ],
+  },
+  'analytics-choice': {
+    id: 'analytics-choice',
+    createSlide: ({ analyticsError }) => AnalyticsChoiceSlide({ analyticsError }),
+    hero: { type: 'analytics' },
+    buttons: [
+      {
+        key: 'analytics-disable',
+        type: 'button',
+        label: 'no',
+        variant: 'secondary',
+        group: 'left',
+        action: 'disable-analytics',
+      },
+      {
+        key: 'analytics-enable',
+        type: 'button',
+        label: 'yes',
+        variant: 'primary',
+        group: 'right',
+        action: 'enable-analytics',
+      },
+    ],
+  },
 };

@@ -5,21 +5,20 @@ export type OnboardingStepId =
  | 'security-check'
  | 'admin-overview'
  | 'tool-layout'
-  | 'tour'
+  | 'tour-overview'
  | 'server-license'
  | 'analytics-choice';

 export type OnboardingStepType =
  | 'modal-slide'
-  | 'tool-prompt'
-  | 'tour'
-  | 'analytics-modal';
+  | 'tool-prompt';

 export interface OnboardingRuntimeState {
  selectedRole: 'admin' | 'user' | null;
  tourRequested: boolean;
-  tourType: 'admin' | 'tools';
+  tourType: 'admin' | 'tools' | 'whatsnew';
  isDesktopApp: boolean;
+  desktopSlideEnabled: boolean;
  analyticsNotConfigured: boolean;
  analyticsEnabled: boolean;
  licenseNotice: {
@@ -42,13 +41,13 @@ export interface OnboardingStep {
  id: OnboardingStepId;
  type: OnboardingStepType;
  condition: (ctx: OnboardingConditionContext) => boolean;
-  slideId?: 'first-login' | 'welcome' | 'desktop-install' | 'security-check' | 'admin-overview' | 'server-license';
+  slideId?: 'first-login' | 'welcome' | 'desktop-install' | 'security-check' | 'admin-overview' | 'server-license' | 'tour-overview' | 'analytics-choice';
 }

 export const DEFAULT_RUNTIME_STATE: OnboardingRuntimeState = {
  selectedRole: null,
  tourRequested: false,
-  tourType: 'tools',
+  tourType: 'whatsnew',
  isDesktopApp: false,
  analyticsNotConfigured: false,
  analyticsEnabled: false,
@@ -61,6 +60,7 @@ export const DEFAULT_RUNTIME_STATE: OnboardingRuntimeState = {
  requiresPasswordChange: false,
  firstLoginUsername: '',
  usingDefaultCredentials: false,
+  desktopSlideEnabled: true,
 };

 export const ONBOARDING_STEPS: OnboardingStep[] = [
@@ -76,18 +76,6 @@ export const ONBOARDING_STEPS: OnboardingStep[] = [
    slideId: 'welcome',
    condition: () => true,
  },
-  {
-    id: 'desktop-install',
-    type: 'modal-slide',
-    slideId: 'desktop-install',
-    condition: (ctx) => !ctx.isDesktopApp,
-  },
-  {
-    id: 'security-check',
-    type: 'modal-slide',
-    slideId: 'security-check',
-    condition: (ctx) => !ctx.loginEnabled && !ctx.isDesktopApp,
-  },
  {
    id: 'admin-overview',
    type: 'modal-slide',
@@ -95,14 +83,27 @@ export const ONBOARDING_STEPS: OnboardingStep[] = [
    condition: (ctx) => ctx.effectiveIsAdmin,
  },
  {
-    id: 'tool-layout',
-    type: 'tool-prompt',
-    condition: () => true,
+    id: 'desktop-install',
+    type: 'modal-slide',
+    slideId: 'desktop-install',
+    condition: (ctx) => !ctx.isDesktopApp && ctx.desktopSlideEnabled,
  },
  {
-    id: 'tour',
-    type: 'tour',
-    condition: (ctx) => ctx.tourRequested || !ctx.effectiveIsAdmin,
+    id: 'security-check',
+    type: 'modal-slide',
+    slideId: 'security-check',
+    condition: () => false,
+  },
+  {
+    id: 'tool-layout',
+    type: 'tool-prompt',
+    condition: () => false,
+  },
+  {
+    id: 'tour-overview',
+    type: 'modal-slide',
+    slideId: 'tour-overview',
+    condition: (ctx) => !ctx.effectiveIsAdmin && ctx.tourType !== 'admin',
  },
  {
    id: 'server-license',
@@ -110,11 +111,6 @@ export const ONBOARDING_STEPS: OnboardingStep[] = [
    slideId: 'server-license',
    condition: (ctx) => ctx.effectiveIsAdmin && ctx.licenseNotice.requiresLicense,
  },
-  {
-    id: 'analytics-choice',
-    type: 'analytics-modal',
-    condition: (ctx) => ctx.effectiveIsAdmin && ctx.analyticsNotConfigured,
-  },
 ];

 export function getStepById(id: OnboardingStepId): OnboardingStep | undefined {
@@ -1,94 +1,71 @@
-import { type OnboardingStepId, ONBOARDING_STEPS } from '@app/components/onboarding/orchestrator/onboardingConfig';
-
 const STORAGE_PREFIX = 'onboarding';
+const TOURS_TOOLTIP_KEY = `${STORAGE_PREFIX}::tours-tooltip-shown`;
+const ONBOARDING_COMPLETED_KEY = `${STORAGE_PREFIX}::completed`;

-export function getStorageKey(stepId: OnboardingStepId): string {
-  return `${STORAGE_PREFIX}::${stepId}`;
-}
-
-export function hasSeenStep(stepId: OnboardingStepId): boolean {
+export function isOnboardingCompleted(): boolean {
  if (typeof window === 'undefined') return false;
  try {
-    return localStorage.getItem(getStorageKey(stepId)) === 'true';
+    return localStorage.getItem(ONBOARDING_COMPLETED_KEY) === 'true';
  } catch {
    return false;
  }
 }

-export function markStepSeen(stepId: OnboardingStepId): void {
+export function markOnboardingCompleted(): void {
  if (typeof window === 'undefined') return;
  try {
-    localStorage.setItem(getStorageKey(stepId), 'true');
+    localStorage.setItem(ONBOARDING_COMPLETED_KEY, 'true');
  } catch (error) {
-    console.error('[onboardingStorage] Error marking step as seen:', error);
+    console.error('[onboardingStorage] Error marking onboarding as completed:', error);
  }
 }

-export function resetStepSeen(stepId: OnboardingStepId): void {
+export function resetOnboardingProgress(): void {
  if (typeof window === 'undefined') return;
  try {
-    localStorage.removeItem(getStorageKey(stepId));
+    localStorage.removeItem(ONBOARDING_COMPLETED_KEY);
  } catch (error) {
-    console.error('[onboardingStorage] Error resetting step seen:', error);
+    console.error('[onboardingStorage] Error resetting onboarding progress:', error);
  }
 }

-export function resetAllOnboardingProgress(): void {
-  if (typeof window === 'undefined') return;
+export function hasShownToursTooltip(): boolean {
+  if (typeof window === 'undefined') return false;
  try {
-    const prefix = `${STORAGE_PREFIX}::`;
-    const keysToRemove: string[] = [];
-    for (let i = 0; i < localStorage.length; i++) {
-      const key = localStorage.key(i);
-      if (key?.startsWith(prefix)) keysToRemove.push(key);
-    }
-    keysToRemove.forEach((key) => localStorage.removeItem(key));
-  } catch (error) {
-    console.error('[onboardingStorage] Error resetting all onboarding progress:', error);
+    return localStorage.getItem(TOURS_TOOLTIP_KEY) === 'true';
+  } catch {
+    return false;
  }
 }

-export function getOnboardingStorageState(): Record<string, boolean> {
-  const state: Record<string, boolean> = {};
-  ONBOARDING_STEPS.forEach((step) => {
-    state[step.id] = hasSeenStep(step.id);
-  });
-  return state;
+export function markToursTooltipShown(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    localStorage.setItem(TOURS_TOOLTIP_KEY, 'true');
+  } catch (error) {
+    console.error('[onboardingStorage] Error marking tours tooltip as shown:', error);
+  }
 }

 export function migrateFromLegacyPreferences(): void {
  if (typeof window === 'undefined') return;
-  
+
  const migrationKey = `${STORAGE_PREFIX}::migrated`;
-  
+
  try {
    // Skip if already migrated
    if (localStorage.getItem(migrationKey) === 'true') return;
-    
+
    const prefsRaw = localStorage.getItem('stirlingpdf_preferences');
    if (prefsRaw) {
      const prefs = JSON.parse(prefsRaw) as Record<string, unknown>;
-      
-      // Migrate based on legacy flags
-      if (prefs.hasSeenIntroOnboarding === true) {
-        markStepSeen('welcome');
-        markStepSeen('desktop-install');
-        markStepSeen('security-check');
-        markStepSeen('admin-overview');
+
+      // If user had completed onboarding in old system, mark new system as complete
+      if (prefs.hasCompletedOnboarding === true || prefs.hasSeenIntroOnboarding === true) {
+        markOnboardingCompleted();
      }
-      
-      if (prefs.toolPanelModePromptSeen === true || prefs.hasSelectedToolPanelMode === true) {
-        markStepSeen('tool-layout');
-      }
-      
-      if (prefs.hasCompletedOnboarding === true) {
-        markStepSeen('tour');
-        markStepSeen('analytics-choice');
-        markStepSeen('server-license');
-      }
-      
    }
-    
+
    // Mark migration complete
    localStorage.setItem(migrationKey, 'true');
  } catch {
@@ -12,8 +12,8 @@ import {
  DEFAULT_RUNTIME_STATE,
 } from '@app/components/onboarding/orchestrator/onboardingConfig';
 import {
-  hasSeenStep,
-  markStepSeen,
+  isOnboardingCompleted,
+  markOnboardingCompleted,
  migrateFromLegacyPreferences,
 } from '@app/components/onboarding/orchestrator/onboardingStorage';
 import { accountService } from '@app/services/accountService';
@@ -35,12 +35,15 @@ function getInitialRuntimeState(baseState: OnboardingRuntimeState): OnboardingRu
  if (typeof window === 'undefined') {
    return baseState;
  }
-  
+
  try {
    const tourRequested = sessionStorage.getItem(SESSION_TOUR_REQUESTED) === 'true';
-    const tourType = (sessionStorage.getItem(SESSION_TOUR_TYPE) as 'admin' | 'tools') || 'tools';
+    const sessionTourType = sessionStorage.getItem(SESSION_TOUR_TYPE);
+    const tourType = (sessionTourType === 'admin' || sessionTourType === 'tools' || sessionTourType === 'whatsnew')
+      ? sessionTourType
+      : 'whatsnew';
    const selectedRole = sessionStorage.getItem(SESSION_SELECTED_ROLE) as 'admin' | 'user' | null;
-    
+
    return {
      ...baseState,
      tourRequested,
@@ -54,7 +57,7 @@ function getInitialRuntimeState(baseState: OnboardingRuntimeState): OnboardingRu

 function persistRuntimeState(state: Partial<OnboardingRuntimeState>): void {
  if (typeof window === 'undefined') return;
-  
+
  try {
    if (state.tourRequested !== undefined) {
      sessionStorage.setItem(SESSION_TOUR_REQUESTED, state.tourRequested ? 'true' : 'false');
@@ -76,7 +79,7 @@ function persistRuntimeState(state: Partial<OnboardingRuntimeState>): void {

 function clearRuntimeStateSession(): void {
  if (typeof window === 'undefined') return;
-  
+
  try {
    sessionStorage.removeItem(SESSION_TOUR_REQUESTED);
    sessionStorage.removeItem(SESSION_TOUR_TYPE);
@@ -145,7 +148,7 @@ export function useOnboardingOrchestrator(
  const location = useLocation();
  const bypassOnboarding = useBypassOnboarding();

-  const [runtimeState, setRuntimeState] = useState<OnboardingRuntimeState>(() => 
+  const [runtimeState, setRuntimeState] = useState<OnboardingRuntimeState>(() =>
    getInitialRuntimeState(defaultState)
  );
  const [isPaused, setIsPaused] = useState(false);
@@ -166,6 +169,7 @@ export function useOnboardingOrchestrator(
      ...prev,
      analyticsEnabled: config?.enableAnalytics === true,
      analyticsNotConfigured: config?.enableAnalytics == null,
+      desktopSlideEnabled: config?.enableDesktopInstallSlide ?? true,
      licenseNotice: {
        totalUsers: serverExperience.totalUsers,
        freeTierLimit: serverExperience.freeTierLimit,
@@ -221,7 +225,7 @@ export function useOnboardingOrchestrator(
  const conditionContext = useMemo<OnboardingConditionContext>(() => ({
    ...serverExperience,
    ...runtimeState,
-    effectiveIsAdmin: serverExperience.effectiveIsAdmin || 
+    effectiveIsAdmin: serverExperience.effectiveIsAdmin ||
      (!serverExperience.loginEnabled && runtimeState.selectedRole === 'admin'),
  }), [serverExperience, runtimeState]);

@@ -235,53 +239,44 @@ export function useOnboardingOrchestrator(

  // Wait for config AND admin status before calculating initial step
  const adminStatusResolved = !configLoading && (
-    config?.enableLogin === false || 
-    config?.enableLogin === undefined || 
+    config?.enableLogin === false ||
+    config?.enableLogin === undefined ||
    config?.isAdmin !== undefined
  );
-  
+
  useEffect(() => {
-    if (configLoading || !adminStatusResolved || activeFlow.length === 0) return;
+    if (configLoading || !adminStatusResolved) return;

-    let firstUnseenIndex = -1;
-    for (let i = 0; i < activeFlow.length; i++) {
-      // Special case: first-login step should always be considered "unseen" if requiresPasswordChange is true
-      const isFirstLoginStep = activeFlow[i].id === 'first-login';
-      const shouldTreatAsUnseen = isFirstLoginStep ? runtimeState.requiresPasswordChange : !hasSeenStep(activeFlow[i].id);
-
-      if (shouldTreatAsUnseen) {
-        firstUnseenIndex = i;
-        break;
-      }
-    }
-
-    // Force reset index when password change is required (overrides initialIndexSet)
-    if (runtimeState.requiresPasswordChange && firstUnseenIndex === 0) {
+    // If there are no steps to show, mark initialized/completed baseline
+    if (activeFlow.length === 0) {
      setCurrentStepIndex(0);
      initialIndexSet.current = true;
-    } else if (firstUnseenIndex === -1) {
+      return;
+    }
+
+    // If onboarding has been completed, don't show it
+    if (isOnboardingCompleted() && !runtimeState.requiresPasswordChange) {
      setCurrentStepIndex(activeFlow.length);
      initialIndexSet.current = true;
-    } else if (!initialIndexSet.current) {
-      setCurrentStepIndex(firstUnseenIndex);
+      return;
+    }
+
+    // Start from the beginning
+    if (!initialIndexSet.current) {
+      setCurrentStepIndex(0);
      initialIndexSet.current = true;
    }
  }, [activeFlow, configLoading, adminStatusResolved, runtimeState.requiresPasswordChange]);

  const totalSteps = activeFlow.length;
-  
-  const allStepsAlreadySeen = useMemo(() => {
-    if (activeFlow.length === 0) return false;
-    return activeFlow.every(step => hasSeenStep(step.id));
-  }, [activeFlow]);
-  
-  const isComplete = isInitialized && initialIndexSet.current && 
-    (currentStepIndex >= totalSteps || allStepsAlreadySeen);
-  const currentStep = (currentStepIndex >= 0 && currentStepIndex < totalSteps && !allStepsAlreadySeen) 
-    ? activeFlow[currentStepIndex] 
+
+  const isComplete = isInitialized &&
+    (totalSteps === 0 || currentStepIndex >= totalSteps || isOnboardingCompleted());
+  const currentStep = (currentStepIndex >= 0 && currentStepIndex < totalSteps)
+    ? activeFlow[currentStepIndex]
    : null;
  const isActive = !shouldBlockOnboarding && !isPaused && !isComplete && isInitialized && currentStep !== null;
-  const isLoading = configLoading || !adminStatusResolved || !isInitialized || 
+  const isLoading = configLoading || !adminStatusResolved || !isInitialized ||
    !initialIndexSet.current || (currentStepIndex === -1 && activeFlow.length > 0);

  useEffect(() => {
@@ -293,35 +288,33 @@ export function useOnboardingOrchestrator(
  }, [isComplete]);

  const next = useCallback(() => {
-    if (currentStep) markStepSeen(currentStep.id);
-    setCurrentStepIndex((prev) => Math.min(prev + 1, totalSteps));
-  }, [currentStep, totalSteps]);
+    const nextIndex = currentStepIndex + 1;
+    if (nextIndex >= totalSteps) {
+      // Reached the end, mark onboarding as completed
+      markOnboardingCompleted();
+    }
+    setCurrentStepIndex(nextIndex);
+  }, [currentStepIndex, totalSteps]);

  const prev = useCallback(() => {
    setCurrentStepIndex((prev) => Math.max(prev - 1, 0));
  }, []);

  const skip = useCallback(() => {
-    if (currentStep) markStepSeen(currentStep.id);
-    setCurrentStepIndex((prev) => Math.min(prev + 1, totalSteps));
-  }, [currentStep, totalSteps]);
+    // Skip marks the entire onboarding as completed
+    markOnboardingCompleted();
+    setCurrentStepIndex(totalSteps);
+  }, [totalSteps]);

  const complete = useCallback(() => {
-    if (currentStep) markStepSeen(currentStep.id);
-    setCurrentStepIndex((prev) => Math.min(prev + 1, totalSteps));
-  }, [currentStep, totalSteps]);
-
-  useEffect(() => {
-    if (!currentStep || isLoading) {
-      return;
+    const nextIndex = currentStepIndex + 1;
+    if (nextIndex >= totalSteps) {
+      // Reached the end, mark onboarding as completed
+      markOnboardingCompleted();
    }
-    // Special case: never auto-complete first-login step if requiresPasswordChange is true
-    const isFirstLoginStep = currentStep.id === 'first-login';
+    setCurrentStepIndex(nextIndex);
+  }, [currentStepIndex, totalSteps]);

-    if (!isFirstLoginStep && hasSeenStep(currentStep.id)) {
-      complete();
-    }
-  }, [currentStep, isLoading, complete, runtimeState.requiresPasswordChange]);

  const updateRuntimeState = useCallback((updates: Partial<OnboardingRuntimeState>) => {
    persistRuntimeState(updates);
@@ -0,0 +1,55 @@
+import React from 'react';
+import { Trans } from 'react-i18next';
+import { Button } from '@mantine/core';
+import OpenInNewIcon from '@mui/icons-material/OpenInNew';
+import i18n from '@app/i18n';
+import { SlideConfig } from '@app/types/types';
+import { UNIFIED_CIRCLE_CONFIG } from '@app/components/onboarding/slides/unifiedBackgroundConfig';
+import styles from '@app/components/onboarding/InitialOnboardingModal/InitialOnboardingModal.module.css';
+
+interface AnalyticsChoiceSlideProps {
+  analyticsError?: string | null;
+}
+
+export default function AnalyticsChoiceSlide({ analyticsError }: AnalyticsChoiceSlideProps): SlideConfig {
+  return {
+    key: 'analytics-choice',
+    title: i18n.t('analytics.title', 'Do you want to help make Stirling PDF better?'),
+    body: (
+      <div className={styles.bodyCopyInner}>
+        <Trans
+          i18nKey="analytics.paragraph1"
+          defaults="Stirling PDF has opt-in analytics to help us improve the product. We do not track any personal information or file contents."
+          components={{ strong: <strong /> }}
+        />
+        <br />
+        <Trans
+          i18nKey="analytics.paragraph2"
+          defaults="Please consider enabling analytics to help Stirling-PDF grow and to allow us to understand our users better."
+          components={{ strong: <strong /> }}
+        />
+        <br />
+        <div style={{ textAlign: 'right', marginTop: 0 }}>
+          <Button
+            variant="default"
+            size="sm"
+            onClick={() => window.open('https://docs.stirlingpdf.com/analytics-telemetry/', '_blank')}
+            rightSection={<OpenInNewIcon style={{ fontSize: 16 }} />}
+          >
+            {i18n.t('analytics.learnMore', 'Learn more about our analytics')}
+          </Button>
+        </div>
+        {analyticsError && (
+          <div style={{ color: 'var(--mantine-color-red-6)', marginTop: 12 }}>
+            {analyticsError}
+          </div>
+        )}
+      </div>
+    ),
+    background: {
+      gradientStops: ['#0EA5E9', '#6366F1'],
+      circles: UNIFIED_CIRCLE_CONFIG,
+    },
+  };
+}
+
@@ -0,0 +1,27 @@
+import React from 'react';
+import { Trans } from 'react-i18next';
+import i18n from '@app/i18n';
+import { SlideConfig } from '@app/types/types';
+import { UNIFIED_CIRCLE_CONFIG } from '@app/components/onboarding/slides/unifiedBackgroundConfig';
+import styles from '@app/components/onboarding/InitialOnboardingModal/InitialOnboardingModal.module.css';
+
+export default function TourOverviewSlide(): SlideConfig {
+  return {
+    key: 'tour-overview',
+    title: i18n.t('onboarding.tourOverview.title', 'Tour Overview'),
+    body: (
+      <span className={styles.bodyCopyInner}>
+        <Trans
+          i18nKey="onboarding.tourOverview.body"
+          defaults="Stirling PDF V2 ships with dozens of tools and a refreshed layout. Take a quick tour to see what changed and where to find the features you need."
+          components={{ strong: <strong /> }}
+        />
+      </span>
+    ),
+    background: {
+      gradientStops: ['#2563EB', '#7C3AED'],
+      circles: UNIFIED_CIRCLE_CONFIG,
+    },
+  };
+}
+
@@ -1,7 +1,6 @@
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import { useLocation } from 'react-router-dom';
-import { ONBOARDING_STEPS } from '@app/components/onboarding/orchestrator/onboardingConfig';
-import { markStepSeen } from '@app/components/onboarding/orchestrator/onboardingStorage';
+import { markOnboardingCompleted } from '@app/components/onboarding/orchestrator/onboardingStorage';

 const SESSION_KEY = 'onboarding::bypass-all';
 const PARAM_KEY = 'bypassOnboarding';
@@ -34,13 +33,12 @@ function setStoredBypass(enabled: boolean): void {

 /**
 * Detects the `bypassOnboarding` query parameter and stores it in session storage
- * so that onboarding remains disabled while the app is open. Also marks all steps
- * as seen to ensure any dependent UI elements remain hidden.
+ * so that onboarding remains disabled while the app is open. Also marks onboarding
+ * as completed to ensure any dependent UI elements remain hidden.
 */
 export function useBypassOnboarding(): boolean {
  const location = useLocation();
  const [bypassOnboarding, setBypassOnboarding] = useState<boolean>(() => readStoredBypass());
-  const stepsMarkedRef = useRef(false);

  const shouldBypassFromSearch = useMemo(() => {
    try {
@@ -57,14 +55,9 @@ export function useBypassOnboarding(): boolean {
    setBypassOnboarding(nextBypass);
    if (nextBypass) {
      setStoredBypass(true);
+      markOnboardingCompleted();
    }
  }, [shouldBypassFromSearch]);

-  useEffect(() => {
-    if (!bypassOnboarding || stepsMarkedRef.current) return;
-    stepsMarkedRef.current = true;
-    ONBOARDING_STEPS.forEach((step) => markStepSeen(step.id));
-  }, [bypassOnboarding]);
-
  return bypassOnboarding;
 }
@@ -51,14 +51,14 @@ export function useTourRequest(): {
  clearTourRequest: () => void;
 } {
  const [tourRequested, setTourRequested] = useState(false);
-  const [requestedTourType, setRequestedTourType] = useState<TourType>('tools');
+  const [requestedTourType, setRequestedTourType] = useState<TourType>('whatsnew');

  useEffect(() => {
    if (typeof window === 'undefined') return;

    const handleTourRequest = (event: Event) => {
      const { detail } = event as CustomEvent<StartTourPayload>;
-      setRequestedTourType(detail?.tourType ?? 'tools');
+      setRequestedTourType(detail?.tourType ?? 'whatsnew');
      setTourRequested(true);
    };

@@ -8,12 +8,8 @@ export enum TourStep {
  FILES_BUTTON,
  FILE_SOURCES,
  WORKBENCH,
-  VIEW_SWITCHER,
-  VIEWER,
-  PAGE_EDITOR,
  ACTIVE_FILES,
  FILE_CHECKBOX,
-  SELECT_CONTROLS,
  CROP_SETTINGS,
  RUN_BUTTON,
  RESULTS,
@@ -28,10 +24,7 @@ interface UserStepActions {
  backToAllTools: () => void;
  selectCropTool: () => void;
  loadSampleFile: () => void;
-  switchToViewer: () => void;
-  switchToPageEditor: () => void;
  switchToActiveFiles: () => void;
-  selectFirstFile: () => void;
  pinFile: () => void;
  modifyCropSettings: () => void;
  executeTool: () => void;
@@ -50,10 +43,7 @@ export function createUserStepsConfig({ t, actions }: CreateUserStepsConfigArgs)
    backToAllTools,
    selectCropTool,
    loadSampleFile,
-    switchToViewer,
-    switchToPageEditor,
    switchToActiveFiles,
-    selectFirstFile,
    pinFile,
    modifyCropSettings,
    executeTool,
@@ -108,26 +98,6 @@ export function createUserStepsConfig({ t, actions }: CreateUserStepsConfigArgs)
      position: 'center',
      padding: 0,
    },
-    [TourStep.VIEW_SWITCHER]: {
-      selector: '[data-tour="view-switcher"]',
-      content: t('onboarding.viewSwitcher', 'Use these controls to select how you want to view your PDFs.'),
-      position: 'bottom',
-      padding: 0,
-    },
-    [TourStep.VIEWER]: {
-      selector: '[data-tour="workbench"]',
-      content: t('onboarding.viewer', "The <strong>Viewer</strong> lets you read and annotate your PDFs."),
-      position: 'center',
-      padding: 0,
-      action: () => switchToViewer(),
-    },
-    [TourStep.PAGE_EDITOR]: {
-      selector: '[data-tour="workbench"]',
-      content: t('onboarding.pageEditor', "The <strong>Page Editor</strong> allows you to do various operations on the pages within your PDFs, such as reordering, rotating and deleting."),
-      position: 'center',
-      padding: 0,
-      action: () => switchToPageEditor(),
-    },
    [TourStep.ACTIVE_FILES]: {
      selector: '[data-tour="workbench"]',
      content: t('onboarding.activeFiles', "The <strong>Active Files</strong> view shows all of the PDFs you have loaded into the tool, and allows you to select which ones to process."),
@@ -141,14 +111,6 @@ export function createUserStepsConfig({ t, actions }: CreateUserStepsConfigArgs)
      position: 'top',
      padding: 10,
    },
-    [TourStep.SELECT_CONTROLS]: {
-      selector: '[data-tour="right-rail-controls"]',
-      highlightedSelectors: ['[data-tour="right-rail-controls"]', '[data-tour="right-rail-settings"]'],
-      content: t('onboarding.selectControls', "The <strong>Right Rail</strong> contains buttons to quickly select/deselect all of your active PDFs, along with buttons to change the app's theme or language."),
-      position: 'left',
-      padding: 5,
-      action: () => selectFirstFile(),
-    },
    [TourStep.CROP_SETTINGS]: {
      selector: '[data-tour="crop-settings"]',
      content: t('onboarding.cropSettings', "Now that we've selected the file we want crop, we can configure the <strong>Crop</strong> tool to choose the area that we want to crop the PDF to."),
@@ -0,0 +1,197 @@
+import type { StepType } from '@reactour/tour';
+import type { TFunction } from 'i18next';
+
+async function waitForElement(selector: string, timeoutMs = 7000, intervalMs = 100): Promise<void> {
+  if (typeof document === 'undefined') return;
+  const start = Date.now();
+  // Immediate hit
+  if (document.querySelector(selector)) return;
+
+  return new Promise((resolve) => {
+    const check = () => {
+      if (document.querySelector(selector) || Date.now() - start >= timeoutMs) {
+        resolve();
+        return;
+      }
+      setTimeout(check, intervalMs);
+    };
+    check();
+  });
+}
+
+async function waitForHighlightable(selector: string, timeoutMs = 7000, intervalMs = 500): Promise<void> {
+  if (typeof document === 'undefined') return;
+  const start = Date.now();
+
+  return new Promise((resolve) => {
+    const check = () => {
+      const el = document.querySelector<HTMLElement>(selector);
+      const isVisible = !!el && el.getClientRects().length > 0;
+      if (isVisible || Date.now() - start >= timeoutMs) {
+        // Nudge Reactour to recalc positions in case layout shifted
+        window.dispatchEvent(new Event('resize'));
+        requestAnimationFrame(() => window.dispatchEvent(new Event('resize')));
+        resolve();
+        return;
+      }
+      setTimeout(check, intervalMs);
+    };
+    check();
+  });
+}
+
+export enum WhatsNewTourStep {
+  QUICK_ACCESS,
+  LEFT_PANEL,
+  FILE_UPLOAD,
+  RIGHT_RAIL,
+  TOP_BAR,
+  PAGE_EDITOR_VIEW,
+  ACTIVE_FILES_VIEW,
+  WRAP_UP,
+}
+
+interface WhatsNewStepActions {
+  saveWorkbenchState: () => void;
+  closeFilesModal: () => void;
+  backToAllTools: () => void;
+  openFilesModal: () => void;
+  loadSampleFile: () => Promise<void> | void;
+  switchToViewer: () => void;
+  switchToPageEditor: () => void;
+  switchToActiveFiles: () => void;
+  selectFirstFile: () => void;
+}
+
+interface CreateWhatsNewStepsConfigArgs {
+  t: TFunction;
+  actions: WhatsNewStepActions;
+}
+
+export function createWhatsNewStepsConfig({ t, actions }: CreateWhatsNewStepsConfigArgs): Record<WhatsNewTourStep, StepType> {
+  const {
+    saveWorkbenchState,
+    closeFilesModal,
+    backToAllTools,
+    openFilesModal,
+    loadSampleFile,
+    switchToViewer,
+    switchToPageEditor,
+    switchToActiveFiles,
+    selectFirstFile,
+  } = actions;
+
+  return {
+    [WhatsNewTourStep.QUICK_ACCESS]: {
+      selector: '[data-tour="quick-access-bar"]',
+      content: t(
+        'onboarding.whatsNew.quickAccess',
+        'Start at the <strong>Quick Access</strong> rail to jump between Reader, Automate, your files, and all the tours.'
+      ),
+      position: 'right',
+      padding: 10,
+      action: () => {
+        saveWorkbenchState();
+        closeFilesModal();
+        backToAllTools();
+      },
+    },
+    [WhatsNewTourStep.LEFT_PANEL]: {
+      selector: '[data-tour="tool-panel"]',
+      content: t(
+        'onboarding.whatsNew.leftPanel',
+        'The left <strong>Tools</strong> panel lists everything you can do. Browse categories or search to find a tool quickly.'
+      ),
+      position: 'center',
+      padding: 0,
+    },
+    [WhatsNewTourStep.FILE_UPLOAD]: {
+      selector: '[data-tour="files-button"]',
+      content: t(
+        'onboarding.whatsNew.fileUpload',
+        'Use the <strong>Files</strong> button to upload or pick a recent PDF. We will load a sample so you can see the workspace.'
+      ),
+      position: 'right',
+      padding: 10,
+      action: async () => {
+        openFilesModal();
+        await waitForElement('[data-tour="file-sources"]', 5000, 100);
+      },
+      actionAfter: async () => {
+        await Promise.resolve(loadSampleFile());
+        closeFilesModal();
+        switchToViewer();
+        // wait for file render and top controls to mount
+        await waitForElement('[data-tour="view-switcher"]', 7000, 100);
+        await waitForHighlightable('[data-tour="view-switcher"]', 7000, 500);
+      },
+    },
+    [WhatsNewTourStep.RIGHT_RAIL]: {
+      selector: '[data-tour="right-rail-controls"]',
+      highlightedSelectors: ['[data-tour="right-rail-controls"]', '[data-tour="right-rail-settings"]'],
+      content: t(
+        'onboarding.whatsNew.rightRail',
+        'The <strong>Right Rail</strong> holds quick actions to select files, change theme or language, and download results.'
+      ),
+      position: 'left',
+      padding: 10,
+      action: async () => {
+        await waitForElement('[data-tour="right-rail-controls"]', 7000, 100);
+        selectFirstFile();
+      },
+    },
+    [WhatsNewTourStep.TOP_BAR]: {
+      selector: '[data-tour="view-switcher"]',
+      content: t(
+        'onboarding.whatsNew.topBar',
+        'The top bar lets you swap between <strong>Viewer</strong>, <strong>Page Editor</strong>, and <strong>Active Files</strong>.'
+      ),
+      position: 'bottom',
+      padding: 8,
+      // Ensure the switcher has mounted before this step renders
+      action: async () => {
+        switchToViewer();
+        await waitForElement('[data-tour="view-switcher"]', 7000, 100);
+        await waitForHighlightable('[data-tour="view-switcher"]', 7000, 500);
+      },
+    },
+    [WhatsNewTourStep.PAGE_EDITOR_VIEW]: {
+      selector: '[data-tour="view-switcher"]',
+      content: t(
+        'onboarding.whatsNew.pageEditorView',
+        'Switch to the Page Editor to reorder, rotate, or delete pages.'
+      ),
+      position: 'bottom',
+      padding: 8,
+      action: async () => {
+        switchToPageEditor();
+        await waitForElement('[data-tour="view-switcher"]', 7000, 100);
+        await waitForHighlightable('[data-tour="view-switcher"]', 7000, 500);
+      },
+    },
+    [WhatsNewTourStep.ACTIVE_FILES_VIEW]: {
+      selector: '[data-tour="view-switcher"]',
+      content: t(
+        'onboarding.whatsNew.activeFilesView',
+        'Use Active Files to see everything you have open and pick what to work on.'
+      ),
+      position: 'bottom',
+      padding: 8,
+      action: async () => {
+        switchToActiveFiles();
+        await waitForElement('[data-tour="view-switcher"]', 7000, 100);
+        await waitForHighlightable('[data-tour="view-switcher"]', 7000, 500);
+      },
+    },
+    [WhatsNewTourStep.WRAP_UP]: {
+      selector: '[data-tour="help-button"]',
+      content: t(
+        'onboarding.whatsNew.wrapUp',
+        'That is what is new in V2. Open the <strong>Tours</strong> menu anytime to replay this, the Tools tour, or the Admin tour.'
+      ),
+      position: 'right',
+      padding: 10,
+    },
+  };
+}
+