feat: Guided Tours Framework (Subgraphs)

[camielvs]

Description

The subgraph-specific interaction mechanics for the guided-tour framework, layered on the framework stack (#2348 / #2299 / #2347 / #2340). Foundation for the Subgraphs tour (#2366) — this PR adds the interaction types and the bridge logic that detects them; the tour content lands in #2366.

Five new tour interactions cover navigating and authoring subgraphs, plus a canvas re-measurement fix so spotlights track the viewport when navigation changes the view.

What changed

Interaction vocabulary (src/components/Learn/tours/registry.ts)

Five new TourStep.interaction values, plus a targetMinCount field:

• navigate-into-subgraph — descends a level (optionally gated to a specific targetTaskName)
• navigate-to-root — returns to the top level
• unpack-subgraph — the active spec's subgraph-task count drops (a subgraph was flattened)
• multi-select-tasks — ≥ targetMinCount (default 2) task nodes are selected
• create-subgraph — the subgraph-task count rises (a subgraph was created)

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

Each interaction is detected by observing the existing MobX stores — navigation.navigationDepth / navigationPath for level changes, navigation.activeSpec.tasks (counting subgraphSpec) for unpack/create, and editor.multiSelection for multi-select. Following the model from #2299, a detected interaction marks the step complete in the shared tour-progress state (it does not advance the tour itself); already-satisfied-on-entry states are marked complete immediately. Gated "Next" / auto-advance (#2340) handle progression.

Contextual checklist labels

Adds the checklist copy for these interactions (using the contextual bold-target support from #2340):

• navigate-into-subgraph → "Open the {targetTaskName} subgraph"
• multi-select-tasks → "Select {targetMinCount} tasks"
• navigate-to-root → "Return to the top level"
• unpack-subgraph → "Unpack the subgraph"
• create-subgraph → "Create a subgraph from the selected tasks"

Spotlight re-measurement while navigating

• Dispatches a resize event (via requestAnimationFrame) whenever the xyflow viewport pans/zooms during an open tour, so reactour re-positions the highlight/popover after navigating into a subgraph shifts the canvas.
• ensureWindowRestored now waits for the target DOM to actually appear — the step's own selector, else the dock window — polling up to 1.5s before forcing a re-measure, instead of measuring against a not-yet-rendered target.

Related Issue and Pull requests

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

Builds on the framework stack (#2348 / #2299 / #2347 / #2340); consumed by the Subgraphs tour in #2366.

Type of Change

• New feature

Checklist

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

Test Instructions

The registry is otherwise inert in this PR — the interactions are exercised end-to-end by the Subgraphs tour in #2366. To verify in isolation:

• No regressions in the existing tours ("Find your way around the editor", "Build your first pipeline"): interaction completion, ensureWindowRestored steps, and the dock/window highlight steps still work.
• Re-measurement — in any canvas-anchored tour step, pan/zoom the viewport; the spotlight/popover should re-position to follow rather than freeze.

Additional Comments

Selector/anchor additions and the seed pipeline for the subgraph tour live in #2366, following the convention that tour-specific DOM anchors ship alongside the tour that needs them.

[github-actions]

🎩 Preview

A preview build has been created at: 06-03-feat_guided_tours_framework_subgraphs_/aabac7b

[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: Onboarding Welcome Page #2435
• feat: Onboarding Pill #2440
• feat: Onboarding Checklist #2421
• feat: Learning Hub - Milestone 2 #2416
• feat: Guided Tours Cleanup #2417
• feat: Guided Tours E2E Tests #2415
• feat: Guided Tours Completion Metrics #2412
• feat: Guided Tour - Secrets #2406
• feat: Guided Tours Framework (Secrets) #2405
• feat: Guided Tour - Subgraphs #2366
• feat: Guided Tours Framework (Subgraphs) #2365 👈 (View in Graphite)
• feat: Guided Tour - First Pipeline #2312
• feat: Guided Tours Framework (First Pipeline) #2347
• feat: Guided Tour - Navigating the Editor #2306 : 1 other dependent PR (#2307 )
• feat: Guided Tours Framework (Navigating the Editor) #2299
• feat: Guided Tours End Screen #2339
• feat: Guided Tours Ephemeral Pipelines #2334
• feat: Guided Tours Custom Navigation #2340
• feat: Guided Tours Foundation #2348
• 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.

[maxy-shpfy]

🤖 This is an AI-generated code review comment.

This PR adds five more interaction branches directly inside EditorTourBridge, raising the file from 526 to 676 lines, cyclomatic complexity from 118 to 142, and FTA from 76.27 to 81.86. The file was already high, but this diff materially worsens the central orchestrator and duplicates local helpers like countSubgraphTasks, making future tour interactions harder to reason about and test.

Suggestion: Extract the subgraph-specific interaction tracking into co-located pure helpers or small handler functions, and share the countSubgraphTasks helper between create/unpack paths. Keep EditorTourBridge as the orchestration layer that delegates each interaction family.

Rule: static-analysis skill thresholds; tangle-ui-review Readability & Component Size; .cursorrules Code Quality prefers reducing nesting and extracting duplicated logic