From 7a47cbe9adbf3bf4eb6294f0e7b6401679096044 Mon Sep 17 00:00:00 2001
From: Mark Street <streetster@gmail.com>
Date: Sun, 31 May 2026 15:52:01 +0100
Subject: [PATCH 1/7] Add scratch editor tour

---
 frontend/package.json                         |   1 +
 frontend/src/app/globals.scss                 |  92 +++
 frontend/src/app/layout.tsx                   |   1 +
 frontend/src/components/Diff/Diff.tsx         |  10 +-
 frontend/src/components/Diff/ToggleButton.tsx |   3 +
 frontend/src/components/Editor/CodeMirror.tsx |   3 +
 frontend/src/components/Scratch/Scratch.tsx   |  32 +-
 .../src/components/Scratch/ScratchToolbar.tsx |  70 ++-
 .../src/components/Scratch/ScratchTour.tsx    | 561 ++++++++++++++++++
 .../components/Scratch/panels/AboutPanel.tsx  |   2 +-
 .../Scratch/panels/DecompilePanel.tsx         |   2 +-
 .../components/Scratch/panels/FamilyPanel.tsx |   5 +-
 .../Scratch/panels/ProblemPanel.tsx           |   5 +-
 frontend/src/components/Tabs.tsx              |   5 +
 .../src/components/compiler/CompilerOpts.tsx  |  34 +-
 frontend/yarn.lock                            |   5 +
 16 files changed, 804 insertions(+), 27 deletions(-)
 create mode 100644 frontend/src/components/Scratch/ScratchTour.tsx

diff --git a/frontend/package.json b/frontend/package.json
index 08198b3c6..89d7b1202 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -33,6 +33,7 @@
         "@sentry/nextjs": "^10.52.0",
         "allotment": "^1.20.3",
         "ansi-to-react": "^6.1.6",
+        "boarding.js": "^3.7.3",
         "clsx": "^2.1.1",
         "codemirror": "^6.0.1",
         "dotenv": "^16.4.5",
diff --git a/frontend/src/app/globals.scss b/frontend/src/app/globals.scss
index e9a4a6cbe..7aa665b37 100644
--- a/frontend/src/app/globals.scss
+++ b/frontend/src/app/globals.scss
@@ -85,3 +85,95 @@ body.no-scroll {
         height: 100svh;
     }
 }
+
+#boarding-popover-item.scratch-tour-popover {
+    width: min(22rem, calc(100vw - 2rem));
+    border: 1px solid var(--g600);
+    border-radius: 8px;
+    background: var(--g200);
+    box-shadow: 0 18px 48px rgb(0 0 0 / 35%);
+    color: var(--g1700);
+
+    .boarding-popover-title {
+        margin-bottom: 0.45rem;
+        font-weight: 700;
+        font-size: 0.95rem;
+        line-height: 1.2;
+    }
+
+    .boarding-popover-description {
+        color: var(--g1200);
+        font-size: 0.875rem;
+        line-height: 1.35;
+
+        strong {
+            color: var(--g1700);
+            font-weight: 700;
+        }
+
+        a {
+            color: var(--link);
+            text-decoration: underline;
+        }
+
+        a:hover {
+            color: var(--g1700);
+        }
+    }
+
+    .boarding-popover-footer {
+        display: flex !important;
+        align-items: center;
+        justify-content: space-between;
+        gap: 0.75rem;
+        margin-top: 1rem;
+    }
+
+    .boarding-navigation-btns {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        margin-left: auto;
+    }
+
+    button {
+        display: inline-flex;
+        min-height: 2rem;
+        align-items: center;
+        justify-content: center;
+        border: 1px solid var(--g700);
+        border-radius: 6px;
+        background: var(--g400);
+        padding: 0.35rem 0.65rem;
+        color: var(--g1700);
+        font-weight: 600;
+        font-size: 0.8125rem;
+        line-height: 1;
+        white-space: nowrap;
+        cursor: pointer;
+    }
+
+    button:hover {
+        background: var(--a600);
+    }
+
+    .boarding-next-btn {
+        border-color: var(--a900);
+        background: var(--a400);
+        color: white;
+    }
+
+    .boarding-next-btn:hover {
+        background: var(--a600);
+    }
+
+    .boarding-disabled {
+        opacity: 0.45;
+        cursor: default;
+        pointer-events: none;
+    }
+
+    .boarding-popover-tip {
+        border-color: var(--g200);
+    }
+}
diff --git a/frontend/src/app/layout.tsx b/frontend/src/app/layout.tsx
index 800b1f540..808bb503d 100644
--- a/frontend/src/app/layout.tsx
+++ b/frontend/src/app/layout.tsx
@@ -1,6 +1,7 @@
 import ThemeProvider from "./ThemeProvider";
 
 import "allotment/dist/style.css";
+import "boarding.js/styles/main.css";
 import "./globals.scss";
 
 export const metadata = {
diff --git a/frontend/src/components/Diff/Diff.tsx b/frontend/src/components/Diff/Diff.tsx
index 6ac30980c..b6c3c607e 100644
--- a/frontend/src/components/Diff/Diff.tsx
+++ b/frontend/src/components/Diff/Diff.tsx
@@ -481,7 +481,11 @@ export default function Diff({
             {columnCount === 3 && <DragBar pos={bar2Px} onChange={setBar2Px} />}
             <div className={styles.headers}>
                 {columns.map((col) => (
-                    <div key={col} className={styles.header}>
+                    <div
+                        key={col}
+                        className={styles.header}
+                        data-tour={`scratch-diff-column-${col}`}
+                    >
                         {COLUMN_LABELS[col]}
                         <CopyButton
                             title="Copy content"
@@ -515,6 +519,7 @@ export default function Diff({
                                     setEnabled={(enabled) =>
                                         setColumn("base", enabled)
                                     }
+                                    dataTour="scratch-diff-toggle-target"
                                 />
                                 <ToggleButton
                                     label="C"
@@ -523,12 +528,14 @@ export default function Diff({
                                     setEnabled={(enabled) =>
                                         setColumn("current", enabled)
                                     }
+                                    dataTour="scratch-diff-toggle-current"
                                 />
                                 <ToggleButton
                                     label="3"
                                     title="3-way diff"
                                     enabled={threeWayDiffEnabled}
                                     setEnabled={handleSetThreeWayDiff}
+                                    dataTour="scratch-diff-toggle-three-way"
                                 />
                                 <ToggleButton
                                     label={<FoldIcon size={16} />}
@@ -538,6 +545,7 @@ export default function Diff({
                                     padding="px-1 py-1"
                                     enabled={compressionEnabled}
                                     setEnabled={setCompressionEnabled}
+                                    dataTour="scratch-diff-toggle-compression"
                                 />
                             </>
                         )}
diff --git a/frontend/src/components/Diff/ToggleButton.tsx b/frontend/src/components/Diff/ToggleButton.tsx
index 803f870aa..df87a9dba 100644
--- a/frontend/src/components/Diff/ToggleButton.tsx
+++ b/frontend/src/components/Diff/ToggleButton.tsx
@@ -9,6 +9,7 @@ type ToggleButtonProps = {
     disabledLabel?: string;
     enabledLabel?: string;
     padding?: string;
+    dataTour?: string;
 };
 
 export default function ToggleButton({
@@ -19,6 +20,7 @@ export default function ToggleButton({
     disabledLabel = "Show ",
     enabledLabel = "Hide ",
     padding = "px-2 py-1",
+    dataTour,
 }: ToggleButtonProps) {
     return (
         <button
@@ -31,6 +33,7 @@ export default function ToggleButton({
                     ? `${enabled ? enabledLabel : disabledLabel}${title}`
                     : undefined
             }
+            data-tour={dataTour}
             className={clsx(
                 padding,
                 "text-md",
diff --git a/frontend/src/components/Editor/CodeMirror.tsx b/frontend/src/components/Editor/CodeMirror.tsx
index 03e41dd7b..6dcfaafa0 100644
--- a/frontend/src/components/Editor/CodeMirror.tsx
+++ b/frontend/src/components/Editor/CodeMirror.tsx
@@ -58,6 +58,7 @@ export interface Props {
     viewRef?: RefObject<EditorView | null>;
     extensions: Extension; // const
     placeholder?: string;
+    dataTour?: string;
 }
 
 export default function CodeMirror({
@@ -70,6 +71,7 @@ export default function CodeMirror({
     viewRef: viewRefProp,
     extensions,
     placeholder: placeholderText,
+    dataTour,
 }: Props) {
     const { ref: el, width } = useSize<HTMLDivElement>();
 
@@ -204,6 +206,7 @@ export default function CodeMirror({
             ref={el}
             onMouseMove={debouncedOnMouseMove}
             className={clsx(styles.container, className)}
+            data-tour={dataTour}
             style={
                 {
                     "--cm-font-size": `${fontSize}px`,
diff --git a/frontend/src/components/Scratch/Scratch.tsx b/frontend/src/components/Scratch/Scratch.tsx
index fa4768fbb..d25c39c56 100644
--- a/frontend/src/components/Scratch/Scratch.tsx
+++ b/frontend/src/components/Scratch/Scratch.tsx
@@ -52,6 +52,7 @@ import styles from "./Scratch.module.scss";
 import ScratchMatchBanner from "./ScratchMatchBanner";
 import ScratchProgressBar from "./ScratchProgressBar";
 import ScratchToolbar from "./ScratchToolbar";
+import ScratchTour from "./ScratchTour";
 import { StreamLanguage } from "@codemirror/language";
 import { pascal } from "@/lib/codemirror/pascal";
 import ObjdiffPanel from "../Diff/ObjdiffPanel";
@@ -322,6 +323,7 @@ export default function Scratch({
                         tabKey={id}
                         label="About"
                         className={styles.about}
+                        dataTour="scratch-tab-about"
                     >
                         {() => (
                             <AboutPanel
@@ -339,6 +341,7 @@ export default function Scratch({
                         key={id}
                         tabKey={id}
                         label="Source code"
+                        dataTour="scratch-tab-source"
                         onSelect={() => {
                             sourceEditor.current?.focus?.();
                             saveContext();
@@ -355,6 +358,7 @@ export default function Scratch({
                             onSelectedLineChange={setSelectedSourceLine}
                             extensions={cmExtensionsSource}
                             placeholder="Write the code for the function you are matching here."
+                            dataTour="scratch-source-editor"
                         />
                     </Tab>
                 );
@@ -365,6 +369,7 @@ export default function Scratch({
                         tabKey={id}
                         label="Context"
                         className={styles.context}
+                        dataTour="scratch-tab-context"
                         onSelect={() => {
                             contextEditor.current?.focus?.();
                             saveSource();
@@ -380,6 +385,7 @@ export default function Scratch({
                             }}
                             extensions={cmExtensionsContext}
                             placeholder="Add your typedefs, structs, and declarations here."
+                            dataTour="scratch-context-editor"
                         />
                     </Tab>
                 );
@@ -390,6 +396,7 @@ export default function Scratch({
                         tabKey={id}
                         label="Options"
                         className={styles.compilerOptsTab}
+                        dataTour="scratch-tab-options"
                     >
                         {() => (
                             <ScrollRestorer
@@ -418,6 +425,7 @@ export default function Scratch({
                     <Tab
                         key={id}
                         tabKey={id}
+                        dataTour="scratch-tab-compilation"
                         label={
                             <>
                                 Compilation
@@ -460,6 +468,7 @@ export default function Scratch({
                         tabKey={id}
                         label="objdiff"
                         className={styles.diffTab}
+                        dataTour="scratch-tab-objdiff"
                     >
                         {compilation && (
                             <ObjdiffPanel
@@ -476,6 +485,7 @@ export default function Scratch({
                         <Tab
                             key={id}
                             tabKey={id}
+                            dataTour="scratch-tab-decompilation"
                             label={
                                 <>
                                     Decompilation
@@ -493,14 +503,24 @@ export default function Scratch({
                 );
             case TabId.FAMILY:
                 return (
-                    <Tab key={id} tabKey={id} label="Family">
+                    <Tab
+                        key={id}
+                        tabKey={id}
+                        label="Family"
+                        dataTour="scratch-tab-family"
+                    >
                         {() => <FamilyPanel scratch={scratch} />}
                     </Tab>
                 );
             case TabId.PROBLEMS:
                 return (
                     compilation?.compiler_output && (
-                        <Tab key={id} tabKey={id} label="Problems">
+                        <Tab
+                            key={id}
+                            tabKey={id}
+                            label="Problems"
+                            dataTour="scratch-tab-problems"
+                        >
                             {() => (
                                 <ProblemPanel
                                     text={compilation.compiler_output}
@@ -555,7 +575,12 @@ export default function Scratch({
     );
 
     return (
-        <div ref={container.ref} className={styles.container}>
+        <div
+            ref={container.ref}
+            className={styles.container}
+            data-tour="scratch-view"
+        >
+            <ScratchTour />
             <ErrorBoundary>
                 <ScratchMatchBanner scratch={scratch} />
             </ErrorBoundary>
@@ -587,6 +612,7 @@ export default function Scratch({
                 )}
             </ErrorBoundary>
             {offlineOverlay}
+            <span className="sr-only" data-tour="scratch-tour-help" />
         </div>
     );
 }
diff --git a/frontend/src/components/Scratch/ScratchToolbar.tsx b/frontend/src/components/Scratch/ScratchToolbar.tsx
index c5f9050e7..59aebbab9 100644
--- a/frontend/src/components/Scratch/ScratchToolbar.tsx
+++ b/frontend/src/components/Scratch/ScratchToolbar.tsx
@@ -13,6 +13,7 @@ import {
     DownloadIcon,
     FileIcon,
     IterationsIcon,
+    MilestoneIcon,
     RepoForkedIcon,
     SyncIcon,
     TrashIcon,
@@ -50,6 +51,10 @@ function exportScratchZip(scratch: api.Scratch) {
     a.click();
 }
 
+function startScratchTour() {
+    window.dispatchEvent(new CustomEvent("scratch-tour:start"));
+}
+
 function EditTimeAgo({ date }: { date: string }) {
     const isActive = Date.now() - new Date(date).getTime() < ACTIVE_MS;
 
@@ -157,12 +162,14 @@ function ActionButton({
     title,
     icon,
     text,
+    dataTour,
 }: {
     onClick: (event?: any) => void;
     disabled?: boolean;
     title?: string;
     icon: JSX.Element;
     text: string;
+    dataTour?: string;
 }) {
     return (
         <button
@@ -170,6 +177,7 @@ function ActionButton({
             disabled={disabled}
             title={title}
             aria-label={text}
+            data-tour={dataTour}
         >
             {icon}
             <span className="hidden md:inline">{text}</span>
@@ -185,6 +193,7 @@ function Actions({
     saveCallback,
     deleteScratch,
     setDecompilationTabEnabled,
+    tourTargetsEnabled = true,
 }: Props) {
     const userIsYou = api.useUserIsYou();
     const forkScratch = api.useForkScratchAndGo(scratch);
@@ -245,6 +254,11 @@ function Actions({
                         title={isSaved ? "No unsaved changes" : fuzzyShortcut}
                         text={isSaved ? "Saved" : "Save"}
                         icon={isSaved ? <CheckIcon /> : <UploadIcon />}
+                        dataTour={
+                            tourTargetsEnabled
+                                ? "scratch-action-save"
+                                : undefined
+                        }
                     />
                 </li>
             )}
@@ -255,6 +269,9 @@ function Actions({
                     title={!canSave ? fuzzyShortcut : undefined}
                     text={!canSave ? "Fork to save" : "Fork"}
                     icon={<RepoForkedIcon />}
+                    dataTour={
+                        tourTargetsEnabled ? "scratch-action-fork" : undefined
+                    }
                 />
             </li>
             {((scratch.owner && userIsYou(scratch.owner)) || isAdmin) && (
@@ -272,6 +289,11 @@ function Actions({
                         }}
                         text="Delete"
                         icon={<TrashIcon />}
+                        dataTour={
+                            tourTargetsEnabled
+                                ? "scratch-action-delete"
+                                : undefined
+                        }
                     />
                 </li>
             )}
@@ -280,6 +302,9 @@ function Actions({
                     onClick={() => exportScratchZip(scratch)}
                     text="Export"
                     icon={<DownloadIcon />}
+                    dataTour={
+                        tourTargetsEnabled ? "scratch-action-export" : undefined
+                    }
                 />
             </li>
             <li>
@@ -289,6 +314,11 @@ function Actions({
                     disabled={isCompiling}
                     text="Compile"
                     icon={<SyncIcon />}
+                    dataTour={
+                        tourTargetsEnabled
+                            ? "scratch-action-compile"
+                            : undefined
+                    }
                 />
             </li>
             {platform?.has_decompiler && (
@@ -297,9 +327,24 @@ function Actions({
                         onClick={() => setDecompilationTabEnabled(true)}
                         icon={<IterationsIcon />}
                         text="Decompile"
+                        dataTour={
+                            tourTargetsEnabled
+                                ? "scratch-action-decompile"
+                                : undefined
+                        }
                     />
                 </li>
             )}
+            <li>
+                <ActionButton
+                    onClick={startScratchTour}
+                    icon={<MilestoneIcon />}
+                    text="Tour"
+                    dataTour={
+                        tourTargetsEnabled ? "scratch-action-tour" : undefined
+                    }
+                />
+            </li>
         </ul>
     );
 }
@@ -329,7 +374,10 @@ function useActionsLocation(): [ActionsLocation, FC<Props>] {
                 aria-hidden={location !== ActionsLocation.IN_NAV}
                 className={styles.inNavActionsContainer}
             >
-                <Actions {...props} />
+                <Actions
+                    {...props}
+                    tourTargetsEnabled={location === ActionsLocation.IN_NAV}
+                />
             </div>
         ),
     ];
@@ -343,6 +391,7 @@ export type Props = {
     saveCallback: () => void;
     deleteScratch: () => Promise<void>;
     setDecompilationTabEnabled: (enabled: boolean) => void;
+    tourTargetsEnabled?: boolean;
 };
 
 export default function ScratchToolbar(props: Props) {
@@ -354,7 +403,7 @@ export default function ScratchToolbar(props: Props) {
     return (
         <>
             <Nav>
-                <div className={styles.container}>
+                <div className={styles.container} data-tour="scratch-toolbar">
                     <Breadcrumbs
                         className={styles.breadcrumbs}
                         pages={[
@@ -381,13 +430,16 @@ export default function ScratchToolbar(props: Props) {
                                             platform={scratch.platform}
                                             size={20}
                                         />
-                                        <ScratchName
-                                            name={scratch.name}
-                                            onChange={
-                                                userIsYou(scratch.owner) &&
-                                                ((name) => setScratch({ name }))
-                                            }
-                                        />
+                                        <span data-tour="scratch-name">
+                                            <ScratchName
+                                                name={scratch.name}
+                                                onChange={
+                                                    userIsYou(scratch.owner) &&
+                                                    ((name) =>
+                                                        setScratch({ name }))
+                                                }
+                                            />
+                                        </span>
                                         <span className="hidden md:inline">
                                             <EditTimeAgo
                                                 date={scratch.last_updated}
diff --git a/frontend/src/components/Scratch/ScratchTour.tsx b/frontend/src/components/Scratch/ScratchTour.tsx
new file mode 100644
index 000000000..67ef8a483
--- /dev/null
+++ b/frontend/src/components/Scratch/ScratchTour.tsx
@@ -0,0 +1,561 @@
+"use client";
+
+import { useEffect } from "react";
+
+import { useSearchParams } from "next/navigation";
+import { Boarding, type BoardingSteps } from "boarding.js";
+
+type TourStep = BoardingSteps[number];
+
+const SELECTOR = {
+    toolbar: '[data-tour="scratch-toolbar"]',
+    scratchView: '[data-tour="scratch-view"]',
+    tourHelp: '[data-tour="scratch-tour-help"]',
+    compileButton: '[data-tour="scratch-action-compile"]',
+    saveButton: '[data-tour="scratch-action-save"]',
+    forkButton: '[data-tour="scratch-action-fork"]',
+    decompileButton: '[data-tour="scratch-action-decompile"]',
+    exportButton: '[data-tour="scratch-action-export"]',
+    aboutTab: '[data-tour="scratch-tab-about"]',
+    aboutPanel: '[data-tour="scratch-about-panel"]',
+    familyTab: '[data-tour="scratch-tab-family"]',
+    familyPanel: '[data-tour="scratch-family-panel"]',
+    sourceTab: '[data-tour="scratch-tab-source"]',
+    sourcePanel: '[data-tour="scratch-tab-source-panel"]',
+    contextTab: '[data-tour="scratch-tab-context"]',
+    contextPanel: '[data-tour="scratch-tab-context-panel"]',
+    optionsTab: '[data-tour="scratch-tab-options"]',
+    optionsPanel: '[data-tour="scratch-tab-options-panel"]',
+    optionsCompiler: '[data-tour="scratch-options-compiler"]',
+    optionsDiff: '[data-tour="scratch-options-diff"]',
+    optionsOther: '[data-tour="scratch-options-other"]',
+    compilationTab: '[data-tour="scratch-tab-compilation"]',
+    compilationPanel: '[data-tour="scratch-tab-compilation-panel"]',
+    targetColumn: '[data-tour="scratch-diff-column-base"]',
+    currentColumn: '[data-tour="scratch-diff-column-current"]',
+    thirdColumn: '[data-tour="scratch-diff-column-previous"]',
+    targetToggle: '[data-tour="scratch-diff-toggle-target"]',
+    currentToggle: '[data-tour="scratch-diff-toggle-current"]',
+    threeWayToggle: '[data-tour="scratch-diff-toggle-three-way"]',
+    compressionToggle: '[data-tour="scratch-diff-toggle-compression"]',
+    objdiffTab: '[data-tour="scratch-tab-objdiff"]',
+    objdiffPanel: '[data-tour="scratch-tab-objdiff-panel"]',
+    problemsTab: '[data-tour="scratch-tab-problems"]',
+    problemsPanel: '[data-tour="scratch-problems-panel"]',
+    decompileTab: '[data-tour="scratch-tab-decompilation"]',
+    decompilePanel: '[data-tour="scratch-decompile-panel"]',
+};
+
+function element(selector: string) {
+    return document.querySelector<HTMLElement>(selector);
+}
+
+function elementExists(selector: string) {
+    return !!element(selector);
+}
+
+function isElementVisible(selector: string) {
+    const el = element(selector);
+    if (!el) return false;
+
+    const rect = el.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+}
+
+function afterReactPaint(callback: () => void) {
+    requestAnimationFrame(() => {
+        requestAnimationFrame(callback);
+    });
+}
+
+function makeStep(
+    selector: string,
+    title: string,
+    description: string,
+    preferredSide: TourStep["popover"]["preferredSide"] = "bottom",
+): TourStep {
+    return {
+        element: selector,
+        popover: {
+            title,
+            description,
+            preferredSide,
+        },
+    };
+}
+
+function makeClickToContinueStep({
+    boarding,
+    selector,
+    waitForSelector,
+    isComplete,
+    title,
+    description,
+    preferredSide = "bottom",
+}: {
+    boarding: Boarding;
+    selector: string;
+    waitForSelector?: string;
+    isComplete?: () => boolean;
+    title: string;
+    description: string;
+    preferredSide?: TourStep["popover"]["preferredSide"];
+}): TourStep {
+    let removeClickListener: (() => void) | undefined;
+    let clicked = false;
+    const isStepComplete = () =>
+        clicked ||
+        isComplete?.() ||
+        (waitForSelector ? isElementVisible(waitForSelector) : false);
+
+    return {
+        element: selector,
+        strictClickHandling: true,
+        onHighlighted: () => {
+            const onClick = (event: MouseEvent) => {
+                const target = event.target;
+                if (!(target instanceof Element)) return;
+                if (!target.closest(selector)) return;
+
+                clicked = true;
+                afterReactPaint(() => {
+                    boarding.clearMovePrevented();
+                    boarding.next();
+                });
+            };
+
+            document.addEventListener("click", onClick, { capture: true });
+            removeClickListener = () => {
+                document.removeEventListener("click", onClick, {
+                    capture: true,
+                });
+            };
+        },
+        onDeselected: () => {
+            removeClickListener?.();
+            removeClickListener = undefined;
+        },
+        onNext: () => {
+            if (isStepComplete()) return;
+
+            boarding.preventMove();
+        },
+        popover: {
+            title,
+            description,
+            preferredSide,
+            showButtons: ["close", "previous"],
+        },
+    };
+}
+
+function isToggleEnabled(selector: string) {
+    return element(selector)?.getAttribute("aria-pressed") === "true";
+}
+
+function resetBoarding(boarding: Boarding) {
+    if (!boarding.isActivated && !boarding.hasHighlightedElement()) return;
+
+    try {
+        boarding.reset(true, "cancel");
+    } catch (error) {
+        if (
+            !(error instanceof Error) ||
+            error.message !== "No SVG found to unmount"
+        ) {
+            throw error;
+        }
+    }
+}
+
+function addIfPresent(steps: TourStep[], step: TourStep) {
+    if (elementExists(step.element as string)) {
+        steps.push(step);
+    }
+}
+
+function addTabSection({
+    steps,
+    boarding,
+    tabSelector,
+    panelSelector,
+    tabTitle,
+    tabDescription,
+    panelTitle,
+    panelDescription,
+    panelPreferredSide = "right",
+}: {
+    steps: TourStep[];
+    boarding: Boarding;
+    tabSelector: string;
+    panelSelector: string;
+    tabTitle: string;
+    tabDescription: string;
+    panelTitle: string;
+    panelDescription: string;
+    panelPreferredSide?: TourStep["popover"]["preferredSide"];
+}) {
+    if (!elementExists(tabSelector)) return;
+
+    steps.push(
+        makeClickToContinueStep({
+            boarding,
+            selector: tabSelector,
+            waitForSelector: panelSelector,
+            title: tabTitle,
+            description: tabDescription,
+        }),
+    );
+
+    steps.push(
+        makeStep(
+            panelSelector,
+            panelTitle,
+            panelDescription,
+            panelPreferredSide,
+        ),
+    );
+}
+
+function buildTourSteps(boarding: Boarding): TourStep[] {
+    const steps: TourStep[] = [];
+
+    addIfPresent(
+        steps,
+        makeStep(
+            SELECTOR.scratchView,
+            "Scratch tour",
+            "This tour highlights the main parts of a scratch. Use <strong>Next</strong> and <strong>Back</strong> to move through it. When a step says <strong>Click</strong> a tab or button, the tour will wait for you to do that before continuing.",
+        ),
+    );
+
+    addIfPresent(
+        steps,
+        makeStep(
+            SELECTOR.toolbar,
+            "Scratch overview",
+            "A scratch is a shareable workspace for matching a function. If you own the scratch you can rename it by clicking on its name and making your changes.",
+        ),
+    );
+
+    addIfPresent(
+        steps,
+        makeStep(
+            SELECTOR.saveButton,
+            "Save",
+            "Hitting Save will save your changes.",
+        ),
+    );
+    addIfPresent(
+        steps,
+        makeStep(
+            SELECTOR.forkButton,
+            "Fork",
+            "Forking a scratch creates your own editable copy, this is how you can save your changes.",
+        ),
+    );
+    addIfPresent(
+        steps,
+        makeStep(
+            SELECTOR.compileButton,
+            "Compile",
+            "Clicking Compile will send your scratch to the backend to be compiled and diffed against the target assembly.",
+        ),
+    );
+    addIfPresent(
+        steps,
+        makeStep(
+            SELECTOR.decompileButton,
+            "Decompile",
+            "When the platform supports it, Decompile can generate a starting point from the target assembly.",
+        ),
+    );
+    addIfPresent(
+        steps,
+        makeStep(
+            SELECTOR.exportButton,
+            "Export",
+            "The Export button creates & downloads a zip of the current scratch, allowing you to inspect them locally.",
+        ),
+    );
+
+    addTabSection({
+        steps,
+        boarding,
+        tabSelector: SELECTOR.aboutTab,
+        panelSelector: SELECTOR.aboutPanel,
+        tabTitle: "About tab",
+        tabDescription:
+            "Click <strong>About</strong> to switch to the About tab where you will find the scratch metadata.",
+        panelTitle: "About",
+        panelDescription:
+            "The About tab shows the score, owner, platform, preset, timestamps, parent scratch, and any notes attached to the scratch.",
+    });
+
+    addTabSection({
+        steps,
+        boarding,
+        tabSelector: SELECTOR.familyTab,
+        panelSelector: SELECTOR.familyPanel,
+        tabTitle: "Family tab",
+        tabDescription:
+            "Click <strong>Family</strong> to switch to the Family tab to see related forks.",
+        panelTitle: "Scratch family",
+        panelDescription:
+            "Forks let people collaborate on the same target function. The family tab helps find related work and improvements.",
+    });
+
+    addTabSection({
+        steps,
+        boarding,
+        tabSelector: SELECTOR.sourceTab,
+        panelSelector: SELECTOR.sourcePanel,
+        tabTitle: "Source code tab",
+        tabDescription:
+            "Click <strong>Source code</strong> to return to the main editor.",
+        panelTitle: "Source code",
+        panelDescription:
+            "Most of the matching loop happens here: edit code, compile, inspect the diff, and repeat.",
+    });
+
+    addTabSection({
+        steps,
+        boarding,
+        tabSelector: SELECTOR.contextTab,
+        panelSelector: SELECTOR.contextPanel,
+        tabTitle: "Context tab",
+        tabDescription:
+            "Click <strong>Context</strong> to see supporting declarations.",
+        panelTitle: "Context",
+        panelDescription:
+            "Use this space for shared typedefs, symbols, function definitions, etc., that are used by the function you are trying to match.",
+    });
+
+    addTabSection({
+        steps,
+        boarding,
+        tabSelector: SELECTOR.optionsTab,
+        panelSelector: SELECTOR.optionsPanel,
+        tabTitle: "Options tab",
+        tabDescription:
+            "Click <strong>Options</strong> to open compiler and diff settings.",
+        panelTitle: "Options",
+        panelDescription:
+            "Options control how your source is compiled and compared. Most scratches will have compiler flags set via preset.",
+    });
+    steps.push(
+        makeStep(
+            SELECTOR.optionsCompiler,
+            "Compiler options",
+            "Compiler options choose the compiler and flags used to build your source.",
+        ),
+    );
+    steps.push(
+        makeStep(
+            SELECTOR.optionsDiff,
+            "Diff options",
+            "Diff options control how the generated object is compared against the target.",
+        ),
+    );
+    steps.push(
+        makeStep(
+            SELECTOR.optionsOther,
+            "Other options",
+            "Match override lets an owner mark a scratch as effectively matching even when naming or symbol details leave a tiny mismatch.",
+        ),
+    );
+
+    addTabSection({
+        steps,
+        boarding,
+        tabSelector: SELECTOR.compilationTab,
+        panelSelector: SELECTOR.compilationPanel,
+        tabTitle: "Compilation tab",
+        tabDescription:
+            "Click <strong>Compilation</strong> to inspect the current diff.",
+        panelTitle: "Compilation",
+        panelDescription:
+            "The Compilation panel shows the current assembly diff and compiler output. A score of 0 means the generated output matches the target.",
+        panelPreferredSide: "left",
+    });
+    addIfPresent(
+        steps,
+        makeStep(
+            SELECTOR.targetColumn,
+            "Target column",
+            "Target shows the assembly you are trying to match.",
+        ),
+    );
+    addIfPresent(
+        steps,
+        makeStep(
+            SELECTOR.currentColumn,
+            "Current column",
+            "Current show what the result of your compiled source code.",
+        ),
+    );
+    addIfPresent(
+        steps,
+        makeStep(
+            SELECTOR.targetToggle,
+            "Column toggles",
+            "The T and C buttons hide or show the Target and Current columns when you need more room.",
+        ),
+    );
+
+    if (elementExists(SELECTOR.threeWayToggle)) {
+        steps.push(
+            makeClickToContinueStep({
+                boarding,
+                selector: SELECTOR.threeWayToggle,
+                isComplete: () => isToggleEnabled(SELECTOR.threeWayToggle),
+                waitForSelector: SELECTOR.thirdColumn,
+                title: "3-way diff",
+                description:
+                    "Click <strong>3</strong> to add a third column comparing against your saved version or previous compile, depending on your editor setting.",
+            }),
+        );
+        steps.push(
+            makeStep(
+                SELECTOR.thirdColumn,
+                "Third diff column",
+                "This extra column gives you another baseline while you compare changes.",
+            ),
+        );
+        steps.push({
+            ...makeClickToContinueStep({
+                boarding,
+                selector: SELECTOR.threeWayToggle,
+                isComplete: () =>
+                    !isToggleEnabled(SELECTOR.threeWayToggle) &&
+                    !isElementVisible(SELECTOR.thirdColumn),
+                title: "Turn 3-way off",
+                description:
+                    "Click <strong>3 again</strong> to return to the normal two-column diff.",
+            }),
+        });
+    }
+
+    if (elementExists(SELECTOR.compressionToggle)) {
+        steps.push(
+            makeStep(
+                SELECTOR.compressionToggle,
+                "Compress diff",
+                "The fold button collapses long unchanged stretches so you can focus on the differences. You can toggle it whenever the full diff has too much noise.",
+            ),
+        );
+    }
+
+    addTabSection({
+        steps,
+        boarding,
+        tabSelector: SELECTOR.objdiffTab,
+        panelSelector: SELECTOR.objdiffPanel,
+        tabTitle: "objdiff tab",
+        tabDescription:
+            "Click <strong>objdiff</strong> to see another view of the comparison.",
+        panelTitle: "objdiff",
+        panelDescription:
+            "objdiff provides an object-level comparison view that can be useful when inspecting data in addition to and instruction differences.",
+        panelPreferredSide: "left",
+    });
+
+    if (elementExists(SELECTOR.problemsTab)) {
+        addTabSection({
+            steps,
+            boarding,
+            tabSelector: SELECTOR.problemsTab,
+            panelSelector: SELECTOR.problemsPanel,
+            tabTitle: "Problems tab",
+            tabDescription:
+                "Click <strong>Problems</strong> to see compiler output.",
+            panelTitle: "Problems",
+            panelDescription:
+                "Any compiler errors and warnings will be shown here.",
+        });
+    }
+
+    if (elementExists(SELECTOR.decompileButton)) {
+        steps.push(
+            makeClickToContinueStep({
+                boarding,
+                selector: SELECTOR.decompileButton,
+                waitForSelector: SELECTOR.decompilePanel,
+                title: "Open decompilation",
+                description:
+                    "Click <strong>Decompile</strong> to open the decompiler panel for this scratch.",
+            }),
+        );
+        steps.push(
+            makeStep(
+                SELECTOR.decompilePanel,
+                "Decompilation",
+                "Decompilation is a helper for generating a starting point. It can save time, but the result still needs review and editing.",
+                "left",
+            ),
+        );
+    }
+
+    addIfPresent(
+        steps,
+        makeStep(
+            SELECTOR.scratchView,
+            "The matching loop",
+            "The usual loop is edit source, context, or options; inspect the diff; and repeat. By default, changes are compiled automatically, and you can configure that behavior in your editor settings.",
+        ),
+    );
+    addIfPresent(
+        steps,
+        makeStep(
+            SELECTOR.tourHelp,
+            "More help",
+            'If you have more questions, the <a href="/faq">FAQ</a> is a good next stop, or feel free to join the <a href="https://discord.gg/sutqNShRRs" target="_blank" rel="noreferrer">decomp.me Discord server</a>, where people ask for help, share scratches, and discuss decompilation in a collaborative environment.',
+        ),
+    );
+
+    return steps;
+}
+
+export default function ScratchTour(): null {
+    const searchParams = useSearchParams();
+    const tourEnabled = searchParams.get("tour") === "1";
+
+    useEffect(() => {
+        const boarding = new Boarding({
+            allowClose: true,
+            className: "scratch-tour-popover",
+            keyboardControl: true,
+            nextBtnText: "Next",
+            prevBtnText: "Back",
+            doneBtnText: "Finish",
+            overlayClickNext: false,
+            padding: 8,
+            radius: 4,
+            strictClickHandling: true,
+            scrollIntoViewOptions: { block: "center", inline: "center" },
+        });
+
+        const startTour = () => {
+            resetBoarding(boarding);
+            const steps = buildTourSteps(boarding);
+            if (steps.length === 0) return;
+
+            boarding.defineSteps(steps);
+            boarding.start();
+        };
+
+        const timeout = tourEnabled
+            ? window.setTimeout(startTour, 300)
+            : undefined;
+
+        window.addEventListener("scratch-tour:start", startTour);
+
+        return () => {
+            if (timeout) window.clearTimeout(timeout);
+            window.removeEventListener("scratch-tour:start", startTour);
+            resetBoarding(boarding);
+        };
+    }, [tourEnabled]);
+
+    return null;
+}
diff --git a/frontend/src/components/Scratch/panels/AboutPanel.tsx b/frontend/src/components/Scratch/panels/AboutPanel.tsx
index ab2016aa2..01e2adf66 100644
--- a/frontend/src/components/Scratch/panels/AboutPanel.tsx
+++ b/frontend/src/components/Scratch/panels/AboutPanel.tsx
@@ -53,7 +53,7 @@ export default function AboutPanel({ scratch, setScratch }: Props) {
     const preset: PresetBase = usePreset(scratch.preset);
 
     return (
-        <div className={styles.container}>
+        <div className={styles.container} data-tour="scratch-about-panel">
             <div>
                 <div className={styles.horizontalField}>
                     <p className={styles.label}>Name</p>
diff --git a/frontend/src/components/Scratch/panels/DecompilePanel.tsx b/frontend/src/components/Scratch/panels/DecompilePanel.tsx
index 87eb6fcb8..d4e64ef1f 100644
--- a/frontend/src/components/Scratch/panels/DecompilePanel.tsx
+++ b/frontend/src/components/Scratch/panels/DecompilePanel.tsx
@@ -50,7 +50,7 @@ export default function DecompilePanel({ scratch }: Props) {
         decompiledCode === null || scratch.context !== debouncedContext;
 
     return (
-        <div className={styles.container}>
+        <div className={styles.container} data-tour="scratch-decompile-panel">
             <section className={styles.main}>
                 <p>
                     Modify the context or compiler to see how the decompilation
diff --git a/frontend/src/components/Scratch/panels/FamilyPanel.tsx b/frontend/src/components/Scratch/panels/FamilyPanel.tsx
index 4a2912f8e..8e131e7ca 100644
--- a/frontend/src/components/Scratch/panels/FamilyPanel.tsx
+++ b/frontend/src/components/Scratch/panels/FamilyPanel.tsx
@@ -20,7 +20,10 @@ type Props = {
 
 export default function FamilyPanel({ scratch }: Props) {
     return (
-        <div className="h-full overflow-auto p-4">
+        <div
+            className="h-full overflow-auto p-4"
+            data-tour="scratch-family-panel"
+        >
             <SortableFamilyList scratch={scratch} />
         </div>
     );
diff --git a/frontend/src/components/Scratch/panels/ProblemPanel.tsx b/frontend/src/components/Scratch/panels/ProblemPanel.tsx
index f8336c1a9..e901dab8f 100644
--- a/frontend/src/components/Scratch/panels/ProblemPanel.tsx
+++ b/frontend/src/components/Scratch/panels/ProblemPanel.tsx
@@ -2,7 +2,10 @@ import CompilerMessageOutput from "../CompilerMessageOutput";
 
 export default function ProblemPanel({ text }: { text: string }) {
     return (
-        <div className="h-full min-h-0 overflow-auto whitespace-pre p-1 font-mono text-xs">
+        <div
+            className="h-full min-h-0 overflow-auto whitespace-pre p-1 font-mono text-xs"
+            data-tour="scratch-problems-panel"
+        >
             <CompilerMessageOutput text={text} />
         </div>
     );
diff --git a/frontend/src/components/Tabs.tsx b/frontend/src/components/Tabs.tsx
index 4866ec670..2c9d7528f 100644
--- a/frontend/src/components/Tabs.tsx
+++ b/frontend/src/components/Tabs.tsx
@@ -45,6 +45,7 @@ export type TabContent = ReactNode | (() => ReactNode);
 export type TabProps = {
     children?: TabContent;
     className?: string;
+    dataTour?: string;
     tabKey: string;
     label?: ReactNode;
     disabled?: boolean;
@@ -77,6 +78,7 @@ export class Tab extends Component<TabProps> {
                             role="tab"
                             aria-selected={ctx.activeTab === key}
                             className={styles.tabButton}
+                            data-tour={this.props.dataTour}
                             disabled={this.props.disabled}
                             onClick={() => {
                                 ctx.setActive(key);
@@ -259,6 +261,9 @@ export default function Tabs({
                                     styles.tabPanelContent,
                                     props.className,
                                 )}
+                                data-tour={
+                                    props.dataTour && `${props.dataTour}-panel`
+                                }
                             >
                                 <ErrorBoundary>{children}</ErrorBoundary>
                             </div>
diff --git a/frontend/src/components/compiler/CompilerOpts.tsx b/frontend/src/components/compiler/CompilerOpts.tsx
index db738a709..6e14b0b8a 100644
--- a/frontend/src/components/compiler/CompilerOpts.tsx
+++ b/frontend/src/components/compiler/CompilerOpts.tsx
@@ -414,7 +414,10 @@ export default function CompilerOpts({
 
     return (
         <>
-            <section className={styles.header}>
+            <section
+                className={styles.header}
+                data-tour="scratch-options-preset"
+            >
                 <PlatformIcon platform={platform} size={32} />
                 <div className={styles.preset}>
                     Preset
@@ -426,7 +429,10 @@ export default function CompilerOpts({
                 </div>
             </section>
             <OptsContext.Provider value={optsEditorProvider}>
-                <section className={styles.section}>
+                <section
+                    className={styles.section}
+                    data-tour="scratch-options-compiler"
+                >
                     <h3 className={styles.heading}>Compiler options</h3>
                     <OptsEditor
                         availableCompilers={availableCompilers}
@@ -438,15 +444,20 @@ export default function CompilerOpts({
                 </section>
             </OptsContext.Provider>
 
-            <LibrariesSection
-                className={styles.section}
-                libraries={value.libraries}
-                setLibraries={setLibraries}
-                platform={platform}
-            />
+            <section data-tour="scratch-options-libraries">
+                <LibrariesSection
+                    className={styles.section}
+                    libraries={value.libraries}
+                    setLibraries={setLibraries}
+                    platform={platform}
+                />
+            </section>
 
             <OptsContext.Provider value={diffOptsEditorProvider}>
-                <section className={styles.section}>
+                <section
+                    className={styles.section}
+                    data-tour="scratch-options-diff"
+                >
                     <h3 className={styles.heading}>Diff options</h3>
                     <DiffOptsEditor
                         platform={platform}
@@ -457,7 +468,10 @@ export default function CompilerOpts({
                 </section>
             </OptsContext.Provider>
 
-            <section className={styles.section}>
+            <section
+                className={styles.section}
+                data-tour="scratch-options-other"
+            >
                 <h3 className={styles.heading}>Other options</h3>
                 <Checkbox
                     checked={matchOverride}
diff --git a/frontend/yarn.lock b/frontend/yarn.lock
index 10764197d..a6cc36a14 100644
--- a/frontend/yarn.lock
+++ b/frontend/yarn.lock
@@ -2840,6 +2840,11 @@ binary-extensions@^2.0.0:
   resolved "https://registry.yarnpkg.com/binary-extensions/-/binary-extensions-2.3.0.tgz#f6e14a97858d327252200242d4ccfe522c445522"
   integrity sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==
 
+boarding.js@^3.7.3:
+  version "3.7.3"
+  resolved "https://registry.yarnpkg.com/boarding.js/-/boarding.js-3.7.3.tgz#0e3ae267faa2ca5407c56e209f5898fb242310eb"
+  integrity sha512-Ndig9L06bwWdEBCor2St9cmcmtGTeSiXDhXeZ3QgWa/RLh4P5mL0DHQB5xRjo9wmSsqwMQhW3v2d79XKH9wnqw==
+
 boolbase@^1.0.0:
   version "1.0.0"
   resolved "https://registry.yarnpkg.com/boolbase/-/boolbase-1.0.0.tgz#68dff5fbe60c51eb37725ea9e3ed310dcc1e776e"

From bc30c219cedf8c09f6aad7e96724a86c6069dfa1 Mon Sep 17 00:00:00 2001
From: Mark Street <streetster@gmail.com>
Date: Sun, 31 May 2026 19:10:59 +0100
Subject: [PATCH 2/7] Feedback part 1

---
 frontend/src/components/CustomLayout.tsx      |  21 ++-
 frontend/src/components/Diff/Diff.tsx         |  75 +++++----
 .../src/components/Scratch/ScratchTour.tsx    | 149 ++++++++----------
 3 files changed, 122 insertions(+), 123 deletions(-)

diff --git a/frontend/src/components/CustomLayout.tsx b/frontend/src/components/CustomLayout.tsx
index 59d72d7ca..d3b2c33f7 100644
--- a/frontend/src/components/CustomLayout.tsx
+++ b/frontend/src/components/CustomLayout.tsx
@@ -89,11 +89,22 @@ export default function CustomLayout({ renderTab, layout, onChange }: Props) {
 
             els.push(
                 <Allotment.Pane key={child.key} minSize={minCollapsedHeight}>
-                    <CustomLayout
-                        renderTab={renderTab}
-                        layout={child}
-                        onChange={setChild}
-                    />
+                    <div
+                        className="size-full min-h-0"
+                        data-tour={
+                            child.key === 1
+                                ? "scratch-layout-left"
+                                : child.key === 2
+                                  ? "scratch-layout-right"
+                                  : undefined
+                        }
+                    >
+                        <CustomLayout
+                            renderTab={renderTab}
+                            layout={child}
+                            onChange={setChild}
+                        />
+                    </div>
                 </Allotment.Pane>,
             );
         }
diff --git a/frontend/src/components/Diff/Diff.tsx b/frontend/src/components/Diff/Diff.tsx
index b6c3c607e..2eec6b5f6 100644
--- a/frontend/src/components/Diff/Diff.tsx
+++ b/frontend/src/components/Diff/Diff.tsx
@@ -512,41 +512,46 @@ export default function Diff({
                         {col === rightmostColumn && (
                             <>
                                 <div className={styles.spacer} />
-                                <ToggleButton
-                                    label="T"
-                                    title="Target column"
-                                    enabled={columnState.base}
-                                    setEnabled={(enabled) =>
-                                        setColumn("base", enabled)
-                                    }
-                                    dataTour="scratch-diff-toggle-target"
-                                />
-                                <ToggleButton
-                                    label="C"
-                                    title="Current column"
-                                    enabled={columnState.current}
-                                    setEnabled={(enabled) =>
-                                        setColumn("current", enabled)
-                                    }
-                                    dataTour="scratch-diff-toggle-current"
-                                />
-                                <ToggleButton
-                                    label="3"
-                                    title="3-way diff"
-                                    enabled={threeWayDiffEnabled}
-                                    setEnabled={handleSetThreeWayDiff}
-                                    dataTour="scratch-diff-toggle-three-way"
-                                />
-                                <ToggleButton
-                                    label={<FoldIcon size={16} />}
-                                    disabledLabel="Collapse streaks of "
-                                    enabledLabel="Show all "
-                                    title="matching lines"
-                                    padding="px-1 py-1"
-                                    enabled={compressionEnabled}
-                                    setEnabled={setCompressionEnabled}
-                                    dataTour="scratch-diff-toggle-compression"
-                                />
+                                <div
+                                    className="flex items-center gap-1"
+                                    data-tour="scratch-diff-toggles"
+                                >
+                                    <ToggleButton
+                                        label="T"
+                                        title="Target column"
+                                        enabled={columnState.base}
+                                        setEnabled={(enabled) =>
+                                            setColumn("base", enabled)
+                                        }
+                                        dataTour="scratch-diff-toggle-target"
+                                    />
+                                    <ToggleButton
+                                        label="C"
+                                        title="Current column"
+                                        enabled={columnState.current}
+                                        setEnabled={(enabled) =>
+                                            setColumn("current", enabled)
+                                        }
+                                        dataTour="scratch-diff-toggle-current"
+                                    />
+                                    <ToggleButton
+                                        label="3"
+                                        title="3-way diff"
+                                        enabled={threeWayDiffEnabled}
+                                        setEnabled={handleSetThreeWayDiff}
+                                        dataTour="scratch-diff-toggle-three-way"
+                                    />
+                                    <ToggleButton
+                                        label={<FoldIcon size={16} />}
+                                        disabledLabel="Collapse streaks of "
+                                        enabledLabel="Show all "
+                                        title="matching lines"
+                                        padding="px-1 py-1"
+                                        enabled={compressionEnabled}
+                                        setEnabled={setCompressionEnabled}
+                                        dataTour="scratch-diff-toggle-compression"
+                                    />
+                                </div>
                             </>
                         )}
                     </div>
diff --git a/frontend/src/components/Scratch/ScratchTour.tsx b/frontend/src/components/Scratch/ScratchTour.tsx
index 67ef8a483..6776854cd 100644
--- a/frontend/src/components/Scratch/ScratchTour.tsx
+++ b/frontend/src/components/Scratch/ScratchTour.tsx
@@ -10,6 +10,8 @@ type TourStep = BoardingSteps[number];
 const SELECTOR = {
     toolbar: '[data-tour="scratch-toolbar"]',
     scratchView: '[data-tour="scratch-view"]',
+    leftPane: '[data-tour="scratch-layout-left"]',
+    rightPane: '[data-tour="scratch-layout-right"]',
     tourHelp: '[data-tour="scratch-tour-help"]',
     compileButton: '[data-tour="scratch-action-compile"]',
     saveButton: '[data-tour="scratch-action-save"]',
@@ -34,6 +36,7 @@ const SELECTOR = {
     targetColumn: '[data-tour="scratch-diff-column-base"]',
     currentColumn: '[data-tour="scratch-diff-column-current"]',
     thirdColumn: '[data-tour="scratch-diff-column-previous"]',
+    diffToggles: '[data-tour="scratch-diff-toggles"]',
     targetToggle: '[data-tour="scratch-diff-toggle-target"]',
     currentToggle: '[data-tour="scratch-diff-toggle-current"]',
     threeWayToggle: '[data-tour="scratch-diff-toggle-three-way"]',
@@ -144,7 +147,8 @@ function makeClickToContinueStep({
             title,
             description,
             preferredSide,
-            showButtons: ["close", "previous"],
+            showButtons: ["close", "previous", "next"],
+            disableButtons: ["next"],
         },
     };
 }
@@ -225,86 +229,49 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         makeStep(
             SELECTOR.scratchView,
             "Scratch tour",
-            "This tour highlights the main parts of a scratch. Use <strong>Next</strong> and <strong>Back</strong> to move through it. When a step says <strong>Click</strong> a tab or button, the tour will wait for you to do that before continuing.",
+            "This tour highlights the core features of the scratch editor. Use <strong>Next</strong> and <strong>Back</strong> to move through it. When a step says <strong>Click</strong> a tab or button, the tour will wait for you to do that before continuing.",
+            "top",
         ),
     );
 
     addIfPresent(
         steps,
         makeStep(
-            SELECTOR.toolbar,
-            "Scratch overview",
-            "A scratch is a shareable workspace for matching a function. If you own the scratch you can rename it by clicking on its name and making your changes.",
+            SELECTOR.leftPane,
+            "Editing area",
+            "The left side of the scratch editor is where you make your changes: edit source code and context, tweak compiler options, and update scratch metadata.",
+            "right",
         ),
     );
 
     addIfPresent(
         steps,
         makeStep(
-            SELECTOR.saveButton,
-            "Save",
-            "Hitting Save will save your changes.",
-        ),
-    );
-    addIfPresent(
-        steps,
-        makeStep(
-            SELECTOR.forkButton,
-            "Fork",
-            "Forking a scratch creates your own editable copy, this is how you can save your changes.",
-        ),
-    );
-    addIfPresent(
-        steps,
-        makeStep(
-            SELECTOR.compileButton,
-            "Compile",
-            "Clicking Compile will send your scratch to the backend to be compiled and diffed against the target assembly.",
+            SELECTOR.rightPane,
+            "Results area",
+            "The right side is where you will see the results of your changes: assembly diff and any warnings or errors from the compiler.",
+            "left",
         ),
     );
+
     addIfPresent(
         steps,
         makeStep(
-            SELECTOR.decompileButton,
-            "Decompile",
-            "When the platform supports it, Decompile can generate a starting point from the target assembly.",
+            SELECTOR.toolbar,
+            "Scratch toolbar",
+            "The toolbar contains scratch-level actions such as saving, forking, exporting, decompiling. <br /> If you own the scratch you can rename it by clicking on its name and making your changes.",
         ),
     );
+
     addIfPresent(
         steps,
         makeStep(
-            SELECTOR.exportButton,
-            "Export",
-            "The Export button creates & downloads a zip of the current scratch, allowing you to inspect them locally.",
+            SELECTOR.forkButton,
+            "Fork",
+            "Forking a scratch creates your own editable copy, this is how you can save your changes if you're not the owner.",
         ),
     );
 
-    addTabSection({
-        steps,
-        boarding,
-        tabSelector: SELECTOR.aboutTab,
-        panelSelector: SELECTOR.aboutPanel,
-        tabTitle: "About tab",
-        tabDescription:
-            "Click <strong>About</strong> to switch to the About tab where you will find the scratch metadata.",
-        panelTitle: "About",
-        panelDescription:
-            "The About tab shows the score, owner, platform, preset, timestamps, parent scratch, and any notes attached to the scratch.",
-    });
-
-    addTabSection({
-        steps,
-        boarding,
-        tabSelector: SELECTOR.familyTab,
-        panelSelector: SELECTOR.familyPanel,
-        tabTitle: "Family tab",
-        tabDescription:
-            "Click <strong>Family</strong> to switch to the Family tab to see related forks.",
-        panelTitle: "Scratch family",
-        panelDescription:
-            "Forks let people collaborate on the same target function. The family tab helps find related work and improvements.",
-    });
-
     addTabSection({
         steps,
         boarding,
@@ -312,10 +279,10 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         panelSelector: SELECTOR.sourcePanel,
         tabTitle: "Source code tab",
         tabDescription:
-            "Click <strong>Source code</strong> to return to the main editor.",
+            "Click the <strong>Source code</strong> tab to select the code editor.",
         panelTitle: "Source code",
         panelDescription:
-            "Most of the matching loop happens here: edit code, compile, inspect the diff, and repeat.",
+            "The matching loop happens here: edit the code, compile, check the diff, repeat until the code matches. <br /> By default, changes are compiled automatically after a short delay; you can configure this behavior in the editor settings found in the hamburger menu.",
     });
 
     addTabSection({
@@ -325,7 +292,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         panelSelector: SELECTOR.contextPanel,
         tabTitle: "Context tab",
         tabDescription:
-            "Click <strong>Context</strong> to see supporting declarations.",
+            "Now click the <strong>Context</strong> tab to see supporting declarations.",
         panelTitle: "Context",
         panelDescription:
             "Use this space for shared typedefs, symbols, function definitions, etc., that are used by the function you are trying to match.",
@@ -338,16 +305,16 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         panelSelector: SELECTOR.optionsPanel,
         tabTitle: "Options tab",
         tabDescription:
-            "Click <strong>Options</strong> to open compiler and diff settings.",
+            "Click the <strong>Options</strong> tab to open compiler and diff settings.",
         panelTitle: "Options",
         panelDescription:
-            "Options control how your source is compiled and compared. Most scratches will have compiler flags set via preset.",
+            "Options control how your source is compiled and compared. Most scratches will have compiler flags set via a preset.",
     });
     steps.push(
         makeStep(
             SELECTOR.optionsCompiler,
             "Compiler options",
-            "Compiler options choose the compiler and flags used to build your source.",
+            "Compiler options allow you to change the compiler and flags used to build your source.",
         ),
     );
     steps.push(
@@ -361,10 +328,35 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         makeStep(
             SELECTOR.optionsOther,
             "Other options",
-            "Match override lets an owner mark a scratch as effectively matching even when naming or symbol details leave a tiny mismatch.",
+            "Match override lets an owner mark a scratch as matching even when naming or symbol details leave a mismatch.",
         ),
     );
 
+    addTabSection({
+        steps,
+        boarding,
+        tabSelector: SELECTOR.familyTab,
+        panelSelector: SELECTOR.familyPanel,
+        tabTitle: "Family tab",
+        tabDescription:
+            "Click <strong>Family</strong> to switch to the Family tab to see related forks.",
+        panelTitle: "Scratch family",
+        panelDescription:
+            "Forks let people collaborate on the same target function. The family tab helps find related work and improvements.",
+    });
+
+    addTabSection({
+        steps,
+        boarding,
+        tabSelector: SELECTOR.aboutTab,
+        panelSelector: SELECTOR.aboutPanel,
+        tabTitle: "About tab",
+        tabDescription: "Now click the <strong>About</strong> tab.",
+        panelTitle: "About",
+        panelDescription:
+            "The About tab shows the score, owner, platform, preset, timestamps, parent scratch, and any notes attached to the scratch.",
+    });
+
     addTabSection({
         steps,
         boarding,
@@ -375,7 +367,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
             "Click <strong>Compilation</strong> to inspect the current diff.",
         panelTitle: "Compilation",
         panelDescription:
-            "The Compilation panel shows the current assembly diff and compiler output. A score of 0 means the generated output matches the target.",
+            "The Compilation panel shows the current assembly diff and compiler output. The lower the score the better; a score of 0 means the generated output matches the target.",
         panelPreferredSide: "left",
     });
     addIfPresent(
@@ -391,15 +383,15 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         makeStep(
             SELECTOR.currentColumn,
             "Current column",
-            "Current show what the result of your compiled source code.",
+            "Current show the result of your compiled source code.",
         ),
     );
     addIfPresent(
         steps,
         makeStep(
-            SELECTOR.targetToggle,
+            SELECTOR.diffToggles,
             "Column toggles",
-            "The T and C buttons hide or show the Target and Current columns when you need more room.",
+            "These controls hide or show diff columns, enable 3-way comparison, and collapse long unchanged stretches when you need more room.",
         ),
     );
 
@@ -412,14 +404,14 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
                 waitForSelector: SELECTOR.thirdColumn,
                 title: "3-way diff",
                 description:
-                    "Click <strong>3</strong> to add a third column comparing against your saved version or previous compile, depending on your editor setting.",
+                    "Click the <strong>3</strong> to add a third column comparing against your saved version or previous compile, depending on your editor setting.",
             }),
         );
         steps.push(
             makeStep(
                 SELECTOR.thirdColumn,
                 "Third diff column",
-                "This extra column gives you another baseline while you compare changes.",
+                "This column allows you to better identify how your changes affect the diff.",
             ),
         );
         steps.push({
@@ -441,7 +433,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
             makeStep(
                 SELECTOR.compressionToggle,
                 "Compress diff",
-                "The fold button collapses long unchanged stretches so you can focus on the differences. You can toggle it whenever the full diff has too much noise.",
+                "The fold button collapses long unchanged stretches so you can focus on the differences.",
             ),
         );
     }
@@ -453,10 +445,10 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         panelSelector: SELECTOR.objdiffPanel,
         tabTitle: "objdiff tab",
         tabDescription:
-            "Click <strong>objdiff</strong> to see another view of the comparison.",
+            "Click the <strong>objdiff</strong> tab to switch from asm-differ to the objdiff backend.",
         panelTitle: "objdiff",
         panelDescription:
-            "objdiff provides an object-level comparison view that can be useful when inspecting data in addition to and instruction differences.",
+            "objdiff provides an object-level comparison view that can be useful when inspecting data in addition to any instruction differences.",
         panelPreferredSide: "left",
     });
 
@@ -468,7 +460,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
             panelSelector: SELECTOR.problemsPanel,
             tabTitle: "Problems tab",
             tabDescription:
-                "Click <strong>Problems</strong> to see compiler output.",
+                "Click the <strong>Problems</strong> panel to see compiler output.",
             panelTitle: "Problems",
             panelDescription:
                 "Any compiler errors and warnings will be shown here.",
@@ -490,20 +482,11 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
             makeStep(
                 SELECTOR.decompilePanel,
                 "Decompilation",
-                "Decompilation is a helper for generating a starting point. It can save time, but the result still needs review and editing.",
-                "left",
+                "When the platform supports it, this table will show the results of running a decompiler against the target assembly and contents of the scratch context.",
             ),
         );
     }
 
-    addIfPresent(
-        steps,
-        makeStep(
-            SELECTOR.scratchView,
-            "The matching loop",
-            "The usual loop is edit source, context, or options; inspect the diff; and repeat. By default, changes are compiled automatically, and you can configure that behavior in your editor settings.",
-        ),
-    );
     addIfPresent(
         steps,
         makeStep(

From b9d1874f4de3cd3c659f57b02c4daa44f4878ca3 Mon Sep 17 00:00:00 2001
From: Mark Street <streetster@gmail.com>
Date: Sun, 31 May 2026 19:18:48 +0100
Subject: [PATCH 3/7] Start tour box at the top of the page

---
 frontend/src/components/Scratch/Scratch.tsx     | 5 +++++
 frontend/src/components/Scratch/ScratchTour.tsx | 5 +++--
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/frontend/src/components/Scratch/Scratch.tsx b/frontend/src/components/Scratch/Scratch.tsx
index d25c39c56..60d937f7e 100644
--- a/frontend/src/components/Scratch/Scratch.tsx
+++ b/frontend/src/components/Scratch/Scratch.tsx
@@ -581,6 +581,11 @@ export default function Scratch({
             data-tour="scratch-view"
         >
             <ScratchTour />
+            <span
+                aria-hidden
+                className="pointer-events-none fixed top-4 left-1/2 size-px"
+                data-tour="scratch-tour-intro"
+            />
             <ErrorBoundary>
                 <ScratchMatchBanner scratch={scratch} />
             </ErrorBoundary>
diff --git a/frontend/src/components/Scratch/ScratchTour.tsx b/frontend/src/components/Scratch/ScratchTour.tsx
index 6776854cd..50ef16880 100644
--- a/frontend/src/components/Scratch/ScratchTour.tsx
+++ b/frontend/src/components/Scratch/ScratchTour.tsx
@@ -8,6 +8,7 @@ import { Boarding, type BoardingSteps } from "boarding.js";
 type TourStep = BoardingSteps[number];
 
 const SELECTOR = {
+    tourIntro: '[data-tour="scratch-tour-intro"]',
     toolbar: '[data-tour="scratch-toolbar"]',
     scratchView: '[data-tour="scratch-view"]',
     leftPane: '[data-tour="scratch-layout-left"]',
@@ -227,10 +228,10 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
     addIfPresent(
         steps,
         makeStep(
-            SELECTOR.scratchView,
+            SELECTOR.tourIntro,
             "Scratch tour",
             "This tour highlights the core features of the scratch editor. Use <strong>Next</strong> and <strong>Back</strong> to move through it. When a step says <strong>Click</strong> a tab or button, the tour will wait for you to do that before continuing.",
-            "top",
+            "bottom",
         ),
     );
 

From d0aeb7529ce4a681aa8d039b9d4d18760bc1c1a7 Mon Sep 17 00:00:00 2001
From: Mark Street <streetster@gmail.com>
Date: Sun, 31 May 2026 19:26:20 +0100
Subject: [PATCH 4/7] highlight diff columns

---
 frontend/src/components/Diff/Diff.module.scss | 23 +++++++++++++++++++
 frontend/src/components/Diff/Diff.tsx         | 11 +++++++++
 .../src/components/Scratch/ScratchTour.tsx    |  6 ++---
 3 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/frontend/src/components/Diff/Diff.module.scss b/frontend/src/components/Diff/Diff.module.scss
index 89f6c2c51..fa0ef5692 100644
--- a/frontend/src/components/Diff/Diff.module.scss
+++ b/frontend/src/components/Diff/Diff.module.scss
@@ -52,6 +52,29 @@
     }
 }
 
+.columnTourTarget {
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    z-index: 1;
+    pointer-events: none;
+}
+
+.columnTourTarget-base {
+    left: 0;
+    width: var(--diff-left-width);
+}
+
+.columnTourTarget-current {
+    left: var(--diff-left-width);
+    right: var(--diff-right-width);
+}
+
+.columnTourTarget-previous {
+    right: 0;
+    width: var(--diff-right-width);
+}
+
 .searchPanel {
     position: absolute;
     z-index: 120;
diff --git a/frontend/src/components/Diff/Diff.tsx b/frontend/src/components/Diff/Diff.tsx
index 2eec6b5f6..bc36eceb6 100644
--- a/frontend/src/components/Diff/Diff.tsx
+++ b/frontend/src/components/Diff/Diff.tsx
@@ -11,6 +11,7 @@ import {
 } from "react";
 
 import { FoldIcon, SearchIcon } from "@primer/octicons-react";
+import clsx from "clsx";
 import AutoSizer from "react-virtualized-auto-sizer";
 import { FixedSizeList } from "react-window";
 import { useDebounce } from "use-debounce";
@@ -479,6 +480,16 @@ export default function Diff({
         >
             {columnCount >= 2 && <DragBar pos={bar1Px} onChange={setBar1Px} />}
             {columnCount === 3 && <DragBar pos={bar2Px} onChange={setBar2Px} />}
+            {columns.map((col) => (
+                <div
+                    key={col}
+                    className={clsx(
+                        styles.columnTourTarget,
+                        styles[`columnTourTarget-${col}`],
+                    )}
+                    data-tour={`scratch-diff-column-${col}-full`}
+                />
+            ))}
             <div className={styles.headers}>
                 {columns.map((col) => (
                     <div
diff --git a/frontend/src/components/Scratch/ScratchTour.tsx b/frontend/src/components/Scratch/ScratchTour.tsx
index 50ef16880..ba93670c2 100644
--- a/frontend/src/components/Scratch/ScratchTour.tsx
+++ b/frontend/src/components/Scratch/ScratchTour.tsx
@@ -34,9 +34,9 @@ const SELECTOR = {
     optionsOther: '[data-tour="scratch-options-other"]',
     compilationTab: '[data-tour="scratch-tab-compilation"]',
     compilationPanel: '[data-tour="scratch-tab-compilation-panel"]',
-    targetColumn: '[data-tour="scratch-diff-column-base"]',
-    currentColumn: '[data-tour="scratch-diff-column-current"]',
-    thirdColumn: '[data-tour="scratch-diff-column-previous"]',
+    targetColumn: '[data-tour="scratch-diff-column-base-full"]',
+    currentColumn: '[data-tour="scratch-diff-column-current-full"]',
+    thirdColumn: '[data-tour="scratch-diff-column-previous-full"]',
     diffToggles: '[data-tour="scratch-diff-toggles"]',
     targetToggle: '[data-tour="scratch-diff-toggle-target"]',
     currentToggle: '[data-tour="scratch-diff-toggle-current"]',

From cc75ceeb0f5e190be8627fdf31a3c8a7b077500d Mon Sep 17 00:00:00 2001
From: Mark Street <streetster@gmail.com>
Date: Sun, 31 May 2026 19:57:01 +0100
Subject: [PATCH 5/7] Finish tour on the Tour button

---
 frontend/src/components/Scratch/Scratch.tsx       |  6 ------
 .../src/components/Scratch/ScratchToolbar.tsx     | 10 +++++++---
 frontend/src/components/Scratch/ScratchTour.tsx   | 15 +++++++--------
 3 files changed, 14 insertions(+), 17 deletions(-)

diff --git a/frontend/src/components/Scratch/Scratch.tsx b/frontend/src/components/Scratch/Scratch.tsx
index 60d937f7e..15700afe2 100644
--- a/frontend/src/components/Scratch/Scratch.tsx
+++ b/frontend/src/components/Scratch/Scratch.tsx
@@ -581,11 +581,6 @@ export default function Scratch({
             data-tour="scratch-view"
         >
             <ScratchTour />
-            <span
-                aria-hidden
-                className="pointer-events-none fixed top-4 left-1/2 size-px"
-                data-tour="scratch-tour-intro"
-            />
             <ErrorBoundary>
                 <ScratchMatchBanner scratch={scratch} />
             </ErrorBoundary>
@@ -617,7 +612,6 @@ export default function Scratch({
                 )}
             </ErrorBoundary>
             {offlineOverlay}
-            <span className="sr-only" data-tour="scratch-tour-help" />
         </div>
     );
 }
diff --git a/frontend/src/components/Scratch/ScratchToolbar.tsx b/frontend/src/components/Scratch/ScratchToolbar.tsx
index 59aebbab9..6e359fe54 100644
--- a/frontend/src/components/Scratch/ScratchToolbar.tsx
+++ b/frontend/src/components/Scratch/ScratchToolbar.tsx
@@ -5,6 +5,7 @@ import {
     type FC,
     type ClipboardEvent,
     type KeyboardEvent,
+    type MouseEvent,
     type JSX,
 } from "react";
 
@@ -51,8 +52,11 @@ function exportScratchZip(scratch: api.Scratch) {
     a.click();
 }
 
-function startScratchTour() {
-    window.dispatchEvent(new CustomEvent("scratch-tour:start"));
+function startScratchTour(event?: MouseEvent<HTMLButtonElement>) {
+    event?.currentTarget.blur();
+    window.setTimeout(() => {
+        window.dispatchEvent(new CustomEvent("scratch-tour:start"));
+    }, 0);
 }
 
 function EditTimeAgo({ date }: { date: string }) {
@@ -460,7 +464,7 @@ export default function ScratchToolbar(props: Props) {
                         "border-gray-6 border-b",
                     )}
                 >
-                    <Actions {...props} />
+                    <Actions {...props} tourTargetsEnabled />
                 </div>
             )}
         </>
diff --git a/frontend/src/components/Scratch/ScratchTour.tsx b/frontend/src/components/Scratch/ScratchTour.tsx
index ba93670c2..fd1ee1e1c 100644
--- a/frontend/src/components/Scratch/ScratchTour.tsx
+++ b/frontend/src/components/Scratch/ScratchTour.tsx
@@ -8,12 +8,11 @@ import { Boarding, type BoardingSteps } from "boarding.js";
 type TourStep = BoardingSteps[number];
 
 const SELECTOR = {
-    tourIntro: '[data-tour="scratch-tour-intro"]',
     toolbar: '[data-tour="scratch-toolbar"]',
     scratchView: '[data-tour="scratch-view"]',
     leftPane: '[data-tour="scratch-layout-left"]',
     rightPane: '[data-tour="scratch-layout-right"]',
-    tourHelp: '[data-tour="scratch-tour-help"]',
+    tourButton: '[data-tour="scratch-action-tour"]',
     compileButton: '[data-tour="scratch-action-compile"]',
     saveButton: '[data-tour="scratch-action-save"]',
     forkButton: '[data-tour="scratch-action-fork"]',
@@ -228,9 +227,9 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
     addIfPresent(
         steps,
         makeStep(
-            SELECTOR.tourIntro,
+            SELECTOR.toolbar,
             "Scratch tour",
-            "This tour highlights the core features of the scratch editor. Use <strong>Next</strong> and <strong>Back</strong> to move through it. When a step says <strong>Click</strong> a tab or button, the tour will wait for you to do that before continuing.",
+            "This button starts a guided tour of the scratch editor. Use <strong>Next</strong> and <strong>Back</strong> to move through it. When a step says <strong>Click</strong> a tab or button, the tour will wait for you to do that before continuing.",
             "bottom",
         ),
     );
@@ -340,7 +339,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         panelSelector: SELECTOR.familyPanel,
         tabTitle: "Family tab",
         tabDescription:
-            "Click <strong>Family</strong> to switch to the Family tab to see related forks.",
+            "Click <strong>Family</strong> to switch to the family tab to see related forks.",
         panelTitle: "Scratch family",
         panelDescription:
             "Forks let people collaborate on the same target function. The family tab helps find related work and improvements.",
@@ -355,7 +354,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         tabDescription: "Now click the <strong>About</strong> tab.",
         panelTitle: "About",
         panelDescription:
-            "The About tab shows the score, owner, platform, preset, timestamps, parent scratch, and any notes attached to the scratch.",
+            "The about tab shows the score, owner, platform, preset, timestamps, parent scratch, and any notes attached to the scratch.",
     });
 
     addTabSection({
@@ -491,9 +490,9 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
     addIfPresent(
         steps,
         makeStep(
-            SELECTOR.tourHelp,
+            SELECTOR.tourButton,
             "More help",
-            'If you have more questions, the <a href="/faq">FAQ</a> is a good next stop, or feel free to join the <a href="https://discord.gg/sutqNShRRs" target="_blank" rel="noreferrer">decomp.me Discord server</a>, where people ask for help, share scratches, and discuss decompilation in a collaborative environment.',
+            'If you have more questions, the <a href="/faq">FAQ</a> is a good next stop, or feel free to join the <a href="https://discord.gg/sutqNShRRs" target="_blank" rel="noreferrer">decomp.me Discord server</a>, where people ask for help, share scratches, and discuss decompilation in a collaborative environment. <br /> You can start the tour again by clicking the <strong>Tour</strong> button.',
         ),
     );
 

From 70c63711b551fab37ef6580fea79c9fcdd7a22ef Mon Sep 17 00:00:00 2001
From: Mark Street <streetster@gmail.com>
Date: Sun, 31 May 2026 20:18:45 +0100
Subject: [PATCH 6/7] Disable tour on mobile

---
 frontend/src/components/Scratch/ScratchToolbar.tsx | 2 +-
 frontend/src/components/Scratch/ScratchTour.tsx    | 6 ++++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/frontend/src/components/Scratch/ScratchToolbar.tsx b/frontend/src/components/Scratch/ScratchToolbar.tsx
index 6e359fe54..778da7bc0 100644
--- a/frontend/src/components/Scratch/ScratchToolbar.tsx
+++ b/frontend/src/components/Scratch/ScratchToolbar.tsx
@@ -339,7 +339,7 @@ function Actions({
                     />
                 </li>
             )}
-            <li>
+            <li className="hidden md:list-item">
                 <ActionButton
                     onClick={startScratchTour}
                     icon={<MilestoneIcon />}
diff --git a/frontend/src/components/Scratch/ScratchTour.tsx b/frontend/src/components/Scratch/ScratchTour.tsx
index fd1ee1e1c..c13bb02c3 100644
--- a/frontend/src/components/Scratch/ScratchTour.tsx
+++ b/frontend/src/components/Scratch/ScratchTour.tsx
@@ -172,6 +172,10 @@ function resetBoarding(boarding: Boarding) {
     }
 }
 
+function isTourViewportSupported() {
+    return window.matchMedia("(min-width: 768px)").matches;
+}
+
 function addIfPresent(steps: TourStep[], step: TourStep) {
     if (elementExists(step.element as string)) {
         steps.push(step);
@@ -519,6 +523,8 @@ export default function ScratchTour(): null {
         });
 
         const startTour = () => {
+            if (!isTourViewportSupported()) return;
+
             resetBoarding(boarding);
             const steps = buildTourSteps(boarding);
             if (steps.length === 0) return;

From 776f34c7f7c1f679c7ee4e429a168becc66c342e Mon Sep 17 00:00:00 2001
From: Mark Street <streetster@gmail.com>
Date: Mon, 1 Jun 2026 19:53:36 +0100
Subject: [PATCH 7/7] improved cta

---
 frontend/src/app/globals.scss                 | 28 ++++++
 .../src/components/Scratch/ScratchTour.tsx    | 89 +++++++++++++------
 .../Scratch/panels/DecompilePanel.tsx         |  5 +-
 3 files changed, 96 insertions(+), 26 deletions(-)

diff --git a/frontend/src/app/globals.scss b/frontend/src/app/globals.scss
index 7aa665b37..bc167aab9 100644
--- a/frontend/src/app/globals.scss
+++ b/frontend/src/app/globals.scss
@@ -86,6 +86,34 @@ body.no-scroll {
     }
 }
 
+.scratch-tour-click-target {
+    position: relative;
+    isolation: isolate;
+    border-radius: 6px;
+    animation: scratch-tour-click-target-pulse 1.2s ease-out infinite;
+}
+
+@keyframes scratch-tour-click-target-pulse {
+    0% {
+        box-shadow: 0 0 0 0 rgb(192 88 255 / 60%);
+    }
+
+    70% {
+        box-shadow: 0 0 0 10px rgb(192 88 255 / 0%);
+    }
+
+    100% {
+        box-shadow: 0 0 0 0 rgb(192 88 255 / 0%);
+    }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .scratch-tour-click-target {
+        animation: none;
+        box-shadow: 0 0 0 3px rgb(192 88 255 / 60%);
+    }
+}
+
 #boarding-popover-item.scratch-tour-popover {
     width: min(22rem, calc(100vw - 2rem));
     border: 1px solid var(--g600);
diff --git a/frontend/src/components/Scratch/ScratchTour.tsx b/frontend/src/components/Scratch/ScratchTour.tsx
index c13bb02c3..2d3f9d891 100644
--- a/frontend/src/components/Scratch/ScratchTour.tsx
+++ b/frontend/src/components/Scratch/ScratchTour.tsx
@@ -7,6 +7,8 @@ import { Boarding, type BoardingSteps } from "boarding.js";
 
 type TourStep = BoardingSteps[number];
 
+const CLICK_TARGET_CLASS = "scratch-tour-click-target";
+
 const SELECTOR = {
     toolbar: '[data-tour="scratch-toolbar"]',
     scratchView: '[data-tour="scratch-view"]',
@@ -47,6 +49,7 @@ const SELECTOR = {
     problemsPanel: '[data-tour="scratch-problems-panel"]',
     decompileTab: '[data-tour="scratch-tab-decompilation"]',
     decompilePanel: '[data-tour="scratch-decompile-panel"]',
+    decompileContent: '[data-tour="scratch-decompile-content"]',
 };
 
 function element(selector: string) {
@@ -57,6 +60,13 @@ function elementExists(selector: string) {
     return !!element(selector);
 }
 
+function clearClickTargets() {
+    const clickTargets = document.querySelectorAll(`.${CLICK_TARGET_CLASS}`);
+    for (let i = 0; i < clickTargets.length; i++) {
+        clickTargets[i].classList.remove(CLICK_TARGET_CLASS);
+    }
+}
+
 function isElementVisible(selector: string) {
     const el = element(selector);
     if (!el) return false;
@@ -115,6 +125,9 @@ function makeClickToContinueStep({
         element: selector,
         strictClickHandling: true,
         onHighlighted: () => {
+            clearClickTargets();
+            element(selector)?.classList.add(CLICK_TARGET_CLASS);
+
             const onClick = (event: MouseEvent) => {
                 const target = event.target;
                 if (!(target instanceof Element)) return;
@@ -135,6 +148,7 @@ function makeClickToContinueStep({
             };
         },
         onDeselected: () => {
+            element(selector)?.classList.remove(CLICK_TARGET_CLASS);
             removeClickListener?.();
             removeClickListener = undefined;
         },
@@ -158,6 +172,8 @@ function isToggleEnabled(selector: string) {
 }
 
 function resetBoarding(boarding: Boarding) {
+    clearClickTargets();
+
     if (!boarding.isActivated && !boarding.hasHighlightedElement()) return;
 
     try {
@@ -225,6 +241,16 @@ function addTabSection({
     );
 }
 
+function addDecompilationInfoStep(steps: TourStep[], selector: string) {
+    steps.push(
+        makeStep(
+            selector,
+            "Decompilation",
+            "When the platform supports it, this tab will show the results of running a decompiler against the target assembly and contents of the scratch context.",
+        ),
+    );
+}
+
 function buildTourSteps(boarding: Boarding): TourStep[] {
     const steps: TourStep[] = [];
 
@@ -233,7 +259,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         makeStep(
             SELECTOR.toolbar,
             "Scratch tour",
-            "This button starts a guided tour of the scratch editor. Use <strong>Next</strong> and <strong>Back</strong> to move through it. When a step says <strong>Click</strong> a tab or button, the tour will wait for you to do that before continuing.",
+            "Welcome to the guided tour of the scratch editor. Use <strong>Next</strong> and <strong>Back</strong> to move through it. <br /><br />When a step says to <strong>Click</strong> a tab or button, the tour will wait for you to do that before continuing.",
             "bottom",
         ),
     );
@@ -263,7 +289,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         makeStep(
             SELECTOR.toolbar,
             "Scratch toolbar",
-            "The toolbar contains scratch-level actions such as saving, forking, exporting, decompiling. <br /> If you own the scratch you can rename it by clicking on its name and making your changes.",
+            "The toolbar contains scratch-level actions such as saving, forking, exporting, decompiling. <br /><br /> If you own the scratch you can rename it by clicking on its name and making your changes.",
         ),
     );
 
@@ -271,8 +297,8 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         steps,
         makeStep(
             SELECTOR.forkButton,
-            "Fork",
-            "Forking a scratch creates your own editable copy, this is how you can save your changes if you're not the owner.",
+            "Fork to save",
+            "Forking a scratch creates your own editable copy, this is how you can save your changes when you aren't the owner.",
         ),
     );
 
@@ -286,7 +312,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
             "Click the <strong>Source code</strong> tab to select the code editor.",
         panelTitle: "Source code",
         panelDescription:
-            "The matching loop happens here: edit the code, compile, check the diff, repeat until the code matches. <br /> By default, changes are compiled automatically after a short delay; you can configure this behavior in the editor settings found in the hamburger menu.",
+            "The matching loop happens here: edit the code, compile, check the diff, repeat until the code matches. <br /><br /> By default, changes are compiled automatically after a short delay; you can configure this behavior in the editor settings found within the hamburger menu.",
     });
 
     addTabSection({
@@ -318,7 +344,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         makeStep(
             SELECTOR.optionsCompiler,
             "Compiler options",
-            "Compiler options allow you to change the compiler and flags used to build your source.",
+            "Compiler options allow you to change the compiler and tweak the flags used to build your source code.",
         ),
     );
     steps.push(
@@ -371,7 +397,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
             "Click <strong>Compilation</strong> to inspect the current diff.",
         panelTitle: "Compilation",
         panelDescription:
-            "The Compilation panel shows the current assembly diff and compiler output. The lower the score the better; a score of 0 means the generated output matches the target.",
+            "The compilation panel shows the current assembly diff and compiler output. The lower the score the better; a score of 0 means the generated output matches the target.",
         panelPreferredSide: "left",
     });
     addIfPresent(
@@ -379,7 +405,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         makeStep(
             SELECTOR.targetColumn,
             "Target column",
-            "Target shows the assembly you are trying to match.",
+            "The target column is the assembly that you are trying to match.",
         ),
     );
     addIfPresent(
@@ -387,7 +413,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         makeStep(
             SELECTOR.currentColumn,
             "Current column",
-            "Current show the result of your compiled source code.",
+            "The current column shows the result of your compiled source code.",
         ),
     );
     addIfPresent(
@@ -395,7 +421,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         makeStep(
             SELECTOR.diffToggles,
             "Column toggles",
-            "These controls hide or show diff columns, enable 3-way comparison, and collapse long unchanged stretches when you need more room.",
+            "These controls hide or show diff columns, enable 3-way comparison, and collapse long unchanged diffs when you need more room.",
         ),
     );
 
@@ -425,7 +451,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
                 isComplete: () =>
                     !isToggleEnabled(SELECTOR.threeWayToggle) &&
                     !isElementVisible(SELECTOR.thirdColumn),
-                title: "Turn 3-way off",
+                title: "Turn 3-way diff off",
                 description:
                     "Click <strong>3 again</strong> to return to the normal two-column diff.",
             }),
@@ -436,8 +462,8 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         steps.push(
             makeStep(
                 SELECTOR.compressionToggle,
-                "Compress diff",
-                "The fold button collapses long unchanged stretches so you can focus on the differences.",
+                "Compress the diff",
+                "The fold button collapses long matches so you can focus on the differences.",
             ),
         );
     }
@@ -462,7 +488,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
             boarding,
             tabSelector: SELECTOR.problemsTab,
             panelSelector: SELECTOR.problemsPanel,
-            tabTitle: "Problems tab",
+            tabTitle: "Problems panel",
             tabDescription:
                 "Click the <strong>Problems</strong> panel to see compiler output.",
             panelTitle: "Problems",
@@ -471,24 +497,37 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         });
     }
 
-    if (elementExists(SELECTOR.decompileButton)) {
+    if (isElementVisible(SELECTOR.decompilePanel)) {
+        addDecompilationInfoStep(
+            steps,
+            elementExists(SELECTOR.decompileContent)
+                ? SELECTOR.decompileContent
+                : SELECTOR.decompilePanel,
+        );
+    } else if (elementExists(SELECTOR.decompileTab)) {
         steps.push(
             makeClickToContinueStep({
                 boarding,
-                selector: SELECTOR.decompileButton,
-                waitForSelector: SELECTOR.decompilePanel,
-                title: "Open decompilation",
+                selector: SELECTOR.decompileTab,
+                waitForSelector: SELECTOR.decompileContent,
+                title: "Decompilation tab",
                 description:
-                    "Click <strong>Decompile</strong> to open the decompiler panel for this scratch.",
+                    "Click the <strong>Decompilation</strong> tab to show the decompiler output.",
             }),
         );
+        addDecompilationInfoStep(steps, SELECTOR.decompileContent);
+    } else if (elementExists(SELECTOR.decompileButton)) {
         steps.push(
-            makeStep(
-                SELECTOR.decompilePanel,
-                "Decompilation",
-                "When the platform supports it, this table will show the results of running a decompiler against the target assembly and contents of the scratch context.",
-            ),
+            makeClickToContinueStep({
+                boarding,
+                selector: SELECTOR.decompileButton,
+                waitForSelector: SELECTOR.decompileContent,
+                title: "Open decompilation panel",
+                description:
+                    "Click <strong>Decompile</strong> to open the decompilation panel for this scratch.",
+            }),
         );
+        addDecompilationInfoStep(steps, SELECTOR.decompileContent);
     }
 
     addIfPresent(
@@ -496,7 +535,7 @@ function buildTourSteps(boarding: Boarding): TourStep[] {
         makeStep(
             SELECTOR.tourButton,
             "More help",
-            'If you have more questions, the <a href="/faq">FAQ</a> is a good next stop, or feel free to join the <a href="https://discord.gg/sutqNShRRs" target="_blank" rel="noreferrer">decomp.me Discord server</a>, where people ask for help, share scratches, and discuss decompilation in a collaborative environment. <br /> You can start the tour again by clicking the <strong>Tour</strong> button.',
+            'If you have more questions, the <a href="/faq">FAQ</a> is a good next stop, or feel free to join the <a href="https://discord.gg/sutqNShRRs" target="_blank" rel="noreferrer">decomp.me Discord server</a>, where people ask for help, share scratches, and discuss decompilation in a collaborative environment. <br /><br />You can start the tour again by clicking the <strong>Tour</strong> button.',
         ),
     );
 
diff --git a/frontend/src/components/Scratch/panels/DecompilePanel.tsx b/frontend/src/components/Scratch/panels/DecompilePanel.tsx
index d4e64ef1f..b595aeb5f 100644
--- a/frontend/src/components/Scratch/panels/DecompilePanel.tsx
+++ b/frontend/src/components/Scratch/panels/DecompilePanel.tsx
@@ -51,7 +51,10 @@ export default function DecompilePanel({ scratch }: Props) {
 
     return (
         <div className={styles.container} data-tour="scratch-decompile-panel">
-            <section className={styles.main}>
+            <section
+                className={styles.main}
+                data-tour="scratch-decompile-content"
+            >
                 <p>
                     Modify the context or compiler to see how the decompilation
                     of the assembly changes.