@coderline/alphatab 1.9.0-alpha.1860 → 1.9.0-alpha.1869

package/dist/alphaTab.js

@@ -1,5 +1,5 @@
 /*!
-* alphaTab v1.9.0-alpha.1860 (develop, build 1860)
+* alphaTab v1.9.0-alpha.1869 (develop, build 1869)
 *
 * Copyright © 2026, Daniel Kuschny and Contributors, All rights reserved.
 *
@@ -190,9 +190,9 @@
 	* @internal
 	*/
 	var VersionInfo = class VersionInfo {
-		static version = "1.9.0-alpha.1860";
-		static date = "2026-07-10T14:22:26.590Z";
-		static commit = "1efc2ecc10ca13f2bfbec400427822dc4bdfc160";
+		static version = "1.9.0-alpha.1869";
+		static date = "2026-07-19T03:42:49.478Z";
+		static commit = "2889cac4e359a41b6f24a82034e6f6ba4f9f4c4f";
 		static print(print) {
 			print(`alphaTab ${VersionInfo.version}`);
 			print(`commit: ${VersionInfo.commit}`);
@@ -29201,11 +29201,45 @@
 		* @since 0.9.7
 		* @defaultValue `true`
 		* @category Player
+		* @json_read_only
 		* @remarks
 		* This setting configures whether alphaTab provides the default user interaction features like selection of the playback range and "seek on click".
 		* By default users can select the desired playback range with the mouse and also jump to individual beats by click. This behavior can be contolled with this setting.
+		* @deprecated Use {@link enableSeekToClick} and {@link enablePlaybackRangeSelection} individually
+		*/
+		get enableUserInteraction() {
+			return this.enableSeekToClick || this.enablePlaybackRangeSelection;
+		}
+		/**
+		* @deprecated Use {@link enableSeekToClick} and {@link enablePlaybackRangeSelection} individually
+		*/
+		set enableUserInteraction(value) {
+			this.enableSeekToClick = value;
+			this.enablePlaybackRangeSelection = value;
+			this.resetPlaybackRangeOnClick = value;
+		}
+		/**
+		* Whether the a click on the music sheet triggers a player seek to the note/beat at the
+		* clicked location.
+		* @since 1.9.0
+		* @defaultValue `true`
+		* @category Player
+		*/
+		enableSeekToClick = true;
+		/**
+		* Whether user click and drag results in a selection defining the playback range.
+		* @since 1.9.0
+		* @defaultValue `true`
+		* @category Player
 		*/
-		enableUserInteraction = true;
+		enablePlaybackRangeSelection = true;
+		/**
+		* Whether a simple click (no range drag) should reset the current playback range.
+		* @since 1.9.0
+		* @defaultValue `true`
+		* @category Player
+		*/
+		resetPlaybackRangeOnClick = true;
 		/**
 		* The X-offset to add when scrolling.
 		* @since 0.9.6
@@ -30362,7 +30396,9 @@
 			o.set("enablecursor", obj.enableCursor);
 			o.set("enableanimatedbeatcursor", obj.enableAnimatedBeatCursor);
 			o.set("enableelementhighlighting", obj.enableElementHighlighting);
-			o.set("enableuserinteraction", obj.enableUserInteraction);
+			o.set("enableseektoclick", obj.enableSeekToClick);
+			o.set("enableplaybackrangeselection", obj.enablePlaybackRangeSelection);
+			o.set("resetplaybackrangeonclick", obj.resetPlaybackRangeOnClick);
 			o.set("scrolloffsetx", obj.scrollOffsetX);
 			o.set("scrolloffsety", obj.scrollOffsetY);
 			o.set("scrollmode", obj.scrollMode);
@@ -30405,6 +30441,15 @@
 				case "enableuserinteraction":
 					obj.enableUserInteraction = v;
 					return true;
+				case "enableseektoclick":
+					obj.enableSeekToClick = v;
+					return true;
+				case "enableplaybackrangeselection":
+					obj.enablePlaybackRangeSelection = v;
+					return true;
+				case "resetplaybackrangeonclick":
+					obj.resetPlaybackRangeOnClick = v;
+					return true;
 				case "scrolloffsetx":
 					obj.scrollOffsetX = v;
 					return true;
@@ -45403,6 +45448,16 @@
 		scaleToWidth(beatWidth) {
 			this.width = beatWidth;
 		}
+		/**
+		* Repositions this beat so its {@link onTimeX} anchor lands at `target`, used for the
+		* centered full-bar note/rest (see {@link BarLayoutingInfo.isCenteredFullBar}). The default
+		* shifts the whole container, matching the regular (non-centered) positioning formula.
+		* {@link BeatContainerGlyph} overrides this to shift only its ink, keeping `x`/`width`
+		* spanning the full bar so bounds lookups and skyline emission stay correct.
+		*/
+		applyCenterOffset(target) {
+			this.x = target - this.onTimeX;
+		}
 	};
 	/**
 	* @internal
@@ -45506,13 +45561,28 @@
 			this.preNotes.renderer = this.renderer;
 			this.preNotes.container = this;
 			this.preNotes.doLayout();
-			this.onNotes.x = this.preNotes.x + this.preNotes.width;
+			this._layoutOnsetX();
 			this.onNotes.renderer = this.renderer;
 			this.onNotes.container = this;
 			this.onNotes.doLayout();
 			this.createBeatTies();
 			this.updateWidth();
 		}
+		/**
+		* Resets `preNotes.x`/`onNotes.x` to their natural (un-centered) baseline.
+		* Shared by {@link doLayout} and {@link applyCenterOffset} so the latter can be called
+		* repeatedly (once per `_scaleToForce` pass) without compounding a previous offset.
+		*/
+		_layoutOnsetX() {
+			this.preNotes.x = 0;
+			this.onNotes.x = this.preNotes.x + this.preNotes.width;
+		}
+		applyCenterOffset(target) {
+			this._layoutOnsetX();
+			const offset = target - this.onTimeX;
+			this.preNotes.x = offset;
+			this.onNotes.x = this.preNotes.x + this.preNotes.width;
+		}
 		createBeatTies() {
 			let i = this.beat.notes.length - 1;
 			while (i >= 0) this.createTies(this.beat.notes[i--]);
@@ -48134,6 +48204,7 @@
 			if (currentHandler !== void 0 && this._cursorHandlerMode === cursorHandlerMode) return;
 			if (cursorHandlerMode) this._defaultCursorHandler = new ToNextBeatAnimatingCursorHandler();
 			else this._defaultCursorHandler = new NonAnimatingCursorHandler();
+			this._cursorHandlerMode = cursorHandlerMode;
 		}
 		_scrollHandlerMode = ScrollMode.Off;
 		_scrollHandlerVertical = true;
@@ -48263,10 +48334,8 @@
 				shouldScroll = !stop;
 				shouldNotifyBeatChange = true;
 			}
-			if (shouldScroll && !this._isBeatMouseDown && this.settings.player.scrollMode !== ScrollMode.Off) {
-				const handler = this.customScrollHandler ?? this._defaultScrollHandler;
-				if (handler) handler.onBeatCursorUpdating(beatBoundings, nextBeatBoundings === null ? void 0 : nextBeatBoundings, cursorMode, startBeatX, nextBeatX, duration);
-			}
+			const handler = this.customScrollHandler ?? this._defaultScrollHandler;
+			if (shouldScroll && !this._isBeatMouseDown && handler) handler.onBeatCursorUpdating(beatBoundings, nextBeatBoundings === null ? void 0 : nextBeatBoundings, cursorMode, startBeatX, nextBeatX, duration);
 			if (shouldNotifyBeatChange) {
 				this._onPlayedBeatChanged(beat);
 				this._onActiveBeatsChanged(new ActiveBeatsChangedEventArgs(beatsToHighlight.map((i) => i.beat)));
@@ -48602,7 +48671,7 @@
 		}
 		_onBeatMouseDown(originalEvent, beat) {
 			if (this._isDestroyed) return;
-			if (this._hasCursor && this.settings.player.enableUserInteraction) {
+			if (this._hasCursor && this.settings.player.enablePlaybackRangeSelection) {
 				this._selectionStart = { beat };
 				this._selectionEnd = void 0;
 			}
@@ -48618,10 +48687,12 @@
 		}
 		_onBeatMouseMove(originalEvent, beat) {
 			if (this._isDestroyed) return;
-			if (this.settings.player.enableUserInteraction) {
+			if (this.settings.player.enablePlaybackRangeSelection) {
 				if (!this._selectionEnd || this._selectionEnd.beat !== beat) {
-					this._selectionEnd = { beat };
-					this._cursorSelectRange(this._selectionStart, this._selectionEnd);
+					if (this._selectionStart?.beat !== beat) {
+						this._selectionEnd = { beat };
+						this._cursorSelectRange(this._selectionStart, this._selectionEnd);
+					}
 				}
 			}
 			this.beatMouseMove.trigger(beat);
@@ -48634,11 +48705,30 @@
 		}
 		_onBeatMouseUp(originalEvent, beat) {
 			if (this._isDestroyed) return;
-			if (this._hasCursor && this.settings.player.enableUserInteraction) this.applyPlaybackRangeFromHighlight();
+			if (this._hasCursor) {
+				let shouldSeekToBeat = beat && this.settings.player.enableSeekToClick;
+				if (this.settings.player.enablePlaybackRangeSelection) {
+					if (this._internalApplyPlaybackRangeFromHighlight()) shouldSeekToBeat = false;
+				}
+				if (shouldSeekToBeat) this._seekToBeat(beat);
+			}
 			this.beatMouseUp.trigger(beat);
 			this.uiFacade.triggerEvent(this.container, "beatMouseUp", beat, originalEvent);
 			this._isBeatMouseDown = false;
 		}
+		_seekToBeat(beat) {
+			const tickCache = this._tickCache;
+			if (!tickCache) return;
+			this._currentBeat = null;
+			let beatTick = tickCache.getMasterBarStart(beat.voice.bar.masterBar) + (tickCache.getRelativeBeatPlaybackRange(beat)?.startTick ?? beat.playbackStart);
+			const playbackRange = this.playbackRange;
+			if (playbackRange) {
+				if (beatTick < playbackRange.startTick) beatTick = playbackRange.startTick;
+				else if (beatTick > playbackRange.endTick) beatTick = playbackRange.endTick;
+			}
+			if (this._player.state === PlayerState.Paused) this._cursorUpdateTick(beatTick, false, 1);
+			this.tickPosition = beatTick;
+		}
 		_onNoteMouseUp(originalEvent, note) {
 			if (this._isDestroyed) return;
 			this.noteMouseUp.trigger(note);
@@ -48660,7 +48750,7 @@
 		_setupClickHandling() {
 			this.canvasElement.mouseDown.on((e) => {
 				if (!e.isLeftMouseButton) return;
-				if (this.settings.player.enableUserInteraction) e.preventDefault();
+				if (this.settings.player.enablePlaybackRangeSelection || this.settings.player.enableSeekToClick) e.preventDefault();
 				const relX = e.getX(this.canvasElement);
 				const relY = e.getY(this.canvasElement);
 				const beat = this._renderer.boundsLookup?.getBeatAtPos(relX, relY) ?? null;
@@ -48687,7 +48777,7 @@
 			});
 			this.canvasElement.mouseUp.on((e) => {
 				if (!this._isBeatMouseDown) return;
-				if (this.settings.player.enableUserInteraction) e.preventDefault();
+				if (this.settings.player.enablePlaybackRangeSelection || this.settings.player.enableSeekToClick) e.preventDefault();
 				const relX = e.getX(this.canvasElement);
 				const relY = e.getY(this.canvasElement);
 				const beat = this._renderer.boundsLookup?.getBeatAtPos(relX, relY) ?? null;
@@ -48698,7 +48788,7 @@
 				} else this._onNoteMouseUp(e, null);
 			});
 			this._renderer.postRenderFinished.on(() => {
-				if (!this._selectionStart || !this._hasCursor || !this.settings.player.enableUserInteraction) return;
+				if (!this._selectionStart || !this._hasCursor || !this.settings.player.enablePlaybackRangeSelection) return;
 				this._cursorSelectRange(this._selectionStart, this._selectionEnd);
 			});
 		}
@@ -48790,6 +48880,9 @@
 		* ```
 		*/
 		applyPlaybackRangeFromHighlight() {
+			this._internalApplyPlaybackRangeFromHighlight();
+		}
+		_internalApplyPlaybackRangeFromHighlight() {
 			if (this._selectionEnd) {
 				const startTick = this._tickCache?.getBeatStart(this._selectionStart.beat) ?? this._selectionStart.beat.absolutePlaybackStart;
 				if ((this._tickCache?.getBeatStart(this._selectionEnd.beat) ?? this._selectionEnd.beat.absolutePlaybackStart) < startTick) {
@@ -48797,27 +48890,32 @@
 					this._selectionStart = this._selectionEnd;
 					this._selectionEnd = t;
 				}
-			}
+			} else if (!this.settings.player.resetPlaybackRangeOnClick) return false;
 			if (this._selectionStart && this._tickCache) {
 				const tickCache = this._tickCache;
 				const realStartMasterBarStart = tickCache.getMasterBarStart(this._selectionStart.beat.voice.bar.masterBar);
 				const startBeatPlaybackStart = tickCache.getRelativeBeatPlaybackRange(this._selectionStart.beat)?.startTick ?? this._selectionStart.beat.playbackStart;
-				this._currentBeat = null;
-				if (this._player.state === PlayerState.Paused) this._cursorUpdateTick(realStartMasterBarStart + startBeatPlaybackStart, false, 1);
-				this.tickPosition = realStartMasterBarStart + startBeatPlaybackStart;
+				let seekToStart = this.settings.player.enableSeekToClick;
 				if (this._selectionEnd && this._selectionStart.beat !== this._selectionEnd.beat) {
+					seekToStart = true;
 					const realEndMasterBarStart = tickCache.getMasterBarStart(this._selectionEnd.beat.voice.bar.masterBar);
 					const endBeatPlaybackEnd = tickCache.getRelativeBeatPlaybackRange(this._selectionEnd.beat)?.endTick ?? this._selectionEnd.beat.playbackStart + this._selectionEnd.beat.playbackDuration;
 					const range = new PlaybackRange();
 					range.startTick = realStartMasterBarStart + startBeatPlaybackStart;
 					range.endTick = realEndMasterBarStart + endBeatPlaybackEnd - 50;
 					this.playbackRange = range;
-				} else {
+				} else if (this.settings.player.resetPlaybackRangeOnClick) {
 					this._selectionStart = void 0;
 					this.playbackRange = null;
 					this._cursorSelectRange(this._selectionStart, this._selectionEnd);
 				}
+				if (seekToStart) {
+					this._currentBeat = null;
+					if (this._player.state === PlayerState.Paused) this._cursorUpdateTick(realStartMasterBarStart + startBeatPlaybackStart, false, 1);
+					this.tickPosition = realStartMasterBarStart + startBeatPlaybackStart;
+				}
 			}
+			return true;
 		}
 		/**
 		* Clears the highlight markers marking the currently selected playback range.
@@ -50103,7 +50201,8 @@
 			settings.player.enableCursor = false;
 			settings.player.playerMode = PlayerMode.Disabled;
 			settings.player.enableElementHighlighting = false;
-			settings.player.enableUserInteraction = false;
+			settings.player.enableSeekToClick = false;
+			settings.player.enablePlaybackRangeSelection = false;
 			settings.player.soundFont = null;
 			settings.display.scale = .8;
 			settings.display.stretchForce = .8;
@@ -50913,7 +51012,9 @@
 		}
 		handleMessage(e) {
 			const data = e.data;
-			switch (data.cmd) {
+			const cmd = data.cmd;
+			if (!cmd) return;
+			switch (cmd) {
 				case "alphaSynth.initialize":
 					AlphaSynthWorkerSynthOutput.preferredSampleRate = data.sampleRate;
 					Logger.logLevel = data.logLevel;
@@ -51007,7 +51108,7 @@
 					this._player.applyTranspositionPitches(data.transpositionPitches);
 					break;
 			}
-			if (data.cmd.startsWith("alphaSynth.exporter")) this._handleExporterMessage(e);
+			if (cmd.startsWith("alphaSynth.exporter")) this._handleExporterMessage(e);
 		}
 		_handleExporterMessage(ev) {
 			const data = ev.data;
@@ -54511,9 +54612,35 @@
 			const force = this.renderer.layoutingInfo.spaceToForce(width);
 			this._scaleToForce(force, true);
 		}
+		/**
+		* `true` when every voice/track/staff contributes exactly one beat, of uniform duration,
+		* spanning the bar's entire duration - i.e. a single full-bar note/rest. Common engraving
+		* practice centers such notes horizontally within the bar rather than anchoring them right
+		* after the pre-beat content (Behind Bars, p. 41; see #2464).
+		*/
+		_isCenteredFullBar() {
+			const masterBar = this.renderer.bar.masterBar;
+			const layoutingInfo = this.renderer.layoutingInfo;
+			const springs = layoutingInfo.springs;
+			if (springs.size !== 1 || !springs.has(masterBar.start) || layoutingInfo.allGraceRods.size > 0) return false;
+			const spring = springs.get(masterBar.start);
+			return spring.allDurations.size === 1 && spring.longestDuration === masterBar.calculateDuration();
+		}
 		/** `emit=false`: positioning-only path; final skyline emission runs later via {@link scaleToWidth}. */
 		_scaleToForce(force, emit) {
 			this.width = this.renderer.layoutingInfo.calculateVoiceWidth(force);
+			if (this._isCenteredFullBar()) {
+				const barNumberWidth = this.renderer.barNumberWidth;
+				const target = (this.width - barNumberWidth) / 2;
+				for (const beatGlyphs of this.beatGlyphs.values()) {
+					const soleBeatGlyph = beatGlyphs[0];
+					soleBeatGlyph.x = 0;
+					soleBeatGlyph.applyCenterOffset(target);
+					soleBeatGlyph.scaleToWidth(this.width);
+					if (emit) this._emitBeatContainerSkyline(soleBeatGlyph);
+				}
+				return;
+			}
 			const positions = this.renderer.layoutingInfo.buildOnTimePositions(force);
 			for (const beatGlyphs of this.beatGlyphs.values()) for (let i = 0, j = beatGlyphs.length; i < j; i++) {
 				const currentBeatGlyph = beatGlyphs[i];
@@ -60835,14 +60962,22 @@
 		calculateBeamY(h, x) {
 			return this.calculateBeamYWithDirection(h, x, this.getBeamDirection(h));
 		}
+		barNumberGlyph;
+		get barNumberWidth() {
+			return this.barNumberGlyph?.width ?? 0;
+		}
 		createPreBeatGlyphs() {
 			super.createPreBeatGlyphs();
+			this.barNumberGlyph = void 0;
 			this.addPreBeatGlyph(new BarLineGlyph(false, this.bar.staff.track.score.stylesheet.extendBarLines));
 			this.createLinePreBeatGlyphs();
 			let hasSpaceAfterStartGlyphs = false;
 			if (this.index === 0) hasSpaceAfterStartGlyphs = this.createStartSpacing();
-			if (this.shouldCreateBarNumber()) this.addPreBeatGlyph(new BarNumberGlyph(0, this.getLineHeight(-.5), this.bar.index + 1));
-			else if (!hasSpaceAfterStartGlyphs) this.addPreBeatGlyph(new SpacingGlyph(0, 0, this.smuflMetrics.oneStaffSpace));
+			if (this.shouldCreateBarNumber()) {
+				const barNumberGlyph = new BarNumberGlyph(0, this.getLineHeight(-.5), this.bar.index + 1);
+				this.barNumberGlyph = barNumberGlyph;
+				this.addPreBeatGlyph(barNumberGlyph);
+			} else if (!hasSpaceAfterStartGlyphs) this.addPreBeatGlyph(new SpacingGlyph(0, 0, this.smuflMetrics.oneStaffSpace));
 		}
 		resolveClefDisplay() {
 			return { isVisible: false };
@@ -64434,8 +64569,11 @@
 			if (this.index === 0 || this.bar.masterBar.isRepeatStart && this.staff.isCascadePrimary) this.addPreBeatGlyph(new BarLineGlyph(false, this.bar.staff.track.score.stylesheet.extendBarLines));
 			this.createLinePreBeatGlyphs();
 			const hasSpaceAfterStartGlyphs = this.createStartSpacing();
-			if (this.shouldCreateBarNumber()) this.addPreBeatGlyph(new BarNumberGlyph(0, this.getLineHeight(-.5), this.bar.index + 1));
-			else if (!hasSpaceAfterStartGlyphs) this.addPreBeatGlyph(new SpacingGlyph(0, 0, this.smuflMetrics.oneStaffSpace));
+			if (this.shouldCreateBarNumber()) {
+				const barNumberGlyph = new BarNumberGlyph(0, this.getLineHeight(-.5), this.bar.index + 1);
+				this.barNumberGlyph = barNumberGlyph;
+				this.addPreBeatGlyph(barNumberGlyph);
+			} else if (!hasSpaceAfterStartGlyphs) this.addPreBeatGlyph(new SpacingGlyph(0, 0, this.smuflMetrics.oneStaffSpace));
 		}
 		createLinePreBeatGlyphs() {
 			const timeSignatureDisplay = this.resolveTimeSignatureDisplay();