@real-music-packages/web-core 0.45.2 → 0.47.0

package/README.md

@@ -78,11 +78,20 @@ npm install @real-music-packages/web-core
 ## Dev
 ```
 npm install
-npm test            # vitest
+npm test            # vitest — all 76 files / 788 tests (~28s)
 npm run build       # tsup → dist/ (ESM + .d.ts)
 npm run build:watch # tsup --watch → rebuild dist/ on every edit (fast dev loop)
+
+bash scripts/quick.sh              # tests reachable from your diff + tsc (~19s)
+bash scripts/quick.sh origin/main  # ...from the whole branch
 ```
 
+`quick.sh` runs `vitest --changed`, so only the tests your diff can reach through
+the module graph. `tsc --noEmit` always runs alongside it (~6.5s) — this package is
+a **published dependency**, so a type regression escapes into every app that vendors
+it. If `--changed` matches no test, it prints `TYPES ONLY` rather than a green tick.
+It is not a release gate; publishing still goes through `npm test` + `npm run build`.
+
 **Iterating against a live app without a publish/re-pin?** See
 [DEVELOPMENT.md](./DEVELOPMENT.md) — `build:watch` + `tools/dev-link.sh <app>`
 links the local web-core into an app so its vite dev server reflects your edits

package/dist/audio.js

@@ -1,10 +1,3 @@
-import {
-  KEYS_PREFER_FLATS
-} from "./chunk-BYZBLH25.js";
-import {
-  getMidiNote,
-  midiToNoteName
-} from "./chunk-GORQ5YMR.js";
 import {
   SALAMANDER_CDN_BASE,
   SALAMANDER_URLS_8,
@@ -12,6 +5,13 @@ import {
   createSalamanderSampler,
   generateReverb
 } from "./chunk-74TMWRNK.js";
+import {
+  KEYS_PREFER_FLATS
+} from "./chunk-BYZBLH25.js";
+import {
+  getMidiNote,
+  midiToNoteName
+} from "./chunk-GORQ5YMR.js";
 
 // src/engine.ts
 var browser = typeof window !== "undefined";

package/dist/chunk-JCDNEJBT.js

@@ -0,0 +1,176 @@
+// src/notationXml.ts
+function stampNoteIds(xml) {
+  const doc = new DOMParser().parseFromString(xml, "application/xml");
+  if (doc.querySelector("parsererror")) return xml;
+  const parts = Array.from(doc.querySelectorAll("score-partwise > part"));
+  parts.forEach((part, partIdx) => {
+    for (const measure of Array.from(part.querySelectorAll("measure"))) {
+      const number = measure.getAttribute("number") ?? "0";
+      const notes = Array.from(measure.children).filter((el) => el.tagName === "note");
+      notes.forEach((note, noteIdx) => {
+        note.setAttribute("id", `n-${partIdx}-${number}-${noteIdx}`);
+      });
+    }
+  });
+  return new XMLSerializer().serializeToString(doc);
+}
+function measureCount(xml) {
+  const doc = new DOMParser().parseFromString(xml, "application/xml");
+  if (doc.querySelector("parsererror")) return 0;
+  const root = doc.documentElement;
+  if (!root || root.tagName !== "score-partwise") return 0;
+  const [firstPart] = childrenNamed(root, "part");
+  return firstPart ? childrenNamed(firstPart, "measure").length : 0;
+}
+function injectSystemBreaks(xml, breakBeforeBarIndexes) {
+  const doc = new DOMParser().parseFromString(xml, "application/xml");
+  if (doc.querySelector("parsererror")) return xml;
+  const root = doc.documentElement;
+  if (!root || root.tagName !== "score-partwise") return xml;
+  for (const part of childrenNamed(root, "part")) {
+    const measures = childrenNamed(part, "measure");
+    for (const pos of breakBeforeBarIndexes) {
+      if (!Number.isInteger(pos) || pos <= 0 || pos >= measures.length) continue;
+      const measure = measures[pos];
+      const existingPrint = firstChildNamed(measure, "print");
+      if (existingPrint) {
+        existingPrint.setAttribute("new-system", "yes");
+      } else {
+        const printEl = doc.createElement("print");
+        printEl.setAttribute("new-system", "yes");
+        measure.insertBefore(printEl, measure.firstChild);
+      }
+    }
+  }
+  return new XMLSerializer().serializeToString(doc);
+}
+function balancedSystemBreaks(totalMeasures, systems) {
+  if (systems <= 1 || totalMeasures <= 0) return [];
+  const per = Math.ceil(totalMeasures / systems);
+  if (per <= 0) return [];
+  const breaks = [];
+  for (let b = per; b < totalMeasures; b += per) breaks.push(b);
+  return breaks;
+}
+function barsPerLineBreaks(totalBars, every) {
+  if (!Number.isFinite(totalBars) || !Number.isFinite(every)) return [];
+  if (every <= 0 || totalBars <= 0) return [];
+  let lines = Math.ceil(totalBars / every);
+  let per = Math.ceil(totalBars / lines);
+  while (lines > 1 && totalBars - (lines - 1) * per < 2) {
+    lines--;
+    per = Math.ceil(totalBars / lines);
+  }
+  return balancedSystemBreaks(totalBars, lines);
+}
+function sectionAwareBreaks(totalBars, sectionStarts, every) {
+  if (!Number.isFinite(totalBars) || totalBars <= 0) return [];
+  const usable = sectionStarts.filter((b) => Number.isInteger(b) && b > 0 && b < totalBars);
+  const boundaries = Array.from(/* @__PURE__ */ new Set([0, ...usable])).sort((a, b) => a - b);
+  const result = /* @__PURE__ */ new Set();
+  if (every > 0) {
+    for (let i = 0; i < boundaries.length; i++) {
+      const start = boundaries[i];
+      const end = i + 1 < boundaries.length ? boundaries[i + 1] : totalBars;
+      for (const pos of barsPerLineBreaks(end - start, every)) result.add(start + pos);
+    }
+  }
+  for (const s of usable) result.add(s);
+  return Array.from(result).sort((a, b) => a - b);
+}
+var STEP_SEMITONE = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
+function firstChildNamed(el, tag) {
+  for (const c of Array.from(el.children)) if (c.tagName === tag) return c;
+  return null;
+}
+function childrenNamed(el, tag) {
+  return Array.from(el.children).filter((c) => c.tagName === tag);
+}
+function textOf(el) {
+  return el && el.textContent != null ? el.textContent.trim() : null;
+}
+function pitchMidiFromElement(pitchEl) {
+  const step = textOf(firstChildNamed(pitchEl, "step")) ?? "C";
+  const octave = Number(textOf(firstChildNamed(pitchEl, "octave")) ?? "4");
+  const alter = Number(textOf(firstChildNamed(pitchEl, "alter")) ?? "0");
+  return 12 * (octave + 1) + (STEP_SEMITONE[step] ?? 0) + Math.trunc(alter);
+}
+function partStaffCount(part) {
+  let maxDeclared = 0;
+  for (const attrs of childrenNamed(part, "measure").flatMap((m) => childrenNamed(m, "attributes"))) {
+    const staves = Number(textOf(firstChildNamed(attrs, "staves")) ?? "0");
+    if (staves > maxDeclared) maxDeclared = staves;
+  }
+  if (maxDeclared > 0) return maxDeclared;
+  let maxStaff = 0;
+  for (const measure of childrenNamed(part, "measure")) {
+    for (const note of childrenNamed(measure, "note")) {
+      const staff = Number(textOf(firstChildNamed(note, "staff")) ?? "0");
+      if (staff > maxStaff) maxStaff = staff;
+    }
+  }
+  return Math.max(1, maxStaff);
+}
+function noteModelFromXml(stampedXml) {
+  const model = /* @__PURE__ */ new Map();
+  let doc;
+  try {
+    doc = new DOMParser().parseFromString(stampedXml, "application/xml");
+  } catch {
+    return model;
+  }
+  if (doc.querySelector("parsererror")) return model;
+  const root = doc.documentElement;
+  if (!root || root.tagName !== "score-partwise") return model;
+  const parts = childrenNamed(root, "part");
+  let staffOffset = 0;
+  for (const part of parts) {
+    const staffCount = partStaffCount(part);
+    let divisions = 1;
+    const measureEls = childrenNamed(part, "measure");
+    measureEls.forEach((measureEl, measureIndex) => {
+      for (const child of Array.from(measureEl.children)) {
+        if (child.tagName === "attributes") {
+          const divText = textOf(firstChildNamed(child, "divisions"));
+          if (divText) divisions = Number(divText) || divisions;
+          continue;
+        }
+        if (child.tagName !== "note") continue;
+        const note = child;
+        const id = note.getAttribute("id");
+        if (!id) continue;
+        const isGrace = !!firstChildNamed(note, "grace");
+        const isRest = !!firstChildNamed(note, "rest");
+        const pitchEl = firstChildNamed(note, "pitch");
+        const staffNumber = Number(textOf(firstChildNamed(note, "staff")) ?? "1") || 1;
+        const durationText = textOf(firstChildNamed(note, "duration"));
+        const durationReal = isGrace || !durationText ? 0 : Number(durationText) / divisions / 4;
+        const tieStopDirect = childrenNamed(note, "tie").some((t) => t.getAttribute("type") === "stop");
+        const notationsEl = firstChildNamed(note, "notations");
+        const tieStopNotated = notationsEl ? childrenNamed(notationsEl, "tied").some((t) => t.getAttribute("type") === "stop") : false;
+        model.set(id, {
+          midi: pitchEl ? pitchMidiFromElement(pitchEl) : null,
+          isRest,
+          tieContinuation: tieStopDirect || tieStopNotated,
+          staffIndex: staffOffset + Math.max(0, staffNumber - 1),
+          durationReal,
+          measureIndex,
+          hidden: note.getAttribute("print-object") === "no"
+        });
+      }
+    });
+    staffOffset += staffCount;
+  }
+  return model;
+}
+
+export {
+  stampNoteIds,
+  measureCount,
+  injectSystemBreaks,
+  balancedSystemBreaks,
+  barsPerLineBreaks,
+  sectionAwareBreaks,
+  noteModelFromXml
+};
+//# sourceMappingURL=chunk-JCDNEJBT.js.map

package/dist/chunk-JCDNEJBT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/notationXml.ts"],"sourcesContent":["// Pure MusicXML→MusicXML/model helpers for `createVerovioNotationPlayer`\n// (notationPlayerVerovio.ts, 0.40.0) — the id-stamping + note-model half of\n// its \"join model ids to Verovio's rendered SVG\" approach (that module's\n// header doc, point 1). No DOM rendering here; everything in this file is\n// pure XML-in → XML/data-out, unit-testable with no live SVG at all.\n//\n// OWNERSHIP NOTE — `stampNoteIds`'s deterministic id scheme\n// (`n-{partIdx}-{measureNumber}-{noteIdxInMeasure}`) is DELIBERATELY\n// duplicated, byte-for-byte, from stave-web-sightread's\n// `src/lib/bach/xmlTransforms.ts:stampNoteIds` (part of that repo's Verovio\n// transform pipeline, docs/superpowers/specs/2026-08-11-verovio-player-design.md\n// §1). stave's copy is the one actually wired into `parseReduction` (its\n// `noteIds` per span must match what got stamped onto the MusicXML BEFORE\n// Verovio ever saw it), so stave remains that scheme's owner for the\n// pipeline's purposes. This copy exists so `createVerovioNotationPlayer`\n// works correctly for ANY caller — including ones that hand in un-stamped\n// MusicXML — without a runtime dependency from web-core back into an app\n// repo (the wrong direction for a shared package). Both copies are pure\n// functions of a note's POSITION (never of any id already present), so\n// calling either one on already-stamped input reproduces the exact same\n// ids — the two copies can never drift apart in OBSERVABLE behavior even\n// though they are physically two files. If the scheme ever needs to change,\n// change it in BOTH places (this file's own tests pin the scheme\n// independently of stave's, so a one-sided edit fails a test here).\nexport function stampNoteIds(xml: string): string {\n  const doc = new DOMParser().parseFromString(xml, 'application/xml');\n  if (doc.querySelector('parsererror')) return xml;\n\n  const parts = Array.from(doc.querySelectorAll('score-partwise > part'));\n  parts.forEach((part, partIdx) => {\n    for (const measure of Array.from(part.querySelectorAll('measure'))) {\n      const number = measure.getAttribute('number') ?? '0';\n      const notes = Array.from(measure.children).filter((el) => el.tagName === 'note');\n      notes.forEach((note, noteIdx) => {\n        note.setAttribute('id', `n-${partIdx}-${number}-${noteIdx}`);\n      });\n    }\n  });\n\n  return new XMLSerializer().serializeToString(doc);\n}\n\n// ─── injectSystemBreaks / balancedSystemBreaks — widow-avoidance helpers ──\n//\n// Used by notationPlayerVerovio.ts's widow pass (`engraveOnce`): when\n// `breaks: 'auto'` leaves a lone trailing measure on its own system (a\n// \"widow\" — Verovio's own `breaksNoWidow` only guards the last PAGE, not the\n// last SYSTEM, per that module's doc), the player forces exact line breaks\n// via `injectSystemBreaks` + `breaks: 'line'`, choosing the break points with\n// `balancedSystemBreaks` so the same number of systems comes out evenly\n// filled instead of front-loaded-then-orphaned.\n//\n// CONTRACT DUPLICATION NOTICE — stave-web-sightread's\n// `src/lib/bach/xmlTransforms.ts` has its OWN `injectSystemBreaks`,\n// `barsPerLineBreaks` and `sectionAwareBreaks`, written on the reasoning\n// that \"a shared package must not runtime-depend on an app repo for\n// something this small\". That reasoning is backwards for break POLICY: the\n// engraver is what owns where systems begin, so those copies are being\n// RETIRED in favour of the ones here, reached through\n// `VerovioLayoutOptions.barsPerLine` / `.sectionStarts` rather than by the\n// app hand-injecting breaks of its own.\n//\n// Until that app-side change lands, both copies exist and must stay in sync.\n// (The app's `injectSystemBreaks` uses `querySelectorAll('measure')` where\n// this one walks direct children only — this one is the stricter of the two\n// on scores with nested measure-like elements.)\n\n/**\n * Insert `<print new-system=\"yes\"/>` as the FIRST child of the `<measure>`\n * at each 0-based position in `breakBeforeBarIndexes`, in EVERY `<part>`\n * (a score's parts share one measure timeline, so a break must be encoded\n * once per part for Verovio to line the systems up across staves). A\n * position that is ≤ 0 or ≥ that part's own measure count is silently\n * ignored FOR THAT PART (0 is a no-op — a part already starts a new system\n * at its own first measure). Idempotent: a measure that already carries a\n * `<print>` element (from a prior call, or from the source data) gets\n * `new-system=\"yes\"` SET on that existing element rather than gaining a\n * second one — calling this twice with the same positions serializes\n * identically both times. Malformed input (fails to parse) is returned\n * unchanged, same defensive style as `stampNoteIds` above. Only ever ADDS\n * `<print>` elements — never touches a `<note>` — so `stampNoteIds`'s\n * position-based id scheme is unaffected by a prior or subsequent call to\n * this function (see this file's own tests for the pinned invariant).\n */\n/**\n * How many `<measure>` elements the FIRST `<part>` has — the `totalBars`\n * that `barsPerLineBreaks`/`sectionAwareBreaks` plan against.\n *\n * The first part specifically, because that is the coordinate system\n * `injectSystemBreaks` positions live in: a score's parts share one measure\n * timeline, so the first part's ordinals index every part. And ORDINALS, not\n * `<measure number>` attributes — scores skip and repeat bar numbers, so a\n * count is the only safe answer. Malformed input, or a document with no\n * part, returns 0 rather than throwing.\n */\nexport function measureCount(xml: string): number {\n  const doc = new DOMParser().parseFromString(xml, 'application/xml');\n  if (doc.querySelector('parsererror')) return 0;\n  const root = doc.documentElement;\n  if (!root || root.tagName !== 'score-partwise') return 0;\n  const [firstPart] = childrenNamed(root, 'part');\n  return firstPart ? childrenNamed(firstPart, 'measure').length : 0;\n}\n\nexport function injectSystemBreaks(xml: string, breakBeforeBarIndexes: readonly number[]): string {\n  const doc = new DOMParser().parseFromString(xml, 'application/xml');\n  if (doc.querySelector('parsererror')) return xml;\n\n  const root = doc.documentElement;\n  if (!root || root.tagName !== 'score-partwise') return xml;\n\n  for (const part of childrenNamed(root, 'part')) {\n    const measures = childrenNamed(part, 'measure');\n    for (const pos of breakBeforeBarIndexes) {\n      if (!Number.isInteger(pos) || pos <= 0 || pos >= measures.length) continue;\n      const measure = measures[pos];\n      const existingPrint = firstChildNamed(measure, 'print');\n      if (existingPrint) {\n        existingPrint.setAttribute('new-system', 'yes');\n      } else {\n        const printEl = doc.createElement('print');\n        printEl.setAttribute('new-system', 'yes');\n        measure.insertBefore(printEl, measure.firstChild);\n      }\n    }\n  }\n\n  return new XMLSerializer().serializeToString(doc);\n}\n\n/**\n * Evenly-spread system-break positions for `totalMeasures` measures across\n * `systems` systems: `[per, 2·per, …]` (each strictly `< totalMeasures`),\n * with `per = Math.ceil(totalMeasures / systems)` — `Math.ceil` naturally\n * front-loads any remainder into the EARLIER systems (e.g. 7 measures / 2\n * systems -> per=4 -> systems of 4+3, never 3+4), which is what keeps a\n * later system from being the short/orphaned one. `systems <= 1` (nothing to\n * break between) returns `[]`.\n */\nexport function balancedSystemBreaks(totalMeasures: number, systems: number): number[] {\n  if (systems <= 1 || totalMeasures <= 0) return [];\n  const per = Math.ceil(totalMeasures / systems);\n  if (per <= 0) return [];\n  const breaks: number[] = [];\n  for (let b = per; b < totalMeasures; b += per) breaks.push(b);\n  return breaks;\n}\n\n/**\n * Balanced system-break positions for a target BARS-PER-LINE layout — the\n * caller-facing sibling of `balancedSystemBreaks`, which takes a system\n * COUNT. Rather than stepping `every` bars at a time from bar 0 (which\n * strands a short remainder — a 5-bar excerpt at `every: 4` renders 4+1, a\n * widow of our own making), this decides how many LINES the excerpt needs\n * (`ceil(totalBars / every)`) and hands that count to\n * `balancedSystemBreaks`. `(5, 4)` is `[3]` (3+2) instead of `[4]` (4+1);\n * `(9, 4)` is `[3, 6]` (3+3+3) instead of `[4, 8]` (4+4+1).\n *\n * WIDOW BACK-OFF: a small `every` against a small `totalBars` can make the\n * straight `ceil(totalBars / every)` line count land on a trailing line of\n * exactly 1 bar — the same widow this function exists to remove, reappearing\n * at a different total/every combination (`lines = 3` on 7 bars: `per = 3`\n * fills two 3-bar lines and leaves 1 bar for the third). The line count is\n * therefore backed down (never below 1) until the trailing line holds at\n * least 2 bars — 7 bars lands on 2 lines (4+3) instead of 3 (3+3+1), which\n * is the same \"fewer, fuller lines\" direction `every` already asks for.\n * This never changes the result for any total/every whose straight `ceil`\n * count already avoids a 1-bar trailing line.\n *\n * `every <= 0` (the \"auto — no forced breaks\" sentinel callers resolve to)\n * or a non-positive/non-finite `totalBars` returns `[]`. Never throws.\n *\n * Ported from stave-web-sightread (`src/lib/bach/xmlTransforms.ts`), whose\n * copy this replaces — see the CONTRACT DUPLICATION NOTICE above. Reached by\n * consumers through `VerovioLayoutOptions.barsPerLine` rather than called\n * directly, so the player owns both the plan and its interaction with the\n * widow pass and the readability floor.\n */\nexport function barsPerLineBreaks(totalBars: number, every: number): number[] {\n  if (!Number.isFinite(totalBars) || !Number.isFinite(every)) return [];\n  if (every <= 0 || totalBars <= 0) return [];\n  let lines = Math.ceil(totalBars / every);\n  let per = Math.ceil(totalBars / lines);\n  while (lines > 1 && totalBars - (lines - 1) * per < 2) {\n    lines--;\n    per = Math.ceil(totalBars / lines);\n  }\n  return balancedSystemBreaks(totalBars, lines);\n}\n\n/**\n * Like `barsPerLineBreaks`, but each SECTION's span is balanced on its own\n * instead of one balance running across the whole excerpt — so a line never\n * ends part-way into a neighbouring section's opening bars, and a section's\n * own bars are never split into a widowed last line either.\n *\n * `sectionStarts` are 0-BASED POSITIONS into the excerpt (the same\n * coordinate `injectSystemBreaks` consumes), NOT MusicXML `<measure\n * number>` attributes — scores skip bar numbers, so a caller holding\n * bar-numbered section labels must convert first. `0` (the excerpt's own\n * start) is never a break and is ignored if present.\n *\n * Every section start > 0 is a HARD break in its own right — a new section\n * always begins its own line, not subject to balancing — unioned with\n * `barsPerLineBreaks`' balanced positions computed WITHIN each section's\n * span (its start up to the next section's start, or `totalBars` for the\n * last) and offset back into excerpt-absolute positions.\n *\n * `every <= 0` suppresses the balanced component, matching\n * `barsPerLineBreaks`, but section-start breaks still apply — that is the\n * \"sections only, otherwise let the engraver decide\" mode. Out-of-range and\n * non-integer starts are ignored. The result is sorted, de-duplicated, and\n * every entry is a valid `injectSystemBreaks` position (integer, `> 0`,\n * `< totalBars`). Never throws.\n */\nexport function sectionAwareBreaks(\n  totalBars: number,\n  sectionStarts: readonly number[],\n  every: number,\n): number[] {\n  if (!Number.isFinite(totalBars) || totalBars <= 0) return [];\n  const usable = sectionStarts.filter((b) => Number.isInteger(b) && b > 0 && b < totalBars);\n  const boundaries = Array.from(new Set([0, ...usable])).sort((a, b) => a - b);\n\n  const result = new Set<number>();\n\n  if (every > 0) {\n    for (let i = 0; i < boundaries.length; i++) {\n      const start = boundaries[i];\n      const end = i + 1 < boundaries.length ? boundaries[i + 1] : totalBars;\n      for (const pos of barsPerLineBreaks(end - start, every)) result.add(start + pos);\n    }\n  }\n\n  for (const s of usable) result.add(s);\n\n  return Array.from(result).sort((a, b) => a - b);\n}\n\n// ─── noteModelFromXml — the note MODEL half of the join ───────────────────\n\n/** One `<note>`'s MODEL identity — the ground truth `EngravedNote`\n *  (notationPlayerSvg.ts) needs that Verovio's rendered SVG cannot supply on\n *  its own (a rendered `g.note`/`g.rest` carries geometry, not pitch/tie/\n *  duration semantics). Keyed by the note's stamped `id` in\n *  `notePositions()`'s return of `verovioEngravedNotes`\n *  (notationPlayerVerovio.ts). */\nexport interface NoteModel {\n  /** `12*(octave+1) + stepSemitone + alter` — the standard MusicXML→MIDI\n   *  conversion (the same formula stave-web-sightread's own\n   *  `practice/probeInputs.ts:pitchMidi` uses — a universal formula, not app\n   *  logic, so this is not an owned-layer violation to restate here). `null`\n   *  for a rest or an `<unpitched>` note (no `<pitch>` child) — mirrors\n   *  `EngravedNote.midi`'s own \"null covers both\" contract. */\n  midi: number | null;\n  /** Has a `<rest/>` child. */\n  isRest: boolean;\n  /** True for the STOP half of a tie — a direct `<tie type=\"stop\">` child OR\n   *  `<notations><tied type=\"stop\">` (exporters vary on which they emit;\n   *  either counts) — matches `EngravedNote.tieContinuation`'s \"continuation\n   *  note of a tie, not the struck start\" contract. */\n  tieContinuation: boolean;\n  /** 0-based, matching `EngravedNote.staffIndex`'s \"0 = top staff of the\n   *  system\" contract: every `<part>` is walked in document order, and\n   *  every DISTINCT staff within it (by `<attributes><staves>` when\n   *  present, else the highest `<staff>` number any of its notes uses, else\n   *  1) is assigned the next index — so a single-part 2-staff piano score\n   *  numbers 0/1 by `<staff>`, and a 2-part 1-staff-per-part reduction (this\n   *  app's own chord+bass shape) numbers 0/1 by PART, with neither case\n   *  needing different code. */\n  staffIndex: number;\n  /** Whole-note fraction (0.25 = quarter) — `duration / divisions / 4`,\n   *  divisions tracked per-part from the LAST `<attributes><divisions>`\n   *  seen at or before this note (MusicXML: divisions persist until\n   *  overridden, default 1). 0 for a grace note (no `<duration>` child —\n   *  the true, spec-correct signal; never guessed from `<type>`). */\n  durationReal: number;\n  /** 0-based position of this note's `<measure>` among its OWN `<part>`'s\n   *  measure children, in document order. Informational only — the live\n   *  join (`verovioOnsetColumns`/`verovioEngravedNotes`, both in\n   *  notationPlayerVerovio.ts) resolves the note's RENDERED measure index\n   *  from the live SVG DOM independently (Verovio's own render order, which\n   *  is what geometry/hit-testing must agree with), never from this field. */\n  measureIndex: number;\n  /** `print-object=\"no\"` on the source `<note>` (stave's `hideDoubledNotes`\n   *  sets this on editorially-doubled notes/rests before handing MusicXML to\n   *  this player). Verovio's importer HONORS this for `<note>` elements\n   *  carrying a `<pitch>` (renders `visibility=\"hidden\"` on its own,\n   *  empirically confirmed against a real 6.2.0 render) but does NOT honor\n   *  it for `<rest>` notes (the `<g class=\"rest\">` renders fully visible\n   *  regardless — same empirical check). `createVerovioNotationPlayer`\n   *  reads this field to force `visibility=\"hidden\"` after every render for\n   *  ANY id where it's true — a no-op re-application on notes Verovio\n   *  already hid, and the actual fix on the rests it doesn't (see that\n   *  module's `applyPrintObjectHiding`). */\n  hidden: boolean;\n}\n\nconst STEP_SEMITONE: Record<string, number> = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };\n\nfunction firstChildNamed(el: Element, tag: string): Element | null {\n  for (const c of Array.from(el.children)) if (c.tagName === tag) return c;\n  return null;\n}\nfunction childrenNamed(el: Element, tag: string): Element[] {\n  return Array.from(el.children).filter((c) => c.tagName === tag);\n}\nfunction textOf(el: Element | null): string | null {\n  return el && el.textContent != null ? el.textContent.trim() : null;\n}\n\nfunction pitchMidiFromElement(pitchEl: Element): number {\n  const step = textOf(firstChildNamed(pitchEl, 'step')) ?? 'C';\n  const octave = Number(textOf(firstChildNamed(pitchEl, 'octave')) ?? '4');\n  const alter = Number(textOf(firstChildNamed(pitchEl, 'alter')) ?? '0');\n  return 12 * (octave + 1) + (STEP_SEMITONE[step] ?? 0) + Math.trunc(alter);\n}\n\n/** How many staves `part` uses: the max `<attributes><staves>N</staves>`\n *  seen anywhere in it (the authoritative declaration when present), else\n *  the highest `<note><staff>N</staff></note>` number any of its notes\n *  uses, else 1 (a plain single-staff part declares neither). */\nfunction partStaffCount(part: Element): number {\n  let maxDeclared = 0;\n  for (const attrs of childrenNamed(part, 'measure').flatMap((m) => childrenNamed(m, 'attributes'))) {\n    const staves = Number(textOf(firstChildNamed(attrs, 'staves')) ?? '0');\n    if (staves > maxDeclared) maxDeclared = staves;\n  }\n  if (maxDeclared > 0) return maxDeclared;\n\n  let maxStaff = 0;\n  for (const measure of childrenNamed(part, 'measure')) {\n    for (const note of childrenNamed(measure, 'note')) {\n      const staff = Number(textOf(firstChildNamed(note, 'staff')) ?? '0');\n      if (staff > maxStaff) maxStaff = staff;\n    }\n  }\n  return Math.max(1, maxStaff);\n}\n\n/**\n * Pure(ish) — MusicXML-in, `id → NoteModel`-out. Walks every `<part>` in\n * document order, then every `<measure>` in document order, then every\n * DIRECT child in document order — `<attributes>` updates the part's own\n * `divisions` cursor; every other non-`<note>` child (`<backup>`,\n * `<forward>`, `<direction>`, …) is a structural/timeline element this\n * function has NO use for (it reads each note's OWN `<duration>` directly,\n * never a cursor POSITION — see `durationReal`'s doc — so unlike\n * `walkMeasureNotes`-style position walks, `<backup>`/`<forward>` need no\n * special handling here beyond being correctly skipped, which plain\n * tag-name filtering already does) — and every `<note>` becomes one model\n * entry, keyed by its `id` attribute (a note with NO `id` — i.e. input that\n * was never run through `stampNoteIds` — is silently skipped: it has no key\n * to join the render against, so there is nothing useful to record).\n *\n * Never throws: malformed input (fails to parse, or no `<score-partwise>`\n * root) returns an empty Map.\n */\nexport function noteModelFromXml(stampedXml: string): Map<string, NoteModel> {\n  const model = new Map<string, NoteModel>();\n  let doc: Document;\n  try {\n    doc = new DOMParser().parseFromString(stampedXml, 'application/xml');\n  } catch {\n    return model;\n  }\n  if (doc.querySelector('parsererror')) return model;\n  const root = doc.documentElement;\n  if (!root || root.tagName !== 'score-partwise') return model;\n\n  const parts = childrenNamed(root, 'part');\n  let staffOffset = 0;\n\n  for (const part of parts) {\n    const staffCount = partStaffCount(part);\n    let divisions = 1;\n    const measureEls = childrenNamed(part, 'measure');\n\n    measureEls.forEach((measureEl, measureIndex) => {\n      for (const child of Array.from(measureEl.children)) {\n        if (child.tagName === 'attributes') {\n          const divText = textOf(firstChildNamed(child, 'divisions'));\n          if (divText) divisions = Number(divText) || divisions;\n          continue;\n        }\n        if (child.tagName !== 'note') continue;\n        const note = child;\n        const id = note.getAttribute('id');\n        if (!id) continue;\n\n        const isGrace = !!firstChildNamed(note, 'grace');\n        const isRest = !!firstChildNamed(note, 'rest');\n        const pitchEl = firstChildNamed(note, 'pitch');\n        const staffNumber = Number(textOf(firstChildNamed(note, 'staff')) ?? '1') || 1;\n        const durationText = textOf(firstChildNamed(note, 'duration'));\n        const durationReal =\n          isGrace || !durationText ? 0 : Number(durationText) / divisions / 4;\n\n        const tieStopDirect = childrenNamed(note, 'tie').some((t) => t.getAttribute('type') === 'stop');\n        const notationsEl = firstChildNamed(note, 'notations');\n        const tieStopNotated = notationsEl\n          ? childrenNamed(notationsEl, 'tied').some((t) => t.getAttribute('type') === 'stop')\n          : false;\n\n        model.set(id, {\n          midi: pitchEl ? pitchMidiFromElement(pitchEl) : null,\n          isRest,\n          tieContinuation: tieStopDirect || tieStopNotated,\n          staffIndex: staffOffset + Math.max(0, staffNumber - 1),\n          durationReal,\n          measureIndex,\n          hidden: note.getAttribute('print-object') === 'no',\n        });\n      }\n    });\n\n    staffOffset += staffCount;\n  }\n\n  return model;\n}\n"],"mappings":";AAwBO,SAAS,aAAa,KAAqB;AAChD,QAAM,MAAM,IAAI,UAAU,EAAE,gBAAgB,KAAK,iBAAiB;AAClE,MAAI,IAAI,cAAc,aAAa,EAAG,QAAO;AAE7C,QAAM,QAAQ,MAAM,KAAK,IAAI,iBAAiB,uBAAuB,CAAC;AACtE,QAAM,QAAQ,CAAC,MAAM,YAAY;AAC/B,eAAW,WAAW,MAAM,KAAK,KAAK,iBAAiB,SAAS,CAAC,GAAG;AAClE,YAAM,SAAS,QAAQ,aAAa,QAAQ,KAAK;AACjD,YAAM,QAAQ,MAAM,KAAK,QAAQ,QAAQ,EAAE,OAAO,CAAC,OAAO,GAAG,YAAY,MAAM;AAC/E,YAAM,QAAQ,CAAC,MAAM,YAAY;AAC/B,aAAK,aAAa,MAAM,KAAK,OAAO,IAAI,MAAM,IAAI,OAAO,EAAE;AAAA,MAC7D,CAAC;AAAA,IACH;AAAA,EACF,CAAC;AAED,SAAO,IAAI,cAAc,EAAE,kBAAkB,GAAG;AAClD;AAuDO,SAAS,aAAa,KAAqB;AAChD,QAAM,MAAM,IAAI,UAAU,EAAE,gBAAgB,KAAK,iBAAiB;AAClE,MAAI,IAAI,cAAc,aAAa,EAAG,QAAO;AAC7C,QAAM,OAAO,IAAI;AACjB,MAAI,CAAC,QAAQ,KAAK,YAAY,iBAAkB,QAAO;AACvD,QAAM,CAAC,SAAS,IAAI,cAAc,MAAM,MAAM;AAC9C,SAAO,YAAY,cAAc,WAAW,SAAS,EAAE,SAAS;AAClE;AAEO,SAAS,mBAAmB,KAAa,uBAAkD;AAChG,QAAM,MAAM,IAAI,UAAU,EAAE,gBAAgB,KAAK,iBAAiB;AAClE,MAAI,IAAI,cAAc,aAAa,EAAG,QAAO;AAE7C,QAAM,OAAO,IAAI;AACjB,MAAI,CAAC,QAAQ,KAAK,YAAY,iBAAkB,QAAO;AAEvD,aAAW,QAAQ,cAAc,MAAM,MAAM,GAAG;AAC9C,UAAM,WAAW,cAAc,MAAM,SAAS;AAC9C,eAAW,OAAO,uBAAuB;AACvC,UAAI,CAAC,OAAO,UAAU,GAAG,KAAK,OAAO,KAAK,OAAO,SAAS,OAAQ;AAClE,YAAM,UAAU,SAAS,GAAG;AAC5B,YAAM,gBAAgB,gBAAgB,SAAS,OAAO;AACtD,UAAI,eAAe;AACjB,sBAAc,aAAa,cAAc,KAAK;AAAA,MAChD,OAAO;AACL,cAAM,UAAU,IAAI,cAAc,OAAO;AACzC,gBAAQ,aAAa,cAAc,KAAK;AACxC,gBAAQ,aAAa,SAAS,QAAQ,UAAU;AAAA,MAClD;AAAA,IACF;AAAA,EACF;AAEA,SAAO,IAAI,cAAc,EAAE,kBAAkB,GAAG;AAClD;AAWO,SAAS,qBAAqB,eAAuB,SAA2B;AACrF,MAAI,WAAW,KAAK,iBAAiB,EAAG,QAAO,CAAC;AAChD,QAAM,MAAM,KAAK,KAAK,gBAAgB,OAAO;AAC7C,MAAI,OAAO,EAAG,QAAO,CAAC;AACtB,QAAM,SAAmB,CAAC;AAC1B,WAAS,IAAI,KAAK,IAAI,eAAe,KAAK,IAAK,QAAO,KAAK,CAAC;AAC5D,SAAO;AACT;AAgCO,SAAS,kBAAkB,WAAmB,OAAyB;AAC5E,MAAI,CAAC,OAAO,SAAS,SAAS,KAAK,CAAC,OAAO,SAAS,KAAK,EAAG,QAAO,CAAC;AACpE,MAAI,SAAS,KAAK,aAAa,EAAG,QAAO,CAAC;AAC1C,MAAI,QAAQ,KAAK,KAAK,YAAY,KAAK;AACvC,MAAI,MAAM,KAAK,KAAK,YAAY,KAAK;AACrC,SAAO,QAAQ,KAAK,aAAa,QAAQ,KAAK,MAAM,GAAG;AACrD;AACA,UAAM,KAAK,KAAK,YAAY,KAAK;AAAA,EACnC;AACA,SAAO,qBAAqB,WAAW,KAAK;AAC9C;AA2BO,SAAS,mBACd,WACA,eACA,OACU;AACV,MAAI,CAAC,OAAO,SAAS,SAAS,KAAK,aAAa,EAAG,QAAO,CAAC;AAC3D,QAAM,SAAS,cAAc,OAAO,CAAC,MAAM,OAAO,UAAU,CAAC,KAAK,IAAI,KAAK,IAAI,SAAS;AACxF,QAAM,aAAa,MAAM,KAAK,oBAAI,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,MAAM,IAAI,CAAC;AAE3E,QAAM,SAAS,oBAAI,IAAY;AAE/B,MAAI,QAAQ,GAAG;AACb,aAAS,IAAI,GAAG,IAAI,WAAW,QAAQ,KAAK;AAC1C,YAAM,QAAQ,WAAW,CAAC;AAC1B,YAAM,MAAM,IAAI,IAAI,WAAW,SAAS,WAAW,IAAI,CAAC,IAAI;AAC5D,iBAAW,OAAO,kBAAkB,MAAM,OAAO,KAAK,EAAG,QAAO,IAAI,QAAQ,GAAG;AAAA,IACjF;AAAA,EACF;AAEA,aAAW,KAAK,OAAQ,QAAO,IAAI,CAAC;AAEpC,SAAO,MAAM,KAAK,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,IAAI,CAAC;AAChD;AA6DA,IAAM,gBAAwC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG;AAE1F,SAAS,gBAAgB,IAAa,KAA6B;AACjE,aAAW,KAAK,MAAM,KAAK,GAAG,QAAQ,EAAG,KAAI,EAAE,YAAY,IAAK,QAAO;AACvE,SAAO;AACT;AACA,SAAS,cAAc,IAAa,KAAwB;AAC1D,SAAO,MAAM,KAAK,GAAG,QAAQ,EAAE,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG;AAChE;AACA,SAAS,OAAO,IAAmC;AACjD,SAAO,MAAM,GAAG,eAAe,OAAO,GAAG,YAAY,KAAK,IAAI;AAChE;AAEA,SAAS,qBAAqB,SAA0B;AACtD,QAAM,OAAO,OAAO,gBAAgB,SAAS,MAAM,CAAC,KAAK;AACzD,QAAM,SAAS,OAAO,OAAO,gBAAgB,SAAS,QAAQ,CAAC,KAAK,GAAG;AACvE,QAAM,QAAQ,OAAO,OAAO,gBAAgB,SAAS,OAAO,CAAC,KAAK,GAAG;AACrE,SAAO,MAAM,SAAS,MAAM,cAAc,IAAI,KAAK,KAAK,KAAK,MAAM,KAAK;AAC1E;AAMA,SAAS,eAAe,MAAuB;AAC7C,MAAI,cAAc;AAClB,aAAW,SAAS,cAAc,MAAM,SAAS,EAAE,QAAQ,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC,GAAG;AACjG,UAAM,SAAS,OAAO,OAAO,gBAAgB,OAAO,QAAQ,CAAC,KAAK,GAAG;AACrE,QAAI,SAAS,YAAa,eAAc;AAAA,EAC1C;AACA,MAAI,cAAc,EAAG,QAAO;AAE5B,MAAI,WAAW;AACf,aAAW,WAAW,cAAc,MAAM,SAAS,GAAG;AACpD,eAAW,QAAQ,cAAc,SAAS,MAAM,GAAG;AACjD,YAAM,QAAQ,OAAO,OAAO,gBAAgB,MAAM,OAAO,CAAC,KAAK,GAAG;AAClE,UAAI,QAAQ,SAAU,YAAW;AAAA,IACnC;AAAA,EACF;AACA,SAAO,KAAK,IAAI,GAAG,QAAQ;AAC7B;AAoBO,SAAS,iBAAiB,YAA4C;AAC3E,QAAM,QAAQ,oBAAI,IAAuB;AACzC,MAAI;AACJ,MAAI;AACF,UAAM,IAAI,UAAU,EAAE,gBAAgB,YAAY,iBAAiB;AAAA,EACrE,QAAQ;AACN,WAAO;AAAA,EACT;AACA,MAAI,IAAI,cAAc,aAAa,EAAG,QAAO;AAC7C,QAAM,OAAO,IAAI;AACjB,MAAI,CAAC,QAAQ,KAAK,YAAY,iBAAkB,QAAO;AAEvD,QAAM,QAAQ,cAAc,MAAM,MAAM;AACxC,MAAI,cAAc;AAElB,aAAW,QAAQ,OAAO;AACxB,UAAM,aAAa,eAAe,IAAI;AACtC,QAAI,YAAY;AAChB,UAAM,aAAa,cAAc,MAAM,SAAS;AAEhD,eAAW,QAAQ,CAAC,WAAW,iBAAiB;AAC9C,iBAAW,SAAS,MAAM,KAAK,UAAU,QAAQ,GAAG;AAClD,YAAI,MAAM,YAAY,cAAc;AAClC,gBAAM,UAAU,OAAO,gBAAgB,OAAO,WAAW,CAAC;AAC1D,cAAI,QAAS,aAAY,OAAO,OAAO,KAAK;AAC5C;AAAA,QACF;AACA,YAAI,MAAM,YAAY,OAAQ;AAC9B,cAAM,OAAO;AACb,cAAM,KAAK,KAAK,aAAa,IAAI;AACjC,YAAI,CAAC,GAAI;AAET,cAAM,UAAU,CAAC,CAAC,gBAAgB,MAAM,OAAO;AAC/C,cAAM,SAAS,CAAC,CAAC,gBAAgB,MAAM,MAAM;AAC7C,cAAM,UAAU,gBAAgB,MAAM,OAAO;AAC7C,cAAM,cAAc,OAAO,OAAO,gBAAgB,MAAM,OAAO,CAAC,KAAK,GAAG,KAAK;AAC7E,cAAM,eAAe,OAAO,gBAAgB,MAAM,UAAU,CAAC;AAC7D,cAAM,eACJ,WAAW,CAAC,eAAe,IAAI,OAAO,YAAY,IAAI,YAAY;AAEpE,cAAM,gBAAgB,cAAc,MAAM,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,MAAM,MAAM,MAAM;AAC9F,cAAM,cAAc,gBAAgB,MAAM,WAAW;AACrD,cAAM,iBAAiB,cACnB,cAAc,aAAa,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,MAAM,MAAM,MAAM,IAChF;AAEJ,cAAM,IAAI,IAAI;AAAA,UACZ,MAAM,UAAU,qBAAqB,OAAO,IAAI;AAAA,UAChD;AAAA,UACA,iBAAiB,iBAAiB;AAAA,UAClC,YAAY,cAAc,KAAK,IAAI,GAAG,cAAc,CAAC;AAAA,UACrD;AAAA,UACA;AAAA,UACA,QAAQ,KAAK,aAAa,cAAc,MAAM;AAAA,QAChD,CAAC;AAAA,MACH;AAAA,IACF,CAAC;AAED,mBAAe;AAAA,EACjB;AAEA,SAAO;AACT;","names":[]}

package/dist/notationBeams.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Re-derive every `<beam>` in `xml` from the time signature: beam within a
+ * beat, break at rests, never span a beat boundary.
+ *
+ * Existing beams are DISCARDED rather than merged — a malformed group
+ * (unclosed, or an `end` with no `begin`) is precisely the input this exists
+ * to repair, so trusting any of it would defeat the purpose.
+ *
+ * Details that are engraving decisions, not implementation accidents:
+ *  - Compound meters (6/8, 9/8, 12/8) group in dotted beats — three eighths —
+ *    because that is what makes them read as compound rather than as fast
+ *    simple time. 3/8 and 3/4 are simple and group per beat.
+ *  - Chord members never carry beams; only a chord's first note does.
+ *  - Grace notes are left untouched. Their beaming belongs to the ornament
+ *    they decorate, not to the beat grid.
+ *  - A beat holding a single beamable note gets NO beam — that note takes a
+ *    flag, which is correct engraving, not a missing feature.
+ *  - Beams never cross a staff or voice change; each (staff, voice) stream is
+ *    grouped independently.
+ *
+ * Malformed input (fails to parse) is returned unchanged, the same defensive
+ * stance as `stampNoteIds`/`injectSystemBreaks` in ./notationXml.ts.
+ */
+declare function rebeamByMeter(xml: string): string;
+
+export { rebeamByMeter };

package/dist/notationBeams.js

@@ -0,0 +1,133 @@
+// src/notationBeams.ts
+var BEAM_COUNT_BY_TYPE = {
+  eighth: 1,
+  "16th": 2,
+  "32nd": 3,
+  "64th": 4,
+  "128th": 5,
+  "256th": 6
+};
+function intText(parent, tag) {
+  const el = parent.querySelector(`:scope > ${tag}`);
+  const n = el ? Number(el.textContent) : NaN;
+  return Number.isFinite(n) ? n : null;
+}
+function insertBeam(note, beam) {
+  const before = note.querySelector(":scope > notations, :scope > lyric");
+  if (before) note.insertBefore(beam, before);
+  else note.appendChild(beam);
+}
+function emitBeams(doc, run) {
+  const maxLevel = Math.max(...run.map((n) => n.beams));
+  for (let level = 1; level <= maxLevel; level++) {
+    let i = 0;
+    while (i < run.length) {
+      if (run[i].beams < level) {
+        i++;
+        continue;
+      }
+      let j = i;
+      while (j + 1 < run.length && run[j + 1].beams >= level) j++;
+      if (j > i) {
+        for (let k = i; k <= j; k++) {
+          const beam = doc.createElement("beam");
+          beam.setAttribute("number", String(level));
+          beam.textContent = k === i ? "begin" : k === j ? "end" : "continue";
+          insertBeam(run[k].el, beam);
+        }
+      } else if (level > 1) {
+        const beam = doc.createElement("beam");
+        beam.setAttribute("number", String(level));
+        beam.textContent = i === 0 ? "forward hook" : "backward hook";
+        insertBeam(run[i].el, beam);
+      }
+      i = j + 1;
+    }
+  }
+}
+function rebeamByMeter(xml) {
+  const doc = new DOMParser().parseFromString(xml, "application/xml");
+  if (doc.querySelector("parsererror")) return xml;
+  for (const part of Array.from(doc.querySelectorAll("score-partwise > part"))) {
+    let divisions = 1;
+    let beats = 4;
+    let beatType = 4;
+    for (const measure of Array.from(part.querySelectorAll("measure"))) {
+      const attrs = measure.querySelector(":scope > attributes");
+      if (attrs) {
+        divisions = intText(attrs, "divisions") ?? divisions;
+        const time = attrs.querySelector(":scope > time");
+        if (time) {
+          beats = intText(time, "beats") ?? beats;
+          beatType = intText(time, "beat-type") ?? beatType;
+        }
+      }
+      const beatDivs = divisions * 4 / beatType;
+      const compound = beatType >= 8 && beats % 3 === 0 && beats > 3;
+      const groupDivs = compound ? beatDivs * 3 : beatDivs;
+      if (!(groupDivs > 0)) continue;
+      const streams = /* @__PURE__ */ new Map();
+      let pos = 0;
+      for (const el of Array.from(measure.children)) {
+        if (el.tagName === "backup") {
+          pos -= intText(el, "duration") ?? 0;
+          continue;
+        }
+        if (el.tagName === "forward") {
+          pos += intText(el, "duration") ?? 0;
+          continue;
+        }
+        if (el.tagName !== "note") continue;
+        const isGrace = !!el.querySelector(":scope > grace");
+        const isChord = !!el.querySelector(":scope > chord");
+        const isRest = !!el.querySelector(":scope > rest");
+        const dur = intText(el, "duration") ?? 0;
+        const type = el.querySelector(":scope > type")?.textContent?.trim() ?? "";
+        if (!isGrace) {
+          for (const b of Array.from(el.querySelectorAll(":scope > beam"))) b.remove();
+        }
+        if (!isGrace && !isChord) {
+          const staff = el.querySelector(":scope > staff")?.textContent?.trim() ?? "1";
+          const voice = el.querySelector(":scope > voice")?.textContent?.trim() ?? "1";
+          const key = `${staff}:${voice}`;
+          let stream = streams.get(key);
+          if (!stream) {
+            stream = [];
+            streams.set(key, stream);
+          }
+          stream.push({
+            el,
+            start: pos,
+            beams: isRest ? 0 : BEAM_COUNT_BY_TYPE[type] ?? 0
+          });
+          pos += dur;
+        }
+      }
+      for (const notes of streams.values()) {
+        let run = [];
+        const flush = () => {
+          if (run.length >= 2) emitBeams(doc, run);
+          run = [];
+        };
+        for (const note of notes) {
+          if (note.beams === 0) {
+            flush();
+            continue;
+          }
+          if (run.length) {
+            const prev = run[run.length - 1];
+            const sameBeat = Math.floor(prev.start / groupDivs) === Math.floor(note.start / groupDivs);
+            if (!sameBeat) flush();
+          }
+          run.push(note);
+        }
+        flush();
+      }
+    }
+  }
+  return new XMLSerializer().serializeToString(doc);
+}
+export {
+  rebeamByMeter
+};
+//# sourceMappingURL=notationBeams.js.map

package/dist/notationBeams.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/notationBeams.ts"],"sourcesContent":["// Beam grouping — the part of engraving the ENGRAVER cannot supply.\n//\n// Verovio does NOT auto-beam imported MusicXML. Strip a score's `<beam>`\n// elements and every eighth/sixteenth comes out with an individual flag\n// (measured on the RSR corpus: 566 beams removed -> 0 beams, 22 flags). Beam\n// grouping is therefore entirely whatever the source file encodes, and a\n// generator that emits beams spanning beat boundaries — or unbalanced groups\n// (`begin` with no `end`) — produces engraving that nothing downstream can\n// improve by rendering harder.\n//\n// This lives in web-core rather than in a consumer app on purpose: beaming is\n// a fact about how notation is DISPLAYED, which this package owns. An app\n// re-deriving it would be inferring something the notation layer holds\n// authoritatively — the exact move the owned-layer rule exists to prevent.\n//\n// Sibling of ./notationXml.ts (stampNoteIds / injectSystemBreaks) and follows\n// its conventions: pure XML-in → XML-out, DOMParser/XMLSerializer, and\n// malformed input returned unchanged rather than thrown on.\n\nconst BEAM_COUNT_BY_TYPE: Record<string, number> = {\n  eighth: 1, '16th': 2, '32nd': 3, '64th': 4, '128th': 5, '256th': 6,\n};\n\ninterface BeamNote {\n  el: Element;\n  /** Divisions from the start of the measure. */\n  start: number;\n  /** Number of beams this note's `<type>` implies; 0 for rests. */\n  beams: number;\n}\n\nfunction intText(parent: Element, tag: string): number | null {\n  const el = parent.querySelector(`:scope > ${tag}`);\n  const n = el ? Number(el.textContent) : NaN;\n  return Number.isFinite(n) ? n : null;\n}\n\n/** Where a `<beam>` may legally sit inside `<note>`: after `<stem>`/`<staff>`,\n *  before `<notations>`/`<lyric>`. Verovio is lenient about this, but emitting\n *  schema-ordered output keeps the result usable by anything else that reads\n *  MusicXML. */\nfunction insertBeam(note: Element, beam: Element): void {\n  const before = note.querySelector(':scope > notations, :scope > lyric');\n  if (before) note.insertBefore(beam, before);\n  else note.appendChild(beam);\n}\n\n/** Emit level-1 begin/continue/end across `run`, then per-level maximal runs\n *  for levels 2+, with hooks for a shorter note that has no partner. */\nfunction emitBeams(doc: Document, run: BeamNote[]): void {\n  const maxLevel = Math.max(...run.map((n) => n.beams));\n  for (let level = 1; level <= maxLevel; level++) {\n    let i = 0;\n    while (i < run.length) {\n      if (run[i].beams < level) { i++; continue; }\n      let j = i;\n      while (j + 1 < run.length && run[j + 1].beams >= level) j++;\n      if (j > i) {\n        for (let k = i; k <= j; k++) {\n          const beam = doc.createElement('beam');\n          beam.setAttribute('number', String(level));\n          beam.textContent = k === i ? 'begin' : k === j ? 'end' : 'continue';\n          insertBeam(run[k].el, beam);\n        }\n      } else if (level > 1) {\n        // A lone 16th among 8ths gets a hook, not a beam it has no partner\n        // for. It points backward unless it opens the group.\n        const beam = doc.createElement('beam');\n        beam.setAttribute('number', String(level));\n        beam.textContent = i === 0 ? 'forward hook' : 'backward hook';\n        insertBeam(run[i].el, beam);\n      }\n      i = j + 1;\n    }\n  }\n}\n\n/**\n * Re-derive every `<beam>` in `xml` from the time signature: beam within a\n * beat, break at rests, never span a beat boundary.\n *\n * Existing beams are DISCARDED rather than merged — a malformed group\n * (unclosed, or an `end` with no `begin`) is precisely the input this exists\n * to repair, so trusting any of it would defeat the purpose.\n *\n * Details that are engraving decisions, not implementation accidents:\n *  - Compound meters (6/8, 9/8, 12/8) group in dotted beats — three eighths —\n *    because that is what makes them read as compound rather than as fast\n *    simple time. 3/8 and 3/4 are simple and group per beat.\n *  - Chord members never carry beams; only a chord's first note does.\n *  - Grace notes are left untouched. Their beaming belongs to the ornament\n *    they decorate, not to the beat grid.\n *  - A beat holding a single beamable note gets NO beam — that note takes a\n *    flag, which is correct engraving, not a missing feature.\n *  - Beams never cross a staff or voice change; each (staff, voice) stream is\n *    grouped independently.\n *\n * Malformed input (fails to parse) is returned unchanged, the same defensive\n * stance as `stampNoteIds`/`injectSystemBreaks` in ./notationXml.ts.\n */\nexport function rebeamByMeter(xml: string): string {\n  const doc = new DOMParser().parseFromString(xml, 'application/xml');\n  if (doc.querySelector('parsererror')) return xml;\n\n  for (const part of Array.from(doc.querySelectorAll('score-partwise > part'))) {\n    // divisions and the time signature persist across measures until restated.\n    let divisions = 1;\n    let beats = 4;\n    let beatType = 4;\n\n    for (const measure of Array.from(part.querySelectorAll('measure'))) {\n      const attrs = measure.querySelector(':scope > attributes');\n      if (attrs) {\n        divisions = intText(attrs, 'divisions') ?? divisions;\n        const time = attrs.querySelector(':scope > time');\n        if (time) {\n          beats = intText(time, 'beats') ?? beats;\n          beatType = intText(time, 'beat-type') ?? beatType;\n        }\n      }\n\n      const beatDivs = (divisions * 4) / beatType;\n      const compound = beatType >= 8 && beats % 3 === 0 && beats > 3;\n      const groupDivs = compound ? beatDivs * 3 : beatDivs;\n      if (!(groupDivs > 0)) continue;\n\n      // Walk in document order, tracking position through backup/forward, and\n      // bucket notes by the (staff, voice) stream they belong to.\n      const streams = new Map<string, BeamNote[]>();\n      let pos = 0;\n\n      for (const el of Array.from(measure.children)) {\n        if (el.tagName === 'backup') { pos -= intText(el, 'duration') ?? 0; continue; }\n        if (el.tagName === 'forward') { pos += intText(el, 'duration') ?? 0; continue; }\n        if (el.tagName !== 'note') continue;\n\n        const isGrace = !!el.querySelector(':scope > grace');\n        const isChord = !!el.querySelector(':scope > chord');\n        const isRest = !!el.querySelector(':scope > rest');\n        const dur = intText(el, 'duration') ?? 0;\n        const type = el.querySelector(':scope > type')?.textContent?.trim() ?? '';\n\n        // Wipe first: every beam in the output is re-derived below. Grace\n        // notes keep whatever they came with.\n        if (!isGrace) {\n          for (const b of Array.from(el.querySelectorAll(':scope > beam'))) b.remove();\n        }\n\n        if (!isGrace && !isChord) {\n          const staff = el.querySelector(':scope > staff')?.textContent?.trim() ?? '1';\n          const voice = el.querySelector(':scope > voice')?.textContent?.trim() ?? '1';\n          const key = `${staff}:${voice}`;\n          let stream = streams.get(key);\n          if (!stream) { stream = []; streams.set(key, stream); }\n          stream.push({\n            el, start: pos,\n            beams: isRest ? 0 : (BEAM_COUNT_BY_TYPE[type] ?? 0),\n          });\n          // Grace notes steal no time; chord members share the previous onset.\n          pos += dur;\n        }\n      }\n\n      for (const notes of streams.values()) {\n        let run: BeamNote[] = [];\n        const flush = (): void => {\n          if (run.length >= 2) emitBeams(doc, run);\n          run = [];\n        };\n        for (const note of notes) {\n          if (note.beams === 0) { flush(); continue; }\n          if (run.length) {\n            const prev = run[run.length - 1];\n            const sameBeat = Math.floor(prev.start / groupDivs) === Math.floor(note.start / groupDivs);\n            if (!sameBeat) flush();\n          }\n          run.push(note);\n        }\n        flush();\n      }\n    }\n  }\n\n  return new XMLSerializer().serializeToString(doc);\n}\n"],"mappings":"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","names":[]}

package/dist/notationPlayerVerovio.d.ts

@@ -1,64 +1,8 @@
 import { N as NotationLayout } from './notationGeometry-DqVBgL7F.js';
 import { EngravedNote } from './notationPlayerSvg.js';
+import { NoteModel } from './notationXml.js';
 import './promo.js';
 
-/** One `<note>`'s MODEL identity — the ground truth `EngravedNote`
- *  (notationPlayerSvg.ts) needs that Verovio's rendered SVG cannot supply on
- *  its own (a rendered `g.note`/`g.rest` carries geometry, not pitch/tie/
- *  duration semantics). Keyed by the note's stamped `id` in
- *  `notePositions()`'s return of `verovioEngravedNotes`
- *  (notationPlayerVerovio.ts). */
-interface NoteModel {
-    /** `12*(octave+1) + stepSemitone + alter` — the standard MusicXML→MIDI
-     *  conversion (the same formula stave-web-sightread's own
-     *  `practice/probeInputs.ts:pitchMidi` uses — a universal formula, not app
-     *  logic, so this is not an owned-layer violation to restate here). `null`
-     *  for a rest or an `<unpitched>` note (no `<pitch>` child) — mirrors
-     *  `EngravedNote.midi`'s own "null covers both" contract. */
-    midi: number | null;
-    /** Has a `<rest/>` child. */
-    isRest: boolean;
-    /** True for the STOP half of a tie — a direct `<tie type="stop">` child OR
-     *  `<notations><tied type="stop">` (exporters vary on which they emit;
-     *  either counts) — matches `EngravedNote.tieContinuation`'s "continuation
-     *  note of a tie, not the struck start" contract. */
-    tieContinuation: boolean;
-    /** 0-based, matching `EngravedNote.staffIndex`'s "0 = top staff of the
-     *  system" contract: every `<part>` is walked in document order, and
-     *  every DISTINCT staff within it (by `<attributes><staves>` when
-     *  present, else the highest `<staff>` number any of its notes uses, else
-     *  1) is assigned the next index — so a single-part 2-staff piano score
-     *  numbers 0/1 by `<staff>`, and a 2-part 1-staff-per-part reduction (this
-     *  app's own chord+bass shape) numbers 0/1 by PART, with neither case
-     *  needing different code. */
-    staffIndex: number;
-    /** Whole-note fraction (0.25 = quarter) — `duration / divisions / 4`,
-     *  divisions tracked per-part from the LAST `<attributes><divisions>`
-     *  seen at or before this note (MusicXML: divisions persist until
-     *  overridden, default 1). 0 for a grace note (no `<duration>` child —
-     *  the true, spec-correct signal; never guessed from `<type>`). */
-    durationReal: number;
-    /** 0-based position of this note's `<measure>` among its OWN `<part>`'s
-     *  measure children, in document order. Informational only — the live
-     *  join (`verovioOnsetColumns`/`verovioEngravedNotes`, both in
-     *  notationPlayerVerovio.ts) resolves the note's RENDERED measure index
-     *  from the live SVG DOM independently (Verovio's own render order, which
-     *  is what geometry/hit-testing must agree with), never from this field. */
-    measureIndex: number;
-    /** `print-object="no"` on the source `<note>` (stave's `hideDoubledNotes`
-     *  sets this on editorially-doubled notes/rests before handing MusicXML to
-     *  this player). Verovio's importer HONORS this for `<note>` elements
-     *  carrying a `<pitch>` (renders `visibility="hidden"` on its own,
-     *  empirically confirmed against a real 6.2.0 render) but does NOT honor
-     *  it for `<rest>` notes (the `<g class="rest">` renders fully visible
-     *  regardless — same empirical check). `createVerovioNotationPlayer`
-     *  reads this field to force `visibility="hidden"` after every render for
-     *  ANY id where it's true — a no-op re-application on notes Verovio
-     *  already hid, and the actual fix on the rests it doesn't (see that
-     *  module's `applyPrintObjectHiding`). */
-    hidden: boolean;
-}
-
 /** Restated independently, not imported as a VALUE from notationPlayerSvg.ts
  *  — same reasoning as `MAX_ENGRAVE_WIDTH_VRV` vs `MAX_ENGRAVE_WIDTH_SVG`
  *  (below): a runtime (non-`type`) import from notationPlayerSvg.ts would
@@ -397,6 +341,31 @@ interface VerovioLayoutOptions {
      * glyphs get, can opt back into the pre-existing behavior.
      */
     minFitFactor?: number;
+    /**
+     * BREAK PLAN — target bars per line. When set (`> 0`), the player plans
+     * system breaks itself (`sectionAwareBreaks`, balanced with a widow
+     * back-off) and encodes them into the document before the first engrave,
+     * forcing `breaks: 'line'`. Leave unset (or `0`) to let Verovio's own
+     * `breaks: 'auto'` decide, which is the default and is content-aware.
+     *
+     * Combine with `sectionStarts` to keep the balancing inside each section.
+     * A PLAYER option, not a Verovio one — stripped in `verovioRenderOptions`
+     * before `setOptions` sees it.
+     */
+    barsPerLine?: number;
+    /**
+     * BREAK PLAN — 0-based measure POSITIONS at which a musical section
+     * begins. Each one > 0 becomes a hard system break, so a section always
+     * starts its own line; `barsPerLine`'s balancing then runs within each
+     * section's span rather than across the whole excerpt.
+     *
+     * POSITIONS, not MusicXML `<measure number>` attributes — scores skip bar
+     * numbers, so a caller holding bar-numbered section labels must convert
+     * first (`measureCount`'s doc explains the coordinate). Setting this alone
+     * (no `barsPerLine`) is the "break at sections, otherwise let the engraver
+     * decide" mode. A PLAYER option — stripped in `verovioRenderOptions`.
+     */
+    sectionStarts?: readonly number[];
 }
 /**
  * Layout defaults applied to EVERY engrave (initial + every reflow) unless a