@coderline/alphatab 1.8.0-alpha.1650 → 1.8.0-alpha.1653

package/dist/alphaTab.core.mjs

@@ -1,5 +1,5 @@
 /*!
- * alphaTab v1.8.0-alpha.1650 (develop, build 1650)
+ * alphaTab v1.8.0-alpha.1653 (develop, build 1653)
  *
  * Copyright © 2025, Daniel Kuschny and Contributors, All rights reserved.
  *
@@ -203,9 +203,9 @@ class AlphaTabError extends Error {
  * @internal
  */
 class VersionInfo {
-    static version = '1.8.0-alpha.1650';
-    static date = '2025-12-20T02:07:19.755Z';
-    static commit = '5789b59da2b7f8897debe003c9b75e4d48b5e9b3';
+    static version = '1.8.0-alpha.1653';
+    static date = '2025-12-23T02:21:29.054Z';
+    static commit = 'b85546e1908f06f3bd049e35e881c4856fb92846';
     static print(print) {
         print(`alphaTab ${VersionInfo.version}`);
         print(`commit: ${VersionInfo.commit}`);
@@ -13089,7 +13089,7 @@ class Bounds {
  */
 class MasterBarBounds {
     /**
-     * Gets or sets the index of this bounds relative within the parent lookup.
+     * The MasterBar index within the data model represented by these bounds.
      */
     index = 0;
     /**
@@ -13297,6 +13297,7 @@ class BoundsLookup {
                 mb.visualBounds = this._boundsToJson(masterBar.visualBounds);
                 mb.realBounds = this._boundsToJson(masterBar.realBounds);
                 mb.index = masterBar.index;
+                mb.isFirstOfLine = masterBar.isFirstOfLine;
                 mb.bars = [];
                 for (const bar of masterBar.bars) {
                     const b = {};
@@ -13353,7 +13354,7 @@ class BoundsLookup {
                 mb.lineAlignedBounds = BoundsLookup._boundsFromJson(masterBar.lineAlignedBounds);
                 mb.visualBounds = BoundsLookup._boundsFromJson(masterBar.visualBounds);
                 mb.realBounds = BoundsLookup._boundsFromJson(masterBar.realBounds);
-                sg.addBar(mb);
+                lookup.addMasterBar(mb);
                 for (const bar of masterBar.bars) {
                     const b = new BarBounds();
                     b.visualBounds = BoundsLookup._boundsFromJson(bar.visualBounds);
@@ -43657,6 +43658,12 @@ var ScrollMode;
      * Scrolling happens as soon the cursors exceed the displayed range.
      */
     ScrollMode[ScrollMode["OffScreen"] = 2] = "OffScreen";
+    /**
+     * Scrolling happens constantly in a smooth fashion.
+     * This will disable the use of any native scroll optimizations but
+     * manually scroll the scroll container in the required speed.
+     */
+    ScrollMode[ScrollMode["Smooth"] = 3] = "Smooth";
 })(ScrollMode || (ScrollMode = {}));
 /**
  * This object defines the details on how to generate the vibrato effects.
@@ -48587,6 +48594,25 @@ class MidiFileGenerator {
     }
 }
 
+/**
+ * Represents the information related to a resize event.
+ * @public
+ */
+class ResizeEventArgs {
+    /**
+     * Gets the size before the resizing happened.
+     */
+    oldWidth = 0;
+    /**
+     * Gets the size after the resize was complete.
+     */
+    newWidth = 0;
+    /**
+     * Gets the settings currently used for rendering.
+     */
+    settings = null;
+}
+
 /**
  * Lists the different position modes for {@link BarRendererBase.getBeatX}
  * @internal
@@ -49013,22 +49039,262 @@ class ScoreRendererWrapper {
 }
 
 /**
- * Represents the information related to a resize event.
- * @public
+ * Some basic scroll handler checking for changed offsets and scroll if changed.
+ * @internal
  */
-class ResizeEventArgs {
-    /**
-     * Gets the size before the resizing happened.
-     */
-    oldWidth = 0;
-    /**
-     * Gets the size after the resize was complete.
-     */
-    newWidth = 0;
-    /**
-     * Gets the settings currently used for rendering.
-     */
-    settings = null;
+class BasicScrollHandler {
+    api;
+    lastScroll = -1;
+    constructor(api) {
+        this.api = api;
+    }
+    [Symbol.dispose]() {
+    }
+    forceScrollTo(currentBeatBounds) {
+        this._scrollToBeat(currentBeatBounds, true);
+        this.lastScroll = -1; // force new scroll on next update
+    }
+    _scrollToBeat(currentBeatBounds, force) {
+        const newLastScroll = this.calculateLastScroll(currentBeatBounds);
+        // no change, and no instant/force scroll
+        if (newLastScroll === this.lastScroll && !force) {
+            return;
+        }
+        this.lastScroll = newLastScroll;
+        this.doScroll(currentBeatBounds);
+    }
+    onBeatCursorUpdating(startBeat, _endBeat, _cursorMode, _actualBeatCursorStartX, _actualBeatCursorEndX, _actualBeatCursorTransitionDuration) {
+        this._scrollToBeat(startBeat, false);
+    }
+}
+/**
+ * This is the default scroll handler for vertical layouts using {@link ScrollMode.Continuous}.
+ * Whenever the system changes, we scroll to the new system position vertically.
+ * @internal
+ */
+class VerticalContinuousScrollHandler extends BasicScrollHandler {
+    calculateLastScroll(currentBeatBounds) {
+        return currentBeatBounds.barBounds.masterBarBounds.realBounds.y;
+    }
+    doScroll(currentBeatBounds) {
+        const ui = this.api.uiFacade;
+        const settings = this.api.settings;
+        const scroll = ui.getScrollContainer();
+        const elementOffset = ui.getOffset(scroll, this.api.container);
+        const y = currentBeatBounds.barBounds.masterBarBounds.realBounds.y + settings.player.scrollOffsetY;
+        ui.scrollToY(scroll, elementOffset.y + y, this.api.settings.player.scrollSpeed);
+    }
+}
+/**
+ * This is the default scroll handler for vertical layouts using {@link ScrollMode.OffScreen}.
+ * Whenever the system changes, we check if the new system bounds are out-of-screen and if yes, we scroll.
+ * @internal
+ */
+class VerticalOffScreenScrollHandler extends BasicScrollHandler {
+    calculateLastScroll(currentBeatBounds) {
+        // check for system change
+        return currentBeatBounds.barBounds.masterBarBounds.realBounds.y;
+    }
+    doScroll(currentBeatBounds) {
+        const ui = this.api.uiFacade;
+        const settings = this.api.settings;
+        const scroll = ui.getScrollContainer();
+        const elementBottom = scroll.scrollTop + ui.getOffset(null, scroll).h;
+        const barBoundings = currentBeatBounds.barBounds.masterBarBounds;
+        if (barBoundings.visualBounds.y + barBoundings.visualBounds.h >= elementBottom ||
+            barBoundings.visualBounds.y < scroll.scrollTop) {
+            const scrollTop = barBoundings.realBounds.y + settings.player.scrollOffsetY;
+            ui.scrollToY(scroll, scrollTop, settings.player.scrollSpeed);
+        }
+    }
+}
+/**
+ * This is the default scroll handler for vertical layouts using {@link ScrollMode.Smooth}.
+ * vertical smooth scrolling aims to place the on-time position
+ * at scrollOffsetY **at the time when a system starts**
+ * this means when a system starts, it is at scrollOffsetY,
+ * then gradually scrolls down the system height reaching the bottom
+ * when the system completes.
+ * @internal
+ */
+class VerticalSmoothScrollHandler {
+    _api;
+    _lastScroll = -1;
+    _scrollContainerResizeUnregister;
+    constructor(api) {
+        this._api = api;
+        // we need a resize listener for the overflow calculation
+        this._scrollContainerResizeUnregister = api.uiFacade.getScrollContainer().resize.on(() => {
+            const scrollContainer = api.uiFacade.getScrollContainer();
+            const overflowNeeded = api.settings.player.scrollOffsetX;
+            const viewPortSize = scrollContainer.width;
+            // the content needs to shift out of screen (and back into screen with the offset)
+            // that's why we need the whole width as additional overflow
+            const overflowNeededAbsolute = viewPortSize + overflowNeeded;
+            api.uiFacade.setCanvasOverflow(api.canvasElement, overflowNeededAbsolute, true);
+        });
+    }
+    [Symbol.dispose]() {
+        this._api.uiFacade.setCanvasOverflow(this._api.canvasElement, 0, true);
+        this._scrollContainerResizeUnregister();
+    }
+    forceScrollTo(currentBeatBounds) {
+        const ui = this._api.uiFacade;
+        const settings = this._api.settings;
+        const scroll = ui.getScrollContainer();
+        const systemTop = currentBeatBounds.barBounds.masterBarBounds.realBounds.y + settings.player.scrollOffsetY;
+        ui.scrollToY(scroll, systemTop, 0);
+        this._lastScroll = -1;
+    }
+    onBeatCursorUpdating(startBeat, _endBeat, _cursorMode, _actualBeatCursorStartX, _actualBeatCursorEndX, actualBeatCursorTransitionDuration) {
+        const ui = this._api.uiFacade;
+        const settings = this._api.settings;
+        const barBoundings = startBeat.barBounds.masterBarBounds;
+        const systemTop = barBoundings.realBounds.y + settings.player.scrollOffsetY;
+        if (systemTop === this._lastScroll && actualBeatCursorTransitionDuration > 0) {
+            return;
+        }
+        // jump to start of new system
+        const scroll = ui.getScrollContainer();
+        ui.scrollToY(scroll, systemTop, 0);
+        // instant scroll
+        if (actualBeatCursorTransitionDuration === 0) {
+            this._lastScroll = -1;
+            return;
+        }
+        // dynamic scrolling
+        this._lastScroll = systemTop;
+        // scroll to bottom over time
+        const systemBottom = systemTop + barBoundings.realBounds.h;
+        // NOTE: this calculation is a bit more expensive, but we only do it once per system
+        // so we should be good:
+        // * the more bars we have, the longer the system will play, hence the duration can take a bit longer
+        // * if we have less bars, we calculate more often, but the calculation will be faster because we sum up less bars.
+        const systemDuration = this._calculateSystemDuration(barBoundings);
+        ui.scrollToY(scroll, systemBottom, systemDuration);
+    }
+    _calculateSystemDuration(barBoundings) {
+        const systemBars = barBoundings.staffSystemBounds.bars;
+        const tickCache = this._api.tickCache;
+        let duration = 0;
+        const masterBars = this._api.score.masterBars;
+        for (const bar of systemBars) {
+            const mb = masterBars[bar.index];
+            const mbInfo = tickCache.getMasterBar(mb);
+            const tempoChanges = tickCache.getMasterBar(mb).tempoChanges;
+            let tempo = tempoChanges[0].tempo;
+            let tick = tempoChanges[0].tick;
+            for (let i = 1; i < tempoChanges.length; i++) {
+                const diff = tempoChanges[i].tick - tick;
+                duration += MidiUtils.ticksToMillis(diff, tempo);
+                tempo = tempoChanges[i].tempo;
+                tick = tempoChanges[i].tick;
+            }
+            const toEnd = mbInfo.end - tick;
+            duration += MidiUtils.ticksToMillis(toEnd, tempo);
+        }
+        return duration;
+    }
+}
+/**
+ * This is the default scroll handler for horizontal layouts using {@link ScrollMode.Continuous}.
+ * Whenever the master bar changes, we scroll to the position horizontally.
+ * @internal
+ */
+class HorizontalContinuousScrollHandler extends BasicScrollHandler {
+    calculateLastScroll(currentBeatBounds) {
+        return currentBeatBounds.barBounds.masterBarBounds.visualBounds.x;
+    }
+    doScroll(currentBeatBounds) {
+        const ui = this.api.uiFacade;
+        const settings = this.api.settings;
+        const scroll = ui.getScrollContainer();
+        const barBoundings = currentBeatBounds.barBounds.masterBarBounds;
+        const scrollLeftContinuous = barBoundings.realBounds.x + settings.player.scrollOffsetX;
+        ui.scrollToX(scroll, scrollLeftContinuous, settings.player.scrollSpeed);
+    }
+}
+/**
+ * This is the default scroll handler for horizontal layouts using {@link ScrollMode.OffScreen}.
+ * Whenever the system changes, we check if the new system bounds are out-of-screen and if yes, we scroll.
+ * @internal
+ */
+class HorizontalOffScreenScrollHandler extends BasicScrollHandler {
+    calculateLastScroll(currentBeatBounds) {
+        return currentBeatBounds.barBounds.masterBarBounds.visualBounds.x;
+    }
+    doScroll(currentBeatBounds) {
+        const ui = this.api.uiFacade;
+        const settings = this.api.settings;
+        const scroll = ui.getScrollContainer();
+        const elementRight = scroll.scrollLeft + ui.getOffset(null, scroll).w;
+        const barBoundings = currentBeatBounds.barBounds.masterBarBounds;
+        if (barBoundings.visualBounds.x + barBoundings.visualBounds.w >= elementRight ||
+            barBoundings.visualBounds.x < scroll.scrollLeft) {
+            const scrollLeftOffScreen = barBoundings.realBounds.x + settings.player.scrollOffsetX;
+            ui.scrollToX(scroll, scrollLeftOffScreen, settings.player.scrollSpeed);
+        }
+    }
+}
+/**
+ * This is the default scroll handler for horizontal layouts using {@link ScrollMode.Smooth}.
+ * horiontal smooth scrolling aims to place the on-time position
+ * at scrollOffsetX from a beat-to-beat perspective.
+ * This achieves an steady cursor at the same position with rather the music sheet scrolling past it.
+ * Due to some animation inconsistencies (e.g. CSS animation vs scrolling) there might be a slight
+ * flickering of the cursor.
+ *
+ * To get a fully steady cursor the beat cursor can simply be visually hidden and a cursor can be placed at
+ * `scrollOffsetX` by the integrator.
+ * @internal
+ */
+class HorizontalSmoothScrollHandler {
+    _api;
+    _lastScroll = -1;
+    _scrollContainerResizeUnregister;
+    constructor(api) {
+        this._api = api;
+        // we need a resize listener for the overflow calculation
+        this._scrollContainerResizeUnregister = api.uiFacade.getScrollContainer().resize.on(() => {
+            const scrollContainer = api.uiFacade.getScrollContainer();
+            const overflowNeeded = api.settings.player.scrollOffsetX;
+            const viewPortSize = scrollContainer.width;
+            // the content needs to shift out of screen (and back into screen with the offset)
+            // that's why we need the whole width as additional overflow
+            const overflowNeededAbsolute = viewPortSize + overflowNeeded;
+            api.uiFacade.setCanvasOverflow(api.canvasElement, overflowNeededAbsolute, false);
+        });
+    }
+    [Symbol.dispose]() {
+        this._scrollContainerResizeUnregister();
+        this._api.uiFacade.setCanvasOverflow(this._api.canvasElement, 0, false);
+    }
+    forceScrollTo(currentBeatBounds) {
+        const ui = this._api.uiFacade;
+        const settings = this._api.settings;
+        const scroll = ui.getScrollContainer();
+        const barStartX = currentBeatBounds.onNotesX + settings.player.scrollOffsetY;
+        ui.scrollToY(scroll, barStartX, 0);
+        this._lastScroll = -1;
+    }
+    onBeatCursorUpdating(_startBeat, _endBeat, _cursorMode, actualBeatCursorStartX, actualBeatCursorEndX, actualBeatCursorTransitionDuration) {
+        const ui = this._api.uiFacade;
+        if (actualBeatCursorEndX === this._lastScroll && actualBeatCursorTransitionDuration > 0) {
+            return;
+        }
+        // jump to start of new system
+        const settings = this._api.settings;
+        const scroll = ui.getScrollContainer();
+        ui.scrollToX(scroll, actualBeatCursorStartX + settings.player.scrollOffsetX, 0);
+        // instant scroll
+        if (actualBeatCursorTransitionDuration === 0) {
+            this._lastScroll = -1;
+            return;
+        }
+        this._lastScroll = actualBeatCursorEndX;
+        const scrollX = actualBeatCursorEndX + settings.player.scrollOffsetX;
+        ui.scrollToX(scroll, scrollX, actualBeatCursorTransitionDuration);
+    }
 }
 
 /**
@@ -49671,6 +49937,7 @@ class AlphaTabApiBase {
     _actualPlayerMode = PlayerMode.Disabled;
     _player;
     _renderer;
+    _defaultScrollHandler;
     /**
      * An indicator by how many midi-ticks the song contents are shifted.
      * Grace beats at start might require a shift for the first beat to start at 0.
@@ -50440,6 +50707,42 @@ class AlphaTabApiBase {
         }
     }
     _tickCache = null;
+    /**
+     * A custom scroll handler which will be used to handle scrolling operations during playback.
+     *
+     * @category Properties - Player
+     * @since 1.8.0
+     * @example
+     * JavaScript
+     * ```js
+     * const api = new alphaTab.AlphaTabApi(document.querySelector('#alphaTab'));
+     * api.customScrollHandler = {
+     *   forceScrollTo(currentBeatBounds) {
+     *     const scroll = api.uiFacade.getScrollElement();
+     *     api.uiFacade.scrollToY(scroll, currentBeatBounds.barBounds.masterBarBounds.realBounds.y, 0);
+     *   },
+     *   onBeatCursorUpdating(startBeat, endBeat, cursorMode, relativePosition, actualBeatCursorStartX, actualBeatCursorEndX, actualBeatCursorTransitionDuration) {
+     *     const scroll = api.uiFacade.getScrollElement();
+     *     api.uiFacade.scrollToY(scroll, startBeat.barBounds.masterBarBounds.realBounds.y, 0);
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * C#
+     * ```cs
+     * var api = new AlphaTabApi<MyControl>(...);
+     * api.CustomScrollHandler = new CustomScrollHandler();
+     * ```
+     *
+     * @example
+     * Android
+     * ```kotlin
+     * val api = AlphaTabApi<MyControl>(...)
+     * api.customScrollHandler = CustomScrollHandler();
+     * ```
+     */
+    customScrollHandler;
     /**
      * The tick cache allowing lookup of midi ticks to beats.
      * @remarks
@@ -51418,7 +51721,6 @@ class AlphaTabApiBase {
     _isInitialBeatCursorUpdate = true;
     _previousStateForCursor = PlayerState.Paused;
     _previousCursorCache = null;
-    _lastScroll = 0;
     _destroyCursors() {
         if (!this._cursorWrapper) {
             return;
@@ -51429,28 +51731,79 @@ class AlphaTabApiBase {
         this._beatCursor = null;
         this._selectionWrapper = null;
     }
+    _createCursors() {
+        if (this._cursorWrapper) {
+            return;
+        }
+        const cursors = this.uiFacade.createCursors();
+        if (cursors) {
+            // store options and created elements for fast access
+            this._cursorWrapper = cursors.cursorWrapper;
+            this._barCursor = cursors.barCursor;
+            this._beatCursor = cursors.beatCursor;
+            this._selectionWrapper = cursors.selectionWrapper;
+            this._isInitialBeatCursorUpdate = true;
+        }
+        if (this._currentBeat !== null) {
+            this._cursorUpdateBeat(this._currentBeat, false, this._previousTick > 10, 1, true);
+        }
+    }
     _updateCursors() {
+        this._updateScrollHandler();
         const enable = this._hasCursor;
-        if (enable && !this._cursorWrapper) {
-            //
-            // Create cursors
-            const cursors = this.uiFacade.createCursors();
-            if (cursors) {
-                // store options and created elements for fast access
-                this._cursorWrapper = cursors.cursorWrapper;
-                this._barCursor = cursors.barCursor;
-                this._beatCursor = cursors.beatCursor;
-                this._selectionWrapper = cursors.selectionWrapper;
-                this._isInitialBeatCursorUpdate = true;
-            }
-            if (this._currentBeat !== null) {
-                this._cursorUpdateBeat(this._currentBeat, false, this._previousTick > 10, 1, true);
-            }
+        if (enable) {
+            this._createCursors();
         }
         else if (!enable && this._cursorWrapper) {
             this._destroyCursors();
         }
     }
+    _scrollHandlerMode = ScrollMode.Off;
+    _scrollHandlerVertical = true;
+    _updateScrollHandler() {
+        const currentHandler = this._defaultScrollHandler;
+        const scrollMode = this.settings.player.scrollMode;
+        const isVertical = Environment.getLayoutEngineFactory(this.settings.display.layoutMode).vertical;
+        // no change
+        if (this._scrollHandlerMode === scrollMode && this._scrollHandlerVertical === isVertical) {
+            return;
+        }
+        // destroy current handler in favor of new one
+        if (currentHandler) {
+            currentHandler[Symbol.dispose]();
+            const scroll = this.uiFacade.getScrollContainer();
+            this.uiFacade.stopScrolling(scroll);
+        }
+        switch (scrollMode) {
+            case ScrollMode.Off:
+                this._defaultScrollHandler = undefined;
+                break;
+            case ScrollMode.Continuous:
+                if (isVertical) {
+                    this._defaultScrollHandler = new VerticalContinuousScrollHandler(this);
+                }
+                else {
+                    this._defaultScrollHandler = new HorizontalContinuousScrollHandler(this);
+                }
+                break;
+            case ScrollMode.OffScreen:
+                if (isVertical) {
+                    this._defaultScrollHandler = new VerticalOffScreenScrollHandler(this);
+                }
+                else {
+                    this._defaultScrollHandler = new HorizontalOffScreenScrollHandler(this);
+                }
+                break;
+            case ScrollMode.Smooth:
+                if (isVertical) {
+                    this._defaultScrollHandler = new VerticalSmoothScrollHandler(this);
+                }
+                else {
+                    this._defaultScrollHandler = new HorizontalSmoothScrollHandler(this);
+                }
+                break;
+        }
+    }
     /**
      * updates the cursors to highlight the beat at the specified tick position
      * @param tick
@@ -51513,57 +51866,9 @@ class AlphaTabApiBase {
     scrollToCursor() {
         const beatBounds = this._currentBeatBounds;
         if (beatBounds) {
-            this._internalScrollToCursor(beatBounds.barBounds.masterBarBounds);
-        }
-    }
-    _internalScrollToCursor(barBoundings) {
-        const scrollElement = this.uiFacade.getScrollContainer();
-        const isVertical = Environment.getLayoutEngineFactory(this.settings.display.layoutMode).vertical;
-        const mode = this.settings.player.scrollMode;
-        if (isVertical) {
-            // when scrolling on the y-axis, we preliminary check if the new beat/bar have
-            // moved on the y-axis
-            const y = barBoundings.realBounds.y + this.settings.player.scrollOffsetY;
-            if (y !== this._lastScroll) {
-                this._lastScroll = y;
-                switch (mode) {
-                    case ScrollMode.Continuous:
-                        const elementOffset = this.uiFacade.getOffset(scrollElement, this.container);
-                        this.uiFacade.scrollToY(scrollElement, elementOffset.y + y, this.settings.player.scrollSpeed);
-                        break;
-                    case ScrollMode.OffScreen:
-                        const elementBottom = scrollElement.scrollTop + this.uiFacade.getOffset(null, scrollElement).h;
-                        if (barBoundings.visualBounds.y + barBoundings.visualBounds.h >= elementBottom ||
-                            barBoundings.visualBounds.y < scrollElement.scrollTop) {
-                            const scrollTop = barBoundings.realBounds.y + this.settings.player.scrollOffsetY;
-                            this.uiFacade.scrollToY(scrollElement, scrollTop, this.settings.player.scrollSpeed);
-                        }
-                        break;
-                }
-            }
-        }
-        else {
-            // when scrolling on the x-axis, we preliminary check if the new bar has
-            // moved on the x-axis
-            const x = barBoundings.visualBounds.x;
-            if (x !== this._lastScroll) {
-                this._lastScroll = x;
-                switch (mode) {
-                    case ScrollMode.Continuous:
-                        const scrollLeftContinuous = barBoundings.realBounds.x + this.settings.player.scrollOffsetX;
-                        this._lastScroll = barBoundings.visualBounds.x;
-                        this.uiFacade.scrollToX(scrollElement, scrollLeftContinuous, this.settings.player.scrollSpeed);
-                        break;
-                    case ScrollMode.OffScreen:
-                        const elementRight = scrollElement.scrollLeft + this.uiFacade.getOffset(null, scrollElement).w;
-                        if (barBoundings.visualBounds.x + barBoundings.visualBounds.w >= elementRight ||
-                            barBoundings.visualBounds.x < scrollElement.scrollLeft) {
-                            const scrollLeftOffScreen = barBoundings.realBounds.x + this.settings.player.scrollOffsetX;
-                            this._lastScroll = barBoundings.visualBounds.x;
-                            this.uiFacade.scrollToX(scrollElement, scrollLeftOffScreen, this.settings.player.scrollSpeed);
-                        }
-                        break;
-                }
+            const handler = this.customScrollHandler ?? this._defaultScrollHandler;
+            if (handler) {
+                handler.forceScrollTo(beatBounds);
             }
         }
     }
@@ -51579,11 +51884,12 @@ class AlphaTabApiBase {
         }
         const isPlayingUpdate = this._player.state === PlayerState.Playing && !stop;
         let nextBeatX = barBoundings.visualBounds.x + barBoundings.visualBounds.w;
+        let nextBeatBoundings = null;
         // get position of next beat on same system
         if (nextBeat && cursorMode === MidiTickLookupFindBeatResultCursorMode.ToNextBext) {
             // if we are moving within the same bar or to the next bar
             // transition to the next beat, otherwise transition to the end of the bar.
-            const nextBeatBoundings = cache.findBeat(nextBeat);
+            nextBeatBoundings = cache.findBeat(nextBeat);
             if (nextBeatBoundings &&
                 nextBeatBoundings.barBounds.masterBarBounds.staffSystemBounds === barBoundings.staffSystemBounds) {
                 nextBeatX = nextBeatBoundings.onNotesX;
@@ -51609,25 +51915,29 @@ class AlphaTabApiBase {
                         beatCursor.transitionToX(0, startBeatX);
                         beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
                     }
+                    // it can happen that the cursor reaches the target position slightly too early (especially on backing tracks)
+                    // to avoid the cursor stopping, causing a wierd look, we animate the cursor to the double position in double time.
+                    // beatCursor!.transitionToX((duration / cursorSpeed), nextBeatX);
+                    const factor = cursorMode === MidiTickLookupFindBeatResultCursorMode.ToNextBext ? 2 : 1;
+                    nextBeatX = startBeatX + (nextBeatX - startBeatX) * factor;
+                    duration = (duration / cursorSpeed) * factor;
                     // we need to put the transition to an own animation frame
                     // otherwise the stop animation above is not applied.
                     this.uiFacade.beginInvoke(() => {
-                        // it can happen that the cursor reaches the target position slightly too early (especially on backing tracks)
-                        // to avoid the cursor stopping, causing a wierd look, we animate the cursor to the double position in double time.
-                        // beatCursor!.transitionToX((duration / cursorSpeed), nextBeatX);
-                        const factor = cursorMode === MidiTickLookupFindBeatResultCursorMode.ToNextBext ? 2 : 1;
-                        const doubleEndBeatX = startBeatX + (nextBeatX - startBeatX) * factor;
-                        beatCursor.transitionToX((duration / cursorSpeed) * factor, doubleEndBeatX);
+                        beatCursor.transitionToX(duration, nextBeatX);
                     });
                 }
                 else {
-                    beatCursor.transitionToX(0, startBeatX);
+                    duration = 0;
+                    beatCursor.transitionToX(duration, nextBeatX);
                     beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
                 }
             }
             else {
                 // ticking cursor
-                beatCursor.transitionToX(0, startBeatX);
+                duration = 0;
+                nextBeatX = startBeatX;
+                beatCursor.transitionToX(duration, nextBeatX);
                 beatCursor.setBounds(startBeatX, barBounds.y, 1, barBounds.h);
             }
             this._isInitialBeatCursorUpdate = false;
@@ -51650,7 +51960,10 @@ class AlphaTabApiBase {
             shouldNotifyBeatChange = true;
         }
         if (shouldScroll && !this._isBeatMouseDown && this.settings.player.scrollMode !== ScrollMode.Off) {
-            this._internalScrollToCursor(barBoundings);
+            const handler = this.customScrollHandler ?? this._defaultScrollHandler;
+            if (handler) {
+                handler.onBeatCursorUpdating(beatBoundings, nextBeatBoundings === null ? undefined : nextBeatBoundings, cursorMode, startBeatX, nextBeatX, duration);
+            }
         }
         // trigger an event for others to indicate which beat/bar is played
         if (shouldNotifyBeatChange) {
@@ -53024,6 +53337,7 @@ class AlphaTabApiBase {
             const tickCache = this._tickCache;
             if (currentBeat && tickCache) {
                 this._player.tickPosition = tickCache.getBeatStart(currentBeat.beat);
+                this.scrollToCursor();
             }
         }
         this.uiFacade.triggerEvent(this.container, 'playerStateChanged', e);
@@ -54984,6 +55298,22 @@ class BrowserUiFacade {
         canvasElement.style.position = 'relative';
         return new HtmlElementContainer(canvasElement);
     }
+    setCanvasOverflow(canvasElement, overflow, isVertical) {
+        const html = canvasElement.element;
+        if (overflow === 0) {
+            html.style.boxSizing = '';
+            html.style.paddingRight = '';
+            html.style.paddingBottom = '';
+        }
+        else if (isVertical) {
+            html.style.boxSizing = 'content-box';
+            html.style.paddingBottom = `${overflow}px`;
+        }
+        else {
+            html.style.boxSizing = 'content-box';
+            html.style.paddingRight = `${overflow}px`;
+        }
+    }
     triggerEvent(container, name, details = null, originalEvent) {
         const element = container.element;
         name = `alphaTab.${name}`;
@@ -55541,54 +55871,79 @@ class BrowserUiFacade {
     scrollToX(element, scrollTargetY, speed) {
         this._internalScrollToX(element.element, scrollTargetY, speed);
     }
+    stopScrolling(scrollElement) {
+        // stop any current animation
+        const currentAnimation = this._scrollAnimationLookup.get(scrollElement.element);
+        if (currentAnimation !== undefined) {
+            this._activeScrollAnimations.delete(currentAnimation);
+        }
+    }
+    get _nativeBrowserSmoothScroll() {
+        const settings = this._api.settings.player;
+        return settings.nativeBrowserSmoothScroll && settings.scrollMode !== ScrollMode.Smooth;
+    }
+    _scrollAnimationId = 0;
+    _activeScrollAnimations = new Set();
+    _scrollAnimationLookup = new Map();
     _internalScrollToY(element, scrollTargetY, speed) {
-        if (this._api.settings.player.nativeBrowserSmoothScroll) {
+        if (this._nativeBrowserSmoothScroll) {
             element.scrollTo({
                 top: scrollTargetY,
                 behavior: 'smooth'
             });
         }
         else {
-            const startY = element.scrollTop;
-            const diff = scrollTargetY - startY;
-            let start = 0;
-            const step = (x) => {
-                if (start === 0) {
-                    start = x;
-                }
-                const time = x - start;
-                const percent = Math.min(time / speed, 1);
-                element.scrollTop = (startY + diff * percent) | 0;
-                if (time < speed) {
-                    window.requestAnimationFrame(step);
-                }
-            };
-            window.requestAnimationFrame(step);
+            this._internalScrollTo(element, element.scrollTop, scrollTargetY, speed, scroll => {
+                element.scrollTop = scroll;
+            });
+        }
+    }
+    _internalScrollTo(element, startScroll, endScroll, scrollDuration, setValue) {
+        // stop any current animation
+        const currentAnimation = this._scrollAnimationLookup.get(element);
+        if (currentAnimation !== undefined) {
+            this._activeScrollAnimations.delete(currentAnimation);
+        }
+        if (scrollDuration === 0) {
+            setValue(endScroll);
+            return;
         }
+        // start new animation
+        const animationId = this._scrollAnimationId++;
+        this._scrollAnimationLookup.set(element, animationId);
+        this._activeScrollAnimations.add(animationId);
+        const diff = endScroll - startScroll;
+        let start = 0;
+        const step = (x) => {
+            if (!this._activeScrollAnimations.has(animationId)) {
+                return;
+            }
+            if (start === 0) {
+                start = x;
+            }
+            const time = x - start;
+            const percent = Math.min(time / scrollDuration, 1);
+            setValue((startScroll + diff * percent) | 0);
+            if (time < scrollDuration) {
+                window.requestAnimationFrame(step);
+            }
+            else {
+                this._activeScrollAnimations.delete(animationId);
+            }
+        };
+        window.requestAnimationFrame(step);
     }
     _internalScrollToX(element, scrollTargetX, speed) {
-        if (this._api.settings.player.nativeBrowserSmoothScroll) {
+        if (this._nativeBrowserSmoothScroll) {
             element.scrollTo({
                 left: scrollTargetX,
                 behavior: 'smooth'
             });
         }
         else {
-            const startX = element.scrollLeft;
-            const diff = scrollTargetX - startX;
-            let start = 0;
-            const step = (t) => {
-                if (start === 0) {
-                    start = t;
-                }
-                const time = t - start;
-                const percent = Math.min(time / speed, 1);
-                element.scrollLeft = (startX + diff * percent) | 0;
-                if (time < speed) {
-                    window.requestAnimationFrame(step);
-                }
-            };
-            window.requestAnimationFrame(step);
+            this._internalScrollTo(element, element.scrollLeft, scrollTargetX, speed, scroll => {
+                element.scrollLeft = scroll;
+            });
         }
     }
     createBackingTrackPlayer() {
@@ -61701,8 +62056,8 @@ class StaffSystem {
                             }
                         }
                     }
+                    this.accoladeWidth += settings.display.systemLabelPaddingLeft;
                     if (hasAnyTrackName) {
-                        this.accoladeWidth += settings.display.systemLabelPaddingLeft;
                         this.accoladeWidth += settings.display.systemLabelPaddingRight;
                     }
                 }