@k-l-lambda/lilylet 0.1.68 → 0.1.70

package/source/lilylet/index.ts

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

package/source/lilylet/lilylet.jison

@@ -130,6 +130,25 @@
 	const dynamicEvent = (type) => ({ type: 'dynamic', dynamicType: type });
 	const markupMark = (content) => ({ markType: 'markup', content });
 
+	// Build an { instruments: { <key>: { name, shortName? } } } fragment from a
+	// `[instrument-<key>` header token. <key> is a staff-layout group key — a single
+	// staff id ("1", "v1", "b") or a range ("1-2", "pl-pr") — taken verbatim after the
+	// "[instrument-" prefix so it lines up with staffLayout's groupKey().
+	const instrumentStaff = (token, name, shortName) => {
+		const key = token.slice('[instrument-'.length);
+		const entry = shortName !== undefined ? { name, shortName } : { name };
+		return { instruments: { [key]: entry } };
+	};
+
+	// Merge two header fragments. Plain fields are overwritten by the later one, but the
+	// `instruments` map is deep-merged so multiple [instrument-<key>] lines accumulate.
+	const mergeHeaders = (a, b) => {
+		const merged = { ...a, ...b };
+		if (a.instruments || b.instruments)
+			merged.instruments = { ...a.instruments, ...b.instruments };
+		return merged;
+	};
+
 	// Parse PITCH token (e.g., "c", "cs", "bf", "css", "bff") into phonet and accidental
 	const parsePitch = (text, octave) => {
 		const phonet = text[0].toLowerCase();
@@ -227,8 +246,10 @@
 \[arranger						return 'HEADER_ARRANGER'
 \[lyricist						return 'HEADER_LYRICIST'
 \[opus							return 'HEADER_OPUS'
+\[instrument\-[A-Za-z0-9_]+(?:\-[A-Za-z0-9_]+)*	return 'HEADER_INSTRUMENT_STAFF'
 \[instrument					return 'HEADER_INSTRUMENT'
 \[genre							return 'HEADER_GENRE'
+\[staves						return 'HEADER_STAVES'
 \[auto\-beam					return 'HEADER_AUTOBEAM'
 \]								return ']'
 
@@ -350,6 +371,8 @@ document
 content
 	: headers measures							-> ({ metadata: $1, measures: $2 })
 	| headers newlines measures					-> ({ metadata: $1, measures: $3 })
+	| newlines headers measures					-> ({ metadata: $2, measures: $3 })
+	| newlines headers newlines measures		-> ({ metadata: $2, measures: $4 })
 	| newlines measures							-> ({ metadata: undefined, measures: $2 })
 	| measures									-> ({ metadata: undefined, measures: $1 })
 	;
@@ -361,9 +384,9 @@ newlines
 
 headers
 	: header									-> $1
-	| headers header							-> ({ ...$1, ...$2 })
+	| headers header							-> mergeHeaders($1, $2)
 	| headers NEWLINE							-> $1
-	| headers NEWLINE header					-> ({ ...$1, ...$3 })
+	| headers NEWLINE header					-> mergeHeaders($1, $3)
 	;
 
 header
@@ -374,7 +397,10 @@ header
 	| HEADER_LYRICIST STRING ']'				-> ({ lyricist: $2.slice(1, -1) })
 	| HEADER_OPUS STRING ']'					-> ({ opus: $2.slice(1, -1) })
 	| HEADER_INSTRUMENT STRING ']'				-> ({ instrument: $2.slice(1, -1) })
+	| HEADER_INSTRUMENT_STAFF STRING ']'		-> instrumentStaff($1, $2.slice(1, -1))
+	| HEADER_INSTRUMENT_STAFF STRING STRING ']'	-> instrumentStaff($1, $2.slice(1, -1), $3.slice(1, -1))
 	| HEADER_GENRE STRING ']'					-> ({ genre: $2.slice(1, -1) })
+	| HEADER_STAVES STRING ']'					-> ({ staves: $2.slice(1, -1) })
 	| HEADER_AUTOBEAM STRING ']'				-> ({ autoBeam: $2.slice(1, -1) })
 	;
 

package/source/lilylet/meiEncoder.ts

@@ -25,7 +25,9 @@ import {
 	NavigationMarkType,
 	Tempo,
 	Event,
+	InstrumentName,
 } from "./types";
+import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
 
 
 // MEI key signatures: positive = sharps, negative = flats
@@ -80,41 +82,62 @@ const CLEF_SHAPES: Record<string, { shape: string; line: number }> = {
 };
 
 
-// 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").
-const resolveClef = (clefStr: string): { shape: string; line: number; dis?: "8" | "15"; disPlace?: "above" | "below" } => {
-	const match = clefStr.match(/^(.*?)([_^])(8|15)$/);
+// 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: number, up: boolean): { diat: number; semi: number } => {
+	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: string): { shape: string; line: number; trans?: { diat: number; semi: number } } => {
+	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] as "8" | "15",
-		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: string): string => {
 	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: string): string => {
 	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
 // division: 1=whole, 2=half, 4=quarter, 8=eighth, etc.
 const DURATIONS: Record<number, string> = {
@@ -1995,6 +2018,76 @@ const analyzePartStructure = (doc: LilyletDoc): PartInfo[] => {
 	return partInfos;
 };
 
+// MEI staffGrp @symbol for a layout group type (Default → none; Square → bracketsq).
+const LAYOUT_SYMBOL: (string | null)[] = [null, "brace", "bracket", "bracketsq"];
+
+// Build <label>/<labelAbbr> child XML for an instrument entry, or "" if none.
+const instrumentLabelXML = (
+	instr: InstrumentName | undefined,
+	indent: string,
+): string => {
+	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: StaffGroup,
+	staffDefAttrs: string[],
+	leafCounter: { i: number },
+	indent: string,
+	instruments: { [key: string]: InstrumentName },
+): string => {
+	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: string | undefined,
+	instr: InstrumentName | undefined,
+	indent: string,
+): string => {
+	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: string,
@@ -2002,36 +2095,75 @@ const encodeScoreDef = (
 	timeDen: number,
 	partInfos: PartInfo[],
 	indent: string,
-	meterSymbol?: 'common' | 'cut'
+	meterSymbol?: 'common' | 'cut',
+	stavesCode?: string,
+	instruments: { [key: string]: InstrumentName } = {}
 ): string => {
 	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`;
+	// Flat ordered list of global staves (n + clef), in part/voice order.
+	const flatStaves: { n: number; clef: Clef }[] = [];
+	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 });
+		}
+	}
+
+	// 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`;
-		} 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`;
 		}
+
+		xml += `${indent}    </staffGrp>\n`;
 	}
 
-	xml += `${indent}    </staffGrp>\n`;
 	xml += `${indent}</scoreDef>\n`;
 	return xml;
 };
@@ -2397,7 +2529,7 @@ const encode = (doc: LilyletDoc, options: MEIEncoderOptions = {}): string => {
 	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

package/source/lilylet/musicXmlDecoder.ts

@@ -749,6 +749,15 @@ const parseMetadata = (doc: Document): Metadata => {
 				}
 			}
 		}
+
+		// 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/source/lilylet/musicXmlEncoder.ts

@@ -43,6 +43,8 @@ import {
 	calculateDuration,
 } from "./musicXmlUtils";
 
+import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
+
 
 // === Constants and Reverse Mappings ===
 
@@ -135,6 +137,11 @@ const BARLINE_TO_XML: Record<string, { barStyle: string; repeat?: string }> = {
 };
 
 
+// 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: (string | null)[] = [null, "brace", "bracket", "square"];
+
 // === XML Helper Functions ===
 
 const escapeXml = (text: string): string => {
@@ -753,6 +760,7 @@ const encodeMeasure = (
 					break;
 				}
 
+				case 'times':
 				case 'tuplet': {
 					const tupletEvents = event.events.filter(e => e.type === 'note' || e.type === 'rest') as (NoteEvent | RestEvent)[];
 					for (let ti = 0; ti < tupletEvents.length; ti++) {
@@ -847,12 +855,122 @@ const encodeMetadata = (metadata: Metadata, level: number): string => {
 	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: string,
+	staffCountPerPart: number[],
+	level: number,
+): { starts: Map<number, string>; stops: Map<number, string> } => {
+	const starts = new Map<number, string>();
+	const stops = new Map<number, string>();
+
+	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: number[] = [];
+	const partLastLeaf: number[] = [];
+	let leaf = 0;
+	for (let pi = 0; pi < staffCountPerPart.length; pi++) {
+		partFirstLeaf[pi] = leaf;
+		leaf += staffCountPerPart[pi];
+		partLastLeaf[pi] = leaf - 1;
+	}
+
+	const leafToPart = (leafIdx: number): number => {
+		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: StaffGroup): void => {
+		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: number, endPart: number, symbol: string, bar?: number): void => {
+		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
  */
@@ -869,15 +987,31 @@ export const encode = (doc: LilyletDoc): string => {
 	// 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: Map<number, string>; stops: Map<number, string> } = {
+		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`;
 

package/source/lilylet/serializer.ts

@@ -278,13 +278,15 @@ const serializeMarks = (marks: Mark[]): string => {
 const serializeNoteEvent = (
 	event: NoteEvent,
 	env: PitchEnv,
-	prevDuration?: Duration
+	prevDuration?: Duration,
+	suppressGracePrefix: boolean = false
 ): { str: string; newEnv: PitchEnv } => {
 	const parts: string[] = [];
 	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 ');
 	}
 
@@ -564,11 +566,12 @@ const serializeBarlineEvent = (event: BarlineEvent): string => {
 const serializeEvent = (
 	event: Event,
 	env: PitchEnv,
-	prevDuration?: Duration
+	prevDuration?: Duration,
+	suppressGracePrefix: boolean = false
 ): { str: string; newEnv: PitchEnv } => {
 	switch (event.type) {
 		case 'note':
-			return serializeNoteEvent(event as NoteEvent, env, prevDuration);
+			return serializeNoteEvent(event as NoteEvent, env, prevDuration, suppressGracePrefix);
 		case 'rest':
 			return serializeRestEvent(event as RestEvent, env, prevDuration);
 		case 'context':
@@ -716,6 +719,7 @@ const serializeVoice = (
 
 	let activeStaff = effectiveInitialStaff;
 	let activeStemDir: StemDirection | undefined;
+	let graceGroupOpen = false;  // whether a scoped \grace { ... } is currently open
 
 	for (let eventIdx = 0; eventIdx < voice.events.length; eventIdx++) {
 		const event = voice.events[eventIdx];
@@ -781,7 +785,19 @@ const serializeVoice = (
 			}
 		}
 
-		const { str: eventStr, newEnv } = serializeEvent(event, pitchEnv, prevDuration);
+		const isGraceNote = event.type === 'note' && !!(event as NoteEvent).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) {
@@ -805,6 +821,11 @@ const serializeVoice = (
 		}
 	}
 
+	// 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 };
 };
 
@@ -930,6 +951,19 @@ const serializeMetadata = (metadata: Metadata): string => {
 	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) + '"]');
 	}