@k-l-lambda/lilylet 0.1.74 → 0.1.75

package/lib/lilylet/serializer.js

@@ -5,6 +5,44 @@
  * Uses relative pitch mode matching the parser's behavior.
  */
 import { StemDirection, } from "./types.js";
+import { parseMeasureLayout } from "./measureLayout.js";
+// Walk a measure-layout AST, recording the FIRST measure index of each alternate
+// ending (1st/2nd house) → its ending number, for the `% volta N` serializer
+// comment convention. Only the alternates of a VoltaMLayout produce labels.
+const collectVoltaLabels = (layout, out) => {
+    const firstIndexOf = (node) => {
+        switch (node.kind) {
+            case "single": return node.measure;
+            case "block": return node.seq.length ? firstIndexOf(node.seq[0]) : undefined;
+            case "volta": return node.body.length ? firstIndexOf(node.body[0]) : undefined;
+            case "aba": return firstIndexOf(node.main);
+        }
+    };
+    const walk = (node) => {
+        switch (node.kind) {
+            case "block":
+                node.seq.forEach(walk);
+                break;
+            case "aba":
+                walk(node.main);
+                node.rest.forEach(walk);
+                break;
+            case "volta":
+                node.body.forEach(walk);
+                if (node.alternates) {
+                    node.alternates.forEach((alt, ai) => {
+                        const first = alt.length ? firstIndexOf(alt[0]) : undefined;
+                        if (first !== undefined && !out.has(first))
+                            out.set(first, ai + 1);
+                        alt.forEach(walk);
+                    });
+                }
+                break;
+            default: break;
+        }
+    };
+    walk(layout);
+};
 const PHONETS = "cdefgab";
 /**
  * Calculate the octave markers needed to serialize a pitch in relative mode.
@@ -369,10 +407,20 @@ const serializeTupletEvent = (event, env) => {
         }
         else if (e.type === 'context') {
             const ctx = e;
+            // A context event inside a tuplet may carry several components at once
+            // (e.g. staff + clef). Emit each present one — previously only staff and
+            // stemDirection were handled, so a clef/ottava change inside a tuplet was
+            // silently dropped on serialization.
             if (ctx.staff != null) {
                 parts.push(' \\staff "' + ctx.staff + '"');
             }
-            else if (ctx.stemDirection != null) {
+            if (ctx.clef != null) {
+                parts.push(' \\clef "' + (CLEF_MAP[ctx.clef] ?? ctx.clef) + '"');
+            }
+            if (ctx.ottava != null) {
+                parts.push(' \\ottava #' + ctx.ottava);
+            }
+            if (ctx.stemDirection != null) {
                 if (ctx.stemDirection === StemDirection.up)
                     parts.push(' \\stemUp');
                 else if (ctx.stemDirection === StemDirection.down)
@@ -511,6 +559,32 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
     // context{staff} events before this index are skipped in the main loop.
     let effectiveInitialStaff = voice.staff;
     let leadStaffScanEnd = 0;
+    // Staff of the first MUSICAL event (note/rest/...), honouring an explicit
+    // note.staff. If it differs from the home staff, the first inline staff switch
+    // would emit a `\staff "X"` that the parser mistakes for the LEADING staff (it
+    // binds home to the first `\staff` before any music), relocating the voice and
+    // any leading clef. We then force an explicit home-staff anchor up front. This
+    // scan is independent of leadStaffScanEnd because a leading clef/key stops that
+    // scan before the first note is reached.
+    let firstMusicalStaff = null;
+    {
+        let scanStaff = voice.staff;
+        for (const e of voice.events) {
+            if (e.type === 'context') {
+                const ctx = e;
+                if (ctx.staff != null)
+                    scanStaff = ctx.staff;
+                continue;
+            }
+            if (e.type === 'pitchReset')
+                continue;
+            if (e.type === 'note')
+                firstMusicalStaff = e.staff ?? scanStaff;
+            else
+                firstMusicalStaff = scanStaff;
+            break;
+        }
+    }
     for (let i = 0; i < voice.events.length; i++) {
         const e = voice.events[i];
         if (e.type === 'pitchReset') {
@@ -538,10 +612,19 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
         // 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.
-    // Use effectiveInitialStaff so carry-over replaces the default emission.
-    if (isGrandStaff || effectiveInitialStaff !== currentStaff) {
+    // Output staff command if the voice's initial staff is not what the PARSER will
+    // assume. The parser (lilylet.jison voice()) assigns every voice with no leading
+    // `\staff` directive to staff 1 unconditionally — it does NOT carry staff across
+    // voices or measures. So we must emit `\staff "N"` whenever effectiveInitialStaff
+    // is not 1, even if the cross-measure carry (currentStaff) happens to match it
+    // (e.g. a whole measure sitting on staff 2 after a prior staff-2 measure — without
+    // this, the round-trip would silently relocate that voice, and its leading clef,
+    // to staff 1). Also emit when it differs from the carry (resets after grand staff)
+    // or always in a grand-staff part for clarity. Finally, force an anchor when the
+    // first note switches staff via note.staff (otherwise that inline `\staff` would
+    // be read as the leading staff and rebind the voice's home).
+    const firstNoteSwitches = firstMusicalStaff != null && firstMusicalStaff !== effectiveInitialStaff;
+    if (isGrandStaff || effectiveInitialStaff !== 1 || effectiveInitialStaff !== currentStaff || firstNoteSwitches) {
         parts.push('\\staff "' + effectiveInitialStaff + '"');
     }
     // Output key/time signatures after \staff (for first voice only)
@@ -568,7 +651,17 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
     // 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];
+    //
+    // The carry-in fallback (`allStaffClefs[staff]`) is the clef state at the START of
+    // the measure and is NOT updated mid-measure, whereas `emittedClefs` IS. So a voice
+    // with no clef of its own must only use the fallback to ESTABLISH a staff that has
+    // not been emitted yet — never to "restate" it once any sibling voice has already
+    // emitted/changed this staff's clef this measure, because the fallback would then be
+    // stale and would wrongly revert that sibling's change (e.g. v1 moves staff 2 to
+    // treble, then v2 with no clef must not re-emit the carried-in bass).
+    const ownClef = findVoiceClef(voice);
+    const carryClef = allStaffClefs?.[voice.staff];
+    const voiceClef = ownClef ?? (emittedClefs?.[voice.staff] === undefined ? carryClef : undefined);
     const clefAlreadyEmitted = voiceClef && emittedClefs?.[voice.staff] === voiceClef;
     if (voiceClef && !clefAlreadyEmitted) {
         parts.push('\\clef "' + (CLEF_MAP[voiceClef] ?? voiceClef) + '"');
@@ -591,7 +684,8 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
                 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];
+                const ctxClef = ctx.clef ||
+                    (emittedClefs?.[activeStaff] === undefined ? allStaffClefs?.[activeStaff] : undefined);
                 if (ctxClef && emittedClefs?.[activeStaff] !== ctxClef) {
                     parts.push('\\clef "' + (CLEF_MAP[ctxClef] ?? ctxClef) + '"');
                     if (emittedClefs)
@@ -618,7 +712,7 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
                 activeStaff = effectiveStaff;
                 parts.push('\\staff "' + activeStaff + '"');
                 // Emit the target staff's clef if it differs from what was last emitted for this staff
-                const targetClef = allStaffClefs?.[activeStaff];
+                const targetClef = emittedClefs?.[activeStaff] === undefined ? allStaffClefs?.[activeStaff] : undefined;
                 if (targetClef && emittedClefs?.[activeStaff] !== targetClef) {
                     parts.push('\\clef "' + (CLEF_MAP[targetClef] ?? targetClef) + '"');
                     if (emittedClefs)
@@ -776,6 +870,9 @@ const serializeMetadata = (metadata) => {
     if (metadata.staves) {
         lines.push('[staves "' + escapeString(metadata.staves) + '"]');
     }
+    if (metadata.measureLayout) {
+        lines.push('[measures "' + escapeString(metadata.measureLayout) + '"]');
+    }
     if (metadata.instruments) {
         for (const [key, instr] of Object.entries(metadata.instruments)) {
             let line = '[instrument-' + key + ' "' + escapeString(instr.name) + '"';
@@ -856,9 +953,26 @@ export const serializeLilyletDoc = (doc) => {
         measureStrs.push(measureStr || 's1');
         currentStaff = newStaff;
     }
-    // Join measures with bar, measure number comment, and double newline
+    // Volta house-label comments (non-binding convention, like the `% n` measure
+    // index): if a measure-layout directive is present, mark the first measure of
+    // each alternate ending with a `% volta N` comment. Derived from the layout
+    // AST; purely cosmetic, never parsed back.
+    const voltaLabels = new Map(); // 1-based measure index → ending number
+    if (doc.metadata?.measureLayout) {
+        try {
+            const layout = parseMeasureLayout(doc.metadata.measureLayout);
+            collectVoltaLabels(layout, voltaLabels);
+        }
+        catch { /* ignore malformed layout */ }
+    }
+    // Join measures with bar, measure number comment, and double newline. A
+    // `% volta N` label (if any) is prepended on its own line before the measure.
     const measuresOutput = measureStrs
-        .map((m, i) => m + ' | %' + (i + 1))
+        .map((m, i) => {
+        const label = voltaLabels.get(i + 1);
+        const prefix = label !== undefined ? '% volta ' + label + '\n' : '';
+        return prefix + m + ' | %' + (i + 1);
+    })
         .join('\n\n');
     parts.push(measuresOutput);
     return parts.join('\n');

package/lib/lilylet/types.d.ts

@@ -242,6 +242,7 @@ export interface Metadata {
     instrument?: string;
     genre?: string;
     staves?: string;
+    measureLayout?: string;
     instruments?: {
         [key: string]: InstrumentName;
     };

package/lib/measureLayout.d.ts

@@ -0,0 +1 @@
+export * from "./lilylet/measureLayout.js";

package/lib/measureLayout.js

@@ -0,0 +1 @@
+export * from "./lilylet/measureLayout.js";

package/lib/measureLayoutFromXml.d.ts

@@ -0,0 +1 @@
+export * from "./lilylet/measureLayoutFromXml.js";

package/lib/measureLayoutFromXml.js

@@ -0,0 +1 @@
+export * from "./lilylet/measureLayoutFromXml.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.74",
+  "version": "0.1.75",
   "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",
@@ -40,11 +40,14 @@
     "test:decoder": "tsx ./tests/lilypondDecoder.ts",
     "test:abc": "tsx ./tests/abc-decoder.ts",
     "test:roundtrip": "tsx ./tests/lilypond-roundtrip.ts",
+    "test:lyl-roundtrip": "tsx ./tests/lyl-roundtrip.ts",
     "test:abc-svg": "tsx ./tests/abc-abcjs-svg.ts",
     "train:bpe": "tsx ./tools/trainBpeTokenizer.ts",
     "build:manual-tokenizer": "tsx ./tools/buildManualTokenizer.ts",
     "build:browser-bundle": "esbuild tools/browserBundle.ts --bundle --format=iife --platform=browser --minify --outfile=dist/lilylet.bundle.js",
     "test:bpe": "tsx ./tests/unit/bpeTokenizer.test.ts",
+    "test:measures": "tsx ./tests/unit/measureLayout.test.ts",
+    "test:measures-xml": "tsx ./tests/unit/measureLayoutFromXml.test.ts",
     "build:tests": "tsc -p tsconfig.tests.json; cp source/lilylet/grammar.jison.js lib-tests/source/lilylet/ && cp source/abc/grammar.jison.js lib-tests/source/abc/ && node tools/fixEsmExtensions.cjs lib-tests && ln -sfn ../../tests/assets lib-tests/tests/assets",
     "test:roundtrip:compiled": "node lib-tests/tests/lilypond-roundtrip.js",
     "ts": "tsx"
@@ -70,7 +73,7 @@
     "ts-node": "^10.9.2",
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
-    "verovio": "^5.7.0",
+    "verovio": "^6.2.0",
     "yargs": "^17.7.2"
   },
   "dependencies": {