feat: Learning Hub Tour Framework

[camielvs]

Description

Foundational groundwork for guided tours in the UI, built on Reactour. Tours live at their own URL (/tour/$tourId) so they're refreshable, shareable, and own their lifecycle cleanly.

Supports forward/back controls, interactive activities ("click here", "drag this"), dynamic highlighting of relevant UI elements, and inline-markdown step copy (**bold**, _italic_, `code`, paragraph breaks). Interactive steps include fallback copy when the prompted state is already satisfied.

Tours run inside a fresh ephemeral pipeline (__tour__<slug>). When the user leaves the tour route the pipeline is deleted — tours have no save state, every visit starts fresh. "Save as new pipeline" in the editor's tour-mode action bar promotes the temp pipeline into a regular one.

Architecture

Route (/tour/$tourId, src/routes/Dashboard/Learn/Tour.tsx)

• Owns the tour pipeline lifecycle: creates a fresh __tour__<slug> on mount, deletes it on unmount unless promoted
• Snapshots the editor's window layout on entry, restores it on exit so the user's saved arrangement isn't disturbed
• Bridges the URL's ?step=N and reactour's internal currentStep so browser back/forward navigates tour steps
• Defers reactour activation until the editor DOM mounts (waitForSelector('[data-testid="editor-v2"]'))
• Falls back to /learn/tours if tourId doesn't match a registered tour

Tour mode context (src/providers/TourProvider/TourModeContext.tsx)

• Exposes useTourMode() to editor components: { tour, tempPipelineName, markPipelinePromoted }
• Editor menu bar uses this to render a "Tour" badge, hide rename/delete actions in the File menu, and show Resume / Save as new pipeline / Exit buttons while the popover is dismissed

Reactour wrapper (src/providers/TourProvider/TourProvider.tsx)

• Wraps the app in <TourProvider> from reactour with custom Prev / Next / Finish buttons and styling
• Finish navigates to /learn/tours; X / ESC dismiss the popover but stay on the route so the user can poke around or resume
• Clamps the popover to the viewport so the step badge isn't clipped near screen edges
• data-tour-anchor="no-spotlight" sentinel lets a step open a centered popover with no highlight cutout

Editor bridge (src/routes/v2/pages/Editor/components/EditorTourBridge.tsx)

• Implements three interaction primitives a step can declare: interaction: "undock-window" | "redock-window" | "select-task"
• Follows window positions so the highlight tracks a floating panel as the user drags it
• select-task detects clicks on a stable [data-tour-node="task"] ancestor (not a library CSS class) so task selection only counts for true task nodes, not IO ports

Orphan cleanup (src/providers/TourProvider/TourOrphanCleanup.tsx)

• Sweeps __tour__* pipelines on app load to catch tab-close / crash orphans. Route unmount handles every normal exit path; this covers what the browser kills before we can run.

Layout snapshot (src/routes/v2/shared/windows/windowPersistence.ts)

• snapshotLayout / restoreLayout stash the editor's persisted window arrangement so a tour can mutate it freely and roll back on exit

Learn page wiring — FeaturedTours and ToursLibrary link directly to /tour/$tourId for registered tours; unregistered IDs render as "Coming soon"

Registry is intentionally empty

src/components/Learn/tours/registry.ts ships with const tours: TourDefinition[] = []. Until the first tour is registered (see #2306), every tile on the Learn page renders as "Coming soon". This keeps the framework merge-safe on its own.

How to add a tour

1. Create src/components/Learn/tours/<yourTour>.tour.json exporting a TourDefinition
2. Import + push into the tours array in registry.ts
3. Use stable data-* anchors on the UI elements your steps target. The codebase already exposes:
   • data-tour="..." for panels and bars you add as you go
   • data-dock-area, data-dock-window, data-dock-window-content, data-window-id for the dock/window system
   • data-tour-anchor="no-spotlight" to open a step with a centered popover and no highlight

Related Issue and Pull requests

Progresses https://github.com/Shopify/oasis-frontend/issues/583

Type of Change

• New feature

Checklist

• I have tested this does not break current pipelines / runs functionality
• I have tested the changes on staging

Screenshots

Test Instructions

With the registry empty, the visible behavior is:

• /learn/tours and the dashboard Featured Tours tile render every tour as "Coming soon"
• No tour can be started; no tour UI appears anywhere
• Existing editor / runs / dashboard flows are unaffected
• Navigating to /tour/anything redirects to /learn/tours

Regression check: confirm pipelines list, editor menu bar, dockable / floating windows, and task nodes behave identically to master — none of the tour engine should be visible until a tour registers.

Additional Comments

More tours are intended to follow the first one, covering a range of topics.

[camielvs]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat: Guided Tour - Navigating the Editor #2306 : 2 dependent PRs (#2307 , #2312 )
• feat: Learning Hub Tour Framework #2299 👈 (View in Graphite)
• feat: Learning Hub Guided Tours #2297
• feat: Learning Hub Tip of the Day #2292
• feat: Learning Hub Tip Browser #2291
• feat: Learning Hub Example Pipelines #2283
• feat: Learning Hub Documentation & FAQ #2282
• feat: Learning Hub Dashboard #2281
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

🎩 Preview

A preview build has been created at: 05-20-feat_learning_hub_tour_framework_and_first_tour/b4ca659