@k-l-lambda/lilylet 0.1.58 → 0.1.60

package/lib/lilylet/lilypondDecoder.js

@@ -451,7 +451,8 @@ const parseLilyDocument = (lilyDocument) => {
                 // Update key/time from context on music events
                 if (term instanceof lilyParser.MusicEvent ||
                     term instanceof lilyParser.LilyTerms.StemDirection ||
-                    term instanceof lilyParser.LilyTerms.OctaveShift) {
+                    term instanceof lilyParser.LilyTerms.OctaveShift ||
+                    term instanceof lilyParser.LilyTerms.Change) {
                     if (context.key && measure.key === null) {
                         measure.key = context.key.key;
                     }
@@ -626,10 +627,21 @@ const parseLilyDocument = (lilyDocument) => {
                         lastOttava = term.value;
                     }
                 }
-                // Handle staff change
+                // Handle staff change (\change Staff = "N")
+                // args[0] is Assignment { key: "Staff", value: { exp: '"N"' } }
                 else if (term instanceof lilyParser.LilyTerms.Change) {
-                    // Ignore \change Staff commands - staff is fixed per track
-                    // (Cross-staff notation is not supported in this decoder)
+                    const assignment = term.args?.[0];
+                    if (assignment?.key === 'Staff') {
+                        // exp is like '"2"' — strip surrounding quotes then parse strictly
+                        const exp = assignment?.value?.exp ?? '';
+                        const raw = exp.replace(/^"|"$/g, '');
+                        // Only accept pure integer staff names (e.g. "1", "2")
+                        // Reject compound names like "1_2", "RH", "LH"
+                        const staffNum = /^\d+$/.test(raw) ? parseInt(raw, 10) : NaN;
+                        if (!isNaN(staffNum)) {
+                            voice.events.push({ type: 'context', staff: staffNum });
+                        }
+                    }
                 }
                 // Handle tempo
                 else if (term instanceof lilyParser.LilyTerms.Tempo) {
@@ -781,6 +793,43 @@ const parseLilyDocument = (lilyDocument) => {
             },
         });
         context.execute(track.music);
+        // Post-process: carry staff state across measure boundaries for this voice.
+        // If measure N ends on staff 2 (via \change Staff), measure N+1 must begin
+        // with context { staff: 2 } so notes at the start of that measure serialize
+        // on the correct staff.
+        {
+            const measureIndices = Array.from(measureMap.keys()).sort((a, b) => a - b);
+            let carryStaff = trackStaff;
+            for (const mi of measureIndices) {
+                const voice = measureMap.get(mi)?.voices[vi];
+                if (!voice)
+                    continue;
+                // Prepend carry-over event if previous measure ended on a different staff,
+                // but skip if the voice's first explicit staff event already resets to
+                // trackStaff — the carry-over would be immediately cancelled (no-op).
+                if (carryStaff !== trackStaff) {
+                    // Suppress carry-over if the first staff event resets to trackStaff
+                    // AND no musical events (notes/rests/etc.) precede it — meaning the
+                    // carry-over would be immediately cancelled with no effect.
+                    const firstStaffCtxIdx = voice.events.findIndex(e => e.type === 'context' && e.staff != null);
+                    const musicalTypes = new Set(['note', 'rest', 'tuplet', 'tremolo']);
+                    const hasMusicBeforeFirstStaff = firstStaffCtxIdx > 0 &&
+                        voice.events.slice(0, firstStaffCtxIdx).some(e => musicalTypes.has(e.type));
+                    const immediatelyCancelled = firstStaffCtxIdx >= 0 &&
+                        voice.events[firstStaffCtxIdx].staff === trackStaff &&
+                        !hasMusicBeforeFirstStaff;
+                    if (!immediatelyCancelled) {
+                        voice.events.unshift({ type: 'context', staff: carryStaff });
+                    }
+                }
+                // Update carryStaff from this measure's events
+                for (const e of voice.events) {
+                    if (e.type === 'context' && e.staff) {
+                        carryStaff = e.staff;
+                    }
+                }
+            }
+        }
     });
     // Filter out empty voices and convert to array, sorted by measure number
     const measures = Array.from(measureMap.entries())

package/lib/lilylet/serializer.js

@@ -439,10 +439,13 @@ const serializeEvent = (event, env, prevDuration) => {
 };
 // Find first clef in voice events
 const findVoiceClef = (voice) => {
+    let activeStaff = voice.staff;
     for (const event of voice.events) {
         if (event.type === 'context') {
             const ctx = event;
-            if (ctx.clef) {
+            if (ctx.staff)
+                activeStaff = ctx.staff;
+            if (ctx.clef && activeStaff === voice.staff) {
                 return ctx.clef;
             }
         }
@@ -460,10 +463,45 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
     let prevDuration;
     // Each voice starts fresh from middle C (step=0, octave=0)
     let pitchEnv = { step: 0, octave: 0 };
+    // Scan leading context-staff events (before the first musical event or clef/ottava)
+    // to compute the effective initial staff. Multiple consecutive staff switches
+    // 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', 'tremolo']);
+    let effectiveInitialStaff = voice.staff;
+    let leadStaffScanEnd = 0;
+    for (let i = 0; i < voice.events.length; i++) {
+        const e = voice.events[i];
+        if (e.type === 'pitchReset') {
+            leadStaffScanEnd = i + 1;
+            continue;
+        }
+        if (e.type === 'context') {
+            const ctx = e;
+            if (ctx.staff != null) {
+                effectiveInitialStaff = ctx.staff;
+                if (!ctx.clef && !ctx.ottava) {
+                    // Pure staff-only event — absorb
+                    leadStaffScanEnd = i + 1;
+                    continue;
+                }
+                // Compound (staff + clef/ottava) — update effectiveInitialStaff but stop scan
+                break;
+            }
+            if (ctx.clef || ctx.ottava)
+                break; // musical context — stop scan
+            leadStaffScanEnd = i + 1; // time/key/stemDir — continue scan
+            continue;
+        }
+        if (MUSICAL_TYPES.has(e.type))
+            break;
+    }
     // Output staff command if voice staff differs from current parser staff,
-    // or always output if it's a grand staff score for clarity
-    if (isGrandStaff || voice.staff !== currentStaff) {
-        parts.push('\\staff "' + voice.staff + '"');
+    // or always output if it's a grand staff score for clarity.
+    // Use effectiveInitialStaff so carry-over replaces the default emission.
+    if (isGrandStaff || effectiveInitialStaff !== currentStaff) {
+        parts.push('\\staff "' + effectiveInitialStaff + '"');
     }
     // Output key/time signatures after \staff (for first voice only)
     if (measureContext && isFirstVoice) {
@@ -495,19 +533,32 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
     }
     // Skip redundant clef context events if this staff's clef is already established
     const clefOutputted = !!voiceClef && !!emittedClefs?.[voice.staff];
-    let activeStaff = voice.staff;
+    let activeStaff = effectiveInitialStaff;
     let activeStemDir;
-    for (const event of voice.events) {
+    for (let eventIdx = 0; eventIdx < voice.events.length; eventIdx++) {
+        const event = voice.events[eventIdx];
+        // Skip leading context-staff events already absorbed into effectiveInitialStaff
+        if (eventIdx < leadStaffScanEnd && event.type === 'context' && event.staff != null) {
+            continue;
+        }
         if (event.type === 'context') {
             const ctx = event;
             // Cross-staff context: update activeStaff and emit \staff directive
             if (ctx.staff && ctx.staff !== activeStaff) {
                 activeStaff = ctx.staff;
                 parts.push('\\staff "' + activeStaff + '"');
+                // Emit target staff clef if the event carries one or allStaffClefs knows it
+                const ctxClef = ctx.clef || allStaffClefs?.[activeStaff];
+                if (ctxClef && emittedClefs?.[activeStaff] !== ctxClef) {
+                    parts.push('\\clef "' + CLEF_MAP[ctxClef] + '"');
+                    if (emittedClefs)
+                        emittedClefs[activeStaff] = ctxClef;
+                }
                 continue;
             }
-            if (ctx.staff)
-                continue; // same staff, no-op
+            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) {
                 continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.58",
+  "version": "0.1.60",
   "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",

package/source/lilylet/lilypondDecoder.ts

@@ -556,7 +556,8 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 				// Update key/time from context on music events
 				if (term instanceof lilyParser.MusicEvent ||
 					term instanceof lilyParser.LilyTerms.StemDirection ||
-					term instanceof lilyParser.LilyTerms.OctaveShift) {
+					term instanceof lilyParser.LilyTerms.OctaveShift ||
+					term instanceof lilyParser.LilyTerms.Change) {
 
 					if (context.key && measure.key === null) {
 						measure.key = context.key.key;
@@ -750,10 +751,21 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 						lastOttava = term.value;
 					}
 				}
-				// Handle staff change
+				// Handle staff change (\change Staff = "N")
+				// args[0] is Assignment { key: "Staff", value: { exp: '"N"' } }
 				else if (term instanceof lilyParser.LilyTerms.Change) {
-					// Ignore \change Staff commands - staff is fixed per track
-					// (Cross-staff notation is not supported in this decoder)
+					const assignment = (term as any).args?.[0];
+					if (assignment?.key === 'Staff') {
+						// exp is like '"2"' — strip surrounding quotes then parse strictly
+						const exp: string = assignment?.value?.exp ?? '';
+						const raw = exp.replace(/^"|"$/g, '');
+						// Only accept pure integer staff names (e.g. "1", "2")
+						// Reject compound names like "1_2", "RH", "LH"
+						const staffNum = /^\d+$/.test(raw) ? parseInt(raw, 10) : NaN;
+						if (!isNaN(staffNum)) {
+							voice.events.push({ type: 'context', staff: staffNum } as any);
+						}
+					}
 				}
 				// Handle tempo
 				else if (term instanceof lilyParser.LilyTerms.Tempo) {
@@ -912,6 +924,47 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 		});
 
 		context.execute(track.music);
+
+		// Post-process: carry staff state across measure boundaries for this voice.
+		// If measure N ends on staff 2 (via \change Staff), measure N+1 must begin
+		// with context { staff: 2 } so notes at the start of that measure serialize
+		// on the correct staff.
+		{
+			const measureIndices = Array.from(measureMap.keys()).sort((a, b) => a - b);
+			let carryStaff = trackStaff;
+			for (const mi of measureIndices) {
+				const voice = measureMap.get(mi)?.voices[vi];
+				if (!voice) continue;
+
+				// Prepend carry-over event if previous measure ended on a different staff,
+				// but skip if the voice's first explicit staff event already resets to
+				// trackStaff — the carry-over would be immediately cancelled (no-op).
+				if (carryStaff !== trackStaff) {
+					// Suppress carry-over if the first staff event resets to trackStaff
+					// AND no musical events (notes/rests/etc.) precede it — meaning the
+					// carry-over would be immediately cancelled with no effect.
+					const firstStaffCtxIdx = voice.events.findIndex(
+						e => e.type === 'context' && (e as any).staff != null
+					);
+					const musicalTypes = new Set(['note', 'rest', 'tuplet', 'tremolo']);
+					const hasMusicBeforeFirstStaff = firstStaffCtxIdx > 0 &&
+						voice.events.slice(0, firstStaffCtxIdx).some(e => musicalTypes.has(e.type));
+					const immediatelyCancelled = firstStaffCtxIdx >= 0 &&
+						(voice.events[firstStaffCtxIdx] as any).staff === trackStaff &&
+						!hasMusicBeforeFirstStaff;
+					if (!immediatelyCancelled) {
+						voice.events.unshift({ type: 'context', staff: carryStaff } as any);
+					}
+				}
+
+				// Update carryStaff from this measure's events
+				for (const e of voice.events) {
+					if (e.type === 'context' && (e as any).staff) {
+						carryStaff = (e as any).staff;
+					}
+				}
+			}
+		}
 	});
 
 	// Filter out empty voices and convert to array, sorted by measure number

package/source/lilylet/serializer.ts

@@ -574,10 +574,12 @@ interface MeasureContext {
 
 // Find first clef in voice events
 const findVoiceClef = (voice: Voice): Clef | undefined => {
+	let activeStaff = voice.staff;
 	for (const event of voice.events) {
 		if (event.type === 'context') {
 			const ctx = event as ContextChange;
-			if (ctx.clef) {
+			if (ctx.staff) activeStaff = ctx.staff;
+			if (ctx.clef && activeStaff === voice.staff) {
 				return ctx.clef;
 			}
 		}
@@ -605,10 +607,41 @@ const serializeVoice = (
 	// Each voice starts fresh from middle C (step=0, octave=0)
 	let pitchEnv: PitchEnv = { step: 0, octave: 0 };
 
+	// Scan leading context-staff events (before the first musical event or clef/ottava)
+	// to compute the effective initial staff. Multiple consecutive staff switches
+	// 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', 'tremolo']);
+	let effectiveInitialStaff = voice.staff;
+	let leadStaffScanEnd = 0;
+	for (let i = 0; i < voice.events.length; i++) {
+		const e = voice.events[i];
+		if (e.type === 'pitchReset') { leadStaffScanEnd = i + 1; continue; }
+		if (e.type === 'context') {
+			const ctx = e as ContextChange;
+			if (ctx.staff != null) {
+				effectiveInitialStaff = ctx.staff;
+				if (!ctx.clef && !ctx.ottava) {
+					// Pure staff-only event — absorb
+					leadStaffScanEnd = i + 1;
+					continue;
+				}
+				// Compound (staff + clef/ottava) — update effectiveInitialStaff but stop scan
+				break;
+			}
+			if (ctx.clef || ctx.ottava) break; // musical context — stop scan
+			leadStaffScanEnd = i + 1; // time/key/stemDir — continue scan
+			continue;
+		}
+		if (MUSICAL_TYPES.has(e.type)) break;
+	}
+
 	// Output staff command if voice staff differs from current parser staff,
-	// or always output if it's a grand staff score for clarity
-	if (isGrandStaff || voice.staff !== currentStaff) {
-		parts.push('\\staff "' + voice.staff + '"');
+	// or always output if it's a grand staff score for clarity.
+	// Use effectiveInitialStaff so carry-over replaces the default emission.
+	if (isGrandStaff || effectiveInitialStaff !== currentStaff) {
+		parts.push('\\staff "' + effectiveInitialStaff + '"');
 	}
 
 	// Output key/time signatures after \staff (for first voice only)
@@ -642,19 +675,31 @@ const serializeVoice = (
 	// Skip redundant clef context events if this staff's clef is already established
 	const clefOutputted = !!voiceClef && !!emittedClefs?.[voice.staff];
 
-	let activeStaff = voice.staff;
+	let activeStaff = effectiveInitialStaff;
 	let activeStemDir: StemDirection | undefined;
 
-	for (const event of voice.events) {
+	for (let eventIdx = 0; eventIdx < voice.events.length; eventIdx++) {
+		const event = voice.events[eventIdx];
+		// Skip leading context-staff events already absorbed into effectiveInitialStaff
+		if (eventIdx < leadStaffScanEnd && event.type === 'context' && (event as ContextChange).staff != null) {
+			continue;
+		}
 		if (event.type === 'context') {
 			const ctx = event as ContextChange;
 			// Cross-staff context: update activeStaff and emit \staff directive
 			if (ctx.staff && ctx.staff !== activeStaff) {
 				activeStaff = ctx.staff;
 				parts.push('\\staff "' + activeStaff + '"');
+				// Emit target staff clef if the event carries one or allStaffClefs knows it
+				const ctxClef = ctx.clef || allStaffClefs?.[activeStaff];
+				if (ctxClef && emittedClefs?.[activeStaff] !== ctxClef) {
+					parts.push('\\clef "' + CLEF_MAP[ctxClef] + '"');
+					if (emittedClefs) emittedClefs[activeStaff] = ctxClef;
+				}
 				continue;
 			}
-			if (ctx.staff) continue;  // same staff, no-op
+			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) {
 				continue;