@k-l-lambda/lilylet 0.1.59 → 0.1.62

package/lib/lilylet/lilypondDecoder.js

@@ -391,6 +391,42 @@ const parseLilyDocument = (lilyDocument) => {
     const measureMap = new Map();
     const staffNames = [];
     const interpreter = lilyDocument.interpret();
+    // Pre-compute partIndex for each track using staff-number-sequence heuristic.
+    // When staff numbers reset (decrease), a new part starts — this handles multi-PianoStaff
+    // scores where both pianos reuse the same staff names ("1" and "2").
+    // Scores that embed partIndex in the staff name ("1_1", "1_2", "2_1") are handled
+    // by parseStaffName; this heuristic only kicks in for plain numeric names.
+    let _seqPart = 1;
+    let _seqMaxStaff = 0;
+    const _trackPartIndices = interpreter.layoutMusic.musicTracks.map((track) => {
+        const staffName = track.contextDict?.Staff;
+        if (staffName && /^\d+_\d+$/.test(staffName)) {
+            // Staff name encodes partIndex explicitly — don't apply heuristic
+            return parseInt(staffName.split('_')[0], 10);
+        }
+        // PianoStaff is present (even as empty string "") when inside a grand-staff group;
+        // undefined means standalone instrument → different part from grand-staff tracks.
+        const hasPianoStaff = (track.contextDict?.PianoStaff !== undefined);
+        const staffNum = parseInt(staffName || '1', 10) || 1;
+        if (hasPianoStaff) {
+            // Grand-staff: new part if transitioning from standalone or staff resets
+            if (_seqMaxStaff > 0 && staffNum < _seqMaxStaff) {
+                _seqPart++;
+                _seqMaxStaff = 0;
+            }
+            else if (_seqMaxStaff === -1) {
+                // Transitioning from a standalone group
+                _seqPart++;
+                _seqMaxStaff = 0;
+            }
+            _seqMaxStaff = Math.max(_seqMaxStaff, staffNum);
+        }
+        else {
+            // Standalone: mark with -1 so next grand-staff group increments
+            _seqMaxStaff = -1;
+        }
+        return _seqPart;
+    });
     interpreter.layoutMusic.musicTracks.forEach((track, vi) => {
         const appendStaff = (staffName) => {
             if (!staffNames.includes(staffName)) {
@@ -399,15 +435,20 @@ const parseLilyDocument = (lilyDocument) => {
         };
         // Parse staff name to extract partIndex and staff number
         // Format: "partIndex_staffIndex" (e.g., "1_1", "1_2", "2_1")
-        // Falls back to partIndex=1 if format doesn't match
+        // Falls back to positional ordering for non-numeric names (e.g., "upper"→1, "lower"→2)
         const parseStaffName = (name) => {
             const match = name.match(/^(\d+)_(\d+)$/);
             if (match) {
                 return { partIndex: parseInt(match[1], 10), staffNum: parseInt(match[2], 10) };
             }
-            // Fallback: single part, staff number from name or 1
             const num = parseInt(name, 10);
-            return { partIndex: 1, staffNum: isNaN(num) ? 1 : num };
+            if (!isNaN(num)) {
+                return { partIndex: 1, staffNum: num };
+            }
+            // Non-numeric name: assign staffNum by order of first appearance in staffNames
+            appendStaff(name);
+            const idx = staffNames.indexOf(name);
+            return { partIndex: 1, staffNum: idx + 1 };
         };
         // Use track.contextDict.Staff as the authoritative staff name (from Staff definition)
         // This won't be affected by \change Staff commands inside the track
@@ -415,16 +456,21 @@ const parseLilyDocument = (lilyDocument) => {
         if (initialStaffName) {
             appendStaff(initialStaffName);
         }
-        const parsedStaff = initialStaffName ? parseStaffName(initialStaffName) : { partIndex: 1, staffNum: 1 };
+        // Empty string staff name ("") means unnamed staff — treat as staff 1 within its part
+        const parsedStaff = (initialStaffName != null && initialStaffName !== '')
+            ? parseStaffName(initialStaffName)
+            : { partIndex: 1, staffNum: 1 };
         // Use these as fixed values for this track - don't update from context.staffName
         const trackStaff = parsedStaff.staffNum;
-        const trackPartIndex = parsedStaff.partIndex;
+        // Use sequence-based partIndex (detects multi-PianoStaff via staff number reset)
+        const trackPartIndex = _trackPartIndices[vi] ?? parsedStaff.partIndex;
         // Track emitted context events across measures for this voice
         let lastKey = undefined; // Track value changes (key fifths)
         let lastTimeSig = undefined; // Track value changes (as string for comparison)
         let lastClef = undefined; // Track value changes
         let lastOttava = undefined; // Track value changes
         let lastStemDirection = undefined; // Track value changes
+        let partialEmitted = false; // Emit \partial context once per track
         const context = new lilyParser.TrackContext(undefined, {
             listener: (term, context) => {
                 const mi = term._measure;
@@ -448,11 +494,12 @@ const parseLilyDocument = (lilyDocument) => {
                     };
                 }
                 const voice = measure.voices[vi];
-                // Update key/time from context on music events
+                // Update key/time/partial from context on music events
                 if (term instanceof lilyParser.MusicEvent ||
                     term instanceof lilyParser.LilyTerms.StemDirection ||
                     term instanceof lilyParser.LilyTerms.OctaveShift ||
-                    term instanceof lilyParser.LilyTerms.Change) {
+                    term instanceof lilyParser.LilyTerms.Change ||
+                    term instanceof lilyParser.LilyTerms.Partial) {
                     if (context.key && measure.key === null) {
                         measure.key = context.key.key;
                     }
@@ -466,6 +513,32 @@ const parseLilyDocument = (lilyDocument) => {
                         measure.partial = true;
                     }
                 }
+                // Emit \partial context event when the Partial term fires (before partialDuration is cleared)
+                if (term instanceof lilyParser.LilyTerms.Partial && context.partialDuration && !partialEmitted) {
+                    const mag = context.partialDuration.magnitude;
+                    const WHOLE = 1920;
+                    let division = 1, dots = 0;
+                    for (const div of [1, 2, 4, 8, 16, 32, 64]) {
+                        const base = WHOLE / div;
+                        if (Math.abs(mag - base) < 1) {
+                            division = div;
+                            dots = 0;
+                            break;
+                        }
+                        if (Math.abs(mag - Math.round(base * 1.5)) < 1) {
+                            division = div;
+                            dots = 1;
+                            break;
+                        }
+                        if (Math.abs(mag - Math.round(base * 1.75)) < 1) {
+                            division = div;
+                            dots = 2;
+                            break;
+                        }
+                    }
+                    voice.events.push({ type: 'context', partial: { division, dots } });
+                    partialEmitted = true;
+                }
                 // Handle music events
                 if (term instanceof lilyParser.MusicEvent) {
                     // Staff is fixed per track (from track definition)
@@ -583,13 +656,17 @@ const parseLilyDocument = (lilyDocument) => {
                     }
                     // Process Rest
                     else if (term instanceof lilyParser.LilyTerms.Rest) {
-                        const restEvent = {
-                            type: 'rest',
-                            duration: convertDuration(term.durationValue),
-                            fullMeasure: (term.name === 'R') || undefined,
-                            invisible: term.isSpacer || undefined,
-                        };
-                        voice.events.push(restEvent);
+                        // Ignore spacer rests inside grace contexts (e.g. \acciaccatura s8,
+                        // \grace s4 — these are notation-only placeholders with no musical content)
+                        if (!(term.isSpacer && context.inGrace)) {
+                            const restEvent = {
+                                type: 'rest',
+                                duration: convertDuration(term.durationValue),
+                                fullMeasure: (term.name === 'R') || undefined,
+                                invisible: term.isSpacer || undefined,
+                            };
+                            voice.events.push(restEvent);
+                        }
                     }
                 }
                 // Handle standalone stem direction (emit when value changes)
@@ -712,41 +789,80 @@ const parseLilyDocument = (lilyDocument) => {
                     // Handle tuplet
                     // Note: Lotus emits Chord events BEFORE the Tuplet term, so we need to
                     // remove the already-added notes and wrap them in a TupletEvent
-                    else if (termAny.proto === 'Tuplet') {
-                        const ratioStr = termAny.args?.[0]; // e.g., "3/2"
-                        const body = termAny.args?.[1]?.body || [];
+                    else if (termAny.proto === 'Tuplet' || termAny.proto === 'Times') {
+                        const isTimes = termAny.proto === 'Times';
+                        const ratioStr = termAny.args?.[0]; // "3/2" for \tuplet, "2/3" for \times
+                        // \tuplet supports an optional base-duration arg: \tuplet 3/2 4 { notes }
+                        // making args = [ratio, baseDur?, body]. Use the last arg (= music block),
+                        // matching what lotus Tuplet.music getter does: this.args[this.args.length-1]
+                        const body = termAny.args?.[termAny.args.length - 1]?.body || [];
                         if (ratioStr && body.length > 0) {
-                            // Parse ratio string
                             const ratioMatch = ratioStr.match(/^(\d+)\/(\d+)$/);
                             if (ratioMatch) {
                                 const [, num, denom] = ratioMatch;
-                                const ratio = {
-                                    numerator: parseInt(denom, 10), // Swapped: lilylet uses actual/normal
-                                    denominator: parseInt(num, 10),
+                                // \tuplet 3/2: divider = 3/2, lilylet ratio = 2/3 → swap
+                                // \times 2/3: factor = 2/3, lilylet ratio = 2/3 → no swap
+                                const ratio = isTimes
+                                    ? { numerator: parseInt(num, 10), denominator: parseInt(denom, 10) }
+                                    : { numerator: parseInt(denom, 10), denominator: parseInt(num, 10) };
+                                // Count sounding (non-grace) notes/rests in the tuplet body,
+                                // recursing into AfterGrace.body (main note) but not AfterGrace.grace.
+                                // Grace / Acciaccatura / Appoggiatura blocks count as 0.
+                                const countSounding = (items) => {
+                                    let n = 0;
+                                    for (const item of items) {
+                                        if (!item)
+                                            continue;
+                                        switch (item.proto) {
+                                            case 'Chord':
+                                            case 'Rest':
+                                                n++;
+                                                break;
+                                            case 'AfterGrace': {
+                                                // args[0] = main note, args[1] = after-grace notes (0-dur, skip)
+                                                const main = item.args?.[0];
+                                                if (main?.proto === 'Chord' || main?.proto === 'Rest')
+                                                    n++;
+                                                else if (main?.body)
+                                                    n += countSounding(main.body);
+                                                break;
+                                            }
+                                            case 'Grace':
+                                            case 'Acciaccatura':
+                                            case 'Appoggiatura': break;
+                                            default:
+                                                if (item.body)
+                                                    n += countSounding(item.body);
+                                                break;
+                                        }
+                                    }
+                                    return n;
                                 };
-                                // Count how many note/rest events are in the tuplet body
-                                const noteCount = body.filter((item) => item.proto === 'Chord' || item.proto === 'Rest').length;
-                                // Remove the last noteCount note/rest events from voice.events
-                                // (they were already added by the Chord/Rest handlers)
+                                const noteCount = countSounding(body);
                                 const tupletEvents = [];
                                 let removed = 0;
+                                // Pop notes/rests from voice.events, skipping context events.
+                                // Grace notes are moved inside the tuplet but do NOT consume a
+                                // sounding-note slot (they have 0 duration in the time signature).
                                 while (removed < noteCount && voice.events.length > 0) {
                                     const lastEvent = voice.events[voice.events.length - 1];
                                     if (lastEvent.type === 'note' || lastEvent.type === 'rest') {
                                         tupletEvents.unshift(voice.events.pop());
-                                        removed++;
+                                        if (!lastEvent.grace)
+                                            removed++;
+                                    }
+                                    else if (lastEvent.type === 'context' || lastEvent.type === 'pitchReset') {
+                                        // Context event between tuplet notes — move it inside tuplet too
+                                        tupletEvents.unshift(voice.events.pop());
                                     }
                                     else {
-                                        break; // Stop if we hit a non-note/rest event
+                                        break;
                                     }
                                 }
                                 if (tupletEvents.length > 0) {
-                                    const tupletEvent = {
-                                        type: 'tuplet',
-                                        ratio,
-                                        events: tupletEvents,
-                                    };
-                                    voice.events.push(tupletEvent);
+                                    voice.events.push(isTimes
+                                        ? { type: 'times', ratio, events: tupletEvents }
+                                        : { type: 'tuplet', ratio, events: tupletEvents });
                                 }
                             }
                         }
@@ -793,6 +909,49 @@ 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', 'times', '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 (including inside tuplets)
+                const scanStaff = (events) => {
+                    for (const e of events) {
+                        if (e.type === 'context' && e.staff) {
+                            carryStaff = e.staff;
+                        }
+                        else if ((e.type === 'tuplet' || e.type === 'times') && e.events) {
+                            scanStaff(e.events);
+                        }
+                    }
+                };
+                scanStaff(voice.events);
+            }
+        }
     });
     // Filter out empty voices and convert to array, sorted by measure number
     const measures = Array.from(measureMap.entries())
@@ -812,6 +971,8 @@ const hasRealContent = (events) => {
             return true;
         if (e.type === 'tuplet')
             return true;
+        if (e.type === 'times')
+            return true;
         if (e.type === 'tremolo')
             return true;
         return false;

package/lib/lilylet/lilypondEncoder.js

@@ -115,6 +115,59 @@ const getSpacerRest = (timeSig) => {
     const { numerator, denominator } = timeSig;
     return `s${denominator}*${numerator}`;
 };
+// === Partial Measure Helpers ===
+const TPQN = 480;
+const voiceDurationTicks = (voice) => {
+    let ticks = 0;
+    const addEvent = (e, factor = 1) => {
+        if (e.type === 'note' || e.type === 'rest') {
+            const ev = e;
+            if (ev.grace)
+                return;
+            let t = (TPQN * 4) / ev.duration.division;
+            let dot = t / 2;
+            for (let i = 0; i < ev.duration.dots; i++) {
+                t += dot;
+                dot /= 2;
+            }
+            ticks += Math.round(t * factor);
+        }
+        else if (e.type === 'tuplet' || e.type === 'times') {
+            const te = e;
+            const f = factor * te.ratio.numerator / te.ratio.denominator;
+            for (const inner of te.events)
+                addEvent(inner, f);
+        }
+    };
+    for (const e of voice.events)
+        addEvent(e);
+    return ticks;
+};
+const ticksToLyDuration = (ticks) => {
+    const whole = TPQN * 4;
+    for (const div of [1, 2, 4, 8, 16, 32, 64]) {
+        const t = whole / div;
+        if (Math.abs(ticks - t) < 1)
+            return String(div);
+        if (Math.abs(ticks - Math.round(t * 1.5)) < 1)
+            return `${div}.`;
+        if (Math.abs(ticks - Math.round(t * 1.75)) < 1)
+            return `${div}..`;
+    }
+    return '4';
+};
+// Return a spacer-rest suffix to pad a voice to the full measure duration.
+// Uses s16*N to avoid complexity with dotted/compound values.
+const padVoiceToMeasure = (voiceTicks, measureTicks) => {
+    const remaining = Math.round(measureTicks - voiceTicks);
+    if (remaining <= 0)
+        return '';
+    const sixteenth = Math.round(TPQN / 4); // 120 ticks
+    const numSixteenths = Math.round(remaining / sixteenth);
+    if (numSixteenths <= 0)
+        return '';
+    return numSixteenths === 1 ? ' s16' : ` s16*${numSixteenths}`;
+};
 /**
  * Calculate the octave markers needed to serialize a pitch in relative mode.
  */
@@ -396,7 +449,11 @@ const encodeContextChange = (event) => {
  * Encode a tuplet event
  */
 const encodeTupletEvent = (event, env, lastDuration) => {
-    let result = `\\tuplet ${event.ratio.denominator}/${event.ratio.numerator} { `;
+    // \times preserves type:"times"; \tuplet is denominator/numerator
+    const header = event.type === 'times'
+        ? `\\times ${event.ratio.numerator}/${event.ratio.denominator}`
+        : `\\tuplet ${event.ratio.denominator}/${event.ratio.numerator}`;
+    let result = `${header} { `;
     let newEnv = env;
     let newDuration = lastDuration;
     for (const subEvent of event.events) {
@@ -519,7 +576,8 @@ const encodeVoice = (voice, measureContext, voiceIndex) => {
                 result += encodeContextChange(event) + ' ';
                 break;
             }
-            case 'tuplet': {
+            case 'tuplet':
+            case 'times': {
                 const { str, newEnv, newDuration } = encodeTupletEvent(event, env, lastDuration);
                 result += str + ' ';
                 env = newEnv;
@@ -600,7 +658,7 @@ export const encode = (doc, options = {}) => {
         for (const part of measure.parts) {
             for (const voice of part.voices) {
                 for (const event of voice.events) {
-                    if (event.type === 'note' || event.type === 'rest' || event.type === 'tuplet' || event.type === 'tremolo') {
+                    if (event.type === 'note' || event.type === 'rest' || event.type === 'tuplet' || event.type === 'times' || event.type === 'tremolo') {
                         return true;
                     }
                 }
@@ -622,6 +680,8 @@ export const encode = (doc, options = {}) => {
     }
     // Track time signature for each measure (for spacer rests)
     const measureTimeSigs = [];
+    // Track partial (pickup) measure durations as LY duration strings (e.g. "8" for \partial 8)
+    const measurePartialDurs = [];
     let currentKey;
     let currentTimeSig;
     for (let mi = 0; mi < measures.length; mi++) {
@@ -633,6 +693,30 @@ export const encode = (doc, options = {}) => {
             currentTimeSig = measure.timeSig;
         // Store time signature for this measure
         measureTimeSigs[mi] = currentTimeSig;
+        // Detect partial (pickup) measures and compute their duration.
+        // Only the first measure (mi===0) can be an implicit partial;
+        // subsequent incomplete measures are NOT treated as partial.
+        const isExplicitPartial = measure.partial === true;
+        if (isExplicitPartial || (mi === 0 && currentTimeSig)) {
+            let maxVoiceTicks = 0;
+            for (const part of measure.parts) {
+                for (const v of part.voices) {
+                    maxVoiceTicks = Math.max(maxVoiceTicks, voiceDurationTicks(v));
+                }
+            }
+            const expectedTicks = currentTimeSig
+                ? Math.round(TPQN * 4 * currentTimeSig.numerator / currentTimeSig.denominator)
+                : TPQN * 4;
+            if (maxVoiceTicks > 0 && maxVoiceTicks < expectedTicks) {
+                measurePartialDurs[mi] = ticksToLyDuration(maxVoiceTicks);
+            }
+            else {
+                measurePartialDurs[mi] = undefined;
+            }
+        }
+        else {
+            measurePartialDurs[mi] = undefined;
+        }
         // Process each part
         for (let pi = 0; pi < measure.parts.length; pi++) {
             const part = measure.parts[pi];
@@ -649,11 +733,19 @@ export const encode = (doc, options = {}) => {
                     staffMeasures.push([]);
                 }
                 // Encode voice content
-                const voiceContent = encodeVoice(voice, {
+                let voiceContent = encodeVoice(voice, {
                     key: currentKey,
                     timeSig: currentTimeSig,
                     isFirst: mi === 0
                 }, vi);
+                // For non-partial measures, pad incomplete voices to fill the full
+                // measure duration. lotus doesn't auto-advance on barlines, so
+                // under-full voices cause measure boundary miscounting.
+                if (!measurePartialDurs[mi] && currentTimeSig) {
+                    const expectedTicks = Math.round(TPQN * 4 * currentTimeSig.numerator / currentTimeSig.denominator);
+                    const voiceTicks = voiceDurationTicks(voice);
+                    voiceContent += padVoiceToMeasure(voiceTicks, expectedTicks);
+                }
                 staffMeasures[mi].push(voiceContent);
             }
         }
@@ -666,10 +758,28 @@ export const encode = (doc, options = {}) => {
         // Build voice lines
         const voiceLines = [];
         for (let vi = 0; vi < maxVoices; vi++) {
+            let prevTimeSigStr;
             const measureContents = measures.map((m, mi) => {
-                // Use correct spacer rest based on time signature
-                const spacer = getSpacerRest(measureTimeSigs[mi]);
-                const content = m[vi] || spacer;
+                // For partial (pickup) measures, use a partial-duration spacer
+                const partialDur = measurePartialDurs[mi];
+                const spacer = partialDur ? `s${partialDur}` : getSpacerRest(measureTimeSigs[mi]);
+                let content = m[vi] || spacer;
+                // Inject \time if the content lacks it and the time sig changed.
+                // lotus processes each voice independently — without \time it
+                // defaults to 4/4, miscounting measure boundaries for other meters.
+                const ts = measureTimeSigs[mi];
+                if (ts) {
+                    const tsStr = `${ts.numerator}/${ts.denominator}`;
+                    if (tsStr !== prevTimeSigStr && !content.includes('\\time')) {
+                        content = `${encodeTimeSig(ts)} ${content}`;
+                    }
+                    prevTimeSigStr = tsStr;
+                }
+                // For partial measures, prepend \partial DUR before all other commands
+                // so the lotus interpreter correctly tracks the pickup measure boundary.
+                if (partialDur && !content.includes('\\partial')) {
+                    content = `\\partial ${partialDur} ${content}`;
+                }
                 // Wrap each measure in its own \relative c' to reset pitch context
                 return `${indent}    \\relative c' { ${content} } |  % ${mi + 1}`;
             });

package/lib/lilylet/musicXmlEncoder.js

@@ -567,7 +567,7 @@ const encodeMeasure = (measure, partIndex, measureNumber, isFirst, prevKey, prev
                     break;
                 }
                 case 'tuplet': {
-                    const tupletEvents = event.events;
+                    const tupletEvents = event.events.filter(e => e.type === 'note' || e.type === 'rest');
                     for (let ti = 0; ti < tupletEvents.length; ti++) {
                         const subEvent = tupletEvents[ti];
                         // Set tuplet ratio on duration so encodeDuration emits <time-modification>

package/lib/lilylet/parser.d.ts

@@ -1,3 +1,14 @@
 import { LilyletDoc } from "./types";
+export interface ParseWarning {
+    type: 'partial-mismatch';
+    message: string;
+    declared: number;
+    actual: number;
+}
 declare const parseCode: (code: string) => LilyletDoc;
-export { parseCode, };
+/**
+ * Return warnings emitted during the most recent parseCode() call.
+ * Currently reports \partial duration mismatches.
+ */
+declare const getParseWarnings: () => ParseWarning[];
+export { parseCode, getParseWarnings, };

package/lib/lilylet/parser.js

@@ -148,4 +148,14 @@ const parseCode = (code) => {
     resolveDocumentPitches(raw);
     return raw;
 };
-export { parseCode, };
+/**
+ * Return warnings emitted during the most recent parseCode() call.
+ * Currently reports \partial duration mismatches.
+ */
+const getParseWarnings = () => {
+    if (parser && parser.getWarnings) {
+        return parser.getWarnings();
+    }
+    return [];
+};
+export { parseCode, getParseWarnings, };