Refactor guided tours into composable infrastructure under src/lib/tours

Author: milanofthe

src/app.css

@@ -718,232 +718,3 @@ body.assembly-pending .svelte-flow__edge {
 	}
 }
 
-/* --- Guided tour (driver.js) — pathview theme ------------------------- */
-
-/* Theme-aware overlay: light scrim on dark, dark scrim on light. Driver.js
- * sets fill via inline attribute on the inner path, so we override with
- * !important. Vars live on :root so toggling theme updates immediately. */
-:root[data-theme='dark'],
-:root:not([data-theme]) {
-	--tour-overlay-color: rgba(255, 255, 255, 0.22);
-}
-
-:root[data-theme='light'] {
-	--tour-overlay-color: rgba(0, 0, 0, 0.55);
-}
-
-.driver-overlay,
-.driver-overlay path {
-	fill: var(--tour-overlay-color) !important;
-}
-
-.driver-popover {
-	background-color: var(--surface) !important;
-	color: var(--text) !important;
-	border: 1px solid var(--border) !important;
-	border-radius: var(--radius-lg) !important;
-	box-shadow: var(--shadow-lg) !important;
-	max-width: 420px !important;
-	min-width: 320px !important;
-	padding: 0 !important;
-	overflow: hidden !important;
-}
-
-.driver-popover,
-.driver-popover * {
-	font-family: var(--font-ui) !important;
-}
-
-.driver-popover-title {
-	display: flex !important;
-	align-items: center !important;
-	min-height: var(--header-height) !important;
-	margin: 0 !important;
-	padding: 0 var(--space-md) !important;
-	background: var(--surface-raised) !important;
-	border-bottom: 1px solid var(--border) !important;
-	border-radius: var(--radius-lg) var(--radius-lg) 0 0 !important;
-	font-size: var(--font-base) !important;
-	font-weight: 500 !important;
-	line-height: 1.3 !important;
-	color: var(--text-muted) !important;
-	text-transform: uppercase !important;
-	letter-spacing: 0.5px !important;
-}
-
-.driver-popover-description {
-	font-size: 12px !important;
-	color: var(--text-muted) !important;
-	line-height: 1.55 !important;
-	margin: 0 !important;
-	padding: 14px 16px 0 !important;
-}
-
-.driver-popover-description p {
-	margin: 0 0 8px !important;
-}
-
-.driver-popover-description p:last-child {
-	margin-bottom: 0 !important;
-}
-
-.driver-popover-description ul {
-	margin: 6px 0 10px !important;
-	padding-left: 18px !important;
-}
-
-.driver-popover-description li {
-	margin: 2px 0 !important;
-}
-
-.driver-popover-description table {
-	width: 100% !important;
-	border-collapse: collapse !important;
-	margin: 6px 0 !important;
-	font-size: 11px !important;
-}
-
-.driver-popover-description table td {
-	padding: 4px 6px !important;
-	border-bottom: 1px solid var(--border) !important;
-	vertical-align: middle !important;
-}
-
-.driver-popover-description table tr:last-child td {
-	border-bottom: none !important;
-}
-
-.driver-popover-description table td:last-child {
-	text-align: right !important;
-	white-space: nowrap !important;
-}
-
-.driver-popover-description kbd {
-	display: inline-block;
-	padding: 2px 5px;
-	font-family: inherit !important;
-	font-size: 10px;
-	background: var(--surface-raised);
-	border: 1px solid var(--border);
-	border-radius: 3px;
-	color: var(--text-muted);
-	min-width: 16px;
-	text-align: center;
-}
-
-.driver-popover-description code {
-	font-family: var(--font-mono) !important;
-	color: var(--accent);
-	background: transparent;
-	padding: 0;
-}
-
-.driver-popover-progress-text {
-	font-size: 10px !important;
-	color: var(--text-disabled) !important;
-}
-
-.driver-popover-footer {
-	margin-top: 0 !important;
-	padding: 12px 16px 14px !important;
-}
-
-/* Footer buttons — match the modal action-button styles (with border). */
-.driver-popover-footer button {
-	display: inline-flex !important;
-	align-items: center !important;
-	justify-content: center !important;
-	gap: var(--space-sm) !important;
-	cursor: pointer !important;
-	border: 1px solid var(--border) !important;
-	background: var(--surface-raised) !important;
-	color: var(--text) !important;
-	padding: var(--space-sm) var(--space-md) !important;
-	border-radius: var(--radius-md) !important;
-	font-size: 11px !important;
-	font-weight: 500 !important;
-	text-shadow: none !important;
-	transition: all var(--transition-fast) !important;
-}
-
-.driver-popover-footer button:hover {
-	background: var(--surface-hover) !important;
-	border-color: var(--border-focus) !important;
-}
-
-.driver-popover-footer button:active {
-	transform: scale(0.98) !important;
-}
-
-.driver-popover-footer button:focus {
-	outline: none !important;
-}
-
-/* Back button as ghost (secondary action). */
-.driver-popover-prev-btn {
-	background: transparent !important;
-	color: var(--text-muted) !important;
-}
-
-.driver-popover-prev-btn:hover {
-	background: var(--surface-hover) !important;
-	color: var(--text) !important;
-	border-color: var(--border-focus) !important;
-}
-
-
-/* Close button: matches the .icon-btn pattern used in modal headers.
- * The default "×" character is hidden and replaced by a Lucide X icon
- * via a pseudo-element mask so theme colours apply on hover. */
-.driver-popover-close-btn {
-	position: absolute !important;
-	top: 6px !important;
-	right: 6px !important;
-	width: 28px !important;
-	height: 28px !important;
-	border: none !important;
-	border-radius: var(--radius-md) !important;
-	background: transparent !important;
-	color: transparent !important;
-	font-size: 0 !important;
-	cursor: pointer !important;
-	text-shadow: none !important;
-	transition: background var(--transition-fast) !important;
-	z-index: 2 !important;
-}
-
-.driver-popover-close-btn::before {
-	content: '' !important;
-	position: absolute !important;
-	inset: 0 !important;
-	background: var(--text-muted) !important;
-	-webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cline x1='18' y1='6' x2='6' y2='18'/%3E%3Cline x1='6' y1='6' x2='18' y2='18'/%3E%3C/svg%3E") center / 16px no-repeat;
-	mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cline x1='18' y1='6' x2='6' y2='18'/%3E%3Cline x1='6' y1='6' x2='18' y2='18'/%3E%3C/svg%3E") center / 16px no-repeat;
-	transition: background var(--transition-fast) !important;
-}
-
-.driver-popover-close-btn:hover {
-	background: var(--surface-hover) !important;
-}
-
-.driver-popover-close-btn:hover::before {
-	background: var(--text) !important;
-}
-
-.driver-popover-close-btn:focus {
-	outline: none !important;
-}
-
-/* Arrow tip color matches popover background; only the visible side counts. */
-.driver-popover-arrow-side-left {
-	border-left-color: var(--surface) !important;
-}
-.driver-popover-arrow-side-right {
-	border-right-color: var(--surface) !important;
-}
-.driver-popover-arrow-side-top {
-	border-top-color: var(--surface) !important;
-}
-.driver-popover-arrow-side-bottom {
-	border-bottom-color: var(--surface) !important;
-}

src/lib/components/FlowCanvas.svelte

@@ -14,6 +14,7 @@
 	import '@xyflow/svelte/dist/style.css';
 
 	import { isInputFocused } from '$lib/utils/focus';
+	import { isTourActive } from '$lib/tours/inputMode';
 	import BaseNode from './nodes/BaseNode.svelte';
 	import EventNode from './nodes/EventNode.svelte';
 	import AnnotationNode from './nodes/AnnotationNode.svelte';
@@ -31,6 +32,7 @@
 	import { dropTargetBridge } from '$lib/stores/dropTargetBridge';
 	import { contextMenuStore } from '$lib/stores/contextMenu';
 	import { nodeUpdatesStore } from '$lib/stores/nodeUpdates';
+	import { assemblyAnimationTrigger } from '$lib/animation/assemblyAnimation';
 		import { nodeRegistry } from '$lib/nodes';
 	import { NODE_TYPES } from '$lib/constants/nodeTypes';
 	import { GRID_SIZE, SNAP_GRID, BACKGROUND_GAP } from '$lib/constants/grid';
@@ -74,6 +76,8 @@
 
 	// Keyboard shortcuts for node manipulation
 	function handleKeydown(event: KeyboardEvent) {
+		// While a guided tour runs, driver.js owns the keyboard.
+		if (isTourActive()) return;
 		if (isInputFocused(event)) return;
 
 		// Handle Delete key (SvelteFlow's deleteKeyCode doesn't work reliably for 'Delete')
@@ -444,6 +448,19 @@
 		}
 	});
 
+	// On model load, the initial routing pass runs with fallback 80×40
+	// dimensions because nodes haven't been measured yet, and the per-node
+	// $effect above silently records first measurements without rerouting.
+	// Trigger a full reroute once measurements have settled.
+	let lastAssemblyTrigger = 0;
+	const unsubAssembly = assemblyAnimationTrigger.subscribe((v) => {
+		if (v > lastAssemblyTrigger) {
+			lastAssemblyTrigger = v;
+			setTimeout(() => updateRoutingContext(), 400);
+		}
+	});
+	onDestroy(() => unsubAssembly());
+
 	// Track if we're currently syncing to prevent loops
 	let isSyncing = false;
 

src/lib/components/ResizablePanel.svelte

@@ -180,6 +180,7 @@
 	class="resizable-panel glass-panel {position}"
 	class:resizing={isResizing}
 	data-panel={title ?? ''}
+	data-tour={title ? `panel-${title.toLowerCase()}` : ''}
 	style="
 		{position === 'left' || position === 'right' ? `width: ${getWidth()}px;` : ''}
 		{(position === 'bottom-left' || position === 'bottom-right') && controlledWidth !== undefined ? `width: ${getWidth()}px;` : ''}

src/lib/components/SubsystemBreadcrumb.svelte

@@ -27,7 +27,7 @@
 </script>
 
 {#if !isAtRoot}
-	<nav class="breadcrumb glass-panel" transition:fly={{ y: -10, duration: 150 }}>
+	<nav class="breadcrumb glass-panel" data-tour="breadcrumb" transition:fly={{ y: -10, duration: 150 }}>
 		{#each breadcrumbs as crumb, i}
 			<button
 				class="crumb-pill"

src/lib/components/WelcomeModal.svelte

@@ -5,7 +5,7 @@
 	import { cubicOut } from 'svelte/easing';
 	import Icon from '$lib/components/icons/Icon.svelte';
 	import { PATHVIEW_VERSION, EXTRACTED_VERSIONS } from '$lib/constants/dependencies';
-	import { startGuidedTour, type TourId } from '$lib/utils/guidedTour';
+	import { startGuidedTour, type TourId } from '$lib/tours';
 
 	interface Example {
 		name: string;
@@ -145,18 +145,18 @@
 				<span>Step-by-step walkthroughs that highlight the editor's main areas in turn so you know what each does.</span>
 			</div>
 			<div class="tour-buttons">
-				<button class="action-card" onclick={() => handleStartTour('ui')}>
-					<Icon name="arrow-right" size={20} />
+				<button class="action-card" onclick={() => handleStartTour('start')}>
+					<Icon name="compass" size={20} />
 					<span class="action-label">Start</span>
 				</button>
+				<button class="action-card" onclick={() => handleStartTour('modeling')}>
+					<Icon name="shapes" size={20} />
+					<span class="action-label">Modeling</span>
+				</button>
 				<button class="action-card" onclick={() => handleStartTour('simulation')}>
-					<Icon name="arrow-right" size={20} />
+					<Icon name="play-circle" size={20} />
 					<span class="action-label">Simulation</span>
 				</button>
-				<button class="action-card" onclick={() => handleStartTour('customization')}>
-					<Icon name="arrow-right" size={20} />
-					<span class="action-label">Modeling</span>
-				</button>
 			</div>
 		</div>
 

src/lib/components/dialogs/BlockPropertiesDialog.svelte

@@ -249,7 +249,7 @@
 
 {#if nodeId && node && typeDef}
 	<div class="dialog-backdrop" onclick={handleBackdropClick} transition:fade={{ duration: 150 }} role="presentation">
-		<div class="properties-dialog glass-panel" style="--node-color: {currentColor}" transition:scale={{ start: 0.95, duration: 150, easing: cubicOut }} role="dialog" tabindex="-1" aria-labelledby="dialog-title">
+		<div class="properties-dialog glass-panel" data-tour="dialog-properties" style="--node-color: {currentColor}" transition:scale={{ start: 0.95, duration: 150, easing: cubicOut }} role="dialog" tabindex="-1" aria-labelledby="dialog-title">
 			<div class="dialog-header">
 				{#if showCode}
 					<span id="dialog-title">Python Code</span>
@@ -258,6 +258,7 @@
 						<input
 							id="dialog-title"
 							class="node-name-input"
+							data-tour="block-name-input"
 							type="text"
 							value={node.name}
 							oninput={(e) => handleNameChange(e.currentTarget.value)}
@@ -377,6 +378,7 @@
 											<button
 												class="pin-btn"
 												class:pinned
+												data-tour="block-pin-btn"
 												onclick={() => togglePinParam(param.name)}
 												use:tooltip={pinned ? "Unpin from node" : "Pin to node"}
 												aria-label={pinned ? "Unpin from node" : "Pin to node"}

src/lib/components/dialogs/ExportDialog.svelte

@@ -135,7 +135,7 @@
 
 {#if open}
 	<div class="dialog-backdrop" transition:fade={{ duration: 150 }} onclick={handleBackdropClick} role="presentation">
-		<div class="dialog glass-panel" transition:scale={{ start: 0.95, duration: 150, easing: cubicOut }} role="dialog" tabindex="-1" aria-labelledby="dialog-title">
+		<div class="dialog glass-panel" data-tour="dialog-python-export" transition:scale={{ start: 0.95, duration: 150, easing: cubicOut }} role="dialog" tabindex="-1" aria-labelledby="dialog-title">
 			<div class="dialog-header">
 				<span id="dialog-title">Export Python Code</span>
 				<div class="header-actions">

src/lib/components/dialogs/KeyboardShortcutsDialog.svelte

@@ -95,6 +95,7 @@
 		<!-- svelte-ignore a11y_no_static_element_interactions, a11y_click_events_have_key_events -->
 		<div
 			class="dialog glass-panel"
+			data-tour="dialog-shortcuts"
 			transition:scale={{ start: 0.95, duration: 150, easing: cubicOut }}
 			onclick={(e) => e.stopPropagation()}
 			role="dialog"

src/lib/components/dialogs/SearchDialog.svelte

@@ -139,6 +139,7 @@
 		<!-- svelte-ignore a11y_no_static_element_interactions, a11y_click_events_have_key_events -->
 		<div
 			class="search-dialog glass-panel"
+			data-tour="dialog-search"
 			transition:scale={{ start: 0.95, duration: 150, easing: cubicOut }}
 			onclick={(e) => e.stopPropagation()}
 			role="dialog"

src/lib/components/dialogs/ToolboxManagerDialog.svelte

@@ -349,6 +349,7 @@
 	<div class="dialog-backdrop" transition:fade={{ duration: 150 }} onclick={handleBackdrop} role="presentation">
 		<div
 			class="dialog glass-panel manager-modal"
+			data-tour="dialog-toolbox-manager"
 			transition:scale={{ start: 0.95, duration: 150, easing: cubicOut }}
 			role="dialog"
 			aria-modal="true"