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

package/dist/notationXml.d.ts

@@ -0,0 +1,175 @@
+declare function stampNoteIds(xml: string): string;
+/**
+ * Insert `<print new-system="yes"/>` as the FIRST child of the `<measure>`
+ * at each 0-based position in `breakBeforeBarIndexes`, in EVERY `<part>`
+ * (a score's parts share one measure timeline, so a break must be encoded
+ * once per part for Verovio to line the systems up across staves). A
+ * position that is ≤ 0 or ≥ that part's own measure count is silently
+ * ignored FOR THAT PART (0 is a no-op — a part already starts a new system
+ * at its own first measure). Idempotent: a measure that already carries a
+ * `<print>` element (from a prior call, or from the source data) gets
+ * `new-system="yes"` SET on that existing element rather than gaining a
+ * second one — calling this twice with the same positions serializes
+ * identically both times. Malformed input (fails to parse) is returned
+ * unchanged, same defensive style as `stampNoteIds` above. Only ever ADDS
+ * `<print>` elements — never touches a `<note>` — so `stampNoteIds`'s
+ * position-based id scheme is unaffected by a prior or subsequent call to
+ * this function (see this file's own tests for the pinned invariant).
+ */
+/**
+ * How many `<measure>` elements the FIRST `<part>` has — the `totalBars`
+ * that `barsPerLineBreaks`/`sectionAwareBreaks` plan against.
+ *
+ * The first part specifically, because that is the coordinate system
+ * `injectSystemBreaks` positions live in: a score's parts share one measure
+ * timeline, so the first part's ordinals index every part. And ORDINALS, not
+ * `<measure number>` attributes — scores skip and repeat bar numbers, so a
+ * count is the only safe answer. Malformed input, or a document with no
+ * part, returns 0 rather than throwing.
+ */
+declare function measureCount(xml: string): number;
+declare function injectSystemBreaks(xml: string, breakBeforeBarIndexes: readonly number[]): string;
+/**
+ * Evenly-spread system-break positions for `totalMeasures` measures across
+ * `systems` systems: `[per, 2·per, …]` (each strictly `< totalMeasures`),
+ * with `per = Math.ceil(totalMeasures / systems)` — `Math.ceil` naturally
+ * front-loads any remainder into the EARLIER systems (e.g. 7 measures / 2
+ * systems -> per=4 -> systems of 4+3, never 3+4), which is what keeps a
+ * later system from being the short/orphaned one. `systems <= 1` (nothing to
+ * break between) returns `[]`.
+ */
+declare function balancedSystemBreaks(totalMeasures: number, systems: number): number[];
+/**
+ * Balanced system-break positions for a target BARS-PER-LINE layout — the
+ * caller-facing sibling of `balancedSystemBreaks`, which takes a system
+ * COUNT. Rather than stepping `every` bars at a time from bar 0 (which
+ * strands a short remainder — a 5-bar excerpt at `every: 4` renders 4+1, a
+ * widow of our own making), this decides how many LINES the excerpt needs
+ * (`ceil(totalBars / every)`) and hands that count to
+ * `balancedSystemBreaks`. `(5, 4)` is `[3]` (3+2) instead of `[4]` (4+1);
+ * `(9, 4)` is `[3, 6]` (3+3+3) instead of `[4, 8]` (4+4+1).
+ *
+ * WIDOW BACK-OFF: a small `every` against a small `totalBars` can make the
+ * straight `ceil(totalBars / every)` line count land on a trailing line of
+ * exactly 1 bar — the same widow this function exists to remove, reappearing
+ * at a different total/every combination (`lines = 3` on 7 bars: `per = 3`
+ * fills two 3-bar lines and leaves 1 bar for the third). The line count is
+ * therefore backed down (never below 1) until the trailing line holds at
+ * least 2 bars — 7 bars lands on 2 lines (4+3) instead of 3 (3+3+1), which
+ * is the same "fewer, fuller lines" direction `every` already asks for.
+ * This never changes the result for any total/every whose straight `ceil`
+ * count already avoids a 1-bar trailing line.
+ *
+ * `every <= 0` (the "auto — no forced breaks" sentinel callers resolve to)
+ * or a non-positive/non-finite `totalBars` returns `[]`. Never throws.
+ *
+ * Ported from stave-web-sightread (`src/lib/bach/xmlTransforms.ts`), whose
+ * copy this replaces — see the CONTRACT DUPLICATION NOTICE above. Reached by
+ * consumers through `VerovioLayoutOptions.barsPerLine` rather than called
+ * directly, so the player owns both the plan and its interaction with the
+ * widow pass and the readability floor.
+ */
+declare function barsPerLineBreaks(totalBars: number, every: number): number[];
+/**
+ * Like `barsPerLineBreaks`, but each SECTION's span is balanced on its own
+ * instead of one balance running across the whole excerpt — so a line never
+ * ends part-way into a neighbouring section's opening bars, and a section's
+ * own bars are never split into a widowed last line either.
+ *
+ * `sectionStarts` are 0-BASED POSITIONS into the excerpt (the same
+ * coordinate `injectSystemBreaks` consumes), NOT MusicXML `<measure
+ * number>` attributes — scores skip bar numbers, so a caller holding
+ * bar-numbered section labels must convert first. `0` (the excerpt's own
+ * start) is never a break and is ignored if present.
+ *
+ * Every section start > 0 is a HARD break in its own right — a new section
+ * always begins its own line, not subject to balancing — unioned with
+ * `barsPerLineBreaks`' balanced positions computed WITHIN each section's
+ * span (its start up to the next section's start, or `totalBars` for the
+ * last) and offset back into excerpt-absolute positions.
+ *
+ * `every <= 0` suppresses the balanced component, matching
+ * `barsPerLineBreaks`, but section-start breaks still apply — that is the
+ * "sections only, otherwise let the engraver decide" mode. Out-of-range and
+ * non-integer starts are ignored. The result is sorted, de-duplicated, and
+ * every entry is a valid `injectSystemBreaks` position (integer, `> 0`,
+ * `< totalBars`). Never throws.
+ */
+declare function sectionAwareBreaks(totalBars: number, sectionStarts: readonly number[], every: number): number[];
+/** 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;
+}
+/**
+ * Pure(ish) — MusicXML-in, `id → NoteModel`-out. Walks every `<part>` in
+ * document order, then every `<measure>` in document order, then every
+ * DIRECT child in document order — `<attributes>` updates the part's own
+ * `divisions` cursor; every other non-`<note>` child (`<backup>`,
+ * `<forward>`, `<direction>`, …) is a structural/timeline element this
+ * function has NO use for (it reads each note's OWN `<duration>` directly,
+ * never a cursor POSITION — see `durationReal`'s doc — so unlike
+ * `walkMeasureNotes`-style position walks, `<backup>`/`<forward>` need no
+ * special handling here beyond being correctly skipped, which plain
+ * tag-name filtering already does) — and every `<note>` becomes one model
+ * entry, keyed by its `id` attribute (a note with NO `id` — i.e. input that
+ * was never run through `stampNoteIds` — is silently skipped: it has no key
+ * to join the render against, so there is nothing useful to record).
+ *
+ * Never throws: malformed input (fails to parse, or no `<score-partwise>`
+ * root) returns an empty Map.
+ */
+declare function noteModelFromXml(stampedXml: string): Map<string, NoteModel>;
+
+export { type NoteModel, balancedSystemBreaks, barsPerLineBreaks, injectSystemBreaks, measureCount, noteModelFromXml, sectionAwareBreaks, stampNoteIds };

package/dist/notationXml.js

@@ -0,0 +1,19 @@
+import {
+  balancedSystemBreaks,
+  barsPerLineBreaks,
+  injectSystemBreaks,
+  measureCount,
+  noteModelFromXml,
+  sectionAwareBreaks,
+  stampNoteIds
+} from "./chunk-JCDNEJBT.js";
+export {
+  balancedSystemBreaks,
+  barsPerLineBreaks,
+  injectSystemBreaks,
+  measureCount,
+  noteModelFromXml,
+  sectionAwareBreaks,
+  stampNoteIds
+};
+//# sourceMappingURL=notationXml.js.map

package/dist/notationXml.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-music-packages/web-core",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "Shared music-theory + audio primitives for the music-suite web apps",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,6 +39,10 @@
       "types": "./dist/ornaments.d.ts",
       "import": "./dist/ornaments.js"
     },
+    "./notationXml": {
+      "types": "./dist/notationXml.d.ts",
+      "import": "./dist/notationXml.js"
+    },
     "./notationBeams": {
       "types": "./dist/notationBeams.d.ts",
       "import": "./dist/notationBeams.js"