@k-l-lambda/lilylet 0.1.69 → 0.1.71

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,6 @@
 import { Clef, Accidental, OrnamentType, StemDirection, HairpinType, PedalType, } from "./types.js";
+import { parseStaffLayout, StaffGroupType } from "./staffLayout.js";
+import { gmProgramOf } from "./gmInstruments.js";
 // MEI key signatures: positive = sharps, negative = flats
 const KEY_SIGS = {
     0: "0",
@@ -44,38 +46,65 @@ 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 Verovio only reads from <staffDef>); the visible clef shape/line is
+// emitted here, and a sounding-pitch transposition change is mirrored by a
+// between-measure <scoreDef>/<staffDef trans.*> emitted in the measure loop
+// (see emitClefTranspositionScoreDef). So only shape/line are emitted here.
 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}"`;
+};
+// The written→sounding transposition a clef declares, as {diat, semi}; {0,0}
+// when the clef declares none. Used to detect mid-piece transposition changes
+// and to emit the resetting <staffDef> when a transposing clef is replaced by a
+// plain one (Verovio retains a prior trans.* until an explicit 0/0 overrides it).
+const clefTransOf = (clefStr) => {
+    const c = resolveClef(clefStr);
+    return c.trans || { diat: 0, semi: 0 };
 };
-// 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
@@ -1368,6 +1397,36 @@ const generateTempoElement = (tempo, indent, staff = 1) => {
     }
     return `${indent}<tempo ${attrs} />\n`;
 };
+// The clef governing a measure's sounding pitch on one global staff: the clef
+// carried in from the previous measure, overridden by a leading clef change that
+// appears before the first note/rest in the measure (the normal boundary-change
+// case). A clef change occurring *after* notes does not retune this measure — it
+// becomes the carried clef for the next measure via clefState. This per-measure
+// granularity matches what Verovio honors for MIDI: a transposition change takes
+// effect only via a between-measure <scoreDef>/<staffDef trans.*>, never from a
+// mid-measure <clef> element.
+const measureStartClef = (measure, globalStaff, partInfos, carriedClef) => {
+    let active = carriedClef;
+    for (let pi = 0; pi < measure.parts.length; pi++) {
+        const partOffset = partInfos[pi]?.staffOffset || 0;
+        for (const voice of measure.parts[pi].voices) {
+            if ((partOffset + (voice.staff || 1)) !== globalStaff)
+                continue;
+            for (const event of voice.events) {
+                if (event.type === 'note' || event.type === 'rest' ||
+                    event.type === 'tuplet' || event.type === 'times' || event.type === 'tremolo') {
+                    break; // notes have started; a later clef change governs the next measure
+                }
+                if (event.type === 'context') {
+                    const ctx = event;
+                    if (ctx.clef)
+                        active = ctx.clef;
+                }
+            }
+        }
+    }
+    return active;
+};
 // Barline style to MEI @right attribute mapping
 const BARLINE_TO_MEI = {
     '|': 'single',
@@ -1622,33 +1681,149 @@ const analyzePartStructure = (doc) => {
     }
     return partInfos;
 };
+// MEI staffGrp @symbol for a layout group type (Default → none; Square → bracketsq).
+const LAYOUT_SYMBOL = [null, "brace", "bracket", "bracketsq"];
+const newChannelAllocator = () => ({ byProgram: new Map(), nextChannel: 0 });
+// Channel for a program: reuse the channel already assigned to that program,
+// else take the next free channel (skipping 9). Wraps past 16 as graceful
+// degradation for scores with more than 15 distinct timbres.
+const allocChannel = (alloc, program) => {
+    const existing = alloc.byProgram.get(program);
+    if (existing !== undefined)
+        return existing;
+    let ch = alloc.nextChannel;
+    if (ch % 16 === 9)
+        ch++; // skip GM drum channel
+    const assigned = ch % 16;
+    alloc.byProgram.set(program, assigned);
+    alloc.nextChannel = ch + 1;
+    return assigned;
+};
+// Build <label>/<labelAbbr> child XML for an instrument entry, or "" if none.
+// When the instrument name resolves to a General MIDI program, also emit an
+// <instrDef midi.instrnum midi.channel> sibling so Verovio's MIDI export assigns
+// that timbre (it honors only the numeric @midi.instrnum) on its own channel
+// (@midi.channel, else all instruments collide on channel 0). Unknown names emit
+// just the label, leaving Verovio's default program (0 = piano).
+const instrumentLabelXML = (instr, indent, channels) => {
+    if (!instr)
+        return "";
+    let xml = `${indent}<label>${escapeXml(instr.name)}</label>\n`;
+    if (instr.shortName !== undefined) {
+        xml += `${indent}<labelAbbr>${escapeXml(instr.shortName)}</labelAbbr>\n`;
+    }
+    const program = gmProgramOf(instr.name);
+    if (program !== undefined) {
+        const chanAttr = channels ? ` midi.channel="${allocChannel(channels, program)}"` : "";
+        xml += `${indent}<instrDef xml:id="${generateId("instrdef")}" midi.instrnum="${program}"${chanAttr} />\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, channels) => {
+    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, channels);
+    }
+    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 + "    ", channels);
+    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 + "    ", channels);
+    }
+    else {
+        for (const sub of group.subs || []) {
+            xml += layoutGroupToMEI(sub, staffDefAttrs, leafCounter, indent + "    ", instruments, channels);
+        }
+    }
+    xml += `${indent}</staffGrp>\n`;
+    return xml;
+};
+// Emit a <staffDef> from its attribute string, with optional instrument <label> children.
+const staffDefWithLabel = (attrs, instr, indent, channels) => {
+    if (attrs === undefined)
+        return "";
+    if (!instr)
+        return `${indent}<staffDef ${attrs} />\n`;
+    let xml = `${indent}<staffDef ${attrs}>\n`;
+    xml += instrumentLabelXML(instr, indent + "    ", channels);
+    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");
+    // One MIDI channel allocator per score: assigns a distinct channel per GM
+    // program so instruments don't collide on channel 0 (see allocChannel).
+    const channels = newChannelAllocator();
     // 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, channels);
+            layoutUsed = true;
         }
     }
-    xml += `${indent}    </staffGrp>\n`;
+    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}            `, channels);
+                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}            `, channels);
+                }
+                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}        `, channels);
+            }
+        }
+        xml += `${indent}    </staffGrp>\n`;
+    }
     xml += `${indent}</scoreDef>\n`;
     return xml;
 };
@@ -1983,7 +2158,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 = {};
@@ -1996,11 +2171,18 @@ const encode = (doc, options = {}) => {
     const octaveEndReplacements = {};
     // Initialize clef state from partInfos (convert local staff to global staff)
     const clefState = {};
+    // Running written→sounding transposition per global staff, as the verbatim
+    // "diat,semi" key. Seeded from the initial clefs (which the leading <scoreDef>
+    // already encoded via staffDefClefAttrs), then advanced whenever a measure
+    // starts under a clef with a different transposition.
+    const transState = {};
     for (let pi = 0; pi < partInfos.length; pi++) {
         const partInfo = partInfos[pi];
         for (const [localStaffStr, clef] of Object.entries(partInfo.clefs)) {
             const globalStaff = partInfo.staffOffset + parseInt(localStaffStr);
             clefState[globalStaff] = clef;
+            const t = clefTransOf(clef);
+            transState[globalStaff] = `${t.diat},${t.semi}`;
         }
     }
     // Helper to check if a measure has any musical content
@@ -2049,6 +2231,41 @@ const encode = (doc, options = {}) => {
                 mei += `${indent}${indent}${indent}${indent}${indent}${indent}<scoreDef xml:id="${generateId('scoredef')}"${meterSymAttr} meter.count="${currentTimeNum}" meter.unit="${currentTimeDen}" />\n`;
             }
         }
+        // Check for a written→sounding transposition change at this measure
+        // boundary and mirror it into MIDI. Verovio applies att.transposition only
+        // from <staffDef>, never from a mid-measure <clef>, so a change of
+        // transposing clef must be re-declared via a between-measure <scoreDef>.
+        // We emit only the staves whose transposition actually changed (a partial
+        // <staffGrp> leaves the others' state intact), using explicit "0,0" to
+        // clear a prior transposition when a transposing clef is replaced by a
+        // plain one. mi === 0 is already covered by the leading <scoreDef>.
+        if (mi > 0) {
+            const changed = [];
+            for (let si = 1; si <= totalStaves; si++) {
+                const startClef = measureStartClef(measure, si, partInfos, clefState[si]);
+                if (startClef === undefined)
+                    continue;
+                const t = clefTransOf(startClef);
+                const key = `${t.diat},${t.semi}`;
+                if (transState[si] === undefined) {
+                    transState[si] = key;
+                    continue;
+                }
+                if (key !== transState[si]) {
+                    transState[si] = key;
+                    const c = resolveClef(startClef);
+                    changed.push(`${indent}${indent}${indent}${indent}${indent}${indent}${indent}${indent}<staffDef xml:id="${generateId('staffdef')}" n="${si}" lines="5" clef.shape="${c.shape}" clef.line="${c.line}" trans.diat="${t.diat}" trans.semi="${t.semi}" />`);
+                }
+            }
+            if (changed.length > 0) {
+                const sd = `${indent}${indent}${indent}${indent}${indent}${indent}`;
+                mei += `${sd}<scoreDef xml:id="${generateId('scoredef')}">\n`;
+                mei += `${sd}${indent}<staffGrp xml:id="${generateId('staffgrp')}">\n`;
+                mei += changed.join("\n") + "\n";
+                mei += `${sd}${indent}</staffGrp>\n`;
+                mei += `${sd}</scoreDef>\n`;
+            }
+        }
         mei += encodeMeasure(measure, mi + 1, `${indent}${indent}${indent}${indent}${indent}${indent}`, totalStaves, tieState, slurState, hairpinState, ottavaState, currentKey, partInfos, clefState, octaveEndReplacements);
     });
     mei += `${indent}${indent}${indent}${indent}${indent}</section>\n`;

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

@@ -773,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,62 @@
+/**
+ * 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 interface SerializeStaffLayoutOptions {
+    anonymous?: boolean;
+    idMap?: (originalId: string) => string;
+}
+export declare const serializeStaffLayout: (layout: StaffLayout, options?: SerializeStaffLayoutOptions) => string;
+export declare const encodeStaffLayoutMEI: (layout: StaffLayout, nameDict?: {
+    [key: string]: string;
+}, indent?: number, tab?: string) => string;