@glowhop/core-tour 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @glowhop/core-tour
 
+## 1.3.0
+
+### Minor Changes
+
+- b38bc4a: Present a step while its scroll is still in flight.
+  
+  Entering a step whose target was off screen used to stall: the tour waited for
+  the smooth scroll to finish before initialising anything, so the previous step's
+  elements sat frozen for the whole journey and everything then snapped into place
+  at once. On Safari before 18.2, where `scrollend` does not exist, that wait was a
+  full second on every step.
+  
+  The scroll now runs alongside the presentation. The spotlight appears
+  immediately and tracks the target as the page travels; the popover and the
+  pointer enter once the page has come to rest, on a rect that will not move
+  again. When a step scrolls, the spotlight moves with the page rather than
+  morphing from the previous step's cutout; steps that do not scroll keep the
+  morph.
+  
+  Scroll completion is detected by watching the scroller hold still rather than by
+  listening for `scrollend`, so every engine behaves the same. A hidden document,
+  which neither animates a smooth scroll nor runs frames often enough to watch one
+  settle, does not wait at all.
+  
+  When a step scrolls is unchanged: only when part of its target falls outside the
+  viewport, and never when `disableAutoScroll` is set.
+  
+  Two smaller behaviour changes fall out of this. The pointer now arrives together
+  with the popover rather than with the spotlight, since its placement is resolved
+  against the popover's. And a target lost while its step is still scrolling no
+  longer freezes the presentation, because a freeze in that window could never be
+  recovered.
+
 ## 1.2.0
 
 ### Minor Changes

package/README.md

@@ -22,7 +22,7 @@ const workflow = tour.create("intro").step({ id: "welcome", target: "#welcome",
 | --- | --- | --- |
 | Placement | `popover.placementTryOrder`, `indicator.placementTryOrder` | Try `top`, `bottom`, `left`, `right`; the resolved position may be `center`. |
 | Interaction | `behavior.allowInteraction` | Allows pointer interaction through the overlay. |
-| Scroll | step/start `scroll` | Uses `behavior`, `block`, and `inline` scroll options. |
+| Scroll | step/start `scroll` | Uses `behavior`, `block`, and `inline` scroll options. The step appears without waiting for the scroll. |
 | Callbacks | `onStart`, `onCancel`, `onFinish`; `beforeAdvance`, `beforePrevious`, `beforeCancel` | Start callbacks are workflow options; transition callbacks are step builder methods. |
 | Actions | `.do(fn)`, `.wait(ms)`, `.waitUntil(fn)`, `.waitUntilElement(selector)` | `waitUntil` defaults to a 16 ms interval and 3000 ms timeout. |
 | Target events | `.onTargetEvent("click", fn)` | Handlers receive the event and step context. |

package/dom/tour-view-driver.d.ts

@@ -58,6 +58,13 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
      * (the caller gave up and is tearing the presentation down).
      */
     private frozen;
+    /**
+     * True between the spotlight's entrance and the popover's, the window in
+     * which a step's scroll is still travelling. The tracking loop drives the
+     * spotlight alone while it is set, and a lost target stops the tracking
+     * instead of freezing the presentation.
+     */
+    private awaitingStepUi;
     private activeTarget;
     private targetFocusedAtFreeze;
     private lastTargetRect;
@@ -74,7 +81,7 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private rafId;
     private rafCancel;
     private root;
-    private scrollAbort;
+    private cancelScroll;
     constructor(commands?: TourViewCommands);
     setCommands(commands: TourViewCommands): void;
     registerRoot(element: HTMLElement | null): void;
@@ -91,7 +98,33 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private syncModality;
     private releaseModality;
     private restoreInertBranches;
+    /**
+     * Brings the spotlight onto the target, then hands the step's popover and
+     * pointer over, in that order but not in lockstep.
+     *
+     * The spotlight's entrance never gates the popover's: the two animate side
+     * by side, as they always have. What does gate the popover is the step's
+     * scroll. It is pinned by a transform it only rewrites on entrance, so a
+     * rect that is still travelling would make it jump through a fade every
+     * fifty pixels; it waits for the page to stop and enters on a rect that will
+     * not move again. Meanwhile the spotlight tracks the target down the page.
+     */
     private appear;
+    /**
+     * Retires the outgoing popover, commits the incoming step's content in its
+     * place, waits out the step's scroll, and brings the popover and pointer in.
+     *
+     * Deliberately one async frame. With nothing to retire, nothing to commit
+     * and nothing to scroll, the entrance animations are created in the tick
+     * this was called in — which is what callers that abort mid-flight rely on,
+     * since `cancelAnimationsOnAbort` can only cancel animations that exist.
+     *
+     * The content commit runs even when no popover is mounted: it carries the
+     * controller's step-index commit and must not be skipped.
+     */
+    private presentStepUi;
+    /** The popover and pointer entrance itself, started synchronously. */
+    private enterStepUi;
     private attachStepResources;
     /**
      * Binds the step's custom event handlers to its target element. Split out
@@ -102,7 +135,15 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private attachTargetResources;
     private listen;
     private schedulePosition;
+    /**
+     * Frame scheduling for the target's own realm, falling back to the ambient
+     * one when that realm exposes no frame callbacks. Shared by the tracking
+     * loop and the scroll sentinel so both read the same clock.
+     */
+    private frameScheduler;
     private updatePosition;
+    /** Per-frame follow-up for the popover and pointer, once they are on screen. */
+    private trackStepUi;
     private observeDynamicOperation;
     private handleKeydown;
     private handleOverlayClick;
@@ -176,7 +217,31 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private cancelAnimationsOnAbort;
     private cancelElementAnimations;
     private isCurrentGeneration;
-    private scrollTargetIntoView;
+    /**
+     * Starts the step's scroll and returns a promise that settles once the page
+     * has stopped moving, or `null` when there is nothing to wait for — the step
+     * opts out, the scroll was applied instantly, or no scroller can be measured.
+     *
+     * `scrollIntoView` is called synchronously so a throwing call still rejects
+     * the `show()` that asked for it. Only the wait is deferred, which is what
+     * lets the backdrop appear while the page is still travelling.
+     */
+    private beginTargetScroll;
+    /**
+     * Resolves once the scroller has held still for a couple of frames.
+     *
+     * Deliberately not the `scrollend` event: Safari only fires it from 18.2, so
+     * older versions would fall through to the safety timeout on every step, and
+     * the presentation would stay pinned to a stale position long after the page
+     * actually stopped. Watching the offset costs a frame loop the browser is
+     * already running during a smooth scroll, works everywhere, and settles just
+     * as quickly when the browser decides there was nothing to scroll at all.
+     *
+     * Returns `null` when the offset cannot be read or frames cannot be
+     * requested — there is then no way to observe the scroll, so callers treat it
+     * as already finished rather than blocking on something unobservable.
+     */
+    private waitForScrollToSettle;
     private throwIfAborted;
     private throwIfStale;
     private getWindow;

package/elements/overlay.d.ts

@@ -7,7 +7,18 @@ export default class OverlayElement extends GlowTourElement {
     private visualState;
     private cssPathDSupported;
     setInteractionAllowed(allowed: boolean): void;
-    moveToTarget(nextPosition: DOMRect, step: TourElementStep): Promise<void>;
+    /**
+     * Brings the cutout onto `nextPosition`, morphing from wherever it was.
+     *
+     * Pass `tracked` when the caller will drive the geometry itself frame by
+     * frame, as it does while a step's scroll is in flight. An animation on the
+     * `d` property overrides the inline value for as long as it runs, so those
+     * per-frame writes would be invisible and the cutout would land on the rect
+     * captured here — the target's position before the page moved — then jump.
+     * Tracked, the geometry is committed once and left alone; only opacity is
+     * ever animated.
+     */
+    moveToTarget(nextPosition: DOMRect, step: TourElementStep, tracked?: boolean): Promise<void>;
     animateTo(position: DOMRect, step: TourElementStep): Promise<void>;
     _getNextStyles(position: DOMRect, step: TourElementStep): Keyframe;
     /** The backdrop with a hole punched around `position`, as a CSS `d` value. */

package/elements/popover.d.ts

@@ -16,7 +16,15 @@ export default class PopoverElement extends GlowTourElement {
     resolvePosition(targetPosition: DOMRect, step: TourElementStep): PopoverPosition;
     private _centerPosition;
     private _applyPositionState;
-    moveToTarget(nextPosition: DOMRect, step: TourElementStep, appear: boolean, onChange?: () => void | Promise<void>): Promise<void>;
+    /**
+     * Fades the popover in at `nextPosition` and commits that placement.
+     *
+     * The outgoing half of a step change is {@link disappear}, deliberately kept
+     * separate: between the two, the caller swaps the step's content while the
+     * popover is off screen, and — when the step scrolls — waits for the scroll
+     * to settle so this entrance reads a rect that will not move again.
+     */
+    present(nextPosition: DOMRect, step: TourElementStep): Promise<void>;
     initializeProps(): void;
     updatePosition(nextPosition: DOMRect, step: TourElementStep, onReposition?: (reposition: Promise<void>) => void): ResolvedPlacement;
     cancelAnimations(): void;

package/index.js

@@ -655,7 +655,7 @@ class OverlayElement extends GlowTourElement {
     this.element.style.setProperty("pointer-events", allowed ? "none" : "auto");
     this.element.setAttribute("data-glow-tour-allow-interaction", String(allowed));
   }
-  async moveToTarget(nextPosition, step) {
+  async moveToTarget(nextPosition, step, tracked = false) {
     const nextVisualState = this._getVisualState(step);
     const path = this._getPathElement();
     if (!path) {
@@ -675,8 +675,13 @@ class OverlayElement extends GlowTourElement {
         ...this._getAnimationOptions(),
         fill: "none"
       }, path);
-      if (!animation2 || await this._waitForAnimation(animation2))
-        this.applyStyles(path, keyframe);
+      if (!animation2 || await this._waitForAnimation(animation2)) {
+        this.applyStyles(path, tracked ? { opacity } : keyframe);
+      }
+      return;
+    }
+    if (tracked) {
+      this.applyStyles(path, keyframe);
       return;
     }
     const baseStyle = {
@@ -1509,12 +1514,7 @@ class PopoverElement extends GlowTourElement {
       }
     }
   }
-  async moveToTarget(nextPosition, step, appear, onChange) {
-    if (!appear) {
-      await this._disappear();
-    }
-    if (onChange)
-      await onChange();
+  async present(nextPosition, step) {
     await this._appear(nextPosition, step);
   }
   initializeProps() {
@@ -1892,7 +1892,10 @@ class ScrollLock {
 }
 
 // packages/core/src/dom/tour-view-driver.ts
-var DEFAULT_SCROLL_END_TIMEOUT = 1000;
+var SCROLL_SETTLE_STILL_FRAMES = 2;
+var SCROLL_SETTLE_GRACE_FRAMES = 3;
+var SCROLL_SETTLE_EPSILON = 0.5;
+var SCROLL_SETTLE_TIMEOUT = 2000;
 var ACTIVE_MODAL_BY_DOCUMENT = new WeakMap;
 var DEFAULT_SHORTCUTS = {
   previous: ["ArrowLeft", "Backspace"],
@@ -1913,6 +1916,7 @@ class DomTourViewDriver {
   generation = 0;
   active = false;
   frozen = false;
+  awaitingStepUi = false;
   activeTarget = null;
   targetFocusedAtFreeze = false;
   lastTargetRect = null;
@@ -1929,7 +1933,7 @@ class DomTourViewDriver {
   rafId = null;
   rafCancel = null;
   root = null;
-  scrollAbort = null;
+  cancelScroll = null;
   constructor(commands) {
     this.commands = commands ?? null;
   }
@@ -2000,6 +2004,7 @@ class DomTourViewDriver {
       this.lastTargetRect = null;
       this.lastViewport = null;
       this.presentationDirty = false;
+      this.awaitingStepUi = true;
       if (replaceVisiblePopover) {
         const listener = (event) => this.queueTransitionKeydown(event, step, generation);
         const currentWindow = this.getWindow();
@@ -2013,12 +2018,13 @@ class DomTourViewDriver {
         return;
       this.activeTarget = target;
       this.syncModality(step.behavior?.allowInteraction === true);
-      await this.scrollTargetIntoView(step, target, signal);
+      const scrolling = this.beginTargetScroll(step, target, signal);
       this.throwIfStale(generation, signal);
       this.initializeElements(step);
-      const targetRect = target.getBoundingClientRect();
-      await this.appear(targetRect, step, !replaceVisiblePopover, onBeforePopoverAppear);
+      const resolveRect = () => target.getBoundingClientRect();
+      await this.appear(resolveRect, step, generation, scrolling, replaceVisiblePopover, onBeforePopoverAppear);
       this.throwIfStale(generation, signal);
+      const targetRect = resolveRect();
       this.lastTargetRect = snapshotRect(targetRect);
       this.lastViewport = snapshotViewport(target);
       this.active = true;
@@ -2051,6 +2057,7 @@ class DomTourViewDriver {
       this.throwIfStale(generation, signal);
       this.active = false;
       this.frozen = false;
+      this.awaitingStepUi = false;
       this.activeTarget = null;
       this.targetFocusedAtFreeze = false;
       this.currentStep = null;
@@ -2078,6 +2085,7 @@ class DomTourViewDriver {
     this.scrollLock.deactivate();
     this.active = false;
     this.frozen = false;
+    this.awaitingStepUi = false;
     this.activeTarget = null;
     this.targetFocusedAtFreeze = false;
     this.currentStep = null;
@@ -2117,7 +2125,8 @@ class DomTourViewDriver {
       return;
     this.activeTarget = target;
     this.initializeElements(step);
-    await this.appear(targetRect, step);
+    this.awaitingStepUi = true;
+    await this.appear(() => targetRect, step, generation, null, false);
     this.throwIfStale(generation);
     this.activateFocus(step, target, this.direction, generation);
     this.syncScrollLock(step);
@@ -2190,19 +2199,34 @@ class DomTourViewDriver {
         element.setAttribute("inert", previous);
     }
   }
-  async appear(targetRect, step, appearPopover = true, onBeforePopoverAppear) {
-    const pointerEnabled = this.isPointerEnabled(step);
-    const popoverPlacement = this.popover?.resolvePosition(targetRect, step).placement;
-    const commitStep = onBeforePopoverAppear ? async () => {
+  async appear(resolveRect, step, generation, scrolling, hadVisiblePopover, onBeforePopoverAppear) {
+    const spotlightRect = resolveRect();
+    const stepUi = this.presentStepUi(resolveRect, step, generation, scrolling, hadVisiblePopover, onBeforePopoverAppear);
+    const spotlight = this.overlay?.moveToTarget(spotlightRect, step, scrolling !== null);
+    if (scrolling)
+      this.schedulePosition(generation);
+    await Promise.all([spotlight ?? Promise.resolve(), stepUi]);
+  }
+  async presentStepUi(resolveRect, step, generation, scrolling, hadVisiblePopover, onBeforePopoverAppear) {
+    if (hadVisiblePopover)
+      await this.popover?.disappear();
+    if (onBeforePopoverAppear) {
       await onBeforePopoverAppear();
       this.syncControlState(step);
       this.syncShortcutLabels(step);
-    } : undefined;
-    const popoverTransition = this.popover ? this.popover.moveToTarget(targetRect, step, appearPopover, commitStep) : Promise.resolve(commitStep?.());
-    await Promise.all([
-      this.overlay?.moveToTarget(targetRect, step) ?? Promise.resolve(),
-      popoverTransition,
-      pointerEnabled ? this.pointer?.moveToTarget(targetRect, step, true, popoverPlacement) ?? Promise.resolve() : this.pointer?.disappear() ?? Promise.resolve()
+    }
+    if (scrolling)
+      await scrolling;
+    if (!this.isCurrentGeneration(generation) || this.currentSignal?.aborted)
+      return;
+    this.awaitingStepUi = false;
+    await this.enterStepUi(resolveRect(), step);
+  }
+  enterStepUi(targetRect, step) {
+    const popoverPlacement = this.popover?.resolvePosition(targetRect, step).placement;
+    return Promise.all([
+      this.popover?.present(targetRect, step) ?? Promise.resolve(),
+      this.isPointerEnabled(step) ? this.pointer?.moveToTarget(targetRect, step, true, popoverPlacement) ?? Promise.resolve() : this.pointer?.disappear() ?? Promise.resolve()
     ]);
   }
   attachStepResources(step, target, generation, signal) {
@@ -2275,17 +2299,11 @@ class DomTourViewDriver {
   schedulePosition(generation = this.generation) {
     if (!this.isCurrentGeneration(generation) || !this.currentStep || this.rafId !== null || this.frozen)
       return;
-    const owner = this.currentStep.target?.ownerDocument?.defaultView;
-    const ownerRequest = owner?.requestAnimationFrame;
-    const ownerCancel = owner?.cancelAnimationFrame;
-    const ownerHasFrameCapability = typeof ownerRequest === "function" || typeof ownerCancel === "function";
-    const request = ownerHasFrameCapability ? ownerRequest : globalThis.requestAnimationFrame;
-    const cancel = ownerHasFrameCapability ? ownerCancel : globalThis.cancelAnimationFrame;
-    if (typeof request !== "function" || typeof cancel !== "function")
+    const frames = this.frameScheduler(this.currentStep.target);
+    if (!frames)
       return;
-    const frameWindow = ownerHasFrameCapability && owner ? owner : globalThis;
-    this.rafCancel = (id) => cancel.call(frameWindow, id);
-    this.rafId = request.call(frameWindow, () => {
+    this.rafCancel = frames.cancel;
+    this.rafId = frames.request(() => {
       this.rafId = null;
       this.rafCancel = null;
       if (!this.isCurrentGeneration(generation))
@@ -2294,13 +2312,29 @@ class DomTourViewDriver {
       this.schedulePosition(generation);
     });
   }
+  frameScheduler(context) {
+    const owner = context?.ownerDocument?.defaultView;
+    const ownerRequest = owner?.requestAnimationFrame;
+    const ownerCancel = owner?.cancelAnimationFrame;
+    const ownerHasFrameCapability = typeof ownerRequest === "function" || typeof ownerCancel === "function";
+    const request = ownerHasFrameCapability ? ownerRequest : globalThis.requestAnimationFrame;
+    const cancel = ownerHasFrameCapability ? ownerCancel : globalThis.cancelAnimationFrame;
+    if (typeof request !== "function" || typeof cancel !== "function")
+      return null;
+    const frameWindow = ownerHasFrameCapability && owner ? owner : globalThis;
+    return {
+      request: (callback) => request.call(frameWindow, callback),
+      cancel: (id) => cancel.call(frameWindow, id)
+    };
+  }
   updatePosition(generation) {
     const step = this.currentStep;
     const target = step?.target;
     if (!this.isCurrentGeneration(generation) || !step || !target)
       return;
     if (!this.isCurrentTargetAvailable(target)) {
-      this.freezeForDisconnectedTarget(step, target, generation);
+      if (!this.awaitingStepUi)
+        this.freezeForDisconnectedTarget(step, target, generation);
       return;
     }
     const targetRect = target.getBoundingClientRect();
@@ -2317,6 +2351,14 @@ class DomTourViewDriver {
       this.syncShortcutLabels(step);
     }
     this.overlay?.updatePosition(targetRect, step, presentationChanged, (transition) => this.observeDynamicOperation(transition, generation));
+    if (!this.awaitingStepUi)
+      this.trackStepUi(targetRect, step, generation, presentationChanged);
+    this.lastTargetRect = targetSnapshot;
+    this.lastViewport = viewportSnapshot;
+    if (presentationChanged)
+      this.presentationDirty = false;
+  }
+  trackStepUi(targetRect, step, generation, presentationChanged) {
     const popoverPlacement = this.popover?.updatePosition(targetRect, step, (reposition) => this.observeDynamicOperation(reposition, generation));
     if (presentationChanged) {
       this.pointer?.syncVisibility(this.isPointerEnabled(step), targetRect, step, popoverPlacement);
@@ -2330,10 +2372,6 @@ class DomTourViewDriver {
     } else if (this.pointer?.getElement()?.getAttribute("aria-hidden") !== "true") {
       this.observeDynamicOperation(this.pointer?.disappear(), generation);
     }
-    this.lastTargetRect = targetSnapshot;
-    this.lastViewport = viewportSnapshot;
-    if (presentationChanged)
-      this.presentationDirty = false;
   }
   observeDynamicOperation(operation, generation) {
     if (!operation)
@@ -2600,8 +2638,8 @@ class DomTourViewDriver {
     return step.behavior?.allowInteraction === true && step.indicator?.disabled !== true;
   }
   cleanupStepResources() {
-    this.scrollAbort?.abort();
-    this.scrollAbort = null;
+    this.cancelScroll?.();
+    this.cancelScroll = null;
     this.presentationDirty = false;
     if (this.rafId !== null)
       this.rafCancel?.(this.rafId);
@@ -2715,45 +2753,77 @@ class DomTourViewDriver {
   isCurrentGeneration(generation) {
     return !this.disposed && generation === this.generation;
   }
-  async scrollTargetIntoView(step, target, signal) {
+  beginTargetScroll(step, target, signal) {
     this.throwIfAborted(signal);
-    if (step.behavior?.disableAutoScroll || isInViewport(target.getBoundingClientRect(), target))
-      return;
+    if (step.behavior?.disableAutoScroll)
+      return null;
+    if (isInViewport(target.getBoundingClientRect(), target))
+      return null;
     const currentWindow = this.getWindow(target);
     if (!currentWindow)
-      return;
-    const controller = new AbortController;
-    this.scrollAbort = controller;
-    await new Promise((resolve, reject) => {
+      return null;
+    const behavior = prefersReducedMotion(target) ? "instant" : step.behavior?.scroll?.behavior ?? "smooth";
+    target.scrollIntoView({
+      behavior,
+      block: step.behavior?.scroll?.block ?? "center",
+      inline: step.behavior?.scroll?.inline ?? "nearest"
+    });
+    if (behavior === "instant")
+      return null;
+    return this.waitForScrollToSettle(target, signal);
+  }
+  waitForScrollToSettle(target, signal) {
+    const owner = ownerDocument(target);
+    const scroller = owner?.scrollingElement;
+    if (typeof scroller?.scrollTop !== "number")
+      return null;
+    const frames = this.frameScheduler(target);
+    if (!frames)
+      return null;
+    if (owner?.visibilityState === "hidden")
+      return null;
+    return new Promise((resolve, reject) => {
+      let frame = null;
       let timeout = null;
-      const abort = () => finish(abortError2());
+      let left = scroller.scrollLeft;
+      let top = scroller.scrollTop;
+      let stillFrames = -SCROLL_SETTLE_GRACE_FRAMES;
       const finish = (error) => {
-        currentWindow.removeEventListener("scrollend", complete);
-        signal.removeEventListener("abort", abort);
-        controller.signal.removeEventListener("abort", abort);
+        if (frame !== null)
+          frames.cancel(frame);
         if (timeout !== null)
           clearTimeout(timeout);
-        if (this.scrollAbort === controller)
-          this.scrollAbort = null;
+        signal.removeEventListener("abort", abort);
+        owner?.removeEventListener("visibilitychange", stopIfHidden);
+        if (this.cancelScroll === abort)
+          this.cancelScroll = null;
         if (error)
           reject(error);
         else
           resolve();
       };
-      const complete = () => finish();
-      currentWindow.addEventListener("scrollend", complete, { once: true });
+      const abort = () => finish(abortError2());
+      const stopIfHidden = () => {
+        if (owner?.visibilityState === "hidden")
+          finish();
+      };
+      const watch = () => {
+        frame = null;
+        const nextLeft = scroller.scrollLeft;
+        const nextTop = scroller.scrollTop;
+        const still = Math.abs(nextLeft - left) <= SCROLL_SETTLE_EPSILON && Math.abs(nextTop - top) <= SCROLL_SETTLE_EPSILON;
+        left = nextLeft;
+        top = nextTop;
+        stillFrames = still ? stillFrames + 1 : 0;
+        if (stillFrames >= SCROLL_SETTLE_STILL_FRAMES)
+          return finish();
+        frame = frames.request(watch);
+      };
+      this.cancelScroll = abort;
       signal.addEventListener("abort", abort, { once: true });
-      controller.signal.addEventListener("abort", abort, { once: true });
-      timeout = setTimeout(complete, DEFAULT_SCROLL_END_TIMEOUT);
-      try {
-        target.scrollIntoView({
-          behavior: prefersReducedMotion(target) ? "instant" : step.behavior?.scroll?.behavior ?? "smooth",
-          block: step.behavior?.scroll?.block ?? "center",
-          inline: step.behavior?.scroll?.inline ?? "nearest"
-        });
-      } catch (error) {
-        finish(error instanceof Error ? error : new Error(String(error)));
-      }
+      owner?.addEventListener("visibilitychange", stopIfHidden);
+      timeout = setTimeout(finish, SCROLL_SETTLE_TIMEOUT);
+      frame = frames.request(watch);
     });
   }
   throwIfAborted(signal) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glowhop/core-tour",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Framework-agnostic tour controller and DOM runtime for GlowTour.js.",
   "license": "MIT",
   "homepage": "https://github.com/Glowhop/GlowTour.js#readme",
@@ -10,8 +10,17 @@
   "keywords": [
     "tour",
     "guided-tour",
+    "product-tour",
     "onboarding",
-    "dom"
+    "walkthrough",
+    "user-onboarding",
+    "tooltip",
+    "spotlight",
+    "typescript",
+    "dom",
+    "headless",
+    "framework-agnostic",
+    "ssr"
   ],
   "engines": {
     "node": ">=18.19.1"

package/types/index.d.ts

@@ -55,12 +55,12 @@ export interface IndicatorOptions extends BaseOptions {
     disabled?: boolean;
     /** Gap between the target and the indicator in pixels. */
     gap?: number;
-    /** Placement preference order when positioning the indicator. @default ["bottom", "top", "right", "left"] */
+    /** Placement preference order when positioning the indicator. @default ["left", "right", "top", "bottom"] */
     placementTryOrder?: readonly TryOrderOptions[];
 }
 /** Configures the darkened overlay backdrop that highlights the target. */
 export interface OverlayOptions extends BaseOptions {
-    /** Color of the overlay backdrop (CSS color). @default "rgba(0, 0, 0, 0.5)" */
+    /** Color of the overlay backdrop (CSS color). Falls back to the `--glow-tour-overlay-color` theme variable when unset. */
     color?: string;
     /** Opacity of the overlay (0-1). @default 0.7 */
     opacity?: number;
@@ -77,11 +77,11 @@ export interface PopoverArrowOptions {
     color?: string;
     /** Size of the arrow in pixels. @default 12 */
     size?: number;
-    /** Border width of the arrow in pixels. @default 0 */
+    /** Border width of the arrow in pixels. Falls back to the `--glow-tour-arrow-border-width` theme variable (`1px`) when unset. */
     borderWidth?: number;
     /** Border radius of the arrow in pixels. @default 0 */
     borderRadius?: number;
-    /** Gap between arrow tip and the target edge in pixels. @default 8 */
+    /** Minimum gap the arrow keeps from the popover edges, in pixels. A placement whose arrow would fall inside this margin is rejected in favour of the next one. @default 16 */
     edgePadding?: number;
     /**
      * CSP nonce applied to the `<style>` element GlowTour.js injects for the
@@ -98,7 +98,7 @@ export interface PopoverArrowOptions {
 }
 /** Configures the popover box that displays content for each step. */
 export interface PopoverOptions extends BaseOptions {
-    /** Placement preference order for the popover around the target. @default ["top", "bottom", "right", "left"] */
+    /** Placement preference order for the popover around the target. @default ["bottom", "top", "right", "left"] */
     placementTryOrder?: readonly TryOrderOptions[];
     /** Arrow configuration. */
     arrow?: PopoverArrowOptions;
@@ -136,9 +136,16 @@ export interface PopoverOptions extends BaseOptions {
         cancel?: readonly string[];
     };
 }
-/** Scroll behavior options passed to Element.scrollIntoView(). */
+/**
+ * Scroll behavior options passed to Element.scrollIntoView().
+ *
+ * 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.
+ */
 export interface ScrollOptions {
-    /** Scroll animation. @default "auto" */
+    /** Scroll animation. Forced to `"instant"` when the user prefers reduced motion. @default "smooth" */
     behavior?: "auto" | "smooth";
     /** Vertical alignment of the target in the viewport. @default "center" */
     block?: "start" | "center" | "end" | "nearest";