@k-l-lambda/lilylet 0.1.82 → 0.1.84

package/source/lilylet/highlight.ts

@@ -18,6 +18,7 @@ export type HighlightScope =
 	| "hairpin"
 	| "header"
 	| "keyword"
+	| "lyric"
 	| "markup"
 	| "mode"
 	| "navigation"
@@ -96,6 +97,7 @@ export const HIGHLIGHT_RULES: HighlightRule[] = [
 	{ re: /(?:\\segno\b)/iy, scope: "navigation" },
 	{ re: /(?:\\chords\b)/iy, scope: "keyword" },
 	{ re: /(?:\\markup\b)/iy, scope: "markup" },
+	{ re: /(?:\\addlyrics\b)/iy, scope: "lyric" },
 	{ re: /(?:\\<)/iy, scope: "hairpin" },
 	{ re: /(?:\\>)/iy, scope: "hairpin" },
 	{ re: /(?:\\!)/iy, scope: "hairpin" },
@@ -155,6 +157,13 @@ export const HIGHLIGHT_RULES: HighlightRule[] = [
 	{ re: /(?:=)/iy, scope: "operator" },
 	{ re: /(?:[rR])/iy, scope: "rest" },
 	{ re: /(?:[sS])/iy, scope: "rest" },
+	{ re: /(?:\{)/iy, scope: "brace" },
+	{ re: /(?:\})/iy, scope: "brace" },
+	{ re: /(?:--)/iy, scope: "lyric" },
+	{ re: /(?:__\b)/iy, scope: "lyric" },
+	{ re: /(?:_\b)/iy, scope: "lyric" },
+	{ re: /(?:"([^\"\\]|\\.)*")/iy, scope: "string" },
+	{ re: /(?:[^ \t\r\n{}\"\\]+)/iy, scope: "string" },
 ];
 
 /**

package/source/lilylet/lilylet.jison

@@ -34,6 +34,20 @@
 		};
 	};
 
+	// Build a lyric lane (one \addlyrics block) from raw lyric items. `--` is a
+	// connector that hyphenates the preceding syllable (it does not consume a
+	// note slot); `_` is a skipped slot; `__` extends the preceding syllable.
+	const addlyricsLane = (items) => {
+		const syllables = [];
+		for (const it of items) {
+			if (it.text !== undefined) syllables.push({ text: it.text });
+			else if (it.hyphen) { if (syllables.length) syllables[syllables.length - 1].hyphen = true; }
+			else if (it.skip) syllables.push({ skip: true });
+			else if (it.extend) { if (syllables.length) syllables[syllables.length - 1].extend = true; else syllables.push({ extend: true }); }
+		}
+		return { syllables };
+	};
+
 	const restEvent = (dur, options = {}) => ({
 		type: 'rest',
 		duration: dur,
@@ -51,7 +65,7 @@
 		mode,
 	});
 
-	const voice = (staff, events) => {
+	const voice = (staff, events, lyrics) => {
 		// Use the first \staff "N" context event that appears before any musical event
 		// (notes/rests/tuplets) as the authoritative voice.staff.
 		// Skip pitchReset events (from NEWLINE tokens at voice-line boundaries).
@@ -67,9 +81,13 @@
 			}
 			break; // first musical/structural event — stop
 		}
+		// \addlyrics lanes are scoped to THIS voice; verse numbers are 1-based by
+		// order of \addlyrics blocks within the voice.
+		const lanes = lyrics && lyrics.length ? lyrics.map((lane, i) => ({ verse: i + 1, ...lane })) : undefined;
 		return {
 			staff: leadingStaff != null ? leadingStaff : 1,
 			events,
+			lyrics: lanes,
 		};
 	};
 
@@ -241,6 +259,7 @@
 
 %option flex unicode case-insensitive
 
+%x lyric
 
 %%
 
@@ -262,7 +281,7 @@
 \[auto\-beam					return 'HEADER_AUTOBEAM'
 \]								return ']'
 
-\"([^\"\\]|\\.)*\"					return 'STRING'
+\"([^\"\\]|\\.)*\"				return 'STRING'
 
 "\\clef"						return 'CMD_CLEF'
 "\\key"							return 'CMD_KEY'
@@ -292,6 +311,7 @@
 "\\segno"						return 'CMD_SEGNO'
 "\\chords"						return 'CMD_CHORDS'
 "\\markup"						return 'CMD_MARKUP'
+"\\addlyrics"					{ this.pushState('lyric'); return 'CMD_ADDLYRICS'; }
 
 "\\<"							return 'CMD_CRESC_BEGIN'
 "\\>"							return 'CMD_DIM_BEGIN'
@@ -369,6 +389,17 @@
 .								{}
 
 
+<lyric>"{"						return '{'
+<lyric>"}"						{ this.popState(); return '}'; }
+<lyric>[ \t]+					{}
+<lyric>(\r?\n)+					{}
+<lyric>"--"						return 'LYRIC_HYPHEN'
+<lyric>"__"						return 'LYRIC_EXTENDER'
+<lyric>"_"						return 'LYRIC_SKIP'
+<lyric>\"([^\"\\]|\\.)*\"		return 'LYRIC_WORD'
+<lyric>[^ \t\r\n{}\"\\]+		return 'LYRIC_WORD'
+
+
 /lex
 
 %start document
@@ -423,7 +454,7 @@ measures
 	;
 
 measure_content
-	: parts										%{
+	: parts									%{
 		// Check \partial declarations: warn if declared duration ≠ actual voice ticks
 		let partialDur = null;
 		outer: for (const p of $1) {
@@ -454,6 +485,17 @@ measure_content
 	%}
 	;
 
+addlyrics_opt
+	: /* empty */								{ $$ = undefined; }
+	| addlyrics_blocks							{ $$ = $1; }
+	;
+
+addlyrics_blocks
+	: addlyrics_block							{ $$ = [$1]; }
+	| addlyrics_blocks addlyrics_block			{ $$ = $1.concat([$2]); }
+	| addlyrics_blocks NEWLINE					{ $$ = $1; }
+	;
+
 parts
 	: part_voices								{ $$ = [part($1)]; }
 	| parts PART_SEP part_start part_voices		{ $$ = $1.concat([part($4)]); }
@@ -464,8 +506,12 @@ part_start
 	;
 
 part_voices
-	: voice_events								{ $$ = [voice(currentStaff, $1)]; }
-	| part_voices VOICE_SEP voice_events		{ $$ = $1.concat([voice(currentStaff, $3)]); }
+	: voice_block								{ $$ = [voice(currentStaff, $1.events, $1.lyrics)]; }
+	| part_voices VOICE_SEP voice_block			{ $$ = $1.concat([voice(currentStaff, $3.events, $3.lyrics)]); }
+	;
+
+voice_block
+	: voice_events addlyrics_opt				{ $$ = { events: $1, lyrics: $2 }; }
 	;
 
 voice_events
@@ -787,3 +833,19 @@ markup_mark
 glissando_mark
 	: CMD_GLISSANDO								-> glissando()
 	;
+
+addlyrics_block
+	: CMD_ADDLYRICS '{' lyric_sequence '}'		-> addlyricsLane($3)
+	;
+
+lyric_sequence
+	: /* empty */								{ $$ = []; }
+	| lyric_sequence lyric_item					{ $$ = $1.concat([$2]); }
+	;
+
+lyric_item
+	: LYRIC_WORD								-> ({ text: $1.charAt(0) === '"' ? unq($1) : $1 })
+	| LYRIC_HYPHEN								-> ({ hyphen: true })
+	| LYRIC_SKIP								-> ({ skip: true })
+	| LYRIC_EXTENDER							-> ({ extend: true })
+	;

package/source/lilylet/meiEncoder.ts

@@ -26,6 +26,8 @@ import {
 	Tempo,
 	Event,
 	InstrumentName,
+	LyricLane,
+	LyricSyllable,
 } from "./types";
 import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
 import { gmProgramOf } from "./gmInstruments";
@@ -327,6 +329,49 @@ const tremoloToStemMod = (division: number): string | undefined => {
 	return undefined;
 };
 
+// Encode the lyric slots attached to one rhythmic event. Lanes are measure-local
+// because the parser stores them on the Voice created for that measure.
+interface LyricCursor {
+	consume(): string;
+	consumeRest(): void;
+}
+
+const lyricWordPosition = (syllables: LyricSyllable[], index: number): 'i' | 'm' | 't' | 'u' => {
+	const syllable = syllables[index];
+	if (!syllable?.text) return 'u';
+	const previous = index > 0 ? syllables[index - 1] : undefined;
+	if (previous?.text && previous.hyphen) return syllable.hyphen ? 'm' : 't';
+	return syllable.hyphen ? 'i' : 'u';
+};
+
+const lyricSyllableXml = (lane: LyricLane, index: number, indent: string): string => {
+	const syllable = lane.syllables[index];
+	if (!syllable || syllable.skip || syllable.text === undefined) return '';
+	const wordpos = lyricWordPosition(lane.syllables, index);
+	const con = syllable.extend ? 'u' : syllable.hyphen ? 'd' : undefined;
+	const attrs = ` wordpos="${wordpos}"${con ? ` con="${con}"` : ''}`;
+	return `${indent}<syl${attrs}>${escapeXml(syllable.text)}</syl>\n`;
+};
+
+const makeLyricCursors = (lanes: LyricLane[] | undefined, indent: string): LyricCursor[] =>
+	(lanes || []).map((lane) => {
+		let index = 0;
+		const consume = (): string => {
+			const current = index++;
+			const syllable = lane.syllables[current];
+			if (!syllable || syllable.skip || syllable.text === undefined) return '';
+			const verse = lane.verse || 1;
+			return `${indent}<verse n="${verse}">\n${lyricSyllableXml(lane, current, indent + '    ')}${indent}</verse>\n`;
+		};
+		return { consume, consumeRest: () => { index++; } };
+	});
+
+const lyricXmlForEvent = (cursors: LyricCursor[], indent: string): string => {
+	let xml = '';
+	for (const cursor of cursors) xml += cursor.consume();
+	return xml;
+};
+
 // Build note element
 const buildNoteElement = (
 	pitch: { pname: string; oct: number; octGes?: number; accid?: string; accidGes?: string },
@@ -341,7 +386,8 @@ const buildNoteElement = (
 		staff?: number;
 		layerStaff?: number;
 		artics?: { type: string; placement?: 'above' | 'below' }[];
-		tremolo?: number;
+			tremolo?: number;
+			lyricXml?: string;
 	} = {},
 	noteId?: string
 ): string => {
@@ -366,8 +412,7 @@ const buildNoteElement = (
 		if (stemMod) attrs += ` stem.mod="${stemMod}"`;
 	}
 
-	// Only artics remain as child elements; ornaments are control events
-	const hasChildren = !inChord && options.artics && options.artics.length > 0;
+	const hasChildren = !inChord && ((options.artics && options.artics.length > 0) || !!options.lyricXml);
 
 	if (!hasChildren) {
 		return `${indent}<note ${attrs} />\n`;
@@ -392,6 +437,8 @@ const buildNoteElement = (
 		}
 	}
 
+	if (options.lyricXml) result += options.lyricXml;
+
 	result += `${indent}</note>\n`;
 	return result;
 };
@@ -592,7 +639,8 @@ const noteEventToMEI = (
 	contextStemDir?: StemDirection,
 	keyFifths: number = 0,
 	ottavaShift: number = 0,
-	measureAccidentals?: Map<string, string>
+	measureAccidentals?: Map<string, string>,
+	lyricXml: string = ''
 ): NoteEventResult => {
 	const dur = DURATIONS[event.duration.division] || "4";
 	const dots = event.duration.dots || 0;
@@ -630,7 +678,7 @@ const noteEventToMEI = (
 		const pitch = encodePitch(event.pitches[0], keyFifths, ottavaShift, measureAccidentals);
 		const noteId = generateId('note');
 		return {
-			xml: buildNoteElement(pitch, dur, dots, indent, false, noteOptions, noteId),
+			xml: buildNoteElement(pitch, dur, dots, indent, false, { ...noteOptions, lyricXml }, noteId),
 			elementId: noteId,
 			hairpin: markOptions.hairpin,
 			pedal: markOptions.pedal,
@@ -693,6 +741,7 @@ const noteEventToMEI = (
 		}
 	}
 
+		if (lyricXml) result += lyricXml;
 	result += `${indent}</chord>\n`;
 	return {
 		xml: result,
@@ -795,7 +844,7 @@ const tupletHasInternalBeams = (event: TupletEvent): boolean => {
 };
 
 // Convert TupletEvent to MEI
-const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: number, keyFifths: number = 0, currentStaff?: number, ottavaShift: number = 0, inParentBeam: boolean = false, measureAccidentals?: Map<string, string>, currentClef?: string): TupletEventResult => {
+const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: number, keyFifths: number = 0, currentStaff?: number, ottavaShift: number = 0, inParentBeam: boolean = false, measureAccidentals?: Map<string, string>, currentClef?: string, lyricCursors: LyricCursor[] = []): TupletEventResult => {
 	// LilyPond \times 2/3 means "multiply duration by 2/3"
 	// So 3 notes × 2/3 = 2 beats worth (3 in time of 2)
 	// MEI: num = number of notes written, numbase = normal equivalent
@@ -847,7 +896,8 @@ const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: numbe
 			const effectiveNoteEvent = effectiveStaff && layerStaff && effectiveStaff !== layerStaff
 				? { ...noteEvent, staff: effectiveStaff }
 				: noteEvent;
-			const result = noteEventToMEI(effectiveNoteEvent, noteIndent, layerStaff, false, undefined, keyFifths, ottavaShift, measureAccidentals);
+			const lyricXml = lyricCursors.length ? lyricXmlForEvent(lyricCursors, noteIndent + '    ') : '';
+				const result = noteEventToMEI(effectiveNoteEvent, noteIndent, layerStaff, false, undefined, keyFifths, ottavaShift, measureAccidentals, lyricXml);
 			xml += result.xml;
 
 			if (!firstNoteId) firstNoteId = result.elementId;
@@ -1152,6 +1202,8 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 	let beamElementOpen = false;  // Whether actual <beam> element is open (passed to tuplets)
 	const baseIndent = indent + '    ';
 
+	const lyricCursors = makeLyricCursors(voice.lyrics, baseIndent);
+
 	// Track current clef to only emit changes
 	let currentClef: Clef | undefined = initialClef;
 
@@ -1327,7 +1379,8 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 					? { ...noteEvent, staff: currentStaff }
 					: noteEvent;
 
-				const result = noteEventToMEI(effectiveNoteEvent, currentIndent, voice.staff, tieEnd, currentStemDirection, keyFifths, currentOttavaShift, measureAccidentals);
+				const eventLyricXml = isGraceNote ? '' : lyricXmlForEvent(lyricCursors, currentIndent + '    ');
+			const result = noteEventToMEI(effectiveNoteEvent, currentIndent, voice.staff, tieEnd, currentStemDirection, keyFifths, currentOttavaShift, measureAccidentals, eventLyricXml);
 				xml += result.xml;
 				lastNoteId = result.elementId;
 				extendOttavaEnd(result.elementId);
@@ -1472,7 +1525,7 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				// Pass beamElementOpen to tuplet so it knows not to create its own beam
 				// A pending ottava shift applies to the tuplet's notes' written octave.
 				applyPendingOttavaShift();
-				const tupletResult = tupletEventToMEI(event as TupletEvent, currentIndent, voice.staff, keyFifths, currentStaff, currentOttavaShift, beamElementOpen, measureAccidentals, currentClef);
+				const tupletResult = tupletEventToMEI(event as TupletEvent, currentIndent, voice.staff, keyFifths, currentStaff, currentOttavaShift, beamElementOpen, measureAccidentals, currentClef, lyricCursors);
 				xml += tupletResult.xml;
 
 				// An ottava span can open on, run through, or close at a tuplet (common

package/source/lilylet/musicXmlDecoder.ts

@@ -30,6 +30,8 @@ import {
 	BarlineEvent,
 	HarmonyEvent,
 	TupletEvent,
+	LyricLane,
+	LyricSyllable,
 } from './types';
 
 import {
@@ -44,6 +46,7 @@ import {
 	MusicXmlHarmony,
 	MusicXmlNotations,
 	MusicXmlPitch,
+	MusicXmlLyric,
 } from './musicXmlTypes';
 
 import {
@@ -554,6 +557,24 @@ const parseNote = (noteEl: Element, divisions: number): MusicXmlNote => {
 		}));
 	}
 
+	// Lyrics are direct children of <note>; retain one slot per verse.
+	const lyricEls = getDirectChildren(noteEl, 'lyric');
+	let lyrics: MusicXmlLyric[] | undefined;
+	if (lyricEls.length > 0) {
+		lyrics = lyricEls.map(lyricEl => {
+			const rawSyllabic = getElementText(lyricEl, 'syllabic');
+			const syllabic = rawSyllabic === 'begin' || rawSyllabic === 'middle' ||
+				rawSyllabic === 'end' || rawSyllabic === 'single' ? rawSyllabic : 'single';
+			const textEl = getDirectChildren(lyricEl, 'text')[0];
+			return {
+				number: getAttributeNumber(lyricEl, 'number') || 1,
+				text: textEl?.textContent ?? undefined,
+				syllabic,
+				extend: getDirectChildren(lyricEl, 'extend').length > 0,
+			};
+		});
+	}
+
 	return {
 		isChord,
 		isRest,
@@ -572,6 +593,7 @@ const parseNote = (noteEl: Element, divisions: number): MusicXmlNote => {
 		notations,
 		fingerings,
 		beams,
+		lyrics,
 	};
 };
 
@@ -1192,7 +1214,7 @@ const directionToMarks = (
  * Result of converting a measure - now includes voices grouped by voice number
  */
 interface MeasureConversionResult {
-	voiceMap: Map<number, { events: Event[]; staff: number }>;
+	voiceMap: Map<number, { events: Event[]; staff: number; lyrics: Map<number, LyricSyllable[]> }>;
 	key?: KeySignature;
 	timeSig?: Fraction;
 	barline?: BarlineEvent;
@@ -1267,6 +1289,36 @@ const convertMeasure = (
 	let leadingBarline: BarlineEvent | undefined;
 	const harmonies: HarmonyEvent[] = [];
 	const clefs: Map<number, ContextChange> = new Map();
+	const lyricLanes: Map<number, { staff: number; lanes: Map<number, LyricSyllable[]>; noteIndex: number }> = new Map();
+	const lyricForNote = (note: MusicXmlNote, voiceNum: number, staffNum: number): void => {
+		if (note.isGrace || note.isChord || note.isRest) return;
+		let state = lyricLanes.get(voiceNum);
+		if (!state) {
+			state = { staff: staffNum, lanes: new Map(), noteIndex: 0 };
+			lyricLanes.set(voiceNum, state);
+		}
+		const byVerse = new Map((note.lyrics || []).map(l => [l.number, l]));
+		for (const number of byVerse.keys()) {
+			if (!state.lanes.has(number)) {
+				const lane: LyricSyllable[] = [];
+				for (let i = 0; i < state.noteIndex; i++) lane.push({ skip: true });
+				state.lanes.set(number, lane);
+			}
+		}
+		for (const [number, lane] of state.lanes) {
+			const lyric = byVerse.get(number);
+			if (!lyric) {
+				lane.push({ skip: true });
+			} else {
+				lane.push({
+					text: lyric.text,
+					hyphen: lyric.syllabic === 'begin' || lyric.syllabic === 'middle' ? true : undefined,
+					extend: lyric.extend || undefined,
+				});
+			}
+		}
+		state.noteIndex++;
+	};
 
 	// Pending marks from directions (to attach to next note), per voice
 	const pendingMarks: Map<number, Mark[]> = new Map();
@@ -1353,6 +1405,7 @@ const convertMeasure = (
 			const note = parseNote(child, voiceTracker.getDivisions());
 			const voiceNum = note.voice;
 			const staffNum = note.staff || 1;
+			lyricForNote(note, voiceNum, staffNum);
 			currentVoice = voiceNum;
 			// Record that this staff now has notes this measure and which voice is
 			// active on it, so a subsequent mid-measure <clef> attaches inline here.
@@ -1687,11 +1740,12 @@ const convertMeasure = (
 	}
 
 	// Build voice map from tracker
-	const voiceMap = new Map<number, { events: Event[]; staff: number }>();
+	const voiceMap = new Map<number, { events: Event[]; staff: number; lyrics: Map<number, LyricSyllable[]> }>();
 	for (const [voiceNum, voiceState] of voiceTracker.getVoices()) {
 		voiceMap.set(voiceNum, {
 			events: voiceState.events,
 			staff: voiceState.staff,
+			lyrics: lyricLanes.get(voiceNum)?.lanes || new Map(),
 		});
 	}
 
@@ -1825,6 +1879,9 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 			voices.push({
 				staff: voiceData.staff,
 				events,
+				lyrics: voiceData.lyrics.size > 0
+					? Array.from(voiceData.lyrics.entries()).sort(([a], [b]) => a - b).map(([verse, syllables]) => ({ verse, syllables }))
+					: undefined,
 			});
 		}
 

package/source/lilylet/musicXmlEncoder.ts

@@ -36,6 +36,8 @@ import {
 	Tempo,
 	Metadata,
 	Fraction,
+	LyricLane,
+	LyricSyllable,
 } from "./types";
 
 import {
@@ -157,6 +159,38 @@ const escapeXml = (text: string): string => {
 
 const indent = (level: number): string => '  '.repeat(level);
 
+interface MusicXmlLyricCursor {
+	lane: LyricLane;
+	index: number;
+	inChain: boolean;
+}
+
+const makeLyricCursors = (lanes: LyricLane[] | undefined): MusicXmlLyricCursor[] =>
+	(lanes || []).map(lane => ({ lane, index: 0, inChain: false }));
+
+const lyricForCursor = (cursor: MusicXmlLyricCursor): string | undefined => {
+	const syllable = cursor.lane.syllables[cursor.index++];
+	if (!syllable || syllable.skip || syllable.text === undefined) return undefined;
+	const syllabic = cursor.inChain
+		? (syllable.hyphen ? 'middle' : 'end')
+		: (syllable.hyphen ? 'begin' : 'single');
+	cursor.inChain = !!syllable.hyphen;
+	return `<lyric number="${cursor.lane.verse || 1}"><syllabic>${syllabic}</syllabic>` +
+		`<text>${escapeXml(syllable.text)}</text>${syllable.extend ? '<extend/>' : ''}</lyric>`;
+};
+
+const lyricXmlForNote = (cursors: MusicXmlLyricCursor[], level: number, grace?: boolean): string => {
+	if (grace) return '';
+	let xml = '';
+	for (const cursor of cursors) {
+		const lyric = lyricForCursor(cursor);
+		if (lyric) {
+			xml += `${indent(level)}${lyric}\n`;
+		}
+	}
+	return xml;
+};
+
 
 // === Encoding Functions ===
 
@@ -396,7 +430,8 @@ const encodeNote = (
 	voice: number,
 	staff: number,
 	level: number,
-	isChord: boolean = false
+	isChord: boolean = false,
+	lyricXml: string = ''
 ): string => {
 	let xml = `${indent(level)}<note>\n`;
 
@@ -458,6 +493,7 @@ const encodeNote = (
 		xml += encodeNotations(event.marks, level + 1);
 	}
 
+	xml += lyricXml;
 	xml += `${indent(level)}</note>\n`;
 
 	return xml;
@@ -762,6 +798,7 @@ const encodeMeasure = (
 	for (const voice of part.voices) {
 		let currentStaff = voice.staff || 1;
 		let voicePosition = 0;
+		const lyricCursors = makeLyricCursors(voice.lyrics);
 
 		// Backup if needed
 		if (currentPosition > 0 && voiceNum > 1) {
@@ -785,7 +822,8 @@ const encodeMeasure = (
 					}
 
 					// Encode main note
-					xml += encodeNote(event, voiceNum, currentStaff, level + 1);
+					xml += encodeNote(event, voiceNum, currentStaff, level + 1, false,
+						lyricXmlForNote(lyricCursors, level + 2, event.grace));
 					const dur = calculateDuration(event.duration);
 					voicePosition += dur;
 
@@ -854,10 +892,12 @@ const encodeMeasure = (
 							if (tupletMarks.length > 0) {
 								const origMarks = subEvent.marks;
 								subEvent.marks = [...(subEvent.marks || []), ...tupletMarks];
-								xml += encodeNote(subEvent, voiceNum, currentStaff, level + 1);
+									xml += encodeNote(subEvent, voiceNum, currentStaff, level + 1, false,
+										lyricXmlForNote(lyricCursors, level + 2, subEvent.grace));
 								subEvent.marks = origMarks;
 							} else {
-								xml += encodeNote(subEvent, voiceNum, currentStaff, level + 1);
+									xml += encodeNote(subEvent, voiceNum, currentStaff, level + 1, false,
+										lyricXmlForNote(lyricCursors, level + 2, subEvent.grace));
 							}
 							const dur = calculateDuration(subEvent.duration);
 							voicePosition += dur;

package/source/lilylet/musicXmlTypes.ts

@@ -53,6 +53,15 @@ export interface MusicXmlAttributes {
 
 export type MusicXmlStemDirection = 'up' | 'down';
 
+export type MusicXmlLyricSyllabic = 'single' | 'begin' | 'middle' | 'end';
+
+export interface MusicXmlLyric {
+	number: number;
+	text?: string;
+	syllabic?: MusicXmlLyricSyllabic;
+	extend?: boolean;
+}
+
 export interface MusicXmlNotations {
 	ties?: { type: 'start' | 'stop' }[];
 	slurs?: { type: 'start' | 'stop'; number: number }[];
@@ -81,6 +90,7 @@ export interface MusicXmlNote {
 	notations?: MusicXmlNotations;
 	fingerings?: number[];      // one per chord member; a single note has at most one
 	beams?: { type: 'begin' | 'continue' | 'end'; number: number }[];
+	lyrics?: MusicXmlLyric[];
 }
 
 // ============ Direction Types ============

package/source/lilylet/serializer.ts

@@ -28,6 +28,7 @@ import {
 	StemDirection,
 	Accidental,
 	ArticulationType,
+	LyricLane,
 	OrnamentType,
 	DynamicType,
 	HairpinType,
@@ -928,6 +929,15 @@ const serializeVoice = (
 		parts.push('}');
 	}
 
+	// \addlyrics lanes are scoped to this voice; emit them inside the voice so
+	// they bind to THIS voice's notes (e.g. lyrics under staff 1 serialize
+	// within staff 1's voice, not as a trailing measure-level block).
+	if (voice.lyrics && voice.lyrics.length) {
+		for (const lane of voice.lyrics) {
+			parts.push(serializeLyricLane(lane));
+		}
+	}
+
 	return { str: parts.join(' '), newStaff: voice.staff };
 };
 
@@ -969,6 +979,33 @@ const serializePart = (
 };
 
 
+// Serialize a \addlyrics lane: syllables separated by `--` (hyphen), `_` (skip),
+// `__` (extender). Bare words are emitted unquoted when they contain no
+// reserved characters, otherwise they are quoted and escaped. A syllable may
+// carry text AND a connector: the text is emitted first, then `--`/`__`, so
+// melismas (`text __`) and hyphenation (`text --`) never lose the syllable text.
+const serializeLyricLane = (lane: LyricLane): string => {
+	const out: string[] = [];
+	for (const s of lane.syllables) {
+		if (s.skip) {
+			out.push('_');
+			continue;
+		}
+		const t = s.text ?? '';
+		// An extender with no preceding text is an orphan (e.g. a leading `__`);
+		// emit it alone rather than an empty quoted string.
+		if (!t && s.extend) {
+			out.push('__');
+			continue;
+		}
+		const bare = /^[^ \t\r\n{}"\\]+$/.test(t);
+		out.push(bare ? t : `"${escapeString(t)}"`);
+		if (s.hyphen) out.push('--');
+		if (s.extend) out.push('__');
+	}
+	return `\\addlyrics { ${out.join(' ')} }`;
+};
+
 // Serialize a measure, tracking staff state across parts
 // Always output key/time at start of each measure
 const serializeMeasure = (

package/source/lilylet/types.ts

@@ -214,6 +214,26 @@ export interface Tempo {
 	bpm?: number;
 }
 
+// === Lyrics ===
+
+// A lyric syllable within a lane, aligned by order to a voice's note events
+// (like LilyPond \lyricsto / \addlyrics). `hyphen` means the syllable is joined
+// to the next with a hyphen (LilyPond `--`); `skip` advances past a note with
+// no syllable (LilyPond `_`); `extend` draws an extender line (LilyPond `__`).
+export interface LyricSyllable {
+	text?: string;
+	hyphen?: boolean;
+	skip?: boolean;
+	extend?: boolean;
+}
+
+// A lyrics lane (verse) scoped to a voice. Verse numbers are 1-based and
+// assigned by order of \addlyrics blocks within the voice.
+export interface LyricLane {
+	verse?: number;
+	syllables: LyricSyllable[];
+}
+
 // === Events ===
 
 export interface NoteEvent {
@@ -301,6 +321,10 @@ export type Event = NoteEvent | RestEvent | ContextChange | TremoloEvent | Tuple
 export interface Voice {
 	staff: number;
 	events: Event[];
+	// \addlyrics lanes scoped to this voice. Lyrics align to THIS voice's note
+	// events, so a lane is serialized inside the voice it belongs to (e.g. a
+	// vocal line under staff 1), not as a trailing measure-level block.
+	lyrics?: LyricLane[];
 }
 
 export interface Metadata {