feat: Guided Tours Framework

package.json

@@ -76,6 +76,7 @@
     "@radix-ui/react-switch": "^1.2.6",
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-tooltip": "^1.2.8",
+    "@reactour/tour": "3.8.0",
     "@tailwindcss/vite": "^4.3.0",
     "@tanstack/history": "1.162.0",
     "@tanstack/react-query": "^5.100.14",

src/components/Learn/FeaturedTours.tsx

@@ -9,6 +9,7 @@ import { APP_ROUTES } from "@/routes/router";
 import { tracking } from "@/utils/tracking";
 
 import { tours as tourCards } from "./tours";
+import { getTour } from "./tours/registry";
 
 interface FeaturedTour {
   id: string;
@@ -30,7 +31,13 @@ function buildFeaturedTours(): FeaturedTour[] {
     const card = tourCards.find((c) => c.id === id);
     if (!card) return [];
     return [
-      { id, title: card.title, duration: card.duration, tag, available: false },
+      {
+        id,
+        title: card.title,
+        duration: card.duration,
+        tag,
+        available: getTour(id) !== undefined,
+      },
     ];
   });
 }
@@ -73,7 +80,7 @@ export function FeaturedTours() {
               key={tour.id}
               variant="ghost"
               size="lg"
-              disabled
+              disabled={!tour.available}
               onClick={() => startTour(tour.id)}
               {...tracking("learning_hub.tours.start", {
                 tour_id: tour.id,

src/components/Learn/ToursLibrary.tsx

@@ -1,3 +1,5 @@
+import { useNavigate } from "@tanstack/react-router";
+
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import {
@@ -10,6 +12,7 @@ import {
 import { Icon } from "@/components/ui/icon";
 import { BlockStack, InlineStack } from "@/components/ui/layout";
 import { Heading, Paragraph, Text } from "@/components/ui/typography";
+import { APP_ROUTES } from "@/routes/router";
 import { tracking } from "@/utils/tracking";
 
 import {
@@ -21,8 +24,19 @@ import {
   type TourDifficulty,
   tours,
 } from "./tours";
+import { getTour } from "./tours/registry";
 
 function TourCard({ tour }: { tour: Tour }) {
+  const isAvailable = getTour(tour.id) !== undefined;
+  const navigate = useNavigate();
+
+  const startTour = () => {
+    void navigate({
+      to: APP_ROUTES.TOUR_DETAIL,
+      params: { tourId: tour.id },
+    });
+  };
+
   return (
     <Card className="h-full py-4 gap-2 hover:border-primary/40 hover:shadow-md transition-all duration-200">
       <CardHeader className="px-4 gap-2">
@@ -41,14 +55,26 @@ function TourCard({ tour }: { tour: Tour }) {
               {tour.duration}
             </Text>
           </InlineStack>
-          <Button
-            size="sm"
-            variant="ghost"
-            {...tracking("learning_hub.tours.start", { tour_id: tour.id })}
-          >
-            Start tour
-            <Icon name="Play" size="sm" aria-hidden="true" />
-          </Button>
+          {isAvailable ? (
+            <Button
+              size="sm"
+              variant="ghost"
+              onClick={startTour}
+              {...tracking("learning_hub.tours.start", { tour_id: tour.id })}
+            >
+              Start tour
+              <Icon name="Play" size="sm" aria-hidden="true" />
+            </Button>
+          ) : (
+            <Button
+              size="sm"
+              variant="ghost"
+              disabled
+              {...tracking("learning_hub.tours.start", { tour_id: tour.id })}
+            >
+              Coming soon
+            </Button>
+          )}
         </InlineStack>
       </CardContent>
     </Card>

src/components/Learn/tours/registry.ts

@@ -0,0 +1,33 @@
+import type { StepType } from "@reactour/tour";
+
+import { publicAsset } from "@/utils/publicAsset";
+
+export type TourStep = StepType & {
+  interaction?: "undock-window" | "redock-window" | "select-task";
+  targetWindowId?: string;
+  fallbackContent?: string;
+};
+
+export interface TourDefinition {
+  id: string;
+  displayName?: string;
+  requiresEditor?: boolean;
+  starterPipelineUrl?: string;
+  steps: TourStep[];
+}
+
+const tourModules = import.meta.glob<TourDefinition>("./*.tour.json", {
+  eager: true,
+  import: "default",
+});
+
+const tours: TourDefinition[] = Object.values(tourModules).map((tour) => ({
+  ...tour,
+  starterPipelineUrl: tour.starterPipelineUrl
+    ? publicAsset(tour.starterPipelineUrl)
+    : undefined,
+}));
+
+export function getTour(id: string): TourDefinition | undefined {
+  return tours.find((tour) => tour.id === id);
+}

src/components/layout/AppMenu.tsx

@@ -196,6 +196,10 @@ const AppMenu = () => {
     return null;
   }
 
+  if (pathname.startsWith(APP_ROUTES.TOUR)) {
+    return null;
+  }
+
   return <DefaultAppMenu />;
 };
 

src/components/layout/RootLayout.tsx

@@ -9,6 +9,7 @@ import { useSessionPipelineStats } from "@/hooks/useSessionPipelineStats";
 import { AnalyticsProvider } from "@/providers/AnalyticsProvider";
 import { BackendProvider } from "@/providers/BackendProvider";
 import { ComponentSpecProvider } from "@/providers/ComponentSpecProvider";
+import { TourProvider } from "@/providers/TourProvider/TourProvider";
 import { PipelineStorageProvider } from "@/services/pipelineStorage/PipelineStorageProvider";
 
 import AppMenu from "./AppMenu";
@@ -26,20 +27,22 @@ function RootLayoutContent() {
     <BackendProvider>
       <ComponentSpecProvider>
         <PipelineStorageProvider>
-          <SessionPipelineStatsTracker />
-          <ToastContainer />
-
-          <div className="App flex flex-col min-h-screen w-full">
-            <AppMenu />
-
-            <main className="flex-1 grid">
-              <Outlet />
-            </main>
-
-            {import.meta.env.VITE_ENABLE_ROUTER_DEVTOOLS === "true" && (
-              <TanStackRouterDevtools />
-            )}
-          </div>
+          <TourProvider>
+            <SessionPipelineStatsTracker />
+            <ToastContainer />
+
+            <div className="App flex flex-col min-h-screen w-full">
+              <AppMenu />
+
+              <main className="flex-1 grid">
+                <Outlet />
+              </main>
+
+              {import.meta.env.VITE_ENABLE_ROUTER_DEVTOOLS === "true" && (
+                <TanStackRouterDevtools />
+              )}
+            </div>
+          </TourProvider>
         </PipelineStorageProvider>
       </ComponentSpecProvider>
     </BackendProvider>

src/providers/TourProvider/TourContent.tsx

@@ -0,0 +1,31 @@
+import { Fragment, type ReactNode } from "react";
+
+const INLINE_TOKEN = /(\*\*[^*]+\*\*|_[^_]+_|`[^`]+`)/g;
+
+function renderInline(text: string): ReactNode[] {
+  return text.split(INLINE_TOKEN).map((part, index) => {
+    if (part.startsWith("**") && part.endsWith("**")) {
+      return <strong key={index}>{part.slice(2, -2)}</strong>;
+    }
+    if (part.startsWith("_") && part.endsWith("_")) {
+      return <em key={index}>{part.slice(1, -1)}</em>;
+    }
+    if (part.startsWith("`") && part.endsWith("`")) {
+      return <code key={index}>{part.slice(1, -1)}</code>;
+    }
+    return <Fragment key={index}>{part}</Fragment>;
+  });
+}
+
+export function TourContent({ text }: { text: string }) {
+  const paragraphs = text.split(/\n{2,}/);
+  return (
+    <>
+      {paragraphs.map((paragraph, index) => (
+        <p key={index} className={index > 0 ? "mt-2" : undefined}>
+          {renderInline(paragraph)}
+        </p>
+      ))}
+    </>
+  );
+}

src/providers/TourProvider/TourModeContext.tsx

@@ -0,0 +1,28 @@
+import { createContext, type ReactNode, useContext } from "react";
+
+import type { TourDefinition } from "@/components/Learn/tours/registry";
+
+export interface TourModeValue {
+  tour: TourDefinition;
+  tempPipelineName: string;
+}
+
+const TourModeContext = createContext<TourModeValue | null>(null);
+
+export function TourModeProvider({
+  value,
+  children,
+}: {
+  value: TourModeValue;
+  children: ReactNode;
+}) {
+  return (
+    <TourModeContext.Provider value={value}>
+      {children}
+    </TourModeContext.Provider>
+  );
+}
+
+export function useTourMode(): TourModeValue | null {
+  return useContext(TourModeContext);
+}