Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: rewrite the guided tour and give every page one (#11105)
Michael Han0fdb81a9b592
diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsxindex 28cf3cc1f1e..4b0ce524204 100644--- a/studio/frontend/src/components/app-sidebar.tsx+++ b/studio/frontend/src/components/app-sidebar.tsx@@ -202,7 +202,7 @@ import { resolveNavRowState } from "@/components/nav-row-state";import { fetchDeviceType, usePlatformStore } from "@/config/env";import { videoNavHint } from "@/config/hardware-verdict";import { AUTH_SESSION_ENDING_EVENT, clearAuthTokens, logout } from "@/features/auth";-import { TOUR_OPEN_EVENT } from "@/features/tour";+import { TOUR_OPEN_EVENT, getTourId, useTourAvailable } from "@/features/tour";import {deleteTrainingRun,emitTrainingRunDeleted,@@ -256,13 +256,6 @@ function renderEmphasizedTranslation(return nodes;}-function getTourId(pathname: string): string | null {- if (pathname.startsWith("/studio")) return "studio";- if (pathname.startsWith("/export")) return "export";- if (pathname.startsWith("/chat")) return "chat";- return null;-}-// Optional user-menu shortcuts that jump to a settings tab; the id is the tab id.const SETTINGS_TAB_MENU_ITEMS: Record<"profile" | "appearance" | "resources" | "chat" | "connections",@@ -773,6 +766,10 @@ export function AppSidebar() {href: s.location.href,}),});+ // Route alone is not enough: a page can gate its tour behind a capability check, and an entry+ // that dispatches to nobody does nothing when clicked.+ const routeTourId = getTourId(pathname);+ const tourAvailable = useTourAvailable(routeTourId);const {pinned,togglePinned,@@ -4406,16 +4403,14 @@ export function AppSidebar() {);}if (item.id === "guidedTour") {- if (!getTourId(pathname)) return null;+ if (!routeTourId || !tourAvailable) return null;return (<DropdownMenuItemkey={item.id}onSelect={() => {- const tourId = getTourId(pathname);- if (!tourId) return;window.dispatchEvent(new CustomEvent(TOUR_OPEN_EVENT, {- detail: { id: tourId },+ detail: { id: routeTourId },}),);}}diff --git a/studio/frontend/src/features/api-monitor/api-monitor-page.tsx b/studio/frontend/src/features/api-monitor/api-monitor-page.tsxindex e366316f133..0df28027d62 100644--- a/studio/frontend/src/features/api-monitor/api-monitor-page.tsx+++ b/studio/frontend/src/features/api-monitor/api-monitor-page.tsx@@ -2,6 +2,8 @@// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0import { useAppShellReadySignal } from "@/components/app-readiness";+import { GuidedTour, useGuidedTourController } from "@/features/tour";+import { apiMonitorTourSteps } from "./tour";// Full-page monitor for Unsloth's OpenAI-compatible API server. Settings still owns// configuration (keys, auto-switch, examples); this page owns observability.@@ -526,6 +528,10 @@ function RequestDetail({export function ApiMonitorPage(): ReactElement {const signalReady = useAppShellReadySignal();+ const tour = useGuidedTourController({+ id: "api-monitor",+ steps: apiMonitorTourSteps,+ });const {data,entries,@@ -696,6 +702,7 @@ export function ApiMonitorPage(): ReactElement {return (<main className="mx-auto flex w-full max-w-6xl flex-col gap-6 px-6 pb-10 pt-12 font-heading sm:px-10">+ <GuidedTour {...tour.tourProps} /><header className="flex flex-wrap items-start justify-between gap-4"><div className="flex min-w-0 flex-col gap-1"><h1 className="text-ui-30 font-semibold leading-[1.04] tracking-[-0.028em] text-foreground sm:text-ui-34">@@ -705,7 +712,7 @@ export function ApiMonitorPage(): ReactElement {Live traffic through Unsloth's OpenAI-compatible server.</p></div>- <div className="flex flex-wrap items-center gap-2">+ <div data-tour="api-toolbar" className="flex flex-wrap items-center gap-2"><Buttontype="button"variant="outline"@@ -793,7 +800,10 @@ export function ApiMonitorPage(): ReactElement {</header>{/* Checked first when a client can't reach the API: base URL and what is loaded. */}- <section className="flex flex-wrap items-center gap-x-6 gap-y-3 rounded-xl border border-border/60 bg-card px-4 py-3">+ <section+ data-tour="api-endpoint"+ className="flex flex-wrap items-center gap-x-6 gap-y-3 rounded-xl border border-border/60 bg-card px-4 py-3"+ ><div className="flex min-w-0 items-center gap-2.5"><span className="flex size-8 shrink-0 items-center justify-center rounded-lg border border-border/60 bg-muted/40"><HugeiconsIcon@@ -951,7 +961,10 @@ export function ApiMonitorPage(): ReactElement {</span></div>- <div className="grid min-h-0 grid-cols-1 lg:grid-cols-[minmax(0,380px)_minmax(0,1fr)]">+ <div+ data-tour="api-log"+ className="grid min-h-0 grid-cols-1 lg:grid-cols-[minmax(0,380px)_minmax(0,1fr)]"+ ><div className="max-h-[560px] min-h-[220px] overflow-y-auto border-b border-border/60 lg:border-b-0 lg:border-r">{loading ? (<div className="flex flex-col gap-3 p-4">diff --git a/studio/frontend/src/features/api-monitor/tour/index.ts b/studio/frontend/src/features/api-monitor/tour/index.tsnew file mode 100644index 00000000000..5da227b51b2--- /dev/null+++ b/studio/frontend/src/features/api-monitor/tour/index.ts@@ -0,0 +1,4 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++export { apiMonitorTourSteps } from "./steps";diff --git a/studio/frontend/src/features/api-monitor/tour/steps.tsx b/studio/frontend/src/features/api-monitor/tour/steps.tsxnew file mode 100644index 00000000000..294a2a14597--- /dev/null+++ b/studio/frontend/src/features/api-monitor/tour/steps.tsx@@ -0,0 +1,42 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import type { TourStep } from "@/features/tour";++export const apiMonitorTourSteps: TourStep[] = [+ {+ id: "endpoint",+ target: "api-endpoint",+ title: "Your endpoint",+ body: (+ <>+ Studio serves an OpenAI-compatible API. Point any client at this base+ URL, keep the model name the same, and it works. Status and queue slots+ sit beside it.+ </>+ ),+ },+ {+ id: "toolbar",+ target: "api-toolbar",+ title: "Controls",+ body: (+ <>+ Pause the live feed to read a request without it scrolling away. Unload+ frees the model's VRAM. API settings is where you create keys.+ </>+ ),+ },+ {+ id: "log",+ target: "api-log",+ title: "Request log",+ body: (+ <>+ Pick a request on the left to see its prompt, reply, token counts and+ any error on the right. Search and the status filter above narrow it+ down.+ </>+ ),+ },+];diff --git a/studio/frontend/src/features/audio/audio-page.tsx b/studio/frontend/src/features/audio/audio-page.tsxindex 241345213e7..625976da8d1 100644--- a/studio/frontend/src/features/audio/audio-page.tsx+++ b/studio/frontend/src/features/audio/audio-page.tsx@@ -28,6 +28,8 @@ import {} from "react";import { AdvancedDisclosure } from "@/components/advanced-disclosure";+import { GuidedTour, useGuidedTourController } from "@/features/tour";+import { buildAudioTourSteps } from "./tour";import { Button } from "@/components/ui/button";import {DropdownMenu,@@ -335,6 +337,12 @@ export function AudioPage({}) {const initialReadySent = useRef(false);const [mode, setMode] = useState<CreateMode>("speak");+ const tourSteps = useMemo(() => buildAudioTourSteps({ mode }), [mode]);+ const tour = useGuidedTourController({+ id: "audio",+ steps: tourSteps,+ enabled: active,+ });const [selectorOpen, setSelectorOpen] = useState(false);const [busy, setBusy] = useState<AudioBusy>(null);const busyRef = useRef<AudioBusy>(busy);@@ -2555,6 +2563,8 @@ export function AudioPage({return (<div className="@container flex h-full min-h-0 min-w-0 flex-1 flex-col overflow-hidden pt-[var(--studio-content-top-inset,0px)]">+ {/* Portals to body, and this page stays mounted off-route, so gate it like the composer. */}+ {active && <GuidedTour {...tour.tourProps} />}{/* Keep the tabs centered over the preview at every width. The model rail holds at 408px whenspace permits and shrinks only to preserve the controls. */}<div className="pointer-events-none relative z-40 grid h-[48px] shrink-0 grid-cols-[minmax(0,408px)_minmax(13rem,1fr)]">@@ -2562,6 +2572,7 @@ export function AudioPage({{/* A long resident model name must yield to the mode pill instead of painting over it. */}<div className="pointer-events-auto flex min-w-0 max-w-full items-center gap-2 overflow-hidden pt-[var(--studio-chat-header-padding-top,11px)]"><ModelSelector+ triggerDataTour="audio-model"models={selectorModels}additionalOnDeviceModels={mode === "transcribe" ? sttOnDeviceModels : trainedTtsModels@@ -2631,7 +2642,10 @@ export function AudioPage({{/* Below 50rem the panes stack and the page scrolls as one column, matching Images and Video:side by side, the 408px rail plus a usable preview needs more width. */}<div className="flex min-h-0 w-full min-w-0 flex-1 flex-col overflow-y-auto overflow-x-hidden @[50rem]:flex-row @[50rem]:overflow-hidden">- <div className="flex w-full shrink-0 flex-col border-b border-border/60 @[50rem]:w-[408px] @[50rem]:overflow-hidden @[50rem]:border-r @[50rem]:border-b-0">+ <div+ data-tour="audio-settings"+ className="flex w-full shrink-0 flex-col border-b border-border/60 @[50rem]:w-[408px] @[50rem]:overflow-hidden @[50rem]:border-r @[50rem]:border-b-0"+ ><divref={attachSettingsScroll}onScroll={onSettingsScroll}@@ -2659,6 +2673,7 @@ export function AudioPage({</div><PillTabs+ dataTour="audio-mode"ariaLabel="Create mode"value={mode}onValueChange={(v) => transitionMode(v as CreateMode)}@@ -2848,6 +2863,7 @@ export function AudioPage({}><Button+ data-tour="audio-record"id="audio-record"variant={isRecording ? "destructive" : "secondary"}disabled={@@ -2952,7 +2968,10 @@ export function AudioPage({) : null}</div>- <div className="relative flex min-h-[60dvh] min-w-0 flex-1 flex-col overflow-hidden @[50rem]:min-h-0">+ <div+ data-tour="audio-output"+ className="relative flex min-h-[60dvh] min-w-0 flex-1 flex-col overflow-hidden @[50rem]:min-h-0"+ >{mode === "transcribe" ? (<divdata-reload-snapshot-sensitive={diff --git a/studio/frontend/src/features/audio/tour/index.ts b/studio/frontend/src/features/audio/tour/index.tsnew file mode 100644index 00000000000..9997d816a2f--- /dev/null+++ b/studio/frontend/src/features/audio/tour/index.ts@@ -0,0 +1,4 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++export { buildAudioTourSteps } from "./steps";diff --git a/studio/frontend/src/features/audio/tour/steps.tsx b/studio/frontend/src/features/audio/tour/steps.tsxnew file mode 100644index 00000000000..8d933959b82--- /dev/null+++ b/studio/frontend/src/features/audio/tour/steps.tsx@@ -0,0 +1,84 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import type { TourStep } from "@/features/tour";++const modeStep: TourStep = {+ id: "mode",+ target: "audio-mode",+ title: "Generate or Transcribe",+ body: (+ <>+ Generate makes speech and music from text. Transcribe turns a recording+ into text. They use different models, so the picker above follows the+ mode.+ </>+ ),+};++const modelStep: TourStep = {+ id: "model",+ target: "audio-model",+ title: "Pick a model",+ body: (+ <>+ TTS and music models for Generate, speech recognition for Transcribe.+ Voices you fine-tuned show up under On Device.+ </>+ ),+};++const outputStep: TourStep = {+ id: "output",+ target: "audio-output",+ title: "Output",+ body: (+ <>+ Clips play here and stay in the history list beside them, ready to+ download. Transcripts appear here too, but are not kept after you leave.+ </>+ ),+};++/** The two modes swap the settings body and the footer, so each gets its own middle step. */+export function buildAudioTourSteps({+ mode,+}: {+ mode: "speak" | "transcribe";+}): TourStep[] {+ if (mode === "transcribe") {+ return [+ modeStep,+ modelStep,+ {+ id: "record",+ target: "audio-record",+ title: "Record or upload",+ body: (+ <>+ Record from your microphone and it transcribes when you stop, or+ upload a wav, mp3, m4a or webm file instead.+ </>+ ),+ },+ outputStep,+ ];+ }++ return [+ modeStep,+ modelStep,+ {+ id: "settings",+ target: "audio-settings",+ title: "Settings",+ body: (+ <>+ Your text or lyrics, plus voice and style where the model supports+ them. Length and temperature sit under Advanced.+ </>+ ),+ },+ outputStep,+ ];+}diff --git a/studio/frontend/src/features/chat/chat-page.tsx b/studio/frontend/src/features/chat/chat-page.tsxindex 863bb5b13b1..af6b9d99e88 100644--- a/studio/frontend/src/features/chat/chat-page.tsx+++ b/studio/frontend/src/features/chat/chat-page.tsx@@ -3574,7 +3574,17 @@ export function ChatPage({},{ enabled: active && fastModeSupported },);- const { isMobile, pinned } = useSidebar();+ const { isMobile, pinned, setPinned } = useSidebar();+ // The tour's orientation step spotlights the nav, so show it for that step and put the user's+ // own pin setting back on the way out; it is persisted, so a tour must not rewrite it.+ const sidebarWasPinnedRef = useRef(pinned);+ const showSidebarForTour = useCallback(() => {+ sidebarWasPinnedRef.current = pinned;+ setPinned(true);+ }, [pinned, setPinned]);+ const restoreSidebarAfterTour = useCallback(() => {+ if (!sidebarWasPinnedRef.current) setPinned(false);+ }, [setPinned]);const enterCompare = useCallback(() => {viewBeforeCompareRef.current = { ...search };@@ -3906,6 +3916,7 @@ export function ChatPage({() =>// eslint-disable-next-line react-hooks/refs -- buildChatTourSteps stores callbacks without invoking them during render.buildChatTourSteps({+ canShowNav: !isMobile,canCompare,openModelSelector,closeModelSelector,@@ -3913,21 +3924,33 @@ export function ChatPage({closeSettings,enterCompare,exitCompare,- }),+ }).map((step) =>+ step.target === "navbar"+ ? {+ ...step,+ onEnter: showSidebarForTour,+ onExit: restoreSidebarAfterTour,+ }+ : step,+ ),[canCompare,closeModelSelector,closeSettings,enterCompare,exitCompare,+ isMobile,openModelSelector,openSettings,+ restoreSidebarAfterTour,+ showSidebarForTour,],);const tour = useGuidedTourController({id: "chat",steps: tourSteps,+ enabled: active,});useEffect(() => {diff --git a/studio/frontend/src/features/chat/projects-page.tsx b/studio/frontend/src/features/chat/projects-page.tsxindex 14d28bc8f94..bd9bd955465 100644--- a/studio/frontend/src/features/chat/projects-page.tsx+++ b/studio/frontend/src/features/chat/projects-page.tsx@@ -42,6 +42,8 @@ import {usePinnedProjectsStore,type ProjectRecord,} from "@/features/chat";+import { GuidedTour, useGuidedTourController } from "@/features/tour";+import { buildProjectsTourSteps } from "./tour";import { NewProjectDialog } from "./components/new-project-dialog";import {Delete02Icon,@@ -260,6 +262,13 @@ export function ProjectsPage() {: sortedProjects.slice(0, visibleCount);const hasMore = !isSearching && sortedProjects.length > visibleCount;+ // The list only renders once at least one project exists, so its step is dropped until then.+ const tourSteps = useMemo(+ () => buildProjectsTourSteps({ hasProjects: visibleProjects.length > 0 }),+ [visibleProjects.length],+ );+ const tour = useGuidedTourController({ id: "projects", steps: tourSteps });+useEffect(() => {if (!hasLoaded || reloadReadySent.current) {return;@@ -389,6 +398,7 @@ export function ProjectsPage() {return (<main className="mx-auto w-full max-w-5xl px-6 pb-10 pt-16 font-heading sm:px-10">+ <GuidedTour {...tour.tourProps} />{/* Global import file input */}<inputref={globalImportRef}@@ -441,6 +451,7 @@ export function ProjectsPage() {<Buttonvariant="outline"size="icon"+ data-tour="projects-io"title="Import / Export projects"className="rounded-full border-none bg-muted shadow-none dark:bg-card">@@ -507,7 +518,9 @@ export function ProjectsPage() {</DropdownMenuSub></DropdownMenuContent></DropdownMenu>- <Button onClick={() => setCreating(true)}>New project</Button>+ <Button data-tour="projects-new" onClick={() => setCreating(true)}>+ New project+ </Button></div></div>@@ -559,7 +572,7 @@ export function ProjectsPage() {<span className="w-40 shrink-0">Modified</span><span className="w-8 shrink-0" /></div>- <div ref={listRef}>+ <div ref={listRef} data-tour="projects-list">{visibleProjects.map((project) => {const pinned = pinnedProjectIdSet.has(project.id);return (diff --git a/studio/frontend/src/features/chat/thread-sidebar.tsx b/studio/frontend/src/features/chat/thread-sidebar.tsxindex 30ae5da3682..73a46f83940 100644--- a/studio/frontend/src/features/chat/thread-sidebar.tsx+++ b/studio/frontend/src/features/chat/thread-sidebar.tsx@@ -197,7 +197,7 @@ export function ThreadSidebar({</SidebarMenuItem>{showCompare ? (<SidebarMenuItem>- <SidebarMenuButton data-tour="chat-compare" onClick={onNewCompare}>+ <SidebarMenuButton onClick={onNewCompare}><HugeiconsIcon icon={ColumnInsertIcon} /><span>Compare</span></SidebarMenuButton>diff --git a/studio/frontend/src/features/chat/tour/index.ts b/studio/frontend/src/features/chat/tour/index.tsindex a5f94c95066..f85ee6784a0 100644--- a/studio/frontend/src/features/chat/tour/index.ts+++ b/studio/frontend/src/features/chat/tour/index.ts@@ -2,4 +2,5 @@// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0export { buildChatTourSteps } from "./steps";+export { buildProjectsTourSteps } from "./projects-steps";diff --git a/studio/frontend/src/features/chat/tour/projects-steps.tsx b/studio/frontend/src/features/chat/tour/projects-steps.tsxnew file mode 100644index 00000000000..22ee8e25a48--- /dev/null+++ b/studio/frontend/src/features/chat/tour/projects-steps.tsx@@ -0,0 +1,51 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import type { TourStep } from "@/features/tour";++export function buildProjectsTourSteps({+ hasProjects,+}: {+ hasProjects: boolean;+}): TourStep[] {+ const steps: TourStep[] = [+ {+ id: "new",+ target: "projects-new",+ title: "Make a project",+ body: (+ <>+ A project keeps related chats together with shared files and a shared+ system prompt. Sources you add reach every chat inside it.+ </>+ ),+ },+ {+ id: "io",+ target: "projects-io",+ title: "Import and export",+ body: (+ <>+ Export chats as JSONL, CSV or ShareGPT, a quick way to turn real+ conversations into training data. Import brings them back.+ </>+ ),+ },+ ];++ if (hasProjects) {+ steps.push({+ id: "list",+ target: "projects-list",+ title: "Open a project",+ body: (+ <>+ Click a row to open it in Chat. The row menu pins it to the sidebar,+ renames it, or deletes it with its chats.+ </>+ ),+ });+ }++ return steps;+}diff --git a/studio/frontend/src/features/chat/tour/steps.tsx b/studio/frontend/src/features/chat/tour/steps.tsxindex ad5de4d5e7a..70b63892117 100644--- a/studio/frontend/src/features/chat/tour/steps.tsx+++ b/studio/frontend/src/features/chat/tour/steps.tsx@@ -4,6 +4,7 @@import type { TourStep } from "@/features/tour";export function buildChatTourSteps({+ canShowNav,canCompare,openModelSelector,closeModelSelector,@@ -12,6 +13,7 @@ export function buildChatTourSteps({enterCompare,exitCompare,}: {+ canShowNav: boolean;canCompare: boolean;openModelSelector: () => void;closeModelSelector: () => void;@@ -27,9 +29,9 @@ export function buildChatTourSteps({title: "Pick a model",body: (<>- Selects what’s loaded for inference. Recommended is Unsloth’s curated- base models; On Device is your downloads and fine-tuned outputs (LoRA- adapters and full finetunes).+ Loads a model for inference. Runs local GGUF, safetensors and your own+ LoRA adapters, plus any cloud provider you add in Settings, such as+ Gemini, OpenAI, Anthropic or OpenRouter.</>),},@@ -39,40 +41,55 @@ export function buildChatTourSteps({title: "Find a model",body: (<>- Search Unsloth’s models, or hit Search Hub for all of Hugging Face.- Switch Recommended and On Device, filter by format, and sort by- trending or recent. An OOM tag means it won’t fit in your VRAM.+ Recommended is Unsloth's curated list, On Device is your downloads and+ finetunes. Search Hub reaches all of Hugging Face. An OOM tag means it+ will not fit in your VRAM.</>),onEnter: openModelSelector,onExit: closeModelSelector,},+ {+ id: "plus-menu",+ target: "chat-plus-menu",+ title: "Tools and attachments",+ body: (+ <>+ Open this to attach PDFs, images, audio and code, or to switch on web+ search, the sandboxed Bash and Python tools, MCP servers and skills.+ </>+ ),+ },{id: "settings",target: "chat-settings",- title: "Settings sidebar",+ title: "Run settings",body: (<>- Sampling (temperature/top-p/top-k) + system prompt live here. If you- want more deterministic outputs, lower temperature first.+ Temperature, top-p, top-k, system prompt and the chat template. Lower+ temperature first when you want steadier answers.</>),onEnter: openSettings,onExit: closeSettings,},- {- id: "plus-menu",- target: "chat-plus-menu",- title: "The + menu",+ ];++ if (canShowNav) {+ // The mobile sidebar is a closed sheet, so there is nothing to spotlight there.+ steps.unshift({+ id: "nav",+ target: "navbar",+ title: "Where everything lives",body: (<>- Everything else lives here: attach photos and files, reuse saved- prompts, toggle tools and MCP, start a side-by-side compare, and- export the chat.+ Chat runs models. Train fine-tunes them, Recipes turns documents into+ datasets, and Export packages the result. Images, Video and Audio are+ their own workspaces, and Model hub manages what is on this device.</>),- },- ];+ });+ }if (canCompare) {// Compare lives in the + menu, with no sidebar button to anchor to; this step enters compare on@@ -80,12 +97,12 @@ export function buildChatTourSteps({steps.push({id: "compare-view",target: "chat-compare-view",- title: "Side-by-side threads",+ title: "Compare two models",body: (<>- Compare any two models side-by-side, available from the + menu. Same- prompt, 2 threads. If LoRA is worse than base, it’s usually data- formatting, too many epochs, or a bad checkpoint choice.+ One prompt, two threads, side by side. The quickest way to check a+ finetune against its base model. If yours is worse, suspect dataset+ formatting, too many epochs or the wrong checkpoint.</>),onEnter: enterCompare,diff --git a/studio/frontend/src/features/data-recipes/pages/data-recipes-page.tsx b/studio/frontend/src/features/data-recipes/pages/data-recipes-page.tsxindex c0ce418a3aa..287e5f02586 100644--- a/studio/frontend/src/features/data-recipes/pages/data-recipes-page.tsx+++ b/studio/frontend/src/features/data-recipes/pages/data-recipes-page.tsx@@ -44,7 +44,7 @@ import {import { HugeiconsIcon } from "@hugeicons/react";import { useNavigate } from "@tanstack/react-router";import type { ReactElement } from "react";-import { useEffect, useRef, useState } from "react";+import { useEffect, useMemo, useRef, useState } from "react";import {createRecipeDraft,createRecipeFromLearningRecipe,@@ -53,6 +53,8 @@ import {useRecipes,} from "../data/recipes-db";import { LEARNING_RECIPES } from "../learning-recipes";+import { GuidedTour, useGuidedTourController } from "@/features/tour";+import { buildDataRecipesTourSteps } from "../tour";type TemplateCard = {title: string;@@ -321,6 +323,14 @@ export function DataRecipesPage(): ReactElement {null,);const reloadReadySent = useRef(false);+ const tourSteps = useMemo(+ () => buildDataRecipesTourSteps({ ready, hasRecipes: recipes.length > 0 }),+ [ready, recipes.length],+ );+ const tour = useGuidedTourController({+ id: "data-recipes",+ steps: tourSteps,+ });useEffect(() => {if (!ready || reloadReadySent.current) {@@ -410,6 +420,7 @@ export function DataRecipesPage(): ReactElement {return (<div className="min-h-[calc(100dvh-var(--studio-titlebar-height,0px))] bg-background"><main className="mx-auto w-full max-w-7xl px-5 py-8 sm:px-9">+ <GuidedTour {...tour.tourProps} /><div className="flex items-center justify-between gap-4"><div><h1 className="text-ui-30 font-semibold leading-[1.04] tracking-[-0.028em] text-foreground sm:text-ui-34">@@ -421,7 +432,7 @@ export function DataRecipesPage(): ReactElement {</div><DropdownMenu><DropdownMenuTrigger asChild={true}>- <Button type="button" disabled={isBusy}>+ <Button type="button" data-tour="recipes-new" disabled={isBusy}><HugeiconsIcon icon={PlusSignIcon} className="size-4" />New Recipe<HugeiconsIcon@@ -453,7 +464,10 @@ export function DataRecipesPage(): ReactElement {{ready ? (recipes.length === 0 ? (- <Empty className="mt-8 border border-dashed border-border/70 dark:border-none">+ <Empty+ data-tour="recipes-templates"+ className="mt-8 border border-dashed border-border/70 dark:border-none"+ ><EmptyHeader><EmptyMedia variant="icon"><HugeiconsIcon icon={CookBookIcon} className="size-5" />@@ -484,7 +498,7 @@ export function DataRecipesPage(): ReactElement {</EmptyContent></Empty>) : (- <div className="mt-8 space-y-2">+ <div data-tour="recipes-list" className="mt-8 space-y-2">{recipes.map((recipe) => (<divkey={recipe.id}diff --git a/studio/frontend/src/features/data-recipes/tour/index.ts b/studio/frontend/src/features/data-recipes/tour/index.tsnew file mode 100644index 00000000000..82ec9e20b8c--- /dev/null+++ b/studio/frontend/src/features/data-recipes/tour/index.ts@@ -0,0 +1,4 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++export { buildDataRecipesTourSteps } from "./steps";diff --git a/studio/frontend/src/features/data-recipes/tour/steps.tsx b/studio/frontend/src/features/data-recipes/tour/steps.tsxnew file mode 100644index 00000000000..e220cc09b58--- /dev/null+++ b/studio/frontend/src/features/data-recipes/tour/steps.tsx@@ -0,0 +1,57 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import type { TourStep } from "@/features/tour";++/** The list and the learning-recipe cards are two branches of one slot; neither mounts until ready. */+export function buildDataRecipesTourSteps({+ ready,+ hasRecipes,+}: {+ ready: boolean;+ hasRecipes: boolean;+}): TourStep[] {+ const steps: TourStep[] = [+ {+ id: "new",+ target: "recipes-new",+ title: "Build a dataset",+ body: (+ <>+ A recipe turns raw documents into training data. Start empty, or from+ a learning recipe already wired up for a common job.+ </>+ ),+ },+ ];++ if (!ready) return steps;++ steps.push(+ hasRecipes+ ? {+ id: "list",+ target: "recipes-list",+ title: "Your recipes",+ body: (+ <>+ Open one to edit its steps or rerun it. Recipes are saved on this+ device, and a run's dataset is ready to pick on the Train page.+ </>+ ),+ }+ : {+ id: "templates",+ target: "recipes-templates",+ title: "Learning recipes",+ body: (+ <>+ Worked examples you can open and run as they are. The fastest way+ to see how nodes connect.+ </>+ ),+ },+ );++ return steps;+}diff --git a/studio/frontend/src/features/export/tour/steps.tsx b/studio/frontend/src/features/export/tour/steps.tsxindex ca7bb1ddb52..d4aa7ac928d 100644--- a/studio/frontend/src/features/export/tour/steps.tsx+++ b/studio/frontend/src/features/export/tour/steps.tsx@@ -7,34 +7,34 @@ export const exportTourSteps: TourStep[] = [{id: "training-run",target: "export-training-run",- title: "Pick training run",+ title: "Pick a run",body: (<>- Start by selecting the training run. Each run groups the checkpoints- produced by that specific fine-tuning job.+ Start here. Each run holds the checkpoints from one fine-tuning job.+ Runs you started on the Train page show up automatically.</>),},{id: "checkpoint",target: "export-checkpoint",- title: "Pick checkpoint",+ title: "Pick a checkpoint",body: (<>- Pick which checkpoint to export. If you trained multiple checkpoints,- it’s worth exporting 1-2 candidates and testing in Chat.+ The last checkpoint is not always the best one. Export one or two+ candidates and compare them in Chat before you commit.</>),},{id: "method",target: "export-method",- title: "Export method",+ title: "Choose a format",body: (<>- Choose the packaging. GGUF is for llama.cpp-style runtimes (pick a- quant). Safetensors is for HF/Transformers-style usage. If you’re unsure,- start with safetensors.+ Merged is a full 16-bit model for vLLM or Transformers. LoRA Only ships+ the adapter alone and needs the base model at inference. GGUF is for+ llama.cpp and Ollama, with a quant level you pick below.</>),},@@ -44,8 +44,9 @@ export const exportTourSteps: TourStep[] = [title: "Export",body: (<>- Export to local or push to HF Hub. After export, test in Chat and compare- against base to confirm behavior is what you expect.+ Save to this device or push straight to a Hugging Face repo. Anything+ exported locally shows up in Chat under On Device, so you can test it+ against the base model right away.</>),},diff --git a/studio/frontend/src/features/hub/catalog/models-header.tsx b/studio/frontend/src/features/hub/catalog/models-header.tsxindex 47798d0501f..1c3da08cb7c 100644--- a/studio/frontend/src/features/hub/catalog/models-header.tsx+++ b/studio/frontend/src/features/hub/catalog/models-header.tsx@@ -68,7 +68,10 @@ export function ModelsHeader({}/>- <div className="flex min-w-0 flex-wrap items-center justify-end gap-1.5 sm:flex-1">+ <div+ data-tour="hub-device"+ className="flex min-w-0 flex-wrap items-center justify-end gap-1.5 sm:flex-1"+ ><HfTokenIndicator onOpenSettings={() => openSettings("general")} /><TransportToggle /><StatPilldiff --git a/studio/frontend/src/features/hub/catalog/models-toolbar.tsx b/studio/frontend/src/features/hub/catalog/models-toolbar.tsxindex 22a938aceab..9194d52c7ba 100644--- a/studio/frontend/src/features/hub/catalog/models-toolbar.tsx+++ b/studio/frontend/src/features/hub/catalog/models-toolbar.tsx@@ -205,6 +205,7 @@ export const ModelsToolbar = memo(function ModelsToolbar({className="flex min-w-0 flex-col gap-2 lg:flex-row lg:flex-wrap lg:items-center"><div+ data-tour="hub-tabs"className={cn("hub-menu-trigger hub-tab-toggle relative inline-flex h-9 w-full shrink-0 items-center rounded-full lg:w-[280px]",)}@@ -251,6 +252,7 @@ export const ModelsToolbar = memo(function ModelsToolbar({<divref={searchWrapRef}+ data-tour="hub-search"className="relative min-w-0 flex-1 lg:min-w-[220px] lg:flex-[1_1_220px]"><HugeiconsIcondiff --git a/studio/frontend/src/features/hub/hub-page.tsx b/studio/frontend/src/features/hub/hub-page.tsxindex 966f568d697..2a8747ad3f5 100644--- a/studio/frontend/src/features/hub/hub-page.tsx+++ b/studio/frontend/src/features/hub/hub-page.tsx@@ -23,6 +23,7 @@ import {requestModelConfigHandoff,} from "@/features/model-picker";import { loadOpenAIAutoSwitchSettings } from "@/features/settings";+import { GuidedTour, useGuidedTourController } from "@/features/tour";import { useDebouncedValue } from "@/hooks/use-debounced-value";import { useGpuInfo, useInferenceGpuInfo } from "@/hooks/use-gpu-info";import { useVramBudgetFraction } from "@/hooks/use-vram-budget-fraction";@@ -44,6 +45,7 @@ import { FreeUpSpaceDialog } from "./catalog/free-up-space-dialog";import { HubDetailView } from "./catalog/hub-detail-view";import { HubFeed } from "./catalog/hub-feed";import { HubTopBar } from "./catalog/hub-top-bar";+import { buildHubTourSteps } from "./tour";import {ModelsCatalog,type ModelsCatalogHandlers,@@ -1771,8 +1773,14 @@ export function ModelsPage() {// Unreachable under the full-page detail overlay.const catalogCovered = detailOpen && !splitMode;+ const tour = useGuidedTourController({+ id: "hub",+ steps: useMemo(() => buildHubTourSteps({ catalogCovered }), [catalogCovered]),+ });+return (<div className="hub-page flex min-h-0 min-w-0 flex-1 basis-0 flex-col overflow-hidden bg-background">+ <GuidedTour {...tour.tourProps} /><HubTopBar><ModelsHeadercachedCount={visibleCachedCount}@@ -1816,6 +1824,7 @@ export function ModelsPage() {)}><div+ data-tour="hub-catalog"className={cn("flex min-h-0 flex-col",// Split mode keeps the catalog as a master pane that grows off a 460px floor; otherwise it@@ -1868,6 +1877,7 @@ export function ModelsPage() {) : (detailOpen && (<div+ data-tour="hub-detail"className="hub-canvas absolute inset-0 z-20 flex min-h-0 flex-col"><HubDetailViewdiff --git a/studio/frontend/src/features/hub/tour/index.ts b/studio/frontend/src/features/hub/tour/index.tsnew file mode 100644index 00000000000..b2fd3c7417b--- /dev/null+++ b/studio/frontend/src/features/hub/tour/index.ts@@ -0,0 +1,4 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++export { buildHubTourSteps } from "./steps";diff --git a/studio/frontend/src/features/hub/tour/steps.tsx b/studio/frontend/src/features/hub/tour/steps.tsxnew file mode 100644index 00000000000..e1ffc8d711c--- /dev/null+++ b/studio/frontend/src/features/hub/tour/steps.tsx@@ -0,0 +1,72 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import type { TourStep } from "@/features/tour";++const catalogStep: TourStep = {+ id: "catalog",+ target: "hub-catalog",+ title: "Results",+ body: (+ <>+ Open any model for its files, quant variants and size. From there you+ download it, run it in Chat, or delete it to free up space.+ </>+ ),+};++const detailStep: TourStep = {+ id: "detail",+ target: "hub-detail",+ title: "Model details",+ body: (+ <>+ Files, quant variants and sizes, with the README below. Download it here,+ run it in Chat, or use Back to return to the results.+ </>+ ),+};++/** Outside split view an open model detail covers the catalog, so describe what is on top. */+export function buildHubTourSteps({+ catalogCovered,+}: {+ catalogCovered: boolean;+}): TourStep[] {+ return [+ {+ id: "tabs",+ target: "hub-tabs",+ title: "Discover or On Device",+ body: (+ <>+ Discover browses Hugging Face. On Device lists what is downloaded+ here, including your own finetunes, with the disk each one uses.+ </>+ ),+ },+ {+ id: "search",+ target: "hub-search",+ title: "Search the Hub",+ body: (+ <>+ Search by name, or paste <span className="font-mono">org/model</span>{" "}+ to jump straight to a repo. Unsloth's own quants rank first.+ </>+ ),+ },+ {+ id: "device",+ target: "hub-device",+ title: "Your hardware",+ body: (+ <>+ VRAM, RAM and cache size, so you know what will run before you+ download. Add a Hugging Face token here for gated repos.+ </>+ ),+ },+ catalogCovered ? detailStep : catalogStep,+ ];+}diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsxindex 538d0a4414e..a45fbbc57c4 100644--- a/studio/frontend/src/features/images/images-page.tsx+++ b/studio/frontend/src/features/images/images-page.tsx@@ -20,6 +20,8 @@ import { HugeiconsIcon, type IconSvgElement } from "@hugeicons/react";import { TestTubeOutlineIcon } from "@/lib/hugeicons-derived";import { ImageDropzone } from "@/components/image-dropzone";+import { GuidedTour, useGuidedTourController } from "@/features/tour";+import { buildImagesTourSteps } from "./tour";import { Button } from "@/components/ui/button";import {DropdownMenu,@@ -1249,6 +1251,15 @@ export function ImagesPage({// Page mode: "create" is the generation workspace, "train" the LoRA training workspace.const pageMode = useImageWorkflowStore((s) => s.pageMode);const setPageMode = useImageWorkflowStore((s) => s.setPageMode);+ const tourSteps = useMemo(+ () => buildImagesTourSteps({ pageMode }),+ [pageMode],+ );+ const tour = useGuidedTourController({+ id: "images",+ steps: tourSteps,+ enabled: active,+ });// Train family + base live here so the top bar can pick them, replacing the generation model selector on Train.const [trainFamilies, setTrainFamilies] = useState<TrainFamilyOption[]>([]);const [trainFamilyName, setTrainFamilyName] = useState("flux.1");@@ -3837,6 +3848,8 @@ export function ImagesPage({// The chat-style layout gives this page no outer top inset, so clear the custom titlebar here as chat does.// 34px on win/linux, 0 under macOS's native one.<div className="diffusion-surface @container flex h-full min-h-0 min-w-0 flex-1 flex-col overflow-hidden pt-[var(--studio-content-top-inset,0px)]">+ {/* Portals to body, and this page stays mounted off-route, so gate it like the composer. */}+ {active && <GuidedTour {...tour.tourProps} />}{/* Keep the tabs centered over the preview at every width: the model rail holds at 408px whenspace permits and shrinks only to preserve the controls. */}<div className="pointer-events-none relative z-40 grid h-[48px] shrink-0 grid-cols-[minmax(0,408px)_minmax(13rem,1fr)]">@@ -3863,6 +3876,7 @@ export function ImagesPage({/>) : (<ModelSelector+ triggerDataTour="images-model"models={imageModels}value={status?.loaded ? status.repo_id ?? undefined : undefined}activeGgufVariant={quant}@@ -3901,6 +3915,7 @@ export function ImagesPage({<div className="grid h-full min-w-0 grid-cols-[1fr_auto_auto] gap-2 @[50rem]:grid-cols-[1fr_auto_1fr] @[50rem]:gap-0"><div className="pointer-events-auto col-start-2 justify-self-center pt-[var(--studio-chat-header-padding-top,11px)]"><PillTabs+ dataTour="images-mode"ariaLabel="Page mode"value={pageMode}onValueChange={(v) => setPageMode(v as "create" | "train")}@@ -3947,7 +3962,10 @@ export function ImagesPage({/* Settings column + preview canvas. Structural borders stay edge-to-edge; spacing belongs inside each pane.The same 50rem page-container breakpoint drives this body and the header above. */<div className="flex min-h-0 w-full min-w-0 flex-1 flex-col overflow-y-auto overflow-x-hidden @[50rem]:flex-row @[50rem]:overflow-hidden">- <div className="flex w-full shrink-0 flex-col border-b border-border/60 @[50rem]:w-[408px] @[50rem]:overflow-hidden @[50rem]:border-r @[50rem]:border-b-0">+ <div+ data-tour="images-settings"+ className="flex w-full shrink-0 flex-col border-b border-border/60 @[50rem]:w-[408px] @[50rem]:overflow-hidden @[50rem]:border-r @[50rem]:border-b-0"+ >{/* pl-0.5 keeps focus rings off the scroll container's edge. */}<divref={attachSettingsScroll}@@ -4541,7 +4559,10 @@ export function ImagesPage({</div></div>- <div className="relative flex min-h-[60dvh] min-w-0 flex-1 flex-col overflow-hidden @[50rem]:min-h-0">+ <div+ data-tour="images-preview"+ className="relative flex min-h-[60dvh] min-w-0 flex-1 flex-col overflow-hidden @[50rem]:min-h-0"+ ><div className="hover-scrollbar relative flex flex-1 items-center justify-center overflow-auto p-6 px-10 @[50rem]:pt-[60px]">{selected && selectedSrc ? (<>diff --git a/studio/frontend/src/features/images/tour/index.ts b/studio/frontend/src/features/images/tour/index.tsnew file mode 100644index 00000000000..17aa7012acb--- /dev/null+++ b/studio/frontend/src/features/images/tour/index.ts@@ -0,0 +1,4 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++export { buildImagesTourSteps } from "./steps";diff --git a/studio/frontend/src/features/images/tour/steps.tsx b/studio/frontend/src/features/images/tour/steps.tsxnew file mode 100644index 00000000000..b1f50983258--- /dev/null+++ b/studio/frontend/src/features/images/tour/steps.tsx@@ -0,0 +1,90 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import type { TourStep } from "@/features/tour";++const modeStep: TourStep = {+ id: "mode",+ target: "images-mode",+ title: "Create or Train",+ body: (+ <>+ Create generates images. Train fine-tunes a diffusion LoRA on your own+ pictures. The sidebar workflows, such as edit, inpaint, extend and+ upscale, all run in Create.+ </>+ ),+};++/** Create and Train swap the whole page body, so each mode gets the anchors it actually has. */+export function buildImagesTourSteps({+ pageMode,+}: {+ pageMode: "create" | "train";+}): TourStep[] {+ if (pageMode === "train") {+ return [+ modeStep,+ {+ id: "train-dataset",+ target: "images-train-dataset",+ title: "Your images",+ body: (+ <>+ Drop in a folder, pick a dataset, or start from an example. Captions+ matter here, so fill gaps in the labeling grid before you train.+ </>+ ),+ },+ {+ id: "train-start",+ target: "images-train-start",+ title: "Start training",+ body: (+ <>+ Runs a LoRA on the base model above. Progress and samples appear on+ the right, and finished LoRAs load back into Create.+ </>+ ),+ },+ ];+ }++ return [+ modeStep,+ {+ id: "model",+ target: "images-model",+ title: "Pick a model",+ body: (+ <>+ Image models you have downloaded, plus anything on Hugging Face. The+ model decides which controls appear below, such as LoRAs and+ ControlNet.+ </>+ ),+ },+ {+ id: "settings",+ target: "images-settings",+ title: "Settings",+ body: (+ <>+ Prompt, aspect ratio, steps, guidance, batch size and seed. Save a+ setup as a preset, and reuse a seed to repeat a result exactly.+ </>+ ),+ },+ {+ id: "preview",+ target: "images-preview",+ title: "Results",+ body: (+ <>+ The selected image fills this pane and everything you make lines up+ below. Save it here, or send it into another workflow like upscale.+ </>+ ),+ },+ ];+}diff --git a/studio/frontend/src/features/images/train/diffusion-train-panel.tsx b/studio/frontend/src/features/images/train/diffusion-train-panel.tsxindex ee73ce7a4ee..48653bc158e 100644--- a/studio/frontend/src/features/images/train/diffusion-train-panel.tsx+++ b/studio/frontend/src/features/images/train/diffusion-train-panel.tsx@@ -1604,6 +1604,7 @@ export function DiffusionTrainPanel({{/* the whole field is the drop zone, so a folder can land on the picker, the thumbnails or thecaption grid. */}<div+ data-tour="images-train-dataset"className={cn(fieldClass,"rounded-lg transition-colors",@@ -1864,7 +1865,10 @@ export function DiffusionTrainPanel({</div>{/* In its own footer, as Create's Generate is. The scroll mask provides the fade, so the footerstays unpainted to avoid dark-mode banding. */}- <div className="relative z-10 flex shrink-0 justify-center pt-0.5 pb-4 pl-8 pr-8">+ <div+ data-tour="images-train-start"+ className="relative z-10 flex shrink-0 justify-center pt-0.5 pb-4 pl-8 pr-8"+ ><Buttontype="button"className="relative z-10 h-11 px-8 disabled:bg-muted disabled:text-muted-foreground disabled:opacity-100"diff --git a/studio/frontend/src/features/model-picker/components/model-selector/pill-tabs.tsx b/studio/frontend/src/features/model-picker/components/model-selector/pill-tabs.tsxindex ef484a221fa..368f0cf421b 100644--- a/studio/frontend/src/features/model-picker/components/model-selector/pill-tabs.tsx+++ b/studio/frontend/src/features/model-picker/components/model-selector/pill-tabs.tsx@@ -21,6 +21,7 @@ export function PillTabs({compact = false,fit = false,disabled = false,+ dataTour,}: {tabs: PillTab[];value: string;@@ -28,6 +29,8 @@ export function PillTabs({ariaLabel: string;className?: string;compact?: boolean;+ /** Guided-tour anchor, read as `[data-tour="..."]`. */+ dataTour?: string;/** Block every tab, for a choice that cannot be applied right now. */disabled?: boolean;/** Size each tab to its label instead of equal widths. The active tab carries@@ -43,6 +46,7 @@ export function PillTabs({<divrole="tablist"aria-label={ariaLabel}+ data-tour={dataTour}className={cn("hub-menu-trigger hub-tab-toggle relative inline-flex items-center rounded-full",compact ? "h-7" : "h-(--picker-control-h)",diff --git a/studio/frontend/src/features/recipe-studio/components/controls/run-validate-floating-controls.tsx b/studio/frontend/src/features/recipe-studio/components/controls/run-validate-floating-controls.tsxindex 2838ab70483..7c9c392fcef 100644--- a/studio/frontend/src/features/recipe-studio/components/controls/run-validate-floating-controls.tsx+++ b/studio/frontend/src/features/recipe-studio/components/controls/run-validate-floating-controls.tsx@@ -26,7 +26,10 @@ export function RunValidateFloatingControls({}: RunValidateFloatingControlsProps): ReactElement {return (<div className="pointer-events-none absolute inset-x-0 bottom-3 z-20 flex justify-center">- <div className="pointer-events-auto flex items-center gap-2">+ <div+ data-tour="recipe-run"+ className="pointer-events-auto flex items-center gap-2"+ ><Buttontype="button"className="corner-squircle h-11 px-5"diff --git a/studio/frontend/src/features/recipe-studio/components/recipe-studio-header.tsx b/studio/frontend/src/features/recipe-studio/components/recipe-studio-header.tsxindex af22778ce5f..b8bf0c0d6f8 100644--- a/studio/frontend/src/features/recipe-studio/components/recipe-studio-header.tsx+++ b/studio/frontend/src/features/recipe-studio/components/recipe-studio-header.tsx@@ -129,7 +129,7 @@ export function RecipeStudioHeader({</span></div></div>- <div className="justify-self-center">+ <div data-tour="recipe-views" className="justify-self-center"><Tabs value={activeView} onValueChange={handleViewValueChange}><TabsList>{supportsEasyMode && (@@ -190,6 +190,7 @@ export function RecipeStudioHeader({type="button"size="sm"variant="outline"+ data-tour="recipe-save"onClick={onSaveRecipe}disabled={saveLoading}>diff --git a/studio/frontend/src/features/recipe-studio/recipe-studio-page.tsx b/studio/frontend/src/features/recipe-studio/recipe-studio-page.tsxindex fa50bb28194..7226129e004 100644--- a/studio/frontend/src/features/recipe-studio/recipe-studio-page.tsx+++ b/studio/frontend/src/features/recipe-studio/recipe-studio-page.tsx@@ -28,6 +28,8 @@ import {import { useShallow } from "zustand/react/shallow";import "@xyflow/react/dist/style.css";import { Button } from "@/components/ui/button";+import { GuidedTour, useGuidedTourController } from "@/features/tour";+import { buildRecipeEditorTourSteps } from "./tour";import { BlockSheet } from "./components/block-sheet";import { LayoutControls } from "./components/controls/layout-controls";import { RunValidateFloatingControls } from "./components/controls/run-validate-floating-controls";@@ -390,6 +392,20 @@ export function RecipeStudioPage({auxNodePositions,llmAuxVisibility,});+ const tourSteps = useMemo(+ () =>+ buildRecipeEditorTourSteps({+ // A placeholder stands in until the recipe loads, so the canvas steps would hit nothing.+ isGraphView: activeView === "editor" && initialRecipeReady,+ supportsEasyMode,+ }),+ [activeView, initialRecipeReady, supportsEasyMode],+ );+ const tour = useGuidedTourController({+ id: "recipe-editor",+ steps: tourSteps,+ });+const executionLocked = runtimeVisualState.executionLocked;const canvasInteractive = interactive && !executionLocked;const runBusy = previewLoading || fullLoading || executionLocked;@@ -723,7 +739,7 @@ export function RecipeStudioPage({</div></div>)}- <Panel position="top-right" className="m-3">+ <Panel position="top-right" className="m-3" data-tour="recipe-add-step"><BlockSheetcontainer={sheetContainer}sheetView={sheetView}@@ -809,6 +825,7 @@ export function RecipeStudioPage({}><main className="flex min-h-0 w-full flex-1 flex-col">+ <GuidedTour {...tour.tourProps} /><divclassName="relative flex min-h-0 w-full flex-1 flex-col overflow-hidden border"ref={setSheetContainer}@@ -828,6 +845,7 @@ export function RecipeStudioPage({}}/><div+ data-tour="recipe-canvas"className="flex min-h-0 w-full flex-1 rounded-t-none"ref={flowContainerRef}>diff --git a/studio/frontend/src/features/recipe-studio/tour/index.ts b/studio/frontend/src/features/recipe-studio/tour/index.tsnew file mode 100644index 00000000000..9516f077f0a--- /dev/null+++ b/studio/frontend/src/features/recipe-studio/tour/index.ts@@ -0,0 +1,4 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++export { buildRecipeEditorTourSteps } from "./steps";diff --git a/studio/frontend/src/features/recipe-studio/tour/steps.tsx b/studio/frontend/src/features/recipe-studio/tour/steps.tsxnew file mode 100644index 00000000000..4e01eba3020--- /dev/null+++ b/studio/frontend/src/features/recipe-studio/tour/steps.tsx@@ -0,0 +1,81 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import type { TourStep } from "@/features/tour";++/** Without an Easy form the tabs read Editor and Runs, so neither "three" nor "Advanced" fits. */+function viewsStep(supportsEasyMode: boolean): TourStep {+ return {+ id: "views",+ target: "recipe-views",+ title: supportsEasyMode ? "Three views" : "Two views",+ body: supportsEasyMode ? (+ <>+ Easy is a plain form, Advanced is the node graph, and Runs keeps every+ execution with the dataset it produced.+ </>+ ) : (+ <>+ Editor is the node graph. Runs keeps every execution with the dataset it+ produced.+ </>+ ),+ };+}++const saveStep: TourStep = {+ id: "save",+ target: "recipe-save",+ title: "Save",+ body: <>Recipes are stored on this device. Save before a long run.</>,+};++/** Only the graph view mounts the canvas and its controls, and only once the recipe has loaded. */+export function buildRecipeEditorTourSteps({+ isGraphView,+ supportsEasyMode,+}: {+ isGraphView: boolean;+ supportsEasyMode: boolean;+}): TourStep[] {+ if (!isGraphView) {+ return [viewsStep(supportsEasyMode), saveStep];+ }++ return [+ viewsStep(supportsEasyMode),+ {+ id: "canvas",+ target: "recipe-canvas",+ title: "The graph",+ body: (+ <>+ Each node is one step, and the wires carry rows forward. A source node+ in, a dataset you can train on out.+ </>+ ),+ },+ {+ id: "add-step",+ target: "recipe-add-step",+ title: "Add a step",+ body: (+ <>+ Source data, samplers, model calls, validators and expressions. Import+ is where a PDF or a folder of text enters the graph.+ </>+ ),+ },+ {+ id: "run",+ target: "recipe-run",+ title: "Check and run",+ body: (+ <>+ Check reports broken wires and missing settings without spending+ tokens. Run lands the result in Runs, ready for the Train page.+ </>+ ),+ },+ ];+}diff --git a/studio/frontend/src/features/studio/studio-navigation.tsx b/studio/frontend/src/features/studio/studio-navigation.tsxindex d2b995cbe5d..a38ae6874a8 100644--- a/studio/frontend/src/features/studio/studio-navigation.tsx+++ b/studio/frontend/src/features/studio/studio-navigation.tsx@@ -37,6 +37,7 @@ export function TrainSubNav({return (<TabsListunstyled={true}+ data-tour="studio-subnav"className="flex min-w-0 flex-1 flex-wrap items-center justify-start gap-3 pb-px text-ui-13 tracking-nav sm:gap-6">{items.map((item) => {diff --git a/studio/frontend/src/features/studio/studio-page.tsx b/studio/frontend/src/features/studio/studio-page.tsxindex 60ba336fdf4..702dd70f9fc 100644--- a/studio/frontend/src/features/studio/studio-page.tsx+++ b/studio/frontend/src/features/studio/studio-page.tsx@@ -4,7 +4,6 @@import { useAppShellReadySignal } from "@/components/app-readiness";import { usePlatformStore } from "@/config/env";import { Button } from "@/components/ui/button";-import { useSidebar } from "@/components/ui/sidebar";import { Spinner } from "@/components/ui/spinner";import { Tabs, TabsContent } from "@/components/ui/tabs";import { useHfTokenStore } from "@/features/hub";@@ -27,9 +26,7 @@ import {import { useNavigate } from "@tanstack/react-router";import {type ReactElement,- useCallback,useEffect,- useMemo,useRef,} from "react";import { useShallow } from "zustand/react/shallow";@@ -39,7 +36,11 @@ import { useTrainingCacheReconciliation } from "./hooks/use-training-cache-reconimport { LiveTrainingView } from "./live-training-view";import { DatasetPreviewDialog } from "./sections/dataset-preview-dialog";import { TrainSubNav } from "./studio-navigation";-import { studioTourSteps, studioTrainingTourSteps } from "./tour";+import {+ studioHistoryTourSteps,+ studioTourSteps,+ studioTrainingTourSteps,+} from "./tour";import {type TrainSubTab,getStudioSubtitle,@@ -112,20 +113,15 @@ export function StudioPage(): ReactElement {showTrainingView,} = useStudioNavigation();- const { setPinned } = useSidebar();- const pinSidebar = useCallback(() => setPinned(true), [setPinned]);-const tourEnabled = hasHydratedRuntime && !isHydratingRuntime;const isConfigTour = activeTab === "configure";- const baseTourSteps =- activeTab === "current-run" ? studioTrainingTourSteps : studioTourSteps;- const tourSteps = useMemo(- () =>- baseTourSteps.map((step) =>- step.target === "navbar" ? { ...step, onEnter: pinSidebar } : step,- ),- [baseTourSteps, pinSidebar],- );+ // Each tab unmounts the others, so each gets the steps whose anchors are actually on screen.+ const tourSteps =+ activeTab === "current-run"+ ? studioTrainingTourSteps+ : activeTab === "history"+ ? studioHistoryTourSteps+ : studioTourSteps;const tour = useGuidedTourController({id: "studio",steps: tourSteps,@@ -268,7 +264,11 @@ export function StudioPage(): ReactElement {<TabsContent value="current-run" className="mt-0"><LiveTrainingView /></TabsContent>- <TabsContent value="history" className="mt-0">+ <TabsContent+ value="history"+ className="mt-0"+ data-tour="studio-history"+ >{selectedHistoryRunId ? (<HistoricalTrainingViewrunId={selectedHistoryRunId}diff --git a/studio/frontend/src/features/studio/tour/history/index.ts b/studio/frontend/src/features/studio/tour/history/index.tsnew file mode 100644index 00000000000..9baab6b047e--- /dev/null+++ b/studio/frontend/src/features/studio/tour/history/index.ts@@ -0,0 +1,4 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++export { studioHistoryTourSteps } from "./steps";diff --git a/studio/frontend/src/features/studio/tour/history/steps.tsx b/studio/frontend/src/features/studio/tour/history/steps.tsxnew file mode 100644index 00000000000..af951b6cb2f--- /dev/null+++ b/studio/frontend/src/features/studio/tour/history/steps.tsx@@ -0,0 +1,21 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import type { TourStep } from "@/features/tour";+import { studioNavStep } from "../steps/nav";++export const studioHistoryTourSteps: TourStep[] = [+ studioNavStep,+ {+ id: "history",+ target: "studio-history",+ title: "Past runs",+ body: (+ <>+ Every finished or stopped run, with its config and loss curves. Open one+ to see how it went, resume it from its last checkpoint, or send its+ checkpoints to Export.+ </>+ ),+ },+];diff --git a/studio/frontend/src/features/studio/tour/index.ts b/studio/frontend/src/features/studio/tour/index.tsindex 2a4cf9ff335..e1293e6e709 100644--- a/studio/frontend/src/features/studio/tour/index.ts+++ b/studio/frontend/src/features/studio/tour/index.ts@@ -1,5 +1,6 @@// SPDX-License-Identifier: AGPL-3.0-only// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0+export { studioHistoryTourSteps } from "./history";export { studioTourSteps } from "./steps";export { studioTrainingTourSteps } from "./training";diff --git a/studio/frontend/src/features/studio/tour/steps/base-model.tsx b/studio/frontend/src/features/studio/tour/steps/base-model.tsxindex da882eb31df..0cb4cd1d646 100644--- a/studio/frontend/src/features/studio/tour/steps/base-model.tsx+++ b/studio/frontend/src/features/studio/tour/steps/base-model.tsx@@ -6,13 +6,13 @@ import { ReadMore, type TourStep } from "@/features/tour";export const studioBaseModelStep: TourStep = {id: "base-model",target: "studio-model-picker",- title: "Model",+ title: "Base model",body: (<>- Search Hugging Face, browse models already on this device, or paste{" "}- <span className="font-mono">org/model</span>. Pick a base model close to- your task (chat/instruct vs base). Smaller models iterate faster; scale up- once prompts + data look good.{" "}+ Search Hugging Face, reuse a model already on this device, or paste{" "}+ <span className="font-mono">org/model</span>. Picking one auto-fills+ sensible hyperparameters. Smaller models iterate faster, so scale up once+ the data looks right. GGUF files cannot be trained.{" "}<ReadMore href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/what-model-should-i-use" /></>),diff --git a/studio/frontend/src/features/studio/tour/steps/dataset.tsx b/studio/frontend/src/features/studio/tour/steps/dataset.tsxindex 8783a337952..856aaea6603 100644--- a/studio/frontend/src/features/studio/tour/steps/dataset.tsx+++ b/studio/frontend/src/features/studio/tour/steps/dataset.tsx@@ -9,11 +9,10 @@ export const studioDatasetStep: TourStep = {title: "Dataset",body: (<>- Search Hub or paste <span className="font-mono">user/dataset</span>. Preview- a few rows: formatting matters more than size. We’ll try to auto-convert- your dataset into a supported training format. If we can’t infer it- cleanly, we’ll prompt you to map the fields manually. If outputs look off- in Chat later, dataset formatting/template is the first thing to check.{" "}+ Search the Hub, or upload PDF, DOCX, JSONL, JSON, CSV or Parquet. Preview+ a few rows before you start, since formatting matters more than size. We+ map the columns for you and ask only when the format is unclear. No+ dataset yet? Build one on the Recipes page.{" "}<ReadMore href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/datasets-guide" /></>),diff --git a/studio/frontend/src/features/studio/tour/steps/index.tsx b/studio/frontend/src/features/studio/tour/steps/index.tsxindex aa712928ccd..df4c7c8131d 100644--- a/studio/frontend/src/features/studio/tour/steps/index.tsx+++ b/studio/frontend/src/features/studio/tour/steps/index.tsx@@ -7,8 +7,7 @@ import { studioDatasetStep } from "./dataset";import { studioMethodStep } from "./method";import { studioNavStep } from "./nav";import { studioParamsStep } from "./params";-import { studioSaveStep } from "./save";-import { studioStartStep } from "./start";+import { studioPreviewStep } from "./preview";export const studioTourSteps: TourStep[] = [studioNavStep,@@ -16,6 +15,5 @@ export const studioTourSteps: TourStep[] = [studioMethodStep,studioDatasetStep,studioParamsStep,- studioStartStep,- studioSaveStep,+ studioPreviewStep,];diff --git a/studio/frontend/src/features/studio/tour/steps/method.tsx b/studio/frontend/src/features/studio/tour/steps/method.tsxindex a3e663096b0..a330fc9d3e1 100644--- a/studio/frontend/src/features/studio/tour/steps/method.tsx+++ b/studio/frontend/src/features/studio/tour/steps/method.tsx@@ -6,12 +6,12 @@ import { ReadMore, type TourStep } from "@/features/tour";export const studioMethodStep: TourStep = {id: "method",target: "studio-method",- title: "Method: QLoRA vs LoRA vs Full",+ title: "Training method",body: (<>- LoRA: trains small adapter weights (fast, common default). QLoRA: LoRA on- 4-bit base weights (much lower VRAM). Full: updates all weights (highest- cost, usually needs more data to be worth it).{" "}+ QLoRA trains adapters on a 4-bit base and needs the least VRAM. LoRA does+ the same in 16-bit. Full fine-tune updates every weight. Continued+ pretraining is for teaching a new domain or language.{" "}<ReadMore href="https://unsloth.ai/docs/basics/lora-hyperparameters-guide" /></>),diff --git a/studio/frontend/src/features/studio/tour/steps/nav.tsx b/studio/frontend/src/features/studio/tour/steps/nav.tsxindex 8a8da8cab00..5aa52100294 100644--- a/studio/frontend/src/features/studio/tour/steps/nav.tsx+++ b/studio/frontend/src/features/studio/tour/steps/nav.tsx@@ -5,13 +5,13 @@ import { ReadMore, type TourStep } from "@/features/tour";export const studioNavStep: TourStep = {id: "nav",- target: "navbar",- title: "Quick orientation",+ target: "studio-subnav",+ title: "Three tabs",body: (<>- Unsloth: pick base model, dataset, hyperparams, then start training. After- you start, you’ll see a Training view with live loss/metrics. Chat is for- testing base vs LoRA adapters. Export packages checkpoints for deployment.{" "}+ Configure sets up a run. Current Run shows live loss and metrics once it+ starts. History keeps every past run, so you can reopen, resume or export+ one. Image and diffusion training lives on the Images page.{" "}<ReadMore href="https://unsloth.ai/docs/get-started/fine-tuning-for-beginners" /></>),diff --git a/studio/frontend/src/features/studio/tour/steps/params.tsx b/studio/frontend/src/features/studio/tour/steps/params.tsxindex 73bf86d84b5..4f5d83dda71 100644--- a/studio/frontend/src/features/studio/tour/steps/params.tsx+++ b/studio/frontend/src/features/studio/tour/steps/params.tsx@@ -6,12 +6,13 @@ import { ReadMore, type TourStep } from "@/features/tour";export const studioParamsStep: TourStep = {id: "params",target: "studio-params",- title: "Dial hyperparams",+ title: "Parameters",body: (<>- Start boring, then iterate. We usually recommend starting with 1-3 epochs- (higher can overfit fast). If you’re unsure, change 1 knob at a time, and- watch train vs eval loss.{" "}+ Simple covers epochs, learning rate, batch size and context length.+ Advanced opens LoRA rank, schedulers, eval and checkpointing. Defaults+ come from the model you picked, so change one knob at a time. 1 to 3+ epochs is a good start.{" "}<ReadMore href="https://unsloth.ai/docs/basics/lora-hyperparameters-guide" /></>),diff --git a/studio/frontend/src/features/studio/tour/steps/preview.tsx b/studio/frontend/src/features/studio/tour/steps/preview.tsxnew file mode 100644index 00000000000..4c5eaeeb4c6--- /dev/null+++ b/studio/frontend/src/features/studio/tour/steps/preview.tsx@@ -0,0 +1,18 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import type { TourStep } from "@/features/tour";++/** The Start button sits inside this card, so one step covers the check and the launch. */+export const studioPreviewStep: TourStep = {+ id: "preview",+ target: "studio-run-preview",+ title: "Check, then start",+ body: (+ <>+ Step count, batch size, context and detected hardware, plus anything that+ downloads on start. Once the Ready pill is on, Start opens the run in+ Current Run and it keeps going if you switch pages. Do a short run first.+ </>+ ),+};diff --git a/studio/frontend/src/features/studio/tour/steps/save.tsx b/studio/frontend/src/features/studio/tour/steps/save.tsxdeleted file mode 100644index a933c4c8aba..00000000000--- a/studio/frontend/src/features/studio/tour/steps/save.tsx+++ /dev/null@@ -1,16 +0,0 @@-// SPDX-License-Identifier: AGPL-3.0-only-// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0--import type { TourStep } from "@/features/tour";--export const studioSaveStep: TourStep = {- id: "save",- target: "studio-save",- title: "Save config",- body: (- <>- Save your training config as a YAML file. Re-running the same baseline- makes it obvious if a change helped (or if you just got lucky).- </>- ),-};diff --git a/studio/frontend/src/features/studio/tour/steps/start.tsx b/studio/frontend/src/features/studio/tour/steps/start.tsxdeleted file mode 100644index b50bf9d3dad..00000000000--- a/studio/frontend/src/features/studio/tour/steps/start.tsx+++ /dev/null@@ -1,17 +0,0 @@-// SPDX-License-Identifier: AGPL-3.0-only-// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0--import type { TourStep } from "@/features/tour";--export const studioStartStep: TourStep = {- id: "start",- target: "studio-start",- title: "Start training",- body: (- <>- Kick off training. If it errors immediately, check HF token / local paths- / dataset access first. Start with a small run to sanity-check loss + sample- outputs before burning hours.- </>- ),-};diff --git a/studio/frontend/src/features/studio/tour/training/steps.tsx b/studio/frontend/src/features/studio/tour/training/steps.tsxindex 11e33d1b9c2..eb305db329d 100644--- a/studio/frontend/src/features/studio/tour/training/steps.tsx+++ b/studio/frontend/src/features/studio/tour/training/steps.tsx@@ -4,25 +4,15 @@import type { TourStep } from "@/features/tour";export const studioTrainingTourSteps: TourStep[] = [- {- id: "nav",- target: "navbar",- title: "Training view",- body: (- <>- This view updates live as training runs. Watch loss, speed, and ETA, and- use Stop if you need to bail out or save.- </>- ),- },{id: "progress",target: "studio-training-progress",- title: "Progress + ETA",+ title: "Progress and ETA",body: (<>- Phase shows what we’re doing (loading model/dataset, configuring,- training). ETA is rough early on; it stabilizes after a few steps.+ Phase says what is happening right now, from loading the model and+ dataset through to training. The ETA is rough at first and settles after+ a few steps. Leaving this page does not stop the run.</>),},@@ -32,34 +22,32 @@ export const studioTrainingTourSteps: TourStep[] = [title: "Training loss",body: (<>- Training loss should generally trend down. Absolute values vary by- dataset + tokenizer, so use it for direction more than “a magic number”.- If loss goes very low (eg below ~0.2), that can be a sign you’re- overfitting. If loss plateaus high, you likely need better data- formatting, more data, or different hyperparams.+ Watch the direction, not the number, since the scale shifts with your+ dataset and tokenizer. Flat and high usually means data formatting or+ hyperparameters. Very low, say under 0.2, usually means overfitting.</>),},{id: "eval-loss",target: "studio-eval-loss",- title: "Eval loss (validation)",+ title: "Eval loss",body: (<>- Eval loss is your sanity check. If training loss keeps dropping but eval- loss goes up, you’re likely overfitting. To track it, set an eval dataset- and `eval_steps` (setting `eval_steps=1` can be very slow).+ Your sanity check. Training loss falling while eval loss climbs is+ overfitting. It needs an eval dataset and an eval_steps value, set in+ Advanced parameters. Small eval_steps values slow the run down a lot.</>),},{id: "stop",target: "studio-training-stop",- title: "Stop / save",+ title: "Stop and save",body: (<>- Stop training any time. “Stop and Save” keeps the checkpoint/adapters so- you can export or compare later.+ Stop any time. Stop and Save keeps the checkpoint and adapters, so you+ can test them in Chat or package them on the Export page.</>),},diff --git a/studio/frontend/src/features/studio/wizard/config-actions.tsx b/studio/frontend/src/features/studio/wizard/config-actions.tsxindex ca929a31996..beb799a6e66 100644--- a/studio/frontend/src/features/studio/wizard/config-actions.tsx+++ b/studio/frontend/src/features/studio/wizard/config-actions.tsx@@ -153,7 +153,6 @@ export function ConfigActions() {<Tooltip><TooltipTrigger asChild={true}><Button- data-tour="studio-save"variant="outline"size="sm"className="h-9 cursor-pointer rounded-lg"diff --git a/studio/frontend/src/features/studio/wizard/run-preview-card.tsx b/studio/frontend/src/features/studio/wizard/run-preview-card.tsxindex 41781c5d506..f0857a21d10 100644--- a/studio/frontend/src/features/studio/wizard/run-preview-card.tsx+++ b/studio/frontend/src/features/studio/wizard/run-preview-card.tsx@@ -418,6 +418,7 @@ export function RunPreviewCard({return (<aside+ data-tour="studio-run-preview"className={cn("elevated-card elevated-card-dark-border flex flex-col gap-7 bg-foreground/[0.012] p-6","dark:bg-white/[0.018]",diff --git a/studio/frontend/src/features/studio/wizard/start-training-cta.tsx b/studio/frontend/src/features/studio/wizard/start-training-cta.tsxindex 3686b47af57..5c564ad528f 100644--- a/studio/frontend/src/features/studio/wizard/start-training-cta.tsx+++ b/studio/frontend/src/features/studio/wizard/start-training-cta.tsx@@ -135,7 +135,6 @@ export function StartTrainingCta() {return (<div className="flex flex-col gap-2"><Button- data-tour="studio-start"size="lg"className={cn("h-11 w-full justify-center rounded-xl text-ui-13p5 font-semibold tracking-tight",diff --git a/studio/frontend/src/features/tour/components/guided-tour.tsx b/studio/frontend/src/features/tour/components/guided-tour.tsxindex 033d2509123..e4c0fcf2533 100644--- a/studio/frontend/src/features/tour/components/guided-tour.tsx+++ b/studio/frontend/src/features/tour/components/guided-tour.tsx@@ -45,7 +45,14 @@ export function GuidedTour({const closeLockRef = useRef(false);const rafRef = useRef<number | null>(null);const lastRectRef = useRef<Rect | null>(null);- const activeStepRef = useRef<TourStep | null>(null);++ // Rewound during render: an effect runs after the onEnter effect below, so reopening would fire+ // the last step's onEnter (Chat's compare step navigates) before rewinding to the first.+ const [wasOpen, setWasOpen] = useState(open);+ if (open !== wasOpen) {+ setWasOpen(open);+ if (open) setIdx(0);+ }const step = steps[idx] ?? null;const total = steps.length;@@ -57,30 +64,19 @@ export function GuidedTour({return padded(targetRect, pad, vw, vh);}, [step?.target, targetRect, vw, vh]);+ // Cleanup, not a second effect: a step is then also left when the tour unmounts mid-step, as a+ // page hiding its tour on navigation does. Without it onEnter's side effects leak onto the next+ // page, and a persisted one (the sidebar pin) is never put back.useEffect(() => {- if (!open) return;- const prev = activeStepRef.current;- if (prev && prev.id !== step?.id) {- void prev.onExit?.();- }- activeStepRef.current = step;- if (step) {- void step.onEnter?.();- }- }, [open, step?.id]); // run before target lookup effect below-- useEffect(() => {- if (open) return;- const prev = activeStepRef.current;- activeStepRef.current = null;- if (prev) {- void prev.onExit?.();- }- }, [open]);+ if (!open || !step) return;+ void step.onEnter?.();+ return () => {+ void step.onExit?.();+ };+ }, [open, step?.id]); // stays above the target lookup effect belowuseEffect(() => {if (!open) return;- setIdx(0);setTargetRect(null);closeLockRef.current = false;lastRectRef.current = null;diff --git a/studio/frontend/src/features/tour/hooks/use-guided-tour-controller.ts b/studio/frontend/src/features/tour/hooks/use-guided-tour-controller.tsindex 1f7b7d0b77b..d6df2145e33 100644--- a/studio/frontend/src/features/tour/hooks/use-guided-tour-controller.ts+++ b/studio/frontend/src/features/tour/hooks/use-guided-tour-controller.ts@@ -1,7 +1,13 @@// SPDX-License-Identifier: AGPL-3.0-only// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0-import { useCallback, useEffect, useMemo, useState } from "react";+import {+ useCallback,+ useEffect,+ useMemo,+ useState,+ useSyncExternalStore,+} from "react";import type { TourStep } from "../types";export const TOUR_OPEN_EVENT = "omx:tour:open";@@ -10,6 +16,38 @@ export type TourOpenDetail = {id?: string;};+// Tour ids with a live listener. A page can mount its controller behind a gate (Video) or disable+// it while it loads (Train), and the menu must not offer a tour nothing answers.+const listening = new Map<string, number>();+const listeningSubscribers = new Set<() => void>();++function registerTour(id: string): () => void {+ listening.set(id, (listening.get(id) ?? 0) + 1);+ for (const notify of listeningSubscribers) notify();+ return () => {+ const left = (listening.get(id) ?? 1) - 1;+ if (left > 0) listening.set(id, left);+ else listening.delete(id);+ for (const notify of listeningSubscribers) notify();+ };+}++function subscribeToListening(notify: () => void): () => void {+ listeningSubscribers.add(notify);+ return () => {+ listeningSubscribers.delete(notify);+ };+}++/** Whether opening this tour would reach anyone. False for a null id. */+export function useTourAvailable(id: string | null): boolean {+ return useSyncExternalStore(+ subscribeToListening,+ () => (id === null ? false : listening.has(id)),+ () => false,+ );+}+export function useGuidedTourController({id,steps,@@ -38,16 +76,27 @@ export function useGuidedTourController({useEffect(() => {if (!hasRuntime || !enabled) return;+ if (steps.length === 0) return;function onOpen(e: Event) {const ce = e as CustomEvent<TourOpenDetail>;if (ce.detail?.id && ce.detail.id !== id) return;- if (steps.length === 0) return;setOpen(true);}window.addEventListener(TOUR_OPEN_EVENT, onOpen);- return () => window.removeEventListener(TOUR_OPEN_EVENT, onOpen);+ const unregister = registerTour(id);+ return () => {+ window.removeEventListener(TOUR_OPEN_EVENT, onOpen);+ unregister();+ };}, [enabled, hasRuntime, id, steps.length]);+ // Keyed on `enabled` alone, so a page going inactive mid-tour drops the tour rather than+ // silently restarting it at step one on return, while a changing step count leaves it alone.+ useEffect(() => {+ if (!enabled) return;+ return () => setOpen(false);+ }, [enabled]);+const onSkip = useCallback(() => {if (!autoKey) return;localStorage.setItem(autoKey, "skipped");diff --git a/studio/frontend/src/features/tour/index.ts b/studio/frontend/src/features/tour/index.tsindex 89018bfa77f..acf1bda38ea 100644--- a/studio/frontend/src/features/tour/index.ts+++ b/studio/frontend/src/features/tour/index.ts@@ -3,5 +3,10 @@export { GuidedTour } from "./components/guided-tour";export { ReadMore } from "./components/read-more";-export { TOUR_OPEN_EVENT, useGuidedTourController } from "./hooks/use-guided-tour-controller";+export {+ TOUR_OPEN_EVENT,+ useGuidedTourController,+ useTourAvailable,+} from "./hooks/use-guided-tour-controller";+export { TOUR_ROUTES, getTourId } from "./lib/tour-routes";export type { TourStep } from "./types";diff --git a/studio/frontend/src/features/tour/lib/tour-routes.ts b/studio/frontend/src/features/tour/lib/tour-routes.tsnew file mode 100644index 00000000000..aa18b24979e--- /dev/null+++ b/studio/frontend/src/features/tour/lib/tour-routes.ts@@ -0,0 +1,28 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++/**+ * Every page that ships a tour, and the route prefix it answers to. The user menu reads this to+ * decide whether to offer "Guided Tour"; each page passes the same id to useGuidedTourController.+ * Longest prefix first: the recipe editor sits under the Data Recipes route.+ */+export const TOUR_ROUTES: ReadonlyArray<{ prefix: string; id: string }> = [+ { prefix: "/data-recipes/", id: "recipe-editor" },+ { prefix: "/data-recipes", id: "data-recipes" },+ { prefix: "/api-monitor", id: "api-monitor" },+ { prefix: "/projects", id: "projects" },+ { prefix: "/studio", id: "studio" },+ { prefix: "/export", id: "export" },+ { prefix: "/images", id: "images" },+ { prefix: "/video", id: "video" },+ { prefix: "/audio", id: "audio" },+ { prefix: "/chat", id: "chat" },+ { prefix: "/hub", id: "hub" },+];++/** The tour id for a route, or null where that page has no tour. */+export function getTourId(pathname: string): string | null {+ return (+ TOUR_ROUTES.find((route) => pathname.startsWith(route.prefix))?.id ?? null+ );+}diff --git a/studio/frontend/src/features/video/tour/index.ts b/studio/frontend/src/features/video/tour/index.tsnew file mode 100644index 00000000000..5cc046172ab--- /dev/null+++ b/studio/frontend/src/features/video/tour/index.ts@@ -0,0 +1,4 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++export { videoTourSteps } from "./steps";diff --git a/studio/frontend/src/features/video/tour/steps.tsx b/studio/frontend/src/features/video/tour/steps.tsxnew file mode 100644index 00000000000..87e1cc18787--- /dev/null+++ b/studio/frontend/src/features/video/tour/steps.tsx@@ -0,0 +1,40 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import type { TourStep } from "@/features/tour";++export const videoTourSteps: TourStep[] = [+ {+ id: "model",+ target: "video-model",+ title: "Pick a model",+ body: (+ <>+ Video models run locally, so check the size before you download. What+ the model supports decides which controls appear below.+ </>+ ),+ },+ {+ id: "settings",+ target: "video-settings",+ title: "Settings",+ body: (+ <>+ Prompt, resolution, duration in frames, steps, guidance and seed.+ Duration and resolution drive VRAM and time most, so start small.+ </>+ ),+ },+ {+ id: "preview",+ target: "video-preview",+ title: "Results",+ body: (+ <>+ The selected clip plays here and every clip lines up below. Download it,+ or reuse its settings for the next run.+ </>+ ),+ },+];diff --git a/studio/frontend/src/features/video/video-page.tsx b/studio/frontend/src/features/video/video-page.tsxindex 21d235d06f6..a3583c96097 100644--- a/studio/frontend/src/features/video/video-page.tsx+++ b/studio/frontend/src/features/video/video-page.tsx@@ -19,6 +19,8 @@ import { AdvancedDisclosure } from "@/components/advanced-disclosure";import { GalleryItemMenu } from "@/components/gallery-item-menu";import { ImageDropzone } from "@/components/image-dropzone";import { MediaPageLink } from "@/components/media-page-link";+import { GuidedTour, useGuidedTourController } from "@/features/tour";+import { videoTourSteps } from "./tour";import { useSettingsDialogStore } from "@/features/settings/stores/settings-dialog-store";import {applyPin,@@ -985,6 +987,11 @@ function VideoGenerator({// Controlled so the body-portaled model selector force-closes when this page is mounted but off-tab.const [selectorOpen, setSelectorOpen] = useState(false);const [pendingH3Load, setPendingH3Load] = useState<PendingH3Load | null>(null);+ const tour = useGuidedTourController({+ id: "video",+ steps: videoTourSteps,+ enabled: active,+ });const {attach: attachSettingsScroll,onScroll: onSettingsScroll,@@ -3350,6 +3357,8 @@ function VideoGenerator({// The chat-style layout gives this page no outer top inset, so clear the custom titlebar here as chat does.// 34px on win/linux, 0 under macOS's native one.<div className="diffusion-surface flex h-full min-h-0 min-w-0 flex-1 flex-col overflow-hidden pt-[var(--studio-content-top-inset,0px)]">+ {/* Portals to body, and this page stays mounted off-route, so gate it like the composer. */}+ {active && <GuidedTour {...tour.tourProps} />}<AlertDialogopen={active && clearConfirmOpen}onOpenChange={(open) => {@@ -3431,6 +3440,7 @@ function VideoGenerator({{/* min-w-0: without it a long resident model name pushes the Images link off a phone screen. */}<div className="pointer-events-auto flex min-w-0 items-center gap-3"><ModelSelector+ triggerDataTour="video-model"models={videoModels}value={status?.loaded ? status.repo_id ?? undefined : undefined}activeGgufVariant={quant}@@ -3490,7 +3500,10 @@ function VideoGenerator({wide row pan the page sideways on a phone. */}<div className="flex min-h-0 w-full min-w-0 flex-1 flex-col overflow-y-auto overflow-x-hidden pl-2 pr-5 pt-9 sm:pr-8 md:flex-row md:overflow-hidden">{/* Widened by the pl-8 so the controls keep their old width. */}- <div className="flex w-full shrink-0 flex-col border-b border-border/60 pl-8 md:w-[400px] md:overflow-hidden md:border-r md:border-b-0">+ <div+ data-tour="video-settings"+ className="flex w-full shrink-0 flex-col border-b border-border/60 pl-8 md:w-[400px] md:overflow-hidden md:border-r md:border-b-0"+ >{/* pl-0.5 keeps focus rings off the scroll container's edge. */}<divref={attachSettingsScroll}@@ -4034,7 +4047,10 @@ function VideoGenerator({</div></div>- <div className="relative flex min-h-[60dvh] min-w-0 flex-1 flex-col overflow-hidden pl-2 md:min-h-0">+ <div+ data-tour="video-preview"+ className="relative flex min-h-[60dvh] min-w-0 flex-1 flex-col overflow-hidden pl-2 md:min-h-0"+ ><div className="hover-scrollbar relative flex flex-1 items-center justify-center overflow-auto p-6">{selected && selectedSrc ? (<>diff --git a/studio/frontend/tests/guided-tour-coverage.test.ts b/studio/frontend/tests/guided-tour-coverage.test.tsnew file mode 100644index 00000000000..56004a72ea2--- /dev/null+++ b/studio/frontend/tests/guided-tour-coverage.test.ts@@ -0,0 +1,168 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++import assert from "node:assert/strict";+import { readFileSync, readdirSync } from "node:fs";+import test from "node:test";++import { readSrc } from "./helpers/kit.ts";++// A tour breaks silently: a renamed anchor leaves the step spotlighting nothing. These read the+// shipped source so a rename has to update both ends.++const SRC_ROOT = new URL("../src/", import.meta.url);++/** Every .ts/.tsx under src. URLs throughout: a file: URL pathname is "/D:/..." on Windows. */+function sourceFiles(dir: URL): Array<{ path: string; text: string }> {+ const out: Array<{ path: string; text: string }> = [];+ for (const entry of readdirSync(dir, { withFileTypes: true })) {+ if (entry.isDirectory()) {+ out.push(...sourceFiles(new URL(`${entry.name}/`, dir)));+ continue;+ }+ if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".tsx")) continue;+ const file = new URL(entry.name, dir);+ out.push({+ path: `src/${file.href.slice(SRC_ROOT.href.length)}`,+ text: readFileSync(file, "utf8"),+ });+ }+ return out;+}++const files = sourceFiles(SRC_ROOT);+const tourStepFiles = files.filter((file) => file.path.includes("/tour/"));++function matchAll(text: string, pattern: RegExp): string[] {+ return [...text.matchAll(pattern)].map((match) => match[1] as string);+}++/** Anchors reach the DOM either as a literal attribute or through a component's dataTour prop. */+const anchors = new Set<string>();+for (const file of files) {+ for (const value of matchAll(file.text, /data-tour="([\w-]+)"/g)) {+ anchors.add(value);+ }+ for (const value of matchAll(+ file.text,+ /(?:dataTour|triggerDataTour|contentDataTour)="([\w-]+)"/g,+ )) {+ anchors.add(value);+ }+}++const targets = new Set<string>();+for (const file of tourStepFiles) {+ for (const target of matchAll(file.text, /target: "([\w-]+)"/g)) {+ targets.add(target);+ }+}++test("every tour step points at an anchor that exists", () => {+ for (const file of tourStepFiles) {+ for (const target of matchAll(file.text, /target: "([\w-]+)"/g)) {+ assert.ok(+ anchors.has(target),+ `${file.path} targets "${target}", which no data-tour attribute or dataTour prop provides`,+ );+ }+ }+});++// The other direction: a dropped step must not leave a stale anchor that reads like a live one.+test("every anchor is used by a step", () => {+ for (const anchor of anchors) {+ assert.ok(+ targets.has(anchor),+ `"${anchor}" is marked as a tour anchor but no step targets it; drop the attribute or the step`,+ );+ }+});++// A prop-carried anchor fails silently if the component stops forwarding it: the source still+// spells the anchor out, so the test above stays green.+test("a prop-carried anchor is forwarded to the DOM", () => {+ const all = files.map((file) => file.text).join("\n");+ for (const prop of ["dataTour", "triggerDataTour", "contentDataTour"]) {+ if (!new RegExp(`${prop}="[\\w-]+"`).test(all)) continue;+ assert.match(+ all,+ // Rendered as the attribute itself, or handed to another prop that is.+ new RegExp(`(?:data-tour|dataTour)=\\{${prop}\\}`),+ `${prop} is used as a tour anchor but nothing forwards it to data-tour`,+ );+ }+});++test("every routed tour is mounted by its page", () => {+ const routes = readSrc("features/tour/lib/tour-routes.ts");+ const routedIds = matchAll(routes, /id: "([\w-]+)"/g);+ assert.ok(routedIds.length > 0);++ const mountedIds = new Set<string>();+ for (const file of files) {+ for (const call of file.text.matchAll(+ /useGuidedTourController\(\{[\s\S]{0,240}?\}\)/g,+ )) {+ const id = /id: "([\w-]+)"/.exec(call[0])?.[1];+ if (id) mountedIds.add(id);+ }+ }++ for (const id of routedIds) {+ assert.ok(+ mountedIds.has(id),+ `the "${id}" tour is offered in the user menu but no page passes that id to useGuidedTourController`,+ );+ }+});++// Mounted by RootLayout, not by their route, so they outlive a navigation away.+const PERSISTENT_PAGES = [+ "features/chat/chat-page.tsx",+ "features/images/images-page.tsx",+ "features/video/video-page.tsx",+ "features/audio/audio-page.tsx",+];++test("a persistently mounted page hides its tour when its route goes", () => {+ for (const page of PERSISTENT_PAGES) {+ assert.match(+ readSrc(page),+ /\{active && <GuidedTour /,+ `${page} renders GuidedTour unconditionally; it portals to body, so the tour would stay modal over the next page`,+ );+ }+});++test("a step is left when the tour unmounts, not only when it advances", () => {+ assert.match(+ readSrc("features/tour/components/guided-tour.tsx"),+ /onEnter\?\.\(\);[\s\S]{0,240}?return \(\) => \{[\s\S]{0,160}?onExit\?\.\(\);/,+ "onEnter must be undone by the effect's cleanup; a separate close-only effect never runs when a page unmounts the tour mid-step, so onEnter's side effects leak onto the next page",+ );+});++test("the menu offers a tour only when one is listening", () => {+ assert.match(+ readSrc("components/app-sidebar.tsx"),+ /useTourAvailable\(/,+ "the Guided Tour entry must consult useTourAvailable; route alone offers it on pages that mount their tour behind a capability gate, where clicking it does nothing",+ );+ assert.match(+ readSrc("features/tour/hooks/use-guided-tour-controller.ts"),+ /registerTour\(id\)/,+ "the controller must register itself while it listens, or useTourAvailable cannot answer",+ );+});++const EM_DASH = "\u2014";++test("tour copy avoids em dashes", () => {+ for (const file of tourStepFiles) {+ assert.ok(+ !file.text.includes(EM_DASH),+ `${file.path} contains an em dash; tour copy uses plain sentences`,+ );+ }+});