feat: Guided Tours Framework

[camielvs]

Description

The guided-tour engine built on Reactour, exposed as a dedicated /tour/$tourId route so tours are refreshable, shareable, and own their lifecycle cleanly.

Supports forward/back controls, interactive activities (select-task, undock-window, redock-window), dynamic highlighting, and inline-markdown step copy (**bold**, _italic_, `code`, paragraph breaks). Interactive steps include fallback copy when the prompted state is already satisfied.

Tours are modal — once started, the user can only exit via the explicit Exit Tour button or the Done button on the final step. ESC, the close (X) button, and clicks on the mask are all disabled, so a tour can't be silently paused or dismissed mid-run.

Registry ships empty (tours: TourDefinition[] = []); the first tour lands in #2306. Until then every Learn-page card stays "Coming soon" and the framework merge is invisible to users.

Architecture

Route (src/routes/Dashboard/Learn/Tour.tsx)

• Resolves the tourId param against the registry; falls back to /learn/tours if unknown.
• Resolves or creates a temporary pipeline (__tour__<slug>) and renders the editor against it.
• Always renders <TourModeProvider> + <EditorV2> from the first frame — the editor body shows a small loading skeleton while the temp pipeline resolves, so the menu bar stays mounted and there's no perceptible flicker on entry.
• Bridges the URL's ?step=N and reactour's currentStep so browser back/forward navigates tour steps.
• Defers reactour activation until the editor DOM mounts (waitForSelector('[data-testid="editor-v2"]')).
• Snapshots the editor's window layout on entry, restores it on exit so the user's saved arrangement isn't disturbed.

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

• showCloseButton={false}, onClickMask={() => undefined}, disableKeyboardNavigation={["esc"]} — the only exits are explicit.
• Custom Prev / Next render via renderNextButton in tourPopover.tsx. On the last step the next-button slot returns a hidden placeholder so the step-dots stay centered.
• PopoverClampBridge keeps the popover inside the viewport so the step-number badge isn't clipped near screen edges.

Tour completion (tourPopover.tsx → TourCompletionActions)

• A small <TourCompletionActions /> component (Done button + space for upstack extensions) gets injected into the last step's content via setSteps augmentation in TourReactourBridge. Done closes the popover and routes back to /learn/tours.

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

• useTourMode() exposes { tour, tempPipelineName } to editor components.
• EditorMenuBar reads this to render a Tour badge next to the pipeline name and the central Exit Tour button. File-menu destructive actions (rename / delete) are hidden in tour mode.
• EditorV2Content reads it too: when pipelineRef is null and we're in tour mode, it shows PipelineEditorSkeleton instead of EmptyEditorState so the loading transition feels coherent.

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".
• Tracks window position so the highlight follows 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.

Editor integration (src/routes/v2/pages/Editor/EditorV2.tsx)

• EditorV2 accepts an optional pipelineRef prop so the tour route can pass in the temp pipeline it resolved itself.
• The body switches on three states: pipelineRef ? <PipelineEditor /> : tourMode ? <PipelineEditorSkeleton /> : <EmptyEditorState />.

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.

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 card as "Coming soon"
• No tour can be started; no tour UI appears anywhere in the editor
• Navigating directly to /tour/anything redirects to /learn/tours
• Existing editor / runs / dashboard flows are unaffected

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 intended to follow the first one (#2306), 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: Guided Tours End Screen #2339
• feat: Guided Tours Ephemeral Pipelines #2334
• feat: Guided Tours Custom Navigation #2340
• feat: Guided Tours Framework #2299 👈 (View in Graphite)
• feat: Learning Hub Guided Tours #2297
• feat: Learning Hub - Milestone 1 #2341
• 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/d9c0e95