Merge pull request #300 from Pouzor/feat/getting-started-walkthrough

feat(walkthrough): Getting Started tour + new-user canvas detection

backend/app/api/routes/canvas.py

@@ -37,6 +37,9 @@ async def load_canvas(
         edges=[EdgeResponse.model_validate(e) for e in edges],
         viewport=viewport,
         custom_style=state.custom_style if state else None,
+        # A CanvasState row exists only after a save (or explicit design create),
+        # so its presence marks an intentional canvas vs. a never-touched one.
+        initialized=state is not None,
     )
 
 

backend/app/schemas/canvas.py

@@ -84,3 +84,8 @@ class CanvasStateResponse(BaseModel):
     edges: list[EdgeResponse]
     viewport: dict[str, Any]
     custom_style: dict[str, Any] | None = None
+    # True once this design's canvas has ever been persisted (a CanvasState row
+    # exists). Lets the frontend tell a brand-new user (show demo) apart from one
+    # who intentionally cleared their canvas (keep it empty). False also for a
+    # missing/uninitialized design.
+    initialized: bool = False

backend/tests/test_canvas.py

@@ -22,6 +22,23 @@ async def test_load_canvas_empty(client: AsyncClient, headers: dict):
     assert data["viewport"] == {"x": 0, "y": 0, "zoom": 1}
 
 
+async def test_load_canvas_uninitialized_reports_initialized_false(client: AsyncClient, headers: dict):
+    # A never-saved canvas has no CanvasState row → initialized False. The frontend
+    # uses this to show the demo canvas only to genuinely new users.
+    data = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert data["initialized"] is False
+
+
+async def test_load_canvas_initialized_true_after_save(client: AsyncClient, headers: dict):
+    # Saving an EMPTY canvas still creates a CanvasState row, so a subsequently
+    # loaded empty canvas is reported initialized — the user cleared it on purpose
+    # and must not get the demo re-seeded.
+    await client.post("/api/v1/canvas/save", json={"nodes": [], "edges": [], "viewport": {}}, headers=headers)
+    data = (await client.get("/api/v1/canvas", headers=headers)).json()
+    assert data["nodes"] == []
+    assert data["initialized"] is True
+
+
 async def test_load_canvas_requires_auth(client: AsyncClient):
     res = await client.get("/api/v1/canvas")
     assert res.status_code == 401

frontend/src/App.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useCallback, useRef, useState } from 'react'
+import { useEffect, useCallback, useMemo, useRef, useState } from 'react'
 import { ReactFlowProvider, type Connection, type Edge } from '@xyflow/react'
 import { type Node } from '@xyflow/react'
 import { applyDagreLayout } from '@/utils/layout'
@@ -45,6 +45,11 @@ import { useThemeStore } from '@/stores/themeStore'
 import { canvasApi, designsApi, liveviewApi } from '@/api/client'
 import * as standaloneStorage from '@/utils/standaloneStorage'
 import { demoNodes, demoEdges } from '@/utils/demoData'
+import { decideCanvasLoad, isNewUserCanvas } from '@/utils/canvasLoadDecision'
+import { WalkthroughActionsProvider, type WalkthroughActionApi } from '@/walkthrough/actions'
+import { WalkthroughInvite } from '@/walkthrough/WalkthroughInvite'
+import { WalkthroughOverlay } from '@/walkthrough/WalkthroughOverlay'
+import { DEMO_SCAN_RUNS, DEMO_PENDING_DEVICES } from '@/walkthrough/demoTourData'
 import { useStatusPolling } from '@/hooks/useStatusPolling'
 import type { NodeData, EdgeData, CustomStyleDef, FloorMapConfig, NodeType } from '@/types'
 import type { ZigbeeNode, ZigbeeEdge } from '@/components/zigbee/types'
@@ -74,6 +79,18 @@ export default function App() {
   const loadedDesignIdRef = useRef<string | null>(loadedDesignId)
   useEffect(() => { loadedDesignIdRef.current = loadedDesignId }, [loadedDesignId])
 
+  // True while the last canvas load failed (backend down/error). Drives the error
+  // banner and keeps us from masking a real failure with the demo canvas.
+  const [loadError, setLoadError] = useState(false)
+  // True when the loaded canvas is the demo (a brand-new user). Reserved as the
+  // entry signal for the upcoming Getting Started walkthrough.
+  const [isNewUser, setIsNewUser] = useState(false)
+
+  // Getting Started tour: when true, the corresponding modal renders injected demo
+  // data instead of hitting the backend.
+  const [tourScanHistoryDemo, setTourScanHistoryDemo] = useState(false)
+  const [tourInventoryDemo, setTourInventoryDemo] = useState(false)
+
   const [themeModalOpen, setThemeModalOpen] = useState(false)
   const [styleEditorType, setStyleEditorType] = useState<NodeType | null>(null)
   const [searchOpen, setSearchOpen] = useState(false)
@@ -151,55 +168,83 @@ export default function App() {
   })
 
   const loadCanvasFromApi = useCallback(async (designId?: string) => {
+    let res
     try {
-      const res = await canvasApi.load(designId)
-      const { nodes: apiNodes, edges: apiEdges } = res.data
-      if (apiNodes.length > 0) {
-        const proxmoxContainerMap = new Map<string, boolean>(
-          (apiNodes as ApiNode[])
-            .filter((n) => n.type === 'group' || n.container_mode === true)
-            .map((n) => [n.id, true])
-        )
-        const { nodes: rfNodes, edges: rfEdges } = migrateClusterHandles(
-          (apiNodes as ApiNode[]).map((n) => deserializeApiNode(n, proxmoxContainerMap)),
-          (apiEdges as ApiEdge[]).map(deserializeApiEdge),
-        )
-        const savedTheme = res.data.viewport?.theme_id
-        if (savedTheme) setTheme(savedTheme)
-        if (res.data.custom_style) setCustomStyle(res.data.custom_style as CustomStyleDef)
-        const savedFloorMap = res.data.viewport?.floor_map as FloorMapConfig | undefined
-        // Clear when the target design has no floor plan, so it doesn't bleed
-        // across canvases when switching designs.
-        setFloorMap(savedFloorMap ?? null)
-        loadCanvas(rfNodes, rfEdges)
-      } else {
-        setFloorMap(null)
-        loadCanvas(demoNodes, demoEdges)
-      }
+      res = await canvasApi.load(designId)
     } catch {
+      // Backend down / errored. Surface it and STOP — never fall back to the demo
+      // canvas, which would hide the real error and look like a fresh account.
+      // Leave the on-screen canvas and provenance untouched so an autosave can't
+      // clobber real data with an empty canvas.
+      setLoadError(true)
+      toast.error('Could not load canvas — backend not responding')
+      return
+    }
+    const { nodes: apiNodes, edges: apiEdges } = res.data
+    const mode = decideCanvasLoad(apiNodes.length > 0, res.data.initialized === true)
+    if (mode === 'real') {
+      const proxmoxContainerMap = new Map<string, boolean>(
+        (apiNodes as ApiNode[])
+          .filter((n) => n.type === 'group' || n.container_mode === true)
+          .map((n) => [n.id, true])
+      )
+      const { nodes: rfNodes, edges: rfEdges } = migrateClusterHandles(
+        (apiNodes as ApiNode[]).map((n) => deserializeApiNode(n, proxmoxContainerMap)),
+        (apiEdges as ApiEdge[]).map(deserializeApiEdge),
+      )
+      const savedTheme = res.data.viewport?.theme_id
+      if (savedTheme) setTheme(savedTheme)
+      if (res.data.custom_style) setCustomStyle(res.data.custom_style as CustomStyleDef)
+      const savedFloorMap = res.data.viewport?.floor_map as FloorMapConfig | undefined
+      // Clear when the target design has no floor plan, so it doesn't bleed
+      // across canvases when switching designs.
+      setFloorMap(savedFloorMap ?? null)
+      loadCanvas(rfNodes, rfEdges)
+    } else if (mode === 'empty') {
+      // Initialized but no nodes: the user cleared this canvas on purpose — respect
+      // it and keep it empty instead of re-seeding the demo.
+      const savedTheme = res.data.viewport?.theme_id
+      if (savedTheme) setTheme(savedTheme)
+      if (res.data.custom_style) setCustomStyle(res.data.custom_style as CustomStyleDef)
+      setFloorMap(null)
+      loadCanvas([], [])
+    } else {
+      // Brand-new, never-saved canvas: seed the demo.
       setFloorMap(null)
       loadCanvas(demoNodes, demoEdges)
-    } finally {
-      // Record provenance so autosave writes back under the design just loaded.
-      setLoadedDesignId(designId ?? null)
     }
+    setLoadError(false)
+    setIsNewUser(isNewUserCanvas(mode))
+    // Record provenance so autosave writes back under the design just loaded.
+    setLoadedDesignId(designId ?? null)
   }, [loadCanvas, setTheme, setCustomStyle, setFloorMap])
 
   // Standalone counterpart of loadCanvasFromApi — reads a design's canvas from
   // localStorage, falling back to the demo canvas when it has never been saved.
   const loadStandaloneCanvas = useCallback((designId: string) => {
     const saved = standaloneStorage.loadCanvas(designId)
-    if (saved && saved.nodes.length > 0) {
+    // A stored entry (even with zero nodes) means the user has saved this canvas,
+    // so treat it as initialized and don't re-seed the demo on top of a canvas
+    // they deliberately cleared.
+    const mode = decideCanvasLoad((saved?.nodes.length ?? 0) > 0, saved !== null)
+    if (mode === 'real' && saved) {
       if (saved.theme_id) setTheme(saved.theme_id)
       if (saved.custom_style) setCustomStyle(saved.custom_style)
       // Floor plans are backend-only; keep the store clear in standalone mode.
       setFloorMap(null)
       const migrated = migrateClusterHandles(saved.nodes, saved.edges)
       loadCanvas(migrated.nodes, migrated.edges)
+    } else if (mode === 'empty' && saved) {
+      if (saved.theme_id) setTheme(saved.theme_id)
+      if (saved.custom_style) setCustomStyle(saved.custom_style)
+      setFloorMap(null)
+      loadCanvas([], [])
     } else {
       setFloorMap(null)
       loadCanvas(demoNodes, demoEdges)
     }
+    setLoadError(false)
+    setIsNewUser(isNewUserCanvas(mode))
     // Record provenance so autosave writes back under the design just loaded.
     setLoadedDesignId(designId)
   }, [loadCanvas, setTheme, setCustomStyle, setFloorMap])
@@ -231,16 +276,73 @@ export default function App() {
         await loadCanvasFromApi(targetId)
       }
     } catch {
-      // If API fails (e.g. fresh DB with no designs), fall back to demo data
-      loadCanvas(demoNodes, demoEdges)
+      // Backend unreachable/errored — surface it. Do NOT seed the demo: that would
+      // hide a real outage behind a fake "new account" canvas.
+      setLoadError(true)
+      toast.error('Could not reach backend — check the server and retry')
     }
-  }, [setDesigns, setActiveDesign, loadCanvasFromApi, loadStandaloneCanvas, activeDesignId, loadCanvas])
+  }, [setDesigns, setActiveDesign, loadCanvasFromApi, loadStandaloneCanvas, activeDesignId])
 
   // Keep a ref so the auth effect can call the latest loader without listing it
   // as a dependency (which would re-fire on every design switch).
   const loadDesignsAndCanvasRef = useRef(loadDesignsAndCanvas)
   useEffect(() => { loadDesignsAndCanvasRef.current = loadDesignsAndCanvas }, [loadDesignsAndCanvas])
 
+  // Retry a failed load from the error banner.
+  const handleRetryLoad = useCallback(() => {
+    setLoadError(false)
+    void loadDesignsAndCanvasRef.current()
+  }, [])
+
+  // Bridge the Getting Started tour steps to the App's modal controls. The overlay
+  // calls closeAll() before each step, then the step's action to open the target.
+  const walkthroughActions = useMemo<WalkthroughActionApi>(() => ({
+    closeAll: () => {
+      setScanConfigOpen(false)
+      setScanHistoryOpen(false)
+      setTourScanHistoryDemo(false)
+      setPendingModalOpen(false)
+      setTourInventoryDemo(false)
+      setEditNodeId(null)
+      setThemeModalOpen(false)
+      setZigbeeImportOpen(false)
+      // Clear any tour-driven multi-selection so the DetailPanel closes.
+      useCanvasStore.setState((s) => ({
+        nodes: s.nodes.map((n) => (n.selected ? { ...n, selected: false } : n)),
+        selectedNodeIds: [],
+        selectedNodeId: null,
+      }))
+    },
+    openScanConfig: () => setScanConfigOpen(true),
+    openScanHistoryDemo: () => {
+      setTourScanHistoryDemo(true)
+      setScanHistoryOpen(true)
+    },
+    openInventoryDemo: () => {
+      setTourInventoryDemo(true)
+      openPendingModal(undefined, 'pending')
+    },
+    editFirstNode: () => {
+      const first = useCanvasStore.getState().nodes.find((n) => n.data.type !== 'groupRect' && n.data.type !== 'text')
+      if (first) setEditNodeId(first.id)
+    },
+    selectTwoNodes: () => {
+      const ids = useCanvasStore.getState().nodes
+        .filter((n) => n.data.type !== 'groupRect' && n.data.type !== 'text')
+        .slice(0, 2)
+        .map((n) => n.id)
+      if (ids.length < 2) return
+      const set = new Set(ids)
+      useCanvasStore.setState((s) => ({
+        nodes: s.nodes.map((n) => ({ ...n, selected: set.has(n.id) })),
+        selectedNodeIds: ids,
+        selectedNodeId: null,
+      }))
+    },
+    openStyle: () => setThemeModalOpen(true),
+    openZigbeeImport: () => setZigbeeImportOpen(true),
+  }), [openPendingModal])
+
   // Load designs + canvas on auth (or immediately in standalone mode, which has
   // no auth gate).
   useEffect(() => {
@@ -823,9 +925,12 @@ export default function App() {
   if (!STANDALONE && !isAuthenticated) return <LoginPage />
 
   return (
+    <WalkthroughActionsProvider value={walkthroughActions}>
     <TooltipProvider>
       <ReactFlowProvider>
-        <div className="flex h-screen w-screen overflow-hidden bg-[#0d1117]">
+        {/* data-new-user marks a first-time (demo) canvas — the hook the upcoming
+            Getting Started walkthrough keys off. */}
+        <div className="flex h-screen w-screen overflow-hidden bg-[#0d1117]" data-new-user={isNewUser}>
           <Sidebar
             onAddNode={() => setAddNodeOpen(true)}
             onAddGroupRect={() => setAddGroupRectOpen(true)}
@@ -840,6 +945,21 @@ export default function App() {
             onOpenPending={openPendingModal}
           />
           <div className="flex flex-col flex-1 min-w-0">
+            {loadError && (
+              <div
+                role="alert"
+                className="flex items-center justify-between gap-3 bg-[#3d1418] border-b border-[#f85149] px-4 py-2 text-sm text-[#ffa198]"
+              >
+                <span>Backend not responding — the canvas could not be loaded.</span>
+                <button
+                  type="button"
+                  onClick={handleRetryLoad}
+                  className="rounded border border-[#f85149] px-2 py-0.5 text-[#ffa198] hover:bg-[#f85149]/20"
+                >
+                  Retry
+                </button>
+              </div>
+            )}
             <Toolbar
               onSave={handleSave}
               onAutoLayout={handleAutoLayout}
@@ -975,6 +1095,7 @@ export default function App() {
           <ScanHistoryModal
             open={scanHistoryOpen}
             onClose={() => setScanHistoryOpen(false)}
+            demoRuns={tourScanHistoryDemo ? DEMO_SCAN_RUNS : undefined}
           />
         )}
 
@@ -1099,6 +1220,7 @@ export default function App() {
           onClose={() => setPendingModalOpen(false)}
           highlightId={pendingHighlightId}
           initialStatus={pendingModalStatus}
+          demoDevices={tourInventoryDemo ? DEMO_PENDING_DEVICES : undefined}
         />
 
         <ExportModal
@@ -1108,7 +1230,10 @@ export default function App() {
         />
 
         <Toaster theme="dark" position="bottom-right" />
+        <WalkthroughInvite />
+        <WalkthroughOverlay />
       </ReactFlowProvider>
     </TooltipProvider>
+    </WalkthroughActionsProvider>
   )
 }

frontend/src/components/modals/PendingDevicesModal.tsx

@@ -25,6 +25,8 @@ interface PendingDevicesModalProps {
   onClose: () => void
   highlightId?: string
   initialStatus?: 'pending' | 'hidden'
+  /** Getting Started tour: render these canned devices and skip the backend fetch. */
+  demoDevices?: PendingDevice[]
 }
 
 const PORT_COLORS: Record<number, string> = {
@@ -113,7 +115,7 @@ function injectAutoEdges(edges: AutoEdge[] | undefined) {
   }))
 }
 
-export function PendingDevicesModal({ open, onClose, highlightId, initialStatus = 'pending' }: PendingDevicesModalProps) {
+export function PendingDevicesModal({ open, onClose, highlightId, initialStatus = 'pending', demoDevices }: PendingDevicesModalProps) {
   const [devices, setDevices] = useState<PendingDevice[]>([])
   const [loading, setLoading] = useState(false)
   const [selected, setSelected] = useState<PendingDevice | null>(null)
@@ -136,6 +138,8 @@ export function PendingDevicesModal({ open, onClose, highlightId, initialStatus
   const [dupPrompt, setDupPrompt] = useState<{ device: PendingDevice; conflict: DuplicateNodeConflict } | null>(null)
 
   const load = useCallback(async () => {
+    // Tour/demo mode: show injected devices, never touch the backend.
+    if (demoDevices) { setDevices(statusFilter === 'pending' ? demoDevices : []); return }
     setLoading(true)
     try {
       const res = statusFilter === 'pending' ? await scanApi.pending() : await scanApi.hidden()
@@ -145,7 +149,7 @@ export function PendingDevicesModal({ open, onClose, highlightId, initialStatus
     } finally {
       setLoading(false)
     }
-  }, [statusFilter])
+  }, [statusFilter, demoDevices])
 
   useEffect(() => { if (open) load() }, [open, load])
   useEffect(() => { if (open && scanEventTs > 0) load() }, [scanEventTs, open, load])

frontend/src/components/modals/ScanHistoryModal.tsx

@@ -20,6 +20,8 @@ export interface ScanRun {
 interface ScanHistoryModalProps {
   open: boolean
   onClose: () => void
+  /** Getting Started tour: render these canned runs and skip the backend fetch. */
+  demoRuns?: ScanRun[]
 }
 
 type KindFilter = 'all' | 'ip' | 'zigbee' | 'zwave' | 'proxmox'
@@ -85,7 +87,7 @@ function runDuration(r: ScanRun, now: number): string {
   return formatDuration(end - start)
 }
 
-export function ScanHistoryModal({ open, onClose }: ScanHistoryModalProps) {
+export function ScanHistoryModal({ open, onClose, demoRuns }: ScanHistoryModalProps) {
   const [runs, setRuns] = useState<ScanRun[]>([])
   const [loading, setLoading] = useState(false)
   const [stopping, setStopping] = useState<string | null>(null)
@@ -95,6 +97,8 @@ export function ScanHistoryModal({ open, onClose }: ScanHistoryModalProps) {
   const prevRunsRef = useRef<ScanRun[]>([])
 
   const load = useCallback(async () => {
+    // Tour/demo mode: show injected runs, never touch the backend.
+    if (demoRuns) { setRuns(demoRuns); prevRunsRef.current = demoRuns; return }
     setLoading(true)
     try {
       const res = await scanApi.runs()
@@ -127,7 +131,7 @@ export function ScanHistoryModal({ open, onClose }: ScanHistoryModalProps) {
     } finally {
       setLoading(false)
     }
-  }, [])
+  }, [demoRuns])
 
   // Load when opened; reset prior-state tracker so we don't replay old transitions
   useEffect(() => {
@@ -155,6 +159,7 @@ export function ScanHistoryModal({ open, onClose }: ScanHistoryModalProps) {
   }, [open, runs])
 
   const handleStop = async (runId: string) => {
+    if (demoRuns) return // tour mode — no backend
     setStopping(runId)
     try {
       await scanApi.stop(runId)

frontend/src/components/modals/SettingsModal.tsx

@@ -11,6 +11,7 @@ import {
   type ZwaveConfigData,
 } from '@/api/client'
 import { useCanvasStore } from '@/stores/canvasStore'
+import { useWalkthroughStore } from '@/stores/walkthroughStore'
 import { toast } from 'sonner'
 import {
   type AlignmentSettings,
@@ -401,6 +402,18 @@ export function SettingsModal({ open, onClose }: SettingsModalProps) {
                 Saves silently after this many seconds with no changes. Manual Ctrl+S still works.
               </p>
             </div>
+
+            <div className="flex items-center justify-between gap-2">
+              <span className="text-xs text-foreground">Getting started tour</span>
+              <Button
+                variant="outline"
+                size="sm"
+                className="h-7 text-xs"
+                onClick={() => { useWalkthroughStore.getState().start(); onClose() }}
+              >
+                Restart walkthrough
+              </Button>
+            </div>
           </div>
           </div>
 

frontend/src/components/panels/DetailPanel.tsx

@@ -516,6 +516,7 @@ function MultiSelectPanel({ nodeIds, nodes, groupName, setGroupName, creatingGro
           </>
         ) : (
           <Button
+            data-tour="create-group"
             size="sm"
             className="w-full gap-2 bg-[#00d4ff]/10 text-[#00d4ff] border border-[#00d4ff]/30 hover:bg-[#00d4ff]/20"
             variant="ghost"

frontend/src/components/panels/Sidebar.tsx

@@ -268,13 +268,13 @@ export function Sidebar({ onAddNode, onAddGroupRect, onAddText, onScan, onZigbee
 
       {/* Actions */}
       <div className="flex flex-col gap-0.5 p-2 border-t border-border">
-        <SidebarItem icon={Plus} label="Add Node" collapsed={collapsed} onClick={onAddNode} />
-        <SidebarItem icon={Square} label="Add Zone" collapsed={collapsed} onClick={onAddGroupRect} />
-        <SidebarItem icon={Type} label="Add Text" collapsed={collapsed} onClick={onAddText} />
-        {!STANDALONE && <SidebarItem icon={ScanLine} label="Scan Network" collapsed={collapsed} onClick={handleScan} />}
-        {!STANDALONE && <SidebarItem icon={Network} label="Zigbee Import" collapsed={collapsed} onClick={onZigbeeImport} />}
-        {!STANDALONE && <SidebarItem icon={RadioTower} label="Z-Wave Import" collapsed={collapsed} onClick={onZwaveImport} />}
-        {!STANDALONE && <SidebarItem icon={Server} label="Proxmox Import" collapsed={collapsed} onClick={onProxmoxImport} />}
+        <SidebarItem icon={Plus} label="Add Node" collapsed={collapsed} onClick={onAddNode} dataTour="add-node" />
+        <SidebarItem icon={Square} label="Add Zone" collapsed={collapsed} onClick={onAddGroupRect} dataTour="add-zone" />
+        <SidebarItem icon={Type} label="Add Text" collapsed={collapsed} onClick={onAddText} dataTour="add-text" />
+        {!STANDALONE && <SidebarItem icon={ScanLine} label="Scan Network" collapsed={collapsed} onClick={handleScan} dataTour="scan-network" />}
+        {!STANDALONE && <SidebarItem icon={Network} label="Zigbee Import" collapsed={collapsed} onClick={onZigbeeImport} dataTour="zigbee-import" />}
+        {!STANDALONE && <SidebarItem icon={RadioTower} label="Z-Wave Import" collapsed={collapsed} onClick={onZwaveImport} dataTour="zwave-import" />}
+        {!STANDALONE && <SidebarItem icon={Server} label="Proxmox Import" collapsed={collapsed} onClick={onProxmoxImport} dataTour="proxmox-import" />}
         <SidebarItem
           icon={Save}
           label="Save Canvas"
@@ -360,12 +360,15 @@ interface SidebarItemProps {
   badge?: boolean
   accent?: boolean
   onClick?: () => void
+  /** Stable anchor for the Getting Started walkthrough spotlight. */
+  dataTour?: string
 }
 
-function SidebarItem({ icon: Icon, label, collapsed, active, badge, accent, onClick }: SidebarItemProps) {
+function SidebarItem({ icon: Icon, label, collapsed, active, badge, accent, onClick, dataTour }: SidebarItemProps) {
   const btn = (
     <button
       onClick={onClick}
+      data-tour={dataTour}
       className={`relative flex items-center gap-2 w-full px-2 py-1.5 rounded-md text-sm transition-colors cursor-pointer ${
         active
           ? 'bg-[#00d4ff]/10 text-[#00d4ff]'

frontend/src/components/panels/Toolbar.tsx

@@ -62,7 +62,7 @@ export function Toolbar({ onSave, onAutoLayout, onExport, onChangeStyle, onUndo,
       <Button size="sm" variant="ghost" className="gap-1.5 text-muted-foreground hover:text-foreground cursor-pointer hover:bg-[#21262d]" onClick={onAutoLayout}>
         <LayoutDashboard size={14} /> Auto Layout
       </Button>
-      <Button size="sm" variant="ghost" className="gap-1.5 text-muted-foreground hover:text-foreground cursor-pointer hover:bg-[#21262d]" onClick={onChangeStyle}>
+      <Button data-tour="style" size="sm" variant="ghost" className="gap-1.5 text-muted-foreground hover:text-foreground cursor-pointer hover:bg-[#21262d]" onClick={onChangeStyle}>
         <Palette size={14} /> Style
       </Button>
       <Button size="sm" variant="ghost" className="gap-1.5 text-muted-foreground hover:text-foreground cursor-pointer hover:bg-[#21262d]" onClick={() => fileInputRef.current?.click()} title="Import from YAML">

frontend/src/components/ui/__tests__/sonner.test.tsx

@@ -0,0 +1,46 @@
+import { describe, it, expect, afterEach, beforeAll, vi } from 'vitest'
+import { render, cleanup, waitFor } from '@testing-library/react'
+import { toast } from 'sonner'
+import { Toaster } from '../sonner'
+
+beforeAll(() => {
+  // sonner reads matchMedia for theme detection; jsdom doesn't provide it.
+  window.matchMedia = vi.fn().mockImplementation((query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  }))
+})
+
+afterEach(() => cleanup())
+
+describe('Toaster', () => {
+  it('renders error toasts on a red surface so failures are visible', async () => {
+    render(<Toaster />)
+    toast.error('Save failed')
+    // The style (with the CSS vars) lands on the toast list, mounted on first toast.
+    const list = await waitFor(() => {
+      const el = document.querySelector('[data-sonner-toaster]') as HTMLElement | null
+      expect(el).not.toBeNull()
+      return el!
+    })
+    const style = list.getAttribute('style') ?? ''
+    expect(style).toContain('--error-bg: #f85149')
+    expect(style).toContain('--error-text: #ffffff')
+
+    // richColors must be on for sonner to apply the per-type surface, and the
+    // toast itself must be tagged as an error so it picks up --error-bg.
+    const item = await waitFor(() => {
+      const el = document.querySelector('[data-sonner-toast]') as HTMLElement | null
+      expect(el).not.toBeNull()
+      return el!
+    })
+    expect(item.getAttribute('data-rich-colors')).toBe('true')
+    expect(item.getAttribute('data-type')).toBe('error')
+  })
+})

frontend/src/components/ui/sonner.tsx

@@ -11,6 +11,7 @@ const Toaster = ({ ...props }: ToasterProps) => {
     <Sonner
       theme={theme as ToasterProps["theme"]}
       className="toaster group"
+      richColors
       icons={{
         success: (
           <CircleCheckIcon className="size-4" />
@@ -34,6 +35,23 @@ const Toaster = ({ ...props }: ToasterProps) => {
           "--normal-text": "var(--popover-foreground)",
           "--normal-border": "var(--border)",
           "--border-radius": "var(--radius)",
+          // richColors (below) is required for sonner to honor per-type surfaces.
+          // Errors get a red surface so failures (e.g. a save while the backend
+          // is down) stand out instead of reading like a normal toast...
+          "--error-bg": "#f85149",
+          "--error-text": "#ffffff",
+          "--error-border": "#da3633",
+          // ...while success/info/warning stay on the neutral popover surface so
+          // the rest of the toast UX is unchanged.
+          "--success-bg": "var(--popover)",
+          "--success-text": "var(--popover-foreground)",
+          "--success-border": "var(--border)",
+          "--info-bg": "var(--popover)",
+          "--info-text": "var(--popover-foreground)",
+          "--info-border": "var(--border)",
+          "--warning-bg": "var(--popover)",
+          "--warning-text": "var(--popover-foreground)",
+          "--warning-border": "var(--border)",
         } as React.CSSProperties
       }
       toastOptions={{

frontend/src/stores/__tests__/walkthroughStore.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { useWalkthroughStore } from '../walkthroughStore'
+import { readWalkthrough, WALKTHROUGH_VERSION } from '@/utils/walkthrough'
+
+beforeEach(() => {
+  localStorage.clear()
+  useWalkthroughStore.setState({ isActive: false, stepIndex: 0, total: 0 })
+})
+
+describe('walkthroughStore', () => {
+  it('start activates at step 0', () => {
+    useWalkthroughStore.getState().start()
+    const s = useWalkthroughStore.getState()
+    expect(s.isActive).toBe(true)
+    expect(s.stepIndex).toBe(0)
+  })
+
+  it('next advances and finishes past the last step', () => {
+    const store = useWalkthroughStore.getState()
+    store.start()
+    store.setTotal(3)
+    store.next()
+    expect(useWalkthroughStore.getState().stepIndex).toBe(1)
+    store.next()
+    expect(useWalkthroughStore.getState().stepIndex).toBe(2)
+    // At the last step, next() finishes the tour and stamps it completed.
+    store.next()
+    expect(useWalkthroughStore.getState().isActive).toBe(false)
+    expect(readWalkthrough()).toEqual({ seenVersion: WALKTHROUGH_VERSION, status: 'completed' })
+  })
+
+  it('prev clamps at 0', () => {
+    const store = useWalkthroughStore.getState()
+    store.start()
+    store.setTotal(3)
+    store.prev()
+    expect(useWalkthroughStore.getState().stepIndex).toBe(0)
+  })
+
+  it('goTo clamps within [0, total-1]', () => {
+    const store = useWalkthroughStore.getState()
+    store.start()
+    store.setTotal(3)
+    store.goTo(9)
+    expect(useWalkthroughStore.getState().stepIndex).toBe(2)
+    store.goTo(-1)
+    expect(useWalkthroughStore.getState().stepIndex).toBe(0)
+  })
+
+  it('skip deactivates and stamps skipped', () => {
+    const store = useWalkthroughStore.getState()
+    store.start()
+    store.skip()
+    expect(useWalkthroughStore.getState().isActive).toBe(false)
+    expect(readWalkthrough().status).toBe('skipped')
+    expect(readWalkthrough().seenVersion).toBe(WALKTHROUGH_VERSION)
+  })
+})

frontend/src/stores/walkthroughStore.ts

@@ -0,0 +1,48 @@
+import { create } from 'zustand'
+import { markWalkthroughSeen } from '@/utils/walkthrough'
+
+/**
+ * Runtime state of an active Getting Started tour. Persistence of the "already
+ * seen" flag lives in utils/walkthrough.ts; this store only tracks the live run.
+ *
+ * `total` is set by the overlay from the mode-filtered step list, so next()/goTo
+ * can clamp and finish() fires when the user advances past the last step.
+ */
+interface WalkthroughStore {
+  isActive: boolean
+  stepIndex: number
+  total: number
+  setTotal: (n: number) => void
+  start: () => void
+  next: () => void
+  prev: () => void
+  goTo: (n: number) => void
+  skip: () => void
+  finish: () => void
+}
+
+export const useWalkthroughStore = create<WalkthroughStore>((set, get) => ({
+  isActive: false,
+  stepIndex: 0,
+  total: 0,
+  setTotal: (n) => set({ total: n }),
+  start: () => set({ isActive: true, stepIndex: 0 }),
+  next: () => {
+    const { stepIndex, total } = get()
+    if (stepIndex >= total - 1) {
+      get().finish()
+      return
+    }
+    set({ stepIndex: stepIndex + 1 })
+  },
+  prev: () => set((s) => ({ stepIndex: Math.max(0, s.stepIndex - 1) })),
+  goTo: (n) => set((s) => ({ stepIndex: Math.max(0, Math.min(n, Math.max(0, s.total - 1))) })),
+  skip: () => {
+    markWalkthroughSeen('skipped')
+    set({ isActive: false })
+  },
+  finish: () => {
+    markWalkthroughSeen('completed')
+    set({ isActive: false })
+  },
+}))

frontend/src/utils/__tests__/canvasLoadDecision.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest'
+import { decideCanvasLoad, isNewUserCanvas } from '../canvasLoadDecision'
+
+describe('decideCanvasLoad', () => {
+  it('renders real nodes when the canvas has any', () => {
+    expect(decideCanvasLoad(true, true)).toBe('real')
+    // hasNodes wins even if the initialized flag is somehow false
+    expect(decideCanvasLoad(true, false)).toBe('real')
+  })
+
+  it('keeps an initialized-but-empty canvas empty (user cleared it)', () => {
+    expect(decideCanvasLoad(false, true)).toBe('empty')
+  })
+
+  it('shows the demo only for a brand-new, uninitialized canvas', () => {
+    expect(decideCanvasLoad(false, false)).toBe('demo')
+  })
+})
+
+describe('isNewUserCanvas', () => {
+  it('is true only for the demo mode', () => {
+    expect(isNewUserCanvas('demo')).toBe(true)
+    expect(isNewUserCanvas('empty')).toBe(false)
+    expect(isNewUserCanvas('real')).toBe(false)
+  })
+})

frontend/src/utils/__tests__/walkthrough.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import {
+  WALKTHROUGH_VERSION,
+  readWalkthrough,
+  writeWalkthrough,
+  subscribeWalkthrough,
+  shouldOfferWalkthrough,
+  markWalkthroughSeen,
+  resetWalkthrough,
+} from '../walkthrough'
+
+beforeEach(() => localStorage.clear())
+
+describe('readWalkthrough', () => {
+  it('defaults to pending / unseen when nothing is stored', () => {
+    expect(readWalkthrough()).toEqual({ seenVersion: null, status: 'pending' })
+  })
+
+  it('round-trips written state', () => {
+    writeWalkthrough({ seenVersion: 3, status: 'completed' })
+    expect(readWalkthrough()).toEqual({ seenVersion: 3, status: 'completed' })
+  })
+
+  it('falls back to defaults on malformed json', () => {
+    localStorage.setItem('homelable.walkthrough', '{not json')
+    expect(readWalkthrough()).toEqual({ seenVersion: null, status: 'pending' })
+  })
+})
+
+describe('shouldOfferWalkthrough', () => {
+  it('offers a brand-new user (seenVersion null)', () => {
+    expect(shouldOfferWalkthrough()).toBe(true)
+  })
+
+  it('offers an upgrader whose seen version is behind', () => {
+    writeWalkthrough({ seenVersion: WALKTHROUGH_VERSION - 1, status: 'completed' })
+    expect(shouldOfferWalkthrough()).toBe(true)
+  })
+
+  it('stops offering once the current version is stamped', () => {
+    markWalkthroughSeen('completed')
+    expect(shouldOfferWalkthrough()).toBe(false)
+    expect(readWalkthrough().seenVersion).toBe(WALKTHROUGH_VERSION)
+  })
+})
+
+describe('resetWalkthrough', () => {
+  it('re-offers after a reset', () => {
+    markWalkthroughSeen('skipped')
+    expect(shouldOfferWalkthrough()).toBe(false)
+    resetWalkthrough()
+    expect(shouldOfferWalkthrough()).toBe(true)
+  })
+})
+
+describe('subscribeWalkthrough', () => {
+  it('notifies listeners on write and unsubscribes cleanly', () => {
+    const spy = vi.fn()
+    const unsub = subscribeWalkthrough(spy)
+    writeWalkthrough({ seenVersion: 1, status: 'completed' })
+    expect(spy).toHaveBeenCalledWith({ seenVersion: 1, status: 'completed' })
+    unsub()
+    writeWalkthrough({ seenVersion: 2, status: 'skipped' })
+    expect(spy).toHaveBeenCalledTimes(1)
+  })
+})

frontend/src/utils/canvasLoadDecision.ts

@@ -0,0 +1,25 @@
+/**
+ * Decides what to render when a design's canvas loads.
+ *
+ * Three cases must stay distinct (issue: clearing a canvas re-showed the demo):
+ *  - `real`  → the canvas has saved nodes; render them.
+ *  - `empty` → the canvas is initialized (ever saved / explicitly created) but
+ *              has no nodes; the user intentionally cleared it — keep it empty.
+ *  - `demo`  → brand-new, never-initialized canvas; seed the demo so first-time
+ *              users see an example (and, later, the Getting Started walkthrough).
+ *
+ * Backend errors are handled by the caller, NOT here — a failed load must show an
+ * error and must never fall back to `demo` (that would hide the real failure).
+ */
+export type CanvasLoadMode = 'real' | 'empty' | 'demo'
+
+export function decideCanvasLoad(hasNodes: boolean, initialized: boolean): CanvasLoadMode {
+  if (hasNodes) return 'real'
+  if (initialized) return 'empty'
+  return 'demo'
+}
+
+/** A new user is one who lands on the demo canvas — the Getting Started hook. */
+export function isNewUserCanvas(mode: CanvasLoadMode): boolean {
+  return mode === 'demo'
+}

frontend/src/utils/walkthrough.ts

@@ -0,0 +1,73 @@
+/**
+ * Getting Started walkthrough — persisted invite state (localStorage).
+ *
+ * Mirrors the autosaveSettings.ts pattern: a `homelable.<name>` key plus a
+ * `window` CustomEvent for same-tab sync, so App and SettingsModal stay aligned
+ * without a global store.
+ *
+ * `seenVersion` is stamped with WALKTHROUGH_VERSION when the user finishes or
+ * dismisses the tour. Bump WALKTHROUGH_VERSION whenever new steps ship so
+ * existing users are re-offered the tour exactly once (they may have missed the
+ * new features). A brand-new user starts at seenVersion=null and is offered too.
+ */
+export const WALKTHROUGH_VERSION = 1
+
+export type WalkthroughStatus = 'pending' | 'skipped' | 'completed'
+
+export interface WalkthroughState {
+  seenVersion: number | null
+  status: WalkthroughStatus
+}
+
+const KEY = 'homelable.walkthrough'
+const EVENT = 'homelable:walkthrough-changed'
+
+export const DEFAULT_WALKTHROUGH_STATE: WalkthroughState = { seenVersion: null, status: 'pending' }
+
+function isStatus(v: unknown): v is WalkthroughStatus {
+  return v === 'pending' || v === 'skipped' || v === 'completed'
+}
+
+export function readWalkthrough(): WalkthroughState {
+  try {
+    const raw = localStorage.getItem(KEY)
+    if (!raw) return { ...DEFAULT_WALKTHROUGH_STATE }
+    const parsed = JSON.parse(raw) as Partial<WalkthroughState>
+    return {
+      seenVersion: typeof parsed.seenVersion === 'number' ? parsed.seenVersion : null,
+      status: isStatus(parsed.status) ? parsed.status : 'pending',
+    }
+  } catch {
+    return { ...DEFAULT_WALKTHROUGH_STATE }
+  }
+}
+
+export function writeWalkthrough(state: WalkthroughState): void {
+  try {
+    localStorage.setItem(KEY, JSON.stringify(state))
+    window.dispatchEvent(new CustomEvent(EVENT, { detail: state }))
+  } catch {
+    // ignore quota / SSR
+  }
+}
+
+export function subscribeWalkthrough(listener: (s: WalkthroughState) => void): () => void {
+  const handler = (e: Event) => listener((e as CustomEvent<WalkthroughState>).detail)
+  window.addEventListener(EVENT, handler)
+  return () => window.removeEventListener(EVENT, handler)
+}
+
+/** True when the invite should be offered (new user, or upgraded past the last seen version). */
+export function shouldOfferWalkthrough(state: WalkthroughState = readWalkthrough()): boolean {
+  return state.seenVersion !== WALKTHROUGH_VERSION
+}
+
+/** Stamp the current version so the invite stops auto-showing until the next bump. */
+export function markWalkthroughSeen(status: Exclude<WalkthroughStatus, 'pending'>): void {
+  writeWalkthrough({ seenVersion: WALKTHROUGH_VERSION, status })
+}
+
+/** Clear the stamp so the tour is offered again (used by "Restart" in Settings). */
+export function resetWalkthrough(): void {
+  writeWalkthrough({ ...DEFAULT_WALKTHROUGH_STATE })
+}

frontend/src/walkthrough/WalkthroughInvite.tsx

@@ -0,0 +1,72 @@
+import { useEffect, useState } from 'react'
+import { Compass, X } from 'lucide-react'
+import './walkthrough.css'
+import { Button } from '@/components/ui/button'
+import { useWalkthroughStore } from '@/stores/walkthroughStore'
+import {
+  readWalkthrough,
+  subscribeWalkthrough,
+  shouldOfferWalkthrough,
+  markWalkthroughSeen,
+  type WalkthroughState,
+} from '@/utils/walkthrough'
+
+/**
+ * First-run invite bubble (bottom-right, above the toaster).
+ *
+ *  - Not now         → hide for this session only (no write), reappears next load
+ *  - Don't show again → persist as skipped, stops offering until the next version
+ *  - Getting started  → launch the tour
+ */
+export function WalkthroughInvite() {
+  const [state, setState] = useState<WalkthroughState>(readWalkthrough)
+  useEffect(() => subscribeWalkthrough(setState), [])
+
+  // "Not now" dismissal — session-local, not persisted.
+  const [dismissedThisSession, setDismissedThisSession] = useState(false)
+
+  const isActive = useWalkthroughStore((s) => s.isActive)
+  const start = useWalkthroughStore((s) => s.start)
+
+  if (isActive || dismissedThisSession || !shouldOfferWalkthrough(state)) return null
+
+  return (
+    <div className="fixed bottom-20 right-4 z-[90] w-80 max-w-[calc(100vw-2rem)] rounded-xl border border-[#30363d] bg-[#161b22] p-4 shadow-2xl walkthrough-invite-enter">
+      <button
+        onClick={() => setDismissedThisSession(true)}
+        aria-label="Not now"
+        className="absolute top-2 right-2 text-muted-foreground hover:text-foreground p-1 rounded transition-colors"
+      >
+        <X size={14} />
+      </button>
+      <div className="flex items-start gap-3">
+        <div className="mt-0.5 flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-[#00d4ff]/10 text-[#00d4ff]">
+          <Compass size={18} />
+        </div>
+        <div className="min-w-0">
+          <h3 className="text-sm font-semibold text-foreground">New here? Take the tour</h3>
+          <p className="mt-1 text-xs leading-relaxed text-muted-foreground">
+            A 2-minute walkthrough of scanning, devices, and building your canvas.
+          </p>
+        </div>
+      </div>
+      <div className="mt-3 flex items-center justify-end gap-2">
+        <Button
+          variant="ghost"
+          size="sm"
+          className="h-7 px-2 text-xs text-muted-foreground hover:text-foreground"
+          onClick={() => markWalkthroughSeen('skipped')}
+        >
+          Don't show again
+        </Button>
+        <Button
+          size="sm"
+          className="h-7 px-3 text-xs bg-[#00d4ff] text-[#0d1117] hover:bg-[#00d4ff]/90"
+          onClick={start}
+        >
+          Getting started
+        </Button>
+      </div>
+    </div>
+  )
+}

frontend/src/walkthrough/WalkthroughOverlay.tsx

@@ -0,0 +1,248 @@
+import { useEffect, useMemo, useState, useCallback } from 'react'
+import { createPortal } from 'react-dom'
+import { ArrowLeft, ArrowRight, X } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import { useWalkthroughStore } from '@/stores/walkthroughStore'
+import { useWalkthroughActions } from './actions'
+import { getSteps, type StepPlacement } from './steps'
+import './walkthrough.css'
+
+const STANDALONE = import.meta.env.VITE_STANDALONE === 'true'
+
+const CARD_W = 320
+const CARD_H_EST = 210
+const GAP = 16
+const PAD = 6 // spotlight padding around the target
+
+/** Coach-card position from the target rect + requested placement. */
+function cardPosition(rect: DOMRect | null, placement: StepPlacement): { left: number; top: number } {
+  const vw = window.innerWidth
+  const vh = window.innerHeight
+  const clampL = (l: number) => Math.max(8, Math.min(l, vw - CARD_W - 8))
+  const clampT = (t: number) => Math.max(8, Math.min(t, vh - CARD_H_EST - 8))
+  if (!rect) return { left: clampL((vw - CARD_W) / 2), top: clampT((vh - CARD_H_EST) / 2) }
+
+  let side = placement
+  if (side === 'auto') {
+    side = rect.right + GAP + CARD_W < vw ? 'right' : rect.left - GAP - CARD_W > 0 ? 'left' : 'bottom'
+  }
+  switch (side) {
+    case 'right': return { left: clampL(rect.right + GAP), top: clampT(rect.top) }
+    case 'left': return { left: clampL(rect.left - GAP - CARD_W), top: clampT(rect.top) }
+    case 'top': return { left: clampL(rect.left), top: clampT(rect.top - GAP - CARD_H_EST) }
+    case 'bottom': return { left: clampL(rect.left), top: clampT(rect.bottom + GAP) }
+    case 'center':
+    default: return { left: clampL((vw - CARD_W) / 2), top: clampT((vh - CARD_H_EST) / 2) }
+  }
+}
+
+/**
+ * Position the card relative to an OPEN MODAL (the step's real subject).
+ * Large modals (inventory, scan history at ~90vw) leave no room beside them, so
+ * the card drops into the empty bottom-right corner instead of covering content.
+ * Small modals get the card beside them, on whichever side has room.
+ */
+function dialogCardPosition(rect: DOMRect): { left: number; top: number } {
+  const vw = window.innerWidth
+  const vh = window.innerHeight
+  const clampT = (t: number) => Math.max(8, Math.min(t, vh - CARD_H_EST - 8))
+  const isLarge = rect.width > vw * 0.6 || rect.height > vh * 0.7
+  if (isLarge) return { left: vw - CARD_W - 16, top: vh - CARD_H_EST - 16 }
+  if (rect.left >= CARD_W + GAP * 2) return { left: rect.left - GAP - CARD_W, top: clampT(rect.top) }
+  if (vw - rect.right >= CARD_W + GAP * 2) return { left: rect.right + GAP, top: clampT(rect.top) }
+  return { left: Math.max(8, Math.min(rect.left, vw - CARD_W - 8)), top: clampT(rect.bottom + GAP) }
+}
+
+export function WalkthroughOverlay() {
+  const { isActive, stepIndex, total, setTotal, next, prev, skip } = useWalkthroughStore()
+  const actions = useWalkthroughActions()
+  const steps = useMemo(() => getSteps(STANDALONE), [])
+  const step = steps[stepIndex]
+
+  // anchorRect: the element the step rings (sidebar/toolbar button). dialogRect:
+  // any open app modal, always kept lit so it stays readable during modal steps.
+  const [anchorRect, setAnchorRect] = useState<DOMRect | null>(null)
+  const [dialogRect, setDialogRect] = useState<DOMRect | null>(null)
+
+  // Keep the store's total in sync with the mode-filtered step list.
+  useEffect(() => {
+    if (isActive) setTotal(steps.length)
+  }, [isActive, steps.length, setTotal])
+
+  // Run the step's action on enter (close leftovers, open the right modal / inject
+  // demo data). Close everything when the tour ends.
+  useEffect(() => {
+    if (!actions) return
+    if (!isActive) { actions.closeAll(); return }
+    actions.closeAll()
+    const key = step?.action as keyof typeof actions | undefined
+    if (key && typeof actions[key] === 'function') (actions[key] as () => void)()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isActive, stepIndex, actions])
+
+  // Track target rects. Polls each frame because modals mount asynchronously after
+  // the step action fires, and layout shifts as they animate in.
+  useEffect(() => {
+    if (!isActive) return
+    let raf = 0
+    const update = () => {
+      const anchorEl = step?.anchor ? document.querySelector(step.anchor) : null
+      setAnchorRect(anchorEl ? anchorEl.getBoundingClientRect() : null)
+      // Any open app modal, excluding our own coach card (inside the overlay).
+      const dialogEl = Array.from(document.querySelectorAll('[role="dialog"]'))
+        .find((el) => !el.closest('[data-walkthrough-overlay]'))
+      setDialogRect(dialogEl ? dialogEl.getBoundingClientRect() : null)
+      raf = window.requestAnimationFrame(update)
+    }
+    update()
+    window.addEventListener('resize', update)
+    window.addEventListener('scroll', update, true)
+    return () => {
+      window.cancelAnimationFrame(raf)
+      window.removeEventListener('resize', update)
+      window.removeEventListener('scroll', update, true)
+    }
+  }, [isActive, stepIndex, step?.anchor])
+
+  const handleKey = useCallback((e: KeyboardEvent) => {
+    if (e.key === 'ArrowRight' || e.key === 'Enter') { e.preventDefault(); next() }
+    else if (e.key === 'ArrowLeft') { e.preventDefault(); prev() }
+    else if (e.key === 'Escape') { e.preventDefault(); skip() }
+  }, [next, prev, skip])
+
+  useEffect(() => {
+    if (!isActive) return
+    window.addEventListener('keydown', handleKey)
+    return () => window.removeEventListener('keydown', handleKey)
+  }, [isActive, handleKey])
+
+  // Flag the tour so app-modal backdrops drop their own dim/blur (see
+  // walkthrough.css) — the spotlight then dims consistently everywhere.
+  useEffect(() => {
+    if (!isActive) return
+    document.body.classList.add('walkthrough-running')
+    return () => document.body.classList.remove('walkthrough-running')
+  }, [isActive])
+
+  if (!isActive || !step) return null
+
+  const isLast = stepIndex >= total - 1
+  // Ring the step's anchor (sidebar/toolbar button) if it has one, else the modal.
+  const ringRect = anchorRect ?? dialogRect
+  // The card follows the OPEN MODAL when there is one (that's what the user reads),
+  // otherwise the step's anchor. Keeps the card off the modal's content.
+  const pos = dialogRect
+    ? dialogCardPosition(dialogRect)
+    : cardPosition(anchorRect, step.placement ?? 'auto')
+  // Cut-outs keep both the ringed control and any open modal lit.
+  const holes = [anchorRect, dialogRect].filter((r): r is DOMRect => r !== null)
+
+  return createPortal(
+    <div className="fixed inset-0 z-[100]" data-walkthrough-overlay>
+      {/* Backdrop: dim everything except the cut-out holes (multi-hole SVG mask so
+          a ringed button AND an open modal can both stay readable). */}
+      <svg className="pointer-events-none absolute inset-0 h-full w-full">
+        <defs>
+          <mask id="wt-spotlight-mask">
+            <rect x="0" y="0" width="100%" height="100%" fill="white" />
+            {holes.map((r, i) => (
+              <rect
+                key={i}
+                x={r.left - PAD}
+                y={r.top - PAD}
+                width={r.width + PAD * 2}
+                height={r.height + PAD * 2}
+                rx="10"
+                fill="black"
+              />
+            ))}
+          </mask>
+        </defs>
+        <rect x="0" y="0" width="100%" height="100%" fill="#010409" fillOpacity="0.72" mask="url(#wt-spotlight-mask)" />
+      </svg>
+
+      {/* Pulsing ring on the primary target */}
+      {ringRect && (
+        <div
+          className="walkthrough-spotlight--pulse pointer-events-none absolute rounded-lg border-2 border-[#00d4ff]"
+          style={{
+            left: ringRect.left - PAD,
+            top: ringRect.top - PAD,
+            width: ringRect.width + PAD * 2,
+            height: ringRect.height + PAD * 2,
+            transition: 'left 0.25s, top 0.25s, width 0.25s, height 0.25s',
+          }}
+        />
+      )}
+
+      {/* Coach card */}
+      <div
+        role="dialog"
+        aria-modal="false"
+        aria-label="Getting started walkthrough"
+        className="walkthrough-card-enter absolute pointer-events-auto rounded-xl border border-[#30363d] bg-[#161b22] p-4 shadow-2xl"
+        style={{ left: pos.left, top: pos.top, width: CARD_W, transition: 'left 0.25s, top 0.25s' }}
+      >
+        <div className="flex items-start justify-between gap-2">
+          <h3 className="text-sm font-semibold text-foreground">{step.title}</h3>
+          <button
+            onClick={skip}
+            aria-label="Skip walkthrough"
+            className="shrink-0 text-muted-foreground hover:text-foreground p-0.5 rounded transition-colors"
+          >
+            <X size={14} />
+          </button>
+        </div>
+        <p className="mt-1.5 text-xs leading-relaxed text-muted-foreground">{step.body}</p>
+
+        {step.link && (
+          <a
+            href={step.link.href}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="mt-2 inline-flex items-center gap-1 text-xs font-medium text-[#00d4ff] hover:underline"
+          >
+            {step.link.label} <ArrowRight size={12} />
+          </a>
+        )}
+
+        <div className="mt-3 flex items-center justify-between gap-2">
+          {/* Progress dots */}
+          <div className="flex items-center gap-1.5">
+            {steps.map((s, i) => (
+              <span
+                key={s.id}
+                className={`h-1.5 rounded-full transition-all ${
+                  i === stepIndex ? 'w-4 bg-[#00d4ff]' : 'w-1.5 bg-[#30363d]'
+                }`}
+              />
+            ))}
+          </div>
+          <div className="flex items-center gap-1.5">
+            <span className="mr-1 text-[10px] font-mono text-muted-foreground">
+              {stepIndex + 1}/{steps.length}
+            </span>
+            <Button
+              variant="ghost"
+              size="sm"
+              aria-label="Previous step"
+              className="h-7 px-2 text-xs text-muted-foreground hover:text-foreground disabled:opacity-40"
+              onClick={prev}
+              disabled={stepIndex === 0}
+            >
+              <ArrowLeft size={13} />
+            </Button>
+            <Button
+              size="sm"
+              className="h-7 px-3 text-xs bg-[#00d4ff] text-[#0d1117] hover:bg-[#00d4ff]/90"
+              onClick={next}
+            >
+              {isLast ? 'Finish' : <>Next <ArrowRight size={13} className="ml-1" /></>}
+            </Button>
+          </div>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  )
+}

frontend/src/walkthrough/__tests__/WalkthroughInvite.test.tsx

@@ -0,0 +1,46 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { renderWithProviders, screen, fireEvent } from '@/test/render'
+import { WalkthroughInvite } from '../WalkthroughInvite'
+import { useWalkthroughStore } from '@/stores/walkthroughStore'
+import { readWalkthrough } from '@/utils/walkthrough'
+
+beforeEach(() => {
+  localStorage.clear()
+  useWalkthroughStore.setState({ isActive: false, stepIndex: 0, total: 0 })
+})
+
+describe('WalkthroughInvite', () => {
+  it('offers the tour to a new user', () => {
+    renderWithProviders(<WalkthroughInvite />)
+    expect(screen.getByText('New here? Take the tour')).toBeInTheDocument()
+  })
+
+  it('is hidden once already seen', () => {
+    localStorage.setItem('homelable.walkthrough', JSON.stringify({ seenVersion: 1, status: 'completed' }))
+    renderWithProviders(<WalkthroughInvite />)
+    expect(screen.queryByText('New here? Take the tour')).not.toBeInTheDocument()
+  })
+
+  it('"Getting started" launches the tour', () => {
+    renderWithProviders(<WalkthroughInvite />)
+    fireEvent.click(screen.getByText('Getting started'))
+    expect(useWalkthroughStore.getState().isActive).toBe(true)
+    // Invite hides while the tour is active.
+    expect(screen.queryByText('New here? Take the tour')).not.toBeInTheDocument()
+  })
+
+  it('"Don\'t show again" persists and hides', () => {
+    renderWithProviders(<WalkthroughInvite />)
+    fireEvent.click(screen.getByText("Don't show again"))
+    expect(readWalkthrough().status).toBe('skipped')
+    expect(screen.queryByText('New here? Take the tour')).not.toBeInTheDocument()
+  })
+
+  it('"Not now" hides without persisting', () => {
+    renderWithProviders(<WalkthroughInvite />)
+    fireEvent.click(screen.getByLabelText('Not now'))
+    expect(screen.queryByText('New here? Take the tour')).not.toBeInTheDocument()
+    // Not persisted → would be offered again on next load.
+    expect(readWalkthrough().seenVersion).toBeNull()
+  })
+})

frontend/src/walkthrough/__tests__/WalkthroughOverlay.test.tsx

@@ -0,0 +1,46 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { renderWithProviders, screen, fireEvent, cleanup, act } from '@/test/render'
+import { WalkthroughOverlay } from '../WalkthroughOverlay'
+import { getSteps } from '../steps'
+import { useWalkthroughStore } from '@/stores/walkthroughStore'
+
+const TOTAL = getSteps(false).length
+
+const startTour = () => act(() => { useWalkthroughStore.getState().start() })
+
+beforeEach(() => {
+  localStorage.clear()
+  useWalkthroughStore.setState({ isActive: false, stepIndex: 0, total: 0 })
+})
+afterEach(() => cleanup())
+
+describe('WalkthroughOverlay', () => {
+  it('renders nothing while inactive', () => {
+    renderWithProviders(<WalkthroughOverlay />)
+    expect(screen.queryByText('Welcome to Homelable')).not.toBeInTheDocument()
+  })
+
+  it('shows the first step and progress when active', () => {
+    renderWithProviders(<WalkthroughOverlay />)
+    startTour()
+    expect(screen.getByText('Welcome to Homelable')).toBeInTheDocument()
+    expect(screen.getByText(`1/${TOTAL}`)).toBeInTheDocument()
+  })
+
+  it('advances and rewinds between steps', () => {
+    renderWithProviders(<WalkthroughOverlay />)
+    startTour()
+    fireEvent.click(screen.getByText('Next'))
+    expect(screen.getByText('Scan your network')).toBeInTheDocument()
+    fireEvent.click(screen.getByLabelText('Previous step'))
+    expect(screen.getByText('Welcome to Homelable')).toBeInTheDocument()
+  })
+
+  it('skip closes the overlay', () => {
+    renderWithProviders(<WalkthroughOverlay />)
+    startTour()
+    fireEvent.click(screen.getByLabelText('Skip walkthrough'))
+    expect(useWalkthroughStore.getState().isActive).toBe(false)
+    expect(screen.queryByText('Welcome to Homelable')).not.toBeInTheDocument()
+  })
+})

frontend/src/walkthrough/__tests__/steps.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest'
+import { getSteps, STEPS } from '../steps'
+
+describe('getSteps', () => {
+  it('returns every step in full mode', () => {
+    expect(getSteps(false)).toHaveLength(STEPS.length)
+  })
+
+  it('drops backend-only (mode:full) steps in standalone', () => {
+    const standalone = getSteps(true)
+    expect(standalone.every((s) => s.mode !== 'full')).toBe(true)
+    expect(standalone.length).toBeLessThan(STEPS.length)
+    const ids = standalone.map((s) => s.id)
+    // Canvas-only steps survive; backend-only steps are filtered out.
+    expect(ids).toEqual(expect.arrayContaining(['welcome', 'nodes', 'grouping', 'style', 'end']))
+    expect(ids).not.toContain('scan')
+    expect(ids).not.toContain('scan-history')
+    expect(ids).not.toContain('inventory')
+    expect(ids).not.toContain('imports')
+  })
+
+  it('ends on a step with a GitHub link (the full-mode recap in standalone)', () => {
+    const last = getSteps(true).at(-1)
+    expect(last?.id).toBe('end')
+    expect(last?.link?.href).toContain('github.com')
+  })
+})

frontend/src/walkthrough/actions.ts

@@ -0,0 +1,30 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * Bridge between tour steps and the App's modal/canvas controls. App builds the
+ * concrete implementation from its useState setters and provides it here; the
+ * overlay resolves each step's `action` string to a function on this object.
+ *
+ * `closeAll` is called before every step's action so leftover modals from the
+ * previous step are dismissed.
+ *
+ * Grows as steps land (openInventoryDemo, editDemoNode, openStyle, …).
+ */
+export interface WalkthroughActionApi {
+  closeAll: () => void
+  openScanConfig: () => void
+  openScanHistoryDemo: () => void
+  openInventoryDemo: () => void
+  editFirstNode: () => void
+  selectTwoNodes: () => void
+  openStyle: () => void
+  openZigbeeImport: () => void
+}
+
+const WalkthroughActionsContext = createContext<WalkthroughActionApi | null>(null)
+
+export const WalkthroughActionsProvider = WalkthroughActionsContext.Provider
+
+export function useWalkthroughActions(): WalkthroughActionApi | null {
+  return useContext(WalkthroughActionsContext)
+}

frontend/src/walkthrough/demoTourData.ts

@@ -0,0 +1,65 @@
+import type { ScanRun } from '@/components/modals/ScanHistoryModal'
+import type { PendingDevice } from '@/components/modals/PendingDeviceModal'
+
+/**
+ * Canned data injected into the real modals during the tour, so the demo steps
+ * look alive on a fresh install without hitting the backend. Never persisted.
+ */
+export const DEMO_SCAN_RUNS: ScanRun[] = [
+  {
+    id: 'tour-scan-running',
+    status: 'running',
+    kind: 'ip',
+    ranges: ['192.168.1.0/24'],
+    devices_found: 12,
+    // 8s ago so the live "Duration" reads a realistic elapsed time.
+    started_at: new Date(Date.now() - 8000).toISOString(),
+    finished_at: null,
+    error: null,
+  },
+  {
+    id: 'tour-scan-done',
+    status: 'done',
+    kind: 'ip',
+    ranges: ['192.168.1.0/24'],
+    devices_found: 9,
+    started_at: new Date(Date.now() - 3600_000).toISOString(),
+    finished_at: new Date(Date.now() - 3560_000).toISOString(),
+    error: null,
+  },
+]
+
+export const DEMO_PENDING_DEVICES: PendingDevice[] = [
+  {
+    id: 'tour-dev-1',
+    ip: '192.168.1.20',
+    mac: 'AA:BB:CC:DD:EE:20',
+    hostname: 'synology-nas',
+    os: 'DSM 7.2',
+    services: [{ port: 5000, protocol: 'tcp', service_name: 'Synology DSM', category: 'nas' }],
+    suggested_type: 'nas',
+    status: 'pending',
+    discovery_source: 'arp',
+    friendly_name: 'Synology NAS',
+    vendor: 'Synology',
+    model: 'DS920+',
+    discovered_at: new Date(Date.now() - 120_000).toISOString(),
+    canvas_count: 0,
+  },
+  {
+    id: 'tour-dev-2',
+    ip: '192.168.1.30',
+    mac: 'AA:BB:CC:DD:EE:30',
+    hostname: 'pi-hole',
+    os: null,
+    services: [{ port: 80, protocol: 'tcp', service_name: 'Pi-hole', category: 'network' }],
+    suggested_type: 'generic',
+    status: 'pending',
+    discovery_source: 'arp',
+    friendly_name: 'Pi-hole',
+    vendor: 'Raspberry Pi',
+    model: null,
+    discovered_at: new Date(Date.now() - 90_000).toISOString(),
+    canvas_count: 0,
+  },
+]

frontend/src/walkthrough/steps.ts

@@ -0,0 +1,121 @@
+/**
+ * Declarative Getting Started steps.
+ *
+ * `anchor` is a CSS selector for the element to ring/spotlight (undefined → the
+ * overlay lights any open modal, or centers the card). `action` is a key resolved
+ * against the walkthrough actions context on step enter (opens a modal, injects
+ * demo data, selects nodes, …). `mode: 'full'` marks a backend-only step that is
+ * filtered out of the standalone/public build. `link` renders a link in the card
+ * (used for the closing "questions?" step).
+ */
+export type StepPlacement = 'center' | 'top' | 'bottom' | 'left' | 'right' | 'auto'
+
+export interface TourStep {
+  id: string
+  title: string
+  body: string
+  anchor?: string
+  placement?: StepPlacement
+  action?: string
+  mode?: 'full' | 'all'
+  link?: { label: string; href: string }
+}
+
+export const STEPS: TourStep[] = [
+  {
+    id: 'welcome',
+    title: 'Welcome to Homelable',
+    body: 'Take a quick tour of the main features : scanning your network, managing devices, and building your canvas. You can skip anytime and restart later from Settings.',
+    placement: 'center',
+    mode: 'all',
+  },
+  {
+    id: 'scan',
+    title: 'Scan your network',
+    body: 'Start here: run an IP scan to auto-discover devices on your network. Pick the ranges and ports, then launch, discovered devices land in your inventory for review.',
+    anchor: '[data-tour="scan-network"]',
+    placement: 'right',
+    action: 'openScanConfig',
+    mode: 'full',
+  },
+  {
+    id: 'scan-history',
+    title: 'Follow scan progress',
+    body: 'Scan History shows every run live. A running scan updates in place with elapsed time and device count. You can stop it here too. (This is example data.)',
+    placement: 'left',
+    action: 'openScanHistoryDemo',
+    mode: 'full',
+  },
+  {
+    id: 'inventory',
+    title: 'Review discovered devices',
+    body: 'Discovered devices wait in your inventory. For each one you can approve it onto the canvas, hide it, or delete it, with detected services and vendor shown. (Example devices.)',
+    placement: 'left',
+    action: 'openInventoryDemo',
+    mode: 'full',
+  },
+  {
+    id: 'nodes',
+    title: 'Your devices on the canvas',
+    body: 'Approved devices become nodes on the canvas. Each shows live status, IP, hostname and running services. Drag to arrange them and draw links between them.',
+    anchor: '.react-flow__node',
+    placement: 'auto',
+    mode: 'all',
+  },
+  {
+    id: 'node-edit',
+    title: 'Edit a device',
+    body: 'Double-click any node to edit it: name, type, IP, the status-check method, appearance, and its parent (e.g. a VM inside a Proxmox host). Changes are yours until you Save.',
+    placement: 'left',
+    action: 'editFirstNode',
+    mode: 'all',
+  },
+  {
+    id: 'text-zone',
+    title: 'Annotate with text & zones',
+    body: 'Add free Text labels and Zones (colored rectangles) to document your layout to group a rack, mark a VLAN, or leave a note. Both live under the canvas actions.',
+    anchor: '[data-tour="add-zone"]',
+    placement: 'right',
+    mode: 'all',
+  },
+  {
+    id: 'grouping',
+    title: 'Group related devices',
+    body: 'Select multiple nodes, then Create Group to box them together and drag them as one. Perfect for a rack, a site, or a subnet.',
+    anchor: '[data-tour="create-group"]',
+    placement: 'left',
+    action: 'selectTwoNodes',
+    mode: 'all',
+  },
+  {
+    id: 'style',
+    title: 'Make it yours',
+    body: 'Switch the canvas theme from Style, or fine-tune colors, borders and fonts per node type. Your homelab, your look.',
+    anchor: '[data-tour="style"]',
+    placement: 'bottom',
+    action: 'openStyle',
+    mode: 'all',
+  },
+  {
+    id: 'imports',
+    title: 'Import from your stack',
+    body: 'Already running Zigbee2MQTT, Z-Wave JS, or Proxmox? Import devices directly from them instead of scanning. One click brings the whole topology in.',
+    anchor: '[data-tour="zigbee-import"]',
+    placement: 'right',
+    action: 'openZigbeeImport',
+    mode: 'full',
+  },
+  {
+    id: 'end',
+    title: "You're all set",
+    body: "That's the tour! Build your map, save it, and share a read-only view. In full mode you also get network scanning, a device inventory, and Zigbee / Z-Wave / Proxmox import. Have a question or an idea?",
+    placement: 'center',
+    mode: 'all',
+    link: { label: 'Ask on GitHub', href: 'https://github.com/Pouzor/homelable/issues' },
+  },
+]
+
+/** Steps for the current build — backend-only steps are dropped in standalone. */
+export function getSteps(standalone: boolean): TourStep[] {
+  return STEPS.filter((s) => s.mode !== 'full' || !standalone)
+}

frontend/src/walkthrough/walkthrough.css

@@ -0,0 +1,39 @@
+/* Getting Started walkthrough animations. Kept in a shared stylesheet (imported
+   by both the invite bubble and the overlay) so keyframes exist regardless of
+   which component is mounted. */
+
+@keyframes wt-invite-enter {
+  from { opacity: 0; transform: translateY(12px); }
+  to { opacity: 1; transform: none; }
+}
+.walkthrough-invite-enter { animation: wt-invite-enter 0.25s ease-out; }
+
+@keyframes wt-card-enter {
+  from { opacity: 0; transform: translateY(6px); }
+  to { opacity: 1; transform: none; }
+}
+.walkthrough-card-enter { animation: wt-card-enter 0.2s ease-out; }
+
+/* The dim surround is drawn by the overlay's SVG mask; this is just the pulsing
+   cyan ring around the primary target (outline so it sits outside the border). */
+.walkthrough-spotlight--pulse { animation: wt-pulse 1.8s ease-in-out infinite; }
+@keyframes wt-pulse {
+  0%, 100% { outline: 0px solid rgba(0, 212, 255, 0.55); }
+  50% { outline: 7px solid rgba(0, 212, 255, 0); }
+}
+
+/* While the tour runs, app modals must not add their own dim/blur — the overlay's
+   SVG spotlight is the single source of dimming, so a ringed sidebar/toolbar
+   control behind an open modal stays crisp instead of being double-dimmed and
+   blurred by the modal's own backdrop. */
+body.walkthrough-running [data-slot="dialog-overlay"] {
+  background: transparent !important;
+  backdrop-filter: none !important;
+  -webkit-backdrop-filter: none !important;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .walkthrough-invite-enter,
+  .walkthrough-card-enter,
+  .walkthrough-spotlight--pulse { animation: none; }
+}