Merge pull request #89620 from NousResearch/bb/agent-tours
Let Hermes give live guided tours of the UI
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -492,7 +492,10 @@ function ArtifactImageCard({ artifact, failedImage, onImageError, onOpenChat }:
|
||||
}, [artifact.href, artifact.id, artifact.value, onImageError])
|
||||
|
||||
return (
|
||||
<article className="group/artifact overflow-hidden rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-chat-bubble-background)">
|
||||
<article
|
||||
className="group/artifact overflow-hidden rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-chat-bubble-background)"
|
||||
data-tour="artifact-card"
|
||||
>
|
||||
<div
|
||||
className={cn(
|
||||
'relative flex h-40 w-full items-center justify-center overflow-hidden border-b border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) p-1.5',
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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<unknown>
|
||||
|
||||
const runners = new Map<string, TourScriptRunner>()
|
||||
|
||||
/** 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
|
||||
}
|
||||
@@ -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<TourResult> {
|
||||
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
|
||||
}
|
||||
@@ -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<void> {
|
||||
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<void> }).__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<void> }).__tourDemo
|
||||
|
||||
if (isTourActive()) {
|
||||
void stopTour()
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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,
|
||||
|
||||
@@ -31,6 +31,8 @@ interface OverlayMainProps {
|
||||
interface OverlayNavItemProps {
|
||||
active: boolean
|
||||
icon: IconComponent
|
||||
/** Stable identity for the row, used as its `data-tour` handle. */
|
||||
id?: string
|
||||
label: string
|
||||
// Renders as an indented child of another nav item: smaller icon and a
|
||||
// lighter active state so it never competes with the boxed parent item.
|
||||
@@ -67,6 +69,10 @@ export function OverlaySidebar({ children, className }: OverlaySidebarProps) {
|
||||
OVERLAY_TOP_CLEARANCE,
|
||||
className
|
||||
)}
|
||||
// Every overlay's left nav (settings, cron, profiles, agents) answers to
|
||||
// one name, so a tour can point at "the nav" without knowing which
|
||||
// overlay is open. See lib/tour.
|
||||
data-tour="overlay-nav"
|
||||
>
|
||||
{children}
|
||||
</aside>
|
||||
@@ -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 => (
|
||||
<Fragment key={group.id}>
|
||||
{group.gapBefore && <div aria-hidden className="h-2" />}
|
||||
<OverlayNavItem active={group.active} icon={group.icon} label={group.label} onClick={group.onSelect} />
|
||||
<OverlayNavItem
|
||||
active={group.active}
|
||||
icon={group.icon}
|
||||
id={group.id}
|
||||
label={group.label}
|
||||
onClick={group.onSelect}
|
||||
/>
|
||||
{group.children && group.active && (
|
||||
<div className="ml-3.5 flex flex-col gap-0.5 pl-1.5">
|
||||
{group.children.map(child => (
|
||||
<OverlayNavItem
|
||||
active={child.active}
|
||||
icon={child.icon}
|
||||
id={child.id}
|
||||
key={child.id}
|
||||
label={child.label}
|
||||
nested
|
||||
|
||||
@@ -103,7 +103,13 @@ export function PageSearchShell({
|
||||
/>
|
||||
)}
|
||||
</div>
|
||||
{hasTabs ? <ShellTabs activeTab={activeTab} onTabChange={onTabChange} tabs={tabs!} /> : <span />}
|
||||
{hasTabs ? (
|
||||
<div className="flex min-w-0 items-center justify-center" data-tour="page-tabs">
|
||||
<ShellTabs activeTab={activeTab} onTabChange={onTabChange} tabs={tabs!} />
|
||||
</div>
|
||||
) : (
|
||||
<span />
|
||||
)}
|
||||
<div className="flex min-w-0 items-center justify-end">{searchTrailingAction}</div>
|
||||
</div>
|
||||
)}
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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) => (
|
||||
<ListRow action={action} description={descriptionNode} title={label} wide={wide} />
|
||||
<ListRow
|
||||
action={action}
|
||||
data-tour={`field-${schemaKey}`}
|
||||
description={descriptionNode}
|
||||
title={label}
|
||||
wide={wide}
|
||||
/>
|
||||
)
|
||||
|
||||
// `fallback_providers` is a list of {provider, model} objects; the generic
|
||||
|
||||
@@ -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,…).
|
||||
<div className={cn('@container', className)} id={id}>
|
||||
<div className={cn('@container', className)} data-tour={dataTour} id={id}>
|
||||
<div
|
||||
className={cn(
|
||||
'grid gap-3 py-3',
|
||||
|
||||
@@ -114,7 +114,14 @@ export function ResponsiveTabs({
|
||||
<>
|
||||
<div className={cn('hidden min-w-0 flex-wrap items-center gap-x-2 gap-y-1 md:flex', wideClassName)}>
|
||||
{tabs.map(tab => (
|
||||
<TextTab active={tab.id === value} key={tab.id} onClick={() => onChange(tab.id)}>
|
||||
<TextTab
|
||||
active={tab.id === value}
|
||||
// Names each tab by its own id, so a tour can walk them one by one
|
||||
// (`[data-tour="tab-images"]`) on every page that uses this row.
|
||||
data-tour={`tab-${tab.id}`}
|
||||
key={tab.id}
|
||||
onClick={() => onChange(tab.id)}
|
||||
>
|
||||
{tab.label}
|
||||
{tab.meta !== undefined && <TextTabMeta>{tabMetaContent(tab.meta)}</TextTabMeta>}
|
||||
</TextTab>
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -0,0 +1,212 @@
|
||||
/* Hermes surface treatment for the APP surface's tour popovers.
|
||||
|
||||
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 {
|
||||
--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.75rem;
|
||||
font-weight: 600;
|
||||
letter-spacing: -0.01em;
|
||||
line-height: 1rem;
|
||||
}
|
||||
|
||||
.driver-popover-title[style*='block'] + .driver-popover-description {
|
||||
margin-top: 0.25rem;
|
||||
}
|
||||
|
||||
.driver-popover-description {
|
||||
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(--ui-text-tertiary);
|
||||
font-size: 0.6875rem;
|
||||
font-variant-numeric: tabular-nums;
|
||||
}
|
||||
|
||||
.driver-popover-close-btn {
|
||||
color: var(--ui-text-tertiary);
|
||||
transition: color 100ms;
|
||||
}
|
||||
|
||||
.driver-popover-close-btn:hover,
|
||||
.driver-popover-close-btn:focus {
|
||||
color: var(--foreground);
|
||||
}
|
||||
|
||||
/* Matches the Button `secondary` + `xs` shape: 12px/1rem medium, 2.5px radius. */
|
||||
.driver-popover-footer-btn {
|
||||
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(--ui-control-hover-background);
|
||||
}
|
||||
|
||||
.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(--ui-bg-elevated);
|
||||
}
|
||||
|
||||
.driver-popover-arrow-side-right {
|
||||
border-right-color: var(--ui-bg-elevated);
|
||||
}
|
||||
|
||||
.driver-popover-arrow-side-top {
|
||||
border-top-color: var(--ui-bg-elevated);
|
||||
}
|
||||
|
||||
.driver-popover-arrow-side-bottom {
|
||||
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;
|
||||
}
|
||||
}
|
||||
@@ -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<Element>()
|
||||
|
||||
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 <body>. */
|
||||
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))
|
||||
}
|
||||
@@ -0,0 +1,487 @@
|
||||
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 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 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
|
||||
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')
|
||||
enter(index + 1)
|
||||
},
|
||||
movePrevious() {
|
||||
calls.push('prev')
|
||||
enter(index - 1)
|
||||
}
|
||||
}
|
||||
|
||||
return instance
|
||||
}
|
||||
}
|
||||
|
||||
/** 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 = `
|
||||
<nav aria-label="Primary"><button id="send-btn" aria-label="Send message">Send</button></nav>
|
||||
<main><h1>Inbox</h1><div data-tour="composer">Composer</div><section><p>Positional only</p></section></main>
|
||||
`
|
||||
// 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(')
|
||||
}
|
||||
})
|
||||
})
|
||||
|
||||
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)
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,387 @@
|
||||
/**
|
||||
* 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 <webview> 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
|
||||
/** 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
|
||||
moveNext: () => void
|
||||
movePrevious: () => void
|
||||
}
|
||||
|
||||
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, 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'
|
||||
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,
|
||||
style?: TourStyle,
|
||||
host?: TourHost
|
||||
): TourResult {
|
||||
const kind = action.kind
|
||||
const base = { animate: true, smoothScroll: true, ...(style || {}) }
|
||||
|
||||
/** 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 || '',
|
||||
popoverClass: first ? 'tour-pop-in' : 'tour-pop-next',
|
||||
side: step.side || undefined,
|
||||
title: step.title || ''
|
||||
}
|
||||
: undefined
|
||||
|
||||
/** 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)
|
||||
}
|
||||
|
||||
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(', '),
|
||||
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 : ''
|
||||
}
|
||||
}
|
||||
|
||||
/** 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])
|
||||
|
||||
if (gone.length > 0) {
|
||||
return missing(gone)
|
||||
}
|
||||
|
||||
if (!holder.driver) {
|
||||
clearOrphans()
|
||||
holder.driver = factory(base)
|
||||
}
|
||||
|
||||
// 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 }
|
||||
}
|
||||
|
||||
if (kind === 'start') {
|
||||
const steps = action.steps || []
|
||||
const gone = unmatched(steps)
|
||||
|
||||
if (gone.length > 0) {
|
||||
return missing(gone)
|
||||
}
|
||||
|
||||
if (holder.driver) {
|
||||
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({
|
||||
...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,
|
||||
// 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 }
|
||||
}
|
||||
|
||||
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 }
|
||||
}
|
||||
|
||||
// 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 {
|
||||
driver.movePrevious()
|
||||
}
|
||||
|
||||
return { action: kind, activeStep: driver.getActiveIndex(), success: true }
|
||||
}
|
||||
|
||||
if (kind === 'stop') {
|
||||
if (holder.driver) {
|
||||
holder.driver.destroy()
|
||||
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 }
|
||||
}
|
||||
|
||||
return { error: 'Unknown tour action: ' + kind, success: false }
|
||||
}
|
||||
@@ -0,0 +1,35 @@
|
||||
/**
|
||||
* 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, TourHost, TourResult, TourStep } from './engine'
|
||||
export {
|
||||
isTourActive,
|
||||
listTourTargets,
|
||||
nextTourStep,
|
||||
previousTourStep,
|
||||
runTour,
|
||||
showTourStep,
|
||||
startTour,
|
||||
stopTour,
|
||||
type TourSurface
|
||||
} from './run-tour'
|
||||
@@ -0,0 +1,115 @@
|
||||
/**
|
||||
* 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 { revealDesktopPane } from '@/store/pane-focus'
|
||||
|
||||
import { collectTourTargets } from './collect-targets'
|
||||
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 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<TourResult> {
|
||||
try {
|
||||
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)
|
||||
|
||||
/** 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)
|
||||
@@ -0,0 +1,191 @@
|
||||
/**
|
||||
* SPOTLIGHT BLUR — a blurred scrim that keeps the highlighted element crisp.
|
||||
*
|
||||
* driver.js paints its scrim as ONE full-viewport <svg> 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 <mask> 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()
|
||||
}
|
||||
@@ -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<string, string>),
|
||||
@@ -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'),
|
||||
|
||||
Generated
+7
@@ -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",
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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"}),
|
||||
)
|
||||
|
||||
|
||||
@@ -26,6 +26,7 @@ GUI_TOOLS = {
|
||||
"read_window_below",
|
||||
"react_to_message",
|
||||
"setup_mcp",
|
||||
"tour",
|
||||
}
|
||||
|
||||
|
||||
|
||||
@@ -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="🧭",
|
||||
)
|
||||
+1
-1
@@ -279,7 +279,7 @@ TOOLSETS = {
|
||||
"open_preview", "read_preview",
|
||||
"read_window_below",
|
||||
"focus_pane", "react_to_message",
|
||||
"setup_mcp",
|
||||
"setup_mcp", "tour",
|
||||
],
|
||||
"includes": []
|
||||
},
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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__<server>__` (e.g., `mcp__github__create_issue` for the `github` MCP server). See [MCP Integration](/user-guide/features/mcp) for configuration.
|
||||
@@ -201,6 +201,53 @@ 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
|
||||
<div data-tour="composer">…</div>
|
||||
```
|
||||
|
||||
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-<id>` | one row in that nav — `nav-models`, `nav-appearance`, … |
|
||||
| `field-<schemaKey>` | 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
|
||||
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.' }
|
||||
])
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
|
||||
@@ -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). |
|
||||
|
||||
Reference in New Issue
Block a user