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

package/dist/alphaTab.core.mjs

@@ -1,5 +1,5 @@
 /*!
-* alphaTab v1.9.0-alpha.1860 (develop, build 1860)
+* alphaTab v1.9.0-alpha.1861 (develop, build 1861)
 *
 * Copyright © 2026, Daniel Kuschny and Contributors, All rights reserved.
 *
@@ -186,9 +186,9 @@ class AlphaTabError extends Error {
 * @internal
 */
 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.1861";
+	static date = "2026-07-11T03:34:14.452Z";
+	static commit = "18845390986e826fff8ae285ee3630080dbd6653";
 	static print(print) {
 		print(`alphaTab ${VersionInfo.version}`);
 		print(`commit: ${VersionInfo.commit}`);
@@ -29197,11 +29197,45 @@ class PlayerSettings {
 	* @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
@@ -30358,7 +30392,9 @@ class PlayerSettingsSerializer {
 		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);
@@ -30401,6 +30437,15 @@ class PlayerSettingsSerializer {
 			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;
@@ -45399,6 +45444,16 @@ class BeatContainerGlyphBase extends Glyph {
 	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
@@ -45502,13 +45557,28 @@ class BeatContainerGlyph extends BeatContainerGlyphBase {
 		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--]);
@@ -48598,7 +48668,7 @@ class AlphaTabApiBase {
 	}
 	_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;
 		}
@@ -48614,10 +48684,12 @@ class AlphaTabApiBase {
 	}
 	_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);
@@ -48630,11 +48702,30 @@ class AlphaTabApiBase {
 	}
 	_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);
@@ -48656,7 +48747,7 @@ class AlphaTabApiBase {
 	_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;
@@ -48683,7 +48774,7 @@ class AlphaTabApiBase {
 		});
 		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;
@@ -48694,7 +48785,7 @@ class AlphaTabApiBase {
 			} 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);
 		});
 	}
@@ -48786,6 +48877,9 @@ class AlphaTabApiBase {
 	* ```
 	*/
 	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) {
@@ -48793,27 +48887,32 @@ class AlphaTabApiBase {
 				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.
@@ -50099,7 +50198,8 @@ class AlphaTabApi extends AlphaTabApiBase {
 		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;
@@ -50909,7 +51009,9 @@ class AlphaSynthWebWorker {
 	}
 	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;
@@ -51003,7 +51105,7 @@ class AlphaSynthWebWorker {
 				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;
@@ -54507,9 +54609,35 @@ class MultiVoiceContainerGlyph extends Glyph {
 		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];
@@ -60831,14 +60959,22 @@ class LineBarRenderer extends BarRendererBase {
 	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 };
@@ -64430,8 +64566,11 @@ class NumberedBarRenderer extends LineBarRenderer {
 		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();

package/dist/alphaTab.d.ts

@@ -2083,6 +2083,7 @@ export declare class AlphaTabApiBase<TSettings> {
     private _onBeatMouseMove;
     private _onNoteMouseMove;
     private _onBeatMouseUp;
+    private _seekToBeat;
     private _onNoteMouseUp;
     private _updateSelectionCursor;
     private _setupClickHandling;
@@ -2170,6 +2171,7 @@ export declare class AlphaTabApiBase<TSettings> {
      * ```
      */
     applyPlaybackRangeFromHighlight(): void;
+    private _internalApplyPlaybackRangeFromHighlight;
     /**
      * Clears the highlight markers marking the currently selected playback range.
      *
@@ -13996,11 +13998,39 @@ export declare class PlayerSettings {
      * @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(): boolean;
+    /**
+     * @deprecated Use {@link enableSeekToClick} and {@link enablePlaybackRangeSelection} individually
+     */
+    set enableUserInteraction(value: boolean);
+    /**
+     * 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: boolean;
+    /**
+     * Whether user click and drag results in a selection defining the playback range.
+     * @since 1.9.0
+     * @defaultValue `true`
+     * @category Player
+     */
+    enablePlaybackRangeSelection: boolean;
+    /**
+     * Whether a simple click (no range drag) should reset the current playback range.
+     * @since 1.9.0
+     * @defaultValue `true`
+     * @category Player
      */
-    enableUserInteraction: boolean;
+    resetPlaybackRangeOnClick: boolean;
     /**
      * The X-offset to add when scrolling.
      * @since 0.9.6
@@ -14268,11 +14298,35 @@ declare interface PlayerSettingsJson {
      * @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
      */
     enableUserInteraction?: boolean;
+    /**
+     * 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?: boolean;
+    /**
+     * Whether user click and drag results in a selection defining the playback range.
+     * @since 1.9.0
+     * @defaultValue `true`
+     * @category Player
+     */
+    enablePlaybackRangeSelection?: boolean;
+    /**
+     * Whether a simple click (no range drag) should reset the current playback range.
+     * @since 1.9.0
+     * @defaultValue `true`
+     * @category Player
+     */
+    resetPlaybackRangeOnClick?: boolean;
     /**
      * The X-offset to add when scrolling.
      * @since 0.9.6