A tour chunk that fails twice no longer drops the first run

Co-authored-by: Gáborjáni-Szabó Ádám <Programcode@users.noreply.github.com>

Author: cursoragent

docs/architecture.md

@@ -141,7 +141,7 @@ Supabase Auth owns user sessions. Protected routes provide a client navigation b
 
 - Google OAuth, six-digit email OTP, and demo-code token-hash handoffs all finish as ordinary Supabase sessions and use the same store hydration path.
 - Google and any emailed sign-in link return to `/auth/callback` (with `?next=/app/...` for a deep link; only `/app` paths are accepted). [`AuthProvider`](../src/lib/supabase/AuthProvider.tsx) exchanges the code there and keeps `loading` true until the exchange settles. The client sets `experimental.appendPkceFlowIdToRedirects`, so each sign-in keeps its own PKCE verifier and its redirect carries `sb_flow_id`; another tab's sign-in or a failed resend no longer breaks a pending link. An `error`/`error_code` from Auth, or a failed exchange, opens `/login` with a localized message. Links that still point at `/?code=` or `/app?code=` are moved onto the callback route before the first render ([`src/lib/auth-callback.ts`](../src/lib/auth-callback.ts)). Each project's Auth redirect allowlist needs `<site origin>/auth/callback**`; a redirect to the Site URL's own host passes without it.
-- Sign-out ends only this device's session (`scope: 'local'`). After a sign-out, `/login` returns only the same account to the page it left; another account starts on `/app`. The onboarding tour is tracked per account on each browser. The one-time DebateOwl welcome ([`src/lib/debateowl-intro.ts`](../src/lib/debateowl-intro.ts)) opens once per browser inside the signed-in app, is remembered in localStorage (`debateowl_intro_seen_v1`), and closing it continues straight into the tour's Start debate step. `?intro=show` opens the welcome again; a finished tour stays finished.
+- Sign-out ends only this device's session (`scope: 'local'`). After a sign-out, `/login` returns only the same account to the page it left; another account starts on `/app`. The onboarding tour is tracked per account on each browser. The one-time DebateOwl welcome ([`src/lib/debateowl-intro.ts`](../src/lib/debateowl-intro.ts)) opens once per browser inside the signed-in app, is remembered in localStorage (`debateowl_intro_seen_v1`), and closing it continues straight into the tour's Start debate step. If that chunk fails twice, the app logs once, remembers the welcome, and continues without the tour. `?intro=show` opens the welcome again; a finished tour stays finished.
 - RLS owns row visibility and mutation rights.
 - Shared backend helpers validate bearer tokens and admin roles.
 - Admin endpoints verify server-side roles.

docs/testing.md

@@ -129,7 +129,7 @@ The server is never reused. CI uses retries and two workers. On failure, traces,
 
 Playwright starts that server with `VITE_E2E=1`. The client then keeps the environment switcher, but the production fallback is `http://e2e.invalid` instead of the production Supabase project, and a request that still names that project is refused in the browser. `playwright.config.ts` also refuses to start when `VITE_SUPABASE_ENV` or `SUPABASE_URL` already points at production. `E2E_ALLOW_PROD=1` is the explicit override. The production canary uses `playwright.production.config.ts` and does not set `VITE_E2E`. Plain `npm run dev` is unchanged and still defaults to production.
 
-The one-time DebateOwl welcome stays closed whenever `VITE_E2E` or `VITE_LOCAL_PREVIEW` is set, so Playwright, the verify stack and agentic tests never meet it; `?intro=show` opens it anyway and `?intro=skip` keeps it closed in any build. Closing it continues into the tour's Start debate step when that account has not finished the tour. The production canary and the service worker offline test (`npm run test:sw`), which drive production builds, seed `debateowl_intro_seen_v1` instead.
+The one-time DebateOwl welcome stays closed whenever `VITE_E2E` or `VITE_LOCAL_PREVIEW` is set, so Playwright, the verify stack and agentic tests never meet it; `?intro=show` opens it anyway and `?intro=skip` keeps it closed in any build. Closing it continues into the tour's Start debate step when that account has not finished the tour. If that chunk fails twice, the app logs once, remembers the welcome, and continues without the tour. The production canary and the service worker offline test (`npm run test:sw`), which drive production builds, seed `debateowl_intro_seen_v1` instead.
 
 `e2e/hungarian-parity.spec.ts` is the focused Hungarian browser contract. On desktop and mobile Chromium it checks persisted `<html lang="hu">`, public and authenticated page chrome, route titles, onboarding, saved-chat empty state, Library controls, Timer semantics, localized close labels, and runtime errors. It deliberately does not reject arbitrary English text because source titles, user content, model names, and citations may legitimately remain in their source language.
 

src/App.tsx

@@ -15,6 +15,7 @@ import { ThemeProvider } from "@/components/ThemeProvider";
 import { useSessionStorageSync } from "@/hooks/use-session-storage-sync";
 import { hasCompletedOnboarding, useOnboardingStore } from "@/hooks/use-onboarding";
 import { browserStorage, markIntroSeen, shouldShowIntro } from "@/lib/debateowl-intro";
+import { focusCurrentDebate, noteTourChunkFailure, tourChunkGaveUp } from "@/lib/onboarding-tour-load";
 import { OfflineIndicator } from "@/components/OfflineIndicator";
 import { StagingBanner } from "@/components/StagingBanner";
 import { captureException, captureProductEvent, toTelemetrySafeError } from "@/lib/observability";
@@ -97,12 +98,15 @@ let onboardingTourPromise: Promise<OnboardingTourComponent> | null = null;
 function loadOnboardingTour(): Promise<OnboardingTourComponent> {
   if (onboardingTourComponent) return Promise.resolve(onboardingTourComponent);
   // A failed fetch has to be retryable. Keeping the rejected promise would
-  // leave the Start debate step closed for the rest of the page.
+  // leave the Start debate step closed for the rest of the page. The second
+  // failure is the last: `noteTourChunkFailure` logs once and the tour owner
+  // continues without it.
   onboardingTourPromise ??= import("@/components/features/onboarding/OnboardingTour").then((mod) => {
     onboardingTourComponent = mod.OnboardingTour;
     return mod.OnboardingTour;
   }).catch((error: unknown) => {
     onboardingTourPromise = null;
+    noteTourChunkFailure(error);
     throw error;
   });
   return onboardingTourPromise;
@@ -307,18 +311,17 @@ export function RouteContent({ children }: { children: ReactNode }) {
  * One first-run moment. The owl welcome, when it is due, opens over the signed-in
  * app once its layout has loaded. Closing it continues straight into the tour's
  * Start debate step. With no welcome, the tour mounts as before.
+ * Rendered only under RequireAuth, so an account is already signed in.
  */
-function AppWelcome() {
+export function AppWelcome() {
   const [showIntro] = useState(() => shouldShowIntro({
     search: window.location.search,
     storage: browserStorage(),
     env: import.meta.env,
   }));
   const [layoutReady, setLayoutReady] = useState(false);
   const userId = useAuth().user?.id;
-  // A missing account is not a finished tour. `hasCompletedOnboarding` says so
-  // only because there is nobody to show it to yet.
-  const tourCompleted = useOnboardingStore((state) => Boolean(userId) && hasCompletedOnboarding(state, userId));
+  const tourCompleted = useOnboardingStore((state) => hasCompletedOnboarding(state, userId));
 
   useEffect(() => {
     if (!showIntro) return;
@@ -364,15 +367,38 @@ function OptionalOnboardingTour({ continueFromIntro }: { continueFromIntro: bool
 function TimedOnboardingTour({ userId, continueFromIntro }: { userId: string; continueFromIntro: boolean }) {
   const [eligibleAt] = useState(() => typeof performance === "undefined" ? 0 : performance.now());
   const [Tour, setTour] = useState<OnboardingTourComponent | null>(() => onboardingTourComponent);
+  const [gaveUp, setGaveUp] = useState(false);
 
   useEffect(() => {
-    if (Tour) return;
+    if (Tour || gaveUp) return;
     let live = true;
-    loadOnboardingTour().then((Loaded) => { if (live) setTour(() => Loaded); }, (): void => undefined);
+    const giveUp = () => {
+      setGaveUp(true);
+      focusCurrentDebate();
+    };
+    // The welcome's preload counts as the first try when it ran. One more
+    // failure after that, and the page continues without the tour.
+    if (tourChunkGaveUp()) {
+      giveUp();
+      return;
+    }
+    const load = () => {
+      loadOnboardingTour().then((Loaded) => {
+        if (live) setTour(() => Loaded);
+      }, () => {
+        if (!live) return;
+        if (tourChunkGaveUp()) {
+          giveUp();
+          return;
+        }
+        load();
+      });
+    };
+    load();
     return () => { live = false; };
-  }, [Tour]);
+  }, [Tour, gaveUp]);
 
-  if (!Tour) return null;
+  if (gaveUp || !Tour) return null;
   return <Tour eligibleAt={eligibleAt} userId={userId} continueFromIntro={continueFromIntro} />;
 }
 

src/components/features/onboarding/DebateOwlIntro.tsx

@@ -63,6 +63,11 @@ export function DebateOwlIntro({ onClose, owlName = OWL_NAME }: { onClose: () =>
           event.preventDefault();
           doneButton.current?.focus();
         }}
+        // The tour's Next button takes focus as this dialog goes. Restoring
+        // focus here would put it back on the page body.
+        onCloseAutoFocus={(event) => {
+          event.preventDefault();
+        }}
       >
         <div className="flex flex-col items-center gap-5 px-6 pt-7 sm:flex-row sm:items-center sm:gap-6 sm:px-8 sm:pt-8">
           <motion.div

src/components/features/onboarding/OnboardingTour.tsx

@@ -5,6 +5,7 @@ import Joyride, { ACTIONS, CallBackProps, EVENTS, STATUS, Step } from 'react-joy
 import { useLocation } from 'react-router-dom';
 import { Button } from '@/components/ui/button';
 import { hasCompletedOnboarding as completedFor, useOnboardingStore } from '@/hooks/use-onboarding';
+import { focusCurrentDebate, focusTourPrimary } from '@/lib/onboarding-tour-load';
 import { useDebateStore } from '@/lib/stores/debate-store';
 
 // Below `lg` the header's menu button is the navigation. There the tour draws no
@@ -128,14 +129,28 @@ export function OnboardingTour({
         setScrollOffset((document.querySelector('header')?.getBoundingClientRect().height ?? 0) + 24);
     }, [resolveTourSteps]);
 
-    // The welcome and this step are one moment: open the spotlight before paint,
-    // while the dialog's close is still the thing the student just did.
+    // The parent leaves `continueFromIntro` true for the whole Start debate step.
+    // Consume it once the spotlight has opened. `startTour` does not reset
+    // `stepIndex`, and the create-dialog pause still depends on `debateDialog`,
+    // so a later language or debate change must not run this handoff again.
+    // If the card is not in the document yet, leave it pending for the next pass.
+    const handoffPending = useRef(continueFromIntro);
     useLayoutEffect(() => {
-        if (!continueFromIntro || hasCompletedOnboarding || location.pathname !== '/app') return;
+        if (!handoffPending.current || hasCompletedOnboarding || location.pathname !== '/app') return;
         if (!document.querySelector('[data-tour="current-debate"]')) return;
+        handoffPending.current = false;
         prepareTour();
         startTour();
-    }, [continueFromIntro, hasCompletedOnboarding, location.pathname, prepareTour, startTour]);
+    }, [hasCompletedOnboarding, location.pathname, prepareTour, startTour]);
+
+    // Joyride also focuses a hidden beacon. That runs in its mount timeout, so
+    // the visible Next button has to take focus after it. The welcome dialog
+    // has already given up restoring focus to the page body.
+    useEffect(() => {
+        if (!continueFromIntro || hasCompletedOnboarding || !isTourRunning) return;
+        const timer = window.setTimeout(() => { focusTourPrimary(); }, 0);
+        return () => window.clearTimeout(timer);
+    }, [continueFromIntro, hasCompletedOnboarding, isTourRunning]);
 
     // Start tour automatically for new users
     useEffect(() => {
@@ -193,6 +208,9 @@ export function OnboardingTour({
         if (finishedStatuses.includes(status)) {
             setOnboardingComplete(userId);
             setStepIndex(0);
+            // The tooltip is about to unmount. The card it was pointing at is the
+            // control the student can use next.
+            requestAnimationFrame(() => { focusCurrentDebate(); });
         } else if (type === EVENTS.STEP_AFTER || type === EVENTS.TARGET_NOT_FOUND) {
             setStepIndex(index + (action === ACTIONS.PREV ? -1 : 1));
         }

src/lib/onboarding-tour-load.ts

@@ -0,0 +1,47 @@
+import { browserStorage, markIntroSeen } from '@/lib/debateowl-intro';
+
+/** The welcome preloads the tour once. The tour owner tries once more, then stops. */
+const TOUR_CHUNK_ATTEMPTS = 2;
+
+let attempts = 0;
+let logged = false;
+
+export function resetTourChunkLoadForTests(): void {
+  attempts = 0;
+  logged = false;
+}
+
+export function tourChunkGaveUp(): boolean {
+  return attempts >= TOUR_CHUNK_ATTEMPTS;
+}
+
+/**
+ * Count one failed fetch of the tour chunk. The second failure logs once,
+ * remembers the welcome, and lets the page continue without the tour.
+ */
+export function noteTourChunkFailure(error: unknown): 'retry' | 'give-up' {
+  attempts += 1;
+  if (attempts < TOUR_CHUNK_ATTEMPTS) return 'retry';
+  if (!logged) {
+    logged = true;
+    const detail = error instanceof Error ? error.message : 'unknown error';
+    console.warn('[Onboarding] Could not load the tour. Continuing without it.', detail);
+    markIntroSeen(browserStorage());
+  }
+  return 'give-up';
+}
+
+/** The Current Debate card is what the first step was pointing at. */
+export function focusCurrentDebate(): void {
+  if (typeof document === 'undefined') return;
+  const card = document.querySelector<HTMLElement>('[data-tour="current-debate"]');
+  if (!card) return;
+  const control = card.querySelector<HTMLElement>('button:not([disabled]), a[href]');
+  (control ?? card).focus();
+}
+
+/** Joyride's Next button, the action the welcome just handed the student. */
+export function focusTourPrimary(): void {
+  if (typeof document === 'undefined') return;
+  document.querySelector<HTMLElement>('[data-action="primary"]')?.focus();
+}

src/test/onboarding/debateowl-intro.test.tsx

@@ -1,12 +1,16 @@
-import { fireEvent, render, screen } from '@testing-library/react';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { User } from '@supabase/supabase-js';
 import { MemoryRouter } from 'react-router-dom';
+import { AppWelcome } from '@/App';
 import { DebateOwlIntro } from '@/components/features/onboarding/DebateOwlIntro';
 import { FirstRun } from '@/components/features/onboarding/FirstRun';
 import { OnboardingTour } from '@/components/features/onboarding/OnboardingTour';
 import { useOnboardingStore } from '@/hooks/use-onboarding';
-import { useDebateStore } from '@/lib/stores/debate-store';
 import { INTRO_SEEN_KEY, firstRunStep, markIntroSeen, shouldShowIntro } from '@/lib/debateowl-intro';
+import { noteTourChunkFailure, resetTourChunkLoadForTests } from '@/lib/onboarding-tour-load';
+import { AuthContext, type AuthContextValue } from '@/lib/supabase/auth-context';
+import { useDebateStore } from '@/lib/stores/debate-store';
 
 function memoryStorage(initial: Record<string, string> = {}) {
   const values = new Map(Object.entries(initial));
@@ -128,17 +132,24 @@ describe('OnboardingTour continuing from the welcome', () => {
   function renderTour(continueFromIntro: boolean) {
     return render(
       <MemoryRouter initialEntries={['/app']}>
-        <div data-tour="current-debate">Current debate</div>
+        <div data-tour="current-debate"><button type="button">Open current debate</button></div>
         <OnboardingTour userId="student-1" continueFromIntro={continueFromIntro} eligibleAt={0} />
       </MemoryRouter>,
     );
   }
 
-  it('opens the Start debate step and not a second welcome dialog', () => {
+  it('opens the Start debate step and not a second welcome dialog', async () => {
     renderTour(true);
     expect(screen.getByText(/Start your first debate here/)).toBeTruthy();
     expect(screen.getByRole('button', { name: 'Start debate' })).toBeTruthy();
     expect(screen.queryByRole('dialog', { name: 'DebateLab is slowly becoming DebateOwl' })).toBeNull();
+    await waitFor(() => {
+      expect(document.activeElement).toBe(document.querySelector('[data-action="primary"]'));
+    });
+    fireEvent.click(screen.getByRole('button', { name: 'Skip tour' }));
+    await waitFor(() => {
+      expect(document.activeElement).toBe(document.querySelector('[data-tour="current-debate"] button'));
+    });
   });
 
   it('stays closed when that account has already finished the tour', () => {
@@ -149,6 +160,85 @@ describe('OnboardingTour continuing from the welcome', () => {
   });
 });
 
+const signedIn: AuthContextValue = {
+  session: null,
+  user: { id: 'student-1' } as User,
+  loading: false,
+  callbackError: null,
+  clearCallbackError: () => undefined,
+  signInWithGoogle: async () => undefined,
+  signInWithEmailOtp: async () => undefined,
+  verifyEmailOtp: async () => undefined,
+  signInWithDemoCode: async () => undefined,
+  signOut: async () => undefined,
+  leaveEnvironment: async () => undefined,
+  discardTabState: () => undefined,
+};
+
+describe('AppWelcome hands the welcome to the Start debate step', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    resetTourChunkLoadForTests();
+    window.history.pushState({}, '', '/app?intro=show');
+    useOnboardingStore.setState({ completedUserIds: [], legacyCompleted: false, isTourRunning: false });
+    useDebateStore.setState({ currentDebateId: null, dialog: null });
+  });
+
+  afterEach(() => {
+    window.history.pushState({}, '', '/');
+  });
+
+  it('Got it closes the welcome into the tour, with focus on the tour and then the card', async () => {
+    render(
+      <AuthContext.Provider value={signedIn}>
+        <MemoryRouter initialEntries={['/app?intro=show']}>
+          <div data-tour="current-debate"><button type="button">Open current debate</button></div>
+          <AppWelcome />
+        </MemoryRouter>
+      </AuthContext.Provider>,
+    );
+
+    const gotIt = await screen.findByRole('button', { name: 'Got it' }, { timeout: 5000 });
+    expect(gotIt).toHaveFocus();
+    fireEvent.click(gotIt);
+
+    expect(await screen.findByText(/Start your first debate here/)).toBeTruthy();
+    expect(screen.queryByRole('dialog', { name: 'DebateLab is slowly becoming DebateOwl' })).toBeNull();
+    expect(localStorage.getItem(INTRO_SEEN_KEY)).toBeTruthy();
+    await waitFor(() => {
+      expect(document.activeElement).toBe(document.querySelector('[data-action="primary"]'));
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: 'Skip tour' }));
+    await waitFor(() => {
+      expect(document.activeElement).toBe(document.querySelector('[data-tour="current-debate"] button'));
+    });
+  });
+});
+
+describe('a tour chunk that fails to load', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    resetTourChunkLoadForTests();
+  });
+
+  it('retries once, then logs once and remembers the welcome', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    expect(noteTourChunkFailure(new Error('offline'))).toBe('retry');
+    expect(localStorage.getItem(INTRO_SEEN_KEY)).toBeNull();
+    expect(warn).not.toHaveBeenCalled();
+
+    expect(noteTourChunkFailure(new Error('offline'))).toBe('give-up');
+    expect(localStorage.getItem(INTRO_SEEN_KEY)).toBeTruthy();
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(String(warn.mock.calls[0]?.[0])).toContain('[Onboarding] Could not load the tour');
+
+    expect(noteTourChunkFailure(new Error('offline'))).toBe('give-up');
+    expect(warn).toHaveBeenCalledTimes(1);
+    warn.mockRestore();
+  });
+});
+
 describe('DebateOwlIntro', () => {
   function renderIntro(owlName?: string) {
     const storage = memoryStorage();