Reference

API

Every export, package by package. For the fields of a tour itself, see the tour schema.

Most apps use one package: @docentjs/dom without a framework, or the adapter for their framework. The adapters re-export what you need from the packages below them.

`@docentjs/dom`

The web renderer, plus browser-ready versions of the engine’s entry points.

Export	What it is
`createTour(tour, options?)`	a controller for one tour, with the DOM renderer, `localStorage` progress and route following connected; see the controller
`createDocent(options?)`	the tour manager, ready for the browser; see the manager
`defineTour(tour)`	returns the tour with `schemaVersion` set, and checks its type
`createLocalStorage()`	a storage adapter over `localStorage` that falls back to memory
`DomRenderer`	the renderer itself, for use with `TourController` directly
`computePosition`, `resolveTarget`, `waitForTarget`, `anchorPoint`	the positioning, target and beacon-placement helpers, for building your own renderer pieces
`createDomEnvironment(document?, renderer?)`	what `createDocent` gives the manager in the browser: routes, element watching and beacons

createTour options: everything in ControllerOptions below, plus renderer (renderer options) and followRoutes.

createDocent options: tours (an array or a TourSource), identity, storage, sink, hooks keyed by tour id, custom predicates, minViewportWidth (no tours below this width, in px), renderer, document, and connect (false to start watching later with connect()).

Renderer options

Option	Purpose
`theme`	theme tokens for every tour
`arrow`, `spotlight`, `overlay`	default looks
`beacon`	default beacon look: `style`, `position`, `offset`, `size`
`progress`, `eyebrow`	default step counter and the line above the title; see themes
`slots`, `templates`	slots and templates
`template`	a registered name, a built-in look, or a theme object
`headless`	your own popover
`css`	extra CSS inside the shadow root
`labels`	button and progress wording
`gap`	space between the popover and the target, in px. Drawn arrows use it as a minimum and take more room if their style needs it
`sheetBreakpoint`	the width below which the screen counts as small: the popover becomes a full-width card beside the target, or docked when it does not fit (default `480`; `0` never)
`mobile`	small-screen settings when a tour sets none, e.g. `{ layout: 'dock', card: 'classic' }`
`avoidOcclusion`	move the target out from under sticky headers (default `true`)
`focus`	move focus into the popover when a tour opens and back when it ends (default `true`); tours opened by hovering a beacon never take focus
`document`	render into another document, such as an iframe

`@docentjs/dom/validate`

The schema checks, for development and CI: validateTour, validateTheme, isValidTour, formatIssues and tourJsonSchema. Re-exported from @docentjs/core/validate; see checking a tour.

`@docentjs/dom/themes`

The presets light, dark, minimal and contrast, and presets, all four by name.

`@docentjs/core`

The engine. It has no DOM code and runs anywhere.

`TourController`

Drives one tour against a renderer. createTour returns a subclass with everything connected.

Method	What it does
`start(at?)`	start from the beginning, or from a step id or index
`resume()`	continue saved progress, or start
`next()`, `back()`, `skip()`, `goTo(step)`	move through the tour
`abort(reason)`	end the tour, recorded as aborted
`notify(name)`	move on a step waiting for `{ on: 'event', name }`
`routeChanged()`	re-check the current route after a navigation it could not see
`updateTour(tour)`	replace the definition while it runs, keeping the current step
`getState()`, `subscribe(fn)`	the engine state: `{ status, index, history, reason? }`
`destroy()`	stop and remove everything

ControllerOptions: tour, renderer, identity, storage, sink, hooks, custom, tourState, defaultWaitMs, now.

`Docent`

The tour manager. Build it with createDocent from the dom package, which supplies the browser environment.

Member	What it does
`ready`	a promise that resolves once tours and progress are loaded
`identify(id, traits)`	set the current user
`track(name)`	report an event
`start(id, { at? })`, `stop()`	start a tour by hand, or end the running one
`reset(id?)`, `refresh()`	forget progress; re-check triggers
`isEligible(id)`, `tourState(id)`	whether a tour would show now; its progress for this user
`updateTour(tour)`	replace a tour’s definition, even while it runs
`getState()`, `subscribe(fn)`	`{ active, tours }`
`getTours()`, `onEvent(fn)`, `getConditionEnv()`	for tooling such as the devtools
`activeController`	the running tour’s controller
`connect()`, `disconnect()`, `destroy()`	start or stop watching; remove everything

Helpers and types

Helpers: beaconTarget, reduce, evaluateCondition, evaluateAll, matchRoute, shouldShow, ProgressStore, createMemoryStorage, createEvent, combineSinks, NOOP_SINK.
Types: everything in the tour schema, plus Renderer, RenderContext, EngineState, TourHooks, StepHooks, DocentEvent, DocentEnvironment (with BeaconRequest and BeaconHandle for platforms that draw beacons), and the four seams: TourSource, Identity, StorageAdapter, EventSink.

`@docentjs/react`

Export	What it is
`useTour(tour, options?)`	`{ state, active, start, resume, next, back, skip, goTo, notify, controller, portal }`; `options.popover` renders your own popover
`useDocent(options?)`	the manager for the component’s lifetime: `{ state, docent, identify, track, start, stop, reset, refresh, portal }`
`<Tour tour autoStart popover>`	the component form; children receive the controls
`<DocentProvider>`	shares `renderer`, `identity`, `storage` and `sink` with every tour below it

`@docentjs/vue`

Export	What it is
`useTour(tour, options?)`	refs `state`, `active`, `popoverContext`, `popoverTarget`, the controls, and `destroy`
`useDocent(options?)`	a reactive `state`, the manager methods, `popoverContext`, `popoverTarget`, and `destroy`
`<TourPopover :tour v-slot="{ ctx }">`	teleports its slot into the positioned box when `popover: true`
`provideDocentDefaults(defaults)`	shares defaults with descendants

`@docentjs/svelte`

Export	What it is
`useTour(tour, options?)`	stores `state` and `active`, the controls, and `destroy`; `options.popover` is a component
`useDocent(options?)`	a `state` store, the manager methods, and `destroy`
`use:tour={handle}`	starts on mount, cleans up on removal

`@docentjs/devtools`

Export	What it is
`DocentDevtools` from `/react`, `/vue`, `/svelte`	a component that mounts the panel in development and renders nothing in production
`mount(docent, { open?, shortcut?, persist?, document? })`	mounts the panel directly and returns a function that removes it

`@docentjs/cli`

npx @docentjs/cli validate "tours/*.json"

Command	What it does
`docent validate <files...>`	check tour files against the schema; exits 1 when anything is wrong
`docent schema [file]`	print the tour JSON Schema, or write it to a file
`docent theme list`	list the ready-made themes
`docent theme add <name\|url>`	check a theme and write it to `docent-theme.json`; refuses one that is not valid

Options for validate: --json, --quiet, --allow-unknown. For theme add: --out <file> to write elsewhere, --force to replace an existing file.

Addresses

Address	What it is
/schema/tour-v1.json	the tour format as JSON Schema
/llms.txt	a summary for AI tools, with links
/llms-small.txt, /llms-full.txt	the documentation as plain text

See Using Docent with AI.