Skip to content

SmythOS Studio: Open-Source Visual AI Agent Builder and deployable runtime stack from SmythOS. Start with an intuitive drag-and-drop workspace, extend with custom code, and deploy your agents anywhere — local, cloud, or edge — with full governance and control.

5.0 KB
Raw Blame
import { useAuthCtx } from '@react/shared/contexts/auth.context';
import { useGetUserSettings, useStoreUserSettings } from '@react/shared/hooks/useUserSettings';
import { TUTORIAL_CUTOFF_DATE } from '@src/shared/constants/tutorial';
import { Observability } from '@src/shared/observability';
import { userSettingKeys } from '@src/shared/userSettingKeys';
import { useEffect, useRef } from 'react';

type UseAgentsPageTutorialOptions = {
  enabled?: boolean;
  maxAttempts?: number;
  intervalMs?: number;
};

/**
 * Triggers the in-app tutorial on the Agents page for new users only.
 * Uses user account creation timestamp to determine if user is new.
 */
export function useAgentsPageTutorial(options: UseAgentsPageTutorialOptions = {}): void {
  const {
    enabled = true,
    maxAttempts = 30, // ~9s total at 300ms
    intervalMs = 300,
  } = options;

  const { data: tutorialSeen, isLoading } = useGetUserSettings(
    userSettingKeys.SEEN_AGENTS_PAGE_TUTORIAL,
  );

  const storeUserSettings = useStoreUserSettings(userSettingKeys.SEEN_AGENTS_PAGE_TUTORIAL);
  const { userInfo } = useAuthCtx();
  const hasStartedRef = useRef(false);

  // Check if user is new based on account creation date
  const isNewUser = userInfo?.user?.createdAt
    ? new Date(userInfo.user.createdAt) > TUTORIAL_CUTOFF_DATE
    : false;

  useEffect(() => {
    if (!enabled || isLoading) return;

    // Check if user is new and hasn't seen the tutorial, or if tutorial has already been started
    if (!isNewUser || tutorialSeen === 'true' || hasStartedRef.current) return;

    let attempts = 0;

    const isReady = () => {
      const TutorialCtor = (window as any)?.Tutorial;
      if (!TutorialCtor) return false;
      const main = document.querySelector('main');
      const sidebar = document.querySelector('div[data-qa="navigation-sidebar"]');
      const searchAgentsInput = document.querySelector('div[data-qa="search-agents-input"]');
      return Boolean(main && sidebar && searchAgentsInput);
    };

    const startTutorial = () => {
      try {
        // Mark as started to prevent multiple triggers
        hasStartedRef.current = true;

        const TutorialCtor = (window as any).Tutorial as any;
        if (!TutorialCtor) return;

        const home_page_onboarding = new TutorialCtor({
          onPopoverRender: (popoverElements: any) => {
            setTimeout(() => {
              popoverElements.popoverTitle.innerText = `${popoverElements.popoverTitle.innerText} (${home_page_onboarding.currentStep + 1}/${home_page_onboarding.getSteps().length})`;
            }, 0);
          },
          onReset: () => {
            // Called when overlay is about to be cleared
            Observability.observeInteraction('home_page_tutorial_completed', {
              page_url: '/agents',
              source: 'Tutorial completed on home page onboarding',
            });

            // Mark tutorial as completed in user settings
            storeUserSettings.mutate('true');
          },
          animate: true,
          showButtons: true,
          nextBtnText: 'Next',
          prevBtnText: 'Previous',
          closeBtnText: 'Close',
          padding: 10,
          overlayOpacity: 0.7,
        });

        home_page_onboarding.defineSteps([
          {
            element: 'main',
            popover: {
              title: '<strong>Welcome to SmythOS</strong>',
              description:
                'This is your team dashboard where you can manage AI agents, access templates, and organize your work.',
              position: 'center',
              align: 'center',
              highlight: true,
            },
          },
          {
            element: 'div[data-qa="navigation-sidebar"]',
            popover: {
              title: '<strong>Main Navigation</strong>',
              description:
                'Use this sidebar to navigate between different sections of SmythOS including Home, Templates, Data Pool, Analytics, Vault, and more.',
              position: 'right',
              align: 'start',
              highlight: true,
            },
          },
          {
            element: 'button[data-qa="create-agent-button"]',
            popover: {
              title: '<strong>Create New Agent</strong>',
              description:
                'Click here to start building a new AI agent from scratch using our visual workflow builder.',
              position: 'bottom',
              align: 'center',
              highlight: true,
            },
          },
        ]);

        home_page_onboarding.start();
      } catch {
        // swallow errors to avoid blocking the page
      }
    };

    const interval = window.setInterval(() => {
      attempts += 1;
      if (isReady()) {
        window.clearInterval(interval);
        startTutorial();
      } else if (attempts >= maxAttempts) {
        window.clearInterval(interval);
      }
    }, intervalMs);

    return () => {
      if (interval) window.clearInterval(interval);
    };
  }, [enabled, maxAttempts, intervalMs, tutorialSeen, storeUserSettings, isNewUser]);
}