@glowhop/core-tour 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @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
+
+- 3058e3d: When a step's target is removed from the DOM while its step is showing, the tour now freezes the presentation in place for a short grace period and resumes on the target without a re-entrance animation if it reconnects, instead of immediately unmounting and replaying the appear animation. When the target reappears somewhere else, the cutout is animated to its new box rather than snapping, unless the step opts out of animation. Interaction with the underlying page stays blocked during the freeze even when `allowInteraction` is `true`. If the target doesn't come back within the grace period, `missingTargetStrategy` and `targetTimeout` apply exactly as before — the grace period counts against `targetTimeout` rather than extending it. Under `wait` the presentation stays frozen and the tour stays `active` for the whole budget, so the popover's buttons keep working instead of going dead behind a `transitioning` status.
+
 ## 1.1.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

@@ -17,6 +17,15 @@ export interface TourViewCommands {
 export interface TourViewDriver<T> {
     show(step: ActiveStep<T>, direction: TourDirection, signal: AbortSignal, onBeforePopoverAppear?: () => void | Promise<void>): Promise<void> | void;
     clear(signal: AbortSignal): Promise<void> | void;
+    /**
+     * Resumes a frozen presentation on `step.target` after its previous target
+     * reconnected or was replaced, without unmounting or replaying `appear()`.
+     * A no-op when the driver isn't frozen for this step — callers only invoke
+     * it in response to a `targetDisconnected` notification they are recovering
+     * from, so a stale or superseded call should be silently ignored rather
+     * than throw.
+     */
+    retarget(step: ActiveStep<T>, signal: AbortSignal): Promise<void> | void;
     dispose(): void;
     releaseMount?(): void;
     setCommands?(commands: TourViewCommands): void;
@@ -24,6 +33,7 @@ export interface TourViewDriver<T> {
 export declare class NoopTourViewDriver<T> implements TourViewDriver<T> {
     show(_step: ActiveStep<T>, _direction: TourDirection, _signal: AbortSignal, onBeforePopoverAppear?: () => void | Promise<void>): void | Promise<void> | undefined;
     clear(_signal: AbortSignal): void;
+    retarget(_step: ActiveStep<T>, _signal: AbortSignal): void;
     dispose(): void;
     releaseMount(): void;
 }
@@ -32,6 +42,7 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private readonly scrollLock;
     private readonly modalToken;
     private readonly stepCleanups;
+    private readonly targetCleanups;
     private commands;
     private direction;
     private currentStep;
@@ -39,6 +50,23 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private disposed;
     private generation;
     private active;
+    /**
+     * True while the presentation is held in place on a lost target: the
+     * reposition loop is stopped and interaction is force-blocked, but overlay,
+     * popover and pointer stay mounted at their last known position instead of
+     * disappearing. Cleared by `retarget()` (target came back) or `clear()`
+     * (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;
     private lastViewport;
     private inertBranches;
@@ -53,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;
@@ -70,11 +98,52 @@ 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
+     * from `attachStepResources` so a lost-then-recovered target can be
+     * rebound on its own by `retarget()`, without re-subscribing the
+     * step-level resources (props, capabilities, controls) that never left.
+     */
+    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;
@@ -100,13 +169,79 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private isLiveDisabled;
     private isPointerEnabled;
     private cleanupStepResources;
+    private cleanupTargetResources;
     private isCurrentTargetAvailable;
-    private stopForDisconnectedTarget;
+    /**
+     * Holds the presentation exactly where it is when its target disappears,
+     * instead of tearing it down: overlay, popover and pointer stay mounted at
+     * their last known rect, focus guard and scroll lock stay engaged, and only
+     * the target's own listeners (now pointing at a dead node) are removed.
+     * The generation is deliberately left untouched — popover buttons, the
+     * keyboard shortcuts and any pending capability/focus bookkeeping must
+     * keep working while frozen, since the popover is the user's escape hatch
+     * out of a tour whose target never comes back. `commands.targetDisconnected`
+     * drives the actual recovery (grace period, then the configured strategy)
+     * and eventually calls back into `retarget()` or `clear()`.
+     */
+    private freezeForDisconnectedTarget;
+    /**
+     * Blocks (or restores) interaction with the underlying page independently
+     * of `step.behavior.allowInteraction`. Used to force interaction off while
+     * frozen — the cutout no longer corresponds to anything after a reflow, so
+     * it must not let clicks through even on a step that normally allows them —
+     * and to restore the step's own setting once retargeted.
+     */
+    private applyInteractionLock;
+    private isFocusInsideTarget;
+    /**
+     * Resumes a presentation frozen by `freezeForDisconnectedTarget` on its new
+     * target: reattaches the target-bound listeners, restores the step's own
+     * interaction setting, and lets the existing reposition loop tween overlay
+     * and popover to the new rect on the next frame. Deliberately skips
+     * `appear()` (no re-entrance animation) and `activateFocus()` (focus stays
+     * where the user left it), only reclaiming it if it was on the target that
+     * just disappeared.
+     */
+    retarget(step: ActiveStep<T>, signal: AbortSignal): Promise<void>;
+    /**
+     * Walks the presentation from where it froze to the new target's box. The
+     * per-frame loop can't do this on its own: it only tweens the cutout when
+     * the step's own visuals changed, and a target that reappears elsewhere is
+     * a pure geometry jump, which would snap. `animateTo` and the popover's
+     * reposition both fall back to an instant move when the step isn't
+     * animated, so this respects `animated: false` and reduced motion without
+     * asking about them.
+     */
+    private moveToRetargetedRect;
     private beginGeneration;
     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"],
@@ -1904,6 +1907,7 @@ class DomTourViewDriver {
   scrollLock = new ScrollLock;
   modalToken = {};
   stepCleanups = [];
+  targetCleanups = [];
   commands;
   direction = "advance";
   currentStep = null;
@@ -1911,6 +1915,10 @@ class DomTourViewDriver {
   disposed = false;
   generation = 0;
   active = false;
+  frozen = false;
+  awaitingStepUi = false;
+  activeTarget = null;
+  targetFocusedAtFreeze = false;
   lastTargetRect = null;
   lastViewport = null;
   inertBranches = [];
@@ -1925,7 +1933,7 @@ class DomTourViewDriver {
   rafId = null;
   rafCancel = null;
   root = null;
-  scrollAbort = null;
+  cancelScroll = null;
   constructor(commands) {
     this.commands = commands ?? null;
   }
@@ -1987,12 +1995,16 @@ class DomTourViewDriver {
       this.cleanupStepResources();
       this.throwIfStale(generation, signal);
       this.active = false;
+      this.frozen = false;
+      this.activeTarget = null;
+      this.targetFocusedAtFreeze = false;
       this.currentStep = step;
       this.currentSignal = signal;
       this.direction = direction;
       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();
@@ -2004,13 +2016,15 @@ class DomTourViewDriver {
       const target = step.target;
       if (!target)
         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;
@@ -2042,6 +2056,10 @@ class DomTourViewDriver {
       this.scrollLock.deactivate();
       this.throwIfStale(generation, signal);
       this.active = false;
+      this.frozen = false;
+      this.awaitingStepUi = false;
+      this.activeTarget = null;
+      this.targetFocusedAtFreeze = false;
       this.currentStep = null;
       this.currentSignal = null;
       this.lastTargetRect = null;
@@ -2066,6 +2084,10 @@ class DomTourViewDriver {
     this.focusGuard.deactivate();
     this.scrollLock.deactivate();
     this.active = false;
+    this.frozen = false;
+    this.awaitingStepUi = false;
+    this.activeTarget = null;
+    this.targetFocusedAtFreeze = false;
     this.currentStep = null;
     this.currentSignal = null;
     this.overlay?.release();
@@ -2084,7 +2106,7 @@ class DomTourViewDriver {
     this.commands = null;
   }
   refreshRegisteredElements() {
-    if (!this.active || !this.currentStep || !this.lastTargetRect)
+    if (!this.active || this.frozen || !this.currentStep || !this.lastTargetRect)
       return;
     const generation = this.beginGeneration();
     this.cleanupStepResources();
@@ -2101,8 +2123,10 @@ class DomTourViewDriver {
     const signal = this.currentSignal;
     if (this.disposed || !step || !target || !targetRect || !signal)
       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);
@@ -2175,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) {
@@ -2212,6 +2251,26 @@ class DomTourViewDriver {
       if (active)
         this.flushPendingKeyboardCommand(step, generation);
     }) ?? (() => {}));
+    this.attachTargetResources(step, target, generation, signal);
+    const currentWindow = this.getWindow(target);
+    if (typeof currentWindow?.addEventListener === "function") {
+      this.listen(currentWindow, "keydown", (event) => {
+        if (this.isCurrentGeneration(generation))
+          this.handleKeydown(event);
+      });
+      this.listen(currentWindow, "click", (event) => {
+        if (this.isCurrentGeneration(generation) && this.activeTarget) {
+          this.handleOverlayClick(event, step, this.activeTarget);
+        }
+      });
+    }
+    this.attachButtonHandlers(step);
+    this.observeControls(step, generation);
+    this.syncControlState(step);
+    this.syncShortcutLabels(step);
+    this.schedulePosition(generation);
+  }
+  attachTargetResources(step, target, generation, signal) {
     for (const handler of step.definition.eventHandlers) {
       const listener = (event) => {
         if (!this.isCurrentGeneration(generation))
@@ -2230,44 +2289,21 @@ class DomTourViewDriver {
           return this.commands?.reportError(error);
         });
       };
-      this.listen(target, handler.event, listener);
-    }
-    const currentWindow = this.getWindow(target);
-    if (typeof currentWindow?.addEventListener === "function") {
-      this.listen(currentWindow, "keydown", (event) => {
-        if (this.isCurrentGeneration(generation))
-          this.handleKeydown(event);
-      });
-      this.listen(currentWindow, "click", (event) => {
-        if (this.isCurrentGeneration(generation)) {
-          this.handleOverlayClick(event, step, target);
-        }
-      });
+      this.listen(target, handler.event, listener, undefined, this.targetCleanups);
     }
-    this.attachButtonHandlers(step);
-    this.observeControls(step, generation);
-    this.syncControlState(step);
-    this.syncShortcutLabels(step);
-    this.schedulePosition(generation);
   }
-  listen(target, type, listener, options) {
+  listen(target, type, listener, options, bucket = this.stepCleanups) {
     target.addEventListener(type, listener, options);
-    this.stepCleanups.push(() => target.removeEventListener(type, listener, options));
+    bucket.push(() => target.removeEventListener(type, listener, options));
   }
   schedulePosition(generation = this.generation) {
-    if (!this.isCurrentGeneration(generation) || !this.currentStep || this.rafId !== null)
+    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))
@@ -2276,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.stopForDisconnectedTarget(target, generation);
+      if (!this.awaitingStepUi)
+        this.freezeForDisconnectedTarget(step, target, generation);
       return;
     }
     const targetRect = target.getBoundingClientRect();
@@ -2299,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);
@@ -2312,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)
@@ -2582,37 +2638,101 @@ 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);
     this.rafId = null;
     this.rafCancel = null;
+    this.cleanupTargetResources();
     for (const cleanup of this.stepCleanups.splice(0))
       cleanup();
   }
+  cleanupTargetResources() {
+    for (const cleanup of this.targetCleanups.splice(0))
+      cleanup();
+  }
   isCurrentTargetAvailable(target) {
     const rootDocument = this.root?.ownerDocument;
     return target.isConnected && (!rootDocument || target.ownerDocument === rootDocument);
   }
-  stopForDisconnectedTarget(target, generation) {
-    if (!this.isCurrentGeneration(generation))
+  freezeForDisconnectedTarget(step, target, generation) {
+    if (!this.isCurrentGeneration(generation) || this.frozen)
       return;
-    this.beginGeneration();
-    this.cleanupStepResources();
-    this.releaseModality();
-    this.focusGuard.deactivate();
-    this.scrollLock.deactivate();
-    this.active = false;
-    this.currentSignal = null;
-    this.currentStep = null;
-    this.lastTargetRect = null;
-    this.lastViewport = null;
+    this.frozen = true;
+    if (this.rafId !== null)
+      this.rafCancel?.(this.rafId);
+    this.rafId = null;
+    this.rafCancel = null;
+    this.targetFocusedAtFreeze = this.isFocusInsideTarget(target);
+    this.cleanupTargetResources();
+    this.applyInteractionLock(step, true);
     Promise.resolve(this.commands?.targetDisconnected(target)).catch((error) => {
       this.commands?.reportError(error).catch(() => {});
     });
   }
+  applyInteractionLock(step, locked) {
+    const allowed = !locked && step.behavior?.allowInteraction === true;
+    this.overlay?.setInteractionAllowed(allowed);
+    this.syncModality(allowed);
+    const popover = this.popover?.getElement();
+    if (isHTMLElement(popover, this.root ?? popover)) {
+      if (allowed)
+        popover.removeAttribute("aria-modal");
+      else
+        popover.setAttribute("aria-modal", "true");
+    }
+  }
+  isFocusInsideTarget(target) {
+    const activeElement = target.ownerDocument?.activeElement;
+    if (!activeElement)
+      return false;
+    return activeElement === target || target.contains(activeElement);
+  }
+  async retarget(step, signal) {
+    this.throwIfAborted(signal);
+    if (this.disposed || !this.frozen || this.currentStep !== step)
+      return;
+    const target = step.target;
+    if (!target)
+      return;
+    this.frozen = false;
+    this.currentSignal = signal;
+    this.activeTarget = target;
+    this.applyInteractionLock(step, false);
+    this.attachTargetResources(step, target, this.generation, signal);
+    const popover = this.popover?.getElement();
+    if (isHTMLElement(popover, this.root ?? popover)) {
+      this.focusGuard.update({
+        allowedTarget: target,
+        allowTargetInteraction: step.behavior?.allowInteraction === true,
+        direction: this.direction,
+        fallback: this.root ?? popover.parentElement,
+        popover
+      });
+    }
+    if (this.targetFocusedAtFreeze) {
+      this.targetFocusedAtFreeze = false;
+      if (step.behavior?.allowInteraction === true)
+        target.focus();
+    }
+    this.syncControlState(step);
+    this.syncShortcutLabels(step);
+    this.moveToRetargetedRect(step, target);
+    this.schedulePosition(this.generation);
+  }
+  moveToRetargetedRect(step, target) {
+    const generation = this.generation;
+    const targetRect = target.getBoundingClientRect();
+    this.observeDynamicOperation(this.overlay?.animateTo(targetRect, step), generation);
+    const placement = this.popover?.updatePosition(targetRect, step, (reposition) => this.observeDynamicOperation(reposition, generation));
+    if (this.isPointerEnabled(step)) {
+      this.observeDynamicOperation(this.pointer?.moveToTarget(targetRect, step, true, placement), generation);
+    }
+    this.lastTargetRect = snapshotRect(targetRect);
+    this.lastViewport = snapshotViewport(target);
+  }
   beginGeneration() {
     this.generation += 1;
     this.pendingKeyboardCommand = null;
@@ -2633,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) {
@@ -3305,6 +3457,7 @@ function prefixReservations(document2) {
 
 // packages/core/src/runtime/tour-controller.ts
 var DEFAULT_TARGET_TIMEOUT = 3000;
+var TARGET_LOSS_GRACE_MS = 150;
 var DISPOSED_ERROR_MESSAGE = "Tour controller is disposed";
 function resolveStartIndex(workflow, startAt) {
   if (startAt === undefined)
@@ -3335,6 +3488,7 @@ class TourController {
   direction = "advance";
   status = "idle";
   error = null;
+  recoveringTarget = null;
   operationToken = 0;
   publicationRevision = 0;
   operation = null;
@@ -3617,34 +3771,63 @@ class TourController {
       this.assertCurrent(operation);
     }
   }
+  async pollForTarget(step, operation, budgetMs) {
+    const startedAt = Date.now();
+    while (true) {
+      const target = await step.resolveTarget(this.signalFor(operation));
+      this.assertCurrent(operation);
+      if (target)
+        return target;
+      if (Date.now() - startedAt >= budgetMs)
+        return null;
+      await abortableDelay(16, this.signalFor(operation));
+      this.assertCurrent(operation);
+    }
+  }
   async recoverDisconnectedTarget(target) {
-    if (this.disposed || this.status !== "active")
+    if (this.disposed || this.status !== "active" || this.recoveringTarget === target)
       return;
     const step = this.currentStep();
     if (!step || step.target !== target)
       return;
+    this.recoveringTarget = target;
     const index = this.index;
     const direction = this.direction;
     const operation = this.beginOperation();
     try {
-      this.setStatus("transitioning");
-      this.assertCurrent(operation);
-      await this.driver.clear(this.signalFor(operation));
       this.assertCurrent(operation);
-      const recoveredTarget = await this.resolveTarget(step, operation);
+      const recoveredDuringGrace = await this.pollForTarget(step, operation, TARGET_LOSS_GRACE_MS);
       this.assertCurrent(operation);
-      if (!recoveredTarget) {
+      if (recoveredDuringGrace) {
+        step.target = recoveredDuringGrace;
+        await this.driver.retarget(step, this.signalFor(operation));
+        this.assertCurrent(operation);
+        this.publish();
+        return;
+      }
+      const strategy = step.behavior?.missingTargetStrategy ?? "error";
+      if (strategy === "skip") {
         await this.advancePastRecoveryMissingTarget(step, index, direction, operation);
         return;
       }
-      step.target = recoveredTarget;
-      await this.driver.show(step, direction, this.signalFor(operation));
+      if (strategy !== "wait")
+        throw this.missingTargetError(step);
+      const timeout = step.behavior?.targetTimeout ?? DEFAULT_TARGET_TIMEOUT;
+      const recoveredAfterWait = await this.pollForTarget(step, operation, Math.max(0, timeout - TARGET_LOSS_GRACE_MS));
       this.assertCurrent(operation);
-      this.setStatus("active");
+      if (!recoveredAfterWait)
+        throw this.missingTargetError(step);
+      step.target = recoveredAfterWait;
+      await this.driver.retarget(step, this.signalFor(operation));
+      this.assertCurrent(operation);
+      this.publish();
     } catch (error) {
       try {
         await this.handleFailure(error, operation);
       } catch {}
+    } finally {
+      if (this.recoveringTarget === target)
+        this.recoveringTarget = null;
     }
   }
   async advancePastMissingTarget(index, direction, operation) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glowhop/core-tour",
-  "version": "1.1.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/runtime/tour-controller.d.ts

@@ -2,6 +2,16 @@ import { WorkflowBuilder } from "../builder";
 import type { WorkflowDefinition } from "../definition";
 import { type TourViewDriver } from "../dom/tour-view-driver";
 import type { GlowTour, GlowTourOptions, RunOptions, StartOptions, TourEventSource, TourState } from "../types";
+/**
+ * How long a step stays frozen on its last known position after its target
+ * disappears from the DOM, before the configured `missingTargetStrategy`
+ * takes over. Covers the dominant case — a framework remounting the target
+ * within a frame or two — without a visible unmount/remount flicker. Not
+ * configurable: it is a presentation detail of the recovery, not a policy
+ * choice; `missingTargetStrategy` and `targetTimeout` remain the only knobs.
+ * Exported for the test suite's timing assertions only.
+ */
+export declare const TARGET_LOSS_GRACE_MS = 150;
 interface TourControllerOptions<T> extends GlowTourOptions {
     assertCanRun?: (workflow: WorkflowDefinition<T>) => Document | void;
     onDispose?: () => void;
@@ -17,6 +27,14 @@ export declare class TourController<T> {
     private direction;
     private status;
     private error;
+    /**
+     * The target currently being recovered from a disconnect, if any. The
+     * public status stays "active" through the grace period (see
+     * TARGET_LOSS_GRACE_MS), so it can no longer serve as the re-entrancy guard
+     * a repeated or overlapping `targetDisconnected` notification for the same
+     * target relies on — this field takes over that job instead.
+     */
+    private recoveringTarget;
     private operationToken;
     private publicationRevision;
     private operation;
@@ -49,6 +67,29 @@ export declare class TourController<T> {
     private transition;
     private runActions;
     private resolveTarget;
+    /**
+     * Repeatedly re-resolves `step.target` until it succeeds or `budgetMs`
+     * elapses, polling every 16ms like `resolveTarget`. Unlike `resolveTarget`
+     * it never applies `missingTargetStrategy` itself — callers decide what a
+     * timed-out budget means (grace period vs. a "wait" strategy's own
+     * timeout), so the same polling loop serves both.
+     */
+    private pollForTarget;
+    /**
+     * Recovers from a target disconnecting while its step is on screen. The
+     * driver has already frozen the presentation in place (overlay, popover,
+     * pointer held at their last position; focus guard and scroll lock still
+     * engaged) and stopped polling geometry — this only decides how long to
+     * keep it frozen and what to do once that budget runs out.
+     *
+     * The public status stays "active" for the whole freeze, "wait" included.
+     * A frozen presentation isn't a transition: nothing is animating, the step
+     * and its index are unchanged, and the popover is still on screen. Calling
+     * it "transitioning" would close `canNavigate` and leave the user staring
+     * at a live-looking popover whose buttons are dead for the rest of the
+     * budget — the popover is the escape hatch out of a target that never
+     * comes back, so it has to keep working.
+     */
     private recoverDisconnectedTarget;
     private advancePastMissingTarget;
     private advancePastRecoveryMissingTarget;

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