@glowhop/core-tour 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @glowhop/core-tour
 
+## 1.5.1
+
+### Patch Changes
+
+- e388604: Fix the popover blinking when a step scrolls its target into view on a page that scrolls inside a container rather than the document. The scroll counted as finished a few frames in, so the popover appeared mid-scroll, stepped aside as if the user were scrolling, and came back once the page stopped. The popover now waits until the target itself has stopped moving.
+
+## 1.5.0
+
+### Minor Changes
+
+- 781a1f7: Report the wait when a step's target is still resolving. A target given as an async resolver, or one the `"wait"` strategy is polling for, keeps the tour on the step the user asked to leave: for as long as that wait lasts, the popover on screen carries `data-glow-tour-awaiting-target` and its advance control is disabled, so a tour waiting on a slow target no longer looks idle with a button that does nothing. Both are cleared when the target settles, and `TourState` gains `awaitingTarget` so a UI that renders its own controls - every adapter's trigger components, and any custom one - can show the wait rather than read it from the DOM. Cancel and previous stay available, a target that resolves synchronously never enters this state, and the freeze of a target lost mid-step is unchanged.
+- 91d778a: Add `tour.hidePopover()` and `tour.showPopover()`, also returned by `useGlowTour` and `injectGlowTour`. Hiding the popover keeps the overlay, the indicator and the scroll lock, and the tour keeps running: the page leaves `inert`, focus moves from the popover to the target, and the keyboard shortcuts do nothing until the popover is shown again. It stays hidden across steps, until `showPopover()` or the end of the tour, and a new `start()` shows it again. Showing it replays its entrance, makes the step modal again and moves focus back into it. `TourState` gains `popoverHidden`.
+- d63e152: Step the popover aside while the user scrolls. The popover and the pointer used to chase the target through a fade every few pixels of travel, and settled in the middle of the screen once the target had scrolled out of view. They now fade out at the first scroll and come back once the page has been still for a moment, while the spotlight keeps following the target. When the user left part of the target outside the viewport, the step scrolls it back after the new `behavior.scroll.returnDelay` (500 ms by default, `false` to leave the page where the user put it); scrolling again restarts the wait, and a wheel or touch drag during the scroll back hands the page back. Steps with `allowScroll: false` or `autoScroll: false` do not scroll back.
+
+### Patch Changes
+
+- 2c568ab: Point each package's npm homepage to its page on glowtour.dev instead of the GitHub README, and describe what each package does in its npm description. Package metadata only: no code, API or export changes.
+- f8259bd: Keep the tour aligned on a phone page that is wider than the device and can be zoomed out. The browser then grows the layout viewport past the initial containing block: the overlay stopped short of the bottom of the screen, leaving an undimmed band, and the popover was placed and clamped against the smaller device-width box. The overlay now spans the taller of `100%` and `100lvh`, and placement measures the box `position: fixed` elements actually use.
+
 ## 1.4.0
 
 ### Minor Changes

package/config/index.js

@@ -480,7 +480,7 @@ var BEHAVIOR_KEYS = [
   "scroll",
   "overlayClick"
 ];
-var SCROLL_KEYS = ["behavior", "block", "inline"];
+var SCROLL_KEYS = ["behavior", "block", "inline", "returnDelay"];
 var CONFIG_VERSION = "1.1";
 var BUILTIN_ACTION_KEYS = {
   wait: ["type", "ms"],
@@ -847,6 +847,8 @@ function validateScrollShape(path, value, issues) {
   validateOptionalEnum(`${path}.behavior`, value.behavior, ["auto", "smooth"], issues);
   validateOptionalEnum(`${path}.block`, value.block, ["start", "center", "end", "nearest"], issues);
   validateOptionalEnum(`${path}.inline`, value.inline, ["start", "center", "end", "nearest"], issues);
+  if (value.returnDelay !== false)
+    validateOptionalFiniteNonNegative(`${path}.returnDelay`, value.returnDelay, issues);
 }
 function validateBehaviorShape(path, value, issues) {
   if (value === undefined)

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

@@ -27,6 +27,17 @@ export interface TourViewDriver<T> {
      * than throw.
      */
     retarget(step: ActiveStep<T>, signal: AbortSignal): Promise<void> | void;
+    /**
+     * Reports that the navigation under way is waiting for the next step's
+     * target to resolve. The presented step has not left yet, so its popover is
+     * the one that carries the wait.
+     */
+    setTargetPending?(pending: boolean): void;
+    /**
+     * Hides or shows the popover of the running tour. A step still entering reads it as it is
+     * presented. Every `start()` shows it again first.
+     */
+    setPopoverHidden?(hidden: boolean): void;
     dispose(): void;
     releaseMount?(): void;
     setCommands?(commands: TourViewCommands): void;
@@ -66,6 +77,14 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
      * instead of freezing the presentation.
      */
     private awaitingStepUi;
+    /**
+     * True while the popover and pointer stand aside for a user scroll, until the
+     * page has been still for `USER_SCROLL_IDLE_DELAY` and, when the target was
+     * left off screen, the step has scrolled it back. The spotlight keeps
+     * tracking the target throughout.
+     */
+    private userScrolling;
+    private scrollTimer?;
     private activeTarget;
     private targetFocusedAtFreeze;
     private lastTargetRect;
@@ -85,6 +104,10 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private handledTriggerClick;
     private popover;
     private presentationDirty;
+    /** True while the controller waits for the next step's target, see `setTargetPending`. */
+    private targetPending;
+    /** True while the consumer hides the popover, see `setPopoverHidden`. */
+    private popoverHidden;
     /**
      * The focus a clear gives back once the popover has faded out. Kept past a clear that a new show
      * supersedes, so that tour returns focus there instead of to the fading popover.
@@ -104,6 +127,21 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     registerOverlay(element: SVGSVGElement | null): void;
     registerPopover(element: HTMLElement | null): void;
     registerPointer(element: HTMLElement | null): void;
+    /**
+     * Flags the presented popover as waiting for the next step's target, and
+     * disables its advance control for as long as the wait lasts: the step the
+     * user asked to leave stays on screen, and an advance that is already
+     * refused by the controller must not keep looking available. Cleared by the
+     * controller when the target settles, and by any teardown.
+     */
+    setTargetPending(pending: boolean): void;
+    /**
+     * Hides the popover and hands the page back while it is hidden: nothing is left to trap focus
+     * in, so the page leaves `inert`, focus moves from the popover to the target, and the shortcuts
+     * stop. The overlay, the pointer and the scroll lock stay. Showing it again replays the entrance
+     * and makes the step modal again. A step still entering applies it once presented.
+     */
+    setPopoverHidden(hidden: boolean): void;
     show(step: ActiveStep<T>, direction: TourDirection, signal: AbortSignal, onBeforePopoverAppear?: () => void | Promise<void>): Promise<void>;
     clear(signal: AbortSignal): Promise<void>;
     releaseMount(): void;
@@ -114,6 +152,8 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private syncModality;
     private claimModal;
     private releaseModality;
+    /** Gives the page back without releasing the document's modal claim. */
+    private liftModality;
     private restoreInertBranches;
     /**
      * Brings the spotlight onto the target, then hands the step's popover and
@@ -163,6 +203,34 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private updatePosition;
     /** Per-frame follow-up for the popover and pointer, once they are on screen. */
     private trackStepUi;
+    /**
+     * A scroll of the page, or of a scroller around the target, while the step is
+     * on screen. The popover and pointer stand aside at the first one, since
+     * following a travelling rect would fade them out and in every few pixels,
+     * and come back once the page has been still for a moment.
+     */
+    private onUserScroll;
+    private waitForScrollIdle;
+    /**
+     * The page has been still for a moment: brings the popover and pointer back,
+     * after `scroll.returnDelay` has scrolled the target back into view when the
+     * user left part of it outside.
+     */
+    private settleScroll;
+    /**
+     * Scrolls the target back in. As on entrance, `awaitingStepUi` leaves the
+     * spotlight to follow the page on its own and the scroll events this raises
+     * to be ignored; set together with `userScrolling`, it marks the scroll back,
+     * which a wheel or touch drag interrupts.
+     */
+    private scrollBack;
+    private revealAfterScroll;
+    private stopUserScroll;
+    /**
+     * Moves the popover along with its target and returns its placement. A hidden popover stays
+     * where it is: moving it would fade it back in. The pointer still keeps clear of its placement.
+     */
+    private placePopover;
     private observeDynamicOperation;
     private handleKeydown;
     /**
@@ -180,6 +248,23 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private queueTransitionClick;
     private flushPendingCommand;
     private loopFocus;
+    /**
+     * Makes a presented step modal and moves focus into its popover, or keeps the popover hidden. A
+     * popover shown again after the entrance passed over it enters now.
+     */
+    private engagePopover;
+    /**
+     * Fades the popover out and stops guarding focus. Focus left in the popover goes to the target,
+     * or is dropped when the target cannot take it: `inert` would otherwise drop it on the body. The
+     * focus the tour gives back when it ends is kept for the step that shows the popover again.
+     */
+    private concealPopover;
+    /**
+     * Replays the popover's entrance on the rect the step was last placed on (a frozen step has no
+     * live target to measure), then makes the step modal again.
+     */
+    private revealPopover;
+    private isPopoverConcealed;
     private activateFocus;
     private syncScrollLock;
     private syncShortcutLabels;
@@ -231,8 +316,9 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private applyInteraction;
     /**
      * Applies a `behavior.allowInteraction` changed through the step props while the step is on
-     * screen. A step still entering reads the new value when it presents, and a frozen one keeps
-     * interaction off until `retarget()` restores it. The indicator fades in or out instead of snapping.
+     * screen, or stepped aside for a user scroll. A step still entering reads the new value when it
+     * presents, and a frozen one keeps interaction off until `retarget()` restores it. The indicator
+     * fades in or out instead of snapping.
      */
     private syncInteraction;
     private isFocusInsideTarget;
@@ -270,8 +356,16 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
      * lets the backdrop appear while the page is still travelling.
      */
     private beginTargetScroll;
+    /** Scrolls the target in as the step asks, and returns the settle wait as `beginTargetScroll` does. */
+    private scrollTargetIntoView;
     /**
-     * Resolves once the scroller has held still for a couple of frames.
+     * Resolves once the scroller, and the target it carries, have held still for
+     * a couple of frames.
+     *
+     * The target's own position is watched alongside the document's offset: a
+     * page that scrolls inside a container rather than the document moves the
+     * target while `scrollingElement` sits at zero, and would otherwise read as
+     * settled a few frames in, presenting the popover mid-scroll.
      *
      * 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

package/elements/popover.d.ts

@@ -14,6 +14,11 @@ export default class PopoverElement extends GlowTourElement {
     private readonly mutationLease;
     protected _getNextStyles(position: DOMRect, step: TourElementStep): Keyframe;
     resolvePosition(targetPosition: DOMRect, step: TourElementStep): PopoverPosition;
+    /**
+     * Marks the popover as waiting for the next step's target. Written through the mutation lease,
+     * like every other attribute the popover owns, so unbinding the element gives it back clean.
+     */
+    setAwaitingTarget(awaiting: boolean): void;
     private _centerPosition;
     private _applyPositionState;
     /**

package/index.js

@@ -417,12 +417,34 @@ function isNode(value, context) {
   const Node = ownerWindow(context)?.Node ?? globalThis.Node;
   return typeof Node === "function" && value instanceof Node;
 }
+var fixedBoxes = new WeakMap;
+function fixedContainingBlock(document2, root) {
+  const view = document2.defaultView;
+  const key = `${root.clientWidth} ${root.clientHeight} ${view?.innerWidth} ${view?.innerHeight}`;
+  const cached = fixedBoxes.get(document2);
+  if (cached?.key === key)
+    return cached;
+  const probe = document2.createElement?.("div");
+  if (!probe?.style)
+    return null;
+  probe.style.cssText = "position:fixed;top:0;right:0;bottom:0;left:0;visibility:hidden;pointer-events:none";
+  root.appendChild(probe);
+  const { height, width } = probe.getBoundingClientRect();
+  probe.remove();
+  if (!(width > 0 && height > 0))
+    return null;
+  const box = { height, key, width };
+  fixedBoxes.set(document2, box);
+  return box;
+}
 function viewportDimensions(context) {
-  const root = ownerDocument(context)?.documentElement;
+  const document2 = ownerDocument(context);
+  const root = document2?.documentElement;
   const width = root?.clientWidth;
   const height = root?.clientHeight;
   if (typeof width === "number" && width > 0 && typeof height === "number" && height > 0) {
-    return { width, height };
+    const fixed = document2 && root && fixedContainingBlock(document2, root);
+    return fixed ? { height: fixed.height, width: fixed.width } : { width, height };
   }
   const currentWindow = ownerWindow(context);
   return {
@@ -467,14 +489,17 @@ function roundedRectPath(rect, viewport, options, context) {
     "Z"
   ].join(" ");
 }
-async function resolveTargetElement(target, options, path = "target") {
+function isPendingTarget(value) {
+  return typeof value?.then === "function";
+}
+function resolveTargetElement(target, options, path = "target") {
   const rootDocument = options.document;
+  const validate = (element) => rootDocument ? validateTargetElement(element, rootDocument, path) : element;
   if (typeof target === "string") {
-    const element = rootDocument ? rootDocument.querySelector(target) : typeof document === "undefined" ? null : document.querySelector(target);
-    return rootDocument ? validateTargetElement(element, rootDocument, path) : element;
+    return validate(rootDocument ? rootDocument.querySelector(target) : typeof document === "undefined" ? null : document.querySelector(target));
   } else if (typeof target === "function") {
-    const element = await target({ signal: options.signal });
-    return rootDocument ? validateTargetElement(element, rootDocument, path) : element;
+    const element = target({ signal: options.signal });
+    return isPendingTarget(element) ? element.then(validate) : validate(element);
   }
   if (rootDocument)
     return validateTargetElement(target, rootDocument, path);
@@ -754,7 +779,7 @@ class OverlayElement extends GlowTourElement {
     for (const [name, value] of Object.entries(OVERLAY_IDLE_ATTRIBUTES)) {
       el.setAttribute(name, value);
     }
-    el.style.setProperty("height", "100lvh");
+    el.style.setProperty("height", "max(100%, 100lvh)");
     this.syncViewBox();
   }
   _getPathElement() {
@@ -1493,6 +1518,9 @@ class PopoverElement extends GlowTourElement {
     }
     return this._centerPosition(popoverPosition, viewport);
   }
+  setAwaitingTarget(awaiting) {
+    this.mutationLease.setAttribute("data-glow-tour-awaiting-target", awaiting ? "" : null);
+  }
   _centerPosition(popoverPosition, viewport) {
     return {
       arrowOffset: null,
@@ -1999,7 +2027,8 @@ function mergeScrollOptions(defaults, overrides) {
   return {
     behavior: overrides?.behavior ?? defaults?.behavior,
     block: overrides?.block ?? defaults?.block,
-    inline: overrides?.inline ?? defaults?.inline
+    inline: overrides?.inline ?? defaults?.inline,
+    returnDelay: overrides?.returnDelay ?? defaults?.returnDelay
   };
 }
 function mergeAnimationOptions(defaults, overrides) {
@@ -2071,6 +2100,8 @@ var SCROLL_SETTLE_STILL_FRAMES = 2;
 var SCROLL_SETTLE_GRACE_FRAMES = 3;
 var SCROLL_SETTLE_EPSILON = 0.5;
 var SCROLL_SETTLE_TIMEOUT = 2000;
+var USER_SCROLL_IDLE_DELAY = 150;
+var DEFAULT_SCROLL_RETURN_DELAY = 500;
 var ACTIVE_MODAL_BY_DOCUMENT = new WeakMap;
 var DEFAULT_SHORTCUTS = {
   previous: ["ArrowLeft", "Backspace"],
@@ -2092,6 +2123,8 @@ class DomTourViewDriver {
   active = false;
   frozen = false;
   awaitingStepUi = false;
+  userScrolling = false;
+  scrollTimer;
   activeTarget = null;
   targetFocusedAtFreeze = false;
   lastTargetRect = null;
@@ -2106,6 +2139,8 @@ class DomTourViewDriver {
   handledTriggerClick = null;
   popover = null;
   presentationDirty = false;
+  targetPending = false;
+  popoverHidden = false;
   focusToRestore = null;
   appliedAllowInteraction = false;
   pointerFading = false;
@@ -2164,11 +2199,40 @@ class DomTourViewDriver {
     this.pointer?.initializeProps();
     this.refreshRegisteredElements();
   }
+  setTargetPending(pending) {
+    if (this.disposed || this.targetPending === pending)
+      return;
+    this.targetPending = pending;
+    this.popover?.setAwaitingTarget(pending);
+    const step = this.currentStep;
+    if (!step)
+      return;
+    const focused = this.popover?.getElement()?.ownerDocument.activeElement;
+    const refocus = pending && step.autoFocuses() && this.findTriggers("advance").includes(focused);
+    this.syncControlState(step);
+    if (refocus)
+      this.focusGuard.focus();
+  }
+  setPopoverHidden(hidden) {
+    if (this.disposed || this.popoverHidden === hidden)
+      return;
+    this.popoverHidden = hidden;
+    const step = this.currentStep;
+    const target = this.activeTarget;
+    if (!this.active || !step || !target)
+      return;
+    if (hidden) {
+      this.liftModality();
+      this.concealPopover();
+    } else {
+      this.revealPopover(step, target, this.generation);
+    }
+  }
   async show(step, direction, signal, onBeforePopoverAppear) {
     this.throwIfAborted(signal);
     const generation = this.beginGeneration();
     const removeAbort = this.cancelAnimationsOnAbort(signal);
-    const replaceVisiblePopover = this.active && onBeforePopoverAppear !== undefined;
+    const replaceVisiblePopover = this.active && !this.popoverHidden && onBeforePopoverAppear !== undefined;
     let removeTransitionListeners = () => {};
     try {
       this.cleanupStepResources();
@@ -2216,8 +2280,7 @@ class DomTourViewDriver {
       this.lastTargetRect = snapshotRect(targetRect);
       this.lastViewport = snapshotViewport(target);
       this.active = true;
-      this.syncModality(step.allowsInteraction());
-      this.activateFocus(step, target, direction, generation);
+      this.engagePopover(step, target, direction, generation);
       this.syncScrollLock(step);
       this.throwIfStale(generation, signal);
       removeTransitionListeners();
@@ -2238,6 +2301,7 @@ class DomTourViewDriver {
     this.throwIfAborted(signal);
     const generation = this.beginGeneration();
     const removeAbort = this.cancelAnimationsOnAbort(signal);
+    this.setTargetPending(false);
     try {
       this.cleanupStepResources();
       this.releaseModality();
@@ -2270,6 +2334,7 @@ class DomTourViewDriver {
   releaseMount() {
     if (this.disposed)
       return;
+    this.setTargetPending(false);
     this.beginGeneration();
     this.cleanupStepResources();
     this.releaseModality();
@@ -2320,8 +2385,7 @@ class DomTourViewDriver {
     this.awaitingStepUi = true;
     await this.appear(() => targetRect, step, generation, null, false);
     this.throwIfStale(generation);
-    this.syncModality(step.allowsInteraction());
-    this.activateFocus(step, target, this.direction, generation);
+    this.engagePopover(step, target, this.direction, generation);
     this.syncScrollLock(step);
     this.throwIfStale(generation);
     this.attachStepResources(step, target, generation, signal);
@@ -2343,6 +2407,10 @@ class DomTourViewDriver {
       return;
     }
     this.claimModal();
+    if (this.popoverHidden) {
+      this.liftModality();
+      return;
+    }
     const popover = this.popover?.getElement();
     if (isHTMLElement(popover, this.root ?? popover))
       popover.setAttribute("aria-modal", "true");
@@ -2378,13 +2446,16 @@ class DomTourViewDriver {
     this.modalDocument = document2;
   }
   releaseModality() {
-    this.popover?.getElement()?.removeAttribute("aria-modal");
-    this.restoreInertBranches();
+    this.liftModality();
     const document2 = this.modalDocument;
     if (document2 && ACTIVE_MODAL_BY_DOCUMENT.get(document2) === this.modalToken) {
       ACTIVE_MODAL_BY_DOCUMENT.delete(document2);
     }
     this.modalDocument = null;
+  }
+  liftModality() {
+    this.popover?.getElement()?.removeAttribute("aria-modal");
+    this.restoreInertBranches();
     this.modalRoot = null;
   }
   restoreInertBranches() {
@@ -2423,7 +2494,7 @@ class DomTourViewDriver {
   enterStepUi(targetRect, step) {
     const popoverPlacement = this.popover?.resolvePosition(targetRect, this.elementProps(step)).placement;
     return Promise.all([
-      this.popover?.present(targetRect, this.elementProps(step)) ?? Promise.resolve(),
+      !this.popoverHidden && this.popover?.present(targetRect, this.elementProps(step)) || Promise.resolve(),
       this.presentPointer(targetRect, step, popoverPlacement) ?? Promise.resolve()
     ]);
   }
@@ -2472,6 +2543,20 @@ class DomTourViewDriver {
         }
       });
     }
+    const targetDocument = ownerDocument(target);
+    if (typeof targetDocument?.addEventListener === "function") {
+      const passive = { capture: true, passive: true };
+      this.listen(targetDocument, "scroll", (event) => this.onUserScroll(event, step, generation), passive);
+      const interrupt = () => {
+        if (!this.isCurrentGeneration(generation) || !this.userScrolling || !this.awaitingStepUi)
+          return;
+        this.awaitingStepUi = false;
+        this.cancelScroll?.();
+        this.waitForScrollIdle(step, generation);
+      };
+      this.listen(targetDocument, "wheel", interrupt, passive);
+      this.listen(targetDocument, "touchmove", interrupt, passive);
+    }
     this.attachButtonHandlers(step);
     this.observeControls(step, generation);
     this.syncControlState(step);
@@ -2567,7 +2652,7 @@ class DomTourViewDriver {
       this.syncShortcutLabels(step);
     }
     this.overlay?.updatePosition(targetRect, this.elementProps(step), presentationChanged, (transition) => this.observeDynamicOperation(transition, generation));
-    if (!this.awaitingStepUi)
+    if (!this.awaitingStepUi && !this.userScrolling)
       this.trackStepUi(targetRect, step, generation, presentationChanged);
     this.lastTargetRect = targetSnapshot;
     this.lastViewport = viewportSnapshot;
@@ -2575,7 +2660,7 @@ class DomTourViewDriver {
       this.presentationDirty = false;
   }
   trackStepUi(targetRect, step, generation, presentationChanged) {
-    const popoverPlacement = this.popover?.updatePosition(targetRect, this.elementProps(step), (reposition) => this.observeDynamicOperation(reposition, generation));
+    const popoverPlacement = this.placePopover(targetRect, step, generation);
     if (presentationChanged) {
       if (this.pointerFading)
         this.pointerFading = false;
@@ -2592,6 +2677,68 @@ class DomTourViewDriver {
       this.observeDynamicOperation(this.pointer?.disappear(), generation);
     }
   }
+  onUserScroll(event, step, generation) {
+    const target = this.activeTarget;
+    if (!target || !this.isCurrentGeneration(generation) || this.frozen || this.awaitingStepUi || step.detached || !step.allowsScroll() || !event.target?.contains?.(target))
+      return;
+    if (!this.userScrolling) {
+      this.userScrolling = true;
+      this.popover?.cancelAnimations();
+      this.pointer?.cancelAnimations();
+      if (!this.popoverHidden)
+        this.observeDynamicOperation(this.popover?.disappear(false), generation);
+      this.observeDynamicOperation(this.pointer?.disappear(), generation);
+    }
+    this.waitForScrollIdle(step, generation);
+  }
+  waitForScrollIdle(step, generation) {
+    clearTimeout(this.scrollTimer);
+    this.scrollTimer = setTimeout(() => this.settleScroll(step, generation), USER_SCROLL_IDLE_DELAY);
+  }
+  settleScroll(step, generation) {
+    const target = this.activeTarget;
+    if (!target)
+      return;
+    const behavior = step.props.get().behavior;
+    const returnDelay = behavior?.scroll?.returnDelay ?? DEFAULT_SCROLL_RETURN_DELAY;
+    if (returnDelay === false || behavior?.autoScroll === false || isInViewport(target.getBoundingClientRect(), target))
+      this.revealAfterScroll(step, target, generation);
+    else
+      this.scrollTimer = setTimeout(() => void this.scrollBack(step, target, generation), returnDelay);
+  }
+  async scrollBack(step, target, generation) {
+    const signal = this.currentSignal;
+    if (!signal)
+      return;
+    const scrollingBack = () => this.userScrolling && this.awaitingStepUi && !signal.aborted && this.isCurrentGeneration(generation);
+    this.awaitingStepUi = true;
+    try {
+      await (this.scrollTargetIntoView(step, target, signal) ?? this.waitForScrollToSettle(target, signal));
+    } catch (error) {
+      if (scrollingBack())
+        this.observeDynamicOperation(Promise.reject(error), generation);
+    }
+    if (scrollingBack())
+      this.revealAfterScroll(step, target, generation);
+  }
+  revealAfterScroll(step, target, generation) {
+    this.stopUserScroll();
+    this.awaitingStepUi = false;
+    this.pointerFading = false;
+    this.popover?.cancelAnimations();
+    this.pointer?.cancelAnimations();
+    this.observeDynamicOperation(this.enterStepUi(presentationRect(step, target), step), generation);
+  }
+  stopUserScroll() {
+    clearTimeout(this.scrollTimer);
+    this.userScrolling = false;
+  }
+  placePopover(targetRect, step, generation) {
+    if (this.popoverHidden) {
+      return this.popover?.resolvePosition(targetRect, this.elementProps(step)).placement;
+    }
+    return this.popover?.updatePosition(targetRect, this.elementProps(step), (reposition) => this.observeDynamicOperation(reposition, generation));
+  }
   observeDynamicOperation(operation, generation) {
     if (!operation)
       return;
@@ -2606,7 +2753,7 @@ class DomTourViewDriver {
   }
   handleKeydown(event) {
     const step = this.currentStep;
-    if (!step || event.defaultPrevented || event.isComposing || event.ctrlKey || event.metaKey || event.altKey)
+    if (!step || this.popoverHidden || event.defaultPrevented || event.isComposing || event.ctrlKey || event.metaKey || event.altKey)
       return;
     if (event.key === "Tab" && !step.allowsInteraction()) {
       this.loopFocus(event);
@@ -2699,6 +2846,44 @@ class DomTourViewDriver {
       focusable[0]?.focus();
     }
   }
+  engagePopover(step, target, direction, generation) {
+    this.syncModality(step.allowsInteraction());
+    if (this.popoverHidden)
+      this.concealPopover();
+    else if (this.isPopoverConcealed())
+      this.revealPopover(step, target, generation);
+    else
+      this.activateFocus(step, target, direction, generation);
+  }
+  concealPopover() {
+    this.focusToRestore = this.focusGuard.release() ?? this.focusToRestore;
+    const popover = this.popover;
+    const element = popover?.getElement();
+    if (!popover || !element)
+      return;
+    const focused = element.ownerDocument.activeElement;
+    if (isHTMLElement(focused, element) && element.contains(focused)) {
+      focused.blur();
+      this.activeTarget?.focus();
+    }
+    if (this.isPopoverConcealed())
+      return;
+    popover.cancelAnimations();
+    this.observeDynamicOperation(popover.disappear(), this.generation);
+  }
+  revealPopover(step, target, generation) {
+    this.focusGuard.captureInitialFocus(target, this.focusToRestore);
+    this.popover?.cancelAnimations();
+    this.observeDynamicOperation(this.popover?.present(this.lastTargetRect, this.elementProps(step)).then(() => {
+      if (!this.isCurrentGeneration(generation) || this.popoverHidden)
+        return;
+      this.syncModality(!this.frozen && step.allowsInteraction());
+      this.activateFocus(step, target, this.direction, generation);
+    }), generation);
+  }
+  isPopoverConcealed() {
+    return this.popover?.getElement()?.getAttribute("aria-hidden") === "true";
+  }
   activateFocus(step, target, direction, generation) {
     const popover = this.popover?.getElement();
     if (!isHTMLElement(popover, this.root ?? popover))
@@ -2867,6 +3052,7 @@ class DomTourViewDriver {
   cleanupStepResources() {
     this.cancelScroll?.();
     this.cancelScroll = null;
+    this.stopUserScroll();
     this.presentationDirty = false;
     this.pointerFading = false;
     if (this.rafId !== null)
@@ -2896,6 +3082,14 @@ class DomTourViewDriver {
     this.targetFocusedAtFreeze = this.isFocusInsideTarget(target);
     this.cleanupTargetResources();
     this.applyInteractionLock(step, true);
+    if (this.userScrolling) {
+      this.stopUserScroll();
+      const targetRect = this.lastTargetRect;
+      this.popover?.cancelAnimations();
+      if (targetRect && !this.popoverHidden) {
+        this.observeDynamicOperation(this.popover?.present(targetRect, this.elementProps(step)), generation);
+      }
+    }
     Promise.resolve(this.commands?.targetDisconnected(target)).catch((error) => {
       this.commands?.reportError(error).catch(() => {});
     });
@@ -2909,7 +3103,7 @@ class DomTourViewDriver {
     this.applyInteractionLock(step, false);
     this.appliedAllowInteraction = step.allowsInteraction();
     const popover = this.popover?.getElement();
-    if (isHTMLElement(popover, this.root ?? popover)) {
+    if (!this.popoverHidden && isHTMLElement(popover, this.root ?? popover)) {
       this.focusGuard.update({
         allowedTarget: target,
         allowTargetInteraction: step.allowsInteraction(),
@@ -2921,12 +3115,14 @@ class DomTourViewDriver {
   }
   syncInteraction(step) {
     const target = this.activeTarget;
-    if (this.disposed || !this.active || this.frozen || this.awaitingStepUi || this.currentStep !== step || !target)
+    if (this.disposed || !this.active || this.frozen || this.awaitingStepUi && !this.userScrolling || this.currentStep !== step || !target)
       return;
     const focusWasInTarget = this.isFocusInsideTarget(target);
     this.applyInteraction(step, target);
     if (focusWasInTarget && !step.allowsInteraction() && step.autoFocuses())
       this.focusGuard.focus();
+    if (this.userScrolling)
+      return;
     const targetRect = target.getBoundingClientRect();
     this.pointer?.cancelAnimations();
     this.observeDynamicOperation(this.presentPointer(targetRect, step, this.popover?.resolvePosition(targetRect, this.elementProps(step)).placement), this.generation);
@@ -2965,7 +3161,7 @@ class DomTourViewDriver {
     const generation = this.generation;
     const targetRect = presentationRect(step, target);
     this.observeDynamicOperation(this.overlay?.animateTo(targetRect, this.elementProps(step)), generation);
-    const placement = this.popover?.updatePosition(targetRect, this.elementProps(step), (reposition) => this.observeDynamicOperation(reposition, generation));
+    const placement = this.placePopover(targetRect, step, generation);
     if (this.isPointerEnabled(step)) {
       this.observeDynamicOperation(this.pointer?.moveToTarget(targetRect, step.props.get(), true, placement), generation);
     }
@@ -2998,14 +3194,17 @@ class DomTourViewDriver {
       return null;
     if (isInViewport(target.getBoundingClientRect(), target))
       return null;
-    const currentWindow = this.getWindow(target);
-    if (!currentWindow)
+    if (!this.getWindow(target))
       return null;
-    const behavior = prefersReducedMotion(target) ? "instant" : step.props.get().behavior?.scroll?.behavior ?? "smooth";
+    return this.scrollTargetIntoView(step, target, signal);
+  }
+  scrollTargetIntoView(step, target, signal) {
+    const scroll = step.props.get().behavior?.scroll;
+    const behavior = prefersReducedMotion(target) ? "instant" : scroll?.behavior ?? "smooth";
     target.scrollIntoView({
       behavior,
-      block: step.props.get().behavior?.scroll?.block ?? "center",
-      inline: step.props.get().behavior?.scroll?.inline ?? "nearest"
+      block: scroll?.block ?? "center",
+      inline: scroll?.inline ?? "nearest"
     });
     if (behavior === "instant")
       return null;
@@ -3026,6 +3225,7 @@ class DomTourViewDriver {
       let timeout = null;
       let left = scroller.scrollLeft;
       let top = scroller.scrollTop;
+      let rect = target.getBoundingClientRect();
       let stillFrames = -SCROLL_SETTLE_GRACE_FRAMES;
       const finish = (error) => {
         if (frame !== null)
@@ -3050,9 +3250,11 @@ class DomTourViewDriver {
         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;
+        const nextRect = target.getBoundingClientRect();
+        const still = Math.abs(nextLeft - left) <= SCROLL_SETTLE_EPSILON && Math.abs(nextTop - top) <= SCROLL_SETTLE_EPSILON && Math.abs(nextRect.left - rect.left) <= SCROLL_SETTLE_EPSILON && Math.abs(nextRect.top - rect.top) <= SCROLL_SETTLE_EPSILON;
         left = nextLeft;
         top = nextTop;
+        rect = nextRect;
         stillFrames = still ? stillFrames + 1 : 0;
         if (stillFrames >= SCROLL_SETTLE_STILL_FRAMES)
           return finish();
@@ -3284,8 +3486,8 @@ class ActiveStep {
   allowsScroll() {
     return this.props.get().behavior?.allowScroll !== false;
   }
-  async resolveTarget(signal) {
-    return await resolveTargetElement(this.definition.target, { document: this.rootDocument, signal }, this.path);
+  resolveTarget(signal) {
+    return resolveTargetElement(this.definition.target, { document: this.rootDocument, signal }, this.path);
   }
   detach() {
     const body = (this.rootDocument ?? globalThis.document)?.body ?? null;
@@ -3628,7 +3830,9 @@ class TourController {
   recoveringTarget = null;
   operationToken = 0;
   publicationRevision = 0;
+  awaitingTargetOperation = null;
   operation = null;
+  popoverHidden = false;
   disposed = false;
   retainedPresentation = null;
   stateListeners = new Set;
@@ -3662,7 +3866,7 @@ class TourController {
       canPrevious: () => this.canNavigate("previous"),
       cancel: (source) => this.cancel(source),
       goTo: (id) => this.goTo(id),
-      isAdvanceDisabled: () => !this.isPresentedAdvanceAvailable(),
+      isAdvanceDisabled: () => this.awaitingTargetOperation !== null || !this.isPresentedAdvanceAvailable(),
       isCancelDisabled: () => !this.isPresentedCancelAvailable(),
       isPreviousDisabled: () => !this.isPresentedPreviousAvailable(),
       previous: (source) => this.previous(source),
@@ -3703,6 +3907,8 @@ class TourController {
     this.error = null;
     this.commandSource = "api";
     this.retainedPresentation = retainedPresentation;
+    this.popoverHidden = false;
+    this.driver.setPopoverHidden?.(false);
     this.pendingTourStart = undefined;
     try {
       this.setStatus("starting");
@@ -3756,6 +3962,17 @@ class TourController {
       await this.handleFailure(error, operation);
     }
   }
+  setPopoverHidden(hidden) {
+    this.assertNotDisposed();
+    if (!this.isRunning() || this.popoverHidden === hidden)
+      return;
+    this.popoverHidden = hidden;
+    this.driver.setPopoverHidden?.(hidden);
+    this.publish();
+  }
+  isRunning() {
+    return this.status === "starting" || this.status === "transitioning" || this.status === "active";
+  }
   dispose() {
     if (this.disposed)
       return;
@@ -3924,23 +4141,38 @@ class TourController {
     const timeout = missingTarget?.timeout ?? DEFAULT_TARGET_TIMEOUT;
     const startedAt = Date.now();
     step.detached = false;
-    while (true) {
-      const target = await step.resolveTarget(signal);
-      this.assertCurrent(operation);
-      if (target)
-        return target;
-      if (strategy === "skip")
-        return null;
-      const body = strategy === "detached" && step.detach();
-      if (body)
-        return body;
-      if (strategy !== "wait" || Date.now() - startedAt >= timeout) {
-        throw this.missingTargetError(step);
+    try {
+      while (true) {
+        const pending = step.resolveTarget(signal);
+        if (isPendingTarget(pending))
+          this.setAwaitingTarget(operation, true);
+        const target = await pending;
+        this.assertCurrent(operation);
+        if (target)
+          return target;
+        if (strategy === "skip")
+          return null;
+        const body = strategy === "detached" && step.detach();
+        if (body)
+          return body;
+        if (strategy !== "wait" || Date.now() - startedAt >= timeout) {
+          throw this.missingTargetError(step);
+        }
+        this.setAwaitingTarget(operation, true);
+        await abortableDelay(16, signal);
+        this.assertCurrent(operation);
       }
-      await abortableDelay(16, signal);
-      this.assertCurrent(operation);
+    } finally {
+      this.setAwaitingTarget(operation, false);
     }
   }
+  setAwaitingTarget(operation, awaiting) {
+    if (this.awaitingTargetOperation === operation === awaiting)
+      return;
+    this.awaitingTargetOperation = awaiting ? operation : null;
+    this.driver.setTargetPending?.(awaiting);
+    this.publish();
+  }
   async pollForTarget(step, operation, budgetMs) {
     const startedAt = Date.now();
     while (true) {
@@ -4125,6 +4357,10 @@ class TourController {
     this.operationToken += 1;
     this.operation?.abort();
     this.operation = null;
+    if (this.awaitingTargetOperation !== null) {
+      this.awaitingTargetOperation = null;
+      this.driver.setTargetPending?.(false);
+    }
   }
   signalFor(operation) {
     this.assertCurrent(operation);
@@ -4288,6 +4524,8 @@ class TourController {
       isFirstStep,
       isLastStep,
       status: this.status,
+      awaitingTarget: this.awaitingTargetOperation !== null,
+      popoverHidden: this.popoverHidden && this.isRunning(),
       error: this.error
     });
   }
@@ -4326,7 +4564,9 @@ function createGlowTour(options = {}) {
     create: (name, options2) => controller.create(name, options2),
     dispose: () => controller.dispose(),
     goTo: (id) => controller.goTo(id),
+    hidePopover: () => controller.setPopoverHidden(true),
     previous: () => controller.previous(),
+    showPopover: () => controller.setPopoverHidden(false),
     start: (workflow, runOptions) => controller.start(workflow, runOptions),
     state: controller.state
   };

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@glowhop/core-tour",
-  "version": "1.4.0",
-  "description": "Framework-agnostic tour controller and DOM runtime for GlowTour.js.",
+  "version": "1.5.1",
+  "description": "Framework-agnostic product tour engine for GlowTour.js: the tour controller and DOM runtime behind onboarding tours in any framework.",
   "license": "MIT",
-  "homepage": "https://github.com/Glowhop/GlowTour.js#readme",
+  "homepage": "https://glowtour.dev/",
   "bugs": {
     "url": "https://github.com/Glowhop/GlowTour.js/issues"
   },
@@ -20,7 +20,9 @@
     "dom",
     "headless",
     "framework-agnostic",
-    "ssr"
+    "ssr",
+    "onboarding-tour",
+    "intro-js-alternative"
   ],
   "engines": {
     "node": ">=18.19.1"

package/runtime/active-step.d.ts

@@ -22,7 +22,8 @@ export declare class ActiveStep<T> {
     autoFocuses(): boolean;
     /** Reads `behavior.allowScroll` live: `props.update({ behavior })` changes it while the step runs. */
     allowsScroll(): boolean;
-    resolveTarget(signal: AbortSignal): Promise<HTMLElement | null>;
+    /** Returns the target, or the promise to wait on when the resolver is async. */
+    resolveTarget(signal: AbortSignal): HTMLElement | Promise<HTMLElement | null> | null;
     /** Marks the step detached and returns the body it stands on, or `null` without a document. */
     detach(): HTMLElement;
     snapshot(): Readonly<{

package/runtime/tour-controller.d.ts

@@ -37,7 +37,14 @@ export declare class TourController<T> {
     private recoveringTarget;
     private operationToken;
     private publicationRevision;
+    /**
+     * The operation currently parked on a target that has not resolved yet, or `null`. The step being
+     * left is still on screen while a navigation waits, so the wait is reported on its presentation.
+     */
+    private awaitingTargetOperation;
     private operation;
+    /** Set by `hidePopover()`, see `TourState.popoverHidden`. Only a running tour reports it. */
+    private popoverHidden;
     private disposed;
     private retainedPresentation;
     private readonly stateListeners;
@@ -63,6 +70,9 @@ export declare class TourController<T> {
     /** The direction of a jump from the current step to the step at `index`. */
     private directionTo;
     cancel(source?: TourEventSource): Promise<void>;
+    /** `tour.hidePopover()` and `tour.showPopover()`. */
+    setPopoverHidden(hidden: boolean): void;
+    private isRunning;
     dispose(): void;
     isDisposed(): boolean;
     /** @internal Called by the private root bridge before it releases DOM resources. */
@@ -84,6 +94,14 @@ export declare class TourController<T> {
     private runStepHook;
     private runActions;
     private resolveTarget;
+    /**
+     * Reports a navigation waiting on the next step's target. The presentation on screen still
+     * belongs to the step being left, so the driver marks that popover and disables its advance
+     * control until the target settles. Keyed by operation: a superseded navigation never clears the
+     * wait its replacement declared. The freeze of a target lost mid-step is deliberately not a wait
+     * here, see `recoverDisconnectedTarget`.
+     */
+    private setAwaitingTarget;
     /**
      * Repeatedly re-resolves `step.target` until it succeeds or `budgetMs`
      * elapses, polling every 16ms like `resolveTarget`. Unlike `resolveTarget`

package/types/index.d.ts

@@ -174,12 +174,16 @@ export interface PopoverOptions extends BaseOptions {
     gap?: number;
 }
 /**
- * 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" */
@@ -188,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 {
@@ -380,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;
 }
@@ -407,6 +428,18 @@ export interface GlowTour<T> {
     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. */

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>;