FEAT Make onboarding tour opt-in via a top-bar button (#2069)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: romanlutz

frontend/src/App.test.tsx

@@ -29,7 +29,6 @@ jest.mock("react-joyride", () => ({
 jest.mock("./hooks/useTour", () => ({
   useTour: () => ({
     startTour: jest.fn(),
-    hasCompletedTour: true,
     tourProps: {
       steps: [],
       run: false,

frontend/src/App.tsx

@@ -335,17 +335,10 @@ function App() {
     />
   )
 
-  // Onboarding tour — pass handleNavigate so the tour can switch views between steps
+  // Onboarding tour — pass handleNavigate so the tour can switch views between steps.
+  // The tour does not auto-start; users launch it from the "Take a tour" button in the top bar.
   const { resolved } = useTheme()
-  const { startTour, hasCompletedTour, tourProps } = useTour(handleNavigate, resolved === 'dark', currentView)
-
-  // Auto-start the tour on first visit
-  useEffect(() => {
-    if (!hasCompletedTour) {
-      startTour()
-    }
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [])
+  const { startTour, tourProps } = useTour(handleNavigate, resolved === 'dark', currentView)
 
   return (
     <ErrorBoundary>

frontend/src/components/Layout/MainLayout.styles.ts

@@ -32,6 +32,9 @@ export const useMainLayoutStyles = makeStyles({
     color: tokens.colorNeutralForeground3,
     marginLeft: tokens.spacingHorizontalXS,
   },
+  spacer: {
+    flex: 1,
+  },
   contentArea: {
     display: 'flex',
     flex: 1,

frontend/src/components/Layout/MainLayout.test.tsx

@@ -4,6 +4,7 @@
  */
 
 import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import { FluentProvider, webLightTheme } from "@fluentui/react-components";
 import MainLayout from "./MainLayout";
 
@@ -138,4 +139,55 @@ describe("MainLayout", () => {
       expect(mockedVersionApi.getVersion).toHaveBeenCalled();
     });
   });
+
+  it("renders a 'Take a tour' button in the top bar when onStartTour is provided", async () => {
+    mockedVersionApi.getVersion.mockResolvedValue({ version: "1.0.0" });
+
+    renderWithProvider(
+      <MainLayout {...defaultProps} onStartTour={jest.fn()}>
+        <div>Content</div>
+      </MainLayout>
+    );
+
+    expect(screen.getByRole("button", { name: /take a tour/i })).toBeInTheDocument();
+
+    await waitFor(() => {
+      expect(mockedVersionApi.getVersion).toHaveBeenCalled();
+    });
+  });
+
+  it("calls onStartTour when the 'Take a tour' button is clicked", async () => {
+    mockedVersionApi.getVersion.mockResolvedValue({ version: "1.0.0" });
+    const onStartTour = jest.fn();
+    const user = userEvent.setup();
+
+    renderWithProvider(
+      <MainLayout {...defaultProps} onStartTour={onStartTour}>
+        <div>Content</div>
+      </MainLayout>
+    );
+
+    await user.click(screen.getByRole("button", { name: /take a tour/i }));
+    expect(onStartTour).toHaveBeenCalledTimes(1);
+
+    await waitFor(() => {
+      expect(mockedVersionApi.getVersion).toHaveBeenCalled();
+    });
+  });
+
+  it("does not render the 'Take a tour' button when onStartTour is not provided", async () => {
+    mockedVersionApi.getVersion.mockResolvedValue({ version: "1.0.0" });
+
+    renderWithProvider(
+      <MainLayout {...defaultProps}>
+        <div>Content</div>
+      </MainLayout>
+    );
+
+    expect(screen.queryByRole("button", { name: /take a tour/i })).not.toBeInTheDocument();
+
+    await waitFor(() => {
+      expect(mockedVersionApi.getVersion).toHaveBeenCalled();
+    });
+  });
 });

frontend/src/components/Layout/MainLayout.tsx

@@ -1,8 +1,10 @@
 import { useEffect, useState } from 'react'
 import {
+  Button,
   Text,
   Tooltip,
 } from '@fluentui/react-components'
+import { QuestionCircleRegular } from '@fluentui/react-icons'
 import { versionApi } from '../../services/api'
 import Navigation, { type ViewName } from '../Sidebar/Navigation'
 import { UserAccountButton } from '../UserAccountButton'
@@ -48,6 +50,17 @@ export default function MainLayout({
         </Tooltip>
         <Text className={styles.title}>Co-PyRIT</Text>
         <Text className={styles.subtitle}>Python Risk Identification Tool</Text>
+        <div className={styles.spacer} />
+        {onStartTour && (
+          <Button
+            appearance="subtle"
+            icon={<QuestionCircleRegular />}
+            onClick={onStartTour}
+            data-testid="start-tour"
+          >
+            Take a tour
+          </Button>
+        )}
         <UserAccountButton />
       </div>
       <div className={styles.contentArea}>
@@ -56,7 +69,6 @@ export default function MainLayout({
             currentView={currentView}
             onNavigate={onNavigate}
             onOpenFeedback={onOpenFeedback}
-            onStartTour={onStartTour}
           />
         </aside>
         <main className={styles.main}>{children}</main>

frontend/src/components/Sidebar/Navigation.tsx

@@ -10,7 +10,6 @@ import type { MenuCheckedValueChangeData, MenuCheckedValueChangeEvent } from '@f
 import {
   ChatRegular,
   HomeRegular,
-  QuestionCircleRegular,
   SettingsRegular,
   HistoryRegular,
   PersonFeedbackRegular,
@@ -26,7 +25,6 @@ export type ViewName = 'home' | 'chat' | 'history' | 'config'
 interface NavigationProps {
   currentView: ViewName
   onNavigate: (view: ViewName) => void
-  onStartTour?: () => void
   onOpenFeedback: () => void
 }
 
@@ -39,7 +37,7 @@ const THEME_LABELS: Record<ThemeMode, string> = {
 }
 
 
-export default function Navigation({ currentView, onNavigate, onStartTour, onOpenFeedback }: NavigationProps) {
+export default function Navigation({ currentView, onNavigate, onOpenFeedback }: NavigationProps) {
   const styles = useNavigationStyles()
   const { mode, resolved, setMode } = useTheme()
 
@@ -100,16 +98,6 @@ export default function Navigation({ currentView, onNavigate, onStartTour, onOpe
 
       <div className={styles.spacer} />
 
-      {onStartTour && (
-        <Button
-          className={styles.navButton}
-          appearance="subtle"
-          icon={<QuestionCircleRegular />}
-          onClick={onStartTour}
-          title="Take a tour"
-          aria-label="Take a tour"
-        />
-      )}
       <Button
         className={styles.navButton}
         appearance="subtle"

frontend/src/hooks/useTour.test.ts

@@ -5,8 +5,6 @@ import { ACTIONS, LIFECYCLE, STATUS } from 'react-joyride'
 import { useTour } from './useTour'
 import { TOUR_STEPS } from '../components/Tour/tourSteps'
 
-const STORAGE_KEY = 'pyrit-tour-completed'
-
 // Minimal EventData shape — only fields our handler reads
 function makeEvent(overrides: Record<string, unknown> = {}) {
   return {
@@ -45,17 +43,6 @@ describe('useTour', () => {
     jest.restoreAllMocks()
   })
 
-  it('returns hasCompletedTour=false when localStorage is empty', () => {
-    const { result } = renderHook(() => useTour(onNavigate, true, 'home'))
-    expect(result.current.hasCompletedTour).toBe(false)
-  })
-
-  it('returns hasCompletedTour=true when localStorage flag is set', () => {
-    localStorage.setItem(STORAGE_KEY, 'true')
-    const { result } = renderHook(() => useTour(onNavigate, true, 'home'))
-    expect(result.current.hasCompletedTour).toBe(true)
-  })
-
   it('startTour sets run=true immediately when already on home', () => {
     const { result } = renderHook(() => useTour(onNavigate, true, 'home'))
 
@@ -116,7 +103,7 @@ describe('useTour', () => {
     expect(result.current.tourProps.stepIndex).toBe(0)
   })
 
-  it('stops tour on ACTIONS.CLOSE and persists to localStorage', () => {
+  it('stops tour on ACTIONS.CLOSE', () => {
     const { result } = renderHook(() => useTour(onNavigate, true, 'home'))
 
     act(() => { result.current.startTour() })
@@ -125,9 +112,7 @@ describe('useTour', () => {
     act(() => {
       result.current.tourProps.onEvent(makeEvent({ action: ACTIONS.CLOSE }))
     })
-
     expect(result.current.tourProps.run).toBe(false)
-    expect(localStorage.getItem(STORAGE_KEY)).toBe('true')
   })
 
   it('stops tour on STATUS.SKIPPED', () => {
@@ -138,9 +123,7 @@ describe('useTour', () => {
     act(() => {
       result.current.tourProps.onEvent(makeEvent({ status: STATUS.SKIPPED }))
     })
-
     expect(result.current.tourProps.run).toBe(false)
-    expect(localStorage.getItem(STORAGE_KEY)).toBe('true')
   })
 
   it('stops tour on STATUS.FINISHED', () => {
@@ -257,9 +240,7 @@ describe('useTour', () => {
         index: lastIndex,
       }))
     })
-
     expect(result.current.tourProps.run).toBe(false)
-    expect(localStorage.getItem(STORAGE_KEY)).toBe('true')
   })
 
   it('clears pending step when tour is cancelled during view switch', () => {

frontend/src/hooks/useTour.ts

@@ -7,8 +7,6 @@ import { TOUR_STEPS } from '../components/Tour/tourSteps'
 import TourTooltip from '../components/Tour/TourTooltip'
 import type { ViewName } from '../components/Sidebar/Navigation'
 
-const STORAGE_KEY = 'pyrit-tour-completed'
-
 // Static Joyride config — hoisted to module scope so they're created once,
 // not on every render. Joyride compares these by reference internally.
 const JOYRIDE_STEPS = [...TOUR_STEPS]
@@ -27,7 +25,7 @@ const JOYRIDE_LOCALE = {
 
 /**
  * Manages the onboarding tour lifecycle: step progression, cross-view
- * navigation, and localStorage persistence.
+ * navigation, and Joyride configuration.
  *
  * Returns props to spread onto `<Joyride>` plus control functions.
  */
@@ -73,8 +71,6 @@ export function useTour(onNavigate: (view: ViewName) => void, isDarkMode: boolea
     })
   }, [currentView])
 
-  const hasCompletedTour = localStorage.getItem(STORAGE_KEY) === 'true'
-
   const startTour = useCallback(() => {
     setStepIndex(0)
     // If we're already on home, start immediately.
@@ -96,7 +92,6 @@ export function useTour(onNavigate: (view: ViewName) => void, isDarkMode: boolea
     pendingStepRef.current = null
     switchingViewRef.current = false
     onNavigate('home')
-    localStorage.setItem(STORAGE_KEY, 'true')
   }, [onNavigate])
 
   const handleJoyrideEvent = useCallback((data: EventData) => {
@@ -178,8 +173,6 @@ export function useTour(onNavigate: (view: ViewName) => void, isDarkMode: boolea
   return {
     /** Call to start (or restart) the tour from step 1 on the Home view. */
     startTour,
-    /** Whether the user has completed the tour at least once. */
-    hasCompletedTour,
     /** Props to spread onto the `<Joyride>` component. */
     tourProps,
   }