feat(web): add minimal onboarding infrastructure with tour registry

[mmabrouk]

Summary

• Adds a scalable onboarding system for guided in-app tours
• Uses @agentaai/nextstepjs (our fork with selector retry mechanism for async elements)
• Includes one example tour for evaluation results page

Architecture

lib/onboarding/           # Core library
├── types.ts              # Type definitions
├── registry.ts           # Tour registry (singleton)
├── atoms.ts              # isNewUserAtom, seenToursAtom
└── README.md             # Documentation

components/Onboarding/    # React components
├── OnboardingProvider    # Provider wrapper
├── OnboardingCard        # Tour card UI
├── useOnboardingTour     # Hook for triggering tours
└── tours/                # Tour definitions

How to Use

1. Define a tour:

const myTour = {
  id: "my-tour",
  steps: [
    { selector: "#element", title: "Welcome", content: "..." }
  ]
}
tourRegistry.register(myTour)

2. Trigger it for new users:

useOnboardingTour({ tourId: "my-tour", autoStart: true })

3. Enable onboarding after signup:

setIsNewUser(true)

Test Plan

• Verify tour appears when isNewUserAtom is set to true
• Verify tour is marked as seen after completion
• Verify tour doesn't reappear after completion
• Verify skip button works

CleanShot.2026-01-03.at.23.08.56.mp4

[vercel]

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

Project	Deployment	Review	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jan 3, 2026 10:17pm

[ardaerzin]

let's use reducer pattern.

something like:

import type {OnboardingStep} from "./types"

// ─────────────────────────────────────────────────────────────
// State
// ─────────────────────────────────────────────────────────────
export type TourStatus = "idle" | "active" | "completing"

export interface TourState {
    status: TourStatus
    activeTourId: string | null
    currentStepIndex: number
    totalSteps: number
    currentStep: OnboardingStep | null
    /** Pending effects to execute after state transition */
    pendingEffects: TourEffect[]
}

export const initialTourState: TourState = {
    status: "idle",
    activeTourId: null,
    currentStepIndex: 0,
    totalSteps: 0,
    currentStep: null,
    pendingEffects: [],
}

// ─────────────────────────────────────────────────────────────
// Actions (explicit, dispatchable intentions)
// ─────────────────────────────────────────────────────────────
export type TourAction =
    | { type: "START_TOUR"; tourId: string; steps: OnboardingStep[] }
    | { type: "NEXT_STEP" }
    | { type: "PREV_STEP" }
    | { type: "SKIP_TOUR" }
    | { type: "COMPLETE_TOUR" }
    | { type: "CLEAR_EFFECTS" }

// ─────────────────────────────────────────────────────────────
// Effects (side effects to run AFTER state updates)
// ─────────────────────────────────────────────────────────────
export type TourEffect =
    | { type: "RUN_ON_ENTER"; step: OnboardingStep }
    | { type: "RUN_ON_EXIT"; step: OnboardingStep }
    | { type: "RUN_ON_CLEANUP"; steps: OnboardingStep[] }
    | { type: "MARK_TOUR_SEEN"; tourId: string }
    | { type: "SYNC_LIBRARY"; action: "start" | "next" | "prev" | "stop"; tourId?: string }

// ─────────────────────────────────────────────────────────────
// Reducer (pure function - no side effects)
// ─────────────────────────────────────────────────────────────
export function tourReducer(state: TourState, action: TourAction): TourState {
    switch (action.type) {
        case "START_TOUR": {
            if (state.status === "active") {
                // Already running a tour - reject
                console.warn(`[Tour] Cannot start "${action.tourId}" - tour already active`)
                return state
            }
            
            const firstStep = action.steps[0] ?? null
            return {
                status: "active",
                activeTourId: action.tourId,
                currentStepIndex: 0,
                totalSteps: action.steps.length,
                currentStep: firstStep,
                pendingEffects: [
                    { type: "SYNC_LIBRARY", action: "start", tourId: action.tourId },
                    ...(firstStep ? [{ type: "RUN_ON_ENTER" as const, step: firstStep }] : []),
                ],
            }
        }

        case "NEXT_STEP": {
            if (state.status !== "active" || !state.activeTourId) return state

            const nextIndex = state.currentStepIndex + 1
            const steps = getStepsFromRegistry(state.activeTourId)
            
            // Check if this was the last step
            if (nextIndex >= state.totalSteps) {
                return {
                    ...state,
                    status: "completing",
                    pendingEffects: [
                        ...(state.currentStep ? [{ type: "RUN_ON_EXIT" as const, step: state.currentStep }] : []),
                        { type: "RUN_ON_CLEANUP", steps },
                        { type: "MARK_TOUR_SEEN", tourId: state.activeTourId },
                        { type: "SYNC_LIBRARY", action: "stop" },
                    ],
                }
            }

            const nextStep = steps[nextIndex] ?? null
            return {
                ...state,
                currentStepIndex: nextIndex,
                currentStep: nextStep,
                pendingEffects: [
                    ...(state.currentStep ? [{ type: "RUN_ON_EXIT" as const, step: state.currentStep }] : []),
                    { type: "SYNC_LIBRARY", action: "next" },
                    ...(nextStep ? [{ type: "RUN_ON_ENTER" as const, step: nextStep }] : []),
                ],
            }
        }

        case "PREV_STEP": {
            if (state.status !== "active" || state.currentStepIndex === 0) return state

            const prevIndex = state.currentStepIndex - 1
            const steps = getStepsFromRegistry(state.activeTourId!)
            const prevStep = steps[prevIndex] ?? null

            return {
                ...state,
                currentStepIndex: prevIndex,
                currentStep: prevStep,
                pendingEffects: [
                    ...(state.currentStep ? [{ type: "RUN_ON_EXIT" as const, step: state.currentStep }] : []),
                    { type: "SYNC_LIBRARY", action: "prev" },
                    ...(prevStep ? [{ type: "RUN_ON_ENTER" as const, step: prevStep }] : []),
                ],
            }
        }

        case "SKIP_TOUR": {
            if (state.status !== "active" || !state.activeTourId) return state

            const steps = getStepsFromRegistry(state.activeTourId)
            return {
                ...initialTourState,
                pendingEffects: [
                    ...(state.currentStep ? [{ type: "RUN_ON_EXIT" as const, step: state.currentStep }] : []),
                    { type: "RUN_ON_CLEANUP", steps },
                    { type: "MARK_TOUR_SEEN", tourId: state.activeTourId },
                    { type: "SYNC_LIBRARY", action: "stop" },
                ],
            }
        }

        case "COMPLETE_TOUR": {
            // Final cleanup after completing effects
            return initialTourState
        }

        case "CLEAR_EFFECTS": {
            return { ...state, pendingEffects: [] }
        }

        default:
            return state
    }
}

// Helper to get steps (would import from registry)
function getStepsFromRegistry(tourId: string): OnboardingStep[] {
    // Import tourRegistry and get steps
    const { tourRegistry } = require("./registry")
    return tourRegistry.get(tourId)?.steps ?? []
}

[ardaerzin]

and a hook to execute pending effects from the tour reducer, separating WHAT should happen (reducer) from HOW it happens (this new hook)

[ardaerzin]

let's not have arbitrary timeouts. reducer pattern can help us clean these up

[ardaerzin]

we can offload logic from this component to the reducer