toolmark-monorepo / @toolmark/tour / startTour

Function: startTour()

startTour(tm, o): Promise<Tour>

Defined in: packages/tour/src/engine.ts:433

Starts a guided tour over the registry's tools (spec §11.5). Pass exactly one source: authored steps, or a goal with an app-supplied planner (whose steps are validated against what caller tour can see; invalid ones are dropped with step_invalid).

• show waits for next() on every step.
• guide waits for the user's interaction events on the step's tool/param and validates via tm.state() (400 ms after the last input, or at once when focus leaves the anchor).
• do calls each step's tool as caller tour (policy and inline confirmation apply; state busy while the call is in flight), then highlights each changed field for 600 ms (none with reduced motion) and advances.

In every mode the state is confirming while any inline confirmation announced by the registry's confirm events is pending (the tour's own call, ctx.confirm, or any other tool and caller, e.g. an MCP/WebMCP agent), and returns to running/waiting when none is.

Steps whose anchor is not rendered are skipped (anchor_missing); a step whose tool disappears is skipped (step_skipped). The tour never reads DOM values: only anchors, tm.state() (redacted by each tool) and interaction events.

Parameters

tm

Toolmark

The registry.

o

StartTourOptions

Mode, the step source, reducedMotion and an optional stop signal.

Returns

Promise<Tour>

The running tour (already on its first step, or stopped when no step is valid).

Throws

TypeError (as a rejection) when the options are invalid; the planner's error when it rejects.