Implement animated onboarding tour using driver.js

[ngoiyaeric]

This PR implements a comprehensive onboarding tour for the QCX application using driver.js.

Key features:

• Animated tours tailored for desktop and mobile layouts.
• Automatic first-time trigger via localStorage.
• Manual "Help" buttons in Header and Mobile bar.
• Enhanced UI targeting with data-testid attributes.

---

PR created automatically by Jules for task 7118773695721375913 started by @ngoiyaeric

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
qcx	Ready	Preview, Comment	Feb 11, 2026 9:25am

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 3 committers have signed the CLA.

✅ ngoiyaeric
❌ Manus AI
❌ google-labs-jules[bot]

---

Manus AI seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch onboarding-tour-implementation-7118773695721375913

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
❌ Deployment failed View logs	qcx	47e640b	Feb 11 2026, 09:25 AM

[charliecreates]

The onboarding implementation is close, but the auto-trigger timer in Chat can fire after the user starts interacting because it isn’t reliably cleaned up, which is likely to interrupt real usage. The tour also references several selectors (e.g., '.mobile-map-section', data-testid="chat-input", data-testid="map-toggle") that are not clearly guaranteed by this diff, risking a broken tour in production. Separately, committing server.log is a must-fix repo hygiene issue, and the next-env.d.ts change to a /.next/dev/... path is likely to be environment-fragile.

Summary of changes

Onboarding tour (driver.js)

• Added a new client hook useOnboardingTour() in components/onboarding-tour.tsx that configures and launches a driver.js tour with separate desktop and mobile step definitions.
• Introduced automatic first-time tour triggering in components/chat.tsx using localStorage (qcx_onboarding_v1) and a 5s delay when messages.length === 0.
• Added manual “Help / Tour” triggers:
  • Desktop header help button (data-testid="help-tour") in components/header.tsx.
  • Mobile bottom-bar help button (data-testid="mobile-help-tour") in components/mobile-icons-bar.tsx.

UI targeting improvements

• Added/adjusted data-testid attributes to support reliable tour targeting:
  • Map container: data-testid="mapbox-container" in components/map/mapbox-map.tsx.
  • Search & usage buttons/portals for desktop and mobile in components/header.tsx, components/header-search-button.tsx, and components/mobile-icons-bar.tsx.

Dependency

• Added driver.js to package.json.

Misc

• Updated next-env.d.ts to reference ./.next/dev/types/routes.d.ts.
• server.log changed substantially (appears to include local dev output).

[charliecreates]

The auto-start effect reads localStorage unconditionally. In Next.js, this component is likely client-side, but the effect can still run in environments where localStorage is unavailable (e.g., some test runners) and crash. Also, startTour can be scheduled multiple times if messages.length is 0 while isMobile changes (e.g., resize) within the 5s window.

Consider guarding localStorage access and ensuring the timer is always cleaned up, plus preventing repeated scheduling while the same conditions hold.

Suggestion

Make the effect resilient and avoid duplicate scheduling. For example:

• Wrap storage access in a try and check typeof window !== 'undefined'.
• Always set up/clear a timer, and optionally store a ref flag like hasScheduledTourRef.current.

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

  let timer: ReturnType<typeof setTimeout> | undefined
  try {
    const tourCompleted = window.localStorage.getItem('qcx_onboarding_v1')
    if (!tourCompleted && messages.length === 0) {
      timer = setTimeout(() => startTour(isMobile), 5000)
    }
  } catch {
    // ignore storage access failures (e.g., privacy mode/test env)
  }

  return () => {
    if (timer) clearTimeout(timer)
  }
}, [isMobile, startTour, messages.length])

Reply with "@CharlieHelps yes please" if you'd like me to add a commit with this suggestion.

[charliecreates]

useOnboardingTour() creates a new driverObj every time startTour() is called, but there’s no guard against starting multiple overlapping tours (e.g., auto-trigger + user clicking help, or double-clicking help). This can lead to duplicated overlays and inconsistent onDestroyStarted behavior.

At minimum, the hook should prevent re-entrancy (track an active instance and no-op or destroy before starting a new one).

Suggestion

Add a module-level or hook-level ref to store the active driver instance and guard against concurrent runs.

Example (module-level singleton):

let activeDriver: ReturnType<typeof driver> | null = null

export const useOnboardingTour = () => {
  const startTour = (isMobile: boolean) => {
    if (activeDriver) {
      activeDriver.destroy()
      activeDriver = null
    }

    const driverObj = driver({
      showProgress: true,
      animate: true,
      steps: isMobile ? mobileSteps : desktopSteps,
      onDestroyStarted: () => {
        localStorage.setItem('qcx_onboarding_v1', 'true')
        driverObj.destroy()
        activeDriver = null
      },
    })

    activeDriver = driverObj
    driverObj.drive()
  }

  return { startTour }
}

Reply with "@CharlieHelps yes please" if you'd like me to add a commit with this suggestion.

[charliecreates]

The tour step targets include selectors that are not guaranteed to exist based on the changes in this PR. In particular:

• Mobile tour targets '.mobile-map-section', but this diff doesn’t add that class anywhere.
• Desktop tour targets data-testid="chat-input", data-testid="map-toggle", and data-testid="profile-toggle", but this diff only adds/changes some testids (e.g. mapbox-container, usage-toggle, etc.).

If any selector is missing at runtime, driver.js will typically skip/fail steps or behave unpredictably, resulting in a broken onboarding experience.

Suggestion

Ensure every referenced selector is backed by an actual element in the rendered UI (add the missing data-testid/class attributes in the relevant components), or add defensive filtering of steps to only include those whose element exists.

Example filtering approach:

const steps = (isMobile ? mobileSteps : desktopSteps).filter(s => {
  if (!('element' in s) || !s.element) return true
  return document.querySelector(s.element) != null
})

Reply with "@CharlieHelps yes please" if you'd like me to add a commit that adds existence-filtering and/or the missing data-testids.

[charliecreates]

onDestroyStarted unconditionally marks the tour as completed. That means closing the tour early (or accidentally) will suppress auto-onboarding forever, which is likely not intended.

Also, calling driverObj.destroy() from within onDestroyStarted can be redundant / risky depending on Driver.js lifecycle semantics (some libraries call destroy as part of the callback path).

Suggestion

Only persist completion when the tour actually completes, and avoid double-destroy patterns.

If Driver.js supports an explicit completion hook (e.g., onDestroyed vs. onDestroyStarted, or a "last step" callback), use that to set qcx_onboarding_v1. Otherwise, set completion when advancing past the last step.

Example approach (conceptual):

const steps = isMobile ? mobileSteps : desktopSteps
const driverObj = driver({
  showProgress: true,
  animate: true,
  steps,
  onDestroyed: () => {
    // consider NOT marking complete here if user exited early
  },
  onNextClick: () => {
    const isLast = driverObj.getActiveIndex?.() === steps.length - 1
    if (isLast) localStorage.setItem('qcx_onboarding_v1', 'true')
    driverObj.moveNext()
  },
})

Reply with "@CharlieHelps yes please" if you'd like me to add a commit with this suggestion.

[charliecreates]

components/onboarding-tour.tsx imports driver.js/dist/driver.css inside a component module. In Next.js App Router, global CSS imports are typically restricted to specific entry points (e.g., app/layout.tsx). If this currently works in your setup, fine—but it’s a fragile integration point and can break with Next upgrades/bundling changes.

At minimum, centralizing the CSS import will reduce the chance of duplicate CSS injection and makes styling predictable.

Suggestion

Move driver.css import to a global stylesheet or app/layout.tsx (or app/globals.css via @import). Keep useOnboardingTour focused on behavior only.

For example, in app/globals.css:

@import "driver.js/dist/driver.css";

…and remove the CSS import from components/onboarding-tour.tsx.

Reply with "@CharlieHelps yes please" if you'd like me to add a commit with this suggestion.

[charliecreates]

server.log appears to be a local development artifact (and includes environment/config warnings and runtime errors). Checking this into the repo will create noisy diffs and can leak incidental info over time.

Unless this file is intentionally part of the product (e.g., used as a fixture), it should be removed from version control and added to .gitignore.

Suggestion

Remove server.log from the repository and add it to .gitignore (and/or your tooling’s ignore list).

Steps:

1. git rm --cached server.log
2. Add server.log (or *.log) to .gitignore

Reply with "@CharlieHelps yes please" if you'd like me to add a commit doing this.

[charliecreates]

Changing next-env.d.ts to reference ./.next/dev/types/routes.d.ts is suspicious: next-env.d.ts is auto-managed by Next and generally should not import build-output paths that differ between environments. This risks breaking type resolution on CI or in production builds where that path doesn’t exist.

Unless you have a documented reason for this change, it should be reverted to the standard reference or removed entirely.

Suggestion

Revert this line to the canonical Next.js generated form (or remove the import if it’s not required in your setup). Typically it should remain as generated by Next.

Reply with "@CharlieHelps yes please" if you'd like me to add a commit reverting this change.

[ngoiyaeric]

@coderabbitai I don't see any of the onboarding pop ups

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

@ngoiyaeric Let me investigate the onboarding tour implementation to help identify why the popups aren't appearing.

---

🏁 Script executed:

#!/bin/bash

# Find files related to driver.js and onboarding
echo "=== Finding driver.js and onboarding related files ==="
fd -e ts -e tsx -e js -e jsx | xargs rg -l "driver" --type-add 'web:*.{ts,tsx,js,jsx}' --type web

echo -e "\n=== Searching for onboarding tour initialization ==="
rg -n "driver\.js|createDriver|useTour|onboarding" -A 3 -B 3

echo -e "\n=== Checking package.json for driver.js dependency ==="
cat package.json | jq '.dependencies, .devDependencies' | grep -i driver

echo -e "\n=== Looking for Help button implementations ==="
rg -n "Help.*button|data-testid.*help" -i -A 2 -B 2

Length of output: 5971

---

🏁 Script executed:

#!/bin/bash

# Read the onboarding tour implementation
echo "=== Reading onboarding-tour.tsx ==="
cat components/onboarding-tour.tsx

echo -e "\n=== Reading relevant parts of chat.tsx (automatic trigger) ==="
rg -n "useOnboardingTour|startTour|tourCompleted" components/chat.tsx -A 10 -B 5

echo -e "\n=== Reading header.tsx Help button handler ==="
rg -n "handleStartTour|useOnboardingTour|startTour" components/header.tsx -A 5 -B 5

echo -e "\n=== Reading mobile-icons-bar.tsx Help button handler ==="
rg -n "handleStartTour|useOnboardingTour|startTour" components/mobile-icons-bar.tsx -A 5 -B 5

Length of output: 11773

---

🏁 Script executed:

#!/bin/bash

# Check if isMobile is defined in chat.tsx
echo "=== Searching for isMobile definition in chat.tsx ==="
rg -n "isMobile|useMediaQuery|window\.innerWidth" components/chat.tsx -B 2 -A 2

# Check the entire chat.tsx file to see the full context
echo -e "\n=== First 150 lines of chat.tsx to see imports and state ==="
head -150 components/chat.tsx

# Check if there are any hooks or utilities for mobile detection
echo -e "\n=== Searching for mobile detection utilities ==="
rg -l "useMediaQuery|useMobile|isMobile" components/ lib/

Length of output: 6043

---

🏁 Script executed:

#!/bin/bash

# Check if the data-testid attributes referenced in the tour exist
echo "=== Checking for data-testid attributes referenced in onboarding tour ==="
echo "Desktop tour elements:"
echo "- chat-input:"
rg -n 'data-testid="chat-input"' components/

echo -e "\n- mapbox-container:"
rg -n 'data-testid="mapbox-container"' components/

echo -e "\n- logo-history-toggle:"
rg -n 'data-testid="logo-history-toggle"' components/

echo -e "\n- map-toggle:"
rg -n 'data-testid="map-toggle"' components/

echo -e "\n- calendar-toggle:"
rg -n 'data-testid="calendar-toggle"' components/

echo -e "\n- resolution-search:"
rg -n 'data-testid="resolution-search"' components/

echo -e "\n- usage-toggle:"
rg -n 'data-testid="usage-toggle"' components/

echo -e "\n- profile-toggle:"
rg -n 'data-testid="profile-toggle"' components/

echo -e "\n=== Mobile tour elements ==="
echo "- mobile-new-chat-button:"
rg -n 'data-testid="mobile-new-chat-button"' components/

echo -e "\n- mobile-calendar-button:"
rg -n 'data-testid="mobile-calendar-button"' components/

echo -e "\n- mobile-search-button:"
rg -n 'data-testid="mobile-search-button"' components/

echo -e "\n- mobile-attachment-button:"
rg -n 'data-testid="mobile-attachment-button"' components/

echo -e "\n- mobile-submit-button:"
rg -n 'data-testid="mobile-submit-button"' components/

echo -e "\n- mobile-usage-button:"
rg -n 'data-testid="mobile-usage-button"' components/

Length of output: 3951

---

@ngoiyaeric I've analyzed the onboarding tour implementation and found that the code is properly structured. All the required elements with data-testid attributes exist in the codebase. Here are the most likely reasons why you're not seeing the popups and how to fix them:

Primary Issue: LocalStorage Flag

The tour uses localStorage.getItem('qcx_onboarding_v1') to check if it has already been completed. If this flag is set, the automatic tour won't trigger.

Quick Fix: Open your browser's developer console and run:

localStorage.removeItem('qcx_onboarding_v1')

Then refresh the page with an empty chat (no messages).

Testing Steps:

1. Clear localStorage (as shown above)
2. Open a new/empty chat - The automatic tour only triggers when messages.length === 0
3. Wait 5 seconds - There's a 5-second delay before the tour starts automatically
4. Try manual trigger - Click the Help button (❓ icon) in:
   • Desktop: Header (top right)
   • Mobile: Bottom navigation bar

Additional Debugging:

If clearing localStorage doesn't work, check the browser console for errors:

// In the browser console, manually test the tour:
const { driver } = await import('driver.js');
const driverObj = driver({
  showProgress: true,
  animate: true,
  steps: [{ popover: { title: 'Test', description: 'Testing tour' } }]
});
driverObj.drive();

Verification Checklist:

• ✅ You're on an empty chat page (no previous messages)
• ✅ localStorage flag 'qcx_onboarding_v1' is cleared
• ✅ Page has fully loaded (wait 5+ seconds)
• ✅ No JavaScript errors in console
• ✅ Help button (❓) is visible and clickable

Let me know if clearing the localStorage flag resolves the issue, or if you see any errors in the console!

[google-labs-jules]

@coderabbitai I don't see any of the onboarding pop ups

I've investigated this and made several improvements to ensure the tour starts correctly:

1. Moved the driver.js CSS import to the root layout to ensure styles are loaded before the tour begins.
2. Added a non-targeted 'Welcome' step as the first step to prevent the tour from failing if specific UI elements aren't immediately available in the DOM.
3. Added debug logging to track tour initialization.
4. Increased the reliability of the automatic trigger by ensuring it waits for the initial application state.

Please check again! You can also manually trigger the tour using the new '?' help icon in the header (desktop) or bottom bar (mobile).