[Danielku15]

Note

AI-authored disclosure (alphatab-ai-authored-v1)

Portions of this content were authored by an AI agent. The agent has read
AGENTS.md and the human submitter accepts responsibility for
compliance with the rules in that document.

Issues

No dedicated issue: part of the 1.9 release preparation.

Proposed changes

Problem. A resize produced a different layout than a fresh render at the same width. Across 2,725 test
cases (109 scores × 5 variations × 5 widths), 40 % differed:

• forced line breaks moved one bar early;
• bar widths shifted by up to 0.5 px;
• system heights and the final barline moved.

Layout and resize were also slow and allocation-heavy. On large scores, every step of a window drag allocated about 45 MB.

What changes. The page/parchment layout is now one flow:

• each bar is measured once;
• the system breaks are decided before bars are added;
• systems are assembled once and reused on resize.

Around that flow, rendering, the browser worker hand-off, the player and the serializers were reworked to avoid
work and allocations nobody needs.

Most of the bug fixes below came out of the resize-vs-fresh comparison and the visual review of the new output.

Layout and resize

• One rule decides which bars fit a system, for the initial layout, resizes and partial updates alike.
  Forced line breaks stay on their bar, and a resize gives the same result as a fresh render at that width.
  This holds in all 2,725 comparison cases (line breaks, bar widths, system heights, glyph positions and bounds).
• Justified bar widths survive the finalize step, and overflows are re-derived per layout pass. Before, they only
  ever grew, so the result depended on the resize history.
• Page and parchment spacing use one duration reference per layout instead of a per-system one. Bar widths no
  longer depend on the neighbouring bars of the system.
• Resizes reuse systems, staves, skylines and effect placements. Glyph, beaming, skyline, tie and bounds data
  avoid per-layout allocations.
• Fixed widths that changed between passes: whammy helper notes, bend helper note heads, and tab note geometry
  that changed when painted. The whammy and stale bend-overflow cases are also present on develop today.

Rendering output (reference images updated in the last commit)

• Numbered notation: rests longer than a quarter repeat 0 (0 0, 0 0 0 0) instead of the dashes of held notes.
• Colours: voice colours now reach stems, beams, flags, tuplets, effects, slur continuations and multi-note tab
  bends. null style entries reset score elements, track names and the header tuning to their own defaults. The
  system separator uses the main glyph colour by default. Bar styles without a staff-line entry use the default
  staff-line colour.
• The bend labels of several bent notes on one beat are merged and stacked instead of drawn over each other.
• Bend and whammy outlines claim less space (placements move by ≤ 0.8 px), and the empty space in front of bend
  helper accidentals is gone.
• Staff lines are painted once per run of bars.
• SVG output: no newlines between elements, black rects without a fill attribute, single music symbols end
  with ; (valid XML), and Kotlin writes symbol codes as integers.

Browser, worker and player

• The worker sends the bounds lookup as a transferable Float64Array instead of a nested Map tree.
• Scores go to the worker as one transferred MessagePack buffer instead of a structured-cloned object tree. Generated
  numeric field ids keep it at 1.6 MB for the dense test score; with string keys it would be 8.7 MB. Errors while
  the worker reads a score now reach api.error.
• Resizes are coalesced while one is in flight. Intermediate widths during a drag raise no render events; this is
  documented on IScoreRenderer.resizeRender.
• Partials far out of view release their DOM and render again when they come back. Before, the whole rendered
  sheet stayed in memory after one scroll through it. Beat highlights survive that re-render.
• The midi is generated once per score load and player change, instead of up to four times. With a worker
  renderer the score is posted for rendering before its midi is generated.
• New setting player.positionUpdateIntervalInMilliseconds, default 10 ms: the audio worklet reports the position
  every 10 ms instead of every 128-frame quantum. 0 restores the previous behaviour.
• destroy() releases the loaded model. Painted partials are no longer retained in the lazy-partial store.

Model, importers, platform and build

• Guitar Pro 3–5: drum grace notes are read as percussion notes, the note duration percent is read little-endian
  (canon.gp5 and five other files had broken values), and notes without fingering get "unknown finger".
• An alphaTex round trip keeps empty Guitar Pro voices, their dynamics and the GP7–8 drum note strings stable.
• JsonConverter accepts null colours and fonts, reads fonts from plain JSON objects and writes typed arrays as
  JSON arrays.
• The horizontal layout builds its bounds lookup once instead of once per partial; before, findBeats returned
  every beat once per partial. A partial render that falls back to a full layout no longer duplicates systems in
  the lookup.
• New log level LogLevel.Trace (Logger.trace). Internal flow details moved from debug to trace. Trace calls are
  stripped from the library builds.
• Library builds inline enum member reads across modules (−10 KB gzip on the minified core). keep_quoted makes
  Ottavia._8va and the other underscore members defined again in the minified bundles.
• The webpack plugin no longer hangs the build when it cannot copy its assets; it reports the error instead.
• Platform fixes: the IntersectionObserver polyfill now checks on scroll/resize, GDI/Android skip zero-width rects,
  Kotlin List.splice returns only the removed elements, Android map/set deletes compare keys, and .NET/Android
  parse numbers like JavaScript parseInt (via the platform parsers).

Measured result (dense test score, 216 bars × 20 staves, all tracks)

	develop	this PR	change
Initial render (Node, svg: layout + paint)	200 ms	105 ms	−47 %
Resize 1300 → 800 px / 800 → 1300 px	63 / 55 ms	24 / 21 ms	−63 % / −60 %
Allocated per initial render	233 MB	114 MB	−51 %
Allocated per resize	58 / 48 MB	19 / 12 MB	−67 % / −74 %
Heap kept by a finished renderer	152 MB	53 MB	−65 %
Chromium renderer memory after scrolling through the score (PSS)	410 MB	256 MB	−38 %
Worker heap in Chromium	81–91 MB	40–44 MB	−51…54 %
Time until visible partials are ready, Chromium (load / resize)	777 / 243 ms	541 / 108 ms	−30 % / −56 %
alphaTab.core.min.mjs gzip	296.2 KiB	303.3 KiB	+2.4 %

The other test scores (canon, full-song, notation-legend, a GP7 file) show the same direction. On all of them,
initial render takes 33–48 % less time and resizes 47–63 % less.

Compared with 1.8.4, the release is faster as well: initial render −28…36 % and resize −13…39 % on real
songs, and allocations are about halved. The one exception is the small notation-legend score, where
both are on par.

Compatibility notes

• Rendering output changes as listed above. The reference images are updated in one commit at the end.
• Main and worker builds must be the same version. The worker message format changed (MessagePack score,
  flat bounds).
• SVG text output differs in whitespace and attributes (see above). It renders the same.

Checklist

• I consent that this change becomes part of alphaTab under its current or any future open source license
• This PR is linked to an accepted issue (see above: release preparation, no dedicated issue)
• Changes are implemented
• New tests were added
  • unit tests for every fix;
  • visual tests for numbered rests, colours and bend labels;
  • the bounds wire format checked against toJson/fromJson over the visual-test corpus.
  • The resize-vs-fresh comparison of the 2,725 cases was a separate harness during development, not part of this PR.
  • Last full run: TS 2374/2374, C# 2204/2204, Kotlin 2204/2204.
• I have read AGENTS.md if an AI helped draft any part of this PR

AI authorship disclosure

• No AI agent authored any part of this PR (description, code, tests, or commit messages)
• An AI agent contributed to this PR. The AI-authored disclosure block
  (alphatab-ai-authored-v1) is present at the top of this body, and I have
  personally reviewed every change and can explain each one

Further details

• This is a breaking change
• This change will require update of the documentation/website