@k-l-lambda/lilylet 0.1.68 → 0.1.70

package/lib/lilylet/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./types";
 export * from "./parser";
 export * from "./serializer";
+export * from "./staffLayout";
 import * as meiEncoder from "./meiEncoder";
 import * as musicXmlDecoder from "./musicXmlDecoder";
 import * as lilypondEncoder from "./lilypondEncoder";

package/lib/lilylet/index.js

@@ -1,6 +1,7 @@
 export * from "./types.js";
 export * from "./parser.js";
 export * from "./serializer.js";
+export * from "./staffLayout.js";
 import * as meiEncoder from "./meiEncoder.js";
 import * as musicXmlDecoder from "./musicXmlDecoder.js";
 import * as lilypondEncoder from "./lilypondEncoder.js";

package/lib/lilylet/meiEncoder.js

@@ -1,4 +1,5 @@
 import { Clef, Accidental, OrnamentType, StemDirection, HairpinType, PedalType, } from "./types.js";
+import { parseStaffLayout, StaffGroupType } from "./staffLayout.js";
 // MEI key signatures: positive = sharps, negative = flats
 const KEY_SIGS = {
     0: "0",
@@ -44,38 +45,55 @@ const CLEF_SHAPES = {
     F: { shape: "F", line: 4 },
     C: { shape: "C", line: 3 },
 };
-// Resolve a clef string into MEI shape/line plus optional octave displacement.
-// Octave transposition follows the LilyPond convention: a "_8"/"_15" suffix lowers
-// the sounding pitch by one/two octaves (the small 8/15 is drawn below the clef),
-// and "^8"/"^15" raises it (drawn above). MEI encodes this as dis ("8" | "15")
-// and dis.place ("below" | "above").
+// Semitone offsets of the major/perfect intervals within one diatonic octave,
+// indexed by diatonic step (0 = unison, 1 = 2nd, … 6 = 7th).
+const DIATONIC_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
+// Convert a LilyPond clef interval-number suffix into an MEI written→sounding
+// transposition. The number N is a diatonic interval number (2 = 2nd, 3 = 3rd,
+// 5 = 5th, 8 = octave, 15 = two octaves); "_" lowers the sounding pitch, "^"
+// raises it. Returns { diat, semi } where diat is the diatonic step shift
+// (N - 1, signed) and semi is the corresponding chromatic shift in semitones,
+// extended octave-wise for compound intervals.
+const clefTransposition = (intervalNumber, up) => {
+    const k = intervalNumber - 1; // diatonic steps
+    const semis = DIATONIC_SEMITONES[k % 7] + 12 * Math.floor(k / 7);
+    const sign = up ? 1 : -1;
+    return { diat: sign * k, semi: sign * semis };
+};
+// Resolve a clef string into MEI shape/line plus optional written→sounding
+// transposition. Per the LilyPond convention a "_N"/"^N" suffix transposes the
+// clef down/up by the diatonic interval N (e.g. "treble_8" octave down,
+// "treble_5" fifth down, "treble^3" third up). MEI's clef.dis only covers octave
+// displacement (8|15|22), so all clef transposition — octaves included — is
+// encoded uniformly via att.transposition (trans.diat / trans.semi) on staffDef.
 const resolveClef = (clefStr) => {
-    const match = clefStr.match(/^(.*?)([_^])(8|15)$/);
+    const match = clefStr.match(/^(.*?)([_^])(\d+)$/);
     const base = match ? match[1] : clefStr;
     const clefInfo = CLEF_SHAPES[base] || CLEF_SHAPES.treble;
     if (!match)
         return { shape: clefInfo.shape, line: clefInfo.line };
+    const trans = clefTransposition(Number(match[3]), match[2] === "^");
     return {
         shape: clefInfo.shape,
         line: clefInfo.line,
-        dis: match[3],
-        disPlace: match[2] === "^" ? "above" : "below",
+        trans,
     };
 };
 // Attributes for a standalone <clef> element (mid-measure clef change).
+// A mid-measure <clef> cannot carry att.transposition (that is a staff-level
+// property on <staffDef>); a mid-piece change of transposition would require a
+// new <staffDef>, which is out of scope here. So only shape/line are emitted.
 const clefElementAttrs = (clefStr) => {
     const c = resolveClef(clefStr);
-    let attrs = `shape="${c.shape}" line="${c.line}"`;
-    if (c.dis)
-        attrs += ` dis="${c.dis}" dis.place="${c.disPlace}"`;
-    return attrs;
+    return `shape="${c.shape}" line="${c.line}"`;
 };
-// Attributes for a <staffDef> clef (clef.* namespace).
+// Attributes for a <staffDef> clef (clef.* namespace), plus att.transposition
+// (trans.diat / trans.semi) when the clef declares a transposition.
 const staffDefClefAttrs = (clefStr) => {
     const c = resolveClef(clefStr);
     let attrs = `clef.shape="${c.shape}" clef.line="${c.line}"`;
-    if (c.dis)
-        attrs += ` clef.dis="${c.dis}" clef.dis.place="${c.disPlace}"`;
+    if (c.trans)
+        attrs += ` trans.diat="${c.trans.diat}" trans.semi="${c.trans.semi}"`;
     return attrs;
 };
 // Lilylet duration division to MEI dur
@@ -1622,33 +1640,120 @@ const analyzePartStructure = (doc) => {
     }
     return partInfos;
 };
+// MEI staffGrp @symbol for a layout group type (Default → none; Square → bracketsq).
+const LAYOUT_SYMBOL = [null, "brace", "bracket", "bracketsq"];
+// Build <label>/<labelAbbr> child XML for an instrument entry, or "" if none.
+const instrumentLabelXML = (instr, indent) => {
+    if (!instr)
+        return "";
+    let xml = `${indent}<label>${escapeXml(instr.name)}</label>\n`;
+    if (instr.shortName !== undefined) {
+        xml += `${indent}<labelAbbr>${escapeXml(instr.shortName)}</labelAbbr>\n`;
+    }
+    return xml;
+};
+// Recursively emit a <staffGrp>/<staffDef> tree from a parsed [staves] layout group.
+// `staffDefAttrs` maps a leaf staff index (0-based, in layout order) to the attribute
+// string for the matching global staff's <staffDef>. `instruments` maps a layout group
+// key (staffLayout's groupKey: a staff id or range) to its instrument name; matching
+// names are emitted as <label>/<labelAbbr> on the staffGrp (groups) or staffDef (leaves).
+// bar.thru reflects the group's conjunction (Solid).
+const layoutGroupToMEI = (group, staffDefAttrs, leafCounter, indent, instruments) => {
+    const isLeaf = !!group.staff && (!group.subs || group.subs.length === 0);
+    const instr = group.key !== undefined ? instruments[group.key] : undefined;
+    // A leaf with no grouping symbol (Default) emits just the next staffDef (with label).
+    if (isLeaf && (group.type === StaffGroupType.Default || !LAYOUT_SYMBOL[group.type])) {
+        return staffDefWithLabel(staffDefAttrs[leafCounter.i++], instr, indent);
+    }
+    const symbol = LAYOUT_SYMBOL[group.type] ? ` symbol="${LAYOUT_SYMBOL[group.type]}"` : "";
+    const barThru = (group.bar ?? 0) > 1 ? ' bar.thru="true"' : '';
+    let xml = `${indent}<staffGrp xml:id="${generateId("staffgrp")}"${symbol}${barThru}>\n`;
+    // A multi-staff group's instrument name labels the whole group.
+    if (!isLeaf)
+        xml += instrumentLabelXML(instr, indent + "    ");
+    if (isLeaf) {
+        // A single staff that still carries a grouping bracket (e.g. "<b>"): MEI allows
+        // a staffGrp wrapping one staffDef. The instrument names the lone staff, so the
+        // label goes on the staffDef inside.
+        xml += staffDefWithLabel(staffDefAttrs[leafCounter.i++], instr, indent + "    ");
+    }
+    else {
+        for (const sub of group.subs || []) {
+            xml += layoutGroupToMEI(sub, staffDefAttrs, leafCounter, indent + "    ", instruments);
+        }
+    }
+    xml += `${indent}</staffGrp>\n`;
+    return xml;
+};
+// Emit a <staffDef> from its attribute string, with optional instrument <label> children.
+const staffDefWithLabel = (attrs, instr, indent) => {
+    if (attrs === undefined)
+        return "";
+    if (!instr)
+        return `${indent}<staffDef ${attrs} />\n`;
+    let xml = `${indent}<staffDef ${attrs}>\n`;
+    xml += instrumentLabelXML(instr, indent + "    ");
+    xml += `${indent}</staffDef>\n`;
+    return xml;
+};
 // Encode scoreDef with part groups
-const encodeScoreDef = (keySig, timeNum, timeDen, partInfos, indent, meterSymbol) => {
+const encodeScoreDef = (keySig, timeNum, timeDen, partInfos, indent, meterSymbol, stavesCode, instruments = {}) => {
     const scoreDefId = generateId("scoredef");
     // Build meter attributes
     const meterSymAttr = meterSymbol ? ` meter.sym="${meterSymbol}"` : '';
     let xml = `${indent}<scoreDef xml:id="${scoreDefId}" key.sig="${keySig}"${meterSymAttr} meter.count="${timeNum}" meter.unit="${timeDen}">\n`;
-    xml += `${indent}    <staffGrp xml:id="${generateId("staffgrp")}">\n`;
-    for (let pi = 0; pi < partInfos.length; pi++) {
-        const info = partInfos[pi];
-        // If part has multiple staves (grand staff), wrap in staffGrp with brace
-        if (info.maxStaff > 1) {
-            xml += `${indent}        <staffGrp xml:id="${generateId("staffgrp")}" symbol="brace" bar.thru="true">\n`;
-            for (let ls = 1; ls <= info.maxStaff; ls++) {
-                const globalStaff = info.staffOffset + ls;
-                const clef = info.clefs[ls] || Clef.treble;
-                xml += `${indent}            <staffDef xml:id="${generateId('staffdef')}" n="${globalStaff}" lines="5" ${staffDefClefAttrs(clef)} />\n`;
-            }
-            xml += `${indent}        </staffGrp>\n`;
+    // Flat ordered list of global staves (n + clef), in part/voice order.
+    const flatStaves = [];
+    for (const info of partInfos) {
+        for (let ls = 1; ls <= info.maxStaff; ls++) {
+            flatStaves.push({ n: info.staffOffset + ls, clef: info.clefs[ls] || Clef.treble });
         }
-        else {
-            // Single staff part
-            const globalStaff = info.staffOffset + 1;
-            const clef = info.clefs[1] || Clef.treble;
-            xml += `${indent}        <staffDef xml:id="${generateId('staffdef')}" n="${globalStaff}" lines="5" ${staffDefClefAttrs(clef)} />\n`;
+    }
+    // If a [staves] layout is present and its leaf count matches the staves, drive
+    // the nested staffGrp (bracket/bracketsq/brace) from it. Otherwise fall back to
+    // the per-part grand-staff grouping.
+    let layoutUsed = false;
+    if (stavesCode) {
+        const layout = parseStaffLayout(stavesCode);
+        if (layout.stavesCount === flatStaves.length) {
+            const staffDefAttrs = flatStaves.map(s => `xml:id="${generateId('staffdef')}" n="${s.n}" lines="5" ${staffDefClefAttrs(s.clef)}`);
+            xml += layoutGroupToMEI(layout.group, staffDefAttrs, { i: 0 }, `${indent}    `, instruments);
+            layoutUsed = true;
+        }
+    }
+    if (!layoutUsed) {
+        xml += `${indent}    <staffGrp xml:id="${generateId("staffgrp")}">\n`;
+        for (let pi = 0; pi < partInfos.length; pi++) {
+            const info = partInfos[pi];
+            // If part has multiple staves (grand staff), wrap in staffGrp with brace.
+            // Instrument key for a part follows staffLayout's groupKey: a single staff
+            // number, or "first-last" for a grand staff.
+            if (info.maxStaff > 1) {
+                const first = info.staffOffset + 1;
+                const last = info.staffOffset + info.maxStaff;
+                const instr = instruments[`${first}-${last}`];
+                xml += `${indent}        <staffGrp xml:id="${generateId("staffgrp")}" symbol="brace" bar.thru="true">\n`;
+                xml += instrumentLabelXML(instr, `${indent}            `);
+                for (let ls = 1; ls <= info.maxStaff; ls++) {
+                    const globalStaff = info.staffOffset + ls;
+                    const clef = info.clefs[ls] || Clef.treble;
+                    const leafInstr = instruments[`${globalStaff}`];
+                    const attrs = `xml:id="${generateId('staffdef')}" n="${globalStaff}" lines="5" ${staffDefClefAttrs(clef)}`;
+                    xml += staffDefWithLabel(attrs, leafInstr, `${indent}            `);
+                }
+                xml += `${indent}        </staffGrp>\n`;
+            }
+            else {
+                // Single staff part
+                const globalStaff = info.staffOffset + 1;
+                const clef = info.clefs[1] || Clef.treble;
+                const leafInstr = instruments[`${globalStaff}`];
+                const attrs = `xml:id="${generateId('staffdef')}" n="${globalStaff}" lines="5" ${staffDefClefAttrs(clef)}`;
+                xml += staffDefWithLabel(attrs, leafInstr, `${indent}        `);
+            }
         }
+        xml += `${indent}    </staffGrp>\n`;
     }
-    xml += `${indent}    </staffGrp>\n`;
     xml += `${indent}</scoreDef>\n`;
     return xml;
 };
@@ -1983,7 +2088,7 @@ const encode = (doc, options = {}) => {
     mei += `${indent}${indent}<body>\n`;
     mei += `${indent}${indent}${indent}<mdiv xml:id="${generateId("mdiv")}">\n`;
     mei += `${indent}${indent}${indent}${indent}<score xml:id="${generateId("score")}">\n`;
-    mei += encodeScoreDef(keySig, currentTimeNum, currentTimeDen, partInfos, `${indent}${indent}${indent}${indent}${indent}`, currentMeterSymbol);
+    mei += encodeScoreDef(keySig, currentTimeNum, currentTimeDen, partInfos, `${indent}${indent}${indent}${indent}${indent}`, currentMeterSymbol, doc.metadata?.staves, doc.metadata?.instruments);
     mei += `${indent}${indent}${indent}${indent}${indent}<section xml:id="${generateId("section")}">\n`;
     // Track tie state across measures for cross-measure ties
     const tieState = {};

package/lib/lilylet/musicXmlDecoder.js

@@ -575,6 +575,15 @@ const parseMetadata = (doc) => {
                 }
             }
         }
+        // Staff layout: recover the raw [staves] string stashed at encode time.
+        const miscFields = getElements(identificationEl, 'miscellaneous-field');
+        for (const field of miscFields) {
+            if (getAttribute(field, 'name') === 'lilylet-staves') {
+                const code = field.textContent?.trim();
+                if (code)
+                    metadata.staves = code;
+            }
+        }
     }
     return Object.keys(metadata).length > 0 ? metadata : {};
 };

package/lib/lilylet/musicXmlEncoder.js

@@ -6,6 +6,7 @@
  */
 import { StemDirection, Accidental, HairpinType, PedalType, } from "./types.js";
 import { DIVISIONS, DIVISION_TO_TYPE, calculateDuration, } from "./musicXmlUtils.js";
+import { parseStaffLayout } from "./staffLayout.js";
 // === Constants and Reverse Mappings ===
 // Phonet to MusicXML step
 const PHONET_TO_STEP = {
@@ -87,6 +88,10 @@ const BARLINE_TO_XML = {
     ':|.': { barStyle: 'light-heavy', repeat: 'backward' },
     ':..:': { barStyle: 'light-heavy', repeat: 'backward' }, // Will need special handling
 };
+// MusicXML <group-symbol> value by StaffGroupType (Default → none). MusicXML's
+// allowed values are brace | bracket | line | square | none — note that, unlike
+// MEI (which uses "bracketsq"), MusicXML's square variant IS spelled "square".
+const GROUP_SYMBOLS_XML = [null, "brace", "bracket", "square"];
 // === XML Helper Functions ===
 const escapeXml = (text) => {
     return text
@@ -566,6 +571,7 @@ const encodeMeasure = (measure, partIndex, measureNumber, isFirst, prevKey, prev
                     // Other context changes are handled in attributes
                     break;
                 }
+                case 'times':
                 case 'tuplet': {
                     const tupletEvents = event.events.filter(e => e.type === 'note' || e.type === 'rest');
                     for (let ti = 0; ti < tupletEvents.length; ti++) {
@@ -649,9 +655,101 @@ const encodeMetadata = (metadata, level) => {
     xml += `${indent(level + 2)}<software>Lilylet</software>\n`;
     xml += `${indent(level + 2)}<encoding-date>${new Date().toISOString().split('T')[0]}</encoding-date>\n`;
     xml += `${indent(level + 1)}</encoding>\n`;
+    // Preserve the raw staff-layout string for a lossless round-trip. MusicXML has
+    // no native carrier for it (its <part-group> only expresses grouping, not the
+    // conjunction/anonymous-id detail), so we stash the verbatim code here.
+    if (metadata.staves) {
+        xml += `${indent(level + 1)}<miscellaneous>\n`;
+        xml += `${indent(level + 2)}<miscellaneous-field name="lilylet-staves">${escapeXml(metadata.staves)}</miscellaneous-field>\n`;
+        xml += `${indent(level + 1)}</miscellaneous>\n`;
+    }
     xml += `${indent(level)}</identification>\n`;
     return xml;
 };
+/**
+ * Build <part-group> start/stop brackets from a parsed staff-layout, keyed by the
+ * part index they wrap around.
+ *
+ * The layout is staff-leaf (one leaf per staff); MusicXML <part-group> brackets group
+ * *parts*. We map each part to the consecutive run of staff-leaves it owns (a grand-staff
+ * part owns `maxStaff` leaves), then translate every layout group whose leaf-span aligns
+ * with whole-part boundaries into a part-group. Groups that fall entirely inside one part
+ * (e.g. the brace over a single grand-staff part) are intrinsic to that part's <staves>
+ * and are skipped here. Returns { starts, stops } maps: partIndex → XML snippets.
+ */
+const buildPartGroups = (stavesCode, staffCountPerPart, level) => {
+    const starts = new Map();
+    const stops = new Map();
+    const layout = parseStaffLayout(stavesCode);
+    const totalLeaves = staffCountPerPart.reduce((a, b) => a + b, 0);
+    if (layout.stavesCount !== totalLeaves) {
+        // Layout/parts mismatch — skip grouping rather than emit something wrong.
+        return { starts, stops };
+    }
+    // leaf index → part index, and the [firstLeaf, lastLeaf] each part spans.
+    const partFirstLeaf = [];
+    const partLastLeaf = [];
+    let leaf = 0;
+    for (let pi = 0; pi < staffCountPerPart.length; pi++) {
+        partFirstLeaf[pi] = leaf;
+        leaf += staffCountPerPart[pi];
+        partLastLeaf[pi] = leaf - 1;
+    }
+    const leafToPart = (leafIdx) => {
+        for (let pi = 0; pi < staffCountPerPart.length; pi++) {
+            if (leafIdx >= partFirstLeaf[pi] && leafIdx <= partLastLeaf[pi])
+                return pi;
+        }
+        return -1;
+    };
+    let groupNumber = 0;
+    const leafCounter = { i: 0 };
+    const walk = (group) => {
+        const isLeaf = !!group.staff && (!group.subs || group.subs.length === 0);
+        const symbol = GROUP_SYMBOLS_XML[group.type];
+        if (isLeaf) {
+            // A leaf may itself carry a bracket (e.g. <b>): a one-staff part-group.
+            const li = leafCounter.i++;
+            if (symbol) {
+                const pi = leafToPart(li);
+                if (pi >= 0 && partFirstLeaf[pi] === li && partLastLeaf[pi] === li) {
+                    emit(pi, pi, symbol, group.bar);
+                }
+            }
+            return;
+        }
+        // Span the leaves covered by this group's subtree, then recurse.
+        const firstLeaf = leafCounter.i;
+        for (const sub of group.subs || [])
+            walk(sub);
+        const lastLeaf = leafCounter.i - 1;
+        if (symbol) {
+            const startPart = leafToPart(firstLeaf);
+            const endPart = leafToPart(lastLeaf);
+            // Only emit when the span aligns with whole-part boundaries AND wraps >1 part
+            // (a group inside a single part is the part's own grand staff, not a part-group).
+            if (startPart >= 0 && endPart >= 0 && startPart !== endPart &&
+                partFirstLeaf[startPart] === firstLeaf && partLastLeaf[endPart] === lastLeaf) {
+                emit(startPart, endPart, symbol, group.bar);
+            }
+        }
+    };
+    const emit = (startPart, endPart, symbol, bar) => {
+        const num = ++groupNumber;
+        const barLine = (bar ?? 0) > 1;
+        let s = `${indent(level)}<part-group type="start" number="${num}">\n`;
+        s += `${indent(level + 1)}<group-symbol>${symbol}</group-symbol>\n`;
+        s += `${indent(level + 1)}<group-barline>${barLine ? 'yes' : 'no'}</group-barline>\n`;
+        s += `${indent(level)}</part-group>\n`;
+        starts.set(startPart, (starts.get(startPart) || '') + s);
+        const e = `${indent(level)}<part-group type="stop" number="${num}"/>\n`;
+        // Stops are emitted after the end part; inner groups must close before outer ones,
+        // so prepend (deepest group, emitted last, closes first).
+        stops.set(endPart, e + (stops.get(endPart) || ''));
+    };
+    walk(layout.group);
+    return { starts, stops };
+};
 /**
  * Encode complete LilyletDoc to MusicXML
  */
@@ -665,15 +763,31 @@ export const encode = (doc) => {
     }
     // Determine number of parts from first measure
     const numParts = doc.measures.length > 0 ? doc.measures[0].parts.length : 1;
+    // Staff-layout → <part-group> brackets/braces (if a [staves] layout is present and
+    // its staff count matches the parts' total staves).
+    let partGroups = {
+        starts: new Map(), stops: new Map(),
+    };
+    if (doc.metadata?.staves && doc.measures.length > 0) {
+        const staffCountPerPart = doc.measures[0].parts.map(part => {
+            let maxStaff = 1;
+            for (const voice of part.voices)
+                maxStaff = Math.max(maxStaff, voice.staff || 1);
+            return maxStaff;
+        });
+        partGroups = buildPartGroups(doc.metadata.staves, staffCountPerPart, 2);
+    }
     // Part list
     xml += `${indent(1)}<part-list>\n`;
     for (let pi = 0; pi < numParts; pi++) {
         const partId = `P${pi + 1}`;
         const partName = doc.measures[0]?.parts[pi]?.name
             || (numParts === 1 ? (doc.metadata?.title ? escapeXml(doc.metadata.title) : 'Music') : `Part ${pi + 1}`);
+        xml += partGroups.starts.get(pi) || '';
         xml += `${indent(2)}<score-part id="${partId}">\n`;
         xml += `${indent(3)}<part-name>${escapeXml(partName)}</part-name>\n`;
         xml += `${indent(2)}</score-part>\n`;
+        xml += partGroups.stops.get(pi) || '';
     }
     xml += `${indent(1)}</part-list>\n`;
     // Encode each part

package/lib/lilylet/serializer.js

@@ -199,11 +199,12 @@ const serializeMarks = (marks) => {
     return parts.join('');
 };
 // Serialize a note event with pitch environment tracking
-const serializeNoteEvent = (event, env, prevDuration) => {
+const serializeNoteEvent = (event, env, prevDuration, suppressGracePrefix = false) => {
     const parts = [];
     let currentEnv = env;
-    // Grace note prefix
-    if (event.grace) {
+    // Grace note prefix. When the caller groups consecutive grace notes into a single
+    // scoped \grace { ... }, it suppresses the per-note prefix and emits the wrapper.
+    if (event.grace && !suppressGracePrefix) {
         parts.push('\\grace ');
     }
     // Single note or chord
@@ -440,10 +441,10 @@ const serializeBarlineEvent = (event) => {
     return '';
 };
 // Serialize a single event with pitch environment tracking
-const serializeEvent = (event, env, prevDuration) => {
+const serializeEvent = (event, env, prevDuration, suppressGracePrefix = false) => {
     switch (event.type) {
         case 'note':
-            return serializeNoteEvent(event, env, prevDuration);
+            return serializeNoteEvent(event, env, prevDuration, suppressGracePrefix);
         case 'rest':
             return serializeRestEvent(event, env, prevDuration);
         case 'context':
@@ -576,6 +577,7 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
     }
     let activeStaff = effectiveInitialStaff;
     let activeStemDir;
+    let graceGroupOpen = false; // whether a scoped \grace { ... } is currently open
     for (let eventIdx = 0; eventIdx < voice.events.length; eventIdx++) {
         const event = voice.events[eventIdx];
         // Skip leading context-staff events already absorbed into effectiveInitialStaff
@@ -639,7 +641,18 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
                 activeStemDir = stemDir;
             }
         }
-        const { str: eventStr, newEnv } = serializeEvent(event, pitchEnv, prevDuration);
+        const isGraceNote = event.type === 'note' && !!event.grace;
+        // Group consecutive grace notes into one scoped \grace { ... } instead of
+        // emitting a separate \grace prefix per note.
+        if (isGraceNote && !graceGroupOpen) {
+            parts.push('\\grace {');
+            graceGroupOpen = true;
+        }
+        else if (!isGraceNote && graceGroupOpen) {
+            parts.push('}');
+            graceGroupOpen = false;
+        }
+        const { str: eventStr, newEnv } = serializeEvent(event, pitchEnv, prevDuration, graceGroupOpen);
         pitchEnv = newEnv;
         if (eventStr) {
             parts.push(eventStr);
@@ -663,6 +676,10 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
             emittedClefs[ctx.staff || activeStaff] = ctx.clef;
         }
     }
+    // Close a grace group left open at the end of the voice (unusual but possible).
+    if (graceGroupOpen) {
+        parts.push('}');
+    }
     return { str: parts.join(' '), newStaff: voice.staff };
 };
 // Serialize a part, tracking staff state across voices
@@ -756,6 +773,19 @@ const serializeMetadata = (metadata) => {
     if (metadata.instrument) {
         lines.push('[instrument "' + escapeString(metadata.instrument) + '"]');
     }
+    if (metadata.staves) {
+        lines.push('[staves "' + escapeString(metadata.staves) + '"]');
+    }
+    if (metadata.instruments) {
+        for (const [key, instr] of Object.entries(metadata.instruments)) {
+            let line = '[instrument-' + key + ' "' + escapeString(instr.name) + '"';
+            if (instr.shortName !== undefined) {
+                line += ' "' + escapeString(instr.shortName) + '"';
+            }
+            line += ']';
+            lines.push(line);
+        }
+    }
     if (metadata.autoBeam) {
         lines.push('[auto-beam "' + escapeString(metadata.autoBeam) + '"]');
     }

package/lib/lilylet/staffLayout.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Staff-layout parser, ported from FindLab starry (app/staffLayout/).
+ *
+ * The layout string uses STAFF as the leaf unit (distinct from ABC's %%score,
+ * which is voice-leaf). Brackets group staves: `{}` = Brace (grand staff),
+ * `<>` = Bracket, `[]` = Square; conjunctions between consecutive staves:
+ * `,` = Blank, `-` = Solid, `.` = Dashed. Staff ids are [a-zA-Z_0-9]+; a slot
+ * with no id is an anonymous staff (auto-named "1","2",…).
+ *
+ * Example: "<[v1-v2].va> {pl-pr} <b>" → 6 staves v1,v2,va,pl,pr,b grouped as
+ * a Bracket over { a Square [v1-v2] dashed-joined to va }, a Brace {pl-pr},
+ * and a Bracket <b>.
+ */
+export declare enum StaffGroupType {
+    Default = 0,
+    Brace = 1,// {}
+    Bracket = 2,// <>
+    Square = 3
+}
+export declare enum StaffConjunctionType {
+    Blank = 0,
+    Dashed = 1,
+    Solid = 2
+}
+export interface RawItem {
+    id: string | null;
+    leftBounds: string[];
+    rightBounds: string[];
+    conjunction: string | null;
+}
+export interface StaffGroup {
+    type: StaffGroupType;
+    subs?: StaffGroup[];
+    staff?: string;
+    level?: number;
+    grand?: boolean;
+    key?: string;
+    bar?: number;
+}
+export interface StaffGroupTrait {
+    group: StaffGroup;
+    range: [number, number];
+    key: string;
+}
+export declare const groupKey: (group: StaffGroup) => string | undefined;
+export declare class StaffLayout {
+    staffIds: string[];
+    conjunctions: StaffConjunctionType[];
+    group: StaffGroup;
+    groups: StaffGroupTrait[];
+    constructor(raw: RawItem[]);
+    get stavesCount(): number;
+}
+export declare const parseStaffLayout: (code: string) => StaffLayout;
+export declare const encodeStaffLayoutMEI: (layout: StaffLayout, nameDict?: {
+    [key: string]: string;
+}, indent?: number, tab?: string) => string;