@k-l-lambda/lilylet 0.1.63 → 0.1.64

package/lib/tests/unit/crossStaffDecoder.test.js

@@ -0,0 +1,147 @@
+/**
+ * Unit test: \change Staff handling in the LilyPond decoder.
+ *
+ * Regression guard for the bug where \change Staff commands are ignored during
+ * .ly → JSON decoding, causing notes that should be on staff 2 (bass) to remain
+ * on staff 1 (treble) in the lilylet output.
+ *
+ * Background: BWV-787 m1 fails because the decoder ignores all \change Staff
+ * commands (lilypondDecoder.ts: "Ignore \change Staff commands - staff is fixed
+ * per track"). Notes that cross staves get wrong tick assignments when
+ * regulateLilylet matches them against spartito events.
+ *
+ * Usage: npx tsx tests/unit/crossStaffDecoder.test.ts
+ */
+import { decode } from "../../source/lilylet/lilypondDecoder.js";
+import { serializeLilyletDoc } from "../../source/lilylet/serializer.js";
+// ─── helpers ────────────────────────────────────────────────────────────────
+let passed = 0;
+let failed = 0;
+function assert(condition, message) {
+    if (condition) {
+        console.log(`  ✓ ${message}`);
+        passed++;
+    }
+    else {
+        console.error(`  ✗ FAIL: ${message}`);
+        failed++;
+    }
+}
+function getNoteStaffs(voice) {
+    return voice.events
+        .filter(e => e.type === 'note')
+        .map(e => e.staff ?? voice.staff);
+}
+const LY_BOILERPLATE = `
+\\version "2.22.0"
+\\language "english"
+\\header { tagline = ##f }
+#(set-global-staff-size 20)
+\\paper { paper-width = 210\\mm paper-height = 297\\mm ragged-last = ##t }
+\\layout { \\context { \\Score autoBeaming = ##f } }
+`;
+// ─── Warm-up parser ──────────────────────────────────────────────────────────
+{
+    const warn = console.warn, assert2 = console.assert;
+    console.warn = () => { };
+    console.assert = () => { };
+    try {
+        await decode('{ c }');
+    }
+    catch { /* ignore */ }
+    console.warn = warn;
+    console.assert = assert2;
+}
+// ─── Test input: two-staff piano, voice crosses from staff 1 to staff 2 ────
+// Voice 1: c c (both on staff 1 / treble)
+// Voice 2: g (starts on staff 2 / bass via \change Staff = "2")
+//          then g (returns to staff 1 via \change Staff = "1")
+// Expected after decode:
+//   voice 2 events: g is on staff 2, second g is on staff 1
+const LY_CROSS_STAFF = LY_BOILERPLATE + `
+\\score {
+  \\new Staff = "1_1" <<
+    \\new Voice {
+      \\relative c' { \\clef treble \\time 4/4 c2 c } |  % 1
+    }
+    \\new Voice {
+      \\relative c' { \\change Staff = "2" \\clef bass g2 \\change Staff = "1" \\stemDown g } |  % 1
+    }
+  >>
+  \\layout { }
+}
+`;
+// ─── Test 1: decoder captures \change Staff as context events in JSON ────────
+console.log('\nTest 1: \\change Staff produces context { staff } events in decoded JSON');
+await (async () => {
+    const doc = await decode(LY_CROSS_STAFF);
+    // Find the voice with cross-staff content (the one with \change Staff)
+    let crossVoice;
+    for (const measure of doc.measures) {
+        for (const part of measure.parts) {
+            for (const voice of part.voices) {
+                const staffContexts = voice.events.filter(e => e.type === 'context' && e.staff !== undefined);
+                if (staffContexts.length > 0) {
+                    crossVoice = voice;
+                    break;
+                }
+            }
+        }
+    }
+    assert(crossVoice !== undefined, 'Found a voice containing context { staff } events');
+    if (crossVoice) {
+        const staffContexts = crossVoice.events.filter(e => e.type === 'context' && e.staff !== undefined);
+        assert(staffContexts.length >= 2, `Voice has ≥2 context staff events (got ${staffContexts.length}) — one for \change Staff = "2", one for \change Staff = "1"`);
+    }
+})();
+// ─── Test 2: notes after \change Staff = "2" are on staff 2 in the JSON ────
+console.log('\nTest 2: note following \\change Staff = "2" has staff=2 in decoded JSON');
+await (async () => {
+    const doc = await decode(LY_CROSS_STAFF);
+    let crossVoice;
+    for (const measure of doc.measures) {
+        for (const part of measure.parts) {
+            for (const voice of part.voices) {
+                const hasStaffContext = voice.events.some(e => e.type === 'context' && e.staff === 2);
+                if (hasStaffContext) {
+                    crossVoice = voice;
+                    break;
+                }
+            }
+        }
+    }
+    if (!crossVoice) {
+        assert(false, 'Could not find cross-staff voice — context events missing from decoder output');
+        return;
+    }
+    // Walk voice events: track activeStaff, verify notes are on correct staff
+    let activeStaff = crossVoice.staff;
+    const noteStaffs = [];
+    for (const event of crossVoice.events) {
+        if (event.type === 'context' && event.staff) {
+            activeStaff = event.staff;
+        }
+        if (event.type === 'note') {
+            noteStaffs.push(event.staff ?? activeStaff);
+        }
+    }
+    assert(noteStaffs.length === 2, `Voice has 2 note events (got ${noteStaffs.length})`);
+    assert(noteStaffs[0] === 2, `First note (after \\change Staff = "2") is on staff 2 (got staff ${noteStaffs[0]})`);
+    assert(noteStaffs[1] === 1, `Second note (after \\change Staff = "1") is on staff 1 (got staff ${noteStaffs[1]})`);
+})();
+// ─── Test 3: serialized .lyl emits \staff "2" before the cross-staff note ───
+console.log('\nTest 3: .lyl serialization emits \\staff "2" for cross-staff note');
+await (async () => {
+    const doc = await decode(LY_CROSS_STAFF);
+    const lyl = serializeLilyletDoc(doc);
+    // The voice that started on staff 1 should switch to \staff "2" mid-line
+    assert(/\\staff "2"/.test(lyl), `lyl contains \\staff "2" switch: ${lyl.includes('\\staff "2"') ? 'yes' : 'NO'}`);
+})();
+// ─── Summary ─────────────────────────────────────────────────────────────────
+console.log(`\n${'═'.repeat(40)}`);
+if (failed > 0) {
+    console.log(`⚠️  ${failed} test(s) FAILED — \\change Staff is not handled by the decoder.`);
+    console.log(`   See lilypondDecoder.ts: "Ignore \\change Staff commands - staff is fixed per track"`);
+}
+console.log(`Total: ${passed + failed}  Passed: ${passed}  Failed: ${failed}`);
+process.exit(failed > 0 ? 1 : 0);

package/lib/tests/unit/crossStaffEdgeCases.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/tests/unit/crossStaffEdgeCases.test.js

@@ -0,0 +1,209 @@
+// tests/unit/crossStaffEdgeCases.test.ts
+//
+// Adversarial edge cases for cross-staff carry-over fixes (written by GPT review).
+// Run with:
+//   npx tsx tests/unit/crossStaffEdgeCases.test.ts
+import { decode } from '../../source/lilylet/lilypondDecoder.js';
+import { serializeLilyletDoc } from '../../source/lilylet/serializer.js';
+let passed = 0;
+let failed = 0;
+function assert(condition, message) {
+    if (condition) {
+        console.log(`  ✓ ${message}`);
+        passed++;
+    }
+    else {
+        console.error(`  ✗ FAIL: ${message}`);
+        failed++;
+    }
+}
+function note(phonet, division = 4, octave = 0) {
+    return { type: 'note', pitches: [{ phonet, octave }], duration: { division, dots: 0 } };
+}
+function rest(division = 4) {
+    return { type: 'rest', duration: { division, dots: 0 } };
+}
+function mkDoc(events, staff = 1) {
+    return {
+        measures: [{
+                parts: [{
+                        voices: [{ staff, events }]
+                    }]
+            }]
+    };
+}
+function getMeasureVoice(doc, measureIndex) {
+    return doc.measures?.[measureIndex]?.parts?.[0]?.voices?.[0];
+}
+function staffContexts(events) {
+    return events.filter((e) => e.type === 'context' && e.staff != null);
+}
+function noteStaffs(voice) {
+    let activeStaff = voice.staff;
+    const out = [];
+    for (const e of voice.events) {
+        if (e.type === 'context' && e.staff != null)
+            activeStaff = e.staff;
+        else if (e.type === 'note')
+            out.push(e.staff ?? activeStaff);
+    }
+    return out;
+}
+function summarizeLeadTypesBeforeFirstStaffCtx(voice) {
+    const idx = voice.events.findIndex((e) => e.type === 'context' && e.staff != null);
+    if (idx < 0)
+        return [];
+    return voice.events.slice(0, idx).map((e) => e.type);
+}
+const LY_BOILERPLATE = `
+\\version "2.22.0" \\language "english" \\header { tagline = ##f }
+\\layout { \\context { \\Score autoBeaming = ##f } }
+`;
+/** Wrap a relative music expression in a minimal full LilyPond score. */
+function makeLy(relativeMusic) {
+    return LY_BOILERPLATE + `
+\\score { \\new Staff = "1_1" << \\new Voice {
+  \\relative c' { ${relativeMusic} }
+} >> \\layout {} }
+`;
+}
+console.log('crossStaffEdgeCases.test.ts\n');
+// Warm-up
+{
+    const w = console.warn, a = console.assert;
+    console.warn = () => { };
+    console.assert = () => { };
+    try {
+        await decode('{ c }');
+    }
+    catch { }
+    console.warn = w;
+    console.assert = a;
+}
+// ─── C1-A: music before reset — carry-over NOT suppressed ────────────────────
+{
+    const LY = `\\time 2/4 c4 \\change Staff = "2" d4 | e4 \\change Staff = "1" f4`;
+    const doc = await decode(makeLy(LY));
+    const m2voice = getMeasureVoice(doc, 1);
+    assert(m2voice !== undefined, 'C1-A: decoded second measure voice exists');
+    const ctxs = staffContexts(m2voice.events);
+    assert(ctxs.length >= 2, 'C1-A: second measure has carry-over and explicit reset contexts');
+    const firstTwo = ctxs.slice(0, 2).map((e) => e.staff);
+    assert(JSON.stringify(firstTwo) === JSON.stringify([2, 1]), 'C1-A: measure 2 starts with carry-over staff 2, then reset to staff 1');
+    const staffs = noteStaffs(m2voice);
+    assert(JSON.stringify(staffs) === JSON.stringify([2, 1]), 'C1-A: e4 on staff 2 (carry-over), f4 on staff 1 (after reset)');
+}
+// ─── C1-B: non-musical context before reset — carry-over suppressed ──────────
+// Strengthened: verifies explicit reset still present and all notes on staff 1.
+{
+    const LY = `\\time 4/4 c4 \\change Staff = "2" d e f | \\time 3/4 \\change Staff = "1" g a b`;
+    const doc = await decode(makeLy(LY));
+    const m2voice = getMeasureVoice(doc, 1);
+    assert(m2voice !== undefined, 'C1-B: decoded second measure voice exists');
+    const ctxs = staffContexts(m2voice.events);
+    assert(ctxs.length >= 1, 'C1-B: second measure still has explicit reset to staff 1');
+    assert(ctxs[0].staff === 1, 'C1-B: first staff context in m2 is reset to 1, not ghost carry-over staff 2');
+    const staffs = noteStaffs(m2voice);
+    assert(staffs.length >= 3 && staffs.every(s => s === 1), 'C1-B: all notes in m2 are on staff 1 after immediate reset');
+}
+// ─── C1-C: grace before reset — discovery + carry-over kept ──────────────────
+// Discovery assertion: prove grace is decoded as a pre-reset musical event.
+{
+    const LY = `c4 \\change Staff = "2" d e f | \\grace g8 \\change Staff = "1" a b c`;
+    const doc = await decode(makeLy(LY));
+    const m2voice = getMeasureVoice(doc, 1);
+    assert(m2voice !== undefined, 'C1-C: decoded second measure voice exists');
+    // Discovery: find events between carry-over (context{staff:2}) and reset (context{staff:1})
+    const allCtxs = staffContexts(m2voice.events);
+    const carryIdx = m2voice.events.findIndex((e) => e.type === 'context' && e.staff === 2);
+    const resetIdx = m2voice.events.findIndex((e) => e.type === 'context' && e.staff === 1);
+    const betweenTypes = carryIdx >= 0 && resetIdx > carryIdx
+        ? m2voice.events.slice(carryIdx + 1, resetIdx).map((e) => e.type)
+        : [];
+    assert(betweenTypes.length > 0, `C1-C discovery: events between carry-over and reset (${betweenTypes.join(', ')})`);
+    const hasMusicalBetween = betweenTypes.some(t => /grace/i.test(t) || t === 'note' || t === 'tuplet');
+    assert(hasMusicalBetween, `C1-C discovery: musical event between carry-over and reset (${betweenTypes.join(', ')})`);
+    const ctxs = allCtxs;
+    assert(ctxs.length >= 2 && ctxs[0].staff === 2, 'C1-C: carry-over staff 2 is kept when musical event precedes explicit reset');
+    const m2lyl = serializeLilyletDoc(mkDoc(m2voice.events, m2voice.staff ?? 1));
+    assert(/\\staff "2"/.test(m2lyl), 'C1-C: serialized m2 contains \\staff "2" before the reset sequence');
+}
+// ─── C2-A: leading { staff:1, clef:"bass" } — clef NOT dropped ───────────────
+{
+    const doc = mkDoc([
+        { type: 'context', staff: 1, clef: 'bass' },
+        note('c'),
+    ], 1);
+    const lyl = serializeLilyletDoc(doc);
+    assert(/\\clef\s+"?bass"?/.test(lyl), 'C2-A: same-staff compound context preserves clef');
+    assert(/[a-g]/.test(lyl), 'C2-A: note still serializes after same-staff compound context');
+}
+// ─── C2-A2: leading { staff:2, clef:"bass" } — both emitted, staff before clef
+{
+    const doc = mkDoc([
+        { type: 'context', staff: 2, clef: 'bass' },
+        note('c'),
+    ], 1);
+    const lyl = serializeLilyletDoc(doc);
+    const iStaff = lyl.indexOf('\\staff "2"');
+    const iClef = lyl.search(/\\clef\s+"?bass"?/);
+    assert(iStaff >= 0, 'C2-A2: different-staff compound emits \\staff "2"');
+    assert(iClef >= 0, 'C2-A2: different-staff compound preserves clef');
+    assert(iStaff < iClef, 'C2-A2: \\staff "2" precedes \\clef in compound context');
+}
+// ─── C2-B: [staff:2, clef, staff:1, note] — correct order throughout ─────────
+{
+    const doc = mkDoc([
+        { type: 'context', staff: 2 },
+        { type: 'context', clef: 'bass' },
+        { type: 'context', staff: 1 },
+        note('c'),
+    ], 1);
+    const lyl = serializeLilyletDoc(doc);
+    const i2 = lyl.indexOf('\\staff "2"');
+    const ic = lyl.search(/\\clef\s+"?bass"?/);
+    const i1 = lyl.indexOf('\\staff "1"');
+    // Find note after last \staff directive (to avoid matching letters in "bass"/"clef")
+    const inote = lyl.indexOf('c', i1 + 1);
+    assert(i2 >= 0, 'C2-B: emits \\staff "2"');
+    assert(ic >= 0, 'C2-B: emits \\clef bass');
+    assert(i1 >= 0, 'C2-B: emits \\staff "1"');
+    assert(i2 >= 0 && ic >= 0 && i1 >= 0 && inote >= 0 && i2 < ic && ic < i1 && i1 < inote, 'C2-B: order is \\staff "2" → clef → \\staff "1" → note');
+}
+// ─── C2-C: [pitchReset, staff:2, staff:1, rest] — no ghost, rest survives ────
+{
+    const doc = mkDoc([
+        { type: 'pitchReset' },
+        { type: 'context', staff: 2 },
+        { type: 'context', staff: 1 },
+        rest(4),
+    ], 1);
+    const lyl = serializeLilyletDoc(doc);
+    assert(!/\\staff "2"/.test(lyl), 'C2-C: collapsed leading staff 2 does not appear as ghost');
+    assert(/\br/.test(lyl), 'C2-C: rest still serializes after collapsing leading staff events');
+}
+// ─── C2-D: unknown leading event stops scan — only if markup is supported ────
+{
+    const markupEvent = { type: 'markup', content: 'hi', placement: 'above' };
+    const probeLyl = serializeLilyletDoc(mkDoc([markupEvent, note('c')], 1));
+    if (!/\\markup/.test(probeLyl)) {
+        console.log('  - SKIP C2-D: serializer does not emit \\markup for this event shape');
+    }
+    else {
+        const doc = mkDoc([
+            markupEvent,
+            { type: 'context', staff: 2 },
+            note('c'),
+        ], 1);
+        const lyl = serializeLilyletDoc(doc);
+        const iMarkup = lyl.indexOf('\\markup');
+        const iStaff2 = lyl.indexOf('\\staff "2"');
+        assert(iMarkup >= 0, 'C2-D: markup serializes');
+        assert(iStaff2 >= 0, 'C2-D: \\staff "2" serializes after markup');
+        assert(iMarkup < iStaff2, 'C2-D: markup precedes \\staff "2" — scan stopped by unknown event, staff not absorbed');
+    }
+}
+// ─── Summary ─────────────────────────────────────────────────────────────────
+console.log(`\nPassed: ${passed}`);
+console.log(`Failed: ${failed}`);
+process.exit(failed > 0 ? 1 : 0);

package/lib/tests/unit/crossStaffMultiMeasure.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Unit test: \change Staff state carries over across measure boundaries.
+ *
+ * Regression guard for the bug where the lyl serializer resets activeStaff
+ * to voice.staff at each measure boundary, so a voice that ended on staff 2
+ * (via \change Staff = "2") incorrectly starts the next measure on staff 1.
+ *
+ * Real-world case: BWV-787 %6 ends with \change Staff = "2".
+ * In %7, the voice starts on staff 2 (e4 on bass), then switches back
+ * with \change Staff = "1". The lyl serializer was outputting \staff "1"
+ * at the top of the %7 voice line, wrongly placing the bass e4 on staff 1.
+ *
+ * Usage: npx tsx tests/unit/crossStaffMultiMeasure.test.ts
+ */
+export {};

package/lib/tests/unit/crossStaffMultiMeasure.test.js

@@ -0,0 +1,231 @@
+/**
+ * Unit test: \change Staff state carries over across measure boundaries.
+ *
+ * Regression guard for the bug where the lyl serializer resets activeStaff
+ * to voice.staff at each measure boundary, so a voice that ended on staff 2
+ * (via \change Staff = "2") incorrectly starts the next measure on staff 1.
+ *
+ * Real-world case: BWV-787 %6 ends with \change Staff = "2".
+ * In %7, the voice starts on staff 2 (e4 on bass), then switches back
+ * with \change Staff = "1". The lyl serializer was outputting \staff "1"
+ * at the top of the %7 voice line, wrongly placing the bass e4 on staff 1.
+ *
+ * Usage: npx tsx tests/unit/crossStaffMultiMeasure.test.ts
+ */
+import { decode } from "../../source/lilylet/lilypondDecoder.js";
+import { serializeLilyletDoc } from "../../source/lilylet/serializer.js";
+import { parseCode } from "../../source/lilylet/parser.js";
+// ─── helpers ────────────────────────────────────────────────────────────────
+let passed = 0;
+let failed = 0;
+function assert(condition, message) {
+    if (condition) {
+        console.log(`  ✓ ${message}`);
+        passed++;
+    }
+    else {
+        console.error(`  ✗ FAIL: ${message}`);
+        failed++;
+    }
+}
+/** Walk voice events, tracking activeStaff via context { staff } events. */
+function getNoteStaffs(voice) {
+    let activeStaff = voice.staff;
+    const result = [];
+    for (const e of voice.events) {
+        if (e.type === 'context' && e.staff)
+            activeStaff = e.staff;
+        if (e.type === 'note')
+            result.push({ phonet: e.pitches[0].phonet, staff: activeStaff });
+    }
+    return result;
+}
+const LY_BOILERPLATE = `
+\\version "2.22.0"
+\\language "english"
+\\header { tagline = ##f }
+#(set-global-staff-size 20)
+\\paper { paper-width = 210\\mm paper-height = 297\\mm ragged-last = ##t }
+\\layout { \\context { \\Score autoBeaming = ##f } }
+`;
+// Two-measure test case:
+//   Measure 1: voice on staff 1 (treble), switches to staff 2 at the end
+//   Measure 2: voice continues on staff 2 (carry-over), then switches back to staff 1
+//
+// Measure 1 notes (staff 1 → staff 2):
+//   c4 d4 \change Staff = "2" e4 f4
+//   → c,d on staff 1; e,f on staff 2
+//
+// Measure 2 notes (starts on staff 2, then back to staff 1):
+//   g4 \change Staff = "1" a4 b4 c4
+//   → g on staff 2; a,b,c on staff 1
+const LY_CROSS_MEASURE = LY_BOILERPLATE + `
+\\score {
+  \\new PianoStaff <<
+    \\new Staff = "1" {
+      \\relative c' { \\clef treble \\time 4/4
+        c1 | c1 |
+      }
+    }
+    \\new Staff = "2" {
+      \\relative c { \\clef bass \\time 4/4
+        c1 | c1 |
+      }
+    }
+  >>
+  \\new Staff = "1_1" <<
+    \\new Voice {
+      \\relative c' { \\clef treble \\time 4/4
+        c4 d4 \\change Staff = "2" e4 f4 |  % 1
+        g4 \\change Staff = "1" a4 b4 c4 |  % 2
+      }
+    }
+  >>
+  \\layout { }
+}
+`;
+// ─── Warm-up ────────────────────────────────────────────────────────────────
+{
+    const warn = console.warn, assert2 = console.assert;
+    console.warn = () => { };
+    console.assert = () => { };
+    try {
+        await decode('{ c }');
+    }
+    catch { /* ignore */ }
+    console.warn = warn;
+    console.assert = assert2;
+}
+// ─── Test 1: decoder captures staff changes across measures ─────────────────
+console.log('\nTest 1: decoder — cross-measure \\change Staff captured in JSON');
+await (async () => {
+    const doc = await decode(LY_CROSS_MEASURE);
+    // Find the cross-staff voice (the one that has context { staff } events)
+    let crossVoice1; // measure 1
+    let crossVoice2; // measure 2
+    for (let mi = 0; mi < doc.measures.length; mi++) {
+        for (const part of doc.measures[mi].parts) {
+            for (const v of part.voices) {
+                if (v.events.some(e => e.type === 'context' && e.staff && e.staff !== v.staff)) {
+                    if (mi === 0)
+                        crossVoice1 = v;
+                    if (mi === 1)
+                        crossVoice2 = v;
+                }
+            }
+        }
+    }
+    assert(crossVoice1 !== undefined, 'Measure 1: cross-staff voice found');
+    assert(crossVoice2 !== undefined, 'Measure 2: cross-staff voice found (staff carry-over)');
+    if (crossVoice1) {
+        const notes1 = getNoteStaffs(crossVoice1);
+        assert(notes1.length === 4, `Measure 1: 4 notes (got ${notes1.length})`);
+        assert(notes1[0]?.staff === 1 && notes1[1]?.staff === 1, `Measure 1: c,d on staff 1 (got ${notes1[0]?.staff},${notes1[1]?.staff})`);
+        assert(notes1[2]?.staff === 2 && notes1[3]?.staff === 2, `Measure 1: e,f on staff 2 (got ${notes1[2]?.staff},${notes1[3]?.staff})`);
+    }
+    if (crossVoice2) {
+        const notes2 = getNoteStaffs(crossVoice2);
+        assert(notes2.length === 4, `Measure 2: 4 notes (got ${notes2.length})`);
+        // g should be on staff 2 (carry-over from measure 1's \change Staff = "2")
+        assert(notes2[0]?.staff === 2, `Measure 2: g on staff 2 (carry-over) (got ${notes2[0]?.staff})`);
+        assert(notes2[1]?.staff === 1 && notes2[2]?.staff === 1 && notes2[3]?.staff === 1, `Measure 2: a,b,c on staff 1 (got ${notes2[1]?.staff},${notes2[2]?.staff},${notes2[3]?.staff})`);
+    }
+})();
+// ─── Test 2: serialized .lyl preserves staff on g (measure 2 first note) ────
+console.log('\nTest 2: serializer — g in measure 2 is on \\staff "2" in .lyl');
+await (async () => {
+    const doc = await decode(LY_CROSS_MEASURE);
+    const lyl = serializeLilyletDoc(doc);
+    console.log('  lyl output:\n' + lyl.split('\n').map(l => '    ' + l).join('\n'));
+    // In the .lyl for measure 2, the voice line that contains g should start
+    // with \staff "2" (or have \staff "2" before g), NOT \staff "1".
+    //
+    // Correct:   \staff "2" g4 \staff "1" a4 b4 c4
+    // Wrong:     \staff "1" g4 \staff "1" a4 b4 c4  (or just \staff "1" g4 a4 b4 c4)
+    // Parse back and check
+    const docRT = parseCode(lyl);
+    let crossVoice2;
+    for (const part of docRT.measures[1]?.parts ?? []) {
+        for (const v of part.voices) {
+            if (v.events.some(e => e.type === 'note' && e.pitches[0].phonet === 'g')) {
+                crossVoice2 = v;
+            }
+        }
+    }
+    assert(crossVoice2 !== undefined, 'Measure 2 round-trip: voice with g found');
+    if (crossVoice2) {
+        const notes2 = getNoteStaffs(crossVoice2);
+        const gNote = notes2.find(n => n.phonet === 'g');
+        assert(gNote?.staff === 2, `Measure 2 round-trip: g is on staff 2 (got ${gNote?.staff})`);
+        const aNotes = notes2.filter(n => ['a', 'b', 'c'].includes(n.phonet));
+        assert(aNotes.every(n => n.staff === 1), `Measure 2 round-trip: a,b,c are on staff 1 (got ${aNotes.map(n => n.staff).join(',')})`);
+    }
+})();
+// ─── Test 3: no redundant consecutive \staff directives ──────────────────────
+// Regression: the carry-over fix prepends context { staff: 2 } to measure 2's
+// voice, but serializeVoice also emits \staff "1" (voice.staff) at the top.
+// This produces "\staff "1" \staff "2" g4" — the first directive is redundant
+// because it is immediately overridden by the carry-over.
+//
+// Expected:  \staff "2" g4 \staff "1" a b c   (or just the carry-over first)
+// Buggy:     \staff "1" \staff "2" g4 ...      (two consecutive \staff)
+console.log('\nTest 3: no redundant consecutive \\staff directives in serialized .lyl');
+await (async () => {
+    const doc = await decode(LY_CROSS_MEASURE);
+    const lyl = serializeLilyletDoc(doc);
+    // Check each measure line for consecutive \staff "N" \staff "M" pattern
+    for (const line of lyl.split('\n')) {
+        const consecutiveStaff = /\\staff\s+"[^"]+"\s+\\staff\s+"[^"]+"/.test(line);
+        assert(!consecutiveStaff, `No consecutive \\staff directives on line: ${line.trim()}`);
+    }
+})();
+// ─── Test 4: carry-over immediately cancelled by \change Staff — no ghost \staff
+//
+// Real-world case: czerny-740-31.ly m68, voice (staff:1):
+//   events = [context{staff:2}, context{staff:1}, rest, ...]
+//
+// The carry-over prepends context{staff:2} but the very first event of the
+// original measure is \change Staff = "1" — switching straight back.
+// There are no notes, clef changes, or ottava shifts between the two staff
+// switches.
+//
+// Correct output:   \staff "1" r4 ...   (carry-over cancelled, only show final staff)
+// Buggy output:     \staff "2" \time 3/4 \staff "1" r4 ...
+console.log('\nTest 4: carry-over immediately cancelled by \\change Staff — no ghost \\staff emitted');
+await (async () => {
+    // Build a doc where voice.staff=1 has a carry-over to staff 2 that is
+    // immediately cancelled by context{staff:1}.
+    const { parseCode } = await import('../../source/lilylet/parser.js');
+    const doc = {
+        measures: [{
+                timeSig: { numerator: 3, denominator: 4 },
+                parts: [{
+                        voices: [{
+                                staff: 1,
+                                events: [
+                                    { type: 'context', staff: 2 }, // carry-over
+                                    { type: 'context', staff: 1 }, // immediate cancel
+                                    { type: 'rest', duration: { division: 4, dots: 0 } },
+                                    { type: 'note', pitches: [{ phonet: 'c', octave: 1 }], duration: { division: 2, dots: 0 } },
+                                ]
+                            }]
+                    }]
+            }]
+    };
+    const lyl = serializeLilyletDoc(doc);
+    // The ghost \staff "2" must not appear — it was immediately cancelled
+    assert(!/\\staff "2"/.test(lyl), `No ghost \\staff "2" when carry-over immediately cancelled — got: ${lyl.trim()}`);
+    // \staff "1" may or may not appear (acceptable either way), but the notes must be on staff 1
+    const docRT = parseCode(lyl);
+    const voices = docRT.measures[0]?.parts[0]?.voices ?? [];
+    const staffOnes = voices.filter(v => v.staff === 1);
+    assert(staffOnes.length > 0, `Round-trip: voice on staff 1 exists`);
+    const notes = staffOnes.flatMap(v => v.events.filter(e => e.type === 'note' || e.type === 'rest'));
+    assert(notes.length === 2, `Round-trip: 2 note/rest events on staff 1 (got ${notes.length})`);
+})();
+// ─── Summary ─────────────────────────────────────────────────────────────────
+console.log(`\n${'═'.repeat(40)}`);
+if (failed > 0)
+    console.log(`⚠️  ${failed} FAILED — \\change Staff state not carried across measure boundaries`);
+console.log(`Total: ${passed + failed}  Passed: ${passed}  Failed: ${failed}`);
+process.exit(failed > 0 ? 1 : 0);

package/lib/tests/unit/fullMeasureRestDecoder.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Unit test: full-measure rest (R1) detection in the LilyPond decoder.
+ *
+ * Regression guard for:
+ *   - lilypondDecoder: R must decode with fullMeasure=true; r must not
+ *   - serializeLilyletDoc: fullMeasure rest must serialize as uppercase R
+ *   - parseCode round-trip: R in .lyl must parse back with fullMeasure=true
+ *
+ * Usage: npx tsx tests/unit/fullMeasureRest.test.ts
+ */
+export {};