feat: Guided Tours Foundation

package.json

@@ -78,6 +78,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.101.0",

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)}
               className="h-auto min-h-10 w-full justify-start whitespace-normal py-2 text-left"
               {...tracking("learning_hub.tours.start", {

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,29 @@
+import type { StepType } from "@reactour/tour";
+
+import { publicAsset } from "@/utils/publicAsset";
+
+type TourStep = StepType;
+
+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/components/ui/dropdown-menu.tsx

@@ -1,23 +1,47 @@
 import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
 import {
+  type ComponentProps,
   type ComponentPropsWithoutRef,
   type ComponentRef,
   forwardRef,
   type HTMLAttributes,
 } from "react";
 
 import { Icon } from "@/components/ui/icon";
+import { dispatchResizeOnToggle } from "@/lib/dispatchResizeOnToggle";
 import { cn } from "@/lib/utils";
 
-const DropdownMenu = DropdownMenuPrimitive.Root;
+const DropdownMenu = ({
+  onOpenChange,
+  ...props
+}: ComponentProps<typeof DropdownMenuPrimitive.Root>) => (
+  <DropdownMenuPrimitive.Root
+    onOpenChange={(open) => {
+      dispatchResizeOnToggle(open);
+      onOpenChange?.(open);
+    }}
+    {...props}
+  />
+);
 
 const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger;
 
 const DropdownMenuGroup = DropdownMenuPrimitive.Group;
 
 const DropdownMenuPortal = DropdownMenuPrimitive.Portal;
 
-const DropdownMenuSub = DropdownMenuPrimitive.Sub;
+const DropdownMenuSub = ({
+  onOpenChange,
+  ...props
+}: ComponentProps<typeof DropdownMenuPrimitive.Sub>) => (
+  <DropdownMenuPrimitive.Sub
+    onOpenChange={(open) => {
+      dispatchResizeOnToggle(open);
+      onOpenChange?.(open);
+    }}
+    {...props}
+  />
+);
 
 const DropdownMenuRadioGroup = DropdownMenuPrimitive.RadioGroup;
 

src/components/ui/popover.tsx

@@ -1,12 +1,23 @@
 import * as PopoverPrimitive from "@radix-ui/react-popover";
 import * as React from "react";
 
+import { dispatchResizeOnToggle } from "@/lib/dispatchResizeOnToggle";
 import { cn } from "@/lib/utils";
 
 function Popover({
+  onOpenChange,
   ...props
 }: React.ComponentProps<typeof PopoverPrimitive.Root>) {
-  return <PopoverPrimitive.Root data-slot="popover" {...props} />;
+  return (
+    <PopoverPrimitive.Root
+      data-slot="popover"
+      onOpenChange={(open) => {
+        dispatchResizeOnToggle(open);
+        onOpenChange?.(open);
+      }}
+      {...props}
+    />
+  );
 }
 
 function PopoverTrigger({

src/lib/dispatchResizeOnToggle.ts

@@ -0,0 +1,13 @@
+// Nudges layout-sensitive listeners (reactour spotlights, floating UI) to
+// re-measure after a portaled element opens or closes. The trailing dispatch
+// covers exit animations.
+export function dispatchResizeOnToggle(open: boolean): void {
+  requestAnimationFrame(() => {
+    window.dispatchEvent(new Event("resize"));
+  });
+  if (!open) {
+    setTimeout(() => {
+      window.dispatchEvent(new Event("resize"));
+    }, 250);
+  }
+}