@k-l-lambda/lilylet 0.1.80 → 0.1.82

package/lib/lilylet/abcDecoder.js

@@ -189,6 +189,70 @@ const convertDuration = (abcDuration, unitLength) => {
     const log2 = Math.round(Math.log2(division));
     return { division: Math.pow(2, Math.max(0, log2)), dots: 0 };
 };
+// A whole note is WHOLE_TICKS ticks. 2^7·3^3·5·7 = 120960 divides by every dot (·3/2, ·7/4),
+// tuplet (÷3, ÷5, ÷7), and common division, so a voice's played length is an exact integer —
+// no float rounding when we compare it to the bar length (unlike calculateDuration's Math.round).
+const WHOLE_TICKS = 120960;
+// A resolved Duration's tick length (dots + optional lilylet tuplet ratio num/den applied).
+const durationTicks = (d) => {
+    let t = WHOLE_TICKS / d.division;
+    if (d.dots) {
+        let dot = t / 2;
+        for (let i = 0; i < d.dots; i++) {
+            t += dot;
+            dot /= 2;
+        }
+    }
+    if (d.tuplet)
+        t = t * d.tuplet.numerator / d.tuplet.denominator;
+    return t;
+};
+// Sum the played tick length of an event list. Context / barline / markup / dynamic events
+// take no time, and GRACE notes steal none (they carry a nominal duration but do not advance
+// the beat). A tuplet/times group scales its inner notes by ratio num/den (e.g. \tuplet 3/2 of
+// eighths = a quarter). This mirrors the parser's own \partial check so the emitted \partial
+// never trips a partial-mismatch warning. Used to measure a voice against its bar length.
+const eventsTicks = (events) => {
+    let total = 0;
+    for (const ev of events) {
+        if (ev.type === "note" || ev.type === "rest") {
+            if (ev.grace)
+                continue;
+            total += durationTicks(ev.duration);
+        }
+        else if (ev.type === "tuplet" || ev.type === "times") {
+            const t = ev;
+            const factor = t.ratio ? t.ratio.numerator / t.ratio.denominator : 1;
+            for (const inner of t.events || []) {
+                if ((inner.type === "note" || inner.type === "rest") && !inner.grace)
+                    total += durationTicks(inner.duration) * factor;
+            }
+        }
+        else if (ev.type === "tremolo") {
+            const tr = ev;
+            total += 2 * (WHOLE_TICKS / tr.division);
+        }
+    }
+    return total;
+};
+// Build a \partial Duration (single {division, dots}) for a pickup of `ticks` whole-note ticks.
+// LilyPond's \partial takes one duration token, so only power-of-2 divisions with up to 2 dots
+// are expressible; a length that isn't (e.g. a 5/8 pickup) returns null and no \partial is added
+// (the bar simply renders short) rather than emitting a wrong duration.
+const ticksToPartialDuration = (ticks) => {
+    if (ticks <= 0)
+        return null;
+    for (let division = 1; division <= 128; division *= 2) {
+        const base = WHOLE_TICKS / division;
+        if (ticks === base)
+            return { division, dots: 0 };
+        if (ticks === base * 1.5)
+            return { division, dots: 1 };
+        if (ticks === base * 1.75)
+            return { division, dots: 2 };
+    }
+    return null;
+};
 /**
  * Apply broken rhythm adjustment.
  * broken > 0 (A>B): current note gets dotted, next gets halved
@@ -492,6 +556,12 @@ const collectAbcRepeatInfo = (bars) => {
         // ("|:" forward, ":|:"/"::"/":||:" end-and-start).
         const startsNext = trailBar.includes("|:") || isEndStart;
         if (startsNext && idx < n) {
+            // A new repeat section opening here also CLOSES any still-open ending
+            // (a volta cannot span into the next repeat section). abc2xml back-patches
+            // the ending-stop onto this measure; without this a final volta (e.g.
+            // ":|2 …|:") would overshoot to the next volta/section bar far ahead.
+            if (openEndingStart >= 1 && openEndingStart <= idx)
+                closeOpenEnding(idx);
             infos[idx].repeatStart = true;
         }
         // A trailing volta digit ("|2", ":|1,2") opens an ending on the NEXT measure.
@@ -660,6 +730,13 @@ const abcLayoutToStaves = (layout) => {
  * `voiceInstr` maps an ABC voice number to its {name, shortName}. The layout's staff ids
  * are arc-first voice numbers, so a staff id "5" looks up voice 5's name.
  */
+// ABC quoted strings carry literal escape sequences (e.g. `nm="Violin\nsolo"` is the 11
+// characters V-i-o-l-i-n-\-n-s-o-l-o). The lilylet doc model holds DECODED strings — the
+// serializer's escapeString re-encodes a real newline back to `\n`. Without decoding here,
+// the stored backslash would be escaped a second time (`\n` → `\\n`). Mirror the lilylet
+// grammar's `unq` unescape table so both import paths agree.
+const ABC_UNESCAPE = { n: "\n", r: "\r", t: "\t", '"': '"', "\\": "\\" };
+const unescapeAbcString = (s) => s.replace(/\\(.)/g, (m, c) => (c in ABC_UNESCAPE ? ABC_UNESCAPE[c] : m));
 const abcInstrumentsToLilylet = (stavesCode, voiceInstr) => {
     const layout = parseStaffLayout(stavesCode);
     const result = {};
@@ -1339,8 +1416,8 @@ const decodeTune = (tune, options = {}) => {
                     continue;
                 const short = props.snm ?? props.sname;
                 voiceInstr.set(v, typeof short === "string" && short.length
-                    ? { name, shortName: short }
-                    : { name });
+                    ? { name: unescapeAbcString(name), shortName: unescapeAbcString(short) }
+                    : { name: unescapeAbcString(name) });
             }
             if (voiceInstr.size > 0) {
                 const instruments = abcInstrumentsToLilylet(metadata.staves, voiceInstr);
@@ -1369,6 +1446,10 @@ const decodeTune = (tune, options = {}) => {
     // index. Built alongside barInfos' navTexts; attached after each measure's
     // parts are assembled (mirrors the MusicXML path attaching nav to a note).
     const navMarksByMeasure = new Map();
+    // Running effective time signature (seeded from the header M:, updated by any inline
+    // [M:...] change). A bar whose played length is SHORTER than this gets a \partial (see
+    // the pickup/anacrusis handling below the per-measure assembly).
+    let curTime = timeSig;
     for (let mi = 0; mi < measures.length; mi++) {
         const abcMeasure = measures[mi];
         // Group patches by voice number
@@ -1561,6 +1642,66 @@ const decodeTune = (tune, options = {}) => {
                     break;
             }
         }
+        // Pickup / short bar → \partial. Update the running time signature from any inline
+        // [M:...] this bar carried (the LAST \time in the bar wins — a bar may restate then
+        // change meter, e.g. \time 3/4 \time 9/8), then compare the bar's played length (the
+        // longest voice, so a bar that is complete in ANY voice is not treated as short)
+        // against the meter's full-bar length. A strictly shorter bar is an anacrusis (bar 1)
+        // or a truncated final bar; emit \partial <bar-length> on the first voice so LilyPond
+        // renders the incomplete bar. A full-measure rest (Z/R) voice is skipped — it fills the
+        // bar by definition, so it must not drag the measured length down.
+        {
+            for (const part of parts) {
+                for (const voice of part.voices) {
+                    for (const e of voice.events) {
+                        if (e.type === "context" && e.time) {
+                            const t = e.time;
+                            curTime = { numerator: t.numerator, denominator: t.denominator };
+                        }
+                    }
+                }
+            }
+            if (curTime) {
+                const barTicks = WHOLE_TICKS * curTime.numerator / curTime.denominator;
+                // \partial is a GLOBAL timing directive — it shortens the bar for every voice at
+                // once. So it is only correct when every sounding voice has the SAME short length.
+                // Collect each voice's played ticks; a full-measure-rest (Z/R) voice fills the bar
+                // and is ignored. If the voices are ragged (different lengths — e.g. a messy meter
+                // change where some voices are 6/8 and others 8/8), no single \partial fits them
+                // all, so we emit none rather than one that mis-sizes some voices.
+                const lengths = [];
+                let anyFull = false;
+                for (const part of parts) {
+                    for (const voice of part.voices) {
+                        if (voice.events.some(e => e.type === "rest" && e.fullMeasure)) {
+                            anyFull = true;
+                            continue;
+                        }
+                        const t = eventsTicks(voice.events);
+                        if (t > 0)
+                            lengths.push(t);
+                    }
+                }
+                const uniform = lengths.length > 0 && lengths.every(t => t === lengths[0]);
+                const played = uniform ? lengths[0] : 0;
+                if (!anyFull && uniform && played < barTicks) {
+                    const partial = ticksToPartialDuration(played);
+                    if (partial) {
+                        // Insert after any leading key/time context so the emitted order is
+                        // \key … \time … \partial …  (LilyPond wants \partial after \time).
+                        const target = measure.parts[0]?.voices[0];
+                        if (target) {
+                            let at = 0;
+                            while (at < target.events.length && target.events[at].type === "context"
+                                && (target.events[at].key || target.events[at].time)
+                                && !target.events[at].clef)
+                                at++;
+                            target.events.splice(at, 0, { type: "context", partial });
+                        }
+                    }
+                }
+            }
+        }
         lilyletMeasures.push(measure);
     }
     // Add tempo to first measure's first voice if present

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.
@@ -163,7 +269,11 @@ const renderRepeatSpan = (infos, lo, hi) => {
         return rangeCode(lo, hi);
     }
     const endInfo = repeatEnds[0];
-    const startIdx = span.find(i => i.repeatStart)?.index ?? lo;
+    // The repeat-start for THIS end is the latest repeat-start at or before it; a
+    // repeat-start sitting AFTER the end (e.g. the second half of a ":|:"/"::" that
+    // opens the next section) belongs to a following span, not this one. Falling
+    // back to `lo` models the implicit "repeat from the start of the span".
+    const startIdx = span.filter(i => i.repeatStart && i.index <= endInfo.index).map(i => i.index).sort((a, b) => b - a)[0] ?? lo;
     const times = endInfo.repeatTimes ?? 2;
     const endingStarts = span.filter(i => i.endingStart !== undefined).map(i => i.index).sort((a, b) => a - b);
     if (endingStarts.length === 0) {
@@ -216,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);
@@ -285,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
@@ -293,19 +380,54 @@ 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;
-    // main wraps in [..] only when it is a comma-separated sequence (so the ABA
-    // parser reads it as one block); a single token (e.g. "2*[..]") needs no bracket.
-    const main = /,/.test(mainCode) ? `[${mainCode}]` : mainCode;
+        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
+    // already-structured token ("2*[..]" / "2*[..]{..}" / "[..]"), parses as one item
+    // and needs no extra bracket. `rest` is parsed as a sequence, so it only needs
+    // bracketing to group a comma sequence — a range there is fine.
+    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
@@ -339,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}>`;
 };
 /**
@@ -361,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 {
@@ -371,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/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[];