@real-music-packages/web-core 0.45.1 → 0.46.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/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

@@ -148,6 +148,22 @@ interface CreateVerovioNotationPlayerOpts {
      * "why" behind the defaults themselves).
      */
     verovioOptions?: VerovioLayoutOptions;
+    /**
+     * TEST-ONLY SEAM — not part of this player's real production behavior.
+     * When set, `engraveOnce`'s fit-pass/fallback-decision math reads system
+     * widths from this function (called with `svgHost`) instead of
+     * `currentLayout.systems`. Exists because jsdom implements neither
+     * `getBBox` nor a real `getBoundingClientRect` (both always report
+     * zero-size boxes), so `currentLayout.systems` widths — and therefore
+     * `fitZoomFactor`'s result — are always 0/`1` (fits) in a headless test
+     * regardless of how dense the underlying MusicXML actually is. A test can
+     * pass a fixed fake (e.g. `() => [1200]`) to exercise the readability-floor
+     * fallback (`VerovioLayoutOptions.minFitFactor`) end-to-end against a REAL
+     * Verovio engrave, asserting on the resulting DOM shape
+     * (`systemMeasureCounts`) rather than on geometry a real browser would be
+     * needed to produce. Never used by any real caller.
+     */
+    measureSystemWidths?: (root: Element) => number[];
 }
 interface VerovioNotationPlayer {
     /** Resolves once the engraving is in the DOM and ready to draw. `setTime`/
@@ -362,6 +378,25 @@ interface VerovioLayoutOptions {
      * never second-guesses.
      */
     avoidWidows?: boolean;
+    /**
+     * Readability floor for CALLER-ENCODED breaks (`breaks: 'line'` or
+     * `'encoded'`) — see `engraveOnce`'s own "Fallback pass" doc. Stave's own
+     * motivating case: `<print new-system="yes"/>` every 4 bars + `breaks:
+     * 'line'` gets exact N-bars-per-line on normal music, but on dense music
+     * (e.g. a Bach fugue excerpt) the one system between two encoded breaks
+     * can be too wide to fit even at Verovio's minimum spacing — the ONLY
+     * lever `fitZoomFactor` then has left is shrinking the effective zoom,
+     * which on a dense-enough system means unreadably small glyphs. Good
+     * sight-reading software prefers readable glyphs over a fixed bar count.
+     *
+     * A PLAYER option, not a Verovio one — like `avoidWidows`, stripped out in
+     * `verovioRenderOptions` before `setOptions` ever sees it. Default 0.75
+     * (see `shouldFallbackToAutoBreaks`'s own doc for the exact trigger
+     * condition). `minFitFactor: 0` disables the fallback entirely — a caller
+     * who always wants their exact encoded bar count, however small the
+     * glyphs get, can opt back into the pre-existing behavior.
+     */
+    minFitFactor?: number;
 }
 /**
  * Layout defaults applied to EVERY engrave (initial + every reflow) unless a
@@ -408,10 +443,10 @@ declare const VEROVIO_LAYOUT_DEFAULTS: {
  * Verovio toolkit (`tests/notationPlayerVerovio.test.ts`'s "options merge"
  * tests call this directly).
  *
- * `avoidWidows` (see `VerovioLayoutOptions`'s own doc) is a PLAYER option,
- * not a Verovio one — destructured out here and never forwarded to
- * `setOptions`, same "narrow the passthrough" spirit as this function only
- * accepting `VerovioLayoutOptions`'s typed surface at all.
+ * `avoidWidows`/`minFitFactor` (see `VerovioLayoutOptions`'s own docs) are
+ * PLAYER options, not Verovio ones — destructured out here and never
+ * forwarded to `setOptions`, same "narrow the passthrough" spirit as this
+ * function only accepting `VerovioLayoutOptions`'s typed surface at all.
  *
  * `pageHeight: 60000` (Verovio's own max) + `pageMarginTop`/`pageMarginBottom:
  * 0` are unconditional, like `adjustPageHeight` — not in `VerovioLayoutOptions`
@@ -455,6 +490,27 @@ declare function verovioRenderOptions(hostWidthPx: number, zoom: number, layout?
  * available width.
  */
 declare function fitZoomFactor(systemWidthsPx: readonly number[], engraveWidthPx: number): number;
+/** Default `VerovioLayoutOptions.minFitFactor` — see that field's own doc. */
+declare const DEFAULT_MIN_FIT_FACTOR = 0.75;
+/**
+ * Pure decision for the readability floor (`VerovioLayoutOptions.minFitFactor`,
+ * `engraveOnce`'s "Fallback pass") — true exactly when ALL of:
+ *   - `factor` (a `fitZoomFactor` result) is finite and strictly below
+ *     `minFitFactor`;
+ *   - `minFitFactor` is a positive, finite floor (0 — or anything
+ *     non-positive/non-finite — disables the fallback unconditionally, the
+ *     documented opt-out);
+ *   - `breaks` is `'line'` or `'encoded'` — the two ways a caller can hand
+ *     Verovio EXACT, pre-decided break points (as opposed to `'auto'`/
+ *     `'smart'`/`'none'`/unset, where Verovio already owns the line-breaking
+ *     decision and there is no "caller's encoded bar count" to fall back
+ *     FROM in the first place).
+ *
+ * Never throws; no DOM/Verovio access — this is the single source of truth
+ * `engraveOnce` calls after every fit-factor computation, so the trigger
+ * condition is unit-testable independent of a real engrave.
+ */
+declare function shouldFallbackToAutoBreaks(factor: number, breaks: VerovioLayoutOptions['breaks'] | undefined, minFitFactor: number): boolean;
 /**
  * Semantic zoom → Verovio options. The migration spike's `zoom-test*.mjs`
  * proved `pageWidth` (Verovio's line-breaking width, in ITS OWN units)
@@ -501,4 +557,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, 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, 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, shouldFallbackToAutoBreaks, systemMeasureCounts, verovioEngravedNotes, verovioNotationLayout, verovioNotesAtColumn, verovioOnsetColumns, verovioRenderOptions, verovioZoomOptions };

package/dist/notationPlayerVerovio.js

@@ -396,7 +396,7 @@ var VEROVIO_LAYOUT_DEFAULTS = {
 };
 function verovioRenderOptions(hostWidthPx, zoom, layout) {
   const { scale, pageWidth } = verovioZoomOptions(hostWidthPx, zoom);
-  const { avoidWidows: _avoidWidows, ...verovioLayout } = layout ?? {};
+  const { avoidWidows: _avoidWidows, minFitFactor: _minFitFactor, ...verovioLayout } = layout ?? {};
   return {
     ...VEROVIO_LAYOUT_DEFAULTS,
     ...verovioLayout,
@@ -417,6 +417,13 @@ function fitZoomFactor(systemWidthsPx, engraveWidthPx) {
   const factor = engraveWidthPx / widest;
   return Number.isFinite(factor) && factor > 0 ? factor : 1;
 }
+var DEFAULT_MIN_FIT_FACTOR = 0.75;
+function shouldFallbackToAutoBreaks(factor, breaks, minFitFactor) {
+  if (!Number.isFinite(factor)) return false;
+  if (!(minFitFactor > 0)) return false;
+  if (breaks !== "line" && breaks !== "encoded") return false;
+  return factor < minFitFactor;
+}
 function verovioZoomOptions(hostWidthPx, zoom) {
   const z = Number.isFinite(zoom) && zoom > 0 ? zoom : 1;
   const scale = Math.max(VEROVIO_MIN_SCALE, Math.min(VEROVIO_MAX_SCALE, VEROVIO_BASE_SCALE * z));
@@ -553,42 +560,61 @@ function createVerovioNotationPlayer(opts) {
       }
     }
   }
+  function runWidowPass(toolkit, widthPx, zoom, xml, layoutOpts) {
+    const counts = systemMeasureCounts(svgHost);
+    if (counts.length >= 2 && counts[counts.length - 1] === 1) {
+      const totalMeasures = counts.reduce((a, b) => a + b, 0);
+      const breakPositions = balancedSystemBreaks(totalMeasures, counts.length);
+      if (breakPositions.length) {
+        const widowXml = injectSystemBreaks(xml, breakPositions);
+        const widowLayoutOpts = { ...layoutOpts, breaks: "line" };
+        toolkit.setOptions(verovioRenderOptions(widthPx, zoom, widowLayoutOpts));
+        const okWidow = !!toolkit.loadData(widowXml);
+        if (okWidow) {
+          renderAllPages(toolkit);
+          rebuildLayoutFromDom();
+          return { xml: widowXml, layoutOpts: widowLayoutOpts };
+        }
+      }
+    }
+    return { xml, layoutOpts };
+  }
   function engraveOnce(toolkit, widthPx, zoom) {
     const layoutOpts = opts.verovioOptions;
+    const effectiveBreaks = layoutOpts?.breaks ?? VEROVIO_LAYOUT_DEFAULTS.breaks;
+    const minFitFactor = layoutOpts?.minFitFactor ?? DEFAULT_MIN_FIT_FACTOR;
+    const avoidWidows = layoutOpts?.avoidWidows !== false;
     let xmlToRender = stampedXml;
     let renderLayoutOpts = layoutOpts;
     toolkit.setOptions(verovioRenderOptions(widthPx, zoom, renderLayoutOpts));
     const ok = !!toolkit.loadData(xmlToRender);
     if (ok) renderAllPages(toolkit);
     rebuildLayoutFromDom();
-    if (ok) {
-      const avoidWidows = layoutOpts?.avoidWidows !== false;
-      const effectiveBreaks = layoutOpts?.breaks ?? VEROVIO_LAYOUT_DEFAULTS.breaks;
-      if (avoidWidows && effectiveBreaks === "auto") {
-        const counts = systemMeasureCounts(svgHost);
-        if (counts.length >= 2 && counts[counts.length - 1] === 1) {
-          const totalMeasures = counts.reduce((a, b) => a + b, 0);
-          const breakPositions = balancedSystemBreaks(totalMeasures, counts.length);
-          if (breakPositions.length) {
-            const widowXml = injectSystemBreaks(stampedXml, breakPositions);
-            const widowLayoutOpts = { ...layoutOpts, breaks: "line" };
-            toolkit.setOptions(verovioRenderOptions(widthPx, zoom, widowLayoutOpts));
-            const okWidow = !!toolkit.loadData(widowXml);
-            if (okWidow) {
-              renderAllPages(toolkit);
-              rebuildLayoutFromDom();
-              xmlToRender = widowXml;
-              renderLayoutOpts = widowLayoutOpts;
-            }
+    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);
+      if (shouldFallbackToAutoBreaks(factor, effectiveBreaks, minFitFactor)) {
+        const autoLayoutOpts = { ...layoutOpts, breaks: "auto" };
+        toolkit.setOptions(verovioRenderOptions(widthPx, zoom, autoLayoutOpts));
+        const okAuto = !!toolkit.loadData(stampedXml);
+        if (okAuto) {
+          renderAllPages(toolkit);
+          rebuildLayoutFromDom();
+          xmlToRender = stampedXml;
+          renderLayoutOpts = autoLayoutOpts;
+          if (avoidWidows) {
+            const widowed = runWidowPass(toolkit, widthPx, zoom, xmlToRender, renderLayoutOpts);
+            xmlToRender = widowed.xml;
+            renderLayoutOpts = widowed.layoutOpts;
           }
+          factor = fitZoomFactor(systemWidthsPx(), widthPx);
         }
       }
-    }
-    if (ok && currentLayout) {
-      const factor = fitZoomFactor(
-        currentLayout.systems.map((s) => s.w),
-        widthPx
-      );
       if (factor < 1) {
         const effectiveZoom = zoom * factor;
         toolkit.setOptions(verovioRenderOptions(widthPx, effectiveZoom, renderLayoutOpts));
@@ -710,6 +736,7 @@ function createVerovioNotationPlayer(opts) {
   };
 }
 export {
+  DEFAULT_MIN_FIT_FACTOR,
   MARKED_NOTE_CLASS,
   MAX_ENGRAVE_WIDTH_VRV,
   VEROVIO_BASE_SCALE,
@@ -719,6 +746,7 @@ export {
   applyPrintObjectHiding,
   createVerovioNotationPlayer,
   fitZoomFactor,
+  shouldFallbackToAutoBreaks,
   systemMeasureCounts,
   verovioEngravedNotes,
   verovioNotationLayout,