@robertlinde/react-tour-kit 0.8.8 → 1.0.0

package/dist/shared/engine/tour-engine.js

@@ -0,0 +1,787 @@
+import { boxesEqual, containsBox, deflate, intersect, projectOnto, sanitizeBox, sanitizeInsets, sanitizeSize, sizesEqual, } from '../geometry/box.util.js';
+import { computeTooltipLayout, getSafeArea } from '../geometry/compute-tooltip-layout.util.js';
+import { buildRevealMargins } from '../geometry/reveal.util.js';
+import { getTargetVisibility } from '../geometry/target-visibility.util.js';
+import { withTimeout } from './abort.util.js';
+import { devWarn, reportError, safeInvoke } from './report.util.js';
+/** Spacing used for layout, shared by both platforms. */
+export const tourLayout = {
+    /** Distance between the highlighted area and the tooltip (arrows are at most this long). */
+    gap: 12,
+    /** Space between the target and the edge of the highlighted area. */
+    highlightPadding: 8,
+    /** Minimum distance between the tooltip and the edge of the safe area. */
+    viewportPadding: 12,
+    /** Minimum distance between an arrow and the tooltip's corners. */
+    arrowPadding: 16,
+};
+/** How long to wait for a step's target to appear before skipping it. */
+export const targetTimeoutMs = 5000;
+/** Safety cap for the renderer to report a tooltip's size; it normally reports within the same frame. */
+const measureTimeoutMs = 1000;
+/** Safety cap for scrolling a target into view. */
+const revealTimeoutMs = 2000;
+/**
+ * Safety cap for `onBeforeStep`. The tour covers the app meanwhile, so it cannot be waiting for the
+ * user; one that never settles would otherwise leave a dimmed screen with no way out.
+ */
+export const beforeStepTimeoutMs = 30_000;
+/** How many tours started from `onTourEnd` callbacks are ended before a new tour starts. */
+const maxChainedEnds = 10;
+/** Size assumed when the renderer never reports one (for example in a test environment without layout). */
+const fallbackTooltipSize = { width: 320, height: 180 };
+const emptySteps = Object.freeze([]);
+const sideOrder = {
+    top: ['top', 'bottom', 'right', 'left'],
+    bottom: ['bottom', 'top', 'right', 'left'],
+    left: ['left', 'right', 'bottom', 'top'],
+    right: ['right', 'left', 'bottom', 'top'],
+};
+/** The part of the viewport that is not covered by insets (notch, keyboard, system bars). */
+function unobstructed(viewport) {
+    return deflate(sanitizeBox(viewport.rect), sanitizeInsets(viewport.insets));
+}
+/** The visible part of the target: clipped by its scroll containers. */
+/**
+ * The visible part of the target: clipped by its scroll containers. A target scrolled completely out
+ * of its container collapses onto the container's nearest edge, where it will appear.
+ */
+function highlightOf(measurement) {
+    if (!measurement.clip) {
+        return measurement.rect;
+    }
+    return intersect(measurement.rect, measurement.clip) ?? projectOnto(measurement.rect, measurement.clip);
+}
+/**
+ * How much of the target the user can see: inside its scroll containers and the screen, and not
+ * covered by elements that stay put (sticky headers, floating buttons). Covered completely counts as
+ * not visible; covered partly as partly visible.
+ */
+function visibilityOf(measurement, screen) {
+    const area = measurement.clip ? intersect(measurement.clip, screen) : screen;
+    const visibility = area ? getTargetVisibility(measurement.rect, area) : 'none';
+    const occluders = measurement.occluders ?? [];
+    if (visibility === 'none' || occluders.length === 0) {
+        return visibility;
+    }
+    if (occluders.some((occluder) => containsBox(occluder, measurement.rect))) {
+        return 'none';
+    }
+    return occluders.some((occluder) => intersect(occluder, measurement.rect) !== undefined) ? 'partial' : visibility;
+}
+function layoutsEqual(a, b) {
+    return (a.placement === b.placement &&
+        Math.abs(a.x - b.x) < 0.01 &&
+        Math.abs(a.y - b.y) < 0.01 &&
+        Math.abs(a.width - b.width) < 0.01 &&
+        Math.abs(a.height - b.height) < 0.01 &&
+        Math.abs(a.maxWidth - b.maxWidth) < 0.01 &&
+        Math.abs(a.maxHeight - b.maxHeight) < 0.01 &&
+        (a.arrowOffset === b.arrowOffset ||
+            (a.arrowOffset !== undefined && b.arrowOffset !== undefined && Math.abs(a.arrowOffset - b.arrowOffset) < 0.01)));
+}
+/**
+ * Creates the platform-independent tour engine: a small store plus the step lifecycle
+ * (`onBeforeStep` → wait for target → measure tooltip → scroll into view → verify → show).
+ *
+ * Every step change is driven by an action, never by a re-render, so user callbacks run exactly
+ * once per navigation no matter how often React renders. Every asynchronous step is cancellable.
+ */
+export function createTourEngine(initialOptions) {
+    let options = initialOptions;
+    const listeners = new Set();
+    let state = {
+        phase: 'idle',
+        session: undefined,
+        currentStep: 0,
+        pendingStepIndex: undefined,
+        shown: undefined,
+        measure: undefined,
+        revealHighlight: undefined,
+    };
+    let publicState = { isActive: false, currentStep: 0, steps: emptySteps, currentTourId: undefined };
+    let viewState = {
+        phase: 'idle',
+        revealHighlight: undefined,
+        followsScroll: initialOptions.adapter.measuresWhileScrolling,
+        tourKey: 0,
+        steps: emptySteps,
+        shown: undefined,
+        measure: undefined,
+    };
+    let sessionCounter = 0;
+    let idCounter = 0;
+    /** Preparation of a step in flight. */
+    let transition;
+    /** Observation of the step on screen. */
+    let stepScope;
+    let shownDetails;
+    let measureSequence = 0;
+    /** A scroll that brings the shown target back into view is running. */
+    let isKeepingInView = false;
+    /** The target moved again while keepInView was scrolling: check once more when it is done. */
+    let isKeepInViewStale = false;
+    /** The scroll of keepInView in flight, stopped when the next step is prepared. */
+    let keepInViewScope;
+    let lastTooltipSize;
+    const reportedSizes = new Map();
+    const sizeWaiters = new Map();
+    let lifecycle = 'live';
+    // -------------------------------------------------------------------------------------------
+    // Store
+    // -------------------------------------------------------------------------------------------
+    /** The public state for `useTour()`; the previous object while nothing in it changed. */
+    function derivePublicState(previous) {
+        const next = {
+            isActive: state.phase !== 'idle',
+            currentStep: state.currentStep,
+            steps: state.session?.source ?? emptySteps,
+            currentTourId: state.session?.tourId,
+        };
+        const isUnchanged = next.isActive === previous.isActive &&
+            next.currentStep === previous.currentStep &&
+            next.steps === previous.steps &&
+            next.currentTourId === previous.currentTourId;
+        return isUnchanged ? previous : next;
+    }
+    /** The state the renderer draws; the previous object while nothing in it changed. */
+    function deriveViewState(previous) {
+        const next = {
+            phase: state.phase,
+            revealHighlight: state.phase === 'revealing' ? state.revealHighlight : undefined,
+            followsScroll: options.adapter.measuresWhileScrolling,
+            tourKey: state.session?.key ?? previous.tourKey,
+            steps: state.session?.steps ?? emptySteps,
+            shown: state.shown,
+            measure: state.measure,
+        };
+        const isUnchanged = next.phase === previous.phase &&
+            next.revealHighlight === previous.revealHighlight &&
+            next.followsScroll === previous.followsScroll &&
+            next.tourKey === previous.tourKey &&
+            next.steps === previous.steps &&
+            next.shown === previous.shown &&
+            next.measure === previous.measure;
+        return isUnchanged ? previous : next;
+    }
+    function setState(patch) {
+        state = { ...state, ...patch };
+        const nextPublic = derivePublicState(publicState);
+        const nextView = deriveViewState(viewState);
+        if (nextPublic === publicState && nextView === viewState) {
+            return;
+        }
+        publicState = nextPublic;
+        viewState = nextView;
+        // Snapshot: listeners may subscribe or unsubscribe while being notified.
+        const snapshot = [...listeners];
+        for (const listener of snapshot) {
+            listener();
+        }
+    }
+    // -------------------------------------------------------------------------------------------
+    // Layout
+    // -------------------------------------------------------------------------------------------
+    function computeLayout(step, highlight, size, previous) {
+        return computeTooltipLayout({
+            ...tourLayout,
+            target: highlight,
+            tooltip: size,
+            viewport: options.adapter.getViewport(step.target),
+            placement: step.placement ?? 'bottom',
+            previousPlacement: previous?.placement,
+            pixelRatio: options.adapter.getPixelRatio?.(),
+        });
+    }
+    function updateShown(measurement, size) {
+        const { shown } = state;
+        if (!shown) {
+            return;
+        }
+        shownDetails = { measurement, size };
+        const highlight = measurement ? highlightOf(measurement) : undefined;
+        const layout = computeLayout(shown.step, highlight, size, shown.layout);
+        if (boxesEqual(highlight, shown.highlight) && layoutsEqual(layout, shown.layout)) {
+            return;
+        }
+        setState({ shown: { ...shown, highlight, layout } });
+    }
+    // -------------------------------------------------------------------------------------------
+    // Step lifecycle
+    // -------------------------------------------------------------------------------------------
+    async function waitForTooltipSize(id, signal) {
+        const reported = reportedSizes.get(id);
+        if (reported) {
+            return reported;
+        }
+        return new Promise((resolve) => {
+            sizeWaiters.set(id, resolve);
+            signal.addEventListener('abort', () => {
+                sizeWaiters.delete(id);
+                resolve(undefined);
+            });
+        });
+    }
+    async function measureTooltip(index, step, signal) {
+        const id = ++idCounter;
+        const safe = getSafeArea(options.adapter.getViewport(step.target), tourLayout.viewportPadding);
+        setState({ measure: { id, stepIndex: index, step, maxWidth: safe.width, maxHeight: safe.height } });
+        const size = await withTimeout(async (childSignal) => waitForTooltipSize(id, childSignal), signal, measureTimeoutMs);
+        reportedSizes.delete(id);
+        return { id, size: size ?? lastTooltipSize ?? fallbackTooltipSize };
+    }
+    /** Scrolls the target into view and returns its measurement if it is (at least partly) visible. */
+    async function reveal(input) {
+        const { target, signal } = input;
+        // While scrolling, the highlight follows the target frame by frame so the user sees where the tour goes.
+        const following = new AbortController();
+        const stopFollowing = () => {
+            following.abort();
+        };
+        signal.addEventListener('abort', stopFollowing);
+        let hasStarted = false;
+        const startFollowing = () => {
+            if (!hasStarted && !signal.aborted) {
+                hasStarted = true;
+                followTarget(target, following.signal).catch(reportError);
+            }
+        };
+        try {
+            return await scrollIntoViewAndVerify({ ...input, startFollowing });
+        }
+        finally {
+            signal.removeEventListener('abort', stopFollowing);
+            stopFollowing();
+        }
+    }
+    /** Moves the reveal highlight with the target, once per frame, until `signal` aborts. */
+    async function followTarget(target, signal) {
+        const { adapter } = options;
+        while (!signal.aborted) {
+            // eslint-disable-next-line no-await-in-loop -- one measurement per frame
+            await adapter.nextFrame(signal);
+            // eslint-disable-next-line no-await-in-loop -- see above
+            const current = signal.aborted ? undefined : await adapter.measure(target);
+            if (!signal.aborted && state.phase === 'revealing' && current) {
+                const highlight = highlightOf(current);
+                if (!boxesEqual(highlight, state.revealHighlight)) {
+                    setState({ revealHighlight: highlight });
+                }
+            }
+        }
+    }
+    async function scrollIntoViewAndVerify({ step, target, measurement, size, signal, startFollowing, }) {
+        const { adapter } = options;
+        const margins = buildRevealMargins({
+            ...tourLayout,
+            target: highlightOf(measurement),
+            tooltip: size,
+            area: unobstructed(adapter.getViewport(target)),
+            sides: sideOrder[step.placement ?? 'bottom'],
+        });
+        // Where the target is now: the second attempt starts where the first one ended.
+        const latest = { measurement };
+        for (const behavior of ['smooth', 'instant']) {
+            // eslint-disable-next-line no-await-in-loop -- the retry depends on the first attempt's outcome
+            await withTimeout(async (childSignal) => {
+                await adapter.reveal(target, {
+                    margins,
+                    behavior,
+                    signal: childSignal,
+                    onScrollStart(destination) {
+                        if (signal.aborted) {
+                            return;
+                        }
+                        if (adapter.measuresWhileScrolling) {
+                            setState({ phase: 'revealing', revealHighlight: highlightOf(latest.measurement) });
+                            startFollowing();
+                        }
+                        else {
+                            // Positions only update once scrolling ends: move the highlight to where the target is
+                            // going, together with the scroll.
+                            const screen = unobstructed(adapter.getViewport(target));
+                            setState({ phase: 'revealing', revealHighlight: highlightOf({ rect: destination, clip: screen }) });
+                        }
+                    },
+                });
+                return true;
+            }, signal, revealTimeoutMs);
+            if (signal.aborted) {
+                return undefined;
+            }
+            // eslint-disable-next-line no-await-in-loop -- see above
+            const current = await adapter.measure(target);
+            if (signal.aborted || !current) {
+                return undefined;
+            }
+            latest.measurement = current;
+            const visibility = visibilityOf(current, unobstructed(adapter.getViewport(target)));
+            if (visibility === 'full') {
+                return current;
+            }
+            // The first attempt can be cut short (the user scrolled, or the page moved while scrolling);
+            // the second one is instant. Partly visible targets are shown, invisible ones are skipped.
+            if (behavior === 'instant') {
+                return visibility === 'partial' ? current : undefined;
+            }
+        }
+        return undefined;
+    }
+    function beginTransition() {
+        transition?.abort();
+        // The step on screen stays observed (and laid out) until the next one is shown; only an
+        // automatic scroll of it stops, so it cannot fight the next step's.
+        keepInViewScope?.abort();
+        keepInViewScope = undefined;
+        const controller = new AbortController();
+        transition = controller;
+        return controller;
+    }
+    /**
+     * Prepares the steps from `requested` on, in the direction of travel, until one can be shown.
+     * Steps whose target cannot be found or brought into view are skipped.
+     */
+    async function prepare(requested, initialDirection, prepareOptions = {}) {
+        const { session } = state;
+        if (!session || lifecycle === 'suspended') {
+            return;
+        }
+        const controller = beginTransition();
+        let index = requested;
+        let direction = initialDirection;
+        let returnedToOrigin = false;
+        while (!controller.signal.aborted) {
+            if (index < 0 || index >= session.steps.length) {
+                if (direction === -1 && prepareOptions.origin !== undefined && !returnedToOrigin) {
+                    // Nothing to show before this step: go back to where the user came from.
+                    returnedToOrigin = true;
+                    index = prepareOptions.origin;
+                    direction = 1;
+                    continue;
+                }
+                finish('target-missing', { stepIndex: Math.min(Math.max(index - direction, 0), session.steps.length - 1) });
+                return;
+            }
+            // eslint-disable-next-line no-await-in-loop -- steps are tried one after another
+            const result = await prepareStep(controller, index, prepareOptions.skipBeforeStepFor !== index);
+            if (result === 'done') {
+                return;
+            }
+            index += direction;
+        }
+    }
+    /**
+     * Runs a step's `onBeforeStep`. Resolves `true` once it has finished, `false` if it did not within
+     * {@link beforeStepTimeoutMs} (its signal is then aborted); rejects with what it throws.
+     */
+    async function callBeforeStep(step, onBeforeStep, parent) {
+        const child = new AbortController();
+        const abortChild = () => {
+            child.abort();
+        };
+        parent.addEventListener('abort', abortChild);
+        let timer;
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                child.abort();
+                resolve(false);
+            }, beforeStepTimeoutMs);
+        });
+        try {
+            const finished = (async () => {
+                await onBeforeStep(step.target, { signal: child.signal });
+                return true;
+            })();
+            return await Promise.race([finished, timedOut]);
+        }
+        finally {
+            clearTimeout(timer);
+            parent.removeEventListener('abort', abortChild);
+        }
+    }
+    /** Runs one step's lifecycle. Resolves `'skip'` when its target cannot be found or shown. */
+    async function prepareStep(controller, index, runBeforeStep) {
+        const { signal } = controller;
+        const step = state.session?.steps[index];
+        if (!step) {
+            return 'done';
+        }
+        setState({ phase: 'preparing', pendingStepIndex: index });
+        try {
+            if (runBeforeStep && step.onBeforeStep) {
+                const isSettled = await callBeforeStep(step, step.onBeforeStep, signal);
+                if (signal.aborted) {
+                    return 'done';
+                }
+                if (!isSettled) {
+                    finish('error', {
+                        stepIndex: index,
+                        error: new Error(`onBeforeStep of step ${index + 1} did not finish within ${beforeStepTimeoutMs / 1000} seconds.`),
+                    });
+                    return 'done';
+                }
+            }
+            const { adapter } = options;
+            const { target } = step;
+            let measurement;
+            if (target !== undefined) {
+                measurement = await withTimeout(async (childSignal) => adapter.waitForTarget(target, childSignal), signal, targetTimeoutMs);
+                if (signal.aborted) {
+                    return 'done';
+                }
+                if (!measurement) {
+                    devWarn(`Skipping step ${index + 1}: its target was not found within ${targetTimeoutMs / 1000} seconds.`);
+                    return 'skip';
+                }
+            }
+            const { id, size } = await measureTooltip(index, step, signal);
+            if (signal.aborted) {
+                return 'done';
+            }
+            if (target !== undefined && measurement) {
+                measurement = await reveal({ step, target, measurement, size, signal });
+                if (signal.aborted) {
+                    return 'done';
+                }
+                if (!measurement) {
+                    devWarn(`Skipping step ${index + 1}: its target could not be scrolled into view.`);
+                    return 'skip';
+                }
+            }
+            show({ controller, id, index, step, measurement, size });
+            return 'done';
+        }
+        catch (error) {
+            if (!signal.aborted) {
+                finish('error', { stepIndex: index, error });
+            }
+            return 'done';
+        }
+    }
+    function show({ controller, id, index, step, measurement, size }) {
+        if (transition === controller) {
+            transition = undefined;
+        }
+        shownDetails = { measurement, size };
+        lastTooltipSize = size;
+        const highlight = measurement ? highlightOf(measurement) : undefined;
+        setState({
+            phase: 'showing',
+            currentStep: index,
+            pendingStepIndex: undefined,
+            measure: undefined,
+            shown: {
+                transitionId: id,
+                stepIndex: index,
+                step,
+                highlight,
+                layout: computeLayout(step, highlight, size, undefined),
+            },
+        });
+        observeShown();
+    }
+    function observeShown() {
+        stepScope?.abort();
+        const { shown } = state;
+        if (!shown) {
+            return undefined;
+        }
+        const scope = new AbortController();
+        stepScope = scope;
+        options.adapter.observe(shown.step.target, () => {
+            void remeasure(scope.signal);
+        }, scope.signal);
+        return scope.signal;
+    }
+    /** `canKeepInView: false` only follows the target (after keepInView's own scroll: no second attempt). */
+    async function remeasure(signal, { canKeepInView = true } = {}) {
+        const sequence = ++measureSequence;
+        const { shown } = state;
+        // While the next step is prepared, the step on screen still follows layout changes (rotation,
+        // resizing), but is neither scrolled back into view nor looked for again: it is about to go.
+        const isShowing = state.phase === 'showing';
+        if (!shown || !shownDetails || (!isShowing && state.phase !== 'preparing')) {
+            return;
+        }
+        const { target } = shown.step;
+        if (target === undefined) {
+            updateShown(undefined, shownDetails.size);
+            return;
+        }
+        const measurement = await options.adapter.measure(target);
+        // The tooltip may have reported a new size meanwhile: use the latest.
+        const size = shownDetails?.size;
+        if (signal.aborted || sequence !== measureSequence || !size || state.shown !== shown) {
+            return;
+        }
+        if (!measurement) {
+            if (state.phase === 'showing') {
+                // The target disappeared (re-mounted, for example): find it again without re-running onBeforeStep.
+                void prepare(shown.stepIndex, 1, { skipBeforeStepFor: shown.stepIndex });
+            }
+            return;
+        }
+        updateShown(measurement, size);
+        if (state.phase === 'showing' && canKeepInView) {
+            void keepInView({ step: shown.step, target, measurement, size, signal });
+        }
+    }
+    /**
+     * When the app moves the shown target out of view (content inserted above it, a resize), scrolls
+     * it back. The step stays on screen and follows the target while it scrolls; nothing is re-run.
+     * Users cannot scroll the page themselves during a tour, so this never fights the user.
+     */
+    async function keepInView({ step, target, measurement, size, signal }) {
+        if (isKeepingInView) {
+            isKeepInViewStale = true;
+            return;
+        }
+        const { adapter } = options;
+        const screen = unobstructed(adapter.getViewport(target));
+        // Only targets that can be seen whole are brought back (larger ones would be scrolled to and fro).
+        // Measured against the screen, not against what is left on screen of the lists around the
+        // target: after a rotation, a list can lie entirely off screen, and that is what scrolling fixes.
+        const fits = measurement.rect.width <= screen.width && measurement.rect.height <= screen.height;
+        if (!fits || visibilityOf(measurement, screen) === 'full') {
+            return;
+        }
+        isKeepingInView = true;
+        isKeepInViewStale = false;
+        let hasScrolled = false;
+        const scope = new AbortController();
+        keepInViewScope = scope;
+        const stop = () => {
+            scope.abort();
+        };
+        signal.addEventListener('abort', stop);
+        try {
+            const margins = buildRevealMargins({
+                ...tourLayout,
+                target: highlightOf(measurement),
+                tooltip: size,
+                area: screen,
+                sides: sideOrder[step.placement ?? 'bottom'],
+            });
+            await withTimeout(async (childSignal) => {
+                await adapter.reveal(target, {
+                    margins,
+                    behavior: 'smooth',
+                    signal: childSignal,
+                    onScrollStart() {
+                        hasScrolled = true;
+                    },
+                });
+                return true;
+            }, scope.signal, revealTimeoutMs);
+        }
+        finally {
+            signal.removeEventListener('abort', stop);
+            isKeepingInView = false;
+            if (keepInViewScope === scope) {
+                keepInViewScope = undefined;
+            }
+            if (!scope.signal.aborted) {
+                if (isKeepInViewStale) {
+                    // Pushed out again while scrolling (more content loaded): check once more.
+                    isKeepInViewStale = false;
+                    void remeasure(signal);
+                }
+                else if (hasScrolled) {
+                    // Where the target ended up: platforms whose scrolling reports no layout events (React
+                    // Native) would otherwise keep the highlight where the target was.
+                    void remeasure(signal, { canKeepInView: false });
+                }
+            }
+        }
+    }
+    function finish(reason, extra = {}) {
+        const { session } = state;
+        if (!session) {
+            return;
+        }
+        const stepIndex = extra.stepIndex ?? state.shown?.stepIndex ?? state.pendingStepIndex ?? state.currentStep;
+        const step = session.steps[stepIndex] ?? session.steps[0];
+        if (!step) {
+            return;
+        }
+        const info = {
+            reason,
+            stepIndex,
+            step,
+            totalSteps: session.steps.length,
+            ...('error' in extra ? { error: extra.error } : {}),
+        };
+        transition?.abort();
+        transition = undefined;
+        stepScope?.abort();
+        stepScope = undefined;
+        shownDetails = undefined;
+        for (const resolve of sizeWaiters.values()) {
+            resolve(lastTooltipSize ?? fallbackTooltipSize);
+        }
+        sizeWaiters.clear();
+        reportedSizes.clear();
+        // Reset before running user code, so a throwing callback can never leave the tour half-open.
+        setState({
+            phase: 'idle',
+            session: undefined,
+            currentStep: 0,
+            pendingStepIndex: undefined,
+            shown: undefined,
+            measure: undefined,
+        });
+        safeInvoke(() => session.onTourEnd?.(session.tourId, info));
+        safeInvoke(() => options.onTourEnd?.(session.tourId, info));
+    }
+    // -------------------------------------------------------------------------------------------
+    // Actions
+    // -------------------------------------------------------------------------------------------
+    const actions = {
+        startTour(steps, tourId, startOptions) {
+            if (lifecycle === 'suspended') {
+                return;
+            }
+            if (steps.length === 0) {
+                devWarn('startTour was called without steps; nothing to show.');
+                return;
+            }
+            const current = state.session;
+            if (current && (tourId === undefined ? steps === current.source : tourId === current.tourId)) {
+                return;
+            }
+            // End the running tour, and any tour its onTourEnd starts, before starting this one.
+            for (let ended = 0; state.session && ended < maxChainedEnds; ended++) {
+                finish('closed');
+            }
+            if (state.session) {
+                devWarn('onTourEnd keeps starting new tours; the last one is replaced without ending it.');
+            }
+            const session = {
+                key: ++sessionCounter,
+                tourId,
+                steps: [...steps],
+                source: steps,
+                onTourEnd: startOptions?.onTourEnd,
+            };
+            lastTooltipSize = undefined;
+            setState({
+                session,
+                phase: 'preparing',
+                currentStep: 0,
+                pendingStepIndex: 0,
+                shown: undefined,
+                measure: undefined,
+            });
+            void prepare(0, 1);
+        },
+        endTour() {
+            finish('closed');
+        },
+        nextStep() {
+            if (lifecycle === 'suspended') {
+                return;
+            }
+            const { session } = state;
+            if (!session || state.phase !== 'showing') {
+                return;
+            }
+            if (state.currentStep >= session.steps.length - 1) {
+                finish('completed');
+                return;
+            }
+            void prepare(state.currentStep + 1, 1, { origin: state.currentStep });
+        },
+        prevStep() {
+            if (lifecycle === 'suspended') {
+                return;
+            }
+            if (!state.session || state.phase !== 'showing' || state.currentStep === 0) {
+                return;
+            }
+            void prepare(state.currentStep - 1, -1, { origin: state.currentStep });
+        },
+        goToStep(index) {
+            if (lifecycle === 'suspended') {
+                return;
+            }
+            const { session } = state;
+            if (!session || !Number.isInteger(index) || index < 0 || index >= session.steps.length) {
+                return;
+            }
+            if (state.phase === 'showing' ? index === state.currentStep : index === state.pendingStepIndex) {
+                return;
+            }
+            const from = state.shown?.stepIndex ?? state.currentStep;
+            void prepare(index, index >= from ? 1 : -1, { origin: state.shown ? from : undefined });
+        },
+    };
+    // -------------------------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------------------------
+    function suspend() {
+        lifecycle = 'suspended';
+        transition?.abort();
+        transition = undefined;
+        stepScope?.abort();
+        stepScope = undefined;
+    }
+    function resume() {
+        lifecycle = 'live';
+        if (state.phase === 'showing') {
+            const signal = observeShown();
+            if (signal) {
+                void remeasure(signal);
+            }
+        }
+        else if (state.phase !== 'idle') {
+            void prepare(state.pendingStepIndex ?? state.currentStep, 1);
+        }
+    }
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        getPublicState: () => publicState,
+        getViewState: () => viewState,
+        actions,
+        configure(next) {
+            options = next;
+        },
+        mount() {
+            if (lifecycle === 'unmounting') {
+                lifecycle = 'live';
+            }
+            else if (lifecycle === 'suspended') {
+                resume();
+            }
+            return () => {
+                lifecycle = 'unmounting';
+                void Promise.resolve().then(() => {
+                    if (lifecycle === 'unmounting') {
+                        suspend();
+                    }
+                });
+            };
+        },
+        reportTooltipSize(id, rawSize) {
+            const size = sanitizeSize(rawSize);
+            if (state.measure?.id === id) {
+                reportedSizes.set(id, size);
+                sizeWaiters.get(id)?.(size);
+                sizeWaiters.delete(id);
+                return;
+            }
+            if (state.shown?.transitionId === id && shownDetails && !sizesEqual(shownDetails.size, size)) {
+                lastTooltipSize = size;
+                updateShown(shownDetails.measurement, size);
+            }
+        },
+        dismiss(reason) {
+            finish(reason);
+        },
+    };
+}
+//# sourceMappingURL=tour-engine.js.map