From a41235bf6617feaff62483ef8ac1d00ed8c6efe9 Mon Sep 17 00:00:00 2001 From: Charles Vien Date: Tue, 14 Apr 2026 17:59:42 -0700 Subject: [PATCH 1/9] Product tours --- apps/code/.storybook/preview.tsx | 2 +- .../src/renderer/components/MainLayout.tsx | 14 + .../src/renderer/components/ThemeWrapper.tsx | 2 +- .../task-detail/components/TaskInput.tsx | 2 +- .../features/tour/components/TourOverlay.tsx | 74 ++++ .../features/tour/components/TourTooltip.tsx | 330 ++++++++++++++++++ .../features/tour/hooks/useElementRect.ts | 43 +++ .../renderer/features/tour/hooks/useTour.ts | 13 + .../features/tour/stores/tourStore.ts | 66 ++++ .../tour/tours/createFirstTaskTour.ts | 35 ++ .../features/tour/tours/tourRegistry.ts | 6 + apps/code/src/renderer/features/tour/types.ts | 17 + 12 files changed, 601 insertions(+), 3 deletions(-) create mode 100644 apps/code/src/renderer/features/tour/components/TourOverlay.tsx create mode 100644 apps/code/src/renderer/features/tour/components/TourTooltip.tsx create mode 100644 apps/code/src/renderer/features/tour/hooks/useElementRect.ts create mode 100644 apps/code/src/renderer/features/tour/hooks/useTour.ts create mode 100644 apps/code/src/renderer/features/tour/stores/tourStore.ts create mode 100644 apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts create mode 100644 apps/code/src/renderer/features/tour/tours/tourRegistry.ts create mode 100644 apps/code/src/renderer/features/tour/types.ts diff --git a/apps/code/.storybook/preview.tsx b/apps/code/.storybook/preview.tsx index 2e3787723..d53ba4046 100644 --- a/apps/code/.storybook/preview.tsx +++ b/apps/code/.storybook/preview.tsx @@ -30,7 +30,7 @@ const preview: Preview = { grayColor="slate" panelBackground="solid" radius="none" - scaling="105%" + scaling="100%" > diff --git a/apps/code/src/renderer/components/MainLayout.tsx b/apps/code/src/renderer/components/MainLayout.tsx index f49e76d66..b0bd6351e 100644 --- a/apps/code/src/renderer/components/MainLayout.tsx +++ b/apps/code/src/renderer/components/MainLayout.tsx @@ -14,6 +14,8 @@ import { SkillsView } from "@features/skills/components/SkillsView"; import { TaskDetail } from "@features/task-detail/components/TaskDetail"; import { TaskInput } from "@features/task-detail/components/TaskInput"; import { useTasks } from "@features/tasks/hooks/useTasks"; +import { TourOverlay } from "@features/tour/components/TourOverlay"; +import { useTourStore } from "@features/tour/stores/tourStore"; import { useConnectivity } from "@hooks/useConnectivity"; import { useIntegrations } from "@hooks/useIntegrations"; import { Box, Flex } from "@radix-ui/themes"; @@ -39,6 +41,11 @@ export function MainLayout() { const { data: tasks } = useTasks(); const { showPrompt, isChecking, check, dismiss } = useConnectivity(); + const startTour = useTourStore((s) => s.startTour); + const isFirstTaskTourDone = useTourStore((s) => + s.completedTourIds.includes("create-first-task"), + ); + useIntegrations(); useTaskDeepLink(); @@ -54,6 +61,12 @@ export function MainLayout() { } }, [view, navigateToTaskInput]); + useEffect(() => { + if (isFirstTaskTourDone) return; + const timer = setTimeout(() => startTour("create-first-task"), 600); + return () => clearTimeout(timer); + }, [isFirstTaskTourDone, startTour]); + const handleToggleCommandMenu = useCallback(() => { toggleCommandMenu(); }, [toggleCommandMenu]); @@ -99,6 +112,7 @@ export function MainLayout() { onToggleShortcutsSheet={toggleShortcutsSheet} /> + ); diff --git a/apps/code/src/renderer/components/ThemeWrapper.tsx b/apps/code/src/renderer/components/ThemeWrapper.tsx index 97dd6286d..bb3d6f72d 100644 --- a/apps/code/src/renderer/components/ThemeWrapper.tsx +++ b/apps/code/src/renderer/components/ThemeWrapper.tsx @@ -27,7 +27,7 @@ export function ThemeWrapper({ children }: { children: React.ReactNode }) { grayColor="slate" panelBackground="solid" radius="medium" - scaling="105%" + scaling="100%" > {children}
diff --git a/apps/code/src/renderer/features/task-detail/components/TaskInput.tsx b/apps/code/src/renderer/features/task-detail/components/TaskInput.tsx index 60bc232c4..f18c90c9d 100644 --- a/apps/code/src/renderer/features/task-detail/components/TaskInput.tsx +++ b/apps/code/src/renderer/features/task-detail/components/TaskInput.tsx @@ -443,7 +443,7 @@ export function TaskInput({ disabled={isCreatingTask} /> )} - + {workspaceMode === "cloud" ? ( s.activeTourId); + const activeStepIndex = useTourStore((s) => s.activeStepIndex); + const advance = useTourStore((s) => s.advance); + const dismiss = useTourStore((s) => s.dismiss); + + const tour = activeTourId ? TOUR_REGISTRY[activeTourId] : null; + const step = tour?.steps[activeStepIndex] ?? null; + + const selector = step ? `[data-tour="${step.target}"]` : null; + const targetRect = useElementRect(selector); + + const advancedRef = useRef(false); + + useEffect(() => { + advancedRef.current = false; + }, []); + + useEffect(() => { + if (!step || step.advanceOn.type !== "click" || !selector) return; + + const el = document.querySelector(selector); + if (!el) return; + + const handler = () => { + if (!advancedRef.current) { + advancedRef.current = true; + setTimeout(advance, 0); + } + }; + + el.addEventListener("click", handler, { capture: true }); + return () => el.removeEventListener("click", handler, { capture: true }); + }, [step, selector, advance]); + + useEffect(() => { + if (!step || step.advanceOn.type !== "action" || !selector) return; + + let frameId: number; + + const poll = () => { + const el = document.querySelector(selector); + if (el?.getAttribute("data-tour-ready") === "true") { + if (!advancedRef.current) { + advancedRef.current = true; + advance(); + } + return; + } + frameId = requestAnimationFrame(poll); + }; + + frameId = requestAnimationFrame(poll); + return () => cancelAnimationFrame(frameId); + }, [step, selector, advance]); + + if (!tour || !step || !targetRect) return null; + + return ( + + ); +} diff --git a/apps/code/src/renderer/features/tour/components/TourTooltip.tsx b/apps/code/src/renderer/features/tour/components/TourTooltip.tsx new file mode 100644 index 000000000..842673301 --- /dev/null +++ b/apps/code/src/renderer/features/tour/components/TourTooltip.tsx @@ -0,0 +1,330 @@ +import { Button, Flex, Text, Theme } from "@radix-ui/themes"; +import { useThemeStore } from "@stores/themeStore"; +import { AnimatePresence, motion, useAnimationControls } from "framer-motion"; +import { useCallback, useEffect, useMemo, useRef } from "react"; +import { createPortal } from "react-dom"; +import type { CaretDirection, TourStep } from "../types"; + +interface TourTooltipProps { + step: TourStep; + stepNumber: number; + totalSteps: number; + targetRect: DOMRect; + onDismiss: () => void; +} + +const TOOLTIP_GAP = 16; +const HOG_SIZE = 56; +const CARET_SIZE = 12; +const CARET_INNER = 11; + +const talkingAnimation = { + rotate: [0, -3, 3, -2, 2, 0], + y: [0, -2, 0, -1, 0], + transition: { + duration: 0.4, + repeat: Infinity, + repeatDelay: 0.1, + }, +}; + +function CaretPair({ direction }: { direction: CaretDirection }) { + const borderColor = "var(--gray-a5)"; + const fillColor = "var(--color-panel-solid)"; + + const base: React.CSSProperties = { + position: "absolute", + width: 0, + height: 0, + }; + + let borderStyle: React.CSSProperties; + let fillStyle: React.CSSProperties; + + switch (direction) { + case "left": + borderStyle = { + ...base, + top: "50%", + marginTop: -CARET_SIZE, + left: -CARET_SIZE, + borderTop: `${CARET_SIZE}px solid transparent`, + borderBottom: `${CARET_SIZE}px solid transparent`, + borderRight: `${CARET_SIZE}px solid ${borderColor}`, + }; + fillStyle = { + ...base, + top: "50%", + marginTop: -CARET_INNER, + left: -CARET_INNER, + borderTop: `${CARET_INNER}px solid transparent`, + borderBottom: `${CARET_INNER}px solid transparent`, + borderRight: `${CARET_INNER}px solid ${fillColor}`, + }; + break; + case "right": + borderStyle = { + ...base, + top: "50%", + marginTop: -CARET_SIZE, + right: -CARET_SIZE, + borderTop: `${CARET_SIZE}px solid transparent`, + borderBottom: `${CARET_SIZE}px solid transparent`, + borderLeft: `${CARET_SIZE}px solid ${borderColor}`, + }; + fillStyle = { + ...base, + top: "50%", + marginTop: -CARET_INNER, + right: -CARET_INNER, + borderTop: `${CARET_INNER}px solid transparent`, + borderBottom: `${CARET_INNER}px solid transparent`, + borderLeft: `${CARET_INNER}px solid ${fillColor}`, + }; + break; + case "top": + borderStyle = { + ...base, + top: -CARET_SIZE, + left: 32, + borderLeft: `${CARET_SIZE}px solid transparent`, + borderRight: `${CARET_SIZE}px solid transparent`, + borderBottom: `${CARET_SIZE}px solid ${borderColor}`, + }; + fillStyle = { + ...base, + top: -CARET_INNER, + left: 33, + borderLeft: `${CARET_INNER}px solid transparent`, + borderRight: `${CARET_INNER}px solid transparent`, + borderBottom: `${CARET_INNER}px solid ${fillColor}`, + }; + break; + case "bottom": + borderStyle = { + ...base, + bottom: -CARET_SIZE, + left: 32, + borderLeft: `${CARET_SIZE}px solid transparent`, + borderRight: `${CARET_SIZE}px solid transparent`, + borderTop: `${CARET_SIZE}px solid ${borderColor}`, + }; + fillStyle = { + ...base, + bottom: -CARET_INNER, + left: 33, + borderLeft: `${CARET_INNER}px solid transparent`, + borderRight: `${CARET_INNER}px solid transparent`, + borderTop: `${CARET_INNER}px solid ${fillColor}`, + }; + break; + } + + return ( + <> +
+
+ + ); +} + +const CARET_OFFSET = 32; + +function computePosition( + targetRect: DOMRect, + caretDirection: CaretDirection, +): { top: number; left: number } { + const centerX = targetRect.left + targetRect.width / 2; + const centerY = targetRect.top + targetRect.height / 2; + + switch (caretDirection) { + case "bottom": + return { + top: targetRect.top - TOOLTIP_GAP - CARET_SIZE, + left: centerX - CARET_OFFSET - CARET_SIZE, + }; + case "top": + return { + top: targetRect.bottom + TOOLTIP_GAP + CARET_SIZE, + left: centerX - CARET_OFFSET - CARET_SIZE, + }; + case "left": + return { + top: centerY, + left: targetRect.right + TOOLTIP_GAP + CARET_SIZE, + }; + case "right": + return { + top: centerY, + left: targetRect.left - TOOLTIP_GAP - CARET_SIZE, + }; + } +} + +function getTransform(caretDirection: CaretDirection): string { + switch (caretDirection) { + case "bottom": + return "translateY(-100%)"; + case "top": + return "translateY(0)"; + case "left": + return "translateY(-50%)"; + case "right": + return "translate(-100%, -50%)"; + } +} + +function getMotionProps(caretDirection: CaretDirection) { + const slide = 10; + switch (caretDirection) { + case "bottom": + return { + initial: { opacity: 0, y: slide }, + animate: { opacity: 1, y: 0 }, + }; + case "top": + return { + initial: { opacity: 0, y: -slide }, + animate: { opacity: 1, y: 0 }, + }; + case "left": + return { + initial: { opacity: 0, x: -slide }, + animate: { opacity: 1, x: 0 }, + }; + case "right": + return { + initial: { opacity: 0, x: slide }, + animate: { opacity: 1, x: 0 }, + }; + } +} + +export function TourTooltip({ + step, + stepNumber, + totalSteps, + targetRect, + onDismiss, +}: TourTooltipProps) { + const isDarkMode = useThemeStore((s) => s.isDarkMode); + const controls = useAnimationControls(); + const isHovering = useRef(false); + + useEffect(() => { + const startTimer = setTimeout(() => { + controls.start(talkingAnimation); + }, 500); + const stopTimer = setTimeout(() => { + if (!isHovering.current) { + controls.stop(); + controls.set({ rotate: 0, y: 0 }); + } + }, 5500); + return () => { + clearTimeout(startTimer); + clearTimeout(stopTimer); + }; + }, [controls]); + + const handleMouseEnter = useCallback(() => { + isHovering.current = true; + controls.start(talkingAnimation); + }, [controls]); + + const handleMouseLeave = useCallback(() => { + isHovering.current = false; + controls.stop(); + controls.set({ rotate: 0, y: 0 }); + }, [controls]); + + const pos = computePosition(targetRect, step.caretDirection); + const motionProps = getMotionProps(step.caretDirection); + + const anchorStyle = useMemo( + (): React.CSSProperties => ({ + position: "fixed", + zIndex: 200, + pointerEvents: "auto", + top: pos.top, + left: pos.left, + transform: getTransform(step.caretDirection), + }), + [pos.top, pos.left, step.caretDirection], + ); + + return createPortal( + + + +
+ + + + + + {step.message} + + + + {stepNumber}/{totalSteps} + + + + + +
+ + + , + document.body, + ); +} diff --git a/apps/code/src/renderer/features/tour/hooks/useElementRect.ts b/apps/code/src/renderer/features/tour/hooks/useElementRect.ts new file mode 100644 index 000000000..3b0e01a7b --- /dev/null +++ b/apps/code/src/renderer/features/tour/hooks/useElementRect.ts @@ -0,0 +1,43 @@ +import { useEffect, useState } from "react"; + +function rectsEqual(a: DOMRect | null, b: DOMRect | null): boolean { + if (a === b) return true; + if (!a || !b) return false; + return ( + Math.abs(a.top - b.top) < 1 && + Math.abs(a.left - b.left) < 1 && + Math.abs(a.width - b.width) < 1 && + Math.abs(a.height - b.height) < 1 + ); +} + +export function useElementRect(selector: string | null): DOMRect | null { + const [rect, setRect] = useState(null); + + useEffect(() => { + if (!selector) { + setRect(null); + return; + } + + let frameId: number; + let prevRect: DOMRect | null = null; + + const poll = () => { + const el = document.querySelector(selector); + const nextRect = el?.getBoundingClientRect() ?? null; + + if (!rectsEqual(nextRect, prevRect)) { + prevRect = nextRect; + setRect(nextRect ? DOMRect.fromRect(nextRect) : null); + } + + frameId = requestAnimationFrame(poll); + }; + + frameId = requestAnimationFrame(poll); + return () => cancelAnimationFrame(frameId); + }, [selector]); + + return rect; +} diff --git a/apps/code/src/renderer/features/tour/hooks/useTour.ts b/apps/code/src/renderer/features/tour/hooks/useTour.ts new file mode 100644 index 000000000..3f9a7e435 --- /dev/null +++ b/apps/code/src/renderer/features/tour/hooks/useTour.ts @@ -0,0 +1,13 @@ +import { useTourStore } from "../stores/tourStore"; + +export function useTour() { + const startTour = useTourStore((s) => s.startTour); + const dismiss = useTourStore((s) => s.dismiss); + const completedTourIds = useTourStore((s) => s.completedTourIds); + + return { + startTour, + dismiss, + isCompleted: (tourId: string) => completedTourIds.includes(tourId), + }; +} diff --git a/apps/code/src/renderer/features/tour/stores/tourStore.ts b/apps/code/src/renderer/features/tour/stores/tourStore.ts new file mode 100644 index 000000000..3698de6e6 --- /dev/null +++ b/apps/code/src/renderer/features/tour/stores/tourStore.ts @@ -0,0 +1,66 @@ +import { create } from "zustand"; +import { persist } from "zustand/middleware"; +import { TOUR_REGISTRY } from "../tours/tourRegistry"; + +interface TourStoreState { + completedTourIds: string[]; + activeTourId: string | null; + activeStepIndex: number; +} + +interface TourStoreActions { + startTour: (tourId: string) => void; + advance: () => void; + dismiss: () => void; +} + +type TourStore = TourStoreState & TourStoreActions; + +export const useTourStore = create()( + persist( + (set, get) => ({ + completedTourIds: [], + activeTourId: null, + activeStepIndex: 0, + + startTour: (tourId) => { + if (get().completedTourIds.includes(tourId)) return; + set({ activeTourId: tourId, activeStepIndex: 0 }); + }, + + advance: () => { + const { activeTourId, activeStepIndex } = get(); + if (!activeTourId) return; + + const tour = TOUR_REGISTRY[activeTourId]; + if (!tour) return; + + if (activeStepIndex >= tour.steps.length - 1) { + set((state) => ({ + completedTourIds: [...state.completedTourIds, activeTourId], + activeTourId: null, + activeStepIndex: 0, + })); + } else { + set({ activeStepIndex: activeStepIndex + 1 }); + } + }, + + dismiss: () => { + const { activeTourId } = get(); + if (!activeTourId) return; + set((state) => ({ + completedTourIds: [...state.completedTourIds, activeTourId], + activeTourId: null, + activeStepIndex: 0, + })); + }, + }), + { + name: "tour-store", + partialize: (state) => ({ + completedTourIds: state.completedTourIds, + }), + }, + ), +); diff --git a/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts b/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts new file mode 100644 index 000000000..cf845990a --- /dev/null +++ b/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts @@ -0,0 +1,35 @@ +import builderHog from "@renderer/assets/images/hedgehogs/builder-hog-03.png"; +import explorerHog from "@renderer/assets/images/hedgehogs/explorer-hog.png"; +import happyHog from "@renderer/assets/images/hedgehogs/happy-hog.png"; +import type { TourDefinition } from "../types"; + +export const createFirstTaskTour: TourDefinition = { + id: "create-first-task", + steps: [ + { + id: "folder-picker", + target: "folder-picker", + caretDirection: "bottom", + hogSrc: explorerHog, + message: "Pick a repo to work with. This tells me where your code lives!", + advanceOn: { type: "click" }, + }, + { + id: "task-editor", + target: "task-input-editor", + caretDirection: "bottom", + hogSrc: builderHog, + message: + "Describe what you want to build or fix. Be as specific as you like!", + advanceOn: { type: "action" }, + }, + { + id: "submit-button", + target: "submit-button", + caretDirection: "left", + hogSrc: happyHog, + message: "Hit send to launch your first task!", + advanceOn: { type: "click" }, + }, + ], +}; diff --git a/apps/code/src/renderer/features/tour/tours/tourRegistry.ts b/apps/code/src/renderer/features/tour/tours/tourRegistry.ts new file mode 100644 index 000000000..c5c4b0f94 --- /dev/null +++ b/apps/code/src/renderer/features/tour/tours/tourRegistry.ts @@ -0,0 +1,6 @@ +import type { TourDefinition } from "../types"; +import { createFirstTaskTour } from "./createFirstTaskTour"; + +export const TOUR_REGISTRY: Record = { + [createFirstTaskTour.id]: createFirstTaskTour, +}; diff --git a/apps/code/src/renderer/features/tour/types.ts b/apps/code/src/renderer/features/tour/types.ts new file mode 100644 index 000000000..687c06201 --- /dev/null +++ b/apps/code/src/renderer/features/tour/types.ts @@ -0,0 +1,17 @@ +export type CaretDirection = "top" | "right" | "bottom" | "left"; + +export type TourStepAdvance = { type: "action" } | { type: "click" }; + +export interface TourStep { + id: string; + target: string; + caretDirection: CaretDirection; + hogSrc: string; + message: string; + advanceOn: TourStepAdvance; +} + +export interface TourDefinition { + id: string; + steps: TourStep[]; +} From 2e3f4358ba798994354f97e83a5daebc5bf7a1c1 Mon Sep 17 00:00:00 2001 From: Charles Vien Date: Tue, 14 Apr 2026 18:20:54 -0700 Subject: [PATCH 2/9] Latest --- .../src/renderer/components/MainLayout.tsx | 7 +- .../components/sections/AdvancedSettings.tsx | 13 + .../task-detail/components/TaskInput.tsx | 10 +- .../features/tour/components/TourOverlay.tsx | 105 ++++- .../features/tour/components/TourTooltip.tsx | 380 ++++++------------ .../features/tour/stores/tourStore.ts | 5 + .../tour/tours/createFirstTaskTour.ts | 4 +- 7 files changed, 251 insertions(+), 273 deletions(-) diff --git a/apps/code/src/renderer/components/MainLayout.tsx b/apps/code/src/renderer/components/MainLayout.tsx index b0bd6351e..9e6c9f330 100644 --- a/apps/code/src/renderer/components/MainLayout.tsx +++ b/apps/code/src/renderer/components/MainLayout.tsx @@ -9,6 +9,7 @@ import { CommandCenterView } from "@features/command-center/components/CommandCe import { InboxView } from "@features/inbox/components/InboxView"; import { FolderSettingsView } from "@features/settings/components/FolderSettingsView"; import { SettingsDialog } from "@features/settings/components/SettingsDialog"; +import { useSettingsDialogStore } from "@features/settings/stores/settingsDialogStore"; import { MainSidebar } from "@features/sidebar/components/MainSidebar"; import { SkillsView } from "@features/skills/components/SkillsView"; import { TaskDetail } from "@features/task-detail/components/TaskDetail"; @@ -61,11 +62,13 @@ export function MainLayout() { } }, [view, navigateToTaskInput]); + const settingsOpen = useSettingsDialogStore((s) => s.isOpen); + useEffect(() => { - if (isFirstTaskTourDone) return; + if (isFirstTaskTourDone || settingsOpen) return; const timer = setTimeout(() => startTour("create-first-task"), 600); return () => clearTimeout(timer); - }, [isFirstTaskTourDone, startTour]); + }, [isFirstTaskTourDone, settingsOpen, startTour]); const handleToggleCommandMenu = useCallback(() => { toggleCommandMenu(); diff --git a/apps/code/src/renderer/features/settings/components/sections/AdvancedSettings.tsx b/apps/code/src/renderer/features/settings/components/sections/AdvancedSettings.tsx index 40c1d4d37..4544d6902 100644 --- a/apps/code/src/renderer/features/settings/components/sections/AdvancedSettings.tsx +++ b/apps/code/src/renderer/features/settings/components/sections/AdvancedSettings.tsx @@ -2,6 +2,7 @@ import { useOnboardingStore } from "@features/onboarding/stores/onboardingStore" import { SettingRow } from "@features/settings/components/SettingRow"; import { useSettingsDialogStore } from "@features/settings/stores/settingsDialogStore"; import { useSettingsStore } from "@features/settings/stores/settingsStore"; +import { useTourStore } from "@features/tour/stores/tourStore"; import { useFeatureFlag } from "@hooks/useFeatureFlag"; import { Button, Flex, Switch } from "@radix-ui/themes"; import { clearApplicationStorage } from "@utils/clearStorage"; @@ -31,6 +32,18 @@ export function AdvancedSettings() { Reset + + + )} - + {workspaceMode === "cloud" ? ( + {targetRect && ( + + )} + , + document.body, + ); +} + export function TourOverlay() { const activeTourId = useTourStore((s) => s.activeTourId); const activeStepIndex = useTourStore((s) => s.activeStepIndex); @@ -20,7 +57,7 @@ export function TourOverlay() { useEffect(() => { advancedRef.current = false; - }, []); + }, [activeStepIndex]); useEffect(() => { if (!step || step.advanceOn.type !== "click" || !selector) return; @@ -42,33 +79,63 @@ export function TourOverlay() { useEffect(() => { if (!step || step.advanceOn.type !== "action" || !selector) return; - let frameId: number; + const SETTLE_MS = 2000; + let settleTimer: ReturnType | null = null; - const poll = () => { + const tryAdvance = () => { + const el = document.querySelector(selector); + if ( + el?.getAttribute("data-tour-ready") === "true" && + !advancedRef.current + ) { + advancedRef.current = true; + advance(); + } + }; + + const resetTimer = () => { + if (settleTimer) clearTimeout(settleTimer); const el = document.querySelector(selector); if (el?.getAttribute("data-tour-ready") === "true") { - if (!advancedRef.current) { - advancedRef.current = true; - advance(); - } - return; + settleTimer = setTimeout(tryAdvance, SETTLE_MS); } - frameId = requestAnimationFrame(poll); }; - frameId = requestAnimationFrame(poll); - return () => cancelAnimationFrame(frameId); + const observer = new MutationObserver(resetTimer); + + const el = document.querySelector(selector); + if (el) { + observer.observe(el, { + subtree: true, + childList: true, + characterData: true, + attributes: true, + }); + resetTimer(); + } + + return () => { + observer.disconnect(); + if (settleTimer) clearTimeout(settleTimer); + }; }, [step, selector, advance]); - if (!tour || !step || !targetRect) return null; + const settingsOpen = useSettingsDialogStore((s) => s.isOpen); + const commandMenuOpen = useCommandMenuStore((s) => s.isOpen); + const overlayBlocked = settingsOpen || commandMenuOpen; + const isActive = !!(tour && step && targetRect && !overlayBlocked); return ( - + <> + + {isActive && ( + + )} + ); } diff --git a/apps/code/src/renderer/features/tour/components/TourTooltip.tsx b/apps/code/src/renderer/features/tour/components/TourTooltip.tsx index 842673301..b9920738a 100644 --- a/apps/code/src/renderer/features/tour/components/TourTooltip.tsx +++ b/apps/code/src/renderer/features/tour/components/TourTooltip.tsx @@ -1,20 +1,18 @@ import { Button, Flex, Text, Theme } from "@radix-ui/themes"; import { useThemeStore } from "@stores/themeStore"; import { AnimatePresence, motion, useAnimationControls } from "framer-motion"; -import { useCallback, useEffect, useMemo, useRef } from "react"; +import { useEffect } from "react"; import { createPortal } from "react-dom"; -import type { CaretDirection, TourStep } from "../types"; +import type { TourStep } from "../types"; interface TourTooltipProps { step: TourStep; stepNumber: number; totalSteps: number; - targetRect: DOMRect; onDismiss: () => void; } -const TOOLTIP_GAP = 16; -const HOG_SIZE = 56; +const HOG_SIZE = 64; const CARET_SIZE = 12; const CARET_INNER = 11; @@ -28,7 +26,42 @@ const talkingAnimation = { }, }; -function CaretPair({ direction }: { direction: CaretDirection }) { +const bubbleVariants = { + initial: { opacity: 0, scale: 0.92, x: 20 }, + animate: { + opacity: 1, + scale: 1, + x: 0, + transition: { type: "spring" as const, stiffness: 300, damping: 24 }, + }, + exit: { + opacity: 0, + scale: 0.95, + x: 10, + transition: { duration: 0.15 }, + }, +}; + +const hogEntranceVariants = { + initial: { opacity: 0, scale: 0.5 }, + animate: { + opacity: 1, + scale: 1, + transition: { + type: "spring" as const, + stiffness: 400, + damping: 18, + delay: 0.15, + }, + }, + exit: { + opacity: 0, + scale: 0.5, + transition: { duration: 0.1 }, + }, +}; + +function RightCaret() { const borderColor = "var(--gray-a5)"; const fillColor = "var(--color-panel-solid)"; @@ -38,221 +71,50 @@ function CaretPair({ direction }: { direction: CaretDirection }) { height: 0, }; - let borderStyle: React.CSSProperties; - let fillStyle: React.CSSProperties; - - switch (direction) { - case "left": - borderStyle = { - ...base, - top: "50%", - marginTop: -CARET_SIZE, - left: -CARET_SIZE, - borderTop: `${CARET_SIZE}px solid transparent`, - borderBottom: `${CARET_SIZE}px solid transparent`, - borderRight: `${CARET_SIZE}px solid ${borderColor}`, - }; - fillStyle = { - ...base, - top: "50%", - marginTop: -CARET_INNER, - left: -CARET_INNER, - borderTop: `${CARET_INNER}px solid transparent`, - borderBottom: `${CARET_INNER}px solid transparent`, - borderRight: `${CARET_INNER}px solid ${fillColor}`, - }; - break; - case "right": - borderStyle = { - ...base, - top: "50%", - marginTop: -CARET_SIZE, - right: -CARET_SIZE, - borderTop: `${CARET_SIZE}px solid transparent`, - borderBottom: `${CARET_SIZE}px solid transparent`, - borderLeft: `${CARET_SIZE}px solid ${borderColor}`, - }; - fillStyle = { - ...base, - top: "50%", - marginTop: -CARET_INNER, - right: -CARET_INNER, - borderTop: `${CARET_INNER}px solid transparent`, - borderBottom: `${CARET_INNER}px solid transparent`, - borderLeft: `${CARET_INNER}px solid ${fillColor}`, - }; - break; - case "top": - borderStyle = { - ...base, - top: -CARET_SIZE, - left: 32, - borderLeft: `${CARET_SIZE}px solid transparent`, - borderRight: `${CARET_SIZE}px solid transparent`, - borderBottom: `${CARET_SIZE}px solid ${borderColor}`, - }; - fillStyle = { - ...base, - top: -CARET_INNER, - left: 33, - borderLeft: `${CARET_INNER}px solid transparent`, - borderRight: `${CARET_INNER}px solid transparent`, - borderBottom: `${CARET_INNER}px solid ${fillColor}`, - }; - break; - case "bottom": - borderStyle = { - ...base, - bottom: -CARET_SIZE, - left: 32, - borderLeft: `${CARET_SIZE}px solid transparent`, - borderRight: `${CARET_SIZE}px solid transparent`, - borderTop: `${CARET_SIZE}px solid ${borderColor}`, - }; - fillStyle = { - ...base, - bottom: -CARET_INNER, - left: 33, - borderLeft: `${CARET_INNER}px solid transparent`, - borderRight: `${CARET_INNER}px solid transparent`, - borderTop: `${CARET_INNER}px solid ${fillColor}`, - }; - break; - } - return ( <> -
-
+
+
); } -const CARET_OFFSET = 32; - -function computePosition( - targetRect: DOMRect, - caretDirection: CaretDirection, -): { top: number; left: number } { - const centerX = targetRect.left + targetRect.width / 2; - const centerY = targetRect.top + targetRect.height / 2; - - switch (caretDirection) { - case "bottom": - return { - top: targetRect.top - TOOLTIP_GAP - CARET_SIZE, - left: centerX - CARET_OFFSET - CARET_SIZE, - }; - case "top": - return { - top: targetRect.bottom + TOOLTIP_GAP + CARET_SIZE, - left: centerX - CARET_OFFSET - CARET_SIZE, - }; - case "left": - return { - top: centerY, - left: targetRect.right + TOOLTIP_GAP + CARET_SIZE, - }; - case "right": - return { - top: centerY, - left: targetRect.left - TOOLTIP_GAP - CARET_SIZE, - }; - } -} - -function getTransform(caretDirection: CaretDirection): string { - switch (caretDirection) { - case "bottom": - return "translateY(-100%)"; - case "top": - return "translateY(0)"; - case "left": - return "translateY(-50%)"; - case "right": - return "translate(-100%, -50%)"; - } -} - -function getMotionProps(caretDirection: CaretDirection) { - const slide = 10; - switch (caretDirection) { - case "bottom": - return { - initial: { opacity: 0, y: slide }, - animate: { opacity: 1, y: 0 }, - }; - case "top": - return { - initial: { opacity: 0, y: -slide }, - animate: { opacity: 1, y: 0 }, - }; - case "left": - return { - initial: { opacity: 0, x: -slide }, - animate: { opacity: 1, x: 0 }, - }; - case "right": - return { - initial: { opacity: 0, x: slide }, - animate: { opacity: 1, x: 0 }, - }; - } -} - export function TourTooltip({ step, stepNumber, totalSteps, - targetRect, onDismiss, }: TourTooltipProps) { const isDarkMode = useThemeStore((s) => s.isDarkMode); const controls = useAnimationControls(); - const isHovering = useRef(false); useEffect(() => { - const startTimer = setTimeout(() => { + const timer = setTimeout(() => { controls.start(talkingAnimation); }, 500); - const stopTimer = setTimeout(() => { - if (!isHovering.current) { - controls.stop(); - controls.set({ rotate: 0, y: 0 }); - } - }, 5500); - return () => { - clearTimeout(startTimer); - clearTimeout(stopTimer); - }; - }, [controls]); - - const handleMouseEnter = useCallback(() => { - isHovering.current = true; - controls.start(talkingAnimation); - }, [controls]); - - const handleMouseLeave = useCallback(() => { - isHovering.current = false; - controls.stop(); - controls.set({ rotate: 0, y: 0 }); + return () => clearTimeout(timer); }, [controls]); - const pos = computePosition(targetRect, step.caretDirection); - const motionProps = getMotionProps(step.caretDirection); - - const anchorStyle = useMemo( - (): React.CSSProperties => ({ - position: "fixed", - zIndex: 200, - pointerEvents: "auto", - top: pos.top, - left: pos.left, - transform: getTransform(step.caretDirection), - }), - [pos.top, pos.left, step.caretDirection], - ); - return createPortal( - -
- - - - - - {step.message} + + + + {step.message} + + + + {stepNumber}/{totalSteps} - - - {stepNumber}/{totalSteps} - - - + -
- + + + + + +
, document.body, diff --git a/apps/code/src/renderer/features/tour/stores/tourStore.ts b/apps/code/src/renderer/features/tour/stores/tourStore.ts index 3698de6e6..901564af2 100644 --- a/apps/code/src/renderer/features/tour/stores/tourStore.ts +++ b/apps/code/src/renderer/features/tour/stores/tourStore.ts @@ -12,6 +12,7 @@ interface TourStoreActions { startTour: (tourId: string) => void; advance: () => void; dismiss: () => void; + resetTours: () => void; } type TourStore = TourStoreState & TourStoreActions; @@ -55,6 +56,10 @@ export const useTourStore = create()( activeStepIndex: 0, })); }, + + resetTours: () => { + set({ completedTourIds: [], activeTourId: null, activeStepIndex: 0 }); + }, }), { name: "tour-store", diff --git a/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts b/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts index cf845990a..c3dd54d28 100644 --- a/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts +++ b/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts @@ -12,7 +12,7 @@ export const createFirstTaskTour: TourDefinition = { caretDirection: "bottom", hogSrc: explorerHog, message: "Pick a repo to work with. This tells me where your code lives!", - advanceOn: { type: "click" }, + advanceOn: { type: "action" }, }, { id: "task-editor", @@ -28,7 +28,7 @@ export const createFirstTaskTour: TourDefinition = { target: "submit-button", caretDirection: "left", hogSrc: happyHog, - message: "Hit send to launch your first task!", + message: "Hit send or press Enter to launch your first task!", advanceOn: { type: "click" }, }, ], From da03a55f2687808de5927361b872d9b7c5cc6ef7 Mon Sep 17 00:00:00 2001 From: Charles Vien Date: Tue, 14 Apr 2026 18:22:44 -0700 Subject: [PATCH 3/9] lint --- .../renderer/features/task-detail/components/TaskInput.tsx | 6 +++++- .../src/renderer/features/tour/components/TourOverlay.tsx | 2 +- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/apps/code/src/renderer/features/task-detail/components/TaskInput.tsx b/apps/code/src/renderer/features/task-detail/components/TaskInput.tsx index 2584fb5c3..6fdc1eeda 100644 --- a/apps/code/src/renderer/features/task-detail/components/TaskInput.tsx +++ b/apps/code/src/renderer/features/task-detail/components/TaskInput.tsx @@ -447,7 +447,11 @@ export function TaskInput({ ref={buttonGroupRef} data-tour="folder-picker" data-tour-ready={ - (workspaceMode === "cloud" ? selectedRepository : selectedDirectory) + ( + workspaceMode === "cloud" + ? selectedRepository + : selectedDirectory + ) ? "true" : undefined } diff --git a/apps/code/src/renderer/features/tour/components/TourOverlay.tsx b/apps/code/src/renderer/features/tour/components/TourOverlay.tsx index 9e67ae8bc..1335ab36e 100644 --- a/apps/code/src/renderer/features/tour/components/TourOverlay.tsx +++ b/apps/code/src/renderer/features/tour/components/TourOverlay.tsx @@ -57,7 +57,7 @@ export function TourOverlay() { useEffect(() => { advancedRef.current = false; - }, [activeStepIndex]); + }, []); useEffect(() => { if (!step || step.advanceOn.type !== "click" || !selector) return; From 6e20a264c7fcb67ef6a9641d0dd867fddc99f4b8 Mon Sep 17 00:00:00 2001 From: Charles Vien Date: Tue, 14 Apr 2026 19:02:39 -0700 Subject: [PATCH 4/9] Fix tour completion on task creation and step transitions --- .../src/renderer/features/task-detail/hooks/useTaskCreation.ts | 2 ++ apps/code/src/renderer/features/tour/components/TourTooltip.tsx | 1 + .../src/renderer/features/tour/tours/createFirstTaskTour.ts | 2 +- 3 files changed, 4 insertions(+), 1 deletion(-) diff --git a/apps/code/src/renderer/features/task-detail/hooks/useTaskCreation.ts b/apps/code/src/renderer/features/task-detail/hooks/useTaskCreation.ts index c2d2c9baa..9ddbb4c2b 100644 --- a/apps/code/src/renderer/features/task-detail/hooks/useTaskCreation.ts +++ b/apps/code/src/renderer/features/task-detail/hooks/useTaskCreation.ts @@ -8,6 +8,7 @@ import { } from "@features/message-editor/utils/content"; import { useSettingsStore } from "@features/settings/stores/settingsStore"; import { useCreateTask } from "@features/tasks/hooks/useTasks"; +import { useTourStore } from "@features/tour/stores/tourStore"; import { useConnectivity } from "@hooks/useConnectivity"; import type { WorkspaceMode } from "@main/services/workspace/schemas"; import { get } from "@renderer/di/container"; @@ -170,6 +171,7 @@ export function useTaskCreation({ } else { navigateToTask(output.task); } + useTourStore.getState().advance(); editor.clear(); }); diff --git a/apps/code/src/renderer/features/tour/components/TourTooltip.tsx b/apps/code/src/renderer/features/tour/components/TourTooltip.tsx index b9920738a..02c298764 100644 --- a/apps/code/src/renderer/features/tour/components/TourTooltip.tsx +++ b/apps/code/src/renderer/features/tour/components/TourTooltip.tsx @@ -109,6 +109,7 @@ export function TourTooltip({ const controls = useAnimationControls(); useEffect(() => { + controls.stop(); const timer = setTimeout(() => { controls.start(talkingAnimation); }, 500); diff --git a/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts b/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts index c3dd54d28..7e98a6d89 100644 --- a/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts +++ b/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts @@ -28,7 +28,7 @@ export const createFirstTaskTour: TourDefinition = { target: "submit-button", caretDirection: "left", hogSrc: happyHog, - message: "Hit send or press Enter to launch your first task!", + message: "Hit send or press Enter to launch your first agent!", advanceOn: { type: "click" }, }, ], From 1c7326efe84de586d3d0410ab742bf8834222f3c Mon Sep 17 00:00:00 2001 From: Charles Vien Date: Tue, 14 Apr 2026 19:03:13 -0700 Subject: [PATCH 5/9] Suppress biome lint for intentional step-change deps --- .../code/src/renderer/features/tour/components/TourOverlay.tsx | 3 ++- .../code/src/renderer/features/tour/components/TourTooltip.tsx | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/apps/code/src/renderer/features/tour/components/TourOverlay.tsx b/apps/code/src/renderer/features/tour/components/TourOverlay.tsx index 1335ab36e..04463a16d 100644 --- a/apps/code/src/renderer/features/tour/components/TourOverlay.tsx +++ b/apps/code/src/renderer/features/tour/components/TourOverlay.tsx @@ -55,9 +55,10 @@ export function TourOverlay() { const advancedRef = useRef(false); + // biome-ignore lint/correctness/useExhaustiveDependencies: reset on step change useEffect(() => { advancedRef.current = false; - }, []); + }, [activeStepIndex]); useEffect(() => { if (!step || step.advanceOn.type !== "click" || !selector) return; diff --git a/apps/code/src/renderer/features/tour/components/TourTooltip.tsx b/apps/code/src/renderer/features/tour/components/TourTooltip.tsx index 02c298764..29394107e 100644 --- a/apps/code/src/renderer/features/tour/components/TourTooltip.tsx +++ b/apps/code/src/renderer/features/tour/components/TourTooltip.tsx @@ -108,13 +108,14 @@ export function TourTooltip({ const isDarkMode = useThemeStore((s) => s.isDarkMode); const controls = useAnimationControls(); + // biome-ignore lint/correctness/useExhaustiveDependencies: restart animation on step change useEffect(() => { controls.stop(); const timer = setTimeout(() => { controls.start(talkingAnimation); }, 500); return () => clearTimeout(timer); - }, [controls]); + }, [controls, step.id]); return createPortal( Date: Tue, 14 Apr 2026 19:12:33 -0700 Subject: [PATCH 6/9] Guard tour advance with expected tour and step IDs --- .../src/renderer/components/MainLayout.tsx | 5 +++-- .../task-detail/hooks/useTaskCreation.ts | 3 ++- .../features/tour/components/TourOverlay.tsx | 18 ++++++++++------ .../features/tour/stores/tourStore.ts | 21 ++++++++++++++++--- 4 files changed, 35 insertions(+), 12 deletions(-) diff --git a/apps/code/src/renderer/components/MainLayout.tsx b/apps/code/src/renderer/components/MainLayout.tsx index 9e6c9f330..b45f5fa56 100644 --- a/apps/code/src/renderer/components/MainLayout.tsx +++ b/apps/code/src/renderer/components/MainLayout.tsx @@ -17,6 +17,7 @@ import { TaskInput } from "@features/task-detail/components/TaskInput"; import { useTasks } from "@features/tasks/hooks/useTasks"; import { TourOverlay } from "@features/tour/components/TourOverlay"; import { useTourStore } from "@features/tour/stores/tourStore"; +import { createFirstTaskTour } from "@features/tour/tours/createFirstTaskTour"; import { useConnectivity } from "@hooks/useConnectivity"; import { useIntegrations } from "@hooks/useIntegrations"; import { Box, Flex } from "@radix-ui/themes"; @@ -44,7 +45,7 @@ export function MainLayout() { const startTour = useTourStore((s) => s.startTour); const isFirstTaskTourDone = useTourStore((s) => - s.completedTourIds.includes("create-first-task"), + s.completedTourIds.includes(createFirstTaskTour.id), ); useIntegrations(); @@ -66,7 +67,7 @@ export function MainLayout() { useEffect(() => { if (isFirstTaskTourDone || settingsOpen) return; - const timer = setTimeout(() => startTour("create-first-task"), 600); + const timer = setTimeout(() => startTour(createFirstTaskTour.id), 600); return () => clearTimeout(timer); }, [isFirstTaskTourDone, settingsOpen, startTour]); diff --git a/apps/code/src/renderer/features/task-detail/hooks/useTaskCreation.ts b/apps/code/src/renderer/features/task-detail/hooks/useTaskCreation.ts index 9ddbb4c2b..3fae7a2cd 100644 --- a/apps/code/src/renderer/features/task-detail/hooks/useTaskCreation.ts +++ b/apps/code/src/renderer/features/task-detail/hooks/useTaskCreation.ts @@ -9,6 +9,7 @@ import { import { useSettingsStore } from "@features/settings/stores/settingsStore"; import { useCreateTask } from "@features/tasks/hooks/useTasks"; import { useTourStore } from "@features/tour/stores/tourStore"; +import { createFirstTaskTour } from "@features/tour/tours/createFirstTaskTour"; import { useConnectivity } from "@hooks/useConnectivity"; import type { WorkspaceMode } from "@main/services/workspace/schemas"; import { get } from "@renderer/di/container"; @@ -171,7 +172,7 @@ export function useTaskCreation({ } else { navigateToTask(output.task); } - useTourStore.getState().advance(); + useTourStore.getState().completeTour(createFirstTaskTour.id); editor.clear(); }); diff --git a/apps/code/src/renderer/features/tour/components/TourOverlay.tsx b/apps/code/src/renderer/features/tour/components/TourOverlay.tsx index 04463a16d..315211528 100644 --- a/apps/code/src/renderer/features/tour/components/TourOverlay.tsx +++ b/apps/code/src/renderer/features/tour/components/TourOverlay.tsx @@ -61,25 +61,31 @@ export function TourOverlay() { }, [activeStepIndex]); useEffect(() => { - if (!step || step.advanceOn.type !== "click" || !selector) return; + if (!step || !activeTourId || step.advanceOn.type !== "click" || !selector) + return; const el = document.querySelector(selector); if (!el) return; + const tourId = activeTourId; + const stepId = step.id; const handler = () => { if (!advancedRef.current) { advancedRef.current = true; - setTimeout(advance, 0); + setTimeout(() => advance(tourId, stepId), 0); } }; el.addEventListener("click", handler, { capture: true }); return () => el.removeEventListener("click", handler, { capture: true }); - }, [step, selector, advance]); + }, [step, selector, advance, activeTourId]); useEffect(() => { - if (!step || step.advanceOn.type !== "action" || !selector) return; + if (!step || !activeTourId || step.advanceOn.type !== "action" || !selector) + return; + const tourId = activeTourId; + const stepId = step.id; const SETTLE_MS = 2000; let settleTimer: ReturnType | null = null; @@ -90,7 +96,7 @@ export function TourOverlay() { !advancedRef.current ) { advancedRef.current = true; - advance(); + advance(tourId, stepId); } }; @@ -119,7 +125,7 @@ export function TourOverlay() { observer.disconnect(); if (settleTimer) clearTimeout(settleTimer); }; - }, [step, selector, advance]); + }, [step, selector, advance, activeTourId]); const settingsOpen = useSettingsDialogStore((s) => s.isOpen); const commandMenuOpen = useCommandMenuStore((s) => s.isOpen); diff --git a/apps/code/src/renderer/features/tour/stores/tourStore.ts b/apps/code/src/renderer/features/tour/stores/tourStore.ts index 901564af2..d6292d591 100644 --- a/apps/code/src/renderer/features/tour/stores/tourStore.ts +++ b/apps/code/src/renderer/features/tour/stores/tourStore.ts @@ -10,7 +10,8 @@ interface TourStoreState { interface TourStoreActions { startTour: (tourId: string) => void; - advance: () => void; + advance: (tourId: string, stepId: string) => void; + completeTour: (tourId: string) => void; dismiss: () => void; resetTours: () => void; } @@ -29,13 +30,16 @@ export const useTourStore = create()( set({ activeTourId: tourId, activeStepIndex: 0 }); }, - advance: () => { + advance: (tourId, stepId) => { const { activeTourId, activeStepIndex } = get(); - if (!activeTourId) return; + if (activeTourId !== tourId) return; const tour = TOUR_REGISTRY[activeTourId]; if (!tour) return; + const currentStep = tour.steps[activeStepIndex]; + if (!currentStep || currentStep.id !== stepId) return; + if (activeStepIndex >= tour.steps.length - 1) { set((state) => ({ completedTourIds: [...state.completedTourIds, activeTourId], @@ -47,6 +51,17 @@ export const useTourStore = create()( } }, + completeTour: (tourId) => { + const { activeTourId, completedTourIds } = get(); + if (activeTourId !== tourId) return; + if (completedTourIds.includes(tourId)) return; + set({ + completedTourIds: [...completedTourIds, tourId], + activeTourId: null, + activeStepIndex: 0, + }); + }, + dismiss: () => { const { activeTourId } = get(); if (!activeTourId) return; From 04dc2dd0b2a62459ce4ce647fb4775908890f206 Mon Sep 17 00:00:00 2001 From: Charles Vien Date: Tue, 14 Apr 2026 22:37:46 -0700 Subject: [PATCH 7/9] Remove unused caretDirection from tour types --- .../src/renderer/features/tour/tours/createFirstTaskTour.ts | 6 +++--- apps/code/src/renderer/features/tour/types.ts | 3 --- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts b/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts index 7e98a6d89..aed17c5ad 100644 --- a/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts +++ b/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts @@ -9,7 +9,7 @@ export const createFirstTaskTour: TourDefinition = { { id: "folder-picker", target: "folder-picker", - caretDirection: "bottom", + hogSrc: explorerHog, message: "Pick a repo to work with. This tells me where your code lives!", advanceOn: { type: "action" }, @@ -17,7 +17,7 @@ export const createFirstTaskTour: TourDefinition = { { id: "task-editor", target: "task-input-editor", - caretDirection: "bottom", + hogSrc: builderHog, message: "Describe what you want to build or fix. Be as specific as you like!", @@ -26,7 +26,7 @@ export const createFirstTaskTour: TourDefinition = { { id: "submit-button", target: "submit-button", - caretDirection: "left", + hogSrc: happyHog, message: "Hit send or press Enter to launch your first agent!", advanceOn: { type: "click" }, diff --git a/apps/code/src/renderer/features/tour/types.ts b/apps/code/src/renderer/features/tour/types.ts index 687c06201..0ba139ccb 100644 --- a/apps/code/src/renderer/features/tour/types.ts +++ b/apps/code/src/renderer/features/tour/types.ts @@ -1,11 +1,8 @@ -export type CaretDirection = "top" | "right" | "bottom" | "left"; - export type TourStepAdvance = { type: "action" } | { type: "click" }; export interface TourStep { id: string; target: string; - caretDirection: CaretDirection; hogSrc: string; message: string; advanceOn: TourStepAdvance; From 672b3800ae9e40fdff6e2dfe70d6fd1ac354f095 Mon Sep 17 00:00:00 2001 From: Charles Vien Date: Fri, 17 Apr 2026 14:37:19 -0700 Subject: [PATCH 8/9] Update tourStore.ts --- .../features/tour/stores/tourStore.ts | 20 +++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/apps/code/src/renderer/features/tour/stores/tourStore.ts b/apps/code/src/renderer/features/tour/stores/tourStore.ts index d6292d591..ca96e9aa3 100644 --- a/apps/code/src/renderer/features/tour/stores/tourStore.ts +++ b/apps/code/src/renderer/features/tour/stores/tourStore.ts @@ -26,7 +26,9 @@ export const useTourStore = create()( activeStepIndex: 0, startTour: (tourId) => { - if (get().completedTourIds.includes(tourId)) return; + const { completedTourIds, activeTourId } = get(); + if (completedTourIds.includes(tourId) || activeTourId === tourId) + return; set({ activeTourId: tourId, activeStepIndex: 0 }); }, @@ -41,19 +43,21 @@ export const useTourStore = create()( if (!currentStep || currentStep.id !== stepId) return; if (activeStepIndex >= tour.steps.length - 1) { - set((state) => ({ - completedTourIds: [...state.completedTourIds, activeTourId], - activeTourId: null, - activeStepIndex: 0, - })); + set((state) => { + if (!state.activeTourId) return state; + return { + completedTourIds: [...state.completedTourIds, state.activeTourId], + activeTourId: null, + activeStepIndex: 0, + }; + }); } else { set({ activeStepIndex: activeStepIndex + 1 }); } }, completeTour: (tourId) => { - const { activeTourId, completedTourIds } = get(); - if (activeTourId !== tourId) return; + const { completedTourIds } = get(); if (completedTourIds.includes(tourId)) return; set({ completedTourIds: [...completedTourIds, tourId], From 4f0e9d24163d401de894c892ac456cb1275b641d Mon Sep 17 00:00:00 2001 From: Charles Vien Date: Mon, 20 Apr 2026 10:19:53 -0700 Subject: [PATCH 9/9] Position tour tooltip relative to target element --- .../features/tour/components/TourOverlay.tsx | 1 + .../features/tour/components/TourTooltip.tsx | 276 +++++++++++++----- .../tour/tours/createFirstTaskTour.ts | 3 - apps/code/src/renderer/features/tour/types.ts | 3 + .../tour/utils/calculateTooltipPlacement.ts | 115 ++++++++ 5 files changed, 328 insertions(+), 70 deletions(-) create mode 100644 apps/code/src/renderer/features/tour/utils/calculateTooltipPlacement.ts diff --git a/apps/code/src/renderer/features/tour/components/TourOverlay.tsx b/apps/code/src/renderer/features/tour/components/TourOverlay.tsx index 315211528..900391748 100644 --- a/apps/code/src/renderer/features/tour/components/TourOverlay.tsx +++ b/apps/code/src/renderer/features/tour/components/TourOverlay.tsx @@ -141,6 +141,7 @@ export function TourOverlay() { stepNumber={activeStepIndex + 1} totalSteps={tour.steps.length} onDismiss={dismiss} + targetRect={targetRect} /> )} diff --git a/apps/code/src/renderer/features/tour/components/TourTooltip.tsx b/apps/code/src/renderer/features/tour/components/TourTooltip.tsx index 29394107e..562ebb3b3 100644 --- a/apps/code/src/renderer/features/tour/components/TourTooltip.tsx +++ b/apps/code/src/renderer/features/tour/components/TourTooltip.tsx @@ -3,16 +3,23 @@ import { useThemeStore } from "@stores/themeStore"; import { AnimatePresence, motion, useAnimationControls } from "framer-motion"; import { useEffect } from "react"; import { createPortal } from "react-dom"; -import type { TourStep } from "../types"; +import type { TooltipPlacement, TourStep } from "../types"; +import { calculateTooltipPlacement } from "../utils/calculateTooltipPlacement"; interface TourTooltipProps { step: TourStep; stepNumber: number; totalSteps: number; onDismiss: () => void; + targetRect: DOMRect; } const HOG_SIZE = 64; +const HOG_GAP = 8; +const BUBBLE_MAX_WIDTH = 280; +const TOOLTIP_WIDTH_ESTIMATE = BUBBLE_MAX_WIDTH + HOG_GAP + HOG_SIZE; +const TOOLTIP_HEIGHT_ESTIMATE = 100; + const CARET_SIZE = 12; const CARET_INNER = 11; @@ -26,22 +33,6 @@ const talkingAnimation = { }, }; -const bubbleVariants = { - initial: { opacity: 0, scale: 0.92, x: 20 }, - animate: { - opacity: 1, - scale: 1, - x: 0, - transition: { type: "spring" as const, stiffness: 300, damping: 24 }, - }, - exit: { - opacity: 0, - scale: 0.95, - x: 10, - transition: { duration: 0.15 }, - }, -}; - const hogEntranceVariants = { initial: { opacity: 0, scale: 0.5 }, animate: { @@ -61,7 +52,53 @@ const hogEntranceVariants = { }, }; -function RightCaret() { +const CARET_SIDE_MAP: Record< + TooltipPlacement, + "left" | "right" | "top" | "bottom" +> = { + right: "left", + left: "right", + bottom: "top", + top: "bottom", +}; + +const TRANSFORM_ORIGIN_MAP: Record = { + right: "left center", + left: "right center", + bottom: "top center", + top: "bottom center", +}; + +function getBubbleVariants(placement: TooltipPlacement) { + const dx = placement === "right" ? 12 : placement === "left" ? -12 : 0; + const dy = placement === "bottom" ? -12 : placement === "top" ? 12 : 0; + + return { + initial: { opacity: 0, scale: 0.92, x: dx, y: dy }, + animate: { + opacity: 1, + scale: 1, + x: 0, + y: 0, + transition: { type: "spring" as const, stiffness: 300, damping: 24 }, + }, + exit: { + opacity: 0, + scale: 0.95, + x: dx * 0.5, + y: dy * 0.5, + transition: { duration: 0.15 }, + }, + }; +} + +function Caret({ + side, + offset = 0, +}: { + side: "left" | "right" | "top" | "bottom"; + offset?: number; +}) { const borderColor = "var(--gray-a5)"; const fillColor = "var(--color-panel-solid)"; @@ -71,32 +108,116 @@ function RightCaret() { height: 0, }; - return ( - <> -
-
- - ); + switch (side) { + case "right": + return ( + <> +
+
+ + ); + case "left": + return ( + <> +
+
+ + ); + case "top": + return ( + <> +
+
+ + ); + case "bottom": + return ( + <> +
+
+ + ); + } } export function TourTooltip({ @@ -104,10 +225,22 @@ export function TourTooltip({ stepNumber, totalSteps, onDismiss, + targetRect, }: TourTooltipProps) { const isDarkMode = useThemeStore((s) => s.isDarkMode); const controls = useAnimationControls(); + const { placement, x, y, arrowOffset } = calculateTooltipPlacement( + targetRect, + TOOLTIP_WIDTH_ESTIMATE, + TOOLTIP_HEIGHT_ESTIMATE, + step.preferredPlacement, + ); + + const caretSide = CARET_SIDE_MAP[placement]; + const hogOnRight = true; + const bubbleVariants = getBubbleVariants(placement); + // biome-ignore lint/correctness/useExhaustiveDependencies: restart animation on step change useEffect(() => { controls.stop(); @@ -117,6 +250,30 @@ export function TourTooltip({ return () => clearTimeout(timer); }, [controls, step.id]); + const hogElement = ( + + + + ); + return createPortal( + {!hogOnRight && hogElement} + - + - - - + {hogOnRight && hogElement}
, diff --git a/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts b/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts index aed17c5ad..9305ee45b 100644 --- a/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts +++ b/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts @@ -9,7 +9,6 @@ export const createFirstTaskTour: TourDefinition = { { id: "folder-picker", target: "folder-picker", - hogSrc: explorerHog, message: "Pick a repo to work with. This tells me where your code lives!", advanceOn: { type: "action" }, @@ -17,7 +16,6 @@ export const createFirstTaskTour: TourDefinition = { { id: "task-editor", target: "task-input-editor", - hogSrc: builderHog, message: "Describe what you want to build or fix. Be as specific as you like!", @@ -26,7 +24,6 @@ export const createFirstTaskTour: TourDefinition = { { id: "submit-button", target: "submit-button", - hogSrc: happyHog, message: "Hit send or press Enter to launch your first agent!", advanceOn: { type: "click" }, diff --git a/apps/code/src/renderer/features/tour/types.ts b/apps/code/src/renderer/features/tour/types.ts index 0ba139ccb..939653ba7 100644 --- a/apps/code/src/renderer/features/tour/types.ts +++ b/apps/code/src/renderer/features/tour/types.ts @@ -1,11 +1,14 @@ export type TourStepAdvance = { type: "action" } | { type: "click" }; +export type TooltipPlacement = "right" | "left" | "top" | "bottom"; + export interface TourStep { id: string; target: string; hogSrc: string; message: string; advanceOn: TourStepAdvance; + preferredPlacement?: TooltipPlacement; } export interface TourDefinition { diff --git a/apps/code/src/renderer/features/tour/utils/calculateTooltipPlacement.ts b/apps/code/src/renderer/features/tour/utils/calculateTooltipPlacement.ts new file mode 100644 index 000000000..b7417f9b7 --- /dev/null +++ b/apps/code/src/renderer/features/tour/utils/calculateTooltipPlacement.ts @@ -0,0 +1,115 @@ +import type { TooltipPlacement } from "../types"; + +const TOOLTIP_MARGIN = 12; +const VIEWPORT_PADDING = 8; + +const DEFAULT_ORDER: TooltipPlacement[] = ["right", "left", "top", "bottom"]; + +export interface PlacedTooltip { + placement: TooltipPlacement; + x: number; + y: number; + arrowOffset: number; +} + +function clamp(value: number, min: number, max: number): number { + return Math.max(min, Math.min(max, value)); +} + +export function calculateTooltipPlacement( + targetRect: DOMRect, + tooltipWidth: number, + tooltipHeight: number, + preferred?: TooltipPlacement, +): PlacedTooltip { + const vw = window.innerWidth; + const vh = window.innerHeight; + + const spaceRight = vw - targetRect.right; + const spaceLeft = targetRect.left; + const spaceAbove = targetRect.top; + + const targetCenterX = targetRect.left + targetRect.width / 2; + const targetCenterY = targetRect.top + targetRect.height / 2; + + const order = preferred + ? [preferred, ...DEFAULT_ORDER.filter((p) => p !== preferred)] + : DEFAULT_ORDER; + + for (const placement of order) { + switch (placement) { + case "right": { + if (spaceRight < tooltipWidth + TOOLTIP_MARGIN) break; + const idealY = targetCenterY - tooltipHeight / 2; + const y = clamp( + idealY, + VIEWPORT_PADDING, + vh - VIEWPORT_PADDING - tooltipHeight, + ); + return { + placement, + x: targetRect.right + TOOLTIP_MARGIN, + y, + arrowOffset: idealY - y, + }; + } + case "left": { + if (spaceLeft < tooltipWidth + TOOLTIP_MARGIN) break; + const idealY = targetCenterY - tooltipHeight / 2; + const y = clamp( + idealY, + VIEWPORT_PADDING, + vh - VIEWPORT_PADDING - tooltipHeight, + ); + return { + placement, + x: targetRect.left - TOOLTIP_MARGIN - tooltipWidth, + y, + arrowOffset: idealY - y, + }; + } + case "top": { + if (spaceAbove < tooltipHeight + TOOLTIP_MARGIN) break; + const idealX = targetCenterX - tooltipWidth / 2; + const x = clamp( + idealX, + VIEWPORT_PADDING, + vw - VIEWPORT_PADDING - tooltipWidth, + ); + return { + placement, + x, + y: targetRect.top - TOOLTIP_MARGIN - tooltipHeight, + arrowOffset: idealX - x, + }; + } + case "bottom": { + const idealX = targetCenterX - tooltipWidth / 2; + const x = clamp( + idealX, + VIEWPORT_PADDING, + vw - VIEWPORT_PADDING - tooltipWidth, + ); + return { + placement, + x, + y: targetRect.bottom + TOOLTIP_MARGIN, + arrowOffset: idealX - x, + }; + } + } + } + + const idealX = targetCenterX - tooltipWidth / 2; + const x = clamp( + idealX, + VIEWPORT_PADDING, + vw - VIEWPORT_PADDING - tooltipWidth, + ); + return { + placement: "bottom", + x, + y: targetRect.bottom + TOOLTIP_MARGIN, + arrowOffset: idealX - x, + }; +}