FIX: Make onboarding tour target-state aware

frontend/e2e/onboarding-tour.spec.ts

@@ -0,0 +1,100 @@
+import { expect, test } from "@playwright/test";
+
+import { makeTarget } from "./_targets";
+
+test.describe("Onboarding tour", () => {
+  test("guides a user with no active target through the visible prerequisite", async ({
+    page,
+  }) => {
+    await page.goto("/");
+    await page.getByRole("button", { name: "Take a tour" }).click();
+
+    const dialog = page.getByRole("alertdialog");
+    await dialog.getByRole("button", { name: "Next", exact: true }).click();
+    await dialog.getByRole("button", { name: "Next", exact: true }).click();
+
+    await expect(dialog).toContainText(
+      "target selection happens in Configuration"
+    );
+    await expect(dialog).toContainText("choose Configure a target");
+    await expect(dialog).toContainText("use Set Active there");
+    await expect(dialog).not.toContainText("come back here to select it");
+    await expect(page.locator('[data-tour="target-card"]')).toBeVisible();
+
+    await dialog.getByRole("button", { name: "Next", exact: true }).click();
+
+    await expect(page).toHaveURL(/\/chat$/);
+    await expect(dialog).toContainText(
+      "Chat needs an active target before the message composer is available"
+    );
+    await expect(dialog).toContainText(
+      "After the tour, choose Configure Target"
+    );
+    await expect(dialog).toContainText(
+      "The message input and converter control appear once a target is active"
+    );
+    await expect(
+      page.locator('[data-tour="chat-prerequisite"]')
+    ).toHaveAttribute("data-testid", "no-target-banner");
+    await expect(page.locator('[data-tour="converter-toggle"]')).toHaveCount(0);
+  });
+
+  test("guides a user with an active target to the visible converter control", async ({
+    page,
+  }) => {
+    await page.route(/\/api\/targets(?:\?.*)?$/, async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          items: [
+            makeTarget({
+              target_registry_name: "tour-target",
+              target_type: "OpenAIChatTarget",
+              endpoint: "https://test.com",
+              model_name: "gpt-4o",
+            }),
+          ],
+          pagination: {
+            limit: 200,
+            has_more: false,
+            next_cursor: null,
+            prev_cursor: null,
+          },
+        }),
+      });
+    });
+
+    await page.goto("/");
+    await page
+      .getByRole("button", { name: "Configuration", exact: true })
+      .click();
+    await expect(
+      page.getByRole("heading", { name: "Target Configuration" })
+    ).toBeVisible();
+    await page.getByRole("button", { name: "Set Active", exact: true }).click();
+    await page.getByRole("button", { name: "Home", exact: true }).click();
+    await expect(page.getByTestId("home-target-active")).toContainText("gpt-4o");
+
+    await page.getByRole("button", { name: "Take a tour" }).click();
+    const dialog = page.getByRole("alertdialog");
+    await dialog.getByRole("button", { name: "Next", exact: true }).click();
+    await dialog.getByRole("button", { name: "Next", exact: true }).click();
+
+    await expect(dialog).toContainText("target currently active for Chat");
+    await expect(dialog).toContainText("use Set Active in Configuration");
+    await expect(page.locator('[data-tour="target-card"]')).toBeVisible();
+
+    await dialog.getByRole("button", { name: "Next", exact: true }).click();
+
+    await expect(page).toHaveURL(/\/chat$/);
+    await expect(dialog).toContainText("Chat shows the message composer");
+    await expect(dialog).toContainText("Toggle converter panel");
+    await expect(page.getByRole("textbox")).toBeVisible();
+    await expect(page.locator('[data-tour="converter-toggle"]')).toHaveAttribute(
+      "aria-label",
+      "Toggle converter panel"
+    );
+    await expect(page.getByTestId("no-target-banner")).toHaveCount(0);
+  });
+});

frontend/src/App.tsx

@@ -345,7 +345,12 @@ function App() {
   // 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, tourProps } = useTour(handleNavigate, resolved === 'dark', currentView)
+  const { startTour, tourProps } = useTour(
+    handleNavigate,
+    resolved === 'dark',
+    currentView,
+    activeTarget !== null,
+  )
 
   return (
     <ErrorBoundary>

frontend/src/components/Chat/ChatInputArea.test.tsx

@@ -58,7 +58,10 @@ describe("ChatInputArea", () => {
 
     expect(screen.getByRole("textbox")).toBeInTheDocument();
     expect(getSendButton()).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: /convert/i })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /convert/i })).toHaveAttribute(
+      "data-tour",
+      "converter-toggle"
+    );
   });
 
   it("should call converter panel toggle handler when convert button is clicked", async () => {
@@ -79,6 +82,22 @@ describe("ChatInputArea", () => {
     expect(onToggleConverterPanel).toHaveBeenCalledTimes(1);
   });
 
+  it("should expose the visible target prerequisite to the tour", () => {
+    render(
+      <TestWrapper>
+        <ChatInputArea {...defaultProps} noTargetSelected />
+      </TestWrapper>
+    );
+
+    expect(screen.getByTestId("no-target-banner")).toHaveAttribute(
+      "data-tour",
+      "chat-prerequisite"
+    );
+    expect(
+      screen.queryByRole("button", { name: /toggle converter panel/i })
+    ).not.toBeInTheDocument();
+  });
+
   it("should call onSend with input value when send button clicked", async () => {
     const user = userEvent.setup();
     const onSend = jest.fn();

frontend/src/components/Chat/ChatInputArea.tsx

@@ -34,11 +34,12 @@ interface StatusBannerProps {
   textClassName: string
   buttonTestId?: string
   buttonClassName?: string
+  tourTarget?: string
 }
 
-function StatusBanner({ icon, text, buttonText, buttonIcon, onButtonClick, testId, className, textClassName, buttonTestId, buttonClassName }: StatusBannerProps) {
+function StatusBanner({ icon, text, buttonText, buttonIcon, onButtonClick, testId, className, textClassName, buttonTestId, buttonClassName, tourTarget }: StatusBannerProps) {
   return (
-    <div className={className} data-testid={testId}>
+    <div className={className} data-testid={testId} data-tour={tourTarget}>
       {icon}
       <Text className={textClassName} size={300}>
         {text}
@@ -507,6 +508,7 @@ const ChatInputArea = forwardRef<ChatInputAreaHandle, ChatInputAreaProps>(functi
             testId="no-target-banner"
             buttonTestId="configure-target-input-btn"
             buttonClassName={styles.touchTarget}
+            tourTarget="chat-prerequisite"
           />
         ) : operatorLocked ? (
           <StatusBanner
@@ -585,6 +587,7 @@ const ChatInputArea = forwardRef<ChatInputAreaHandle, ChatInputAreaProps>(functi
                   onClick={onToggleConverterPanel}
                   disabled={disabled}
                   data-testid="toggle-converter-panel-btn"
+                  data-tour="converter-toggle"
                   aria-label="Toggle converter panel"
                 />
               </Tooltip>

frontend/src/components/Chat/ChatWindow.tsx

@@ -632,7 +632,7 @@ export default function ChatWindow({
         />
       )}
       <div className={styles.chatArea} data-testid="chat-area">
-        <div className={styles.ribbon} data-tour="chat-area">
+        <div className={styles.ribbon}>
           <div className={styles.conversationInfo}>
             {activeTarget ? (
               <TargetBadge target={activeTarget} />

frontend/src/components/Tour/TourTooltip.styles.ts

@@ -2,12 +2,13 @@ import { makeStyles, tokens } from '@fluentui/react-components'
 import { mobileTouchTarget } from '../../styles/touchTargets'
 
 export const useTourTooltipStyles = makeStyles({
-  // Outer wrapper: provides space for the mascot to overflow below the card
+  // Include the mascot's overhang in the floating bounds so Joyride can keep it in the viewport.
   wrapper: {
     display: 'flex',
     flexDirection: 'column',
     width: '420px',
     maxWidth: `calc(100vw - ${tokens.spacingHorizontalM} - ${tokens.spacingHorizontalM})`,
+    paddingBottom: `calc(${tokens.spacingVerticalXXL} + ${tokens.spacingVerticalL})`,
     position: 'relative',
   },
   container: {
@@ -25,7 +26,7 @@ export const useTourTooltipStyles = makeStyles({
   // Mascot positioned at bottom-left, overlapping the card edge
   mascot: {
     position: 'absolute',
-    bottom: '-40px',
+    bottom: 0,
     left: '-20px',
     width: '90px',
     height: '90px',

frontend/src/components/Tour/tourSteps.ts

@@ -11,50 +11,62 @@ export interface TourStep extends Step {
   readonly viewRequired: ViewName
 }
 
-export const TOUR_STEPS: readonly TourStep[] = [
-  {
-    target: '[data-tour="sidebar-nav"]',
-    content:
-      'Ahoy! Welcome to Co-PyRIT! This is your main navigation panel. Home is your dashboard, Chat is where you send prompts, ' +
-      'History tracks past attacks, and Configuration is where you set up targets. Feel free to try clicking between these views!',
-    placement: 'right-start',
-    skipBeacon: true,
-    viewRequired: 'home',
-  },
-  {
-    target: '[data-tour="labels-card"]',
-    content:
-      'Labels like "operator" and "operation" tag every attack you run, making them easy to find later. ' +
-      'Update the defaults before you start!',
-    placement: 'bottom',
-    skipBeacon: true,
-    viewRequired: 'home',
-  },
-  {
-    target: '[data-tour="target-card"]',
-    content:
-      'Targets are the AI endpoints you\'re testing. Head to Configuration to set one up, ' +
-      'then come back here to select it before chatting.',
-    placement: 'bottom',
-    skipBeacon: true,
-    viewRequired: 'home',
-  },
-  {
-    target: '[data-tour="chat-area"]',
-    content:
-      'This is where you send prompts and view assistant responses. Use the converter panel toggle on the ' +
-      'left of the message input box to transform your text before sending — like Base64 encoding or translation.',
-    placement: 'bottom',
-    skipBeacon: true,
-    viewRequired: 'chat',
-  },
-  {
-    target: '[data-tour="history-filters"]',
-    content:
-      'Every attack is logged here. Filter by different criteria like outcome, converter type, or labels to ' +
-      'find exactly what you need!',
-    placement: 'bottom',
-    skipBeacon: true,
-    viewRequired: 'history',
-  },
-]
+/** Builds tour guidance for the controls available in the current target state. */
+export function createTourSteps(hasActiveTarget: boolean): TourStep[] {
+  return [
+    {
+      target: '[data-tour="sidebar-nav"]',
+      content:
+        'Ahoy! Welcome to Co-PyRIT! This is your main navigation panel. Home is your dashboard, Chat is where you send prompts, ' +
+        'History tracks past attacks, and Configuration is where you set up targets. Feel free to try clicking between these views!',
+      placement: 'right-start',
+      skipBeacon: true,
+      viewRequired: 'home',
+    },
+    {
+      target: '[data-tour="labels-card"]',
+      content:
+        'Labels like "operator" and "operation" tag every attack you run, making them easy to find later. ' +
+        'Update the defaults before you start!',
+      placement: 'bottom',
+      skipBeacon: true,
+      viewRequired: 'home',
+    },
+    {
+      target: '[data-tour="target-card"]',
+      content: hasActiveTarget
+        ? 'This card shows the target currently active for Chat. To switch targets after the tour, choose Manage targets ' +
+          'and use Set Active in Configuration.'
+        : 'Targets are the AI endpoints you\'re testing. This card only shows the current target; target selection happens ' +
+          'in Configuration. After the tour, choose Configure a target, then create or choose one and use Set Active there.',
+      placement: 'bottom',
+      skipBeacon: true,
+      viewRequired: 'home',
+    },
+    {
+      target: hasActiveTarget
+        ? '[data-tour="converter-toggle"]'
+        : '[data-tour="chat-prerequisite"]',
+      content: hasActiveTarget
+        ? 'With a target active, Chat shows the message composer. Use this Toggle converter panel button to transform text ' +
+          'before sending, such as Base64 encoding or translation.'
+        : 'Chat needs an active target before the message composer is available. After the tour, choose Configure Target to ' +
+          'create or activate one in Configuration, then return to Chat. The message input and converter control appear once ' +
+          'a target is active.',
+      placement: 'bottom',
+      skipBeacon: true,
+      viewRequired: 'chat',
+    },
+    {
+      target: '[data-tour="history-filters"]',
+      content:
+        'Every attack is logged here. Filter by different criteria like outcome, converter type, or labels to ' +
+        'find exactly what you need!',
+      placement: 'bottom',
+      skipBeacon: true,
+      viewRequired: 'history',
+    },
+  ]
+}
+
+export const TOUR_STEPS = createTourSteps(false)

frontend/src/hooks/useTour.test.ts

@@ -59,6 +59,30 @@ describe('useTour', () => {
     })
   })
 
+  it('uses visible setup guidance when no target is active', () => {
+    const { result } = renderHook(() => useTour(onNavigate, true, 'home', false))
+    const steps = result.current.tourProps.steps
+
+    expect(steps[2].content).toContain('target selection happens in Configuration')
+    expect(steps[2].content).toContain('choose Configure a target')
+    expect(steps[2].content).toContain('use Set Active there')
+    expect(steps[3].target).toBe('[data-tour="chat-prerequisite"]')
+    expect(steps[3].content).toContain('before the message composer is available')
+    expect(steps[3].content).toContain('converter control appear once a target is active')
+  })
+
+  it('uses the active target card and visible converter control when a target is active', () => {
+    const { result } = renderHook(() => useTour(onNavigate, true, 'home', true))
+    const steps = result.current.tourProps.steps
+
+    expect(steps[2].content).toContain('target currently active for Chat')
+    expect(steps[2].content).toContain('after the tour')
+    expect(steps[2].content).toContain('use Set Active in Configuration')
+    expect(steps[3].target).toBe('[data-tour="converter-toggle"]')
+    expect(steps[3].content).toContain('Chat shows the message composer')
+    expect(steps[3].content).toContain('Toggle converter panel')
+  })
+
   it('startTour navigates to home and defers step when on a different view', () => {
     const { result, rerender } = renderHook(
       ({ currentView }) => useTour(onNavigate, true, currentView),