@glowhop/core-tour 1.3.1 → 1.5.0

package/types/index.d.ts

@@ -16,32 +16,70 @@ export interface TargetResolverContext {
 }
 /** Configures step-level interaction behavior and error handling. */
 export interface StepBehavior {
-    /** Allow user interaction with the page outside the target element. @default false */
+    /** Allow user interaction with the target: the page is no longer inert and pointer events reach the target through the cutout, while the dimmed area still catches clicks. Change it during the step with `context.props.update({ behavior: { allowInteraction } })`. @default false */
     allowInteraction?: boolean;
-    /** Disable automatic focus on the target when the step is entered. @default false */
-    disableAutoFocus?: boolean;
-    /** Disable automatic scroll to the target when the step is entered. @default false */
-    disableAutoScroll?: boolean;
-    /** How to handle when the target is not found: `"wait"` waits and retries, `"skip"` advances to next step, `"error"` halts the tour. @default "error" */
-    missingTargetStrategy?: "wait" | "skip" | "error";
+    /** Leave the page scrollable while the step is shown; set `false` to lock it. Change it during the step with `context.props.update({ behavior: { allowScroll } })`. @default true */
+    allowScroll?: boolean;
+    /**
+     * Focus the popover's Advance control (Back when going back) when the step is shown. Set `false`
+     * to never move focus during the step: it stays where it is, on the body when a modal step
+     * makes the page inert, and placing it is up to you. Focus that leaves the popover and target
+     * is still pulled back, and focus returns to where it was when the tour ends. @default true
+     */
+    autoFocus?: boolean;
+    /** Scroll the target into view when the step is entered. @default true */
+    autoScroll?: boolean;
+    /** What the step does when its target cannot be found. */
+    missingTarget?: MissingTargetOptions;
     /** Scroll behavior options. */
     scroll?: ScrollOptions;
-    /** Timeout in ms to wait for target to appear before applying missingTargetStrategy. @default 3000 */
-    targetTimeout?: number;
     /**
      * Behavior when the dimmed overlay backdrop (outside the cutout around the
      * target) is clicked: `"advance"` moves to the next step, `"cancel"` ends
      * the tour, `"none"` ignores the click. Has no effect when
-     * `allowInteraction` is `true`, since the page stays fully interactive and
-     * there is no modal backdrop to click.
+     * `allowInteraction` is `true`: clicks on the dimmed area are then ignored.
      * @default "none"
      */
     overlayClick?: "none" | "advance" | "cancel";
 }
+/** How a step handles a target that cannot be found. */
+export interface MissingTargetOptions {
+    /**
+     * `"wait"` retries until `timeout`, `"skip"` moves past the step, `"error"` fails the tour,
+     * `"detached"` shows the popover centered in the viewport over a backdrop that covers the whole
+     * screen. A detached step has no pointer and no cutout, does not scroll, keeps the page blocked
+     * even when `allowInteraction` is `true`, and binds no `targetEvents`; its `context.target` is the
+     * document's `<body>`.
+     * @default "error"
+     */
+    strategy?: "wait" | "skip" | "error" | "detached";
+    /** How long to look for the target with the `"wait"` strategy, in milliseconds. @default 3000 */
+    timeout?: number;
+}
 /** Placement directions for positioning the pointer or popover around the target. */
 export type TryOrderOptions = "top" | "bottom" | "left" | "right";
 /** A resolved placement direction, including `"center"` for centered positioning. */
 export type ResolvedPlacement = TryOrderOptions | "center";
+/** One CSS class, or several. A string may hold several space-separated classes. */
+export type ClassValue = string | readonly string[];
+/**
+ * Classes added to the tour components while a step is shown, one entry per component.
+ *
+ * They are added to the classes passed to the component itself, never replacing them. A step's entry
+ * overrides the workflow's entry for the same component; the components the step leaves out keep the
+ * workflow's classes.
+ */
+export interface TourClassNames {
+    overlay?: ClassValue;
+    popover?: ClassValue;
+    pointer?: ClassValue;
+    header?: ClassValue;
+    content?: ClassValue;
+    footer?: ClassValue;
+    advance?: ClassValue;
+    previous?: ClassValue;
+    cancel?: ClassValue;
+}
 /** Base configuration for animated elements. */
 export interface BaseOptions {
     /** Enable or disable animations. */
@@ -51,8 +89,8 @@ export interface BaseOptions {
 }
 /** Configures the pointer indicator that highlights the target element. */
 export interface IndicatorOptions extends BaseOptions {
-    /** Hide the indicator. @default false */
-    disabled?: boolean;
+    /** Hide the indicator. It only shows on steps that allow interaction. @default false */
+    hidden?: boolean;
     /** Gap between the target and the indicator in pixels. */
     gap?: number;
     /** Placement preference order when positioning the indicator. @default ["left", "right", "top", "bottom"] */
@@ -72,7 +110,7 @@ export interface OverlayOptions extends BaseOptions {
 /** Configures the arrow that points from the popover to the target. */
 export interface PopoverArrowOptions {
     /** Hide the arrow. @default false */
-    disabled?: boolean;
+    hidden?: boolean;
     /** Color of the arrow (CSS color). */
     color?: string;
     /** Size of the arrow in pixels. @default 12 */
@@ -90,11 +128,41 @@ export interface PopoverArrowOptions {
      */
     styleNonce?: string;
     /**
-     * Skip injecting the built-in arrow `<style>` element entirely. Provide the
+     * Inject the built-in arrow `<style>` element. Set `false` to provide the
      * equivalent rules yourself through whatever channel your CSP allows, such
      * as an external stylesheet.
+     * @default true
      */
-    disableAutoStyles?: boolean;
+    autoStyles?: boolean;
+}
+/**
+ * Whether the user may run a tour control. `"enabled"` is the default. New states may be added in
+ * a minor version.
+ */
+export type TourControlState = "enabled" | "disabled";
+/** One navigation command: whether the user may run it and the keys that run it. */
+export interface TourControl {
+    /**
+     * `"disabled"` blocks the command everywhere the tour UI offers it: its button is disabled, and
+     * its keys and `overlayClick` do nothing. Navigation through the tour API and the step context
+     * stays available. To hide a button, give it a class through `classNames`.
+     * @default "enabled"
+     */
+    state?: TourControlState;
+    /** Keys that run the command while the step is shown. An empty array turns them off. */
+    keys?: readonly string[];
+}
+/**
+ * The advance, previous and cancel commands. A step's controls override the workflow ones field by
+ * field: a step that only sets `advance.state` keeps the workflow's `advance.keys`.
+ */
+export interface TourControls {
+    /** @default { state: "enabled", keys: ["Enter", "ArrowRight"] } */
+    advance?: TourControl;
+    /** @default { state: "enabled", keys: ["ArrowLeft", "Backspace"] } */
+    previous?: TourControl;
+    /** @default { state: "enabled", keys: ["Escape"] } */
+    cancel?: TourControl;
 }
 /** Configures the popover box that displays content for each step. */
 export interface PopoverOptions extends BaseOptions {
@@ -102,47 +170,20 @@ export interface PopoverOptions extends BaseOptions {
     placementTryOrder?: readonly TryOrderOptions[];
     /** Arrow configuration. */
     arrow?: PopoverArrowOptions;
-    /** Hide the footer section. @default false */
-    hideFooter?: boolean;
-    /**
-     * Disables only previous-button and previous-keyboard controls. Programmatic
-     * navigation through the tour API and step context remains available.
-     */
-    disablePreviousButton?: boolean;
-    /** Hide the previous button. @default false */
-    hidePreviousButton?: boolean;
-    /**
-     * Disables only advance-button and advance-keyboard controls. Programmatic
-     * navigation through the tour API and step context remains available.
-     */
-    disableAdvanceButton?: boolean;
-    /** Hide the advance button. @default false */
-    hideAdvanceButton?: boolean;
     /** Gap between the target and the popover in pixels. @default 16 */
     gap?: number;
-    /** Keyboard shortcuts for navigation. */
-    keyboardShortcuts?: {
-        /**
-         * Keys that trigger previous step. @default ["ArrowLeft", "Backspace"]
-         */
-        previous?: readonly string[];
-        /**
-         * Keys that trigger advance step. @default ["Enter", "ArrowRight"]
-         */
-        advance?: readonly string[];
-        /**
-         * Keys that trigger cancel. @default ["Escape"]
-         */
-        cancel?: readonly string[];
-    };
 }
 /**
- * Scroll behavior options passed to Element.scrollIntoView().
+ * How a step scrolls its target into view, on entrance and after the user scrolled away.
  *
  * A step scrolls only when part of its target falls outside the viewport, and
  * does not wait for the scroll before presenting: the spotlight appears at once
  * and tracks the target as the page travels, and the popover and pointer enter
  * when the page has come to rest.
+ *
+ * While the user scrolls, the popover and pointer step aside and the spotlight
+ * keeps following the target. Once the page is still they come back, after
+ * `returnDelay` scrolls the target back into view if it was left outside it.
  */
 export interface ScrollOptions {
     /** Scroll animation. Forced to `"instant"` when the user prefers reduced motion. @default "smooth" */
@@ -151,6 +192,12 @@ export interface ScrollOptions {
     block?: "start" | "center" | "end" | "nearest";
     /** Horizontal alignment of the target in the viewport. @default "nearest" */
     inline?: "start" | "center" | "end" | "nearest";
+    /**
+     * Milliseconds to wait, once the user stops scrolling with part of the target outside the
+     * viewport, before scrolling it back into view. `false` leaves the page where the user put it.
+     * Ignored when `autoScroll` is `false`. @default 500
+     */
+    returnDelay?: number | false;
 }
 /** Animation timing configuration. */
 export interface AnimationOptions {
@@ -165,8 +212,8 @@ export interface AnimationOptions {
 export interface LifecycleHookContext<T> {
     /**
      * The step associated with this lifecycle transition:
-     * - `onStart`: the first step about to be entered (`workflow.steps[0]`), or
-     *   `null` if the workflow has no steps.
+     * - `onStart`: the step `start()` starts on (the `startAt` step, or the first
+     *   step), or `null` if the workflow has no steps.
      * - `onCancel`: the step the tour is currently on when cancellation is
      *   requested. Always non-null in practice, since a step is always active
      *   at the point a tour can be cancelled.
@@ -190,15 +237,6 @@ export interface LifecycleHookContext<T> {
 }
 /** Options for starting a tour workflow. */
 export interface StartOptions<T> {
-    /** Allow users to cancel the tour. @default true */
-    cancellable?: boolean;
-    /**
-     * Leaves page scroll available while the tour is active. Set `false` to lock
-     * scroll instead, restoring it on finish, cancel, error, or dispose.
-     *
-     * @default true
-     */
-    allowScroll?: boolean;
     /** Default overlay options for all steps. */
     overlay?: OverlayOptions;
     /** Default popover options for all steps. */
@@ -209,6 +247,10 @@ export interface StartOptions<T> {
     animated?: boolean;
     /** Default step behavior for all steps. */
     behavior?: StepBehavior;
+    /** Default controls for all steps. See `TourControls`. */
+    controls?: TourControls;
+    /** Classes added to the tour components on every step. See `TourClassNames`. */
+    classNames?: TourClassNames;
     /** Lifecycle hook called when the tour starts. */
     onStart?: (context: LifecycleHookContext<T>) => void | Promise<void>;
     /** Lifecycle hook called when the tour is cancelled. */
@@ -225,12 +267,22 @@ export interface StartOptions<T> {
 }
 /** Update to step properties, either as a full replacement or via a function. */
 export type StepPropsUpdate<T> = ReadonlyStepProps<T> | ((current: ReadonlyStepProps<T>) => ReadonlyStepProps<T>);
+/**
+ * Partial change to step properties, for `StepPropsStore.update`. Fields it leaves out are kept.
+ * `data` is merged key by key; `overlay`, `popover`, `indicator`, `behavior` and `controls` are
+ * merged the way step options merge over workflow defaults; arrays such as `placementTryOrder` or
+ * `keys` are replaced. `classNames` is merged per component: a component it names gets exactly the
+ * classes given.
+ */
+export type StepPropsPatch<T> = Partial<ReadonlyStepProps<T>>;
 /** Store for the current step's properties. */
 export interface StepPropsStore<T> {
     /** Get the current step properties. */
     get(): ReadonlyStepProps<T>;
-    /** Update the current step properties. */
+    /** Replace the current step properties. */
     set(update: StepPropsUpdate<T>): void;
+    /** Merge a partial change into the current step properties. See `StepPropsPatch`. */
+    update(patch: StepPropsPatch<T> | ((current: ReadonlyStepProps<T>) => StepPropsPatch<T>)): void;
     /** Subscribe to changes in step properties. Returns an unsubscribe function. */
     subscribe(listener: (props: ReadonlyStepProps<T>) => void): () => void;
 }
@@ -242,17 +294,39 @@ export interface StepContext<T> {
     cancel(): Promise<void>;
     /** Navigate to the previous step. */
     previous(): Promise<void>;
-    /** The DOM element being highlighted for this step. */
+    /**
+     * Navigate to the step with this id, skipping the steps in between. Stops the remaining actions
+     * of this step, like `advance()`. Throws when no step has this id.
+     */
+    goTo(id: string): Promise<void>;
+    /**
+     * The direction of the navigation that entered this step. Captured when the context is created, so
+     * it does not change while the step's callbacks run.
+     */
+    readonly direction: TourDirection;
+    /** The step properties as initially configured, before any `props.set()`. */
+    readonly initialProps: ReadonlyStepProps<T>;
+    /** The DOM element being highlighted for this step, or the document's `<body>` for a detached step. */
     readonly target: HTMLElement;
     /** Store for reading and updating the current step's properties. */
     readonly props: StepPropsStore<T>;
     /** Signal that aborts when the step is exited or the tour is cancelled. */
     readonly signal: AbortSignal;
 }
-/** Context passed to transition hooks (beforeAdvance, beforePrevious, beforeCancel). */
-export type BeforeActionStepContext<T> = Readonly<ReadonlyStepProps<T> & {
-    readonly target: HTMLElement;
-}>;
+/**
+ * Context passed to the `beforeEnter` and `beforeLeave` step hooks. It has no navigation methods:
+ * a transition is already in progress when these hooks run. `direction` is the direction of that
+ * navigation, so the step being left and the step being entered see the same value.
+ */
+export interface StepHookContext<T> extends Omit<StepContext<T>, "advance" | "cancel" | "goTo" | "previous"> {
+    /**
+     * Call it synchronously, or before the hook's returned promise resolves, to stop the navigation.
+     * The tour stays on the step it was on and emits nothing: `beforeLeave` keeps the step, and
+     * `beforeEnter` does not show the next one. When `beforeEnter` aborts the first step of `start()`,
+     * the tour goes back to `idle`, like an `onStart` abort.
+     */
+    abort(): void;
+}
 /** Context passed to target event handlers. */
 export type StepEventContext<T> = StepContext<T>;
 /** Options for the waitUntil step action. */
@@ -268,16 +342,16 @@ export type StepActionResult = boolean | void;
 export type StepAction<T> = (context: StepContext<T>) => Promise<StepActionResult> | StepActionResult;
 /** A step action or a delay in milliseconds. */
 export type StepActionInstruction<T> = StepAction<T> | number;
-/** A callback that runs before transitioning to the next/previous step or cancelling. */
-export type StepTransitionAction<T> = (context: BeforeActionStepContext<T>) => void | Promise<void>;
+/** A callback that runs before a step is entered or left (`beforeEnter` / `beforeLeave`). */
+export type StepHookAction<T> = (context: StepHookContext<T>) => void | Promise<void>;
 /** Handler for an event fired on the target element during a step. */
-export interface EventHandler<TStepProps, TEvent extends Event = Event> {
+export interface TargetEventHandler<TStepProps, TEvent extends Event = Event> {
     /** Event name(s) to listen for. */
     event: string;
     /** Callback invoked when the event fires. */
     callback: (event: TEvent, context: StepEventContext<TStepProps>) => void | Promise<void>;
 }
-/** Tour lifecycle status. */
+/** Tour lifecycle status. New statuses may be added in a minor release: keep a default branch when switching over it. */
 export type TourStatus = "idle" | "starting" | "transitioning" | "active" | "finished" | "cancelled" | "error" | "disposed";
 /** Direction of tour navigation. */
 export type TourDirection = "advance" | "previous";
@@ -316,6 +390,17 @@ export interface TourState<T> {
     readonly isLastStep: boolean;
     /** Current status of the tour. */
     readonly status: TourStatus;
+    /**
+     * Whether a navigation is waiting for the next step's target to resolve, i.e. an async resolver
+     * or the `"wait"` missing-target strategy. The step being left stays on screen meanwhile, and its
+     * advance control is refused, so a UI can show the wait instead of looking idle.
+     */
+    readonly awaitingTarget: boolean;
+    /**
+     * Whether `hidePopover()` hid the popover of the running tour. `false` again after
+     * `showPopover()`, and whenever a tour starts or ends.
+     */
+    readonly popoverHidden: boolean;
     /** Error encountered during the tour, if any. */
     readonly error: Error | null;
 }
@@ -331,22 +416,37 @@ export interface GlowTour<T> {
     /** Create a new workflow builder with the given name. */
     create(name: string, options?: StartOptions<T>): WorkflowBuilder<T>;
     /** Run a workflow, optionally starting at a specific step. */
-    run(workflow: WorkflowDefinition<T>, options?: RunOptions): Promise<void>;
+    start(workflow: WorkflowDefinition<T>, options?: RunOptions): Promise<void>;
     /** Advance to the next step. */
     advance(): Promise<void>;
     /** Go to the previous step. */
     previous(): Promise<void>;
-    /** Jump to a specific step by index. */
-    goToStep(index: number): Promise<void>;
+    /**
+     * Go to the step with this id, skipping the steps in between. Does nothing while a transition is
+     * in progress or when that step is already shown. Throws when no step has this id.
+     */
+    goTo(id: string): Promise<void>;
     /** Cancel the current tour. */
     cancel(): Promise<void>;
+    /**
+     * Show the popover again after `hidePopover()`, and move focus into it when the step auto
+     * focuses. Does nothing when no tour is running.
+     */
+    showPopover(): void;
+    /**
+     * Hide the popover of the running tour. The overlay, the indicator and the scroll lock stay; the
+     * page is no longer inert, focus leaves the popover for the target, and the keyboard shortcuts
+     * do nothing until `showPopover()`. The popover stays hidden across steps, until `showPopover()`
+     * or the end of the tour. Does nothing when no tour is running.
+     */
+    hidePopover(): void;
     /** Dispose the tour and free resources. */
     dispose(): void;
     /** Observable store of the current tour state. */
     readonly state: ReadonlyTourState<T>;
 }
 /**
- * Per-run options. Unlike `StartOptions`, these belong to one `run()` call and
+ * Per-run options. Unlike `StartOptions`, these belong to one `start()` call and
  * are never baked into the reusable workflow definition.
  */
 export interface RunOptions {
@@ -365,13 +465,15 @@ export interface RunOptions {
 /**
  * What triggered a transition.
  *
- * `"api"` covers every call your own code makes — `advance()`, `previous()`,
- * `goToStep()`, `cancel()`, and the `context.advance()` available inside a step
- * action. The other three are the user acting on the tour UI directly.
+ * `"api"` covers every call your own code makes: `advance()`, `previous()`,
+ * `goTo()`, `cancel()`, and the same methods on the context of a step action.
+ * The other three are the user acting on the tour UI directly.
+ *
+ * New sources may be added in a minor release: keep a default branch when switching over it.
  */
 export type TourEventSource = "api" | "trigger" | "keyboard" | "overlay";
-/** Name of a monitoring event. */
-export type TourEventType = "tour:start" | "step:enter" | "step:leave" | "tour:complete" | "tour:cancel" | "tour:error";
+/** Name of a monitoring event. New events may be added in a minor release: keep a default branch when switching over it. */
+export type TourEventType = "tour:start" | "step:enter" | "step:leave" | "step:skip" | "tour:complete" | "tour:cancel" | "tour:error";
 /**
  * A monitoring event, as handed to `onEvent`.
  *
@@ -402,7 +504,7 @@ export interface TourEvent {
      * How long the thing this event names had been running, in milliseconds.
      *
      * For `step:leave`, the time spent on that step. For `tour:complete`,
-     * `tour:cancel` and `tour:error`, the time since `run()` was called. For
+     * `tour:cancel` and `tour:error`, the time since `start()` was called. For
      * `tour:start` and `step:enter` — the beginnings — always `0`.
      */
     readonly durationMs: number;
@@ -444,11 +546,6 @@ export type StepParameters<T> = {
     id: string;
     /** The target element or selector for this step. */
     target: TargetResolver;
-    /**
-     * Reset step properties to initial values when entering this step.
-     * @default true
-     */
-    resetPropsOnEnter?: boolean;
     /** Overlay options for this step (overrides workflow defaults). */
     overlay?: OverlayOptions;
     /** Popover options for this step (overrides workflow defaults). */
@@ -457,8 +554,12 @@ export type StepParameters<T> = {
     indicator?: IndicatorOptions;
     /** Step behavior (overrides workflow defaults). */
     behavior?: StepBehavior;
-    /** The title content for this step. */
-    title: T;
+    /** Navigation controls for this step (overrides workflow defaults field by field). See `TourControls`. */
+    controls?: TourControls;
+    /** Classes added to the tour components on this step (overrides workflow defaults per component). See `TourClassNames`. */
+    classNames?: TourClassNames;
+    /** The title content for this step. Without a title, the popover is named by its content. */
+    title?: T;
     /** The body content for this step. */
     content: T;
     /** Arbitrary data associated with this step. */

package/utils/options.d.ts

@@ -1,7 +1,19 @@
-import type { AnimationOptions, IndicatorOptions, OverlayOptions, PopoverOptions, ScrollOptions, StepBehavior } from "../types";
+import type { DeepReadonly, ReadonlyStepProps } from "../definition";
+import type { AnimationOptions, IndicatorOptions, OverlayOptions, PopoverOptions, ScrollOptions, StepBehavior, StepPropsPatch, TourControls } from "../types";
+/**
+ * Merges a partial change into step props: fields it leaves out are kept, `data` is merged key by
+ * key, `overlay` / `popover` / `indicator` / `behavior` / `controls` go through their option merges,
+ * `classNames` is merged per component, and arrays are replaced.
+ * Builds a step's initial props over the workflow defaults, and backs `StepPropsStore.update`.
+ */
+export declare function mergeStepProps<T>(base: StepPropsPatch<T>, patch: StepPropsPatch<T>): ReadonlyStepProps<T>;
 export declare function mergeOverlayOptions(defaults?: OverlayOptions, overrides?: OverlayOptions): OverlayOptions | undefined;
 export declare function mergeIndicatorOptions(defaults?: IndicatorOptions, overrides?: IndicatorOptions): IndicatorOptions | undefined;
 export declare function mergePopoverOptions(defaults?: PopoverOptions, overrides?: PopoverOptions): PopoverOptions | undefined;
 export declare function mergeScrollOptions(defaults?: ScrollOptions, overrides?: ScrollOptions): ScrollOptions | undefined;
 export declare function mergeAnimationOptions(defaults?: AnimationOptions, overrides?: AnimationOptions): AnimationOptions | undefined;
 export declare function mergeStepBehavior(defaults?: StepBehavior, overrides?: StepBehavior): StepBehavior | undefined;
+/** Whether a control is enabled, so its button, keys and `overlayClick` may run its command. */
+export declare function isControlAvailable(props: {
+    readonly controls?: DeepReadonly<TourControls>;
+} | undefined, command: "advance" | "previous" | "cancel"): boolean;

package/utils/utils.d.ts

@@ -10,15 +10,16 @@ export declare function isNode(value: unknown, context?: Node | null): value is
  * `getBoundingClientRect()` reports coordinates in.
  *
  * Deliberately not `innerWidth`/`innerHeight`: those measure the *visual*
- * viewport, which on mobile shrinks and grows with the browser's URL bar and on
- * desktop includes the classic scrollbar. Either gap skews the overlay's
- * `viewBox` against its own `100%`-sized box, and the default
- * `preserveAspectRatio` then scales and centres the backdrop — leaving undimmed
- * bands and a cutout that no longer lines up with its target.
+ * viewport on some engines, which on mobile shrinks and grows with the
+ * browser's URL bar and pinch zoom, and on desktop includes the classic
+ * scrollbar. Either gap skews the overlay's `viewBox` against its own
+ * `100%`-sized box, and the default `preserveAspectRatio` then scales and
+ * centres the backdrop — leaving undimmed bands and a cutout that no longer
+ * lines up with its target.
  */
 export declare function viewportDimensions(context?: Node | null): {
-    width: number;
     height: number;
+    width: number;
 };
 /**
  * The box the overlay `<svg>` is actually painted into, in CSS pixels.
@@ -36,8 +37,8 @@ export declare function viewportDimensions(context?: Node | null): {
  * yet — detached nodes, server-rendered markup, test doubles.
  */
 export declare function paintedBoxDimensions(element?: Element | null): {
-    width: number;
     height: number;
+    width: number;
 };
 export declare function isInViewport(rect: {
     left: number;
@@ -55,7 +56,14 @@ export declare function roundedRectPath(rect: RectGeometry, viewport: {
     padding: number;
     radius: number;
 }, context?: Node | null): string;
+/** Whether a target resolution is still pending, i.e. the resolver returned a promise. */
+export declare function isPendingTarget(value: HTMLElement | null | Promise<HTMLElement | null>): value is Promise<HTMLElement | null>;
+/**
+ * Resolves a step's target. Deliberately not `async`: a selector or an element target settles
+ * synchronously, and only a resolver that returns a promise hands back something to wait on.
+ * Callers use {@link isPendingTarget} to tell the two apart, and a tour that has to wait says so.
+ */
 export declare function resolveTargetElement(target: TargetResolver, options: {
     readonly document?: Document;
     readonly signal: AbortSignal;
-}, path?: string): Promise<HTMLElement | null>;
+}, path?: string): HTMLElement | null | Promise<HTMLElement | null>;