fix: 2D overscroll snapping by clearing expander state and guarding animations

Author: bfiessinger

@types/scrolltosmooth.d.ts

@@ -136,6 +136,11 @@ export declare class ScrollToSmooth {
         px: number;
     } | false;
     protected _getDocumentExpanders(): HTMLDivElement[];
+    /**
+     * Clear inline expander dimensions so stale overscroll state never leaks into
+     * subsequent user-driven or snapped scroll calculations.
+     */
+    protected _clearExpanderSizes(): void;
     protected _getScrollEventTarget(): Window | HTMLElement;
     protected _getTargetElement(el: Element): Element | null;
     private _collectLinks;

dist/plugins/horizontal.cjs.js

@@ -247,6 +247,7 @@ const HorizontalScrollPlugin = {
     // ----------------------------------------------------------------
     proto.scrollTo = function (target, axis) {
       this.cancelScroll();
+      this._isScrolling = true;
       const resolvedAxis = axis ?? this.settings.axis ?? 'y';
       const container = this.container;
       const startX = this._getContainerScrollPosition('x');
@@ -473,6 +474,22 @@ const HorizontalScrollPlugin = {
       this.container.style.setProperty('--sts-scroll-x', String(Math.round(currentX)));
       this.container.style.setProperty('--sts-scroll-y', String(Math.round(currentY)));
       if (elapsed >= duration) {
+        // Ensure final frame lands exactly on the target and clear any
+        // transient overscroll expander dimensions from easing overshoot.
+        if (axis === 'both') {
+          this._expandDocument(targetX, docWidth, viewWidth, 'x');
+          this._expandDocument(targetY, docHeight, viewHeight, 'y');
+          scrollBothAxes(this.container, targetX, targetY);
+        } else if (axis === 'x') {
+          this._expandDocument(targetX, docWidth, viewWidth, 'x');
+          this._setContainerScrollPosition(targetX, 'x');
+        } else {
+          this._expandDocument(targetY, docHeight, viewHeight, 'y');
+          this._setContainerScrollPosition(targetY, 'y');
+        }
+        this._clearExpanderSizes();
+        this.container.style.setProperty('--sts-scroll-x', String(Math.round(targetX)));
+        this.container.style.setProperty('--sts-scroll-y', String(Math.round(targetY)));
         fireOnScrollEnd(this.settings, axis, startX, startY, targetX, targetY);
         this._isScrolling = false;
         this._processQueue();

dist/plugins/horizontal.iife.min.js

@@ -245,6 +245,7 @@ const HorizontalScrollPlugin = {
     // ----------------------------------------------------------------
     proto.scrollTo = function (target, axis) {
       this.cancelScroll();
+      this._isScrolling = true;
       const resolvedAxis = axis ?? this.settings.axis ?? 'y';
       const container = this.container;
       const startX = this._getContainerScrollPosition('x');
@@ -471,6 +472,22 @@ const HorizontalScrollPlugin = {
       this.container.style.setProperty('--sts-scroll-x', String(Math.round(currentX)));
       this.container.style.setProperty('--sts-scroll-y', String(Math.round(currentY)));
       if (elapsed >= duration) {
+        // Ensure final frame lands exactly on the target and clear any
+        // transient overscroll expander dimensions from easing overshoot.
+        if (axis === 'both') {
+          this._expandDocument(targetX, docWidth, viewWidth, 'x');
+          this._expandDocument(targetY, docHeight, viewHeight, 'y');
+          scrollBothAxes(this.container, targetX, targetY);
+        } else if (axis === 'x') {
+          this._expandDocument(targetX, docWidth, viewWidth, 'x');
+          this._setContainerScrollPosition(targetX, 'x');
+        } else {
+          this._expandDocument(targetY, docHeight, viewHeight, 'y');
+          this._setContainerScrollPosition(targetY, 'y');
+        }
+        this._clearExpanderSizes();
+        this.container.style.setProperty('--sts-scroll-x', String(Math.round(targetX)));
+        this.container.style.setProperty('--sts-scroll-y', String(Math.round(targetY)));
         fireOnScrollEnd(this.settings, axis, startX, startY, targetX, targetY);
         this._isScrolling = false;
         this._processQueue();