@real-music-packages/web-core 0.46.0 → 0.48.0

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/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
@@ -511,6 +480,21 @@ declare const DEFAULT_MIN_FIT_FACTOR = 0.75;
  * condition is unit-testable independent of a real engrave.
  */
 declare function shouldFallbackToAutoBreaks(factor: number, breaks: VerovioLayoutOptions['breaks'] | undefined, minFitFactor: number): boolean;
+/** True when fitting the current engraving would cross the caller's
+ * readability floor. Shared by the encoded-break fallback and auto's
+ * narrower re-plan path so the two policies cannot drift. */
+declare function isBelowReadabilityFloor(factor: number, minFitFactor: number): boolean;
+/** One narrower candidate for the auto-break readability floor, or null when
+ * the measured fit already holds the floor (or one bar is the terminal
+ * layout). Uses ceiling-halves so 4 -> 2 -> 1 and 3 -> 2 -> 1. */
+declare function nextReadabilityFloorBarsPerLine(currentBarsPerLine: number, fittedZoomFactor: number, minFitFactor: number): number | null;
+/**
+ * Pure planner seam for the width-aware auto floor. `fittedZoomAt` is the
+ * measured-layout oracle: production obtains each measurement by engraving
+ * that candidate, while jsdom-free tests can supply deterministic factors.
+ * The returned list is the sequence to try; its final `1` is terminal.
+ */
+declare function readabilityFloorPlan(initialBarsPerLine: number, widthPx: number, minFitFactor: number, fittedZoomAt: (barsPerLine: number, widthPx: number) => number): number[];
 /**
  * Semantic zoom → Verovio options. The migration spike's `zoom-test*.mjs`
  * proved `pageWidth` (Verovio's line-breaking width, in ITS OWN units)
@@ -557,4 +541,4 @@ declare const MAX_ENGRAVE_WIDTH_VRV = 1400;
  *  (in stave-web-sightread) §2 for the full design. */
 declare function createVerovioNotationPlayer(opts: CreateVerovioNotationPlayerOpts): VerovioNotationPlayer;
 
-export { type CreateVerovioNotationPlayerOpts, DEFAULT_MIN_FIT_FACTOR, EngravedNote, MARKED_NOTE_CLASS, MAX_ENGRAVE_WIDTH_VRV, VEROVIO_BASE_SCALE, VEROVIO_LAYOUT_DEFAULTS, VEROVIO_MAX_SCALE, VEROVIO_MIN_SCALE, type VerovioLayoutOptions, type VerovioNotationPlayer, type VerovioOnset, type VerovioRenderOptions, applyPrintObjectHiding, createVerovioNotationPlayer, fitZoomFactor, shouldFallbackToAutoBreaks, systemMeasureCounts, verovioEngravedNotes, verovioNotationLayout, verovioNotesAtColumn, verovioOnsetColumns, verovioRenderOptions, verovioZoomOptions };
+export { type CreateVerovioNotationPlayerOpts, DEFAULT_MIN_FIT_FACTOR, EngravedNote, MARKED_NOTE_CLASS, MAX_ENGRAVE_WIDTH_VRV, VEROVIO_BASE_SCALE, VEROVIO_LAYOUT_DEFAULTS, VEROVIO_MAX_SCALE, VEROVIO_MIN_SCALE, type VerovioLayoutOptions, type VerovioNotationPlayer, type VerovioOnset, type VerovioRenderOptions, applyPrintObjectHiding, createVerovioNotationPlayer, fitZoomFactor, isBelowReadabilityFloor, nextReadabilityFloorBarsPerLine, readabilityFloorPlan, shouldFallbackToAutoBreaks, systemMeasureCounts, verovioEngravedNotes, verovioNotationLayout, verovioNotesAtColumn, verovioOnsetColumns, verovioRenderOptions, verovioZoomOptions };

package/dist/notationPlayerVerovio.js

@@ -10,138 +10,14 @@ import {
   vstackAudioPlayheadLine
 } from "./chunk-DBFGX6OK.js";
 import "./chunk-PVZXLC23.js";
-
-// 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 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;
-}
-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;
-}
+import {
+  balancedSystemBreaks,
+  injectSystemBreaks,
+  measureCount,
+  noteModelFromXml,
+  sectionAwareBreaks,
+  stampNoteIds
+} from "./chunk-JCDNEJBT.js";
 
 // src/notationPlayerVerovio.ts
 var MARKED_NOTE_CLASS = "rmp-note-marked";
@@ -396,7 +272,13 @@ var VEROVIO_LAYOUT_DEFAULTS = {
 };
 function verovioRenderOptions(hostWidthPx, zoom, layout) {
   const { scale, pageWidth } = verovioZoomOptions(hostWidthPx, zoom);
-  const { avoidWidows: _avoidWidows, minFitFactor: _minFitFactor, ...verovioLayout } = layout ?? {};
+  const {
+    avoidWidows: _avoidWidows,
+    minFitFactor: _minFitFactor,
+    barsPerLine: _barsPerLine,
+    sectionStarts: _sectionStarts,
+    ...verovioLayout
+  } = layout ?? {};
   return {
     ...VEROVIO_LAYOUT_DEFAULTS,
     ...verovioLayout,
@@ -419,10 +301,31 @@ function fitZoomFactor(systemWidthsPx, engraveWidthPx) {
 }
 var DEFAULT_MIN_FIT_FACTOR = 0.75;
 function shouldFallbackToAutoBreaks(factor, breaks, minFitFactor) {
-  if (!Number.isFinite(factor)) return false;
-  if (!(minFitFactor > 0)) return false;
+  if (!isBelowReadabilityFloor(factor, minFitFactor)) return false;
   if (breaks !== "line" && breaks !== "encoded") return false;
-  return factor < minFitFactor;
+  return true;
+}
+function isBelowReadabilityFloor(factor, minFitFactor) {
+  return Number.isFinite(factor) && Number.isFinite(minFitFactor) && minFitFactor > 0 && factor < minFitFactor;
+}
+function nextReadabilityFloorBarsPerLine(currentBarsPerLine, fittedZoomFactor, minFitFactor) {
+  if (!isBelowReadabilityFloor(fittedZoomFactor, minFitFactor)) return null;
+  if (!Number.isFinite(currentBarsPerLine) || currentBarsPerLine <= 1) return null;
+  return Math.max(1, Math.ceil(currentBarsPerLine / 2));
+}
+function readabilityFloorPlan(initialBarsPerLine, widthPx, minFitFactor, fittedZoomAt) {
+  if (!Number.isFinite(initialBarsPerLine) || initialBarsPerLine <= 0 || !(widthPx > 0)) return [];
+  let bars = Math.max(1, Math.floor(initialBarsPerLine));
+  let factor = fittedZoomAt(bars, widthPx);
+  const plan = [];
+  for (; ; ) {
+    const next = nextReadabilityFloorBarsPerLine(bars, factor, minFitFactor);
+    if (next === null) return plan;
+    plan.push(next);
+    bars = next;
+    factor = fittedZoomAt(bars, widthPx);
+    if (bars === 1) return plan;
+  }
 }
 function verovioZoomOptions(hostWidthPx, zoom) {
   const z = Number.isFinite(zoom) && zoom > 0 ? zoom : 1;
@@ -470,6 +373,19 @@ function createVerovioNotationPlayer(opts) {
   }
   const stampedXml = opts.rendered ? musicXml : stampNoteIds(musicXml);
   const noteModel = opts.rendered ? /* @__PURE__ */ new Map() : noteModelFromXml(stampedXml);
+  const measureTotal = measureCount(stampedXml);
+  const breakPlan = (() => {
+    const layout = opts.verovioOptions;
+    const starts = layout?.sectionStarts ?? [];
+    const every = layout?.barsPerLine ?? 0;
+    if (!starts.length && !(every > 0)) return [];
+    return sectionAwareBreaks(measureTotal, starts, every);
+  })();
+  const plannedXml = breakPlan.length ? injectSystemBreaks(stampedXml, breakPlan) : stampedXml;
+  function autoFloorPlanXml(barsPerLine) {
+    const positions = barsPerLine <= 1 ? Array.from({ length: Math.max(0, measureTotal - 1) }, (_, i) => i + 1) : sectionAwareBreaks(measureTotal, [], barsPerLine);
+    return positions.length ? injectSystemBreaks(stampedXml, positions) : stampedXml;
+  }
   const root = document.createElement("div");
   root.style.position = "relative";
   root.style.width = "100%";
@@ -581,23 +497,47 @@ function createVerovioNotationPlayer(opts) {
   }
   function engraveOnce(toolkit, widthPx, zoom) {
     const layoutOpts = opts.verovioOptions;
-    const effectiveBreaks = layoutOpts?.breaks ?? VEROVIO_LAYOUT_DEFAULTS.breaks;
+    const planLayoutOpts = breakPlan.length ? { ...layoutOpts, breaks: "line" } : layoutOpts;
+    const effectiveBreaks = planLayoutOpts?.breaks ?? VEROVIO_LAYOUT_DEFAULTS.breaks;
     const minFitFactor = layoutOpts?.minFitFactor ?? DEFAULT_MIN_FIT_FACTOR;
     const avoidWidows = layoutOpts?.avoidWidows !== false;
-    let xmlToRender = stampedXml;
-    let renderLayoutOpts = layoutOpts;
+    let xmlToRender = plannedXml;
+    let renderLayoutOpts = planLayoutOpts;
     toolkit.setOptions(verovioRenderOptions(widthPx, zoom, renderLayoutOpts));
     const ok = !!toolkit.loadData(xmlToRender);
     if (ok) renderAllPages(toolkit);
     rebuildLayoutFromDom();
-    if (ok && avoidWidows && effectiveBreaks === "auto") {
-      const widowed = runWidowPass(toolkit, widthPx, zoom, xmlToRender, renderLayoutOpts);
-      xmlToRender = widowed.xml;
-      renderLayoutOpts = widowed.layoutOpts;
-    }
     if (ok && currentLayout) {
       const systemWidthsPx = () => opts.measureSystemWidths ? opts.measureSystemWidths(svgHost) : currentLayout.systems.map((s) => s.w);
       let factor = fitZoomFactor(systemWidthsPx(), widthPx);
+      let terminalAutoFloorPlan = false;
+      if (effectiveBreaks === "auto") {
+        if (!isBelowReadabilityFloor(factor, minFitFactor) && avoidWidows) {
+          const widowed = runWidowPass(toolkit, widthPx, zoom, xmlToRender, renderLayoutOpts);
+          xmlToRender = widowed.xml;
+          renderLayoutOpts = widowed.layoutOpts;
+          factor = fitZoomFactor(systemWidthsPx(), widthPx);
+        }
+        let barsPerLine = Math.max(1, ...systemMeasureCounts(svgHost));
+        for (; ; ) {
+          const nextBarsPerLine = nextReadabilityFloorBarsPerLine(barsPerLine, factor, minFitFactor);
+          if (nextBarsPerLine === null) break;
+          const floorXml = autoFloorPlanXml(nextBarsPerLine);
+          const floorLayoutOpts = { ...layoutOpts, breaks: "line" };
+          toolkit.setOptions(verovioRenderOptions(widthPx, zoom, floorLayoutOpts));
+          if (!toolkit.loadData(floorXml)) break;
+          renderAllPages(toolkit);
+          rebuildLayoutFromDom();
+          xmlToRender = floorXml;
+          renderLayoutOpts = floorLayoutOpts;
+          factor = fitZoomFactor(systemWidthsPx(), widthPx);
+          barsPerLine = nextBarsPerLine;
+          if (barsPerLine === 1 && isBelowReadabilityFloor(factor, minFitFactor)) {
+            terminalAutoFloorPlan = true;
+            break;
+          }
+        }
+      }
       if (shouldFallbackToAutoBreaks(factor, effectiveBreaks, minFitFactor)) {
         const autoLayoutOpts = { ...layoutOpts, breaks: "auto" };
         toolkit.setOptions(verovioRenderOptions(widthPx, zoom, autoLayoutOpts));
@@ -615,7 +555,7 @@ function createVerovioNotationPlayer(opts) {
           factor = fitZoomFactor(systemWidthsPx(), widthPx);
         }
       }
-      if (factor < 1) {
+      if (factor < 1 && !terminalAutoFloorPlan) {
         const effectiveZoom = zoom * factor;
         toolkit.setOptions(verovioRenderOptions(widthPx, effectiveZoom, renderLayoutOpts));
         const ok2 = !!toolkit.loadData(xmlToRender);
@@ -746,6 +686,9 @@ export {
   applyPrintObjectHiding,
   createVerovioNotationPlayer,
   fitZoomFactor,
+  isBelowReadabilityFloor,
+  nextReadabilityFloorBarsPerLine,
+  readabilityFloorPlan,
   shouldFallbackToAutoBreaks,
   systemMeasureCounts,
   verovioEngravedNotes,