@coderline/alphatab 1.8.0-alpha.1647 → 1.8.0-alpha.1651

package/dist/alphaTab.core.mjs

@@ -1,5 +1,5 @@
 /*!
- * alphaTab v1.8.0-alpha.1647 (develop, build 1647)
+ * alphaTab v1.8.0-alpha.1651 (develop, build 1651)
  *
  * 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.1647';
-    static date = '2025-12-17T02:10:13.730Z';
-    static commit = 'a1bd11d4a3eef22409f1f49a5dd172ace16108cc';
+    static version = '1.8.0-alpha.1651';
+    static date = '2025-12-21T02:27:24.035Z';
+    static commit = '758ae890dfa8cdb21a9dd469ade012f834ac0433';
     static print(print) {
         print(`alphaTab ${VersionInfo.version}`);
         print(`commit: ${VersionInfo.commit}`);
@@ -2744,6 +2744,23 @@ class RenderStylesheet {
      * Whether barlines should be drawn across staves within the same system.
      */
     extendBarLines = false;
+    /**
+     * Whether to hide empty staves.
+     */
+    hideEmptyStaves = false;
+    /**
+     * Whether to also hide empty staves in the first system.
+     * @remarks
+     * Only has an effect when activating {@link hideEmptyStaves}.
+     */
+    hideEmptyStavesInFirstSystem = false;
+    /**
+     * Whether to show brackets and braces across single staves.
+     * @remarks
+     * This allows a more consistent view for identifying staves when using
+     * {@link hideEmptyStaves}
+     */
+    showSingleStaffBrackets = false;
 }
 
 /**
@@ -8673,7 +8690,10 @@ class AlphaTex1LanguageDefinitions {
         ['firstsystemtracknameorientation', [[[[10, 17], 0, ['horizontal', 'vertical']]]]],
         ['othersystemstracknameorientation', [[[[10, 17], 0, ['horizontal', 'vertical']]]]],
         ['extendbarlines', null],
-        ['chorddiagramsinscore', [[[[10], 1, ['true', 'false']]]]]
+        ['chorddiagramsinscore', [[[[10], 1, ['true', 'false']]]]],
+        ['hideemptystaves', null],
+        ['hideemptystavesinfirstsystem', null],
+        ['showsinglestaffbrackets', null]
     ]);
     static staffMetaDataSignatures = AlphaTex1LanguageDefinitions._signatures([
         ['tuning', [[[[10, 17], 0, ['piano', 'none', 'voice']]], [[[10, 17], 5]]]],
@@ -9013,6 +9033,9 @@ class AlphaTex1LanguageDefinitions {
         ['othersystemstracknameorientation', null],
         ['extendbarlines', null],
         ['chorddiagramsinscore', null],
+        ['hideemptystaves', null],
+        ['hideemptystavesinfirstsystem', null],
+        ['showsinglestaffbrackets', null],
         [
             'tuning',
             [
@@ -13066,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;
     /**
@@ -13274,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 = {};
@@ -13330,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);
@@ -13887,6 +13911,15 @@ class AlphaTex1LanguageHandler {
                     ? AlphaTex1LanguageHandler._booleanLikeValue(metaData.arguments.arguments, 0)
                     : true;
                 return ApplyNodeResult.Applied;
+            case 'hideemptystaves':
+                score.stylesheet.hideEmptyStaves = true;
+                return ApplyNodeResult.Applied;
+            case 'hideemptystavesinfirstsystem':
+                score.stylesheet.hideEmptyStavesInFirstSystem = true;
+                return ApplyNodeResult.Applied;
+            case 'showsinglestaffbrackets':
+                score.stylesheet.showSingleStaffBrackets = true;
+                return ApplyNodeResult.Applied;
             default:
                 return ApplyNodeResult.NotAppliedUnrecognizedMarker;
         }
@@ -15718,6 +15751,15 @@ class AlphaTex1LanguageHandler {
         if (stylesheet.globalDisplayChordDiagramsInScore) {
             nodes.push(Atnf.meta('chordDiagramsInScore'));
         }
+        if (stylesheet.hideEmptyStaves) {
+            nodes.push(Atnf.meta('hideEmptyStaves'));
+        }
+        if (stylesheet.hideEmptyStavesInFirstSystem) {
+            nodes.push(Atnf.meta('hideEmptyStavesInFirstSystem'));
+        }
+        if (stylesheet.showSingleStaffBrackets) {
+            nodes.push(Atnf.meta('showSingleStaffBrackets'));
+        }
         // Unsupported:
         // 'globaldisplaychorddiagramsontop',
         // 'pertrackchorddiagramsontop',
@@ -38804,6 +38846,9 @@ class RenderStylesheetSerializer {
             }
         }
         o.set("extendbarlines", obj.extendBarLines);
+        o.set("hideemptystaves", obj.hideEmptyStaves);
+        o.set("hideemptystavesinfirstsystem", obj.hideEmptyStavesInFirstSystem);
+        o.set("showsinglestaffbrackets", obj.showSingleStaffBrackets);
         return o;
     }
     static setProperty(obj, property, v) {
@@ -38865,6 +38910,15 @@ class RenderStylesheetSerializer {
             case "extendbarlines":
                 obj.extendBarLines = v;
                 return true;
+            case "hideemptystaves":
+                obj.hideEmptyStaves = v;
+                return true;
+            case "hideemptystavesinfirstsystem":
+                obj.hideEmptyStavesInFirstSystem = v;
+                return true;
+            case "showsinglestaffbrackets":
+                obj.showSingleStaffBrackets = v;
+                return true;
         }
         return false;
     }
@@ -43604,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.
@@ -45892,6 +45952,19 @@ class BeatTickLookup {
         }
         return null;
     }
+    /**
+     * Looks for the first visible beat which starts at this lookup so it can be used for cursor placement.
+     * @param checker The custom checker to see if a beat is visible.
+     * @returns The first beat which is visible according to the given tracks or null.
+     */
+    getVisibleBeatAtStartWithChecker(checker) {
+        for (const b of this.highlightedBeats) {
+            if (b.playbackStart === this.start && checker.isVisible(b.beat)) {
+                return b.beat;
+            }
+        }
+        return null;
+    }
 }
 
 /**
@@ -46331,6 +46404,18 @@ class MidiTickLookupFindBeatResult {
         }
     }
 }
+/**
+ * @internal
+ */
+class TrackLookupBeatVisibilityChecker {
+    _lookup;
+    constructor(lookup) {
+        this._lookup = lookup;
+    }
+    isVisible(beat) {
+        return this._lookup.has(beat.voice.bar.staff.track.index);
+    }
+}
 /**
  * This class holds all information about when {@link MasterBar}s and {@link Beat}s are played.
  *
@@ -46391,31 +46476,44 @@ class MidiTickLookup {
      * @returns The information about the current beat or null if no beat could be found.
      */
     findBeat(trackLookup, tick, currentBeatHint = null) {
+        return this.findBeatWithChecker(new TrackLookupBeatVisibilityChecker(trackLookup), tick, currentBeatHint);
+    }
+    /**
+     * Finds the currently played beat given a list of tracks and the current time.
+     * @param checker The checker to ask whether a beat is visible and should be considered for result.
+     * @param tick The current time in midi ticks.
+     * @param currentBeatHint Used for optimized lookup during playback. By passing in a previous result lookup of the next one can be optimized using heuristics. (optional).
+     * @returns The information about the current beat or null if no beat could be found.
+     */
+    findBeatWithChecker(checker, tick, currentBeatHint = null) {
         let result = null;
         if (currentBeatHint) {
-            result = this._findBeatFast(trackLookup, currentBeatHint, tick);
+            result = this._findBeatFast(checker, currentBeatHint, tick);
         }
         if (!result) {
-            result = this._findBeatSlow(trackLookup, currentBeatHint, tick, false);
+            result = this._findBeatSlow(checker, currentBeatHint, tick, false);
         }
         return result;
     }
-    _findBeatFast(trackLookup, currentBeatHint, tick) {
+    _findBeatFast(checker, currentBeatHint, tick) {
         // still within current lookup.
         if (tick >= currentBeatHint.start && tick < currentBeatHint.end) {
             return currentBeatHint;
         }
         // already on the next beat?
-        if (currentBeatHint.nextBeat && tick >= currentBeatHint.nextBeat.start && tick < currentBeatHint.nextBeat.end) {
+        if (currentBeatHint.nextBeat &&
+            tick >= currentBeatHint.nextBeat.start &&
+            tick < currentBeatHint.nextBeat.end &&
+            (checker === undefined || checker.isVisible(currentBeatHint.nextBeat.beat))) {
             const next = currentBeatHint.nextBeat;
             // fill next in chain
-            this._fillNextBeat(next, trackLookup);
+            this._fillNextBeat(next, checker);
             return next;
         }
         // likely a loop or manual seek, need to fallback to slow path
         return null;
     }
-    _fillNextBeatMultiBarRest(current, trackLookup) {
+    _fillNextBeatMultiBarRest(current, checker) {
         const group = this.multiBarRestInfo.get(current.masterBar.masterBar.index);
         // this is a bit sensitive. we assume that the sequence of multi-rest bars and the
         // chained nextMasterBar equal. so we just jump over X bars
@@ -46429,7 +46527,7 @@ class MidiTickLookup {
         if (endMasterBar) {
             // one more following -> use start of next
             if (endMasterBar.nextMasterBar) {
-                current.nextBeat = this._firstBeatInMasterBar(trackLookup, endMasterBar.nextMasterBar, endMasterBar.nextMasterBar.start, true);
+                current.nextBeat = this._firstBeatInMasterBar(checker, endMasterBar.nextMasterBar, endMasterBar.nextMasterBar.start, true);
                 // if we have the next beat take the difference between the times as duration
                 if (current.nextBeat) {
                     current.tickDuration = current.nextBeat.start - current.start;
@@ -46459,19 +46557,19 @@ class MidiTickLookup {
         }
         current.calculateDuration();
     }
-    _fillNextBeat(current, trackLookup) {
+    _fillNextBeat(current, checker) {
         // on multibar rests take the duration until the end.
         if (this._isMultiBarRestResult(current)) {
-            this._fillNextBeatMultiBarRest(current, trackLookup);
+            this._fillNextBeatMultiBarRest(current, checker);
         }
         else {
-            this._fillNextBeatDefault(current, trackLookup);
+            this._fillNextBeatDefault(current, checker);
         }
     }
-    _fillNextBeatDefault(current, trackLookup) {
-        current.nextBeat = this._findBeatInMasterBar(current.masterBar, current.beatLookup.nextBeat, current.end, trackLookup, true);
+    _fillNextBeatDefault(current, checker) {
+        current.nextBeat = this._findBeatInMasterBar(current.masterBar, current.beatLookup.nextBeat, current.end, checker, true);
         if (current.nextBeat == null) {
-            current.nextBeat = this._findBeatSlow(trackLookup, current, current.end, true);
+            current.nextBeat = this._findBeatSlow(checker, current, current.end, true);
         }
         // if we have the next beat take the difference between the times as duration
         if (current.nextBeat) {
@@ -46502,7 +46600,7 @@ class MidiTickLookup {
             beat.isRest &&
             beat.voice.bar.isRestOnly);
     }
-    _findBeatSlow(trackLookup, currentBeatHint, tick, isNextSearch) {
+    _findBeatSlow(checker, currentBeatHint, tick, isNextSearch) {
         // get all beats within the masterbar
         let masterBar = null;
         if (currentBeatHint != null) {
@@ -46524,14 +46622,14 @@ class MidiTickLookup {
         if (!masterBar) {
             return null;
         }
-        return this._firstBeatInMasterBar(trackLookup, masterBar, tick, isNextSearch);
+        return this._firstBeatInMasterBar(checker, masterBar, tick, isNextSearch);
     }
-    _firstBeatInMasterBar(trackLookup, startMasterBar, tick, isNextSearch) {
+    _firstBeatInMasterBar(checker, startMasterBar, tick, isNextSearch) {
         let masterBar = startMasterBar;
         // scan through beats and find first one which has a beat visible
         while (masterBar) {
             if (masterBar.firstBeat) {
-                const beat = this._findBeatInMasterBar(masterBar, masterBar.firstBeat, tick, trackLookup, isNextSearch);
+                const beat = this._findBeatInMasterBar(masterBar, masterBar.firstBeat, tick, checker, isNextSearch);
                 if (beat) {
                     return beat;
                 }
@@ -46549,7 +46647,7 @@ class MidiTickLookup {
      * @param isNextSearch
      * @returns
      */
-    _findBeatInMasterBar(masterBar, currentStartLookup, tick, visibleTracks, isNextSearch) {
+    _findBeatInMasterBar(masterBar, currentStartLookup, tick, checker, isNextSearch) {
         if (!currentStartLookup) {
             return null;
         }
@@ -46563,7 +46661,7 @@ class MidiTickLookup {
             (currentStartLookup.start <= relativeTick || (isNextSearch && relativeTick < 0)) &&
                 relativeTick < currentStartLookup.end) {
                 startBeatLookup = currentStartLookup;
-                startBeat = currentStartLookup.getVisibleBeatAtStart(visibleTracks);
+                startBeat = currentStartLookup.getVisibleBeatAtStartWithChecker(checker);
                 // found the matching beat lookup but none of the beats are visible
                 // in this case scan further to the next lookup which has any visible beat
                 if (!startBeat) {
@@ -46571,7 +46669,7 @@ class MidiTickLookup {
                         let currentMasterBar = masterBar;
                         while (currentMasterBar != null && startBeat == null) {
                             while (currentStartLookup != null) {
-                                startBeat = currentStartLookup.getVisibleBeatAtStart(visibleTracks);
+                                startBeat = currentStartLookup.getVisibleBeatAtStartWithChecker(checker);
                                 if (startBeat) {
                                     startBeatLookup = currentStartLookup;
                                     masterBar = currentMasterBar;
@@ -46589,7 +46687,7 @@ class MidiTickLookup {
                         let currentMasterBar = masterBar;
                         while (currentMasterBar != null && startBeat == null) {
                             while (currentStartLookup != null) {
-                                startBeat = currentStartLookup.getVisibleBeatAtStart(visibleTracks);
+                                startBeat = currentStartLookup.getVisibleBeatAtStartWithChecker(checker);
                                 if (startBeat) {
                                     startBeatLookup = currentStartLookup;
                                     masterBar = currentMasterBar;
@@ -46613,17 +46711,17 @@ class MidiTickLookup {
         if (startBeat == null) {
             return null;
         }
-        const result = this._createResult(masterBar, startBeatLookup, startBeat, isNextSearch, visibleTracks);
+        const result = this._createResult(masterBar, startBeatLookup, startBeat, isNextSearch, checker);
         return result;
     }
-    _createResult(masterBar, beatLookup, beat, isNextSearch, visibleTracks) {
+    _createResult(masterBar, beatLookup, beat, isNextSearch, checker) {
         const result = new MidiTickLookupFindBeatResult(masterBar);
         result.beat = beat;
         result.beatLookup = beatLookup;
         result.tickDuration = beatLookup.end - beatLookup.start;
         if (!isNextSearch) {
             // the next beat filling will adjust this result with the respective durations
-            this._fillNextBeat(result, visibleTracks);
+            this._fillNextBeat(result, checker);
         }
         else if (this._isMultiBarRestResult(result)) {
             const multiRest = this.multiBarRestInfo.get(masterBar.masterBar.index);
@@ -48496,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
@@ -48922,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);
+    }
 }
 
 /**
@@ -49550,6 +49907,19 @@ class ExternalMediaPlayer extends BackingTrackPlayer {
     }
 }
 
+/**
+ * @internal
+ */
+class BoundsLookupVisibilityChecker {
+    bounds = null;
+    isVisible(beat) {
+        const bounds = this.bounds;
+        if (!bounds) {
+            return false;
+        }
+        return bounds.findBeat(beat) !== null;
+    }
+}
 /**
  * This class represents the public API of alphaTab and provides all logic to display
  * a music sheet in any UI using the given {@link IUiFacade}
@@ -49560,12 +49930,14 @@ class AlphaTabApiBase {
     _startTime = 0;
     _trackIndexes = null;
     _trackIndexLookup = null;
+    _beatVisibilityChecker = new BoundsLookupVisibilityChecker();
     _isDestroyed = false;
     _score = null;
     _tracks = [];
     _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.
@@ -50335,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
@@ -51313,7 +51721,6 @@ class AlphaTabApiBase {
     _isInitialBeatCursorUpdate = true;
     _previousStateForCursor = PlayerState.Paused;
     _previousCursorCache = null;
-    _lastScroll = 0;
     _destroyCursors() {
         if (!this._cursorWrapper) {
             return;
@@ -51324,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
@@ -51356,12 +51814,9 @@ class AlphaTabApiBase {
         this._previousTick = tick;
         const cache = this._tickCache;
         if (cache) {
-            const tracks = this._trackIndexLookup;
-            if (tracks != null && tracks.size > 0) {
-                const beat = cache.findBeat(tracks, tick, this._currentBeat);
-                if (beat) {
-                    this._cursorUpdateBeat(beat, stop, shouldScroll, cursorSpeed, forceUpdate || this.playerState === PlayerState.Paused);
-                }
+            const beat = cache.findBeatWithChecker(this._beatVisibilityChecker, tick, this._currentBeat);
+            if (beat) {
+                this._cursorUpdateBeat(beat, stop, shouldScroll, cursorSpeed, forceUpdate || this.playerState === PlayerState.Paused);
             }
         }
     }
@@ -51411,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);
             }
         }
     }
@@ -51477,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;
@@ -51507,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;
@@ -51548,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) {
@@ -52563,6 +52978,7 @@ class AlphaTabApiBase {
         if (this._isDestroyed) {
             return;
         }
+        this._beatVisibilityChecker.bounds = this.boundsLookup;
         this._currentBeat = null;
         this._cursorUpdateTick(this._previousTick, false, 1, true, true);
         this.postRenderFinished.trigger();
@@ -52921,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);
@@ -54881,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}`;
@@ -55438,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() {
@@ -60570,8 +61028,10 @@ class RenderStaff {
     height = 0;
     index = 0;
     staffIndex = 0;
+    isVisible = false;
+    _emptyBarCount = 0;
     get isFirstInSystem() {
-        return this.index === 0;
+        return this.system.firstVisibleStaff === this;
     }
     topEffectInfos = [];
     bottomEffectInfos = [];
@@ -60606,10 +61066,11 @@ class RenderStaff {
     get contentBottom() {
         return this.y + this.topPadding + this.topOverflow + this.staffBottom;
     }
-    constructor(trackIndex, staff, factory) {
+    constructor(system, trackIndex, staff, factory) {
         this._factory = factory;
         this.trackIndex = trackIndex;
         this.modelStaff = staff;
+        this.system = system;
         for (const b of factory.effectBands) {
             if (b.shouldCreate && !b.shouldCreate(staff)) {
                 continue;
@@ -60625,6 +61086,7 @@ class RenderStaff {
                     break;
             }
         }
+        this._updateVisibility();
     }
     getSharedLayoutData(key, def) {
         if (this._sharedLayoutData.has(key)) {
@@ -60651,6 +61113,20 @@ class RenderStaff {
         renderer.reLayout();
         this.barRenderers.push(renderer);
         this.system.layout.registerBarRenderer(this.staffId, renderer);
+        if (renderer.bar.isEmpty || renderer.bar.isRestOnly) {
+            this._emptyBarCount++;
+        }
+        this._updateVisibility();
+    }
+    _updateVisibility() {
+        const stylesheet = this.modelStaff.track.score.stylesheet;
+        const canHideEmptyStaves = stylesheet.hideEmptyStaves && (stylesheet.hideEmptyStavesInFirstSystem || this.system.index > 0);
+        if (canHideEmptyStaves) {
+            this.isVisible = this._emptyBarCount < this.barRenderers.length;
+        }
+        else {
+            this.isVisible = true;
+        }
     }
     addBar(bar, layoutingInfo, additionalMultiBarsRestBars) {
         const renderer = this._factory.create(this.system.layout.renderer, bar);
@@ -60670,6 +61146,10 @@ class RenderStaff {
         }
         this.barRenderers.push(renderer);
         this.system.layout.registerBarRenderer(this.staffId, renderer);
+        if (bar.isEmpty || bar.isRestOnly) {
+            this._emptyBarCount++;
+        }
+        this._updateVisibility();
     }
     revertLastBar() {
         this._sharedLayoutData = new Map();
@@ -60680,6 +61160,10 @@ class RenderStaff {
         for (const r of this.barRenderers) {
             r.afterStaffBarReverted();
         }
+        if (lastBar.bar.isEmpty || lastBar.bar.isRestOnly) {
+            this._emptyBarCount--;
+        }
+        this._updateVisibility();
         return lastBar;
     }
     scaleToWidth(width) {
@@ -60790,6 +61274,7 @@ class RenderStaff {
             this.height += this.topPadding + topOverflow + this.bottomOverflow + this.bottomPadding;
         }
         this.height = Math.ceil(this.height);
+        this._updateVisibility();
     }
     paint(cx, cy, canvas, startIndex, count) {
         if (this.height === 0 || count === 0) {
@@ -61190,6 +61675,8 @@ class StaffTrackGroup {
     track;
     staffSystem;
     staves = [];
+    firstVisibleStaff;
+    lastVisibleStaff;
     bracket = null;
     constructor(staffSystem, track) {
         this.staffSystem = staffSystem;
@@ -61204,18 +61691,47 @@ class StaffTrackGroup {
  * @internal
  */
 class SystemBracket {
-    firstStaffInBracket = null;
-    lastStaffInBracket = null;
+    _system;
+    firstStaffInBracket;
+    lastStaffInBracket;
+    firstVisibleStaffInBracket;
+    lastVisibleStaffInBracket;
     drawAsBrace = false;
     braceScale = 1;
     width = 0;
     index = 0;
-    get canPaint() {
-        return this.firstStaffInBracket !== null && this.lastStaffInBracket !== null;
+    canPaint = false;
+    constructor(system) {
+        this._system = system;
+    }
+    updateCanPaint() {
+        let firstVisibleStaff = undefined;
+        let lastVisibleStaff = undefined;
+        for (let i = this.firstStaffInBracket.index; i <= this.lastStaffInBracket.index; i++) {
+            const staff = this._system.allStaves[i];
+            if (staff.isVisible) {
+                if (!firstVisibleStaff) {
+                    firstVisibleStaff = staff;
+                }
+                lastVisibleStaff = staff;
+            }
+        }
+        this.firstVisibleStaffInBracket = firstVisibleStaff;
+        this.lastVisibleStaffInBracket = lastVisibleStaff;
+        if (!firstVisibleStaff || !lastVisibleStaff) {
+            this.canPaint = false;
+            return;
+        }
+        // single staff brackets?
+        const singleStaffBrackets = this._system.layout.renderer.score.stylesheet.showSingleStaffBrackets;
+        if (!singleStaffBrackets && firstVisibleStaff === lastVisibleStaff) {
+            this.canPaint = false;
+            return;
+        }
+        this.canPaint = true;
     }
     finalizeBracket(smuflMetrics) {
-        // systems with just a single staff do not have a bracket
-        if (this.firstStaffInBracket === this.lastStaffInBracket) {
+        if (!this.canPaint) {
             this.width = 0;
             return;
         }
@@ -61229,11 +61745,11 @@ class SystemBracket {
         else {
             this.width = smuflMetrics.bracketThickness;
         }
-        if (!this.drawAsBrace || !this.firstStaffInBracket || !this.lastStaffInBracket) {
+        if (!this.drawAsBrace) {
             return;
         }
-        const firstStart = this.firstStaffInBracket.contentTop;
-        const lastEnd = this.lastStaffInBracket.contentBottom;
+        const firstStart = this.firstVisibleStaffInBracket.contentTop;
+        const lastEnd = this.lastVisibleStaffInBracket.contentBottom;
         const requiredHeight = lastEnd - firstStart;
         const requiredScaleForBracket = requiredHeight / bravuraBraceHeightAtMusicFontSize;
         this.braceScale = requiredScaleForBracket;
@@ -61245,8 +61761,8 @@ class SystemBracket {
  */
 class SingleTrackSystemBracket extends SystemBracket {
     track;
-    constructor(track) {
-        super();
+    constructor(system, track) {
+        super(system);
         this.track = track;
         this.drawAsBrace = SingleTrackSystemBracket.isTrackDrawAsBrace(track);
     }
@@ -61311,6 +61827,7 @@ class StaffSystem {
     topPadding;
     bottomPadding;
     allStaves = [];
+    firstVisibleStaff;
     constructor(layout) {
         this.layout = layout;
         this.topPadding = layout.renderer.settings.display.systemPaddingTop;
@@ -61329,14 +61846,40 @@ class StaffSystem {
         this.masterBarsRenderers.push(renderers);
         renderers.layoutingInfo.preBeatSize = 0;
         let src = 0;
-        for (let i = 0, j = this.staves.length; i < j; i++) {
-            const g = this.staves[i];
-            for (let k = 0, l = g.staves.length; k < l; k++) {
-                const s = g.staves[k];
+        let firstVisibleStaff = undefined;
+        let anyStaffVisible = false;
+        for (const g of this.staves) {
+            let firstVisibleStaffInGroup = undefined;
+            let lastVisibleStaffInGroup = undefined;
+            for (const s of g.staves) {
                 const renderer = renderers.renderers[src++];
                 s.addBarRenderer(renderer);
+                if (s.isVisible) {
+                    anyStaffVisible = true;
+                    if (!firstVisibleStaffInGroup) {
+                        firstVisibleStaffInGroup = s;
+                    }
+                    if (!firstVisibleStaff) {
+                        firstVisibleStaff = s;
+                    }
+                    lastVisibleStaffInGroup = s;
+                }
+            }
+            g.firstVisibleStaff = firstVisibleStaffInGroup;
+            g.lastVisibleStaff = lastVisibleStaffInGroup;
+            if (!firstVisibleStaff) {
+                firstVisibleStaff = firstVisibleStaffInGroup;
             }
         }
+        if (!anyStaffVisible) {
+            const group = this.staves[0];
+            const firstStaff = group.staves[0];
+            firstStaff.isVisible = true;
+            group.firstVisibleStaff = firstStaff;
+            group.lastVisibleStaff = firstStaff;
+            firstVisibleStaff = firstStaff;
+        }
+        this.firstVisibleStaff = firstVisibleStaff;
         this._calculateAccoladeSpacing(tracks);
         this._updateWidthFromLastBar();
         return renderers;
@@ -61347,15 +61890,26 @@ class StaffSystem {
         result.layoutingInfo = new BarLayoutingInfo();
         result.masterBar = tracks[0].score.masterBars[barIndex];
         this.masterBarsRenderers.push(result);
+        let firstVisibleStaff = undefined;
+        let anyStaffVisible = false;
         // add renderers
         const barLayoutingInfo = result.layoutingInfo;
         for (const g of this.staves) {
+            let firstVisibleStaffInGroup = undefined;
+            let lastVisibleStaffInGroup = undefined;
             for (const s of g.staves) {
                 const bar = g.track.staves[s.modelStaff.index].bars[barIndex];
                 const additionalMultiBarsRestBars = additionalMultiBarRestIndexes == null
                     ? null
                     : additionalMultiBarRestIndexes.map(b => g.track.staves[s.modelStaff.index].bars[b]);
                 s.addBar(bar, barLayoutingInfo, additionalMultiBarsRestBars);
+                if (s.isVisible) {
+                    anyStaffVisible = true;
+                    if (!firstVisibleStaffInGroup) {
+                        firstVisibleStaffInGroup = s;
+                    }
+                    lastVisibleStaffInGroup = s;
+                }
                 const renderer = s.barRenderers[s.barRenderers.length - 1];
                 result.renderers.push(renderer);
                 if (renderer.isLinkedToPrevious) {
@@ -61365,7 +61919,21 @@ class StaffSystem {
                     result.canWrap = false;
                 }
             }
+            g.firstVisibleStaff = firstVisibleStaffInGroup;
+            g.lastVisibleStaff = lastVisibleStaffInGroup;
+            if (!firstVisibleStaff) {
+                firstVisibleStaff = firstVisibleStaffInGroup;
+            }
+        }
+        if (!anyStaffVisible) {
+            const group = this.staves[0];
+            const firstStaff = group.staves[0];
+            firstStaff.isVisible = true;
+            group.firstVisibleStaff = firstStaff;
+            group.lastVisibleStaff = firstStaff;
+            firstVisibleStaff = firstStaff;
         }
+        this.firstVisibleStaff = firstVisibleStaff;
         this._calculateAccoladeSpacing(tracks);
         barLayoutingInfo.finish();
         // ensure same widths of new renderer
@@ -61378,19 +61946,35 @@ class StaffSystem {
             this.masterBarsRenderers.splice(this.masterBarsRenderers.length - 1, 1);
             let width = 0;
             let barDisplayScale = 0;
-            for (let i = 0, j = this.allStaves.length; i < j; i++) {
-                const s = this.allStaves[i];
-                const lastBar = s.revertLastBar();
-                const computedWidth = lastBar.computedWidth;
-                if (computedWidth > width) {
-                    width = computedWidth;
+            let firstVisibleStaff = undefined;
+            for (const g of this.staves) {
+                let firstVisibleStaffInGroup = undefined;
+                let lastVisibleStaffInGroup = undefined;
+                for (const s of g.staves) {
+                    const lastBar = s.revertLastBar();
+                    const computedWidth = lastBar.computedWidth;
+                    if (computedWidth > width) {
+                        width = computedWidth;
+                    }
+                    const newBarDisplayScale = lastBar.barDisplayScale;
+                    if (newBarDisplayScale > barDisplayScale) {
+                        barDisplayScale = newBarDisplayScale;
+                    }
+                    lastBar.afterReverted();
+                    if (s.isVisible) {
+                        if (!firstVisibleStaffInGroup) {
+                            firstVisibleStaffInGroup = s;
+                        }
+                        lastVisibleStaffInGroup = s;
+                    }
                 }
-                const newBarDisplayScale = lastBar.barDisplayScale;
-                if (newBarDisplayScale > barDisplayScale) {
-                    barDisplayScale = newBarDisplayScale;
+                g.firstVisibleStaff = firstVisibleStaffInGroup;
+                g.lastVisibleStaff = lastVisibleStaffInGroup;
+                if (!firstVisibleStaff) {
+                    firstVisibleStaff = firstVisibleStaffInGroup;
                 }
-                lastBar.afterReverted();
             }
+            this.firstVisibleStaff = firstVisibleStaff;
             this.width -= width;
             this.computedWidth -= width;
             this.totalBarDisplayScale -= barDisplayScale;
@@ -61472,8 +62056,8 @@ class StaffSystem {
                             }
                         }
                     }
+                    this.accoladeWidth += settings.display.systemLabelPaddingLeft;
                     if (hasAnyTrackName) {
-                        this.accoladeWidth += settings.display.systemLabelPaddingLeft;
                         this.accoladeWidth += settings.display.systemLabelPaddingRight;
                     }
                 }
@@ -61497,6 +62081,7 @@ class StaffSystem {
             }
             let braceWidth = 0;
             for (const b of this._brackets) {
+                b.updateCanPaint();
                 b.finalizeBracket(settings.display.resources.engravingSettings);
                 braceWidth = Math.max(braceWidth, b.width);
             }
@@ -61504,6 +62089,12 @@ class StaffSystem {
             this.width += this.accoladeWidth;
             this.computedWidth += this.accoladeWidth;
         }
+        else {
+            for (const b of this._brackets) {
+                b.updateCanPaint();
+                b.finalizeBracket(settings.display.resources.engravingSettings);
+            }
+        }
     }
     _getStaffTrackGroup(track) {
         for (let i = 0, j = this.staves.length; i < j; i++) {
@@ -61533,12 +62124,12 @@ class StaffSystem {
                     break;
                 case BracketExtendMode.GroupStaves:
                     // when grouping staves, we create one bracket for the whole track across all staves
-                    bracket = new SingleTrackSystemBracket(track);
+                    bracket = new SingleTrackSystemBracket(this, track);
                     bracket.index = this._brackets.length;
                     this._brackets.push(bracket);
                     break;
                 case BracketExtendMode.GroupSimilarInstruments:
-                    bracket = new SimilarInstrumentSystemBracket(track);
+                    bracket = new SimilarInstrumentSystemBracket(this, track);
                     bracket.index = this._brackets.length;
                     this._brackets.push(bracket);
                     break;
@@ -61585,8 +62176,10 @@ class StaffSystem {
         }
     }
     paintPartial(cx, cy, canvas, startIndex, count) {
-        for (let i = 0, j = this.allStaves.length; i < j; i++) {
-            this.allStaves[i].paint(cx, cy, canvas, startIndex, count);
+        for (const s of this.allStaves) {
+            if (s.isVisible) {
+                s.paint(cx, cy, canvas, startIndex, count);
+            }
         }
         const res = this.layout.renderer.settings.display.resources;
         if (this.staves.length > 0 && startIndex === 0) {
@@ -61623,9 +62216,9 @@ class StaffSystem {
                     const oldBaseLine = canvas.textBaseline;
                     const oldTextAlign = canvas.textAlign;
                     for (const g of this.staves) {
-                        if (g.staves.length > 0) {
-                            const firstStart = cy + g.staves[0].contentTop;
-                            const lastEnd = cy + g.staves[g.staves.length - 1].contentBottom;
+                        if (g.firstVisibleStaff) {
+                            const firstStart = cy + g.firstVisibleStaff.contentTop;
+                            const lastEnd = cy + g.lastVisibleStaff.contentBottom;
                             let trackNameText = '';
                             switch (trackNameMode) {
                                 case TrackNameMode.FullName:
@@ -61679,6 +62272,9 @@ class StaffSystem {
             if (this.allStaves.length > 0 && needsSystemBarLine) {
                 let previousStaffInBracket = null;
                 for (const s of this.allStaves) {
+                    if (!s.isVisible) {
+                        continue;
+                    }
                     if (previousStaffInBracket !== null) {
                         const previousBottom = previousStaffInBracket.contentBottom;
                         const thisTop = s.contentTop;
@@ -61705,17 +62301,17 @@ class StaffSystem {
         const settings = this.layout.renderer.settings;
         for (const bracket of this._brackets) {
             if (bracket.canPaint) {
-                const barStartX = cx + bracket.firstStaffInBracket.x;
+                const barStartX = cx + bracket.firstVisibleStaffInBracket.x;
                 const barSize = bracket.width;
                 const barOffset = settings.display.accoladeBarPaddingRight;
-                const firstStart = cy + bracket.firstStaffInBracket.contentTop;
-                const lastEnd = cy + bracket.lastStaffInBracket.contentBottom;
+                const firstStart = cy + bracket.firstVisibleStaffInBracket.contentTop;
+                const lastEnd = cy + bracket.lastVisibleStaffInBracket.contentBottom;
                 let accoladeStart = firstStart;
                 let accoladeEnd = lastEnd;
                 if (bracket.drawAsBrace) {
                     CanvasHelper.fillMusicFontSymbolSafe(canvas, barStartX - barOffset - barSize, accoladeEnd, bracket.braceScale, MusicFontSymbol.Brace);
                 }
-                else if (bracket.firstStaffInBracket !== bracket.lastStaffInBracket) {
+                else if (bracket.firstVisibleStaffInBracket !== bracket.lastVisibleStaffInBracket) {
                     // brackets typically overflow by 1/4 staff-space
                     const smuflMetrics = settings.display.resources.engravingSettings;
                     const bracketOverflow = smuflMetrics.oneStaffSpace * 0.25;
@@ -61747,40 +62343,86 @@ class StaffSystem {
             this.bottomPadding = Math.max(this.bottomPadding, neededHeight);
             this._hasSystemSeparator = true;
         }
+        const anyStaffVisible = this._finalizeTrackGroups();
+        // for now we always force one staff to be visible.
+        // making also whole systems invisible needs separate attention (also on player cursor handling)
+        if (!anyStaffVisible) {
+            const group = this.staves[0];
+            const firstStaff = group.staves[0];
+            firstStaff.isVisible = true;
+            this._finalizeTrackGroups(true);
+        }
+        for (const b of this._brackets) {
+            b.finalizeBracket(settings.display.resources.engravingSettings);
+        }
+    }
+    _finalizeTrackGroups(onlyFirstGroup = false) {
         let currentY = 0;
+        const settings = this.layout.renderer.settings;
         const smufl = settings.display.resources.engravingSettings;
         const topBracketSpikeHeight = smufl.glyphHeights.get(MusicFontSymbol.BracketTop);
         const bottomBracketSpikeHeight = smufl.glyphHeights.get(MusicFontSymbol.BracketBottom);
         let previousStaff = undefined;
-        for (const staff of this.allStaves) {
-            // check if we need "in-between padding"
-            if (previousStaff !== undefined && previousStaff.trackIndex !== staff.trackIndex) {
-                currentY += settings.display.trackStaffPaddingBetween;
-            }
-            const bracket = this._staffToBracket.has(staff) ? this._staffToBracket.get(staff) : undefined;
-            const hasBracket = bracket && !bracket.drawAsBrace && bracket.canPaint;
-            if (hasBracket && bracket.firstStaffInBracket === staff) {
-                const spikeOverflow = topBracketSpikeHeight - staff.topOverflow;
-                if (spikeOverflow > 0) {
-                    currentY += spikeOverflow;
+        let endSpikeOverflow = 0;
+        let anyStaffVisible = false;
+        for (const group of this.staves) {
+            let firstVisibleStaffInGroup = undefined;
+            let lastVisibleStaffInGroup = undefined;
+            for (const staff of group.staves) {
+                // check if we need "in-between padding"
+                if (previousStaff !== undefined && previousStaff.trackIndex !== staff.trackIndex) {
+                    currentY += settings.display.trackStaffPaddingBetween;
+                }
+                const bracket = this._staffToBracket.has(staff) ? this._staffToBracket.get(staff) : undefined;
+                const hasBracket = bracket && !bracket.drawAsBrace && bracket.canPaint;
+                if (hasBracket && bracket.firstStaffInBracket === staff) {
+                    const spikeOverflow = topBracketSpikeHeight - staff.topOverflow;
+                    if (spikeOverflow > 0) {
+                        currentY += spikeOverflow;
+                    }
+                }
+                staff.x = this.accoladeWidth;
+                staff.y = currentY;
+                if (!onlyFirstGroup) {
+                    staff.finalizeStaff();
+                }
+                if (staff.isVisible) {
+                    currentY += staff.height;
+                    anyStaffVisible = true;
+                    previousStaff = staff;
+                    if (!firstVisibleStaffInGroup) {
+                        firstVisibleStaffInGroup = staff;
+                    }
+                    lastVisibleStaffInGroup = staff;
+                }
+                endSpikeOverflow = 0;
+                if (hasBracket && bracket.lastStaffInBracket === staff) {
+                    const spikeOverflow = bottomBracketSpikeHeight - staff.bottomOverflow;
+                    if (spikeOverflow > 0) {
+                        if (staff.isVisible) {
+                            currentY += spikeOverflow;
+                        }
+                        else {
+                            endSpikeOverflow = spikeOverflow;
+                        }
+                    }
                 }
             }
-            staff.x = this.accoladeWidth;
-            staff.y = currentY;
-            staff.finalizeStaff();
-            currentY += staff.height;
-            if (hasBracket && bracket.lastStaffInBracket === staff) {
-                const spikeOverflow = bottomBracketSpikeHeight - staff.bottomOverflow;
-                if (spikeOverflow > 0) {
-                    currentY += spikeOverflow;
-                }
+            group.firstVisibleStaff = firstVisibleStaffInGroup;
+            group.lastVisibleStaff = lastVisibleStaffInGroup;
+            if (!this.firstVisibleStaff) {
+                this.firstVisibleStaff = firstVisibleStaffInGroup;
+            }
+            if (onlyFirstGroup) {
+                break;
             }
-            previousStaff = staff;
         }
-        this._contentHeight = currentY;
-        for (const b of this._brackets) {
-            b.finalizeBracket(smufl);
+        // ensure we add overflow if last bracket is hidden
+        if (endSpikeOverflow) {
+            currentY += endSpikeOverflow;
         }
+        this._contentHeight = currentY;
+        return anyStaffVisible;
     }
     buildBoundingsLookup(cx, cy) {
         if (this.layout.renderer.boundsLookup.isFinished) {
@@ -61814,6 +62456,9 @@ class StaffSystem {
         const masterBarBoundsLookup = new Map();
         for (let i = 0; i < this.staves.length; i++) {
             for (const staff of this.staves[i].staves) {
+                if (!staff.isVisible) {
+                    continue;
+                }
                 for (const renderer of staff.barRenderers) {
                     let masterBarBounds;
                     if (!masterBarBoundsLookup.has(renderer.bar.masterBar.index)) {
@@ -62124,8 +62769,9 @@ class ScoreLayout {
     }
     firstBarIndex = 0;
     lastBarIndex = 0;
-    createEmptyStaffSystem() {
+    createEmptyStaffSystem(index) {
         const system = new StaffSystem(this);
+        system.index = index;
         const allFactories = Environment.defaultRenderers;
         const renderStaves = [];
         for (let trackIndex = 0; trackIndex < this.renderer.tracks.length; trackIndex++) {
@@ -62137,7 +62783,7 @@ class ScoreLayout {
                 let previousStaff = undefined;
                 for (const factory of allFactories) {
                     if (this.profile.has(factory.staffId) && factory.canCreate(track, staff)) {
-                        const renderStaff = new RenderStaff(trackIndex, staff, factory);
+                        const renderStaff = new RenderStaff(system, trackIndex, staff, factory);
                         // insert shared effect bands at front
                         renderStaff.topEffectInfos.splice(0, 0, ...sharedTopEffects);
                         renderStaff.bottomEffectInfos.push(...sharedBottomEffects);
@@ -65295,7 +65941,7 @@ class HorizontalScreenLayout extends ScoreLayout {
         }
         endBarIndex = startIndex + endBarIndex - 1; // map count to array index
         endBarIndex = Math.min(score.masterBars.length - 1, Math.max(0, endBarIndex));
-        this._system = this.createEmptyStaffSystem();
+        this._system = this.createEmptyStaffSystem(0);
         this._system.isLast = true;
         this._system.x = this.pagePadding[0];
         this._system.y = this.pagePadding[1];
@@ -65568,8 +66214,7 @@ class PageViewLayout extends ScoreLayout {
             this._systems = [];
             let currentIndex = 0;
             const maxWidth = this._maxWidth;
-            let system = this.createEmptyStaffSystem();
-            system.index = this._systems.length;
+            let system = this.createEmptyStaffSystem(this._systems.length);
             system.x = this.pagePadding[0];
             system.y = y;
             while (currentIndex < this._allMasterBarRenderers.length) {
@@ -65600,8 +66245,7 @@ class PageViewLayout extends ScoreLayout {
                     this._fitSystem(system);
                     y += this._paintSystem(system, oldHeight);
                     // note: we do not increase currentIndex here to have it added to the next system
-                    system = this.createEmptyStaffSystem();
-                    system.index = this._systems.length;
+                    system = this.createEmptyStaffSystem(this._systems.length);
                     system.x = this.pagePadding[0];
                     system.y = y;
                 }
@@ -65686,8 +66330,7 @@ class PageViewLayout extends ScoreLayout {
         return barsPerRow;
     }
     _createStaffSystem(currentBarIndex, endIndex) {
-        const system = this.createEmptyStaffSystem();
-        system.index = this._systems.length;
+        const system = this.createEmptyStaffSystem(this._systems.length);
         const barsPerRow = this._getBarsPerSystem(system.index);
         const maxWidth = this._maxWidth;
         const end = endIndex + 1;
@@ -68367,16 +69010,77 @@ class NumberedBarRendererFactory extends BarRendererFactory {
 class ClefGlyph extends MusicFontGlyph {
     _clef;
     _clefOttava;
+    _ottavaGlyph;
     constructor(x, y, clef, clefOttava) {
         super(x, y, 1, ClefGlyph._getSymbol(clef, clefOttava));
         this._clef = clef;
         this._clefOttava = clefOttava;
     }
+    getBoundingBoxTop() {
+        let top = super.getBoundingBoxTop();
+        const ottava = this._ottavaGlyph;
+        if (ottava) {
+            const ottavaTop = this.y + ottava.getBoundingBoxTop();
+            top = ModelUtils.minBoundingBox(top, ottavaTop);
+        }
+        return top;
+    }
+    getBoundingBoxBottom() {
+        let bottom = super.getBoundingBoxBottom();
+        const ottava = this._ottavaGlyph;
+        if (ottava) {
+            const ottavaBottom = this.y + ottava.getBoundingBoxBottom();
+            bottom = ModelUtils.maxBoundingBox(bottom, ottavaBottom);
+        }
+        return bottom;
+    }
     doLayout() {
         this.center = true;
         super.doLayout();
         this.width = this.renderer.smuflMetrics.glyphWidths.get(MusicFontSymbol.GClef);
         this.offsetX = this.width / 2;
+        this._ottavaGlyph = undefined;
+        switch (this._clef) {
+            case Clef.C3:
+            case Clef.C4:
+                switch (this._clefOttava) {
+                    case Ottavia._8vb:
+                        return;
+                }
+                break;
+            case Clef.F4:
+            case Clef.G2:
+                return;
+        }
+        let ottavaSymbol;
+        let top = false;
+        switch (this._clefOttava) {
+            case Ottavia._15ma:
+                ottavaSymbol = MusicFontSymbol.Clef15;
+                top = true;
+                break;
+            case Ottavia._8va:
+                ottavaSymbol = MusicFontSymbol.Clef8;
+                top = true;
+                break;
+            case Ottavia._8vb:
+                ottavaSymbol = MusicFontSymbol.Clef8;
+                break;
+            case Ottavia._15mb:
+                ottavaSymbol = MusicFontSymbol.Clef15;
+                break;
+            default:
+                return;
+        }
+        const ottavaX = this.width / 2;
+        const ottavaY = top
+            ? this.renderer.smuflMetrics.glyphTop.get(this.symbol)
+            : this.renderer.smuflMetrics.glyphBottom.get(this.symbol) -
+                this.renderer.smuflMetrics.glyphHeights.get(ottavaSymbol);
+        this._ottavaGlyph = new MusicFontGlyph(ottavaX, -ottavaY, 1, ottavaSymbol);
+        this._ottavaGlyph.center = true;
+        this._ottavaGlyph.renderer = this.renderer;
+        this._ottavaGlyph.doLayout();
     }
     static _getSymbol(clef, clefOttava) {
         switch (clef) {
@@ -68424,44 +69128,10 @@ class ClefGlyph extends MusicFontGlyph {
         const _ = ElementStyleHelper.bar(canvas, BarSubElement.StandardNotationClef, this.renderer.bar);
         try {
             super.paint(cx, cy, canvas);
-            switch (this._clef) {
-                case Clef.C3:
-                case Clef.C4:
-                    switch (this._clefOttava) {
-                        case Ottavia._8vb:
-                            return;
-                    }
-                    break;
-                case Clef.F4:
-                case Clef.G2:
-                    return;
-            }
-            let ottavaGlyph;
-            let top = false;
-            switch (this._clefOttava) {
-                case Ottavia._15ma:
-                    ottavaGlyph = MusicFontSymbol.Clef15;
-                    top = true;
-                    break;
-                case Ottavia._8va:
-                    ottavaGlyph = MusicFontSymbol.Clef8;
-                    top = true;
-                    break;
-                case Ottavia._8vb:
-                    ottavaGlyph = MusicFontSymbol.Clef8;
-                    break;
-                case Ottavia._15mb:
-                    ottavaGlyph = MusicFontSymbol.Clef15;
-                    break;
-                default:
-                    return;
+            const ottava = this._ottavaGlyph;
+            if (ottava) {
+                ottava.paint(cx + this.x, cy + this.y, canvas);
             }
-            const ottavaX = this.width / 2;
-            const ottavaY = top
-                ? this.renderer.smuflMetrics.glyphTop.get(this.symbol)
-                : this.renderer.smuflMetrics.glyphBottom.get(this.symbol) -
-                    this.renderer.smuflMetrics.glyphHeights.get(ottavaGlyph);
-            CanvasHelper.fillMusicFontSymbolSafe(canvas, cx + this.x + ottavaX, cy + this.y - ottavaY, 1, ottavaGlyph, true);
         }
         finally {
             _?.[Symbol.dispose]?.();