@k-l-lambda/lilylet 0.1.68 → 0.1.70

package/lib/lilylet/abcDecoder.js

@@ -5,6 +5,7 @@
  */
 import parse from "../abc/parser.js";
 import { Phonet, Accidental, ArticulationType, OrnamentType, DynamicType, HairpinType, PedalType, NavigationMarkType, Placement, } from "./types.js";
+import { parseStaffLayout, StaffGroupType } from "./staffLayout.js";
 // ============ Constants ============
 // NotaGen catalog tags appear as leading single-% comments in ABC files,
 // in the order: period, composer, instrumentation. They are mapped to
@@ -335,6 +336,9 @@ const convertClef = (clefStr) => {
     // Split off an optional ABC octave shift suffix: "treble-8", "bass+8", "treble-15".
     // ABC: "-N" lowers the sounding pitch (small N drawn below), "+N" raises it.
     // LilyPond/Lilylet: "_N" = below, "^N" = above. Translate the sign accordingly.
+    // (Only octave amounts 8/15 are handled here; the Lilylet "_N"/"^N" clef suffix
+    // itself accepts arbitrary diatonic intervals — see meiEncoder.resolveClef — and a
+    // voice's transpose= property is folded into the same suffix via transposeClefSuffix.)
     const shift = clefStr?.match(/^(.*?)([+-])(8|15)$/);
     const base = shift ? shift[1] : clefStr;
     let resolved;
@@ -355,6 +359,31 @@ const convertClef = (clefStr) => {
         resolved += (shift[2] === "-" ? "_" : "^") + shift[3];
     return resolved;
 };
+/**
+ * Fold an ABC voice `transpose=N` property (a written→sounding shift in
+ * SEMITONES) into the Lilylet clef-suffix form `_M` / `^M`, where M is a
+ * diatonic interval number. ABC carries only semitones, so the diatonic
+ * interval is approximated by the nearest scale-step count
+ * (steps = round(semi * 7/12), interval number = |steps| + 1); `_` lowers,
+ * `^` raises. The Lilylet→MEI encoder later expands the suffix back into
+ * trans.diat / trans.semi (see meiEncoder.resolveClef). This is exact when the
+ * semitone count is a major/perfect interval (e.g. -2, -9, +2, ±12) and a
+ * nearest-interval approximation otherwise.
+ */
+const transposeClefSuffix = (clef, semitones) => {
+    if (!clef || !semitones)
+        return clef;
+    // A clef that already carries an octave suffix (treble_8 etc.) is left as-is;
+    // stacking another shift on top is not meaningful for ABC sources.
+    if (/[_^]\d+$/.test(clef))
+        return clef;
+    const steps = Math.round((semitones * 7) / 12);
+    if (steps === 0)
+        return clef;
+    const num = Math.abs(steps) + 1;
+    const suffix = (steps < 0 ? "_" : "^") + num;
+    return (clef + suffix);
+};
 /**
  * Convert ABC barline to Lilylet barline style
  */
@@ -431,6 +460,149 @@ const parseScoreLayout = (headers) => {
     }
     return voiceMap.size > 0 ? voiceMap : null;
 };
+/**
+ * Translate an ABC %%score layout into the equivalent lilylet staves expression.
+ *
+ * The two models differ in their leaf unit: ABC %%score is VOICE-leaf (an arc `( … )`
+ * collapses several voices onto one staff), whereas lilylet staves is STAFF-leaf. So
+ * each ABC staff becomes exactly one lilylet staff id, named (per spec) by the FIRST
+ * voice token inside its arc.
+ *
+ * Bracket mapping (ABC → lilylet):
+ *   ( … )  arc    → one staff leaf (id = first voice)         e.g. (1 3) → "1"
+ *   bare   leaf   → one staff leaf (id = that voice)          e.g. 7     → "7"
+ *   { … }  curly  → brace (grand staff)                       → { … }
+ *   [ … ]  square → bracket (orchestral)                      → < … >
+ *
+ * Conjunction between two siblings: a trailing `|` in %%score means barlines run through
+ * the two staves, mapped to the solid conjunction `-`; otherwise the blank `,` is used.
+ */
+const abcLayoutToStaves = (layout) => {
+    // First voice token under a node (the staff's lilylet id).
+    const firstVoice = (node) => {
+        if (typeof node === "string")
+            return node;
+        for (const item of node.items || []) {
+            const v = firstVoice(item);
+            if (v !== null)
+                return v;
+        }
+        return null;
+    };
+    // A node is a single staff (an arc, or a bare leaf) iff it has no curly/square nesting.
+    const isStaffLeaf = (node) => {
+        if (typeof node === "string")
+            return true;
+        if (node.bound === "curly" || node.bound === "square")
+            return false;
+        // arc or unbounded: a staff only if every descendant is too (no nested groups)
+        return (node.items || []).every(isStaffLeaf);
+    };
+    const emit = (node) => {
+        if (isStaffLeaf(node))
+            return firstVoice(node) || "";
+        const group = node;
+        const open = group.bound === "curly" ? "{" : "<"; // square → bracket <>, curly → brace {}
+        const close = group.bound === "curly" ? "}" : ">";
+        const items = group.items || [];
+        let inner = "";
+        items.forEach((item, i) => {
+            inner += emit(item);
+            if (i < items.length - 1) {
+                const conj = item.barThruAfter ? "-" : ",";
+                inner += conj;
+            }
+        });
+        return `${open}${inner}${close}`;
+    };
+    const tops = layout.map((top, i) => {
+        let s = emit(top);
+        // A bare top-level staff leaf (e.g. the `9` in `[ … ] 9 [ … ]`) still occupies a slot;
+        // emit() already yields its id with no wrapper, which is the desired output.
+        return { s, barThru: !!top.barThruAfter, isLast: i === layout.length - 1 };
+    });
+    let out = "";
+    tops.forEach((t, i) => {
+        out += t.s;
+        if (i < tops.length - 1)
+            out += t.barThru ? " - " : " ";
+    });
+    out = out.trim();
+    return out.length > 0 ? out : null;
+};
+/**
+ * Translate ABC voice instrument names (V:n nm="…" snm="…") into a lilylet `instruments`
+ * map keyed by staff-layout group key.
+ *
+ * ABC names sit on individual voices; lilylet staves are staff-leaf (an arc's first voice
+ * is the staff id). So we first collect a per-staff name from the staff-id voice. Then,
+ * per the user's rule: if a GROUP carries an instrument only on its first staff and the
+ * rest of the group is unnamed, the name belongs to the whole group — hoist it to the
+ * group key and drop it from the leaf. This matches engraving convention (one bracketed
+ * section, e.g. "Violini", named once for the group rather than on its top staff).
+ *
+ * `voiceInstr` maps an ABC voice number to its {name, shortName}. The layout's staff ids
+ * are arc-first voice numbers, so a staff id "5" looks up voice 5's name.
+ */
+const abcInstrumentsToLilylet = (stavesCode, voiceInstr) => {
+    const layout = parseStaffLayout(stavesCode);
+    const result = {};
+    // Per-staff instrument, keyed by staff id (the arc-first voice number as a string).
+    const staffInstr = new Map();
+    for (const id of layout.staffIds) {
+        const v = parseInt(id, 10);
+        if (!isNaN(v) && voiceInstr.has(v))
+            staffInstr.set(id, voiceInstr.get(v));
+    }
+    // First staff id under a group (in layout order).
+    const firstStaffId = (group) => {
+        if (group.staff)
+            return group.staff;
+        for (const sub of group.subs || []) {
+            const id = firstStaffId(sub);
+            if (id !== undefined)
+                return id;
+        }
+        return undefined;
+    };
+    // All staff ids under a group except the first.
+    const restStaffIds = (group) => {
+        const all = [];
+        const collect = (g) => {
+            if (g.staff)
+                all.push(g.staff);
+            (g.subs || []).forEach(collect);
+        };
+        collect(group);
+        return all.slice(1);
+    };
+    // Walk groups top-down; hoist a first-staff-only name onto the group, else keep leaves.
+    const walk = (group) => {
+        const isLeaf = !!group.staff && (!group.subs || group.subs.length === 0);
+        if (isLeaf) {
+            // A plain leaf keeps its own name (assigned in the flush pass below).
+            return;
+        }
+        const first = firstStaffId(group);
+        const firstInstr = first !== undefined ? staffInstr.get(first) : undefined;
+        const rest = restStaffIds(group);
+        const restNamed = rest.some(id => staffInstr.has(id));
+        // Group with a real grouping symbol, named only on its first staff → hoist.
+        const hasSymbol = group.type !== StaffGroupType.Default;
+        if (hasSymbol && firstInstr && !restNamed && group.key !== undefined) {
+            result[group.key] = firstInstr;
+            staffInstr.delete(first); // consumed by the group
+            return; // children below the hoisted name carry nothing
+        }
+        for (const sub of group.subs || [])
+            walk(sub);
+    };
+    walk(layout.group);
+    // Flush any per-staff names that weren't hoisted onto a group.
+    for (const [id, instr] of staffInstr)
+        result[id] = instr;
+    return Object.keys(result).length > 0 ? result : null;
+};
 // ============ Marks/Decorations Conversion ============
 const convertArticulationMark = (artName) => {
     switch (artName) {
@@ -681,7 +853,7 @@ const processBarPatch = (patch, unitLength, slurDepth, pitchCtx) => {
         }
         // Grace notes
         if (term.grace) {
-            const graceEvents = convertGraceEvents(term, unitLength);
+            const graceEvents = convertGraceEvents(term, unitLength, pitchCtx);
             events.push(...graceEvents);
             i++;
             continue;
@@ -852,7 +1024,7 @@ const convertEventTerm = (eventTerm, unitLength, pendingMarks, pendingContextCha
 /**
  * Convert grace notes to NoteEvents with grace flag
  */
-const convertGraceEvents = (graceTerm, unitLength) => {
+const convertGraceEvents = (graceTerm, unitLength, pitchCtx) => {
     const events = [];
     if (!graceTerm.events)
         return events;
@@ -862,7 +1034,7 @@ const convertGraceEvents = (graceTerm, unitLength) => {
             const chord = eventData.chord;
             if (!chord || !chord.pitches)
                 continue;
-            const pitches = chord.pitches.filter((p) => p.phonet !== "z" && p.phonet !== "Z" && p.phonet !== "x").map(convertPitch);
+            const pitches = chord.pitches.filter((p) => p.phonet !== "z" && p.phonet !== "Z" && p.phonet !== "x").map((p) => convertPitch(p, pitchCtx));
             if (pitches.length === 0)
                 continue;
             const duration = convertDuration(eventData.duration, unitLength);
@@ -984,7 +1156,17 @@ const decodeTune = (tune, options = {}) => {
                         properties: voiceValue?.properties,
                     });
                     if (clefStr) {
-                        const clef = convertClef(clefStr);
+                        let clef = convertClef(clefStr);
+                        // Fold a voice transpose= (semitones) into the clef suffix so it
+                        // survives to MEI as trans.diat/trans.semi (transposing instruments
+                        // like "Clarinet transpose=-2", "Horn transpose=-9").
+                        const transposeRaw = voiceValue?.properties?.transpose;
+                        const transposeSemi = typeof transposeRaw === "number"
+                            ? transposeRaw
+                            : (transposeRaw != null ? Number(transposeRaw) : NaN);
+                        if (clef && Number.isFinite(transposeSemi) && transposeSemi !== 0) {
+                            clef = transposeClefSuffix(clef, transposeSemi);
+                        }
                         if (clef)
                             voiceClefs.set(voiceId, clef);
                     }
@@ -995,6 +1177,39 @@ const decodeTune = (tune, options = {}) => {
     }
     // Parse score layout
     const scoreLayout = parseScoreLayout(headers);
+    // Translate the ABC %%score layout into a lilylet staves expression (staff-leaf model).
+    const layoutHeader = headers.find((h) => h.staffLayout);
+    if (layoutHeader) {
+        const staves = abcLayoutToStaves(layoutHeader.staffLayout);
+        if (staves)
+            metadata.staves = staves;
+        // Translate per-voice nm/snm into a lilylet instruments map. Collect names by ABC
+        // voice number (the staff id is the arc-first voice), then let abcInstrumentsToLilylet
+        // apply the first-staff-only → whole-group hoisting rule.
+        if (metadata.staves) {
+            const voiceInstr = new Map();
+            for (const [vid, config] of voiceConfigs) {
+                const props = config.properties;
+                if (!props)
+                    continue;
+                const name = props.nm ?? props.name;
+                if (typeof name !== "string" || !name.length)
+                    continue;
+                const v = typeof vid === "number" ? vid : parseInt(String(vid), 10);
+                if (isNaN(v))
+                    continue;
+                const short = props.snm ?? props.sname;
+                voiceInstr.set(v, typeof short === "string" && short.length
+                    ? { name, shortName: short }
+                    : { name });
+            }
+            if (voiceInstr.size > 0) {
+                const instruments = abcInstrumentsToLilylet(metadata.staves, voiceInstr);
+                if (instruments)
+                    metadata.instruments = instruments;
+            }
+        }
+    }
     // Group measures by voice
     // ABC measures contain BarPatches, each with a voice control V:n
     const measures = body.measures;