feat: restructure note model, snapshot serialisation, and staff rendering

Track / note model
- Replace ad-hoc note objects with a unified ISbDmNoteEvent runtime
  representation; remove ISbDmNote.
- Track now holds measures only; polyrhythm-specific logic is moved out
  into a dedicated MigrationTrack used during legacy import.
- Simplify and tighten edit/clipboard/undo paths around the new model.

Snapshot serialisation
- Introduce compact V2 snapshot format with on-demand migration.
- Add ArrangementSnapshotMigrator with a clear legacy → modern path.
- Cleanly separate legacy and Animada-native serialisation formats.
- Add snapshot-packing (stringify/parse) and numeric-functions helpers.
- Move BananaDrumUrlImporter and the legacy Note type under
  serialisation/migration/.

Staff / polyrhythm rendering
- Tuplet-aware StaffNoteViewer: glyph picker, per-pulse rest glyphs,
  beam-count via effectiveStepsPerPulse.
- Tuplet brackets render whenever the pulse is not fully covered by a
  continuous beam, even for pure-rest pulses; bracket span tightened to
  first-notehead-center → last-notehead-center.
- First-bar offset for the tuplet layer via --staff-note-prefix-width.
- Play beam in the first bar aligns to the actual music start using
  measureFirstBarMusicStartPx() / getBoundingClientRect.
- New PolyrhythmEventGroupBuilder and PolyrhythmEventNoteViewer; group
  consecutive rests into standard rest values.

Instrument / note characteristics
- INoteStyleMeta.characteristics is now mandatory and is propagated from
  each variant into the runtime noteStyles (Instrument.ts previously
  read a non-existent instrumentMeta.meta.characteristics, leaving
  TechniqueType info undefined at runtime).
- Tag every variant in bateria-instruments.ts with the correct
  ExcitationMode and TechniqueType (HandTechnique / StickTechnique),
  including damping for the surdos.
- Add ExcitationMode.Vocal + VocalCharacteristics for non-instrument
  samples and apply it to the spoken number sounds.
- Break circular imports by loading bateriaInstruments and numberSounds
  dynamically inside their loaders.

Misc
- Numerous test updates and new specs (snapshots, snapshot-packing,
  Track, utils, PolyrhythmFlow integration).
- Minor cleanups in App, ScoreLibrary, SelectionManager, TimeCoordinator,
  TrackPlayer and various UI framework components.

Signed-off-by: Mike Lischke <mike@lischke-online.de>

Author: mike-lischke

.vscode/settings.json

@@ -7,6 +7,10 @@
         "npx tsc": true,
         "npm run -s tsc": true,
         "npm run -s lint": true,
-        "npx -y ts-prune": true
+        "npx -y ts-prune": true,
+        "npm run -s test": true,
+        "npx eslint": true,
+        "mv": true,
+        "npx vitest": true
     },
 }

cspell.json

@@ -8,23 +8,32 @@
         "abelian",
         "Agogo",
         "Agogô",
+        "Agogôs",
         "animada",
+        "Apito",
         "Atabaque",
         "Banandrum",
         "barline",
         "bateria",
+        "beamable",
         "Beija",
+        "Cabasa",
         "Caixa",
         "Capoeira",
+        "Caxixi",
         "Chocalho",
         "Cinco",
         "colour",
         "Colours",
+        "Cuica",
+        "Cuicas",
         "deserialise",
         "deserialisers",
         "Dois",
+        "Ganzá",
         "guiderail",
         "initialise",
+        "inspectable",
         "Metas",
         "Nove",
         "Oito",
@@ -34,16 +43,19 @@
         "prefresh",
         "Quatro",
         "recalc",
+        "Reco",
         "repi",
         "Repinique",
         "repiniques",
         "Rimshot",
+        "rimshots",
         "Scorebook",
         "Seis",
         "serialisation",
         "serialise",
         "Serialised",
         "Sete",
+        "Shekere",
         "spacebar",
         "Surdo",
         "surdos",
@@ -54,6 +66,8 @@
         "Três",
         "tuplet",
         "tuplets",
+        "unbeamed",
+        "unpitched",
         "Whippies"
     ],
     "ignoreWords": [

package.json

@@ -12,14 +12,16 @@
     "scripts": {
         "dev": "vite --host",
         "build": "npm run generate-themes && vite build",
-        "serve:e2e": "node build/serve-dist.mjs",
+        "watch": "npm run watch:src & npm run watch:tests & wait",
+        "watch:src": "tsc --noEmit --watch",
+        "watch:tests": "tsc -p tests/tsconfig.json --noEmit --watch",
         "test": "vitest --no-watch",
+        "lint": "eslint 'src/**/*.{ts,tsx}' 'tests/**/*.{ts,tsx}'",
         "test:e2e": "playwright test",
         "test:e2e:headed": "playwright test --headed",
         "test:e2e:ui": "playwright test --ui",
+        "serve:e2e": "node build/serve-dist.mjs",
         "playwright:install": "playwright install chromium",
-        "lint": "eslint 'src/**/*.{ts,tsx}'",
-        "watch": "tsc --noEmit --watch",
         "generate-themes": "tsx build/generate-daisyui-themes.ts"
     },
     "dependencies": {

src/App.scss

@@ -414,6 +414,7 @@ h6 {
 }
 
 .note-line {
+    position: relative;
     transition: opacity 0.2s;
     overflow-x: hidden;
 }
@@ -422,6 +423,14 @@ h6 {
     display: flex;
 }
 
+.note-line .polyrhythms-wrapper,
+.bar-track-row .polyrhythms-wrapper {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    pointer-events: none;
+}
+
 .note-line .polyrhythm-viewer {
     position: absolute;
     padding-left: calc(1.5pt + 4px);
@@ -512,8 +521,9 @@ h6 {
     top: 50%;
     left: 0;
     right: 0;
-    border-top: 1px solid var(--color-base-content);
+    border-top: 1px solid var(--color-base-300);
     transform: translateY(-50%);
+    z-index: -1;
 }
 
 .staff-note-viewer-prefix {
@@ -526,15 +536,15 @@ h6 {
     align-items: center;
     justify-content: center;
     gap: 10px;
-    color: var(--color-base-content);
+    color: var(--color-base-300);
     pointer-events: none;
 }
 
 .staff-note-viewer-neutral-clef {
     width: 8px;
     height: var(--staff-barline-height);
-    border-left: 3px solid currentColor;
-    border-right: 3px solid currentColor;
+    border-left: 3px solid var(--color-base-content);
+    border-right: 3px solid var(--color-base-content);
     border-radius: 1px;
 }
 
@@ -614,32 +624,29 @@ h6 {
     flex-shrink: 0;
 }
 
-.staff-note-viewer-run.beam-right::before,
-.staff-note-viewer-run.beam-right::after {
-    content: "";
+/* Beam stroke attached to a beamed note. Position (top, left/right, width) is set inline by
+   StaffNoteViewer.renderBeamSegments per beam segment (shared vs partial, level 1..3). */
+.staff-note-viewer-beam {
     position: absolute;
-    left: calc(50% + 5px);
-    right: calc(-50% - 5px);
     height: 3px;
     background: var(--color-base-content);
     pointer-events: none;
     z-index: 2;
 }
 
-.staff-note-viewer-run.beam-right::before {
-    top: calc(50% - 36px);
-}
-
-.staff-note-viewer-run.beam-right::after {
-    top: calc(50% - 31px);
-}
-
 .staff-note-viewer-tuplets {
     position: absolute;
     inset: 0;
     pointer-events: none;
 }
 
+/* In the first bar the prefix (clef + time signature) sits to the left of the runs area; the
+   tuplets layer must align with the runs, not with the bar's outer edge, so its bracket
+   percentages refer to the same horizontal extent as the noteheads. */
+.staff-note-viewer.first-bar .staff-note-viewer-tuplets {
+    left: var(--staff-note-prefix-width);
+}
+
 .staff-note-viewer-tuplet-number {
     position: absolute;
     top: calc(50% - 55px);
@@ -656,12 +663,42 @@ h6 {
     z-index: 2;
 }
 
+/*
+ * Tuplet bracket: drawn when the tuplet pulse is not covered by a continuous beam (e.g. a
+ * triplet of 8th-note + 8th-rest + 8th-rest). Spans the pulse horizontally with a thin top
+ * line and short downward ticks at each end; the number sits centered, breaking the line.
+ */
+.staff-note-viewer-tuplet-bracket {
+    position: absolute;
+    top: calc(50% - 55px);
+    height: 9px;
+    border-top: 1.5px solid var(--color-base-content);
+    border-left: 1.5px solid var(--color-base-content);
+    border-right: 1.5px solid var(--color-base-content);
+    border-bottom: 0;
+    box-sizing: border-box;
+    color: var(--color-base-content);
+    z-index: 2;
+    pointer-events: none;
+}
+
+.staff-note-viewer-tuplet-bracket > .staff-note-viewer-tuplet-text {
+    position: absolute;
+    top: -10px;
+    left: 50%;
+    transform: translateX(-50%);
+    font-size: 16px;
+    font-weight: 700;
+    line-height: 1;
+    background: var(--color-base-100);
+    padding: 0 3px;
+}
+
 /* Note symbol: 16th-note SVG icon */
 .staff-note-viewer-note-symbol {
     display: block;
-    width: auto;
-    height: 50px;
-    opacity: 0.85;
+    width: 25px;
+    height: 60px;
 
     /* The note head is in the lower part of this SVG; lift it so the head center sits on the middle line. */
     transform: translateY(-14.5px);
@@ -670,9 +707,36 @@ h6 {
 /* Rest symbol: 16th-rest SVG icon */
 .staff-note-viewer-rest-symbol {
     display: block;
-    width: auto;
+    width: 22px;
     height: 40px;
-    opacity: 0.7;
+}
+
+/* Augmentation dots are absolutely positioned so they don't displace the centered note / rest
+   glyph in the flex slot. Without this, flex centering would shift the glyph left by half the
+   dot+gap width, opening a gap between the note stem and any beam (which anchors at slot center). */
+
+/* Augmentation dot drawn next to a grouped rest icon (no dotted-rest SVGs exist). */
+.staff-note-viewer-rest-dot {
+    position: absolute;
+    /* Rest icons have some transparent padding on the right; offset so the dot reads as adjacent. */
+    left: calc(50% + 8px);
+    top: calc(50% + 6px);
+    width: 4px;
+    height: 4px;
+    border-radius: 50%;
+    background: var(--color-base-content);
+}
+
+/* Augmentation dot drawn next to a dotted note glyph (no dotted-note SVGs exist). */
+.staff-note-viewer-note-dot {
+    position: absolute;
+    /* Just past the right edge of the 25px-wide notehead icon (centered in slot). */
+    left: calc(50% + 8px);
+    top: calc(50% + 4px);
+    width: 4px;
+    height: 4px;
+    border-radius: 50%;
+    background: var(--color-base-content);
 }
 
 /* Polyrhythm fragment: an absolutely-positioned slice of a polyrhythm within a bar */
@@ -770,6 +834,15 @@ h6 {
     align-items: center;
 }
 
+/* Polyrhythm notes: anchor symbols to the left edge of their flex cell so the i-th note's
+   on-screen position matches its actual time position (i/N of the pulse), rather than the
+   cell's center. With centered symbols the first note appeared delayed relative to playback
+   — most visible at low BPMs — because each note sat in the middle of its 1/N subdivision. */
+.polyrhythm-fragment .note-details-viewer,
+.polyrhythm-viewer .note-details-viewer {
+    justify-content: flex-start;
+}
+
 .note-details-viewer .note-style-symbol {
     width: 70%;
     height: 70%;

src/App.tsx

@@ -39,8 +39,11 @@ import { AppStorage, type IUISettings } from "./core/AppStorage.js";
 import {
     SbDmEntityType, ScoreBookDataModel, type ISbDmScore, type ISbDmScoreFolder
 } from "./core/ScoreBookDataModel.js";
-import { BananaDrumUrlImporter } from "./core/serialisation/BananaDrumUrlImporter.js";
-import { isNaturalNumber } from "./core/serialisation/snapshot-version.js";
+import { ArrangementSnapshotMigrator } from "./core/serialisation/migration/ArrangementSnapshotMigrator.js";
+import {
+    stringifyPackedArrangement
+} from "./core/serialisation/snapshot-packing.js";
+import { isNaturalNumber } from "./core/serialisation/snapshots.js";
 import type { IArrangementSnapshot, ISerialisedArrangement } from "./core/types/general.js";
 import { UndoManager } from "./core/UndoManager.js";
 import { convertErrorToString } from "./core/utils.js";
@@ -72,7 +75,7 @@ interface IAppState {
     headerPinned: boolean;
 }
 
-const newSong: ISerialisedArrangement = { composition: emptySongString, version: 2, title: "New Song" };
+const newSong: ISerialisedArrangement = { composition: emptySongString, version: 1, title: "New Song" };
 
 export class App extends UIComponent<{}, IAppState> {
     private scoreLibraryRef = createRef<DrawerSidebar>();
@@ -120,11 +123,12 @@ export class App extends UIComponent<{}, IAppState> {
         this.applyThemePreference(this.selectedThemePreference);
         this.systemThemeQuery.addEventListener("change", this.handleSystemThemeChange);
         escapeStack.attach();
+
         requisitions.register("settingsChanged", this.handleSettingsChanged);
         requisitions.register("playRangeChanged", this.handlePlayRangeChanged);
 
         void this.dataModel.initialize().then(() => {
-            const arrangementSnapshot = BananaDrumUrlImporter.getArrangementSnapshotFromParams(
+            const arrangementSnapshot = ArrangementSnapshotMigrator.migrateFromParams(
                 new URL(window.location.href).searchParams,
                 this.dataModel.instruments
             );
@@ -483,7 +487,20 @@ export class App extends UIComponent<{}, IAppState> {
                                 try {
                                     const params = new URL(url).searchParams;
                                     const title = params.get("t") ?? "Imported Score";
-                                    await this.dataModel.addScore(title, params.toString(), parent);
+
+                                    // Migrate the BananaDrum link to the current snapshot
+                                    // format and store it in the compact V2 wire format.
+                                    const snapshot = ArrangementSnapshotMigrator.migrateFromParams(
+                                        params,
+                                        this.dataModel.instruments,
+                                    );
+                                    if (!snapshot) {
+                                        throw new Error("URL does not contain a recognised score payload");
+                                    }
+
+                                    snapshot.title = title;
+                                    const content = stringifyPackedArrangement(snapshot);
+                                    await this.dataModel.addScore(title, content, parent);
 
                                     return true;
                                 } catch (error) {
@@ -548,12 +565,7 @@ export class App extends UIComponent<{}, IAppState> {
                 });
 
                 if (data.type === SbDmEntityType.Score) {
-                    const params = new URLSearchParams(data.content);
-                    const arrangementSnapshot = BananaDrumUrlImporter.getArrangementSnapshotFromParams(
-                        params,
-                        this.dataModel.instruments
-                    );
-
+                    const arrangementSnapshot = this.dataModel.decodeScoreContent(data);
                     this.loadScorebook(arrangementSnapshot ?? newSong);
                 }
 
@@ -637,7 +649,8 @@ export class App extends UIComponent<{}, IAppState> {
         const resolvedArrangementToLoad = arrangementToLoad ?? newSong;
         const arrangement = this.dataModel.loadArrangement(resolvedArrangementToLoad);
         if (snapshotToLoad) {
-            arrangement.applyArrangementSnapshot(snapshotToLoad, this.dataModel.instruments);
+            const currentSnapshot = ArrangementSnapshotMigrator.migrate(snapshotToLoad, this.dataModel.instruments);
+            arrangement.applyArrangementSnapshot(currentSnapshot, this.dataModel.instruments);
         }
         this.undoManager = new UndoManager(this.dataModel);
         this.stopCurrentScoreAutoSave = this.undoManager.topics.currentState.subscribe(() => {