feat: Learning Hub Tour 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.11",

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,
+      },
     ];
   });
 }
@@ -68,7 +75,7 @@ export function FeaturedTours() {
               key={tour.id}
               variant="ghost"
               size="lg"
-              disabled
+              disabled={!tour.available}
               className="w-full"
               {...tracking("learning_hub.tours.start", {
                 tour_id: tour.id,

src/components/Learn/ToursLibrary.tsx

@@ -1,3 +1,5 @@
+import { Link } 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,11 @@ import {
   type TourDifficulty,
   tours,
 } from "./tours";
+import { getTour } from "./tours/registry";
 
 function TourCard({ tour }: { tour: Tour }) {
+  const isAvailable = getTour(tour.id) !== undefined;
+
   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 +47,28 @@ 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
+              asChild
+              size="sm"
+              variant="ghost"
+              {...tracking("learning_hub.tours.start", { tour_id: tour.id })}
+            >
+              <Link to={APP_ROUTES.TOUR_DETAIL} params={{ tourId: tour.id }}>
+                Start tour
+                <Icon name="Play" size="sm" aria-hidden="true" />
+              </Link>
+            </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/TourModeContext.tsx

@@ -0,0 +1,30 @@
+import { createContext, type ReactNode, useContext } from "react";
+
+import type { TourDefinition } from "@/components/Learn/tours/registry";
+
+export interface TourModeValue {
+  tour: TourDefinition;
+  tempPipelineName: string;
+  // Suppresses the route's on-unmount delete after a Save-as promotion.
+  markPipelinePromoted: () => void;
+}
+
+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);
+}

src/providers/TourProvider/TourOrphanCleanup.tsx

@@ -0,0 +1,22 @@
+import { useRouterState } from "@tanstack/react-router";
+import { useEffect } from "react";
+
+import { APP_ROUTES } from "@/routes/router";
+import { usePipelineStorage } from "@/services/pipelineStorage/PipelineStorageProvider";
+
+import { cleanupOrphanTourPipelines } from "./tourPipelineLifecycle";
+
+export function TourOrphanCleanup() {
+  const storage = usePipelineStorage();
+  const pathname = useRouterState({
+    select: (state) => state.location.pathname,
+  });
+
+  useEffect(() => {
+    // Skip on tour routes so we don't race the route's own create flow.
+    if (pathname.startsWith(APP_ROUTES.TOUR)) return;
+    void cleanupOrphanTourPipelines(storage);
+  }, [storage, pathname]);
+
+  return null;
+}

src/providers/TourProvider/TourProvider.tsx

@@ -0,0 +1,32 @@
+import { TourProvider as ReactourProvider } from "@reactour/tour";
+import type { ReactNode } from "react";
+
+import { TourOrphanCleanup } from "./TourOrphanCleanup";
+import {
+  computeDefaultPopoverPosition,
+  POPOVER_STYLES,
+  PopoverClampBridge,
+  renderNextButton,
+} from "./tourPopover";
+
+export function TourProvider({ children }: { children: ReactNode }) {
+  return (
+    <ReactourProvider
+      steps={[]}
+      styles={POPOVER_STYLES}
+      scrollSmooth
+      showBadge
+      showCloseButton={false}
+      showNavigation
+      showPrevNextButtons
+      padding={{ mask: 0, popover: 10 }}
+      position={computeDefaultPopoverPosition}
+      nextButton={renderNextButton}
+      onClickMask={() => undefined}
+    >
+      <PopoverClampBridge />
+      <TourOrphanCleanup />
+      {children}
+    </ReactourProvider>
+  );
+}