[feature] Add user onboarding

web/ee/docker/Dockerfile.dev

@@ -18,7 +18,7 @@ COPY ee/package.json ./ee/yarn.lock* ./ee/package-lock.json* ./ee/pnpm-lock.yaml
 COPY oss/package.json ./oss/yarn.lock* ./oss/package-lock.json* ./oss/pnpm-lock.yaml* ./oss/.npmrc* ./oss/
 COPY ./pnpm-workspace.yaml ./turbo.json ./
 
-COPY ./entrypoint.sh /app/entrypoint.sh   
+COPY ./entrypoint.sh /app/entrypoint.sh
 
 RUN pnpm i
 

web/oss/package.json

@@ -95,6 +95,8 @@
         "lexical": "^0.38.2",
         "lodash": "^4.17.21",
         "lucide-react": "^0.475.0",
+        "motion": "^12.23.24",
+        "@agentaai/nextstepjs": "^2.1.3-agenta.1",
         "next": "15.5.9",
         "papaparse": "^5.5.3",
         "postcss": "^8.5.6",
@@ -137,4 +139,4 @@
         "node-mocks-http": "^1.17.2",
         "tailwind-scrollbar": "^3"
     }
-}
+}

web/oss/src/components/DeploymentsDashboard/components/Drawer/index.tsx

@@ -3,10 +3,11 @@ import {ComponentProps, ReactNode, useState} from "react"
 import {CloseOutlined, FullscreenExitOutlined, FullscreenOutlined} from "@ant-design/icons"
 import {Button, Divider, Drawer} from "antd"
 import clsx from "clsx"
-import {useAtomValue} from "jotai"
+import {useAtomValue, useSetAtom} from "jotai"
 import {createUseStyles} from "react-jss"
 
 import {envRevisionsAtom} from "@/oss/components/DeploymentsDashboard/atoms"
+import {openSelectDeployVariantModalAtom} from "@/oss/components/DeploymentsDashboard/modals/store/deploymentModalsStore"
 import EnhancedDrawer from "@/oss/components/EnhancedUIs/Drawer"
 import {JSSTheme} from "@/oss/lib/Types"
 import {revisionListAtom} from "@/oss/state/variant/selectors/variant"
@@ -98,6 +99,8 @@ const DeploymentsDrawerContent = ({
 }: DeploymentsDrawerProps) => {
     const variants = useAtomValue(revisionListAtom) || []
     const envRevisions = useAtomValue(envRevisionsAtom)
+    const openSelectDeployVariantModal = useSetAtom(openSelectDeployVariantModalAtom)
+
     return (
         <div className="flex h-full">
             <div className={`flex-1 overflow-auto ${mainContentClassName}`}>
@@ -118,7 +121,9 @@ const DeploymentsDrawerContent = ({
                 >
                     {envRevisions ? (
                         <UseApiContent
-                            handleOpenSelectDeployVariantModal={() => close()}
+                            handleOpenSelectDeployVariantModal={() =>
+                                openSelectDeployVariantModal({variants, envRevisions})
+                            }
                             variants={variants}
                             revisionId={drawerVariantId}
                             selectedEnvironment={envRevisions}

web/oss/src/components/DeploymentsDashboard/index.tsx

@@ -98,6 +98,7 @@ const DeploymentsDashboard: FC<DeploymentsDashboardProps> = ({
                     <Button
                         type="primary"
                         onClick={() => envRevisions && openDeploymentsDrawer({initialWidth: 720})}
+                        id="tour-setup-prompt"
                     >
                         Use API
                     </Button>

web/oss/src/components/Layout/Layout.tsx

@@ -22,11 +22,15 @@ import CustomWorkflowBanner from "../CustomWorkflowBanner"
 import ProtectedRoute from "../ProtectedRoute/ProtectedRoute"
 
 import BreadcrumbContainer from "./assets/Breadcrumbs"
-import {useStyles} from "./assets/styles"
+import {StyleProps, useStyles} from "./assets/styles"
 import ErrorFallback from "./ErrorFallback"
 import {SidebarIsland} from "./SidebarIsland"
 import {getDeviceTheme, useAppTheme} from "./ThemeContextProvider"
 
+const OnboardingWidget = dynamic(() => import("../Onboarding/components/OnboardingWidget"), {
+    ssr: false,
+    loading: () => null,
+})
 const FooterIsland = dynamic(() => import("./FooterIsland").then((m) => m.FooterIsland), {
     ssr: false,
     loading: () => null,
@@ -305,6 +309,7 @@ const App: React.FC<LayoutProps> = ({children}) => {
                         {children}
                         {contextHolder}
                     </AppWithVariants>
+                    <OnboardingWidget />
                 </ProtectedRoute>
             )}
         </Suspense>

web/oss/src/components/Onboarding/components/CustomNextStepProvider/index.tsx

@@ -0,0 +1,115 @@
+import {useEffect, useRef} from "react"
+
+import {useAtomValue, useSetAtom} from "jotai"
+import {NextStep, useNextStep} from "@agentaai/nextstepjs"
+
+import {
+    isNewUserAtom,
+    onboardingStepsAtom,
+    triggerOnboardingAtom,
+    userOnboardingStatusAtom,
+} from "@/oss/state/onboarding"
+import {urlLocationAtom} from "@/oss/state/url"
+
+import OnboardingCard from "../../index"
+import OnboardingAutoAdvance from "../OnboardingAutoAdvance"
+
+const CustomNextStepProvider = ({children}: {children: React.ReactNode}) => {
+    const onboardingSteps = useAtomValue(onboardingStepsAtom)
+    const isNewUser = useAtomValue(isNewUserAtom)
+    const userLocation = useAtomValue(urlLocationAtom)
+    const userOnboardingJourneyStatus = useAtomValue(userOnboardingStatusAtom)
+    const manualTrigger = useAtomValue(triggerOnboardingAtom)
+    const setTriggerOnboarding = useSetAtom(triggerOnboardingAtom)
+    const {startNextStep} = useNextStep()
+    const autoStartSignatureRef = useRef<string | null>(null)
+
+    const previousSectionRef = useRef(userLocation.resolvedSection ?? userLocation.section)
+    useEffect(() => {
+        const resolvedSection = userLocation.resolvedSection ?? userLocation.section
+        if (previousSectionRef.current !== resolvedSection) {
+            previousSectionRef.current = resolvedSection
+            if (!manualTrigger) {
+                setTriggerOnboarding(null)
+            }
+        }
+    }, [userLocation.resolvedSection, userLocation.section, manualTrigger, setTriggerOnboarding])
+
+    useEffect(() => {
+        if (!isNewUser) {
+            autoStartSignatureRef.current = null
+            return
+        }
+
+        const normalizedSection = userLocation.resolvedSection
+        if (!normalizedSection) {
+            autoStartSignatureRef.current = null
+            return
+        }
+
+        if (!onboardingSteps?.length) {
+            autoStartSignatureRef.current = null
+            return
+        }
+
+        const currentTour = onboardingSteps[0]
+        if (!currentTour?.tour) return
+
+        const tourSection =
+            (currentTour.steps?.find((step) => step?.onboardingSection)
+                ?.onboardingSection as keyof typeof userOnboardingJourneyStatus) ??
+            normalizedSection
+
+        const signature = `${tourSection}:${currentTour.tour}:${currentTour.steps?.length ?? 0}`
+        if (autoStartSignatureRef.current === signature) return
+
+        autoStartSignatureRef.current = signature
+
+        startNextStep(currentTour.tour)
+    }, [
+        isNewUser,
+        userLocation.resolvedSection,
+        userOnboardingJourneyStatus,
+        onboardingSteps,
+        startNextStep,
+    ])
+
+    const lastManualTriggerRef = useRef<typeof manualTrigger>(null)
+    useEffect(() => {
+        if (!manualTrigger) {
+            lastManualTriggerRef.current = null
+            return
+        }
+        if (!onboardingSteps?.length) return
+        if (lastManualTriggerRef.current === manualTrigger) return
+
+        lastManualTriggerRef.current = manualTrigger
+        const targetTour =
+            manualTrigger.tourId !== undefined
+                ? (onboardingSteps.find((tour) => tour.tour === manualTrigger.tourId) ??
+                  onboardingSteps[0])
+                : onboardingSteps[0]
+        const tourId = targetTour?.tour
+        if (!tourId) return
+
+        startNextStep(tourId)
+    }, [manualTrigger, onboardingSteps, startNextStep])
+
+    const handleComplete = () => {
+        setTriggerOnboarding(null)
+    }
+
+    return (
+        <NextStep
+            steps={onboardingSteps}
+            cardComponent={OnboardingCard}
+            showNextStep={true}
+            onComplete={handleComplete}
+        >
+            <OnboardingAutoAdvance />
+            {children}
+        </NextStep>
+    )
+}
+
+export default CustomNextStepProvider

web/oss/src/components/Onboarding/components/NextViewport/index.tsx

@@ -0,0 +1,67 @@
+import {forwardRef, useEffect, useRef, type MutableRefObject, type ReactNode} from "react"
+
+import clsx from "clsx"
+
+interface NextViewportProps {
+    id: string
+    className?: string
+    children: ReactNode
+}
+
+const NextViewport = forwardRef<HTMLDivElement, NextViewportProps>(
+    ({id, className, children}, forwardedRef) => {
+        const containerRef = useRef<HTMLDivElement | null>(null)
+
+        useEffect(() => {
+            const node = containerRef.current
+            if (typeof window === "undefined" || !node) return
+
+            let animationFrame: number | null = null
+            const notifyViewportChange = () => {
+                window.dispatchEvent(new CustomEvent("nextstep:viewport-scroll", {detail: {id}}))
+                window.dispatchEvent(new Event("resize"))
+            }
+
+            const scheduleNotification = () => {
+                if (animationFrame) cancelAnimationFrame(animationFrame)
+                animationFrame = window.requestAnimationFrame(() => {
+                    notifyViewportChange()
+                })
+            }
+
+            const resizeObserver =
+                typeof ResizeObserver !== "undefined"
+                    ? new ResizeObserver(() => scheduleNotification())
+                    : null
+
+            resizeObserver?.observe(node)
+            node.addEventListener("scroll", scheduleNotification, {passive: true})
+            scheduleNotification()
+
+            return () => {
+                node.removeEventListener("scroll", scheduleNotification)
+                resizeObserver?.disconnect()
+                if (animationFrame) cancelAnimationFrame(animationFrame)
+            }
+        }, [id])
+
+        const setRef = (node: HTMLDivElement | null) => {
+            containerRef.current = node
+            if (typeof forwardedRef === "function") {
+                forwardedRef(node)
+            } else if (forwardedRef) {
+                ;(forwardedRef as MutableRefObject<HTMLDivElement | null>).current = node
+            }
+        }
+
+        return (
+            <div id={id} ref={setRef} className={clsx("relative h-full w-full", className)}>
+                {children}
+            </div>
+        )
+    },
+)
+
+NextViewport.displayName = "NextViewport"
+
+export default NextViewport

web/oss/src/components/Onboarding/components/OnboardingAutoAdvance/index.tsx

@@ -0,0 +1,97 @@
+import {useEffect, useMemo} from "react"
+
+import {useAtomValue, useSetAtom} from "jotai"
+import {useNextStep} from "@agentaai/nextstepjs"
+
+import {
+    onboardingStepsAtom,
+    triggerOnboardingAtom,
+    updateUserOnboardingStatusAtom,
+} from "@/oss/state/onboarding"
+import type {OnboardingStep, UserOnboardingStatus} from "@/oss/state/onboarding/types"
+import {urlLocationAtom} from "@/oss/state/url"
+
+const OnboardingAutoAdvance = () => {
+    const onboardingTours = useAtomValue(onboardingStepsAtom)
+    const updateUserOnboardingStatus = useSetAtom(updateUserOnboardingStatusAtom)
+    const setTriggerOnboarding = useSetAtom(triggerOnboardingAtom)
+    const userLocation = useAtomValue(urlLocationAtom)
+    const {currentTour, currentStep, isNextStepVisible, setCurrentStep, closeNextStep} =
+        useNextStep()
+
+    const {activeStep, totalSteps} = useMemo(() => {
+        if (!currentTour) {
+            return {activeStep: null, totalSteps: 0}
+        }
+
+        const matchingTour = onboardingTours.find((tour) => tour.tour === currentTour)
+        if (!matchingTour) {
+            return {activeStep: null, totalSteps: 0}
+        }
+
+        const step = matchingTour.steps[currentStep] as OnboardingStep | undefined
+        return {activeStep: step ?? null, totalSteps: matchingTour.steps.length}
+    }, [currentTour, currentStep, onboardingTours])
+
+    const resolvedSectionFromLocation = useMemo(
+        () => userLocation.resolvedSection ?? userLocation.section,
+        [userLocation.resolvedSection, userLocation.section],
+    )
+
+    useEffect(() => {
+        if (!activeStep?.advanceOnClick || !activeStep.selector || !isNextStepVisible) {
+            return
+        }
+
+        const handleClick = async (event: MouseEvent) => {
+            if (!activeStep.selector) return
+
+            const target = event.target
+            if (!(target instanceof Element)) return
+
+            const matchedTarget = target.closest(activeStep.selector)
+            if (!matchedTarget) {
+                return
+            }
+
+            try {
+                await activeStep.onNext?.()
+            } catch (error) {
+                console.error("Failed to run onboarding advance handler", error)
+            }
+
+            if (currentStep >= totalSteps - 1) {
+                const resolvedSection =
+                    (activeStep?.onboardingSection as keyof UserOnboardingStatus | undefined) ??
+                    resolvedSectionFromLocation
+                if (resolvedSection) {
+                    updateUserOnboardingStatus({section: resolvedSection, status: "done"})
+                }
+                setTriggerOnboarding(null)
+                closeNextStep()
+                return
+            }
+
+            setCurrentStep(currentStep + 1)
+        }
+
+        document.addEventListener("click", handleClick, true)
+        return () => {
+            document.removeEventListener("click", handleClick, true)
+        }
+    }, [
+        activeStep,
+        currentStep,
+        totalSteps,
+        isNextStepVisible,
+        closeNextStep,
+        setCurrentStep,
+        resolvedSectionFromLocation,
+        setTriggerOnboarding,
+        updateUserOnboardingStatus,
+    ])
+
+    return null
+}
+
+export default OnboardingAutoAdvance