From 5dc20eb319e7a16886ad21093e1c790f6072e807 Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Tue, 18 Aug 2026 20:31:59 -0500 Subject: [PATCH 01/11] build(desktop): add driver.js for guided tours Pure-ESM, MIT, ~5KB gzipped, no runtime deps. Excluded from optimizeDeps: it only enters the graph through a dynamic import, so letting the scanner discover it at first use prebundles the ?raw IIFE as a module (breaking the raw-text transform) and forces a mid-session page reload. --- apps/desktop/package.json | 1 + apps/desktop/vite.config.ts | 25 +++++++++++++++++++++++++ package-lock.json | 7 +++++++ 3 files changed, 33 insertions(+) diff --git a/apps/desktop/package.json b/apps/desktop/package.json index 0c4dbf30cd..300c4582ab 100644 --- a/apps/desktop/package.json +++ b/apps/desktop/package.json @@ -120,6 +120,7 @@ "d3-force": "3.0.0", "dnd-core": "14.0.1", "dompurify": "3.4.13", + "driver.js": "1.8.0", "emojibase-data": "16.0.3", "fflate": "0.8.3", "frimousse": "0.3.0", diff --git a/apps/desktop/vite.config.ts b/apps/desktop/vite.config.ts index 46d5bea536..7627a62c47 100644 --- a/apps/desktop/vite.config.ts +++ b/apps/desktop/vite.config.ts @@ -155,6 +155,17 @@ export default defineConfig(({ command }) => ({ } } }, + // driver.js only enters the graph through the tour's DYNAMIC import chain + // (lib/tour/run-tour.ts), so the dep scanner never sees it at startup. Left + // alone, first use registers it as a missing dep at runtime — which (a) + // esbuild-prebundles the `?raw` IIFE import as a JS module, breaking the + // raw-text transform ("does not provide an export named 'default'"), and + // (b) triggers Vite's "new dependencies optimized" full page reload mid- + // session. It's pure ESM with no CJS deps, so serving it unoptimized is + // free. Query and bare forms all listed — exclusion matches exact ids. + optimizeDeps: { + exclude: ['driver.js', 'driver.js/dist/driver.js.iife.js', 'driver.js/dist/driver.js.iife.js?raw', 'driver.js/dist/driver.css?raw'] + }, resolve: { alias: { '@/debug/dev-only': debugEntry(command, process.env as Record), @@ -162,6 +173,20 @@ export default defineConfig(({ command }) => ({ '@hermes/plugin-sdk': path.resolve(__dirname, './src/sdk/index.ts'), '@hermes/shared/billing': path.resolve(__dirname, '../shared/src/billing-types.ts'), '@hermes/shared': path.resolve(__dirname, '../shared/src'), + // The tour tool's preview surface injects driver.js's prebuilt IIFE into + // the pane's guest page as raw source; the package's exports map doesn't + // expose that dist file (nor ./package.json), so resolve the main entry + // (dist/driver.js.cjs) and point at its sibling. Both keys on purpose: + // alias matching is exact, and the id reaches it with the `?raw` query + // still attached in dev but stripped in some build paths. + 'driver.js/dist/driver.js.iife.js?raw': `${path.join( + path.dirname(requireFromApp.resolve('driver.js')), + 'driver.js.iife.js' + )}?raw`, + 'driver.js/dist/driver.js.iife.js': path.join( + path.dirname(requireFromApp.resolve('driver.js')), + 'driver.js.iife.js' + ), react: reactDir, 'react-dom': reactDomDir, 'react/jsx-dev-runtime': path.join(reactDir, 'jsx-dev-runtime.js'), diff --git a/package-lock.json b/package-lock.json index 4b79b63afe..507d5ee0b7 100644 --- a/package-lock.json +++ b/package-lock.json @@ -106,6 +106,7 @@ "d3-force": "3.0.0", "dnd-core": "14.0.1", "dompurify": "3.4.13", + "driver.js": "1.8.0", "emojibase-data": "16.0.3", "fflate": "0.8.3", "frimousse": "0.3.0", @@ -9573,6 +9574,12 @@ "url": "https://dotenvx.com" } }, + "node_modules/driver.js": { + "version": "1.8.0", + "resolved": "https://registry.npmjs.org/driver.js/-/driver.js-1.8.0.tgz", + "integrity": "sha512-+8/IO7h1v14IzWh2GP60N7T3PFZweXwdn5e5POuxRSBoCYUojsBxzqawPeXh3YZIibRy7EehYNEyxe7slwwtdg==", + "license": "MIT" + }, "node_modules/dunder-proto": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz", From 018176915b28aa6a8555864e15472c12481da012 Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Tue, 18 Aug 2026 20:32:07 -0500 Subject: [PATCH 02/11] =?UTF-8?q?feat(desktop):=20tour=20engine=20?= =?UTF-8?q?=E2=80=94=20highlight=20and=20narrate=20any=20DOM?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A surface-agnostic walkthrough engine plus the API that drives it. collectTourTargets scans any document for addressable elements and marks each selector stable (identity-based, survives a re-render) or positional; runTourEngine turns one action into a driver.js highlight, a multi-step tour, or a step change. Both are written self-contained — no imports, no closures — so the same source runs in the renderer and, stringified, inside a webview guest page. Popovers are repainted from the app's own theme tokens, so tours follow every theme and custom skin. The named verbs (startTour, showTourStep, nextTourStep, …) are the public API: the agent tool is one caller, and a feature can ship its own curated tour through the same entry. --- apps/desktop/src/lib/tour/app-tour.css | 72 ++++++ apps/desktop/src/lib/tour/collect-targets.ts | 159 ++++++++++++++ apps/desktop/src/lib/tour/engine.test.ts | 217 +++++++++++++++++++ apps/desktop/src/lib/tour/engine.ts | 182 ++++++++++++++++ apps/desktop/src/lib/tour/index.ts | 34 +++ apps/desktop/src/lib/tour/run-tour.ts | 59 +++++ 6 files changed, 723 insertions(+) create mode 100644 apps/desktop/src/lib/tour/app-tour.css create mode 100644 apps/desktop/src/lib/tour/collect-targets.ts create mode 100644 apps/desktop/src/lib/tour/engine.test.ts create mode 100644 apps/desktop/src/lib/tour/engine.ts create mode 100644 apps/desktop/src/lib/tour/index.ts create mode 100644 apps/desktop/src/lib/tour/run-tour.ts diff --git a/apps/desktop/src/lib/tour/app-tour.css b/apps/desktop/src/lib/tour/app-tour.css new file mode 100644 index 0000000000..84cd7dd35b --- /dev/null +++ b/apps/desktop/src/lib/tour/app-tour.css @@ -0,0 +1,72 @@ +/* Theme bridge for the APP surface's tour popovers: driver.js ships a fixed + light palette, so repaint it with the app's own tokens and it follows every + theme (including custom skins) for free. Scoped to driver.js's classes. + + The preview surface keeps the stock look on purpose — it renders inside a + guest page where these variables don't exist. */ + +.driver-popover { + background-color: var(--color-popover); + border: 1px solid var(--color-border); + border-radius: var(--radius-md); + box-shadow: var(--shadow-nous); + color: var(--color-popover-foreground); + font-family: var(--font-sans); +} + +.driver-popover-title { + font-size: 0.875rem; + font-weight: 600; + line-height: 1.4; +} + +.driver-popover-description { + color: var(--color-muted-foreground); + font-size: 0.8125rem; +} + +.driver-popover-progress-text { + color: var(--color-muted-foreground); + font-size: 0.75rem; +} + +.driver-popover-close-btn { + color: var(--color-muted-foreground); +} + +.driver-popover-close-btn:hover, +.driver-popover-close-btn:focus { + color: var(--color-foreground); +} + +.driver-popover-footer-btn { + background-color: var(--color-secondary); + border-color: var(--color-border); + border-radius: var(--radius-sm); + color: var(--color-secondary-foreground); + font-family: var(--font-sans); + text-shadow: none; +} + +.driver-popover-footer-btn:hover, +.driver-popover-footer-btn:focus { + background-color: var(--color-accent); + color: var(--color-accent-foreground); +} + +/* Each arrow variant paints exactly one border edge; the rest are transparent. */ +.driver-popover-arrow-side-left { + border-left-color: var(--color-popover); +} + +.driver-popover-arrow-side-right { + border-right-color: var(--color-popover); +} + +.driver-popover-arrow-side-top { + border-top-color: var(--color-popover); +} + +.driver-popover-arrow-side-bottom { + border-bottom-color: var(--color-popover); +} diff --git a/apps/desktop/src/lib/tour/collect-targets.ts b/apps/desktop/src/lib/tour/collect-targets.ts new file mode 100644 index 0000000000..2a7ad83c28 --- /dev/null +++ b/apps/desktop/src/lib/tour/collect-targets.ts @@ -0,0 +1,159 @@ +/** + * TOUR TARGET COLLECTOR — discovers what a tour can point at. + * + * Fully generic: works on ANY document (the Hermes app's own DOM or an + * arbitrary page in the preview webview) by scanning for the things that make + * an element addressable — explicit `data-tour` markers first, then the + * standard affordances (aria-labels, roles, headings, labelled interactive + * elements). Each target carries a CSS selector, a human label, and whether + * that selector is STABLE (an identity attribute that survives a re-render) or + * merely positional, so a caller can prefer the durable ones. + * + * Injected into preview webviews as source (`collectTourTargets.toString()`), + * so it must stay self-contained: no imports, no closures, no renderer + * globals. Types erase at compile time. + */ + +export interface TourTarget { + /** Human-readable label (aria-label, text content, alt, title …). */ + label: string + /** Viewport rect, rounded: [x, y, width, height]. */ + rect: [number, number, number, number] + /** Element role: explicit ARIA role or the tag name. */ + role: string + /** A CSS selector that uniquely matches this element right now. */ + selector: string + /** True when the selector keys off identity (data-tour, id, data-testid, + * aria-label) rather than DOM position — i.e. it survives a re-render. */ + stable: boolean +} + +/** Scan `doc` for tourable elements (capped at `max`). Self-contained. */ +export function collectTourTargets(doc: Document, max: number): TourTarget[] { + const results: TourTarget[] = [] + const seen = new Set() + + const cssEscape = (value: string) => + typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(value) : value.replace(/["\\]/g, '\\$&') + + const labelOf = (el: Element): string => { + for (const attr of ['aria-label', 'title', 'alt', 'placeholder']) { + const value = el.getAttribute(attr) + + if (value) { + return value + } + } + + const text = (el.textContent || '').trim().replace(/\s+/g, ' ') + + return text.length > 80 ? text.slice(0, 77) + '…' : text + } + + /** Identity-based selector, or '' when the element has no durable handle. */ + const stableSelector = (el: Element): string => { + const dataTour = el.getAttribute('data-tour') + + if (dataTour) { + return '[data-tour="' + cssEscape(dataTour) + '"]' + } + + if (el.id) { + return '#' + cssEscape(el.id) + } + + const testId = el.getAttribute('data-testid') + + if (testId) { + return '[data-testid="' + cssEscape(testId) + '"]' + } + + const aria = el.getAttribute('aria-label') + const byAria = aria ? el.tagName.toLowerCase() + '[aria-label="' + cssEscape(aria) + '"]' : '' + + return byAria && doc.querySelectorAll(byAria).length === 1 ? byAria : '' + } + + /** Positional fallback: tag + nth-child path up to an id or . */ + const positionalSelector = (el: Element): string => { + const path: string[] = [] + let node: Element | null = el + + while (node && node !== doc.body && path.length < 8) { + if (node.id) { + path.unshift('#' + cssEscape(node.id)) + + break + } + + const parent: Element | null = node.parentElement + const index = parent ? Array.prototype.indexOf.call(parent.children, node) : -1 + + path.unshift(node.tagName.toLowerCase() + (index >= 0 ? ':nth-child(' + (index + 1) + ')' : '')) + node = parent + } + + return path.join(' > ') + } + + const visible = (el: Element): boolean => { + const rect = el.getBoundingClientRect() + + if (rect.width < 4 || rect.height < 4) { + return false + } + + const win = doc.defaultView + + return !win || (rect.bottom > 0 && rect.top < win.innerHeight && rect.right > 0 && rect.left < win.innerWidth) + } + + const push = (el: Element) => { + if (results.length >= max || seen.has(el) || !visible(el)) { + return + } + + const label = labelOf(el) + + if (!label) { + return + } + + const stable = stableSelector(el) + const selector = stable || positionalSelector(el) + + // Only report selectors that resolve back to this exact element. + if (!selector || doc.querySelector(selector) !== el) { + return + } + + const rect = el.getBoundingClientRect() + + seen.add(el) + results.push({ + label, + rect: [Math.round(rect.x), Math.round(rect.y), Math.round(rect.width), Math.round(rect.height)], + role: el.getAttribute('role') || el.tagName.toLowerCase(), + selector, + stable: !!stable + }) + } + + // Priority order: explicit tour markers, then landmarks/headings, then + // labelled interactive elements. Each tier only fills remaining capacity. + for (const el of doc.querySelectorAll('[data-tour]')) { + push(el) + } + + for (const el of doc.querySelectorAll('nav, main, aside, header, footer, [role], h1, h2, h3')) { + push(el) + } + + for (const el of doc.querySelectorAll('a[href], button, input, select, textarea, [tabindex], [aria-label]')) { + push(el) + } + + // Durable handles first: a caller picking off the top gets selectors that + // survive a re-render, and positional ones stay available as a last resort. + return results.sort((a, b) => Number(b.stable) - Number(a.stable)) +} diff --git a/apps/desktop/src/lib/tour/engine.test.ts b/apps/desktop/src/lib/tour/engine.test.ts new file mode 100644 index 0000000000..91dc8ecf5c --- /dev/null +++ b/apps/desktop/src/lib/tour/engine.test.ts @@ -0,0 +1,217 @@ +import { describe, expect, it } from 'vitest' + +import { collectTourTargets } from './collect-targets' +import { runTourEngine, type TourDriver, type TourHolder } from './engine' + +/** A recording fake of the driver.js surface the engine touches. */ +function makeFactory(calls: string[]) { + return (config?: object) => { + const steps = (config as { steps?: unknown[] } | undefined)?.steps ?? [] + let active = false + let index = 0 + + const instance: TourDriver = { + destroy() { + calls.push('destroy') + active = false + }, + drive(stepIndex?: number) { + calls.push(`drive:${stepIndex ?? 0}`) + active = true + index = stepIndex ?? 0 + }, + getActiveIndex: () => index, + highlight(step: object) { + calls.push(`highlight:${JSON.stringify(step)}`) + active = true + }, + isActive: () => active, + isLastStep: () => index >= steps.length - 1, + moveNext() { + calls.push('next') + index += 1 + }, + movePrevious() { + calls.push('prev') + index -= 1 + } + } + + return instance + } +} + +function seedDom() { + document.body.innerHTML = ` + +

Inbox

Composer

Positional only

+ ` + // happy-dom lays nothing out — every rect is 0×0, which the collector's + // visibility filter (rightly) drops. Give elements a real-looking box. + Element.prototype.getBoundingClientRect = () => + ({ bottom: 40, height: 32, left: 8, right: 128, top: 8, width: 120, x: 8, y: 8 }) as DOMRect +} + +describe('collectTourTargets', () => { + it('reports resolving selectors, durable handles first', () => { + seedDom() + const targets = collectTourTargets(document, 150) + + expect(targets.length).toBeGreaterThan(0) + expect(targets.some(t => t.selector === '[data-tour="composer"]')).toBe(true) + + for (const target of targets) { + expect(document.querySelector(target.selector)).not.toBeNull() + expect(target.label).toBeTruthy() + } + + // Stable targets sort ahead of positional ones, so a caller taking the + // first N gets selectors that survive a re-render. + const firstPositional = targets.findIndex(t => !t.stable) + + if (firstPositional !== -1) { + expect(targets.slice(firstPositional).every(t => !t.stable)).toBe(true) + } + }) + + it('flags identity selectors stable and nth-child paths not', () => { + seedDom() + const targets = collectTourTargets(document, 150) + const byTour = targets.find(t => t.selector === '[data-tour="composer"]') + const positional = targets.find(t => t.selector.includes('nth-child')) + + expect(byTour?.stable).toBe(true) + expect(positional?.stable ?? false).toBe(false) + }) + + it('honors the cap', () => { + seedDom() + expect(collectTourTargets(document, 2)).toHaveLength(2) + }) +}) + +describe('runTourEngine', () => { + it('targets answers with the page identity and its targets', () => { + seedDom() + const result = runTourEngine(makeFactory([]), {}, { kind: 'targets' }, collectTourTargets, document) + + expect(result.success).toBe(true) + expect(result.targets?.length).toBeGreaterThan(0) + }) + + it('show validates the selector before touching driver.js', () => { + seedDom() + const calls: string[] = [] + const holder: TourHolder = {} + const factory = makeFactory(calls) + const bad = runTourEngine(factory, holder, { kind: 'show', selector: '#nope' }, collectTourTargets, document) + + expect(bad.success).toBe(false) + expect(bad.error).toContain('#nope') + // The recovery hint points at the re-scan, not a dead end. + expect(bad.hint).toContain('targets') + expect(calls).toEqual([]) + + const good = runTourEngine( + factory, + holder, + { kind: 'show', selector: '#send-btn', text: 'Click here to send', title: 'Send' }, + collectTourTargets, + document + ) + + expect(good.success).toBe(true) + expect(calls.some(c => c.startsWith('highlight:'))).toBe(true) + expect(holder.driver).toBeDefined() + }) + + it('start → next pages through and cleans up after the last step', () => { + seedDom() + const calls: string[] = [] + const holder: TourHolder = {} + const factory = makeFactory(calls) + + const started = runTourEngine( + factory, + holder, + { + kind: 'start', + steps: [ + { selector: '#send-btn', title: 'Send' }, + { text: 'That is the whole flow.', title: 'Done' } + ] + }, + collectTourTargets, + document + ) + + expect(started).toMatchObject({ activeStep: 0, steps: 2, success: true }) + expect(runTourEngine(factory, holder, { kind: 'next' }, collectTourTargets, document)).toMatchObject({ + activeStep: 1, + success: true + }) + + // Advancing past the last step ends the tour. + expect(runTourEngine(factory, holder, { kind: 'next' }, collectTourTargets, document)).toMatchObject({ + done: true, + success: true + }) + expect(holder.driver).toBeUndefined() + }) + + it('start honors startAt and rejects unknown selectors, naming each', () => { + seedDom() + const holder: TourHolder = {} + const factory = makeFactory([]) + + expect( + runTourEngine( + factory, + holder, + { kind: 'start', startAt: 1, steps: [{ selector: '#send-btn' }, { title: 'Second' }] }, + collectTourTargets, + document + ) + ).toMatchObject({ activeStep: 1, success: true }) + + const result = runTourEngine( + factory, + {}, + { kind: 'start', steps: [{ selector: '#ghost', title: 'x' }, { selector: '#send-btn' }] }, + collectTourTargets, + document + ) + + expect(result.success).toBe(false) + expect(result.error).toContain('#ghost') + expect(result.error).not.toContain('#send-btn') + }) + + it('treats a malformed selector as unmatched instead of throwing', () => { + seedDom() + const result = runTourEngine(makeFactory([]), {}, { kind: 'show', selector: '<<<' }, collectTourTargets, document) + + expect(result.success).toBe(false) + expect(result.error).toContain('<<<') + }) + + it('next without a running tour errors, stop is idempotent', () => { + const holder: TourHolder = {} + const factory = makeFactory([]) + + expect(runTourEngine(factory, holder, { kind: 'next' }, collectTourTargets, document).success).toBe(false) + expect(runTourEngine(factory, holder, { kind: 'stop' }, collectTourTargets, document).success).toBe(true) + expect(runTourEngine(factory, holder, { kind: 'stop' }, collectTourTargets, document).success).toBe(true) + }) + + it('is self-contained source (injectable into a guest page)', () => { + // The preview surface stringifies these functions into a webview. Any + // captured import/closure reference would throw there — the source must + // reference nothing but its own parameters and page globals. + for (const source of [runTourEngine.toString(), collectTourTargets.toString()]) { + expect(source).not.toContain('__vite') + expect(source).not.toContain('import(') + expect(source).not.toContain('require(') + } + }) +}) diff --git a/apps/desktop/src/lib/tour/engine.ts b/apps/desktop/src/lib/tour/engine.ts new file mode 100644 index 0000000000..2a2c9ca364 --- /dev/null +++ b/apps/desktop/src/lib/tour/engine.ts @@ -0,0 +1,182 @@ +/** + * TOUR ENGINE — the one function that runs a tour action, on BOTH surfaces. + * + * The app surface calls it directly (imported driver.js factory + a module + * holder + `document`). The preview surface injects `runTourEngine.toString()` + * into the pane's alongside the driver.js IIFE and calls it with the + * page's own globals. Because the same source runs in both places it MUST stay + * self-contained: no imports, no closure references, no renderer globals — + * everything arrives as a parameter. The minimal structural types below erase + * at compile time, so the stringified function stays plain JS. + */ + +import type { TourTarget } from './collect-targets' + +/** The slice of a driver.js instance the engine drives. */ +export interface TourDriver { + destroy: () => void + drive: (stepIndex?: number) => void + getActiveIndex: () => number | undefined + highlight: (step: object) => void + isActive: () => boolean + isLastStep: () => boolean + moveNext: () => void + movePrevious: () => void +} + +export type TourDriverFactory = (config?: object) => TourDriver + +/** Where a surface keeps its live instance between actions (module state in + * the app, a window global in the preview page). */ +export interface TourHolder { + driver?: TourDriver +} + +/** One highlighted moment: an element, and what to say about it. Omit the + * selector for a centered narration step. */ +export interface TourStep { + selector?: string + side?: 'top' | 'right' | 'bottom' | 'left' + text?: string + title?: string +} + +/** A normalized action. `kind` is the verb; the rest is per-verb payload. */ +export interface TourAction extends TourStep { + kind: 'targets' | 'show' | 'start' | 'next' | 'prev' | 'stop' + startAt?: number + steps?: TourStep[] +} + +export interface TourResult { + action?: string + activeStep?: number + done?: boolean + error?: string + hint?: string + steps?: number + success: boolean + targets?: TourTarget[] + title?: string + url?: string +} + +/** Run one tour action. Self-contained (see module doc). */ +export function runTourEngine( + factory: TourDriverFactory, + holder: TourHolder, + action: TourAction, + collectTargets: (doc: Document, max: number) => TourTarget[], + doc: Document +): TourResult { + const kind = action.kind + + const popoverOf = (step: TourStep) => + step.title || step.text + ? { description: step.text || '', side: step.side || undefined, title: step.title || '' } + : undefined + + const stepOf = (step: TourStep) => ({ element: step.selector || undefined, popover: popoverOf(step) }) + + /** Selectors that match nothing right now — the caller's cue to re-scan. */ + const unmatched = (steps: TourStep[]) => + steps + .map(step => step.selector) + .filter((selector): selector is string => { + try { + return !!selector && !doc.querySelector(selector) + } catch { + return true + } + }) + + const missing = (selectors: string[]): TourResult => ({ + error: 'No element matches selector(s): ' + selectors.join(', '), + hint: "The DOM may have re-rendered — re-scan with 'targets' and prefer targets marked stable.", + success: false + }) + + if (kind === 'targets') { + return { + success: true, + targets: collectTargets(doc, 150), + title: doc.title, + url: doc.location ? doc.location.href : '' + } + } + + if (kind === 'show') { + const gone = unmatched([action]) + + if (gone.length > 0) { + return missing(gone) + } + + if (!holder.driver) { + holder.driver = factory({ animate: true, smoothScroll: true }) + } + + holder.driver.highlight(stepOf(action)) + + return { action: kind, success: true } + } + + if (kind === 'start') { + const steps = action.steps || [] + const gone = unmatched(steps) + + if (gone.length > 0) { + return missing(gone) + } + + if (holder.driver) { + holder.driver.destroy() + } + + const startAt = action.startAt || 0 + + holder.driver = factory({ + animate: true, + showProgress: steps.length > 1, + smoothScroll: true, + steps: steps.map(stepOf) + }) + holder.driver.drive(startAt) + + return { action: kind, activeStep: startAt, steps: steps.length, success: true } + } + + if (kind === 'next' || kind === 'prev') { + const driver = holder.driver + + if (!driver || !driver.isActive()) { + return { error: "No tour is running — start one first.", success: false } + } + + if (kind === 'next' && driver.isLastStep()) { + driver.destroy() + holder.driver = undefined + + return { action: kind, done: true, success: true } + } + + if (kind === 'next') { + driver.moveNext() + } else { + driver.movePrevious() + } + + return { action: kind, activeStep: driver.getActiveIndex(), success: true } + } + + if (kind === 'stop') { + if (holder.driver) { + holder.driver.destroy() + holder.driver = undefined + } + + return { action: kind, success: true } + } + + return { error: 'Unknown tour action: ' + kind, success: false } +} diff --git a/apps/desktop/src/lib/tour/index.ts b/apps/desktop/src/lib/tour/index.ts new file mode 100644 index 0000000000..d70b9b8b9c --- /dev/null +++ b/apps/desktop/src/lib/tour/index.ts @@ -0,0 +1,34 @@ +/** + * TOURS — highlight-and-narrate walkthroughs for any surface. + * + * Two consumers, one engine: + * + * - The `tour` agent tool, via the gateway (see run-tour.ts). + * - Your own curated tours, via this module: + * + * ```ts + * import { startTour, showTourStep, stopTour } from '@/lib/tour' + * + * startTour([ + * { selector: '[data-tour="composer"]', title: 'Composer', text: 'Type here.' }, + * { selector: '[data-tour="files"]', title: 'Files', text: 'Your project.' } + * ]) + * ``` + * + * Tours run against whatever is in the DOM — mark elements with `data-tour="…"` + * to give them durable handles (see `collectTourTargets`, which reports those + * first and flags every selector as stable or positional). + */ + +export { collectTourTargets, type TourTarget } from './collect-targets' +export type { TourAction, TourResult, TourStep } from './engine' +export { + listTourTargets, + nextTourStep, + previousTourStep, + runTour, + showTourStep, + startTour, + stopTour, + type TourSurface +} from './run-tour' diff --git a/apps/desktop/src/lib/tour/run-tour.ts b/apps/desktop/src/lib/tour/run-tour.ts new file mode 100644 index 0000000000..8634cc143e --- /dev/null +++ b/apps/desktop/src/lib/tour/run-tour.ts @@ -0,0 +1,59 @@ +/** + * RUN TOUR — the tour verbs, on either surface. + * + * `runTour` is the generic entry (one normalized action in, a result out) and + * the named verbs below are the ergonomic API — used by the agent tool through + * the gateway, and by any curated in-app tour. surface='app' drives driver.js + * against the Hermes DOM; surface='preview' runs the same engine source inside + * the preview pane's guest page. + * + * Dynamic-imported by gateway-event.ts, so driver.js (and the preview's raw + * injection payload) stay off the boot path until a tour actually runs. + */ + +import 'driver.js/dist/driver.css' +import './app-tour.css' + +import { driver as driverFactory } from 'driver.js' + +import { runPreviewTour } from '@/app/chat/right-rail/preview-tour' + +import { collectTourTargets } from './collect-targets' +import { runTourEngine, type TourAction, type TourHolder, type TourResult, type TourStep } from './engine' + +/** Which document a tour runs against. */ +export type TourSurface = 'app' | 'preview' + +/** The app surface's live driver instance, reused across actions. */ +const appHolder: TourHolder = {} + +/** Run one tour action on `surface`. Never throws — failures come back as + * `{success: false, error}` so a caller (or the agent) can recover. */ +export async function runTour(action: TourAction, surface: TourSurface = 'app'): Promise { + try { + return surface === 'preview' + ? await runPreviewTour(action) + : runTourEngine(driverFactory, appHolder, action, collectTourTargets, document) + } catch (error) { + return { error: error instanceof Error ? error.message : String(error), success: false } + } +} + +/** What's on screen right now, durable (`stable`) handles first. */ +export const listTourTargets = (surface?: TourSurface) => runTour({ kind: 'targets' }, surface) + +/** Spotlight one element with a popover, replacing any current highlight. */ +export const showTourStep = (step: TourStep, surface?: TourSurface) => runTour({ ...step, kind: 'show' }, surface) + +/** Begin a multi-step tour the user pages through with Next/Prev. */ +export const startTour = (steps: TourStep[], surface?: TourSurface, startAt = 0) => + runTour({ kind: 'start', startAt, steps }, surface) + +/** Advance a running tour; past the last step it ends and cleans up. */ +export const nextTourStep = (surface?: TourSurface) => runTour({ kind: 'next' }, surface) + +/** Step a running tour backward. */ +export const previousTourStep = (surface?: TourSurface) => runTour({ kind: 'prev' }, surface) + +/** End the tour and clear the overlay. Safe to call when none is running. */ +export const stopTour = (surface?: TourSurface) => runTour({ kind: 'stop' }, surface) From ec69940537d133d971cdcf8fc1749c1e9f8fc76e Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Tue, 18 Aug 2026 20:32:14 -0500 Subject: [PATCH 03/11] feat(desktop): run tours inside the preview pane MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The guest page is out-of-process, so the first action injects a self-contained bundle over executeJavaScript — the driver.js IIFE, its stylesheet, and the engine source — parked on window globals so later actions reuse the live instance. Injection is idempotent and vanishes with the page, so a navigation resets the tour. This is what lets a tour walk through any web app open in the in-app browser, not just Hermes itself. --- .../src/app/chat/right-rail/preview-pane.tsx | 20 ++++++ .../chat/right-rail/preview-tour-runner.ts | 38 +++++++++++ .../src/app/chat/right-rail/preview-tour.ts | 67 +++++++++++++++++++ 3 files changed, 125 insertions(+) create mode 100644 apps/desktop/src/app/chat/right-rail/preview-tour-runner.ts create mode 100644 apps/desktop/src/app/chat/right-rail/preview-tour.ts diff --git a/apps/desktop/src/app/chat/right-rail/preview-pane.tsx b/apps/desktop/src/app/chat/right-rail/preview-pane.tsx index b9d0701881..7d6150b2f3 100644 --- a/apps/desktop/src/app/chat/right-rail/preview-pane.tsx +++ b/apps/desktop/src/app/chat/right-rail/preview-pane.tsx @@ -30,6 +30,7 @@ import { previewConsoleState } from './preview-console-store' import { LocalFilePreview, PreviewEmptyState } from './preview-file' import { PREVIEW_BROWSER_ATTR, registerPreviewNav } from './preview-nav' import { registerPreviewPageReader } from './preview-reader' +import { registerPreviewTourRunner } from './preview-tour-runner' type PreviewWebview = HTMLElement & { canGoBack?: () => boolean @@ -454,6 +455,25 @@ export function PreviewPane({ embedded = false, onRestartServer, reloadRequest = }) }, [isWebPreview, tabId]) + // Publish the TOUR runner for this tab (the tour tool, surface='preview'): + // runs injected driver.js actions inside the guest page so the agent can + // give guided walkthroughs of whatever web app is open here. + useEffect(() => { + if (!isWebPreview || !tabId) { + return + } + + return registerPreviewTourRunner(tabId, async code => { + const webview = webviewRef.current + + if (!webview?.executeJavaScript) { + throw new Error('preview webview is not ready') + } + + return webview.executeJavaScript(code) + }) + }, [isWebPreview, tabId]) + // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see eslint rule comment) useEffect(() => { if (!consoleOpen) { diff --git a/apps/desktop/src/app/chat/right-rail/preview-tour-runner.ts b/apps/desktop/src/app/chat/right-rail/preview-tour-runner.ts new file mode 100644 index 0000000000..84a15c8869 --- /dev/null +++ b/apps/desktop/src/app/chat/right-rail/preview-tour-runner.ts @@ -0,0 +1,38 @@ +/** + * PREVIEW TOUR RUNNER REGISTRY — the tour tool's script bridge into the + * preview pane, the tour analog of preview-nav's handle registry. + * + * A live browser pane registers a script runner (its webview's + * `executeJavaScript`) here, keyed by tab id; `activeTourRunner` resolves the + * ACTIVE tab from the store. Kept separate from preview-tour.ts so the pane + * component's static import stays tiny — the engine source + driver.js + * payload only load when a tour actually runs (gateway-event dynamic-imports + * preview-tour.ts). + */ + +import { $rightRailActiveTabId } from '@/store/layout' +import { $previewTabs } from '@/store/preview' + +/** Runs JS source in the pane's guest page, resolving its completion value. */ +export type TourScriptRunner = (code: string) => Promise + +const runners = new Map() + +/** Register a live preview's script runner; returns an idempotent unregister. */ +export function registerPreviewTourRunner(tabId: string, runner: TourScriptRunner): () => void { + runners.set(tabId, runner) + + return () => { + if (runners.get(tabId) === runner) { + runners.delete(tabId) + } + } +} + +/** The ACTIVE preview tab's script runner. Null = no live page to tour. */ +export function activeTourRunner(): TourScriptRunner | null { + const tabs = $previewTabs.get() + const tab = tabs.find(t => t.id === $rightRailActiveTabId.get()) ?? tabs[0] + + return (tab && runners.get(tab.id)) || null +} diff --git a/apps/desktop/src/app/chat/right-rail/preview-tour.ts b/apps/desktop/src/app/chat/right-rail/preview-tour.ts new file mode 100644 index 0000000000..12ad67dc71 --- /dev/null +++ b/apps/desktop/src/app/chat/right-rail/preview-tour.ts @@ -0,0 +1,67 @@ +/** + * PREVIEW TOUR — runs tour actions inside the preview pane's guest page, so a + * tour can walk through ANY web app open in the in-app browser, not just + * Hermes itself. + * + * The guest page is out-of-process; nothing here can touch its DOM directly. + * Instead the first action injects a self-contained bundle over + * `executeJavaScript` — the vendored driver.js IIFE, its stylesheet, and the + * same engine/collector SOURCE the app surface runs (see lib/tour/engine.ts's + * self-containment contract) — parked on window globals so subsequent actions + * reuse the live driver instance. Injection is idempotent and vanishes with + * the page (a navigation resets the tour, which is the right behavior). + * + * Dynamic-imported by run-tour.ts so the raw driver.js payload stays out of + * the boot path. + */ + +import driverCss from 'driver.js/dist/driver.css?raw' +import driverIife from 'driver.js/dist/driver.js.iife.js?raw' + +import { collectTourTargets } from '@/lib/tour/collect-targets' +import { runTourEngine, type TourAction, type TourResult } from '@/lib/tour/engine' + +import { activeTourRunner } from './preview-tour-runner' + +/** Build the idempotent inject-and-run script for one tour action. */ +function buildTourScript(action: TourAction): string { + return `(function () { + var w = window; + if (!w.__hermesTourEngine) { + ${driverIife} + w.__hermesTourHolder = {}; + w.__hermesTourCollect = (${collectTourTargets.toString()}); + w.__hermesTourEngine = (${runTourEngine.toString()}); + } + if (!document.getElementById('__hermes-tour-style')) { + var style = document.createElement('style'); + style.id = '__hermes-tour-style'; + style.textContent = ${JSON.stringify(driverCss)}; + (document.head || document.documentElement).appendChild(style); + } + return JSON.stringify(w.__hermesTourEngine( + w.driver.js.driver, + w.__hermesTourHolder, + ${JSON.stringify(action)}, + w.__hermesTourCollect, + document + )); +})()` +} + +/** Run one tour action in the ACTIVE preview tab's page. */ +export async function runPreviewTour(action: TourAction): Promise { + const run = activeTourRunner() + + if (!run) { + return { error: 'No live page is open in the preview pane — open one first.', success: false } + } + + const raw = await run(buildTourScript(action)) + + if (typeof raw !== 'string' || !raw) { + return { error: 'The page did not answer the tour action.', success: false } + } + + return JSON.parse(raw) as TourResult +} From 0d572e063b298c46b59636e6d37a22d02ad76f56 Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Tue, 18 Aug 2026 20:32:14 -0500 Subject: [PATCH 04/11] feat(desktop): answer tour.request from the renderer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Translates the wire payload into a normalized action and dynamic-imports the engine, keeping driver.js off the boot path. Active session only — a background turn must never paint an overlay over what the user is looking at. --- .../hooks/use-message-stream/gateway-event.ts | 43 +++++++++++++++++++ apps/desktop/src/lib/chat-messages.ts | 8 ++++ 2 files changed, 51 insertions(+) diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event.ts index abc364337c..8a247c8263 100644 --- a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event.ts +++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event.ts @@ -22,6 +22,7 @@ import { triggerHaptic } from '@/lib/haptics' import { modelOptionsQueryKey } from '@/lib/model-options' import { isProviderSetupErrorMessage } from '@/lib/provider-setup-errors' import { invalidateSlashCompletions } from '@/lib/slash-completion-cache' +import type { TourAction, TourStep } from '@/lib/tour' import { type AgentNoticePayload, clearAgentNotice, nativeNoticeInput, showAgentNotice } from '@/store/agent-notices' import { reconcileApprovalModeForProfile } from '@/store/approval-mode' import { billingCtaLabel, clearBillingBlock, runBillingRecovery, setBillingBlock } from '@/store/billing-block' @@ -1454,6 +1455,48 @@ export function useGatewayEventHandler(deps: GatewayEventDeps) { // Agent closed its own read-only tab via the desktop-gated close_terminal tool. // The process is untouched — this only drops the view. closeAgentTerminalByProc(payload?.process_id ?? '') + } else if (event.type === 'tour.request') { + // tour tool: run one guided-tour action (highlight/step/discover) via + // driver.js — on the app's own DOM or inside the preview pane's guest + // page — and answer with the outcome. Dynamic import keeps driver.js + // and the preview injection payload off the boot path. Active session + // only: a background turn must never paint overlays on the user's + // screen (desktop AGENTS.md: offer, don't hijack). + const requestId = typeof payload?.request_id === 'string' ? payload.request_id : '' + + if (requestId) { + const answer = (result: unknown) => + $gateway.get()?.request('tour.respond', { + request_id: requestId, + text: result ? JSON.stringify(result) : '' + }) + + if (isActiveEvent) { + void import('@/lib/tour') + .then(({ runTour }) => + runTour( + { + kind: (payload?.action ?? 'stop') as TourAction['kind'], + selector: payload?.selector, + side: payload?.side as TourStep['side'], + startAt: payload?.step_index, + steps: payload?.steps as TourStep[] | undefined, + text: payload?.text, + title: payload?.title + }, + payload?.surface === 'preview' ? 'preview' : 'app' + ) + ) + .then(answer, error => + answer({ error: error instanceof Error ? error.message : String(error), success: false }) + ) + } else { + void answer({ + error: 'Tours only run in the session the user is looking at.', + success: false + }) + } + } } else if (event.type === 'pane.reveal') { // Agent revealed a pane via the desktop-gated focus_pane tool, in // response to an explicit user request. Active session only — a diff --git a/apps/desktop/src/lib/chat-messages.ts b/apps/desktop/src/lib/chat-messages.ts index c580295276..8602a54ecb 100644 --- a/apps/desktop/src/lib/chat-messages.ts +++ b/apps/desktop/src/lib/chat-messages.ts @@ -118,6 +118,14 @@ export type GatewayEventPayload = { pane?: string // layout.apply (agent applying a layout preset via the apply_layout tool) preset?: string + // tour.request (tour tool — agent-guided driver.js walkthrough). `action` + // and `steps` name the tour verb and step list; `surface` picks the app's + // own DOM vs the preview pane's guest page. + surface?: string + selector?: string + side?: string + steps?: unknown + step_index?: number // message.reaction (agent reacting via the react_to_message tool) — the // durable messages.id, that row's full reaction list after the write, and // the row's role so a live (not-yet-round-tripped) message can be matched. From 23d88c2b0e684568f296d7e87ae2144d849ba32f Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Tue, 18 Aug 2026 20:32:23 -0500 Subject: [PATCH 05/11] =?UTF-8?q?feat(tools):=20tour=20=E2=80=94=20let=20t?= =?UTF-8?q?he=20agent=20walk=20a=20user=20through=20the=20UI?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit One generic tool in the desktop_ui toolset: discover what is on screen, highlight an element with narration, or hand the user a paged tour. No tour content lives in the code — the agent authors each one live, which is what makes 'how does this work?' answerable as a walkthrough instead of a wall of text. Rides the existing blocking-prompt bridge (tour.request/.respond) like read_preview, so it works on every connection topology. --- agent/agent_init.py | 2 + agent/agent_runtime_helpers.py | 19 +++- agent/tool_executor.py | 27 +++++ run_agent.py | 2 + tools/tour_tool.py | 202 +++++++++++++++++++++++++++++++++ toolsets.py | 2 +- tui_gateway/methods_prompt.py | 10 ++ tui_gateway/server.py | 12 ++ 8 files changed, 274 insertions(+), 2 deletions(-) create mode 100644 tools/tour_tool.py diff --git a/agent/agent_init.py b/agent/agent_init.py index 67fc38bf3f..938e13f612 100644 --- a/agent/agent_init.py +++ b/agent/agent_init.py @@ -529,6 +529,7 @@ def init_agent( read_preview_callback: callable = None, read_window_below_callback: callable = None, setup_mcp_callback: callable = None, + tour_callback: callable = None, step_callback: callable = None, stream_delta_callback: callable = None, interim_assistant_callback: callable = None, @@ -824,6 +825,7 @@ def init_agent( agent.read_preview_callback = read_preview_callback agent.read_window_below_callback = read_window_below_callback agent.setup_mcp_callback = setup_mcp_callback + agent.tour_callback = tour_callback agent.step_callback = step_callback agent.stream_delta_callback = stream_delta_callback agent.interim_assistant_callback = interim_assistant_callback diff --git a/agent/agent_runtime_helpers.py b/agent/agent_runtime_helpers.py index 5d87894a65..79cfe58135 100644 --- a/agent/agent_runtime_helpers.py +++ b/agent/agent_runtime_helpers.py @@ -99,7 +99,7 @@ def _ra(): AGENT_RUNTIME_POST_HOOK_TOOL_NAMES = frozenset( - {"todo", "session_search", "memory", "clarify", "read_terminal", "read_preview", "read_window_below", "setup_mcp", "delegate_task"} + {"todo", "session_search", "memory", "clarify", "read_terminal", "read_preview", "read_window_below", "setup_mcp", "tour", "delegate_task"} ) @@ -3236,6 +3236,23 @@ def invoke_tool(agent, function_name: str, function_args: dict, effective_task_i ), next_args, ) + elif function_name == "tour": + def _execute(next_args: dict) -> Any: + from tools.tour_tool import tour_tool as _tour_tool + return _finish_agent_tool( + _tour_tool( + action=next_args.get("action", ""), + surface=next_args.get("surface"), + selector=next_args.get("selector"), + title=next_args.get("title"), + text=next_args.get("text"), + side=next_args.get("side"), + steps=next_args.get("steps"), + step_index=next_args.get("step_index"), + callback=getattr(agent, "tour_callback", None), + ), + next_args, + ) elif function_name == "setup_mcp": def _execute(next_args: dict) -> Any: from tools.setup_mcp_tool import setup_mcp_tool as _setup_mcp_tool diff --git a/agent/tool_executor.py b/agent/tool_executor.py index 4fedb6dc7d..90226b02e1 100644 --- a/agent/tool_executor.py +++ b/agent/tool_executor.py @@ -2197,6 +2197,33 @@ def execute_tool_calls_sequential(agent, assistant_message, messages: list, effe tool_duration = time.time() - tool_start_time if agent._should_emit_quiet_tool_messages(): agent._vprint(f" {_get_cute_tool_message_impl('read_window_below', function_args, tool_duration, result=function_result)}") + elif function_name == "tour": + def _execute(next_args: dict) -> Any: + from tools.tour_tool import tour_tool as _tour_tool + return _tour_tool( + action=next_args.get("action", ""), + surface=next_args.get("surface"), + selector=next_args.get("selector"), + title=next_args.get("title"), + text=next_args.get("text"), + side=next_args.get("side"), + steps=next_args.get("steps"), + step_index=next_args.get("step_index"), + callback=getattr(agent, "tour_callback", None), + ) + function_result, function_args, middleware_trace, _execution_blocked, _execution_dispatched = _managed_values(_run_agent_tool_execution_middleware( + agent, + function_name=function_name, + function_args=function_args, + effective_task_id=effective_task_id, + tool_call_id=getattr(tool_call, "id", "") or "", + execute=_execute, + scope_block=_ts_scope_block, + display_index=i, + )) + tool_duration = time.time() - tool_start_time + if agent._should_emit_quiet_tool_messages(): + agent._vprint(f" {_get_cute_tool_message_impl('tour', function_args, tool_duration, result=function_result)}") elif function_name == "setup_mcp": def _execute(next_args: dict) -> Any: from tools.setup_mcp_tool import setup_mcp_tool as _setup_mcp_tool diff --git a/run_agent.py b/run_agent.py index b09262eae4..b4308f27a6 100644 --- a/run_agent.py +++ b/run_agent.py @@ -472,6 +472,7 @@ class AIAgent: read_preview_callback: callable = None, read_window_below_callback: callable = None, setup_mcp_callback: callable = None, + tour_callback: callable = None, step_callback: callable = None, stream_delta_callback: callable = None, interim_assistant_callback: callable = None, @@ -560,6 +561,7 @@ class AIAgent: read_preview_callback=read_preview_callback, read_window_below_callback=read_window_below_callback, setup_mcp_callback=setup_mcp_callback, + tour_callback=tour_callback, step_callback=step_callback, stream_delta_callback=stream_delta_callback, interim_assistant_callback=interim_assistant_callback, diff --git a/tools/tour_tool.py b/tools/tour_tool.py new file mode 100644 index 0000000000..9893020ba5 --- /dev/null +++ b/tools/tour_tool.py @@ -0,0 +1,202 @@ +#!/usr/bin/env python3 +"""Run a guided tour (highlight + narrate UI elements) in the Hermes desktop GUI. + +One generic tool, no baked-in tour definitions: the agent discovers what is on +screen (``action="targets"``), then highlights any element by CSS selector with +its own title/text — either one step at a time (``show``, agent-paced) or as a +full step list the user pages through with Next/Prev (``start``). + +Two surfaces share the same engine (driver.js in the renderer): + +- ``surface="app"`` — the Hermes desktop app's own DOM (tours of Hermes itself). +- ``surface="preview"`` — the page loaded in the in-app browser/preview pane + (tours of ANY web app, e.g. a project open via open_preview). + +Round-trips through the gateway's blocking-prompt bridge like ``read_preview``: +tui_gateway emits ``tour.request``, the renderer drives driver.js (injecting it +into the preview's webview when needed) and answers ``tour.respond`` with the +outcome, so the agent knows whether the selector matched. This module is just +schema + a thin dispatcher over the platform-injected callback. + +Lives in the ``desktop_ui`` toolset, which the GUI gateway enables only for +desktop-sourced sessions. +""" + +import json +from typing import Callable, Optional + +from tools.registry import registry, tool_error + +ACTIONS = ("targets", "show", "start", "next", "prev", "stop") +SURFACES = ("app", "preview") +SIDES = ("top", "right", "bottom", "left") + + +def tour_tool( + action: str = "", + surface: Optional[str] = None, + selector: Optional[str] = None, + title: Optional[str] = None, + text: Optional[str] = None, + side: Optional[str] = None, + steps: Optional[list] = None, + step_index: Optional[int] = None, + callback: Optional[Callable] = None, +) -> str: + """Dispatch one tour action to the desktop renderer and return its outcome.""" + if callback is None: + return tool_error("tour is only available in the Hermes desktop app.") + + verb = (action or "").strip().lower() + if verb not in ACTIONS: + return tool_error(f"action must be one of: {', '.join(ACTIONS)}.") + + where = (surface or "app").strip().lower() + if where not in SURFACES: + return tool_error(f"surface must be one of: {', '.join(SURFACES)}.") + + if side is not None and side not in SIDES: + return tool_error(f"side must be one of: {', '.join(SIDES)}.") + + # Every highlighted moment needs something to point at or something to say. + def _empty(step: dict) -> bool: + return not (step.get("selector") or step.get("title") or step.get("text")) + + if verb == "show" and _empty({"selector": selector, "title": title, "text": text}): + return tool_error("show needs a selector (and/or title/text for the popover).") + + if verb == "start": + if not isinstance(steps, list) or not steps: + return tool_error("start needs a non-empty steps array.") + for i, step in enumerate(steps): + if not isinstance(step, dict): + return tool_error(f"steps[{i}] must be an object.") + if _empty(step): + return tool_error(f"steps[{i}] needs a selector and/or title/text.") + + payload = { + key: val + for key, val in ( + ("action", verb), + ("surface", where), + ("selector", selector), + ("title", title), + ("text", text), + ("side", side), + ("steps", steps), + ("step_index", step_index), + ) + if val is not None + } + + try: + raw = callback(payload) + except Exception as exc: + return tool_error(f"Tour action failed: {exc}") + + if not raw: + return tool_error( + "The tour request timed out, or no GUI window answered. " + "For surface='preview' open a page in the preview pane first." + ) + + # The renderer answers with a JSON object; pass it through, else wrap it. + try: + return json.dumps(json.loads(raw), ensure_ascii=False) + except (TypeError, ValueError): + return json.dumps({"text": str(raw)}, ensure_ascii=False) + + +_STEP_SCHEMA = { + "type": "object", + "properties": { + "selector": { + "type": "string", + "description": "CSS selector of the element this step highlights. Omit for a centered narration-only step.", + }, + "title": {"type": "string", "description": "Popover title."}, + "text": {"type": "string", "description": "Popover body text."}, + "side": { + "type": "string", + "enum": list(SIDES), + "description": "Preferred popover side. Omit to auto-place.", + }, + }, +} + +TOUR_SCHEMA = { + "name": "tour", + "description": ( + "Give a live guided tour in the Hermes desktop GUI: dim the screen, " + "highlight an element, and attach a popover with your own title/text. " + "Works on two surfaces — 'app' (the Hermes app itself) and 'preview' " + "(whatever page is open in the in-app browser, so any web app can be " + "toured). ALWAYS call action='targets' first to discover what is on " + "screen instead of guessing selectors; each target reports " + "`stable: true` when its selector keys off identity (data-tour, id, " + "data-testid, aria-label) and survives a re-render — prefer those, and " + "re-scan if a selector stops matching. Then either narrate at your own " + "pace with action='show' (one highlight per call — replaces the " + "previous one; pair each with a chat message describing it), or hand " + "control to the user with action='start' + a steps array (driver.js " + "renders Next/Prev buttons; 'next'/'prev' also page it " + "programmatically). action='stop' clears the tour. Use when the user " + "asks how something works, where something is, or for a walkthrough of " + "an app or workflow." + ), + "parameters": { + "type": "object", + "properties": { + "action": { + "type": "string", + "enum": list(ACTIONS), + "description": "targets: list tourable elements. show: highlight one element. start: begin a multi-step user-paced tour. next/prev: page a started tour. stop: end the tour.", + }, + "surface": { + "type": "string", + "enum": list(SURFACES), + "description": "Where the tour runs: 'app' (Hermes desktop UI, default) or 'preview' (the page in the in-app browser pane).", + }, + "selector": { + "type": "string", + "description": "For show: CSS selector of the element to highlight (from action='targets', preferring a stable one). Omit for a centered narration popover.", + }, + "title": {"type": "string", "description": "For show: popover title."}, + "text": {"type": "string", "description": "For show: popover body text."}, + "side": { + "type": "string", + "enum": list(SIDES), + "description": "For show: preferred popover side. Omit to auto-place.", + }, + "steps": { + "type": "array", + "items": _STEP_SCHEMA, + "description": "For start: the ordered tour steps.", + }, + "step_index": { + "type": "integer", + "description": "For start: 0-indexed step to begin at (default 0).", + }, + }, + "required": ["action"], + }, +} + + +registry.register( + name="tour", + toolset="desktop_ui", + schema=TOUR_SCHEMA, + handler=lambda args, **kw: tour_tool( + action=args.get("action", ""), + surface=args.get("surface"), + selector=args.get("selector"), + title=args.get("title"), + text=args.get("text"), + side=args.get("side"), + steps=args.get("steps"), + step_index=args.get("step_index"), + callback=kw.get("callback"), + ), + emoji="🧭", +) diff --git a/toolsets.py b/toolsets.py index 8bb86024f5..18a6bf4227 100644 --- a/toolsets.py +++ b/toolsets.py @@ -279,7 +279,7 @@ TOOLSETS = { "open_preview", "read_preview", "read_window_below", "focus_pane", "react_to_message", - "setup_mcp", + "setup_mcp", "tour", ], "includes": [] }, diff --git a/tui_gateway/methods_prompt.py b/tui_gateway/methods_prompt.py index bb8f329db3..115fd14047 100644 --- a/tui_gateway/methods_prompt.py +++ b/tui_gateway/methods_prompt.py @@ -1432,6 +1432,16 @@ def _(rid, params: dict) -> dict: return _respond(rid, params, "text", allow_expired=True) +@method("tour.respond") +def _(rid, params: dict) -> dict: + # `text` is a JSON string with the tour action's outcome (tour tool) — + # matched targets, the active step, or an error naming the bad selector. + # allow_expired=True for the same reason as terminal.read: a preview tour + # injecting driver.js into a slow page can lose the race with the tool's + # bounded wait. + return _respond(rid, params, "text", allow_expired=True) + + @method("mcp.setup.respond") def _(rid, params: dict) -> dict: # `result` is a JSON string of the setup card's outcome ({status, server, diff --git a/tui_gateway/server.py b/tui_gateway/server.py index d024c7e411..e7b09ab8c2 100644 --- a/tui_gateway/server.py +++ b/tui_gateway/server.py @@ -3551,6 +3551,7 @@ def _block( "preview.read.request", "window.read.request", "mcp.setup.request", + "tour.request", }: _emit( f"{event.removesuffix('.request')}.expire", @@ -6307,6 +6308,17 @@ def _agent_cbs(sid: str) -> dict: {"server": server, "action": action, "reason": reason}, timeout=600, ), + # tour tool (desktop GUI): the renderer drives driver.js — highlighting + # elements in the app's own DOM or injecting the engine into the + # preview pane's webview — and answers tour.respond with the outcome + # (did the selector match, which step is active). Generous timeout: a + # preview tour's first action loads the engine into a live page. + "tour_callback": lambda payload: _block( + "tour.request", + sid, + dict(payload), + timeout=45, + ), } # Interim assistant commentary (text alongside tool calls, or the attempted From 93b50ea0bb750cfeb121dbf4d7d30c0ec0dec59c Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Tue, 18 Aug 2026 20:32:23 -0500 Subject: [PATCH 06/11] test+docs(tour): cover the engine and document the API Ten behavior tests for target discovery, stable-selector ordering, step paging, recovery hints, and the self-containment contract the preview injection depends on. Docs cover data-tour markup and the curated-tour entry point alongside the tool itself. --- tests/run_agent/test_run_agent.py | 1 + .../tui_gateway/test_gui_surface_toolsets.py | 1 + website/docs/reference/tools-reference.md | 26 ++++++++++++++++++- website/docs/reference/toolsets-reference.md | 2 +- 4 files changed, 28 insertions(+), 2 deletions(-) diff --git a/tests/run_agent/test_run_agent.py b/tests/run_agent/test_run_agent.py index ddd8702fb7..135e37e83f 100644 --- a/tests/run_agent/test_run_agent.py +++ b/tests/run_agent/test_run_agent.py @@ -2321,6 +2321,7 @@ class TestAgentRuntimePostHookOwnershipSync: ("read_preview", {}), ("read_window_below", {}), ("setup_mcp", {"server": "linear", "action": "install"}), + ("tour", {"action": "stop"}), ("delegate_task", {"goal": "Check the child path"}), ) diff --git a/tests/tui_gateway/test_gui_surface_toolsets.py b/tests/tui_gateway/test_gui_surface_toolsets.py index 366c39334d..8c236c68b3 100644 --- a/tests/tui_gateway/test_gui_surface_toolsets.py +++ b/tests/tui_gateway/test_gui_surface_toolsets.py @@ -26,6 +26,7 @@ GUI_TOOLS = { "read_window_below", "react_to_message", "setup_mcp", + "tour", } diff --git a/website/docs/reference/tools-reference.md b/website/docs/reference/tools-reference.md index 4851c2edad..664d8c3ab9 100644 --- a/website/docs/reference/tools-reference.md +++ b/website/docs/reference/tools-reference.md @@ -8,7 +8,7 @@ description: "Authoritative reference for Hermes built-in tools, grouped by tool This page documents Hermes' built-in tools, grouped by toolset. Availability varies by platform, credentials, and enabled toolsets. -**Quick counts (current registry):** ~83 tools — 10 browser tools (core) + 2 CDP-gated browser tools, 4 file tools, 4 Home Assistant tools, 2 terminal tools (`terminal`, `process`), 7 desktop-GUI tools (`read_terminal`, `close_terminal`, `open_preview`, `read_preview`, `read_window_below`, `focus_pane`, `react_to_message` — desktop-app sessions only), 2 web tools, 5 Feishu tools, 7 Spotify tools (registered by the bundled `spotify` plugin), 5 Yuanbao tools, 12 kanban tools (registered when the kanban dispatcher spawns the agent), 3 project tools (desktop/GUI sessions), 2 Discord tools, 3 video tools (`video_generate`, `xai_video_edit`, `xai_video_extend`), and a handful of standalone tools (`memory`, `clarify`, `delegate_task`, `execute_code`, `cronjob`, `session_search`, `skill_view`/`skill_manage`/`skills_list`, `text_to_speech`, `image_generate`, `vision_analyze`, `video_analyze`, `todo`, `computer_use`, `x_search`). +**Quick counts (current registry):** ~83 tools — 10 browser tools (core) + 2 CDP-gated browser tools, 4 file tools, 4 Home Assistant tools, 2 terminal tools (`terminal`, `process`), 8 desktop-GUI tools (`read_terminal`, `close_terminal`, `open_preview`, `read_preview`, `read_window_below`, `focus_pane`, `react_to_message`, `tour` — desktop-app sessions only), 2 web tools, 5 Feishu tools, 7 Spotify tools (registered by the bundled `spotify` plugin), 5 Yuanbao tools, 12 kanban tools (registered when the kanban dispatcher spawns the agent), 3 project tools (desktop/GUI sessions), 2 Discord tools, 3 video tools (`video_generate`, `xai_video_edit`, `xai_video_extend`), and a handful of standalone tools (`memory`, `clarify`, `delegate_task`, `execute_code`, `cronjob`, `session_search`, `skill_view`/`skill_manage`/`skills_list`, `text_to_speech`, `image_generate`, `vision_analyze`, `video_analyze`, `todo`, `computer_use`, `x_search`). :::tip MCP Tools In addition to built-in tools, Hermes can load tools dynamically from MCP servers. MCP tools appear with the prefix `mcp____` (e.g., `mcp__github__create_issue` for the `github` MCP server). See [MCP Integration](/user-guide/features/mcp) for configuration. @@ -201,6 +201,30 @@ messaging, and cron sessions. | `read_window_below` | Identify the OS window directly underneath the Hermes desktop window — app name, title, bounds (metadata only, never pixels). On macOS, other apps' titles appear only when Screen Recording is already granted; the tool never prompts for it. | — | | `focus_pane` | Reveal and focus a pane in the Hermes desktop app (chat, files, terminal, review, sessions). | — | | `react_to_message` | React to a message with a single emoji, iMessage-tapback style. Opt-in via Settings → Appearance (`display.message_reactions`). | — | +| `tour` | Give a live guided tour: dim the screen, highlight an element, and attach a narrated popover (driver.js). Works on the Hermes app's own UI and on any page open in the preview pane; `targets` discovers what's on screen, `show` narrates step-by-step, `start` hands the user Next/Prev controls. | — | + +### Tours + +The `tour` tool discovers its own targets — call `action='targets'` and it returns every addressable element on screen with a selector, a label, and a `stable` flag. Stable selectors key off identity (`data-tour`, `id`, `data-testid`, `aria-label`) and survive a re-render; positional `nth-child` paths don't, so stable ones sort first and should be preferred. + +To give an element a durable handle of your own, mark it up: + +```html +
…
+``` + +The same engine backs curated (non-agent) tours in the desktop app, so a feature can ship its own walkthrough: + +```ts +import { startTour, showTourStep, stopTour } from '@/lib/tour' + +startTour([ + { selector: '[data-tour="composer"]', title: 'Composer', text: 'Type here.' }, + { selector: '[data-tour="files"]', title: 'Files', text: 'Browse your project.' } +]) +``` + +Pass `'preview'` as the second argument to run against the page in the preview pane instead of the app. ## `todo` toolset diff --git a/website/docs/reference/toolsets-reference.md b/website/docs/reference/toolsets-reference.md index f830261c57..5eba1ea86c 100644 --- a/website/docs/reference/toolsets-reference.md +++ b/website/docs/reference/toolsets-reference.md @@ -71,7 +71,7 @@ Or in-session: | `video_gen` | `video_generate`, `xai_video_edit`, `xai_video_extend` | Text-to-video and image-to-video via plugin-registered backends (xAI Grok-Imagine, FAL.ai Veo 3.1 / Pixverse v6 / Kling O3). Pass `image_url` to animate an image; omit it for text-to-video. `xai_video_edit` / `xai_video_extend` are provider-specific edit/extend tools, gated on xAI Imagine credentials. | | `kanban` | `kanban_attach`, `kanban_attach_url`, `kanban_attachments`, `kanban_block`, `kanban_comment`, `kanban_complete`, `kanban_create`, `kanban_heartbeat`, `kanban_link`, `kanban_list`, `kanban_request_changes`, `kanban_request_review`, `kanban_show`, `kanban_unblock` | Multi-agent coordination tools. Registered for dispatcher-spawned task workers (`HERMES_KANBAN_TASK`) and for profiles that explicitly list the `kanban` toolset by name (the `all`/`*` wildcard does **not** enable it). Workers mark tasks done, request first-class review, block, heartbeat, comment, and create/link follow-up tasks; orchestrator profiles additionally get board-routing tools like list/unblock. `delegate_task` children are not Kanban run owners: their schema strips/disables this toolset and runtime guards reject direct board mutations, even if parent `HERMES_KANBAN_*` env vars are present. | | `memory` | `memory` | Persistent cross-session memory management. | -| `desktop_ui` | `close_terminal`, `focus_pane`, `open_preview`, `react_to_message`, `read_preview`, `read_terminal`, `read_window_below` | Affordances that act on the Hermes desktop app itself — read/close the embedded terminal pane, open and read the in-app browser, identify the OS window behind the app, reveal a pane, react to a message. Enabled for sessions whose source is the desktop app, whichever backend it's connected to (local, SSH, URL, or Hermes Cloud). Never present on CLI, TUI, messaging, or cron sessions. | +| `desktop_ui` | `close_terminal`, `focus_pane`, `open_preview`, `react_to_message`, `read_preview`, `read_terminal`, `read_window_below`, `tour` | Affordances that act on the Hermes desktop app itself — read/close the embedded terminal pane, open and read the in-app browser, identify the OS window behind the app, reveal a pane, react to a message, run a guided tour (highlight + narrate UI elements in the app or the preview pane). Enabled for sessions whose source is the desktop app, whichever backend it's connected to (local, SSH, URL, or Hermes Cloud). Never present on CLI, TUI, messaging, or cron sessions. | | `project` | `project_create`, `project_list`, `project_switch` | Create and switch desktop [Projects](../user-guide/cli.md) (named, multi-folder workspaces). GUI / desktop sessions only. | | `safe` | `image_generate`, `vision_analyze`, `web_extract`, `web_search` (via `includes`) | Read-only research + media generation. No file writes, no terminal, no code execution. | | `search` | `web_search` | Web search only (without extract). | From 98bbfbda6e7cedc45f30684452a121295a068c56 Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Wed, 19 Aug 2026 00:42:38 -0500 Subject: [PATCH 07/11] fix(desktop): keep a tour bound to its target across navigation and re-renders MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A tour step that moved the app deadlocked: driver.js checks waitForElement before running any hook, so the step waited for an element on a page the hook had not opened yet. The move now happens in the step's own onHighlightStarted — the one hook driver fires however a step is reached — so clicking Next, pressing an arrow key and calling the API all behave the same. Steps also re-bind themselves. driver.js holds the highlight as a node reference and re-measures it, so a poll or refetch that swapped the node left it measuring a detached element and the spotlight vanished, looking like the tour closed itself. One observer now covers both cases: the target that has not mounted yet, and the one that was replaced underneath. Orphaned overlays are swept before a tour starts, since driver.js can only tear down what its own instance built. --- apps/desktop/src/lib/tour/engine.test.ts | 280 ++++++++++++++++++++++- apps/desktop/src/lib/tour/engine.ts | 245 ++++++++++++++++++-- apps/desktop/src/lib/tour/index.ts | 3 +- apps/desktop/src/lib/tour/run-tour.ts | 66 +++++- 4 files changed, 563 insertions(+), 31 deletions(-) diff --git a/apps/desktop/src/lib/tour/engine.test.ts b/apps/desktop/src/lib/tour/engine.test.ts index 91dc8ecf5c..958e66f3a7 100644 --- a/apps/desktop/src/lib/tour/engine.test.ts +++ b/apps/desktop/src/lib/tour/engine.test.ts @@ -6,34 +6,53 @@ import { runTourEngine, type TourDriver, type TourHolder } from './engine' /** A recording fake of the driver.js surface the engine touches. */ function makeFactory(calls: string[]) { return (config?: object) => { - const steps = (config as { steps?: unknown[] } | undefined)?.steps ?? [] + const cfg = (config ?? {}) as { + onDestroyed?: () => void + onNextClick?: () => void + onPrevClick?: () => void + steps?: { onHighlightStarted?: () => void; waitForElement?: number }[] + } + + const steps = cfg.steps ?? [] let active = false let index = 0 - const instance: TourDriver = { + const enter = (at: number) => { + index = at + steps[at]?.onHighlightStarted?.() + } + + const instance: TourDriver & { clickNext: () => void; clickPrev: () => void } = { + // Stands in for the popover's own Next/Prev buttons. driver.js runs a + // configured handler if one exists, otherwise its built-in advance — + // both end up entering the step, which is what must trigger the move. + clickNext: () => (cfg.onNextClick ? cfg.onNextClick() : instance.moveNext()), + clickPrev: () => (cfg.onPrevClick ? cfg.onPrevClick() : instance.movePrevious()), destroy() { calls.push('destroy') active = false + cfg.onDestroyed?.() }, drive(stepIndex?: number) { calls.push(`drive:${stepIndex ?? 0}`) active = true - index = stepIndex ?? 0 + enter(stepIndex ?? 0) }, getActiveIndex: () => index, highlight(step: object) { calls.push(`highlight:${JSON.stringify(step)}`) active = true + ;(step as { onHighlightStarted?: () => void }).onHighlightStarted?.() }, isActive: () => active, isLastStep: () => index >= steps.length - 1, moveNext() { calls.push('next') - index += 1 + enter(index + 1) }, movePrevious() { calls.push('prev') - index -= 1 + enter(index - 1) } } @@ -41,6 +60,24 @@ function makeFactory(calls: string[]) { } } +/** A fake app: records where a tour sent it, and what it revealed. */ +function makeHost(startRoute = '/session-1') { + let route = startRoute + const panes: string[] = [] + + return { + host: { + currentRoute: () => route, + navigate: (to: string) => { + route = to + }, + revealPane: (pane: string) => void panes.push(pane) + }, + panes, + route: () => route + } +} + function seedDom() { document.body.innerHTML = ` @@ -215,3 +252,236 @@ describe('runTourEngine', () => { } }) }) + +describe('tours that move the app', () => { + it('navigates and reveals panes as their steps are entered', () => { + seedDom() + const app = makeHost('/session-1') + const holder: TourHolder = {} + + runTourEngine( + makeFactory([]), + holder, + { + kind: 'start', + steps: [ + { pane: 'sessions', title: 'Sidebar' }, + { navigate: '/artifacts', title: 'Artifacts' } + ] + }, + collectTourTargets, + document, + undefined, + app.host + ) + + // The engine moves the app itself, before driver.js sees the step — and + // exactly once per step, not once here and once from a driver hook. + expect(app.panes).toEqual(['sessions']) + expect(app.route()).toBe('/session-1') + + runTourEngine(makeFactory([]), holder, { kind: 'next' }, collectTourTargets, document, undefined, app.host) + expect(app.route()).toBe('/artifacts') + }) + + it('moves the app however the step is reached', () => { + // The class of bug this pins: the move used to live on the paths (the API, + // then the buttons), so whichever path wasn't wired advanced the text while + // the app stayed put — and the step waited forever for an element on a page + // it never opened. It now hangs off the step's own onHighlightStarted, the + // one hook driver fires for every path, so a custom or agent-authored tour + // behaves the same whether the user clicks Next, presses →, or code calls it. + seedDom() + + for (const advance of ['api', 'button', 'driver'] as const) { + const app = makeHost('/session-1') + const holder: TourHolder = {} + const factory = makeFactory([]) + + runTourEngine( + factory, + holder, + { kind: 'start', steps: [{ title: 'Intro' }, { navigate: '/artifacts', title: 'Away' }] }, + collectTourTargets, + document, + undefined, + app.host + ) + + expect(app.route(), advance).toBe('/session-1') + + if (advance === 'api') { + runTourEngine(factory, holder, { kind: 'next' }, collectTourTargets, document, undefined, app.host) + } else if (advance === 'button') { + // The popover's own Next button — driver's handler, not ours. + ;(holder.driver as unknown as { clickNext: () => void }).clickNext() + } else { + // Arrow keys and any other internal advance land here. + holder.driver?.moveNext() + } + + expect(app.route(), advance).toBe('/artifacts') + } + }) + + it('returns to where it started, however the tour ends', () => { + seedDom() + + for (const end of ['lastStep', 'dismissed'] as const) { + const app = makeHost('/session-1') + const holder: TourHolder = {} + + runTourEngine( + makeFactory([]), + holder, + { kind: 'start', steps: [{ navigate: '/artifacts', title: 'Away' }] }, + collectTourTargets, + document, + undefined, + app.host + ) + + expect(app.route()).toBe('/artifacts') + + // 'next' past the last step vs. an Esc/✕ dismissal both destroy the tour. + if (end === 'lastStep') { + runTourEngine(makeFactory([]), holder, { kind: 'next' }, collectTourTargets, document, undefined, app.host) + } else { + holder.driver?.destroy() + } + + expect(app.route(), end).toBe('/session-1') + // Nothing lingers: the slot is empty and the tour owns no other state. + expect(holder.driver, end).toBeUndefined() + } + }) + + it('leaves the route alone when no step navigates', () => { + seedDom() + const app = makeHost('/session-1') + const holder: TourHolder = {} + + runTourEngine( + makeFactory([]), + holder, + { kind: 'start', steps: [{ selector: '#send-btn', title: 'Here' }] }, + collectTourTargets, + document, + undefined, + app.host + ) + holder.driver?.destroy() + + expect(app.route()).toBe('/session-1') + }) + + it('waits for targets that mount after a step moves the app', () => { + seedDom() + const app = makeHost() + + // #not-mounted-yet does not exist at start time — it appears after the + // navigation. Neither the navigating step NOR the steps after it may fail + // selector pre-validation, and each must carry a wait. + const result = runTourEngine( + makeFactory([]), + {}, + { + kind: 'start', + steps: [ + { navigate: '/artifacts', selector: '#not-mounted-yet', title: 'Later' }, + { selector: '#also-not-here', title: 'Later still' } + ] + }, + collectTourTargets, + document, + undefined, + app.host + ) + + expect(result.success).toBe(true) + }) + + it('still rejects a bad selector when nothing moves the app', () => { + seedDom() + + const result = runTourEngine( + makeFactory([]), + {}, + { kind: 'start', steps: [{ selector: '#ghost', title: 'x' }] }, + collectTourTargets, + document, + undefined, + makeHost().host + ) + + expect(result.success).toBe(false) + expect(result.error).toContain('#ghost') + }) + + it('survives the surface re-rendering underneath it', async () => { + // The bug this pins: sitting idle on a page whose data polls/refetches used + // to kill the tour. driver.js holds the highlighted node by REFERENCE, so + // when React swapped it for an equivalent one, driver kept measuring a + // detached node (rect all zeros) and the spotlight vanished — looking like + // the tour closed itself while the user did nothing. Any list that refetches + // hits this, so it matters for curated and agent-authored tours alike. + seedDom() + const calls: string[] = [] + const holder: TourHolder = {} + + runTourEngine( + makeFactory(calls), + holder, + { kind: 'start', steps: [{ selector: '#send-btn', title: 'Send' }] }, + collectTourTargets, + document, + undefined, + makeHost().host + ) + + const drivesBefore = calls.filter(c => c.startsWith('drive:')).length + + // Simulate a refetch: the old node is replaced by an equivalent new one. + const old = document.querySelector('#send-btn')! + + old.classList.add('driver-active-element') + + const fresh = old.cloneNode(true) as HTMLElement + + old.replaceWith(fresh) + fresh.classList.remove('driver-active-element') + + // MutationObserver callbacks are microtask-scheduled, then rAF-coalesced. + await new Promise(resolve => setTimeout(resolve, 50)) + + expect(calls.filter(c => c.startsWith('drive:')).length).toBeGreaterThan(drivesBefore) + expect(holder.driver?.isActive()).toBe(true) + }) + + it('stops watching once the tour ends', async () => { + seedDom() + const calls: string[] = [] + const holder: TourHolder = {} + const factory = makeFactory(calls) + + runTourEngine( + factory, + holder, + { kind: 'start', steps: [{ selector: '#send-btn', title: 'Send' }] }, + collectTourTargets, + document, + undefined, + makeHost().host + ) + runTourEngine(factory, holder, { kind: 'stop' }, collectTourTargets, document, undefined, makeHost().host) + + const after = calls.length + const node = document.querySelector('#send-btn')! + + node.replaceWith(node.cloneNode(true)) + await new Promise(resolve => setTimeout(resolve, 50)) + + // No re-drive attempts once it's over. + expect(calls.length).toBe(after) + }) +}) diff --git a/apps/desktop/src/lib/tour/engine.ts b/apps/desktop/src/lib/tour/engine.ts index 2a2c9ca364..ac5fb88780 100644 --- a/apps/desktop/src/lib/tour/engine.ts +++ b/apps/desktop/src/lib/tour/engine.ts @@ -17,6 +17,9 @@ export interface TourDriver { destroy: () => void drive: (stepIndex?: number) => void getActiveIndex: () => number | undefined + /** driver.js's own state bag. Used to read the live, eased stage rect so a + * companion layer can travel with the cutout instead of jumping ahead. */ + getState?: (key?: string) => unknown highlight: (step: object) => void isActive: () => boolean isLastStep: () => boolean @@ -26,21 +29,52 @@ export interface TourDriver { export type TourDriverFactory = (config?: object) => TourDriver +/** Look-and-feel passed into every driver instance: the scrim, how the cutout + * hugs the highlighted element, and the transition speed. Surface-supplied so + * the app can match its own overlay tokens while a guest page keeps + * driver.js's defaults. */ +export interface TourStyle { + duration?: number + overlayColor?: string + overlayOpacity?: number + popoverOffset?: number + stagePadding?: number + stageRadius?: number +} + /** Where a surface keeps its live instance between actions (module state in * the app, a window global in the preview page). */ export interface TourHolder { driver?: TourDriver + /** Tears down the keep-alive observer. Runs with the driver. */ + release?: () => void } -/** One highlighted moment: an element, and what to say about it. Omit the - * selector for a centered narration step. */ +/** One highlighted moment: an element, what to say about it, and optionally + * where the app must be for the element to exist. `navigate` (a route path) + * and `pane` (a desktop pane name) run before the step is shown; the host + * supplies the actual navigation (see TourHost), so the engine itself stays + * self-contained and portable to a guest page. */ export interface TourStep { + navigate?: string + pane?: string selector?: string side?: 'top' | 'right' | 'bottom' | 'left' text?: string title?: string } +/** How the engine reaches the app around it. Omitted on the preview surface, + * where a guest page has neither routes nor panes. */ +export interface TourHost { + /** Where the app is right now, so the tour can put it back when it ends. */ + currentRoute?: () => string + /** Go to a route path. */ + navigate?: (to: string) => void + /** Reveal a desktop pane by name. */ + revealPane?: (pane: string) => void +} + /** A normalized action. `kind` is the verb; the rest is per-verb payload. */ export interface TourAction extends TourStep { kind: 'targets' | 'show' | 'start' | 'next' | 'prev' | 'stop' @@ -67,28 +101,150 @@ export function runTourEngine( holder: TourHolder, action: TourAction, collectTargets: (doc: Document, max: number) => TourTarget[], - doc: Document + doc: Document, + style?: TourStyle, + host?: TourHost ): TourResult { const kind = action.kind + const base = { animate: true, smoothScroll: true, ...(style || {}) } - const popoverOf = (step: TourStep) => + /** driver.js reads `popoverClass` off the POPOVER object, not off the step + * (`r.popoverClass` where r = step.popover), so the entrance animation has + * to be declared in here. `first` settles down into place, every step after + * rises — styled in app-tour.css. */ + const popoverOf = (step: TourStep, first = false) => step.title || step.text - ? { description: step.text || '', side: step.side || undefined, title: step.title || '' } + ? { + description: step.text || '', + popoverClass: first ? 'tour-pop-in' : 'tour-pop-next', + side: step.side || undefined, + title: step.title || '' + } : undefined - const stepOf = (step: TourStep) => ({ element: step.selector || undefined, popover: popoverOf(step) }) + /** Move the app where a step needs to be. + * + * Called from `onHighlightStarted`, which driver.js fires for EVERY way a + * step can be reached — the API, its own Next/Prev buttons, arrow keys, + * `drive(i)`. Hooking the paths individually is what let a user clicking + * Next (or pressing →) advance the text while the app never navigated, so + * the step sat waiting for an element on a page it never opened. One hook, + * no path can skip it. */ + const moveFor = (step: TourStep) => { + if (step.pane && host?.revealPane) { + host.revealPane(step.pane) + } - /** Selectors that match nothing right now — the caller's cue to re-scan. */ - const unmatched = (steps: TourStep[]) => - steps - .map(step => step.selector) - .filter((selector): selector is string => { - try { - return !!selector && !doc.querySelector(selector) - } catch { - return true + if (step.navigate && host?.navigate) { + host.navigate(step.navigate) + } + + // No waiting here: a target that mounts after the move is picked up by the + // keep-alive below, which re-drives the step the moment the element exists. + // driver.js's own `waitForElement` can't do the job — it returns BEFORE the + // hooks run, so the step would wait for an element on a page this hook was + // about to open, which is the deadlock that looked like a freeze. + } + + /** Keep the current step bound to a LIVE node. + * + * Covers the two ways a step's element goes missing under it: + * + * - It hasn't mounted yet, because the step just navigated somewhere. + * - It mounted, then the surface re-rendered — a poll, a refetch, a list + * reordering — and React swapped the node. driver.js holds the highlight + * as a node REFERENCE and re-measures it with getBoundingClientRect(), so + * a detached node measures all zeros: the spotlight collapses and the + * tour looks like it closed itself while the user did nothing. + * + * Both are "the element the step wants isn't the element driver is holding", + * so both are fixed the same way: re-drive the step to rebind. */ + const bindKeepAlive = (steps: TourStep[]) => { + let queued = false + + // Coalesce a mutation burst into one check on the next frame. Falls back to + // a timeout where rAF is absent (jsdom, and any host page without it) — + // this module is stringified into the preview webview, so it can't assume + // browser globals beyond the DOM. + const soon = (fn: () => void) => { + if (typeof requestAnimationFrame === 'function') { + requestAnimationFrame(fn) + } else { + setTimeout(fn, 16) + } + } + + const observer = new MutationObserver(() => { + if (queued) { + return + } + + queued = true + soon(() => { + queued = false + + const driver = holder.driver + + if (!driver?.isActive()) { + return } + + const index = driver.getActiveIndex() ?? 0 + const selector = steps[index]?.selector + + if (!selector) { + return + } + + const wanted = doc.querySelector(selector) + + // Nothing to bind to yet — a navigating step whose page is still + // rendering. The next mutation brings us back. + if (!wanted) { + return + } + + // Already on the right node: nothing to do. This is the common case, + // so it stays a single identity check per mutation batch. + if (wanted === doc.querySelector('.driver-active-element')) { + return + } + + driver.drive(index) }) + }) + + observer.observe(doc.body, { childList: true, subtree: true }) + + return () => observer.disconnect() + } + + /** Every step carries its move on `onHighlightStarted`, the one hook driver + * fires no matter how the step was reached. */ + const stepOf = (step: TourStep, first = false) => ({ + element: step.selector || undefined, + onHighlightStarted: () => moveFor(step), + popover: popoverOf(step, first) + }) + + /** Selectors that match nothing right now — the caller's cue to re-scan. + * + * Skipped entirely once any step moves the app: from that point the later + * steps' targets legitimately don't exist yet (they mount on the page the + * tour is about to open), so pre-validating them would reject a correct + * tour. driver.js waits for each one via `waitForElement` instead. */ + const unmatched = (steps: TourStep[]) => + steps.some(step => step.navigate || step.pane) + ? [] + : steps + .map(step => step.selector) + .filter((selector): selector is string => { + try { + return !!selector && !doc.querySelector(selector) + } catch { + return true + } + }) const missing = (selectors: string[]): TourResult => ({ error: 'No element matches selector(s): ' + selectors.join(', '), @@ -105,6 +261,22 @@ export function runTourEngine( } } + /** Remove any driver DOM this engine no longer owns. + * + * driver.js tears itself down through the instance that built it, so an + * instance we lose our handle to — a hot reload, a double install, an + * exception between create and store — leaves its overlay and popover on + * screen forever. They then sit ON TOP of the next tour: the new step is + * running underneath a stale popover, which reads as "the tour froze". + * Cheap to check, and the only way to guarantee a clean start. */ + const clearOrphans = () => { + for (const node of doc.querySelectorAll('.driver-popover, svg.driver-overlay')) { + node.remove() + } + + doc.body.classList.remove('driver-active', 'driver-fade', 'driver-simple', 'driver-no-scroll') + } + if (kind === 'show') { const gone = unmatched([action]) @@ -113,10 +285,12 @@ export function runTourEngine( } if (!holder.driver) { - holder.driver = factory({ animate: true, smoothScroll: true }) + clearOrphans() + holder.driver = factory(base) } - holder.driver.highlight(stepOf(action)) + // A one-off highlight is its own arrival, so it uses the settle-down enter. + holder.driver.highlight(stepOf(action, true)) return { action: kind, success: true } } @@ -133,14 +307,38 @@ export function runTourEngine( holder.driver.destroy() } + // Whatever the previous tour left behind goes now, so this one isn't + // rendered underneath a stale popover. + clearOrphans() + const startAt = action.startAt || 0 + // A tour that navigates must hand the app back. Captured before the first + // step moves anywhere, and restored on EVERY exit — Esc, the ✕, an overlay + // click, and the last step all funnel through onDestroyed. + const origin = steps.some(step => step.navigate) ? host?.currentRoute?.() : undefined + holder.driver = factory({ - animate: true, + ...base, + onDestroyed: () => { + holder.driver = undefined + holder.release?.() + holder.release = undefined + + if (origin !== undefined && host?.navigate && host.currentRoute?.() !== origin) { + host.navigate(origin) + } + }, showProgress: steps.length > 1, - smoothScroll: true, - steps: steps.map(stepOf) + // Each step moves the app from its own onHighlightStarted, so buttons, + // arrow keys and the API all take the same path (see moveFor). + steps: steps.map((step, i) => stepOf(step, i === startAt)) }) + + // Survive the surface re-rendering underneath the tour (see bindKeepAlive). + holder.release?.() + holder.release = bindKeepAlive(steps) + holder.driver.drive(startAt) return { action: kind, activeStep: startAt, steps: steps.length, success: true } @@ -160,6 +358,8 @@ export function runTourEngine( return { action: kind, done: true, success: true } } + // No move here: driver fires the step's own onHighlightStarted, which is + // where every path — this one, the buttons, arrow keys — does the moving. if (kind === 'next') { driver.moveNext() } else { @@ -175,6 +375,11 @@ export function runTourEngine( holder.driver = undefined } + // Belt and braces: destroy() only cleans up what THIS instance built. + clearOrphans() + holder.release?.() + holder.release = undefined + return { action: kind, success: true } } diff --git a/apps/desktop/src/lib/tour/index.ts b/apps/desktop/src/lib/tour/index.ts index d70b9b8b9c..248fffea50 100644 --- a/apps/desktop/src/lib/tour/index.ts +++ b/apps/desktop/src/lib/tour/index.ts @@ -21,8 +21,9 @@ */ export { collectTourTargets, type TourTarget } from './collect-targets' -export type { TourAction, TourResult, TourStep } from './engine' +export type { TourAction, TourHost, TourResult, TourStep } from './engine' export { + isTourActive, listTourTargets, nextTourStep, previousTourStep, diff --git a/apps/desktop/src/lib/tour/run-tour.ts b/apps/desktop/src/lib/tour/run-tour.ts index 8634cc143e..88df01d9ab 100644 --- a/apps/desktop/src/lib/tour/run-tour.ts +++ b/apps/desktop/src/lib/tour/run-tour.ts @@ -17,28 +17,84 @@ import './app-tour.css' import { driver as driverFactory } from 'driver.js' import { runPreviewTour } from '@/app/chat/right-rail/preview-tour' +import { revealDesktopPane } from '@/store/pane-focus' import { collectTourTargets } from './collect-targets' -import { runTourEngine, type TourAction, type TourHolder, type TourResult, type TourStep } from './engine' +import { + runTourEngine, + type TourAction, + type TourHolder, + type TourHost, + type TourResult, + type TourStep, + type TourStyle +} from './engine' +import { type Stage, stopSpotlightBlur, syncSpotlightBlur } from './spotlight-blur' /** Which document a tour runs against. */ export type TourSurface = 'app' | 'preview' -/** The app surface's live driver instance, reused across actions. */ +/** The app around the tour, consumed straight from what the app already + * exposes: HashRouter means a route IS `location.hash`, and pane reveals are + * `revealDesktopPane` (the same path the focus_pane tool drives). Nothing is + * registered and nothing persists — a step reads these while it runs. */ +const APP_HOST: TourHost = { + currentRoute: () => window.location.hash.replace(/^#/, '') || '/', + navigate: to => { + window.location.hash = to + }, + revealPane: pane => void revealDesktopPane(pane) +} + +/** The app's own overlay treatment: a softly rounded cutout and a transition + * slow enough to read as travel between steps. The fade itself — scrim colour, + * strength, and the desaturation of everything outside the spotlight — lives + * in app-tour.css, so both layers are tuned in one place and follow the theme + * (light fades toward white, dark toward near-black). */ +const TOUR_STYLE: TourStyle = { + duration: 520, + popoverOffset: 8, + stagePadding: 6, + stageRadius: 8 +} + +/** The one live tour, if any. This is the ONLY thing that outlives an action, + * and it holds a driver instance rather than a copy of any app state — the + * origin route a navigating tour restores lives in that instance's own + * closure, so it dies with the tour. `onDestroyed` empties this slot however + * the tour ended (Esc, ✕, overlay click, last step), leaving nothing behind. */ const appHolder: TourHolder = {} /** Run one tour action on `surface`. Never throws — failures come back as * `{success: false, error}` so a caller (or the agent) can recover. */ export async function runTour(action: TourAction, surface: TourSurface = 'app'): Promise { try { - return surface === 'preview' - ? await runPreviewTour(action) - : runTourEngine(driverFactory, appHolder, action, collectTourTargets, document) + if (surface === 'preview') { + return await runPreviewTour(action) + } + + const result = runTourEngine(driverFactory, appHolder, action, collectTourTargets, document, TOUR_STYLE, APP_HOST) + + // Mirror driver.js's cutout onto a blur layer for as long as the tour is + // up, and drop the whole thing once it isn't. The layer reads driver's own + // per-frame stage rect, so it eases between steps exactly like the cutout. + if (isTourActive()) { + syncSpotlightBlur(() => (appHolder.driver?.getState?.('__activeStagePosition') as null | Stage) ?? null) + } else { + stopSpotlightBlur() + } + + return result } catch (error) { return { error: error instanceof Error ? error.message : String(error), success: false } } } +/** Whether a tour is currently on screen (app surface). The user can dismiss a + * tour with Esc, the ✕, or an overlay click, so a caller must never track that + * with its own flag — ask here. */ +export const isTourActive = (): boolean => appHolder.driver?.isActive() ?? false + /** What's on screen right now, durable (`stable`) handles first. */ export const listTourTargets = (surface?: TourSurface) => runTour({ kind: 'targets' }, surface) From d433a452cc9c1c04cc4f66191a238296c5894d10 Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Wed, 19 Aug 2026 00:42:48 -0500 Subject: [PATCH 08/11] feat(desktop): give tours a themed spotlight and directional motion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The stock driver.js look is replaced with the app's own: unfocused UI fades toward var(--background) and desaturates, so it recedes in light and dark without a mode branch. The dimming is masked to a feathered cutout that tracks driver's eased stage rect each frame, keeping the highlighted element crisp — a plain backdrop-filter blurs the spotlight too, because it clips to the element box rather than the cutout. Popovers enter from wherever they land: left, right, above or below their target, and a shorter settle for centered narration steps, which have nothing beside them to measure against. Travel, duration and easing are tokens on .driver-popover, and the whole thing collapses to a fade under prefers-reduced-motion. --- apps/desktop/src/lib/tour/app-tour.css | 198 +++++++++++++++++--- apps/desktop/src/lib/tour/spotlight-blur.ts | 191 +++++++++++++++++++ 2 files changed, 360 insertions(+), 29 deletions(-) create mode 100644 apps/desktop/src/lib/tour/spotlight-blur.ts diff --git a/apps/desktop/src/lib/tour/app-tour.css b/apps/desktop/src/lib/tour/app-tour.css index 84cd7dd35b..2c378712ea 100644 --- a/apps/desktop/src/lib/tour/app-tour.css +++ b/apps/desktop/src/lib/tour/app-tour.css @@ -1,72 +1,212 @@ -/* Theme bridge for the APP surface's tour popovers: driver.js ships a fixed - light palette, so repaint it with the app's own tokens and it follows every - theme (including custom skins) for free. Scoped to driver.js's classes. +/* Hermes surface treatment for the APP surface's tour popovers. - The preview surface keeps the stock look on purpose — it renders inside a - guest page where these variables don't exist. */ + driver.js ships a fixed light palette, a heavy drop shadow, and 19px/14px + type — none of which is how this app draws a floating popover. Repaint it + with the popover primitive's own recipe (components/ui/popover.tsx): a glass + fill over --ui-bg-elevated, a single --ui-stroke-secondary hairline, and NO + shadow. Radius and type follow the app scale, which is near-square + (--radius-scalar: 0.2) and 12px-based. + + The scrim and the cutout geometry are config, not CSS — see TOUR_STYLE in + run-tour.ts. + + The preview surface keeps the stock look on purpose: it renders inside a + guest page where none of these variables exist. */ .driver-popover { - background-color: var(--color-popover); - border: 1px solid var(--color-border); - border-radius: var(--radius-md); - box-shadow: var(--shadow-nous); - color: var(--color-popover-foreground); + --tour-surface: color-mix(in srgb, var(--ui-bg-elevated) 92%, transparent); + + backdrop-filter: blur(12px); + background-color: var(--tour-surface); + border: 1px solid var(--ui-stroke-secondary); + border-radius: var(--radius-lg); + box-shadow: none; + color: var(--foreground); font-family: var(--font-sans); + max-width: 20rem; + min-width: 15rem; + padding: 0.75rem; } .driver-popover-title { - font-size: 0.875rem; + font-size: 0.75rem; font-weight: 600; - line-height: 1.4; + letter-spacing: -0.01em; + line-height: 1rem; +} + +.driver-popover-title[style*='block'] + .driver-popover-description { + margin-top: 0.25rem; } .driver-popover-description { - color: var(--color-muted-foreground); - font-size: 0.8125rem; + color: var(--ui-text-secondary); + font-size: 0.75rem; + line-height: 1.15rem; +} + +.driver-popover-footer { + gap: 0.75rem; + margin-top: 0.75rem; } .driver-popover-progress-text { - color: var(--color-muted-foreground); - font-size: 0.75rem; + color: var(--ui-text-tertiary); + font-size: 0.6875rem; + font-variant-numeric: tabular-nums; } .driver-popover-close-btn { - color: var(--color-muted-foreground); + color: var(--ui-text-tertiary); + transition: color 100ms; } .driver-popover-close-btn:hover, .driver-popover-close-btn:focus { - color: var(--color-foreground); + color: var(--foreground); } +/* Matches the Button `secondary` + `xs` shape: 12px/1rem medium, 2.5px radius. */ .driver-popover-footer-btn { - background-color: var(--color-secondary); - border-color: var(--color-border); - border-radius: var(--radius-sm); - color: var(--color-secondary-foreground); + background-color: var(--ui-bg-quaternary); + border: none; + border-radius: 2.5px; + color: var(--foreground); font-family: var(--font-sans); + font-size: 0.75rem; + font-weight: 500; + line-height: 1rem; + padding: 0.1875rem 0.5rem; text-shadow: none; + transition: background-color 100ms; } .driver-popover-footer-btn:hover, .driver-popover-footer-btn:focus { - background-color: var(--color-accent); - color: var(--color-accent-foreground); + background-color: var(--ui-control-hover-background); } -/* Each arrow variant paints exactly one border edge; the rest are transparent. */ +.driver-popover-navigation-btns button + button { + margin-left: 0.25rem; +} + +/* The arrow is a CSS border triangle, so it can't share the body's + backdrop-blur — paint it with the opaque token underneath the glass instead. + Each variant colors exactly one edge; the rest stay transparent. */ .driver-popover-arrow-side-left { - border-left-color: var(--color-popover); + border-left-color: var(--ui-bg-elevated); } .driver-popover-arrow-side-right { - border-right-color: var(--color-popover); + border-right-color: var(--ui-bg-elevated); } .driver-popover-arrow-side-top { - border-top-color: var(--color-popover); + border-top-color: var(--ui-bg-elevated); } .driver-popover-arrow-side-bottom { - border-bottom-color: var(--color-popover); + border-bottom-color: var(--ui-bg-elevated); +} + +/* THE FADE — everything that isn't the spotlight recedes. + + Two layers, both themed, both live-editable here: + 1. driver.js's own scrim path, repainted from the app background so light + mode fades toward white and dark toward near-black (no mode branch — + --background already resolves per theme). + 2. The companion layer (spotlight-blur.ts), which carries the feathered + edge and desaturates what's behind it. */ +.driver-overlay path { + fill: var(--background) !important; + opacity: 0.8; +} + +#__hermes-tour-spotlight-blur { + backdrop-filter: grayscale(1) opacity(0.55); + -webkit-backdrop-filter: grayscale(1) opacity(0.55); +} + +/* Popover entrance, in two flavors — both slide AND fade. + + The tour ARRIVES by settling DOWN into place. Every step after slides in + from the LEFT, so the sideways nudge reads as "next" (like turning a page) + rather than repeating the arrival. + + Easing is the app's own enter curve (`thread-jump-in`, the transform + transitions, the opacity fades) — NOT expo. Expo-out dumps ~70% of the + travel in the first ~50ms and crawls through the rest, which is why a + longer distance felt snappy-then-sludgy and the fade looked like it wasn't + happening at all: opacity was ~0.95 before the eye caught it. + + driver.js builds a fresh popover node per step, so both re-trigger for free. + + `!important` because driver's own `.driver-fade .driver-popover` rule sets a + plain fade on the same element and would otherwise win on order. */ +.driver-popover { + --tour-pop-travel: 10px; + /* Centered steps have no neighbour to measure against — see the side rules. */ + --tour-pop-travel-centered: 5px; + --tour-pop-duration: 340ms; + --tour-pop-ease: cubic-bezier(0.22, 1, 0.36, 1); +} + +@keyframes tour-pop-in { + from { + opacity: 0; + transform: translateY(calc(var(--tour-pop-travel) * -1)); + } +} + +/* One keyframe, direction supplied by the vars below. */ +@keyframes tour-pop-next { + from { + opacity: 0; + transform: translate(var(--tour-pop-x, 0), var(--tour-pop-y, 0)); + } +} + +/* Enter from the side the popover LANDED on, so the motion agrees with the + layout instead of fighting it: a popover to the left of its target drifts in + from the left, one below its target rises up into it. driver.js sets these + side classes as it positions each step, so the rule follows placement + automatically — including when it flips a step to avoid a screen edge. + + The centered case (`side-over`, an element-less narration step) gets its own + shorter travel. With no target beside it, nothing anchors the eye, so the + same 10px that reads as a nudge next to an element reads as a real slide out + in the open. */ +.driver-popover.tour-pop-next.driver-popover-side-left { + --tour-pop-x: calc(var(--tour-pop-travel) * -1); +} + +.driver-popover.tour-pop-next.driver-popover-side-right { + --tour-pop-x: var(--tour-pop-travel); +} + +.driver-popover.tour-pop-next.driver-popover-side-top { + --tour-pop-y: calc(var(--tour-pop-travel) * -1); +} + +.driver-popover.tour-pop-next.driver-popover-side-bottom { + --tour-pop-y: var(--tour-pop-travel); +} + +.driver-popover.tour-pop-next.driver-popover-side-over { + --tour-pop-y: var(--tour-pop-travel-centered); +} + +.driver-popover.tour-pop-in { + animation: tour-pop-in var(--tour-pop-duration) var(--tour-pop-ease) !important; +} + +.driver-popover.tour-pop-next { + animation: tour-pop-next var(--tour-pop-duration) var(--tour-pop-ease) !important; +} + +@media (prefers-reduced-motion: reduce) { + .driver-popover.tour-pop-in, + .driver-popover.tour-pop-next { + animation: none; + } } diff --git a/apps/desktop/src/lib/tour/spotlight-blur.ts b/apps/desktop/src/lib/tour/spotlight-blur.ts new file mode 100644 index 0000000000..71a2fc76ce --- /dev/null +++ b/apps/desktop/src/lib/tour/spotlight-blur.ts @@ -0,0 +1,191 @@ +/** + * SPOTLIGHT BLUR — a blurred scrim that keeps the highlighted element crisp. + * + * driver.js paints its scrim as ONE full-viewport whose fill path has the + * spotlight punched out. A `backdrop-filter` on that element blurs the cutout + * too, because backdrop-filter clips to the element's BOX, not its fill — which + * is why the highlighted control came out fuzzy. + * + * So the blur goes on its own layer, masked to everything-except-the-spotlight. + * Two details make it not look cheap: + * + * - The mask is an SVG whose hole is a ROUNDED rect run through a + * feGaussianBlur, so the blur fades out across a soft band instead of + * ending on a hard edge. (`clip-path` can't do this — it's binary. A + * data-URI mask can, but rebuilding and reparsing that string every frame + * is wasteful; an inline mask lets a frame be four attribute writes.) + * - The hole follows driver.js's OWN animated rect (`__activeStagePosition`, + * eased per frame by driver itself) rather than the target's static box, + * so the blur travels with the cutout between steps instead of jumping to + * the destination while the cutout is still gliding. + * + * App surface only — a preview guest page keeps driver.js's stock look. + */ + +/** Matches DialogOverlay's scrim treatment. The actual effect (grayscale/fade) + * lives in app-tour.css so it can be tuned in one place. */ +const FEATHER_PX = 12 + +/** Matches TOUR_STYLE.stagePadding/stageRadius, so the soft hole sits over + * driver's own cutout rather than beside it. */ +const STAGE_PADDING = 6 +const STAGE_RADIUS = 8 + +const LAYER_ID = '__hermes-tour-spotlight-blur' +const MASK_ID = '__hermes-tour-spotlight-mask' +const SVG_NS = 'http://www.w3.org/2000/svg' + +/** One rect's worth of geometry — driver's stage, or an element's box. */ +export interface Stage { + height: number + width: number + x: number + y: number +} + +/** Reads driver.js's live (animated) stage rect. Supplied by run-tour. */ +type StageSource = () => null | Stage + +let frame = 0 +let stageSource: StageSource | undefined +let hole: SVGRectElement | undefined +let outer: SVGRectElement | undefined + +function teardownDom(): void { + document.getElementById(LAYER_ID)?.remove() + document.getElementById(`${LAYER_ID}-defs`)?.remove() + hole = undefined + outer = undefined +} + +/** The blur layer plus the mask that shapes it. Built once per tour. */ +function mount(): void { + if (document.getElementById(LAYER_ID)) { + return + } + + const svg = document.createElementNS(SVG_NS, 'svg') + + svg.id = `${LAYER_ID}-defs` + svg.setAttribute('aria-hidden', 'true') + svg.style.cssText = 'position:fixed;width:0;height:0;pointer-events:none' + + const mask = document.createElementNS(SVG_NS, 'mask') + + mask.id = MASK_ID + // Viewport coordinates, so the rects below take plain CSS pixels. + mask.setAttribute('maskUnits', 'userSpaceOnUse') + + const filter = document.createElementNS(SVG_NS, 'filter') + + filter.id = `${MASK_ID}-feather` + + // Roomy region: a blur clipped to the shape's own box would square off the + // very edge we're trying to soften. + for (const [name, value] of [ + ['x', '-50%'], + ['y', '-50%'], + ['width', '200%'], + ['height', '200%'] + ]) { + filter.setAttribute(name, value) + } + + const blur = document.createElementNS(SVG_NS, 'feGaussianBlur') + + blur.setAttribute('stdDeviation', String(FEATHER_PX / 2)) + filter.appendChild(blur) + + // White shows the blur, black hides it: paint everything, then punch a + // feathered hole where the spotlight is. + outer = document.createElementNS(SVG_NS, 'rect') + outer.setAttribute('fill', 'white') + + hole = document.createElementNS(SVG_NS, 'rect') + hole.setAttribute('fill', 'black') + hole.setAttribute('rx', String(STAGE_RADIUS + STAGE_PADDING / 2)) + hole.setAttribute('filter', `url(#${filter.id})`) + + mask.append(outer, hole) + svg.append(filter, mask) + document.body.appendChild(svg) + + const layer = document.createElement('div') + + layer.id = LAYER_ID + layer.setAttribute('aria-hidden', 'true') + layer.style.cssText = [ + 'position:fixed', + 'inset:0', + 'pointer-events:none', + // Under driver.js's own overlay (10000) so the scrim tint reads on top of + // this, and far under the popover, which stays perfectly sharp. + 'z-index:9998', + `mask:url(#${MASK_ID})`, + `-webkit-mask:url(#${MASK_ID})` + ].join(';') + + document.body.appendChild(layer) +} + +/** Move the feathered hole onto `stage`. Four attribute writes. */ +function paint(stage: null | Stage): void { + if (!hole || !outer) { + return + } + + outer.setAttribute('width', String(window.innerWidth)) + outer.setAttribute('height', String(window.innerHeight)) + + if (!stage) { + // A narration step highlights nothing: blur everything, no hole. + hole.setAttribute('width', '0') + hole.setAttribute('height', '0') + + return + } + + hole.setAttribute('x', String(stage.x - STAGE_PADDING)) + hole.setAttribute('y', String(stage.y - STAGE_PADDING)) + hole.setAttribute('width', String(Math.max(0, stage.width + STAGE_PADDING * 2))) + hole.setAttribute('height', String(Math.max(0, stage.height + STAGE_PADDING * 2))) +} + +/** Follow the stage every frame — driver eases it, we just mirror it. */ +function tick(): void { + frame = requestAnimationFrame(tick) + + if (!document.querySelector('svg.driver-overlay')) { + // The tour ended (last step, Esc, ✕, overlay click). + stopSpotlightBlur() + + return + } + + mount() + paint(stageSource?.() ?? null) +} + +/** + * Track the live spotlight with a blurred, soft-edged layer. Idempotent: safe + * to call on every tour action. Everything it creates dies with driver.js's + * overlay, however the tour ended, so nothing lingers between tours. + */ +export function syncSpotlightBlur(stage: StageSource): void { + stageSource = stage + + if (!frame) { + frame = requestAnimationFrame(tick) + } +} + +/** Stop following and remove the layer. */ +export function stopSpotlightBlur(): void { + if (frame) { + cancelAnimationFrame(frame) + frame = 0 + } + + stageSource = undefined + teardownDom() +} From 702d7bacc9226594f23093b35011c864060d3b8b Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Wed, 19 Aug 2026 00:42:57 -0500 Subject: [PATCH 09/11] feat(desktop): name the app's shared surfaces for tours Tours address elements by selector, and a positional nth-child path breaks on the next re-render. These are the durable handles, applied at the shared primitive rather than per screen: every route overlay's nav and its rows, every settings field (keyed by its config schema key, so new fields are named for free), the filter tabs on any search shell page, and artifact cards. One edit per primitive covers every screen built from it, which keeps the tour vocabulary small enough to stay accurate. --- apps/desktop/src/app/artifacts/index.tsx | 5 ++++- .../src/app/overlays/overlay-split-layout.tsx | 19 ++++++++++++++++++- apps/desktop/src/app/page-search-shell.tsx | 8 +++++++- .../desktop/src/app/settings/config-field.tsx | 11 ++++++++++- apps/desktop/src/app/settings/primitives.tsx | 5 ++++- .../src/components/ui/tab-dropdown.tsx | 9 ++++++++- 6 files changed, 51 insertions(+), 6 deletions(-) diff --git a/apps/desktop/src/app/artifacts/index.tsx b/apps/desktop/src/app/artifacts/index.tsx index 07f2cc7048..73321f5ae7 100644 --- a/apps/desktop/src/app/artifacts/index.tsx +++ b/apps/desktop/src/app/artifacts/index.tsx @@ -492,7 +492,10 @@ function ArtifactImageCard({ artifact, failedImage, onImageError, onOpenChat }: }, [artifact.href, artifact.id, artifact.value, onImageError]) return ( -
+
{children} @@ -97,6 +103,7 @@ export function OverlayMain({ children, className }: OverlayMainProps) { export const OverlayNavItem = memo(function OverlayNavItem({ active, icon: Icon, + id, label, nested, onClick, @@ -114,6 +121,9 @@ export const OverlayNavItem = memo(function OverlayNavItem({ ? 'border-(--ui-stroke-tertiary) bg-(--ui-bg-tertiary) text-foreground' : 'border-transparent bg-transparent text-(--ui-text-secondary) hover:bg-(--chrome-action-hover) hover:text-foreground' )} + // Names the row by its own id, so a tour can address one link + // (`[data-tour="nav-models"]`) instead of guessing at nth-child. + data-tour={id ? `nav-${id}` : undefined} onClick={onClick} type="button" > @@ -159,13 +169,20 @@ export function OverlayNav({ footer, groups }: { footer?: ReactNode; groups: Ove {groups.map(group => ( {group.gapBefore &&
} - + {group.children && group.active && (
{group.children.map(child => ( )}
- {hasTabs ? : } + {hasTabs ? ( +
+ +
+ ) : ( + + )}
{searchTrailingAction}
)} diff --git a/apps/desktop/src/app/settings/config-field.tsx b/apps/desktop/src/app/settings/config-field.tsx index 21e4678722..dc645d06ba 100644 --- a/apps/desktop/src/app/settings/config-field.tsx +++ b/apps/desktop/src/app/settings/config-field.tsx @@ -74,8 +74,17 @@ export function ConfigField({ description ) + // Every config row is addressable by its canonical schema key, so a tour can + // point at one setting (`[data-tour="field-model"]`) without hunting through + // the section for an nth-child path. See lib/tour. const row = (action: ReactNode, wide = false) => ( - + ) // `fallback_providers` is a list of {provider, model} objects; the generic diff --git a/apps/desktop/src/app/settings/primitives.tsx b/apps/desktop/src/app/settings/primitives.tsx index 59f3e1fe00..ab875ed703 100644 --- a/apps/desktop/src/app/settings/primitives.tsx +++ b/apps/desktop/src/app/settings/primitives.tsx @@ -111,6 +111,7 @@ export function ListRow({ hint, action, below, + 'data-tour': dataTour, id, wide = false, className @@ -120,6 +121,8 @@ export function ListRow({ hint?: ReactNode action?: ReactNode below?: ReactNode + /** Durable handle for tours (see lib/tour) — usually the field's schema key. */ + 'data-tour'?: string id?: string wide?: boolean className?: string @@ -128,7 +131,7 @@ export function ListRow({ // Container-queried, not viewport-queried: the label/control split keys on // the row's own pane width, so a narrow detail column (messaging, split // views) stacks instead of squishing the label against minmax(15rem,…). -
+
{tabs.map(tab => ( - onChange(tab.id)}> + onChange(tab.id)} + > {tab.label} {tab.meta !== undefined && {tabMetaContent(tab.meta)}} From f0d0971899ebe5d0b6165615ba937261bf5c94d5 Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Wed, 19 Aug 2026 00:43:06 -0500 Subject: [PATCH 10/11] feat(desktop): add a dev-only tour demo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Looking at the tour UI needed an agent turn per iteration. This adds a demo that walks the Artifacts page — a route step, a late-mounting target, per-step narration, the return trip — behind three triggers: a floating button, Ctrl+Shift+X, and a palette row. The button is not redundant; a chord can be eaten by a menu accelerator or the main process before the renderer sees it. DEV-gated and dynamically imported, so it is absent from production builds. --- apps/desktop/src/app/contrib/dev/tour-demo.ts | 224 ++++++++++++++++++ apps/desktop/src/app/contrib/wiring.tsx | 16 +- apps/desktop/src/lib/icons.ts | 2 + 3 files changed, 234 insertions(+), 8 deletions(-) create mode 100644 apps/desktop/src/app/contrib/dev/tour-demo.ts diff --git a/apps/desktop/src/app/contrib/dev/tour-demo.ts b/apps/desktop/src/app/contrib/dev/tour-demo.ts new file mode 100644 index 0000000000..943f02e6af --- /dev/null +++ b/apps/desktop/src/app/contrib/dev/tour-demo.ts @@ -0,0 +1,224 @@ +// Dev-only: eyeball the tour UI without asking the agent for one. +// +// Three triggers, all the same toggle: a floating button (bottom-left), the +// Ctrl+Shift+X chord, and a ⌘K row. The button exists because a chord can be +// swallowed before the renderer ever sees it — by a menu accelerator, a +// main-process before-input-event hook, or the OS — and a demo you can't +// reliably open is worse than no demo. +// +// The steps walk the Artifacts page: a route step, a late-mounting target, +// per-step narration, and the return trip on exit. That covers the whole +// feature on a surface every user has, which is what the agent does when +// asked "how does X work?". +// +// Installed only under `import.meta.env.DEV` (see contrib/wiring.tsx), so none +// of this ships in a production build. + +import { PALETTE_AREA, type PaletteContribution } from '@/app/command-palette/contrib' +import { ARTIFACTS_ROUTE } from '@/app/routes' +import { registry } from '@/contrib/registry' +import { Compass } from '@/lib/icons' +import { isTourActive, startTour, stopTour, type TourStep } from '@/lib/tour' + +const BUTTON_ID = '__hermes-tour-demo-button' + +/** + * The demo tour: the Artifacts page, start to finish. + * + * A realistic walkthrough rather than a style swatch — it navigates to a page, + * explains that page's nav, then explains one item on it, and hands the app + * back when it ends. That exercises the whole feature (route step, late- + * mounting target, per-step narration, return trip) on a surface every user + * has, which is what the agent does when asked "how does X work?". + * + * `data-tour` handles are used on purpose: they're the documented way to give + * an element a durable name, and they survive re-renders and class changes. + */ +function demoSteps(): TourStep[] { + return [ + { + // Opens centered, wherever you happen to be: a tour says what it's about + // to do before it moves you anywhere. + text: "I'll take you to the Artifacts page and show you how it's organised. Use Next to follow along — you'll land back here at the end.", + title: "Let's look at Artifacts" + }, + { + navigate: ARTIFACTS_ROUTE, + selector: '[data-tour="page-tabs"]', + text: 'Here we are. This row filters what the page lists, with a live count beside each one. We\'ll take them in turn.', + title: 'Artifacts, filtered' + }, + { + selector: '[data-tour="tab-all"]', + side: 'bottom', + text: 'Everything the agent produced or touched, newest first.', + title: 'All' + }, + { + selector: '[data-tour="tab-image"]', + side: 'bottom', + text: 'Screenshots, renders, and diagrams — these get a thumbnail in the grid.', + title: 'Images' + }, + { + selector: '[data-tour="tab-file"]', + side: 'bottom', + text: 'Documents and data the agent wrote or read, listed by name and path.', + title: 'Files' + }, + { + selector: '[data-tour="tab-link"]', + side: 'bottom', + text: 'Pages the agent opened or cited, so you can retrace where something came from.', + title: 'Links' + }, + { + // Nothing pins this to the FIRST card; the selector matches whichever + // card the grid renders first, so the step works on any library. + selector: '[data-tour="artifact-card"]', + side: 'right', + text: 'Whichever filter you pick, each result is a card: a preview, its name, and where it came from. Opening one brings it up in the preview pane.', + title: 'One artifact' + }, + { + text: 'Closing the tour returns you to the session you started from — a tour borrows the app, it never leaves you somewhere else.', + title: 'And back' + } + ] +} + +/** Guards against a double-fire (two installs, or a chord that repeats) + * turning one request into start-then-immediately-stop. */ +let inFlight = false + +/** Toggle the demo tour. Resolves once the tour is up (or torn down). */ +export async function toggleTourDemo(): Promise { + if (inFlight) { + return + } + + inFlight = true + + try { + // Ask the engine, never a local flag: Esc / the ✕ / an overlay click all + // end a tour without telling us, and a stale "it's running" belief would + // turn the next toggle into a no-op stop — the trigger would look dead. + if (isTourActive()) { + await stopTour() + + return + } + + const result = await startTour(demoSteps()) + + if (!result.success) { + console.warn('[dev] tour demo could not start:', result.error) + } + } finally { + inFlight = false + } +} + +/** The always-there trigger: a floating button, styled off app tokens. */ +function mountButton(): () => void { + document.getElementById(BUTTON_ID)?.remove() + + const button = document.createElement('button') + + button.id = BUTTON_ID + button.type = 'button' + button.textContent = 'Tour demo' + button.title = 'Dev only — toggle the tour UI (Ctrl+Shift+X)' + button.style.cssText = [ + 'position:fixed', + 'left:12px', + 'bottom:12px', + // Under the tour overlay (10000) so a running tour still dims it, but over + // ordinary app chrome. + 'z-index:9999', + 'padding:4px 8px', + 'font:500 11px/1rem var(--font-sans, system-ui)', + 'color:var(--foreground, #fff)', + 'background:var(--ui-bg-quaternary, rgba(255,255,255,.1))', + 'border:1px solid var(--ui-stroke-secondary, rgba(255,255,255,.15))', + 'border-radius:2.5px', + 'cursor:pointer', + 'opacity:.75', + // driver.js sets `.driver-active * { pointer-events: none }` while a tour + // is up, which would make this button unable to STOP the tour it started. + 'pointer-events:auto' + ].join(';') + + // Fire on pointerdown, not click: the tour mounts an overlay that swallows + // pointer events, so waiting for the full click can drop the trailing half + // of the gesture onto the fresh overlay. + const onPointerDown = (event: PointerEvent) => { + event.preventDefault() + event.stopPropagation() + void toggleTourDemo() + } + + button.addEventListener('pointerdown', onPointerDown) + document.body.appendChild(button) + + return () => { + button.removeEventListener('pointerdown', onPointerDown) + button.remove() + } +} + +// Ctrl+Shift+X on every platform (Ctrl, not Cmd, so it can't clash with a +// system Cmd chord). Matched on `code` so it's layout independent, and +// captured before the composer so a focused input can't swallow it. +function isTriggerChord(e: KeyboardEvent): boolean { + return e.ctrlKey && e.shiftKey && !e.metaKey && !e.altKey && e.code === 'KeyX' +} + +/** + * Install the dev triggers: a floating button, a capture-phase hotkey + * (Ctrl+Shift+X), a ⌘K palette entry, and a `window.__tourDemo()` console + * hook. Returns a disposer. + */ +export function installTourDemo(): () => void { + const onKeyDown = (e: KeyboardEvent) => { + if (!isTriggerChord(e)) { + return + } + + e.preventDefault() + e.stopPropagation() + void toggleTourDemo() + } + + window.addEventListener('keydown', onKeyDown, { capture: true }) + ;(window as unknown as { __tourDemo?: () => Promise }).__tourDemo = toggleTourDemo + + const unmountButton = mountButton() + + const disposePalette = registry.register({ + id: 'dev.tourDemo', + area: PALETTE_AREA, + data: { + id: 'dev.tourDemo', + icon: Compass, + keywords: ['tour', 'walkthrough', 'highlight', 'driver', 'dev', 'demo'], + label: 'Dev: toggle tour demo', + // keepOpen:false closes the palette, and that teardown can land a + // stray pointer/focus event on the just-mounted overlay — defer past it. + run: () => window.setTimeout(() => void toggleTourDemo(), 120) + } satisfies PaletteContribution + }) + + console.info('[dev] tour demo ready — click the "Tour demo" button, press Ctrl+Shift+X, or run window.__tourDemo()') + + return () => { + window.removeEventListener('keydown', onKeyDown, { capture: true }) + unmountButton() + disposePalette() + delete (window as unknown as { __tourDemo?: () => Promise }).__tourDemo + + if (isTourActive()) { + void stopTour() + } + } +} diff --git a/apps/desktop/src/app/contrib/wiring.tsx b/apps/desktop/src/app/contrib/wiring.tsx index 3aa1d34f45..ef6ff754f2 100644 --- a/apps/desktop/src/app/contrib/wiring.tsx +++ b/apps/desktop/src/app/contrib/wiring.tsx @@ -325,21 +325,21 @@ export function ContribWiring({ children }: { children: ReactNode }) { return () => window.removeEventListener('hermes:open-keybinds', onOpenKeybinds) }, [navigate]) - // Dev-only: install the credit-notice demo trigger (Ctrl+Shift+C / ⌘K palette - // / window.__creditsDemo). Dynamic import inside the DEV guard so the module - // is dropped from production builds. + // Dev-only: install the demo triggers (credit notices on Ctrl+Shift+C, the + // tour UI on Ctrl+Shift+X — each also a ⌘K entry and a window hook). Dynamic + // imports inside the DEV guard so the modules are dropped from production + // builds. useEffect(() => { if (!import.meta.env.DEV) { return } - let dispose: (() => void) | undefined + const disposers: (() => void)[] = [] - void import('./dev/credits-notice-demo').then(m => { - dispose = m.installCreditsNoticeDemo() - }) + void import('./dev/credits-notice-demo').then(m => disposers.push(m.installCreditsNoticeDemo())) + void import('./dev/tour-demo').then(m => disposers.push(m.installTourDemo())) - return () => dispose?.() + return () => disposers.forEach(dispose => dispose()) }, []) // Post-turn rehydrate from stored history (same behavior as DesktopController, diff --git a/apps/desktop/src/lib/icons.ts b/apps/desktop/src/lib/icons.ts index 943dd1870a..949130e870 100644 --- a/apps/desktop/src/lib/icons.ts +++ b/apps/desktop/src/lib/icons.ts @@ -31,6 +31,7 @@ import { IconClock as Clock, IconCloud as Cloud, IconCommand as Command, + IconCompass as Compass, IconCopy as Copy, IconCopy as CopyIcon, IconCornerDownLeft as CornerDownLeft, @@ -159,6 +160,7 @@ export { Clock, Cloud, Command, + Compass, Copy, CopyIcon, CornerDownLeft, From bbd6607968d26db9f56075beebc8808873f98077 Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Wed, 19 Aug 2026 00:43:06 -0500 Subject: [PATCH 11/11] docs(tour): document navigating steps and the handle vocabulary --- website/docs/reference/tools-reference.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/website/docs/reference/tools-reference.md b/website/docs/reference/tools-reference.md index 664d8c3ab9..35b4ff466e 100644 --- a/website/docs/reference/tools-reference.md +++ b/website/docs/reference/tools-reference.md @@ -213,6 +213,18 @@ To give an element a durable handle of your own, mark it up:
…
``` +Handles are applied at the **primitive**, not the call site, so one edit names every instance. The ones that already exist: + +| Handle | What it names | +|---|---| +| `overlay-nav` | the left nav of any route overlay (settings, cron, profiles, agents) | +| `nav-` | one row in that nav — `nav-models`, `nav-appearance`, … | +| `field-` | one settings row, by its config key — `field-model`, `field-provider`, … | +| `page-tabs` | the filter tabs on any `PageSearchShell` page (artifacts, skills, …) | +| `artifact-card` | an artifact card in the grid | + +When adding a surface, tag its shared primitive the same way rather than tagging screens one by one — that keeps the tour vocabulary small and stops selectors from rotting. + The same engine backs curated (non-agent) tours in the desktop app, so a feature can ship its own walkthrough: ```ts @@ -224,6 +236,17 @@ startTour([ ]) ``` +A step can also move the app to where its target lives, and the tour puts things back when it ends: + +```ts +startTour([ + { navigate: '/artifacts', selector: '[data-tour="page-tabs"]', title: 'Filters', text: '…' }, + { pane: 'sessions', selector: '[data-slot="sidebar"]', title: 'Sessions', text: '…' } +]) +``` + +`navigate` takes a route path and `pane` a desktop pane name. Both run as the step is entered, targets that mount late are waited for, and closing the tour — by any route, including Esc — returns to wherever it started. + Pass `'preview'` as the second argument to run against the page in the preview pane instead of the app. ## `todo` toolset