@k-l-lambda/lilylet 0.1.67 → 0.1.69

package/lib/lilylet/meiEncoder.js

@@ -538,7 +538,8 @@ const noteEventToMEI = (event, indent, layerStaff, tieEnd, contextStemDir, keyFi
 // Convert RestEvent to MEI
 const restEventToMEI = (event, indent, keyFifths = 0, ottavaShift = 0, measureAccidentals, crossStaff) => {
     const dur = DURATIONS[event.duration.division] || "4";
-    let attrs = `xml:id="${generateId('rest')}" dur="${dur}"`;
+    const restId = generateId('rest');
+    let attrs = `xml:id="${restId}" dur="${dur}"`;
     if (event.duration.dots > 0)
         attrs += ` dots="${event.duration.dots}"`;
     // Cross-staff attribute
@@ -551,13 +552,14 @@ const restEventToMEI = (event, indent, keyFifths = 0, ottavaShift = 0, measureAc
     }
     // Space rest (invisible)
     if (event.invisible) {
-        return `${indent}<space ${attrs} />\n`;
+        return { xml: `${indent}<space ${attrs} />\n`, elementId: restId };
     }
     // Full measure rest
     if (event.fullMeasure) {
-        return `${indent}<mRest xml:id="${generateId('mrest')}" />\n`;
+        const mRestId = generateId('mrest');
+        return { xml: `${indent}<mRest xml:id="${mRestId}" />\n`, elementId: mRestId };
     }
-    return `${indent}<rest ${attrs} />\n`;
+    return { xml: `${indent}<rest ${attrs} />\n`, elementId: restId };
 };
 // Check if a tuplet has balanced internal beam groups (both [ and ] inside the same tuplet)
 // Returns false for cross-tuplet beams where [ is in one tuplet and ] in another
@@ -645,7 +647,7 @@ const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff
         }
         else if (e.type === 'rest') {
             const restIndent = beamOpen ? baseIndent + '    ' : baseIndent;
-            xml += restEventToMEI(e, restIndent, keyFifths, ottavaShift, measureAccidentals);
+            xml += restEventToMEI(e, restIndent, keyFifths, ottavaShift, measureAccidentals).xml;
         }
         else if (e.type === 'context') {
             const ctx = e;
@@ -809,6 +811,7 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
     const barlines = [];
     const markups = [];
     const pendingMarkups = [];
+    const pendingDynamics = [];
     // Track current stem direction from context changes
     let currentStemDirection = undefined;
     // Track current staff for cross-staff notation
@@ -824,6 +827,13 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
         }
         pendingMarkups.length = 0;
     };
+    // Helper to flush pending leading dynamics onto a note ID
+    const flushPendingDynamics = (noteId) => {
+        for (const label of pendingDynamics) {
+            dynamics.push({ startid: noteId, label });
+        }
+        pendingDynamics.length = 0;
+    };
     // Helper to check if pitches match for tie continuation
     const pitchesMatch = (p1, p2) => {
         if (p1.length !== p2.length)
@@ -884,6 +894,8 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 }
                 // Flush any pending markups onto this note
                 flushPendingMarkups(result.elementId);
+                // Flush any pending leading dynamics onto this note
+                flushPendingDynamics(result.elementId);
                 // If there's a pending ottava, start the span on this note
                 if (pendingOttava !== null && pendingOttava !== 0) {
                     const dis = Math.abs(pendingOttava) === 2 ? 15 : 8;
@@ -996,7 +1008,12 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
             case 'rest': {
                 // For cross-staff notation: pass staff number if different from voice's home staff
                 const restCrossStaff = currentStaff !== (voice.staff || 1) ? currentStaff : undefined;
-                xml += restEventToMEI(event, currentIndent, keyFifths, currentOttavaShift, measureAccidentals, restCrossStaff);
+                const restResult = restEventToMEI(event, currentIndent, keyFifths, currentOttavaShift, measureAccidentals, restCrossStaff);
+                xml += restResult.xml;
+                // A leading dynamic/markup attaches to the next event, which may be this rest
+                flushPendingMarkups(restResult.elementId);
+                flushPendingDynamics(restResult.elementId);
+                lastNoteId = restResult.elementId;
                 break;
             }
             case 'tuplet':
@@ -1012,6 +1029,7 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 // Flush any pending markups onto the first note of the tuplet
                 if (tupletResult.firstNoteId) {
                     flushPendingMarkups(tupletResult.firstNoteId);
+                    flushPendingDynamics(tupletResult.firstNoteId);
                     lastNoteId = tupletResult.firstNoteId;
                 }
                 // Process slur ends first (to close any pending slurs from before this tuplet)
@@ -1127,6 +1145,13 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                     }
                 }
                 break;
+            case 'dynamic':
+                {
+                    // Standalone (leading) dynamic - attaches to the following note
+                    const dynEvent = event;
+                    pendingDynamics.push(dynEvent.dynamicType);
+                }
+                break;
         }
         // Close beam element if beam ends
         if (beamEnd) {

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':
@@ -455,12 +456,25 @@ const serializeEvent = (event, env, prevDuration) => {
             return serializeTremoloEvent(event, env);
         case 'barline':
             return { str: serializeBarlineEvent(event), newEnv: env };
+        case 'markup': {
+            const mk = event;
+            const prefix = mk.placement === 'above' ? '^' : mk.placement === 'below' ? '_' : '';
+            return { str: `${prefix}\\markup "${mk.content}"`, newEnv: env };
+        }
+        case 'dynamic': {
+            const dynStr = DYNAMIC_MAP[event.dynamicType];
+            return { str: dynStr || '', newEnv: env };
+        }
         default:
             return { str: '', newEnv: env };
     }
 };
-// Find first clef in voice events
+// Find the voice's leading clef: the clef in effect at the START of the voice, i.e.
+// a clef context event that appears before any musical event on the home staff.
+// A clef that first appears AFTER a note is a mid-voice change and must be emitted
+// inline where it occurs, not hoisted to the front — so it is not returned here.
 const findVoiceClef = (voice) => {
+    const MUSICAL = new Set(['note', 'rest', 'tuplet', 'times', 'tremolo']);
     let activeStaff = voice.staff;
     for (const event of voice.events) {
         if (event.type === 'context') {
@@ -471,6 +485,11 @@ const findVoiceClef = (voice) => {
                 return ctx.clef;
             }
         }
+        else if (MUSICAL.has(event.type)) {
+            // Reached music on the home staff before any clef — no leading clef.
+            if (activeStaff === voice.staff)
+                return undefined;
+        }
     }
     return undefined;
 };
@@ -490,7 +509,6 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
     // before any music collapse to the last one (earlier ones are no-ops).
     // leadStaffScanEnd is the index of the first event that ends this scan —
     // context{staff} events before this index are skipped in the main loop.
-    const MUSICAL_TYPES = new Set(['note', 'rest', 'tuplet', 'times', 'tremolo']);
     let effectiveInitialStaff = voice.staff;
     let leadStaffScanEnd = 0;
     for (let i = 0; i < voice.events.length; i++) {
@@ -516,8 +534,9 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
             leadStaffScanEnd = i + 1; // time/key/stemDir — continue scan
             continue;
         }
-        if (MUSICAL_TYPES.has(e.type))
-            break;
+        // Any other event (note/rest/tuplet/markup/dynamic/harmony/barline/…) has a
+        // visible position; a staff switch after it must not be hoisted ahead of it.
+        break;
     }
     // Output staff command if voice staff differs from current parser staff,
     // or always output if it's a grand staff score for clarity.
@@ -545,18 +564,20 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
             parts.push('\\time ' + numerator + '/' + denominator);
         }
     }
-    // Output clef only if not yet emitted or changed for this staff
-    const voiceClef = allStaffClefs?.[voice.staff] || findVoiceClef(voice);
+    // Output clef only if not yet emitted or changed for this staff.
+    // Prefer this voice's leading clef (a clef before any music); fall back to the
+    // carry-in clef from previous measures. A clef that first appears mid-voice is NOT
+    // hoisted here — it is emitted inline at its position.
+    const voiceClef = findVoiceClef(voice) ?? allStaffClefs?.[voice.staff];
     const clefAlreadyEmitted = voiceClef && emittedClefs?.[voice.staff] === voiceClef;
     if (voiceClef && !clefAlreadyEmitted) {
         parts.push('\\clef "' + (CLEF_MAP[voiceClef] ?? voiceClef) + '"');
         if (emittedClefs)
             emittedClefs[voice.staff] = voiceClef;
     }
-    // Skip redundant clef context events if this staff's clef is already established
-    const clefOutputted = !!voiceClef && !!emittedClefs?.[voice.staff];
     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
@@ -581,8 +602,11 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
             if (ctx.staff && !ctx.clef && !ctx.ottava)
                 continue; // same staff, pure no-op
             if (ctx.staff) { /* same staff but has clef/ottava — fall through to emit them */ }
-            // Skip clef-only context events if clef already established for this staff
-            if (clefOutputted && ctx.clef && !ctx.key && !ctx.time && !ctx.ottava && !ctx.stemDirection && !ctx.tempo) {
+            // Skip a clef-only context event only if it is REDUNDANT — i.e. it restates the
+            // clef already active for this staff. A clef that differs is a genuine change and
+            // must be emitted inline at its position.
+            if (ctx.clef && !ctx.key && !ctx.time && !ctx.ottava && !ctx.stemDirection && !ctx.tempo &&
+                emittedClefs?.[ctx.staff || activeStaff] === ctx.clef) {
                 continue;
             }
         }
@@ -617,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);
@@ -641,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
@@ -775,25 +814,31 @@ export const serializeLilyletDoc = (doc) => {
         if (measure.timeSig) {
             currentTime = measure.timeSig;
         }
-        // Collect clefs from this measure's voices, per part
-        measure.parts.forEach((part, pi) => {
-            const staffClefs = partStaffClefs[pi] || (partStaffClefs[pi] = {});
-            for (const voice of part.voices) {
-                let clefActiveStaff = voice.staff;
-                for (const event of voice.events) {
-                    if (event.type === 'context') {
-                        const ctx = event;
-                        if (ctx.staff) {
-                            clefActiveStaff = ctx.staff;
-                        }
-                        if (ctx.clef) {
-                            staffClefs[clefActiveStaff] = ctx.clef;
+        // Collect clefs from this measure's voices, per part — but only AFTER serializing
+        // the measure, so that during serialization allStaffClefs reflects the clef state
+        // CARRIED IN from previous measures (a mid-measure clef change must not be hoisted
+        // to the measure's front; it is emitted inline at its position).
+        const collectClefs = () => {
+            measure.parts.forEach((part, pi) => {
+                const staffClefs = partStaffClefs[pi] || (partStaffClefs[pi] = {});
+                for (const voice of part.voices) {
+                    let clefActiveStaff = voice.staff;
+                    for (const event of voice.events) {
+                        if (event.type === 'context') {
+                            const ctx = event;
+                            if (ctx.staff) {
+                                clefActiveStaff = ctx.staff;
+                            }
+                            if (ctx.clef) {
+                                staffClefs[clefActiveStaff] = ctx.clef;
+                            }
                         }
                     }
                 }
-            }
-        });
+            });
+        };
         const { str: measureStr, newStaff } = serializeMeasure(measure, i === 0, currentStaff, isGrandStaff, currentKey, currentTime, partStaffClefs, partEmittedClefs);
+        collectClefs();
         // Always include measure, even if empty (use space rest for empty measures)
         measureStrs.push(measureStr || 's1');
         currentStaff = newStaff;

package/lib/lilylet/types.d.ts

@@ -221,7 +221,11 @@ export interface MarkupEvent {
     content: string;
     placement?: Placement;
 }
-export type Event = NoteEvent | RestEvent | ContextChange | TremoloEvent | TupletEvent | TimesEvent | PitchResetEvent | BarlineEvent | HarmonyEvent | MarkupEvent;
+export interface DynamicEvent {
+    type: 'dynamic';
+    dynamicType: DynamicType;
+}
+export type Event = NoteEvent | RestEvent | ContextChange | TremoloEvent | TupletEvent | TimesEvent | PitchResetEvent | BarlineEvent | HarmonyEvent | MarkupEvent | DynamicEvent;
 export interface Voice {
     staff: number;
     events: Event[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.67",
+  "version": "0.1.69",
   "description": "Lilylet is a lilyopnd-like sheet music language designed for Markdown rendering and symbolic music representation in AIGC applications.",
   "type": "module",
   "main": "lib/index.js",
@@ -30,7 +30,6 @@
     "test": "tsx ./tests/parser.ts",
     "test:mei": "tsx ./tests/mei.ts",
     "test:mei-hashes": "tsx ./tests/computeMeiHashes.ts",
-    "test:unit": "tsx ./tests/unit/encodePitch.test.ts",
     "test:partial": "tsx ./tests/unit/partialWarning.test.ts",
     "test:decoder": "tsx ./tests/lilypondDecoder.ts",
     "test:abc": "tsx ./tests/abc-decoder.ts",

package/source/abc/abc.jison

@@ -37,14 +37,14 @@
 
 	const patch = (terms, bar) => {
 		const control = {};
-		terms.forEach(term => {
+		(terms || []).forEach(term => {
 			if (term.control)
 				control[term.control.name] = term.control.value;
 		});
 
 		return {
 			control,
-			terms,
+			terms: terms || [],
 			bar,
 		};
 	};
@@ -195,10 +195,10 @@ Am									\b[A-G](?=[m][a][j]|[m][i][n]\b)
 a									\b[a-g](?=[\W\d\sA-Ga-g_yzHJLMOPRSTuv]*\b)
 z									\b[z]
 Z									\b[Z]
-x									\b[x](?=[\W\d\s])
+x									\b[x](?=[\W\d\s]|[_^=]*[A-Ga-g])
 y									\b[y]
 N									[0-9]
-P									\b[HJLMOPRSTuv](?=[A-Ga-g][A-Ga-g0-9]*\b)
+P									\b[HJLMOPRSTuv](?=[_^=]*[A-Ga-g][A-Ga-g0-9_^=,']*)
 PP									\b[HJLMOPRSTuv](?=[xz!\[^_=\s"])
 
 SPECIAL								[:!^_,'/<>={}()\[\]|.\-+~&]
@@ -211,8 +211,8 @@ SPECIAL								[:!^_,'/<>={}()\[\]|.\-+~&]
 <string>\\\"						return 'STR_CONTENT'
 <string>[^"]+						return 'STR_CONTENT'
 
-^[T][:][\s]*						{ this.pushState('title_string'); return 'T:'; }
-^[C][:][\s]*						{ this.pushState('title_string'); return 'C:'; }
+^[T][:][\s]*						{ var pre = this.matched.slice(0, this.matched.length - yytext.length); if (pre === '' || pre.slice(-1) === '\n') { this.pushState('title_string'); return 'T:'; } this.unput(yytext.slice(1)); yytext = 'T'; return 'T'; }
+^[C][:][\s]*						{ var pre = this.matched.slice(0, this.matched.length - yytext.length); if (pre === '' || pre.slice(-1) === '\n') { this.pushState('title_string'); return 'C:'; } this.unput(yytext.slice(1)); yytext = 'C'; return 'A'; }
 <title_string>\n					{ this.popState(); }
 <title_string>[^\n]+				return 'STR_CONTENT'
 
@@ -226,10 +226,10 @@ SPECIAL								[:!^_,'/<>={}()\[\]|.\-+~&]
 <voice_header>[ \t]+				{}
 <voice_header>\n					{ this.popState(); }
 <voice_header>\]					{ this.popState(); return ']'; }
-<key_signature>"treble"				return 'TREBLE';
-<key_signature>"bass"				return 'BASS';
-<key_signature>"tenor"				return 'TENOR';
-<key_signature>"alto"				return 'ALTO';
+<key_signature>"treble"[0-9]*		return 'TREBLE';
+<key_signature>"bass"[0-9]*			return 'BASS';
+<key_signature>"tenor"[0-9]*		return 'TENOR';
+<key_signature>"alto"[0-9]*			return 'ALTO';
 <key_signature>"none"				return 'NAME';
 <key_signature>"Dor"				return 'NAME';
 <key_signature>"Phr"				return 'NAME';
@@ -239,7 +239,7 @@ SPECIAL								[:!^_,'/<>={}()\[\]|.\-+~&]
 <key_signature>"Loc"				return 'NAME';
 <key_signature>"HP"					return 'NAME';
 <key_signature>"Hp"					return 'NAME';
-<key_signature>[a-z]+[ \t]*=[^\n\]]*	{}
+<key_signature>[a-z]+[ \t]*[=][^\n\]]*	{}
 <key_signature>[A-G]				return 'A';
 <key_signature>[A-Z][a-z]+			return 'NAME';
 <key_signature>[b]					return 'FLAT';
@@ -262,9 +262,10 @@ SPECIAL								[:!^_,'/<>={}()\[\]|.\-+~&]
 <spec_comment_name>[\w]+			{ this.popState(); this.pushState('spec_comment_skip'); }
 <spec_comment_name>\n				{ this.popState(); this.popState(); }
 <spec_comment>[ \t]+				{}
-<spec_comment>[([{]				{ this._scoreDepth = (this._scoreDepth || 0) + 1; return yytext; }
+<spec_comment>[([{]					{ this._scoreDepth = (this._scoreDepth || 0) + 1; return yytext; }
 <spec_comment>[)\]}]				{ this._scoreDepth = (this._scoreDepth || 0) - 1; return yytext; }
 <spec_comment>[|]					return yytext
+<spec_comment>[A-Z][:]				{ this.popState(); this.popState(); this.unput(yytext); return 'LAYOUT_END'; }
 <spec_comment>[\w]+					return 'NN'
 <spec_comment>\n					{ if (this._scoreDepth > 0) { /* layout continues on next line */ } else { this.popState(); this.popState(); return 'LAYOUT_END'; } }
 <spec_comment_skip>[^\n]+			{}
@@ -467,6 +468,7 @@ numeric_tempo
 
 voice_exp
 	: number							-> voice($1)
+	| number assigns					-> voice($1, null, $2)
 	| number NAME						-> voice($1, $2)
 	| number NAME assigns				-> voice($1, $2, $3)
 	| number NAME plus_minus_number		-> voice($1, $2 + ($3 < 0 ? '-' : '+') + Math.abs($3))
@@ -539,10 +541,18 @@ bar
 	| '|' ']' ':'						-> '|]'
 	| ':' '|' ']'						-> ':|]'
 	| '|' N								-> '|' + $2
+	| '|' N volta_rest					-> '|' + $2 + $3
 	| ':' '|' N							-> ':|' + $2
+	| ':' '|' N volta_rest				-> ':|' + $2 + $3
 	| '&'								-> '&'
 	;
 
+// Additional volta endings after the first number, comma-separated: "1,2", "1,2,3".
+volta_rest
+	: ',' N								-> ',' + $2
+	| volta_rest ',' N					-> $1 + ',' + $3
+	;
+
 music
 	: %empty							-> []
 	| music expressive_mark				-> $1 ? [...$1, $2] : [$2]
@@ -555,10 +565,17 @@ music
 	| music N							-> $1
 	| music NAME						-> $1
 	| music '^' NAME					-> $1
-	| music '^'							-> $1
+	| music '^' articulation_letter		-> $1
 	| music '[' N						-> $1
 	;
 
+// Articulation-class letters (P macro: HJLMOPRSTuv). After a stray '^' inside a
+// text annotation, a word like "Menuetto"/"Largo" starts with one of these and the
+// lexer emits it as the articulation token, not NAME — swallow it like '^' NAME.
+articulation_letter
+	: 'P' | 'T' | 'H' | 'J' | 'L' | 'M' | 'R' | 'O' | 'S' | 'u' | 'v'
+	;
+
 control
 	: '[' H ':' header_value ']'		-> ({control: header($2, $4)})
 	| '[' 'K:' header_value ']'			-> ({control: header("K", $3)})
@@ -757,7 +774,14 @@ duration
 	: number '/' number					-> frac(Number($1), Number($3))
 	| '/' number						-> frac(1, Number($2))
 	| number							-> frac(Number($1))
-	| '/'								-> frac(1, 2)
+	| slashes							-> frac(1, Math.pow(2, $1))
+	| number slashes					-> frac(Number($1), Math.pow(2, $2))
+	;
+
+// One or more '/' halve the unit length each: '/'=1/2, '//'=1/4, '///'=1/8.
+slashes
+	: '/'								-> 1
+	| slashes '/'						-> $1 + 1
 	;
 
 broken_rhythm