@k-l-lambda/lilylet 0.1.81 → 0.1.83

package/lib/lilylet/highlight.d.ts

@@ -1,5 +1,5 @@
 /** Generic highlight scopes Lilylet tokens can carry. */
-export type HighlightScope = "articulation" | "bar" | "brace" | "chordBracket" | "comment" | "dynamic" | "grace" | "hairpin" | "header" | "keyword" | "markup" | "mode" | "navigation" | "number" | "octave" | "operator" | "ornament" | "paren" | "pedal" | "pitch" | "punctuation" | "rest" | "separator" | "squareBracket" | "stem" | "string" | "tie" | "tuplet";
+export type HighlightScope = "articulation" | "bar" | "brace" | "chordBracket" | "comment" | "dynamic" | "grace" | "hairpin" | "header" | "keyword" | "lyric" | "markup" | "mode" | "navigation" | "number" | "octave" | "operator" | "ornament" | "paren" | "pedal" | "pitch" | "punctuation" | "rest" | "separator" | "squareBracket" | "stem" | "string" | "tie" | "tuplet";
 export interface HighlightRule {
     /** Sticky, case-insensitive regex anchored at the scan position. */
     re: RegExp;

package/lib/lilylet/highlight.js

@@ -50,6 +50,7 @@ export const HIGHLIGHT_RULES = [
     { re: /(?:\\segno\b)/iy, scope: "navigation" },
     { re: /(?:\\chords\b)/iy, scope: "keyword" },
     { re: /(?:\\markup\b)/iy, scope: "markup" },
+    { re: /(?:\\addlyrics\b)/iy, scope: "lyric" },
     { re: /(?:\\<)/iy, scope: "hairpin" },
     { re: /(?:\\>)/iy, scope: "hairpin" },
     { re: /(?:\\!)/iy, scope: "hairpin" },
@@ -109,6 +110,13 @@ export const HIGHLIGHT_RULES = [
     { re: /(?:=)/iy, scope: "operator" },
     { re: /(?:[rR])/iy, scope: "rest" },
     { re: /(?:[sS])/iy, scope: "rest" },
+    { re: /(?:\{)/iy, scope: "brace" },
+    { re: /(?:\})/iy, scope: "brace" },
+    { re: /(?:--)/iy, scope: "lyric" },
+    { re: /(?:__\b)/iy, scope: "lyric" },
+    { re: /(?:_\b)/iy, scope: "lyric" },
+    { re: /(?:"([^\"\\]|\\.)*")/iy, scope: "string" },
+    { re: /(?:[^ \t\r\n{}\"\\]+)/iy, scope: "string" },
 ];
 /**
  * Match a single token at `pos` in `line` using longest-match. Returns the

package/lib/lilylet/index.d.ts

@@ -3,6 +3,7 @@ export * from "./parser";
 export * from "./serializer";
 export * from "./staffLayout";
 export * from "./measureLayout";
+export * from "./onsets";
 import * as meiEncoder from "./meiEncoder";
 import * as musicXmlDecoder from "./musicXmlDecoder";
 import * as lilypondEncoder from "./lilypondEncoder";

package/lib/lilylet/index.js

@@ -3,6 +3,7 @@ export * from "./parser.js";
 export * from "./serializer.js";
 export * from "./staffLayout.js";
 export * from "./measureLayout.js";
+export * from "./onsets.js";
 import * as meiEncoder from "./meiEncoder.js";
 import * as musicXmlDecoder from "./musicXmlDecoder.js";
 import * as lilypondEncoder from "./lilypondEncoder.js";

package/lib/lilylet/measureLayoutFromXml.js

@@ -19,7 +19,7 @@
  * repeat/volta/segno-jump. Compaction is best-effort; the flat form is the
  * always-valid fallback.
  */
-import { parseMeasureLayout, expandMeasureLayout } from "./measureLayout.js";
+import { parseMeasureLayout, expandMeasureLayout, LayoutType } from "./measureLayout.js";
 import { getDirectChildren, getAttribute } from "./musicXmlUtils.js";
 // Collapse runs of ≥3 consecutive ascending indices into "a..b"; emit the rest
 // comma-separated. Mirrors lotus seqToCode for a flat index list.
@@ -62,14 +62,9 @@ const simulate = (infos) => {
         byIndex.set(info.index, info);
     const segnoIdx = infos.find(i => i.segno)?.index ?? 1;
     const codaIdx = infos.find(i => i.coda)?.index;
-    // Ending (volta) spans, sorted by start index. On pass P of the enclosing
-    // repeat, the ending whose number === P is played; others are skipped by
-    // jumping to the next ending's start (the last ending is the fallthrough).
-    const endingSpans = infos
-        .filter(i => i.endingStart !== undefined)
-        .map(i => ({ number: i.endingStart, start: i.index }))
-        .sort((a, b) => a.start - b.start);
-    const nextEndingStartAfter = (idx) => endingSpans.find(e => e.start > idx)?.start;
+    // Classify repeat/volta sections once so ending-skip decisions are scoped to
+    // the current repeat section, not a later independent section's endings.
+    const sections = classifyRepeatSections(infos, 1, n);
     const order = [];
     const passCount = new Map(); // forward-repeat start index → completed passes
     let repeatStartStack = [1]; // implicit start at measure 1
@@ -87,15 +82,16 @@ const simulate = (infos) => {
         if (info?.endingStart !== undefined) {
             const start = repeatStartStack[repeatStartStack.length - 1] ?? 1;
             const currentPass = (passCount.get(start) ?? 0) + 1;
+            const section = findSectionForIndex(sections, i);
+            const endingSpans = section ? endingSpansForSection(infos, section) : [];
             const isLastEnding = endingSpans[endingSpans.length - 1]?.start === i;
             if (info.endingStart !== currentPass && !isLastEnding) {
-                const next = nextEndingStartAfter(i);
+                const next = endingSpans.find(e => e.start > i)?.start;
                 if (next !== undefined) {
                     i = next;
                     continue;
                 }
-                // no further ending: fall past all endings
-                i = i + 1;
+                i = section ? section.hi + 1 : i + 1;
                 continue;
             }
         }
@@ -108,7 +104,10 @@ const simulate = (infos) => {
         // Fine stop (only after a D.C./D.S. jump has occurred)
         if (info?.fine && (jumpedDaCapo || jumpedDalSegno))
             break;
-        // Backward repeat → jump to current repeat-start, counting the pass
+        // Backward repeat → jump to current repeat-start, counting the pass.
+        // If this same measure ALSO carries a D.C./D.S. (e.g. ABC "!D.C.!:|"), the
+        // repeat is resolved FIRST (all passes), then we fall through to the
+        // navigation jump below — the da-capo wraps the repeat, not the reverse.
         if (info?.repeatEnd) {
             const start = repeatStartStack[repeatStartStack.length - 1] ?? 1;
             const times = info.repeatTimes ?? 2;
@@ -119,8 +118,13 @@ const simulate = (infos) => {
                 continue;
             }
             repeatStartStack = repeatStartStack.filter(s => s !== start);
-            i++;
-            continue;
+            // repeat exhausted: only advance past it when there is no pending
+            // navigation on this measure (otherwise fall through to D.C./D.S.).
+            const hasPendingNav = (info.dacapo && !jumpedDaCapo) || (info.dalsegno && !jumpedDalSegno);
+            if (!hasPendingNav) {
+                i++;
+                continue;
+            }
         }
         // D.S. (dal segno) — jump back to segno once, arm To-Coda
         if (info?.dalsegno && !jumpedDalSegno) {
@@ -146,6 +150,108 @@ const simulate = (infos) => {
 // "pre, T*[body]{[e1…], [e2…]}, post". Anything more tangled (nested repeats,
 // D.C./D.S. over a volta, segno jumps) is left to the flat fallback.
 const rangeCode = (a, b) => a === b ? `${a}` : flatToCode(Array.from({ length: b - a + 1 }, (_, k) => a + k));
+const isAscendingRun = (seq) => seq.every((v, i) => i === 0 || v === seq[i - 1] + 1);
+const compactFlatToCode = (seq) => {
+    const parts = [];
+    let plain = [];
+    const flushPlain = () => {
+        if (plain.length > 0) {
+            parts.push(flatToCode(plain));
+            plain = [];
+        }
+    };
+    let i = 0;
+    while (i < seq.length) {
+        let repeatLen = 0;
+        for (let len = Math.floor((seq.length - i) / 2); len >= 1; len--) {
+            const chunk = seq.slice(i, i + len);
+            if (!isAscendingRun(chunk))
+                continue;
+            const next = seq.slice(i + len, i + 2 * len);
+            if (JSON.stringify(chunk) === JSON.stringify(next)) {
+                repeatLen = len;
+                break;
+            }
+        }
+        if (repeatLen > 0) {
+            flushPlain();
+            parts.push(`2*[${flatToCode(seq.slice(i, i + repeatLen))}]`);
+            i += repeatLen * 2;
+        }
+        else
+            plain.push(seq[i++]);
+    }
+    flushPlain();
+    return parts.join(", ");
+};
+const layoutExpandsTo = (code, seq, type = LayoutType.Full) => {
+    try {
+        const got = expandMeasureLayout(parseMeasureLayout(code), type);
+        return JSON.stringify(got) === JSON.stringify(seq);
+    }
+    catch {
+        return false;
+    }
+};
+const classifyRepeatSections = (infos, lo, hi) => {
+    const inSpan = (idx) => idx >= lo && idx <= hi;
+    const repeatEnds = infos.filter(i => i.repeatEnd && inSpan(i.index)).map(i => i.index).sort((a, b) => a - b);
+    const repeatStarts = infos.filter(i => i.repeatStart && inSpan(i.index)).map(i => i.index).sort((a, b) => a - b);
+    const endingStops = infos.filter(i => i.endingStop !== undefined && inSpan(i.index)).map(i => i.index).sort((a, b) => a - b);
+    if (repeatEnds.length === 0) {
+        return [{ lo, hi, startIdx: lo, times: 1, endingStarts: [], spurious: false }];
+    }
+    const sections = [];
+    let prevHi = lo - 1;
+    for (const e of repeatEnds) {
+        if (e <= prevHi)
+            continue;
+        const sectionLo = prevHi + 1;
+        const nextStart = repeatStarts.find(s => s > e);
+        const sectionEndingStarts = infos
+            .filter(i => i.endingStart !== undefined && i.index >= sectionLo && (nextStart === undefined || i.index < nextStart) && inSpan(i.index))
+            .map(i => i.index)
+            .sort((a, b) => a - b);
+        let sectionHi;
+        if (repeatEnds.length === 1)
+            sectionHi = hi;
+        else if (sectionEndingStarts.length) {
+            const lastStart = sectionEndingStarts[sectionEndingStarts.length - 1];
+            const stop = endingStops.find(s => s >= lastStart);
+            sectionHi = stop ?? lastStart;
+        }
+        else
+            sectionHi = e;
+        const explicitStartInSection = repeatStarts.some(s => s >= sectionLo && s <= e);
+        const implicitFromStart = sectionLo === lo && lo === 1;
+        const spurious = sectionEndingStarts.length === 0 && !explicitStartInSection && !implicitFromStart;
+        const startIdx = repeatStarts.filter(s => s >= sectionLo && s <= e).sort((a, b) => b - a)[0] ?? sectionLo;
+        const endInfo = infos.find(i => i.index === e);
+        sections.push({ lo: sectionLo, hi: sectionHi, startIdx, endIdx: e, times: endInfo?.repeatTimes ?? 2, endingStarts: sectionEndingStarts, spurious });
+        prevHi = sectionHi;
+    }
+    if (prevHi < hi)
+        sections.push({ lo: prevHi + 1, hi, startIdx: prevHi + 1, times: 1, endingStarts: [], spurious: false });
+    return sections;
+};
+const findSectionForIndex = (sections, idx) => sections.find(s => idx >= s.lo && idx <= s.hi);
+const endingSpansForSection = (infos, section) => {
+    const spans = [];
+    for (let e = 0; e < section.endingStarts.length; e++) {
+        const start = section.endingStarts[e];
+        const nextStart = section.endingStarts[e + 1];
+        let stop;
+        if (nextStart !== undefined)
+            stop = nextStart - 1;
+        else {
+            const stopInfo = infos.find(info => info.index >= start && info.index <= section.hi && info.endingStop !== undefined);
+            stop = stopInfo ? stopInfo.index : start;
+        }
+        const number = infos.find(info => info.index === start)?.endingStart ?? e + 1;
+        spans.push({ number, start, stop });
+    }
+    return spans;
+};
 // Render the repeat/volta structure over measures [lo..hi] (no navigation),
 // or null if it isn't a single clean repeat/volta span. Shared by the plain
 // path and the da-capo ABA wrapper.
@@ -220,62 +326,39 @@ const renderRepeatSpan = (infos, lo, hi) => {
 // Used both for the whole piece (lo=1, hi=total) and recursively for the A / B
 // halves of a da-capo ABA.
 const renderRepeatSections = (infos, lo, hi) => {
-    const inSpan = (idx) => idx >= lo && idx <= hi;
-    const repeatEnds = infos.filter(i => i.repeatEnd && inSpan(i.index)).map(i => i.index).sort((a, b) => a - b);
-    const repeatStarts = infos.filter(i => i.repeatStart && inSpan(i.index)).map(i => i.index).sort((a, b) => a - b);
-    if (repeatEnds.length <= 1)
-        return renderRepeatSpan(infos, lo, hi);
-    const endingStops = infos.filter(i => i.endingStop !== undefined && inSpan(i.index)).map(i => i.index);
+    const sections = classifyRepeatSections(infos, lo, hi);
     const parts = [];
-    let prevHi = lo - 1;
-    for (const e of repeatEnds) {
-        const sectionLo = prevHi + 1;
-        // The next section's repeat-start bounds this section's voltas (2nd/3rd
-        // endings sit AFTER the repeat-end but BEFORE the next section starts).
-        const nextStart = repeatStarts.find(s => s > e);
-        const sectionEndingStarts = infos
-            .filter(i => i.endingStart !== undefined && i.index >= sectionLo && (nextStart === undefined || i.index < nextStart) && inSpan(i.index))
-            .map(i => i.index)
-            .sort((a, b) => a - b);
-        let sectionHi;
-        if (sectionEndingStarts.length) {
-            const lastStart = sectionEndingStarts[sectionEndingStarts.length - 1];
-            // the last ending's stop closes the section; else the ending start itself
-            const stop = endingStops.filter(s => s >= lastStart).sort((a, b) => a - b)[0];
-            sectionHi = stop ?? lastStart;
+    for (const section of sections) {
+        if (section.spurious) {
+            parts.push(rangeCode(section.lo, section.hi));
+            continue;
         }
-        else
-            sectionHi = e;
-        const code = renderRepeatSpan(infos, sectionLo, sectionHi);
+        const code = renderRepeatSpan(infos, section.lo, section.hi);
         if (code === null)
             return null;
         parts.push(code);
-        prevHi = sectionHi;
     }
-    // trailing non-repeated tail
-    if (prevHi < hi)
-        parts.push(rangeCode(prevHi + 1, hi));
     return parts.join(", ");
 };
-const tryStructured = (infos, total) => {
+const tryStructured = (infos, total, performed) => {
     const dacapo = infos.find(i => i.dacapo);
     const dalsegno = infos.some(i => i.dalsegno);
     const tocoda = infos.some(i => i.tocoda);
-    // D.C. (da capo → return to measure 1) over an inner repeat/volta maps cleanly
-    // to ABA <main, rest>: the trailing A' re-expansion uses LayoutType.Once (body
-    // once + the LAST alternate), which is exactly the "over-volta" convention —
-    // on the da-capo pass internal volta repeats are dropped, only the final
-    // pass-through plays, stopping at Fine. D.S. (segno ≠ measure 1) and To-Coda
-    // truncation can't be expressed this way → flat fallback.
-    if (dacapo && !dalsegno && !tocoda) {
-        // D.C. over a volta → ABA <main, rest>; Once re-expansion gives the
-        // over-volta replay (body + last ending, no inner repeat). Plain D.C. al
-        // Fine without a volta can't bound A' at an arbitrary Fine → flat fallback.
-        return buildDaCapoABA(infos, dacapo.index);
+    // D.C. / D.S. jumps that replay from the start can use the ABA form. A real
+    // Segno (not measure 1) and To-Coda still fall back to flat because the DSL has
+    // no "replay from arbitrary middle marker" construct. Bare Fine/Segno/Coda marks
+    // without a jump are visual landmarks only; they must not block repeat structuring.
+    const hasExplicitSegno = infos.some(i => i.segno);
+    if (!tocoda && dacapo)
+        return buildDaCapoABA(infos, dacapo.index, performed);
+    if (!tocoda && dalsegno && !hasExplicitSegno) {
+        const ds = infos.find(i => i.dalsegno);
+        if (ds)
+            return buildDaCapoABA(infos, ds.index, performed);
     }
-    if (dalsegno || tocoda || infos.some(i => i.fine || i.segno || i.coda))
+    if (dalsegno || tocoda)
         return null;
-    // No navigation: one or more plain repeat/volta sections in sequence. Most
+    // No playback-changing navigation: one or more plain repeat/volta sections in sequence. Most
     // real pieces (AABB minuets, sonata exposition+recap) have ≥2 repeat sections;
     // render each independently and join with commas.
     return renderRepeatSections(infos, 1, total);
@@ -289,7 +372,7 @@ const tryStructured = (infos, total) => {
 // via renderRepeatSections. Returns null when the shape doesn't fit (no Fine to
 // bound A, or no rest tail) → caller uses the flat fallback. The end-of-build
 // re-expand check still validates the result against the simulated order.
-const buildDaCapoABA = (infos, dcIdx) => {
+const buildDaCapoABA = (infos, dcIdx, performed) => {
     const fineIdx = infos.find(i => i.fine)?.index;
     if (fineIdx === undefined) {
         // No explicit Fine: fall back to the legacy single-volta ABA shape, where
@@ -297,14 +380,12 @@ const buildDaCapoABA = (infos, dcIdx) => {
         return buildDaCapoABALegacy(infos, dcIdx);
     }
     if (fineIdx >= dcIdx)
-        return null; // Fine must precede the D.C. tail
+        return null; // Fine must precede the D.C./D.S. tail
     const restLo = fineIdx + 1;
-    if (restLo > dcIdx)
-        return null; // no B section
     const mainCode = renderRepeatSections(infos, 1, fineIdx);
-    const restCode = renderRepeatSections(infos, restLo, dcIdx);
+    const restCode = restLo > dcIdx ? "" : renderRepeatSections(infos, restLo, dcIdx);
     if (mainCode === null || restCode === null)
-        return null;
+        return buildDaCapoABAFromReplay(infos, dcIdx, fineIdx, performed);
     // `main` is parsed by the ABA grammar as ONE item (parseItem). It needs wrapping
     // in [..] when it is a comma sequence ("1, 2*[..]") or a BARE range ("1..37",
     // which parseItem stops at the first number). A lone number, or a single
@@ -314,7 +395,39 @@ const buildDaCapoABA = (infos, dcIdx) => {
     const isSingleToken = /^\d+$/.test(mainCode) || /^\d+\*\[/.test(mainCode) || /^\[/.test(mainCode);
     const main = isSingleToken ? mainCode : `[${mainCode}]`;
     const rest = /,/.test(restCode) ? `[${restCode}]` : restCode;
-    return `<${main}, ${rest}>`;
+    const candidate = `<${main}, ${rest}>`;
+    return layoutExpandsTo(candidate, performed) ? candidate : buildDaCapoABAFromReplay(infos, dcIdx, fineIdx, performed);
+};
+const wrapAbaMain = (code) => /^\d+$/.test(code) || /^\d+\*\[/.test(code) || /^\[/.test(code) ? code : `[${code}]`;
+const wrapAbaRest = (code) => code === "" ? "" : (/,/.test(code) ? `[${code}]` : code);
+const buildDaCapoABAFromReplay = (infos, dcIdx, fineIdx, performed) => {
+    // Some ABC/MusicXML D.C. exports place repeat-end/start boundaries so the
+    // notated pre-Fine span (1..Fine) is not enough to render main via source flags,
+    // even though the simulated order is a clean ABA: A(full) B A(once). Detect that
+    // shape from the final da-capo replay, then reuse the section renderer for the
+    // longer A candidate and derive B from the performed middle slice.
+    for (let k = Math.min(fineIdx, performed.length - 1); k >= 1; k--) {
+        const replay = Array.from({ length: k }, (_, i) => i + 1);
+        if (JSON.stringify(performed.slice(-k)) !== JSON.stringify(replay))
+            continue;
+        for (let mainHi = k; mainHi < dcIdx; mainHi++) {
+            const mainCode = renderRepeatSections(infos, 1, mainHi);
+            if (mainCode === null)
+                continue;
+            const mainFull = expandMeasureLayout(parseMeasureLayout(mainCode));
+            const mainOnce = expandMeasureLayout(parseMeasureLayout(mainCode), LayoutType.Once);
+            if (JSON.stringify(mainOnce) !== JSON.stringify(replay))
+                continue;
+            if (JSON.stringify(performed.slice(0, mainFull.length)) !== JSON.stringify(mainFull))
+                continue;
+            const restSeq = performed.slice(mainFull.length, performed.length - mainOnce.length);
+            const restCode = compactFlatToCode(restSeq);
+            const candidate = `<${wrapAbaMain(mainCode)}, ${wrapAbaRest(restCode)}>`;
+            if (layoutExpandsTo(candidate, performed))
+                return candidate;
+        }
+    }
+    return null;
 };
 // Legacy ABA builder for D.C. WITHOUT an explicit Fine: main = the single
 // volta/repeat structure before the D.C., rest = the post-volta tail. Kept for
@@ -348,10 +461,9 @@ const buildDaCapoABALegacy = (infos, dcIdx) => {
     const voltaCode = `${times}*[${rangeCode(startIdx, bodyEnd)}]{${altCode}}`;
     const pre = startIdx > 1 ? rangeCode(1, startIdx - 1) + ", " : "";
     const main = pre ? `[${pre}${voltaCode}]` : voltaCode;
-    // rest = the tail from after the last ending to the D.C. measure
-    if (lastStop >= dcIdx)
-        return null; // no tail to form the ABA "rest"
-    const rest = rangeCode(lastStop + 1, dcIdx);
+    // rest = the tail from after the last ending to the D.C. measure. It may be
+    // empty when the navigation jump follows immediately after the main repeat.
+    const rest = lastStop >= dcIdx ? "" : rangeCode(lastStop + 1, dcIdx);
     return `<${main}, ${rest}>`;
 };
 /**
@@ -370,7 +482,7 @@ export const buildMeasureLayout = (infos, totalMeasures) => {
     // No actual unfolding happened (e.g. a lone start-repeat with no end): skip.
     if (performed.length === totalMeasures && performed.every((v, k) => v === k + 1))
         return undefined;
-    const structured = tryStructured(infos, totalMeasures);
+    const structured = tryStructured(infos, totalMeasures, performed);
     if (structured) {
         // Trust the structured form only if it reproduces the simulated order.
         try {
@@ -380,6 +492,9 @@ export const buildMeasureLayout = (infos, totalMeasures) => {
         }
         catch { /* fall through to flat */ }
     }
+    const compacted = compactFlatToCode(performed);
+    if (compacted !== flatToCode(performed) && layoutExpandsTo(compacted, performed))
+        return compacted;
     return flatToCode(performed);
 };
 // Recognize navigation semantics from a <words> string (case-insensitive).

package/lib/lilylet/meiEncoder.js

@@ -266,6 +266,42 @@ const tremoloToStemMod = (division) => {
     }
     return undefined;
 };
+const lyricWordPosition = (syllables, index) => {
+    const syllable = syllables[index];
+    if (!syllable?.text)
+        return 'u';
+    const previous = index > 0 ? syllables[index - 1] : undefined;
+    if (previous?.text && previous.hyphen)
+        return syllable.hyphen ? 'm' : 't';
+    return syllable.hyphen ? 'i' : 'u';
+};
+const lyricSyllableXml = (lane, index, indent) => {
+    const syllable = lane.syllables[index];
+    if (!syllable || syllable.skip || syllable.text === undefined)
+        return '';
+    const wordpos = lyricWordPosition(lane.syllables, index);
+    const con = syllable.extend ? 'u' : syllable.hyphen ? 'd' : undefined;
+    const attrs = ` wordpos="${wordpos}"${con ? ` con="${con}"` : ''}`;
+    return `${indent}<syl${attrs}>${escapeXml(syllable.text)}</syl>\n`;
+};
+const makeLyricCursors = (lanes, indent) => (lanes || []).map((lane) => {
+    let index = 0;
+    const consume = () => {
+        const current = index++;
+        const syllable = lane.syllables[current];
+        if (!syllable || syllable.skip || syllable.text === undefined)
+            return '';
+        const verse = lane.verse || 1;
+        return `${indent}<verse n="${verse}">\n${lyricSyllableXml(lane, current, indent + '    ')}${indent}</verse>\n`;
+    };
+    return { consume, consumeRest: () => { index++; } };
+});
+const lyricXmlForEvent = (cursors, indent) => {
+    let xml = '';
+    for (const cursor of cursors)
+        xml += cursor.consume();
+    return xml;
+};
 // Build note element
 const buildNoteElement = (pitch, dur, dots, indent, inChord, options = {}, noteId) => {
     const id = noteId || generateId('note');
@@ -295,8 +331,7 @@ const buildNoteElement = (pitch, dur, dots, indent, inChord, options = {}, noteI
         if (stemMod)
             attrs += ` stem.mod="${stemMod}"`;
     }
-    // Only artics remain as child elements; ornaments are control events
-    const hasChildren = !inChord && options.artics && options.artics.length > 0;
+    const hasChildren = !inChord && ((options.artics && options.artics.length > 0) || !!options.lyricXml);
     if (!hasChildren) {
         return `${indent}<note ${attrs} />\n`;
     }
@@ -316,6 +351,8 @@ const buildNoteElement = (pitch, dur, dots, indent, inChord, options = {}, noteI
             result += `${indent}    <artic artic="${defaultArtics.join(' ')}" />\n`;
         }
     }
+    if (options.lyricXml)
+        result += options.lyricXml;
     result += `${indent}</note>\n`;
     return result;
 };
@@ -466,7 +503,7 @@ const extractMarkOptions = (marks) => {
     return result;
 };
 // Convert NoteEvent to MEI
-const noteEventToMEI = (event, indent, layerStaff, tieEnd, contextStemDir, keyFifths = 0, ottavaShift = 0, measureAccidentals) => {
+const noteEventToMEI = (event, indent, layerStaff, tieEnd, contextStemDir, keyFifths = 0, ottavaShift = 0, measureAccidentals, lyricXml = '') => {
     const dur = DURATIONS[event.duration.division] || "4";
     const dots = event.duration.dots || 0;
     const markOptions = extractMarkOptions(event.marks);
@@ -503,7 +540,7 @@ const noteEventToMEI = (event, indent, layerStaff, tieEnd, contextStemDir, keyFi
         const pitch = encodePitch(event.pitches[0], keyFifths, ottavaShift, measureAccidentals);
         const noteId = generateId('note');
         return {
-            xml: buildNoteElement(pitch, dur, dots, indent, false, noteOptions, noteId),
+            xml: buildNoteElement(pitch, dur, dots, indent, false, { ...noteOptions, lyricXml }, noteId),
             elementId: noteId,
             hairpin: markOptions.hairpin,
             pedal: markOptions.pedal,
@@ -565,6 +602,8 @@ const noteEventToMEI = (event, indent, layerStaff, tieEnd, contextStemDir, keyFi
             result += `${indent}    <artic artic="${defaultArtics.join(' ')}" />\n`;
         }
     }
+    if (lyricXml)
+        result += lyricXml;
     result += `${indent}</chord>\n`;
     return {
         xml: result,
@@ -642,7 +681,7 @@ const tupletHasInternalBeams = (event) => {
     return starts > 0 && starts === ends;
 };
 // Convert TupletEvent to MEI
-const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff, ottavaShift = 0, inParentBeam = false, measureAccidentals, currentClef) => {
+const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff, ottavaShift = 0, inParentBeam = false, measureAccidentals, currentClef, lyricCursors = []) => {
     // LilyPond \times 2/3 means "multiply duration by 2/3"
     // So 3 notes × 2/3 = 2 beats worth (3 in time of 2)
     // MEI: num = number of notes written, numbase = normal equivalent
@@ -685,7 +724,8 @@ const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff
             const effectiveNoteEvent = effectiveStaff && layerStaff && effectiveStaff !== layerStaff
                 ? { ...noteEvent, staff: effectiveStaff }
                 : noteEvent;
-            const result = noteEventToMEI(effectiveNoteEvent, noteIndent, layerStaff, false, undefined, keyFifths, ottavaShift, measureAccidentals);
+            const lyricXml = lyricCursors.length ? lyricXmlForEvent(lyricCursors, noteIndent + '    ') : '';
+            const result = noteEventToMEI(effectiveNoteEvent, noteIndent, layerStaff, false, undefined, keyFifths, ottavaShift, measureAccidentals, lyricXml);
             xml += result.xml;
             if (!firstNoteId)
                 firstNoteId = result.elementId;
@@ -863,6 +903,7 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
     let xml = `${indent}<layer xml:id="${layerId}" n="${layerN}">\n`;
     let beamElementOpen = false; // Whether actual <beam> element is open (passed to tuplets)
     const baseIndent = indent + '    ';
+    const lyricCursors = makeLyricCursors(voice.lyrics, baseIndent);
     // Track current clef to only emit changes
     let currentClef = initialClef;
     // Track hairpin spans. Use a stack of open hairpins (not a single slot): the
@@ -1021,7 +1062,8 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 const effectiveNoteEvent = currentStaff !== voice.staff
                     ? { ...noteEvent, staff: currentStaff }
                     : noteEvent;
-                const result = noteEventToMEI(effectiveNoteEvent, currentIndent, voice.staff, tieEnd, currentStemDirection, keyFifths, currentOttavaShift, measureAccidentals);
+                const eventLyricXml = isGraceNote ? '' : lyricXmlForEvent(lyricCursors, currentIndent + '    ');
+                const result = noteEventToMEI(effectiveNoteEvent, currentIndent, voice.staff, tieEnd, currentStemDirection, keyFifths, currentOttavaShift, measureAccidentals, eventLyricXml);
                 xml += result.xml;
                 lastNoteId = result.elementId;
                 extendOttavaEnd(result.elementId);
@@ -1166,7 +1208,7 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 // Pass beamElementOpen to tuplet so it knows not to create its own beam
                 // A pending ottava shift applies to the tuplet's notes' written octave.
                 applyPendingOttavaShift();
-                const tupletResult = tupletEventToMEI(event, currentIndent, voice.staff, keyFifths, currentStaff, currentOttavaShift, beamElementOpen, measureAccidentals, currentClef);
+                const tupletResult = tupletEventToMEI(event, currentIndent, voice.staff, keyFifths, currentStaff, currentOttavaShift, beamElementOpen, measureAccidentals, currentClef, lyricCursors);
                 xml += tupletResult.xml;
                 // An ottava span can open on, run through, or close at a tuplet (common
                 // in etudes where the 8va covers a whole tuplet run). Anchor the span on

package/lib/lilylet/onsets.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Note-onset extraction from a parsed Lilylet document.
+ *
+ * Walks measures -> parts -> voices -> events, accumulating each note's ONSET (position
+ * within its measure, in duration units of RES=480 per quarter) and its SOUNDING
+ * MIDI pitch. Sounding pitch honors octave-/interval-transposing clefs ("treble_8" sounds
+ * an octave lower than written, etc.), tracked per voice and PERSISTED across measures.
+ *
+ * Shared by tools/astServer.ts (the HTTP onset API) and the clef-onset unit test.
+ */
+/**
+ * The written->sounding semitone shift a clef string declares. Per the LilyPond convention a
+ * "_N"/"^N" suffix transposes DOWN/UP by the diatonic interval N: "treble_8" = octave down
+ * (-12), "treble^8" = +12, "treble_15" = two octaves down (-24), "treble_5" = fifth down (-7).
+ * A plain clef (no suffix) declares 0.
+ */
+export declare const clefShift: (clefStr: string) => number;
+/**
+ * Sounding MIDI pitch of a resolved (absolute-octave) Lilylet pitch. Octave 0 = middle-C
+ * octave = MIDI 60 (see parser.resolveRelativePitch). `shift` is the active clef's
+ * written->sounding semitone transposition.
+ */
+export declare const pitchToMidi: (pitch: any, shift?: number) => number;
+export interface NoteOnset {
+    onset: number;
+    onsetNorm: number;
+    durationDiv: number;
+    midi: number[];
+    staff: number;
+    voice: number;
+    grace: boolean;
+}
+export interface MeasureOnsets {
+    index: number;
+    timeSig: {
+        numerator: number;
+        denominator: number;
+    } | null;
+    measureDivisions: number;
+    notes: NoteOnset[];
+}
+/**
+ * Per-measure note onsets for a parsed LilyletDoc. The active clef transposition is tracked
+ * per (positional) voice index and PERSISTS across measures — a \clef stays in force until the
+ * next one, so a "treble_8" set in measure 1 still lowers measure 2 by an octave.
+ *
+ * Measure length (`measureDivisions`, used to normalize onsets to [0,1)) comes from the time
+ * signature for a full bar, but an INCOMPLETE bar carrying a `\partial` (a pickup, or a bar
+ * split by a repeat barline) is only as long as its `\partial` value. Honoring `\partial` makes
+ * the lilylet bar length match the corresponding MIDI measure's tick span (MuseScore emits a
+ * short 1/8 or 3/8 measure for exactly these), so the two onset grids align.
+ */
+export declare const measureOnsets: (doc: any) => MeasureOnsets[];