@k-l-lambda/lilylet 0.1.81 → 0.1.82

package/source/lilylet/measureLayoutFromXml.ts

@@ -20,7 +20,7 @@
  * always-valid fallback.
  */
 
-import { parseMeasureLayout, expandMeasureLayout } from "./measureLayout";
+import { parseMeasureLayout, expandMeasureLayout, LayoutType } from "./measureLayout";
 import { getDirectChildren, getAttribute } from "./musicXmlUtils";
 
 // One decoded measure's repeat-relevant markup, in source order.
@@ -79,15 +79,9 @@ const simulate = (infos: MeasureRepeatInfo[]): number[] => {
 	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: number): number | undefined =>
-		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: number[] = [];
 	const passCount = new Map<number, number>();   // forward-repeat start index → completed passes
@@ -108,12 +102,14 @@ const simulate = (infos: MeasureRepeatInfo[]): number[] => {
 		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; continue;
+				i = section ? section.hi + 1 : i + 1;
+				continue;
 			}
 		}
 
@@ -125,7 +121,10 @@ const simulate = (infos: MeasureRepeatInfo[]): number[] => {
 		// 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;
@@ -133,7 +132,10 @@ const simulate = (infos: MeasureRepeatInfo[]): number[] => {
 			passCount.set(start, done);
 			if (done < times) { i = start; 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
@@ -157,6 +159,119 @@ const simulate = (infos: MeasureRepeatInfo[]): number[] => {
 
 const rangeCode = (a: number, b: number): string => a === b ? `${a}` : flatToCode(Array.from({ length: b - a + 1 }, (_, k) => a + k));
 
+const isAscendingRun = (seq: number[]): boolean => seq.every((v, i) => i === 0 || v === seq[i - 1] + 1);
+
+const compactFlatToCode = (seq: number[]): string => {
+	const parts: string[] = [];
+	let plain: number[] = [];
+	const flushPlain = (): void => {
+		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: string, seq: number[], type: LayoutType = LayoutType.Full): boolean => {
+	try {
+		const got = expandMeasureLayout(parseMeasureLayout(code), type);
+		return JSON.stringify(got) === JSON.stringify(seq);
+	} catch { return false; }
+};
+
+interface RepeatSection {
+	lo: number;
+	hi: number;
+	startIdx: number;
+	endIdx?: number;
+	times: number;
+	endingStarts: number[];
+	spurious: boolean;
+}
+
+const classifyRepeatSections = (infos: MeasureRepeatInfo[], lo: number, hi: number): RepeatSection[] => {
+	const inSpan = (idx: number): boolean => 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: RepeatSection[] = [];
+	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: number;
+		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: RepeatSection[], idx: number): RepeatSection | undefined =>
+	sections.find(s => idx >= s.lo && idx <= s.hi);
+
+const endingSpansForSection = (infos: MeasureRepeatInfo[], section: RepeatSection): Array<{ number: number; start: number; stop: number }> => {
+	const spans: Array<{ number: number; start: number; stop: number }> = [];
+	for (let e = 0; e < section.endingStarts.length; e++) {
+		const start = section.endingStarts[e];
+		const nextStart = section.endingStarts[e + 1];
+		let stop: number;
+		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.
@@ -229,64 +344,38 @@ const renderRepeatSpan = (infos: MeasureRepeatInfo[], lo: number, hi: number): s
 // 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: MeasureRepeatInfo[], lo: number, hi: number): string | null => {
-	const inSpan = (idx: number) => 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: string[] = [];
-	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: number;
-		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: MeasureRepeatInfo[], total: number): string | null => {
+const tryStructured = (infos: MeasureRepeatInfo[], total: number, performed: number[]): string | null => {
 	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)) return null;
+	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);
@@ -301,20 +390,19 @@ const tryStructured = (infos: MeasureRepeatInfo[], total: number): string | null
 // 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: MeasureRepeatInfo[], dcIdx: number): string | null => {
+const buildDaCapoABA = (infos: MeasureRepeatInfo[], dcIdx: number, performed: number[]): string | null => {
 	const fineIdx = infos.find(i => i.fine)?.index;
 	if (fineIdx === undefined) {
 		// No explicit Fine: fall back to the legacy single-volta ABA shape, where
 		// A ends at the last pre-D.C. ending and B is the tail to the D.C. measure.
 		return buildDaCapoABALegacy(infos, dcIdx);
 	}
-	if (fineIdx >= dcIdx) return null;          // Fine must precede the D.C. tail
+	if (fineIdx >= dcIdx) 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);
-	if (mainCode === null || restCode === null) return null;
+	const restCode = restLo > dcIdx ? "" : renderRepeatSections(infos, restLo, dcIdx);
+	if (mainCode === null || restCode === 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",
@@ -325,7 +413,38 @@ const buildDaCapoABA = (infos: MeasureRepeatInfo[], dcIdx: number): string | nul
 	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: string): string => /^\d+$/.test(code) || /^\d+\*\[/.test(code) || /^\[/.test(code) ? code : `[${code}]`;
+const wrapAbaRest = (code: string): string => code === "" ? "" : (/,/.test(code) ? `[${code}]` : code);
+
+const buildDaCapoABAFromReplay = (infos: MeasureRepeatInfo[], dcIdx: number, fineIdx: number, performed: number[]): string | null => {
+	// 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
@@ -359,9 +478,9 @@ const buildDaCapoABALegacy = (infos: MeasureRepeatInfo[], dcIdx: number): string
 
 	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}>`;
 };
 
@@ -382,7 +501,7 @@ export const buildMeasureLayout = (infos: MeasureRepeatInfo[], totalMeasures: nu
 	// 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 {
@@ -390,6 +509,8 @@ export const buildMeasureLayout = (infos: MeasureRepeatInfo[], totalMeasures: nu
 			if (JSON.stringify(got) === JSON.stringify(performed)) return structured;
 		} catch { /* fall through to flat */ }
 	}
+	const compacted = compactFlatToCode(performed);
+	if (compacted !== flatToCode(performed) && layoutExpandsTo(compacted, performed)) return compacted;
 	return flatToCode(performed);
 };
 

package/source/lilylet/onsets.ts

@@ -0,0 +1,158 @@
+/**
+ * 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.
+ */
+
+import { calculateDuration } from "./musicXmlUtils";
+import { Accidental } from "./types";
+
+// Onset resolution in ticks per quarter note. calculateDuration() rounds its result to an
+// integer, so it must run at a resolution fine enough to represent every note value exactly:
+// the shared DIVISIONS=4 (MusicXML export) rounds a 32nd (0.5) and a dotted 16th (1.5) to
+// integers, drifting the onset cursor. 480 is divisible by all common note/dot/tuplet values,
+// so durations stay exact. Onsets are reported in these units and also normalized per measure.
+const RES = 480;
+
+const PHONET_SEMITONE: Record<string, number> = { c: 0, d: 2, e: 4, f: 5, g: 7, a: 9, b: 11 };
+const ACCIDENTAL_SEMITONE: Record<string, number> = {
+	[Accidental.natural]: 0, [Accidental.sharp]: 1, [Accidental.flat]: -1,
+	[Accidental.doubleSharp]: 2, [Accidental.doubleFlat]: -2,
+};
+
+// Diatonic-step -> semitones within an octave (unison..seventh), for "_N"/"^N" clef suffixes.
+const DIATONIC_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
+
+/**
+ * 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 const clefShift = (clefStr: string): number => {
+	const m = /^.*?([_^])(\d+)$/.exec(clefStr || "");
+	if (!m) return 0;
+	const k = parseInt(m[2], 10) - 1;					// diatonic steps above unison
+	const semis = DIATONIC_SEMITONES[k % 7] + 12 * Math.floor(k / 7);
+	return (m[1] === "^" ? 1 : -1) * semis;
+};
+
+/**
+ * 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 const pitchToMidi = (pitch: any, shift = 0): number => {
+	const semi = PHONET_SEMITONE[pitch.phonet] ?? 0;
+	const acc = pitch.accidental ? (ACCIDENTAL_SEMITONE[pitch.accidental] ?? 0) : 0;
+	return 60 + (pitch.octave || 0) * 12 + semi + acc + shift;
+};
+
+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[];
+}
+
+// Walk a voice's events, accumulating onset in duration units. Tuplet/times scale their inner
+// durations by ratio (num/den). Grace notes take no time. `clefRef.shift` is the active clef's
+// written->sounding shift, updated by \clef contextChanges (persisted by the caller across
+// measures). Returns the total consumed duration (the voice's played length).
+const walkVoice = (events: any[], staff: number, voice: number,
+	scale: number, startCursor: number, clefRef: { shift: number }, out: NoteOnset[]): number => {
+	let cursor = startCursor;
+	for (const ev of events) {
+		if (ev.type === "context" && typeof ev.clef === "string") {
+			clefRef.shift = clefShift(ev.clef);
+		}
+		else if (ev.type === "note") {
+			const dur = calculateDuration(ev.duration, RES) * scale;
+			const midi = (ev.pitches || []).map((p: any) => pitchToMidi(p, clefRef.shift));
+			if (ev.grace) {
+				out.push({ onset: cursor, onsetNorm: 0, durationDiv: 0, midi, staff: ev.staff ?? staff, voice, grace: true });
+				continue; // grace steals no measure time
+			}
+			out.push({ onset: cursor, onsetNorm: 0, durationDiv: dur, midi, staff: ev.staff ?? staff, voice, grace: false });
+			cursor += dur;
+		}
+		else if (ev.type === "rest") {
+			cursor += calculateDuration(ev.duration, RES) * scale;
+		}
+		else if (ev.type === "tuplet" || ev.type === "times") {
+			const r = ev.ratio || { numerator: 1, denominator: 1 };
+			cursor = walkVoice(ev.events || [], staff, voice, scale * (r.numerator / r.denominator), cursor, clefRef, out);
+		}
+		else if (ev.type === "tremolo") {
+			const each = (RES * 4 / ev.division) * scale;
+			out.push({ onset: cursor, onsetNorm: 0, durationDiv: each,
+				midi: (ev.pitchA || []).map((p: any) => pitchToMidi(p, clefRef.shift)), staff, voice, grace: false });
+			cursor += each;
+			out.push({ onset: cursor, onsetNorm: 0, durationDiv: each,
+				midi: (ev.pitchB || []).map((p: any) => pitchToMidi(p, clefRef.shift)), staff, voice, grace: false });
+			cursor += each;
+		}
+		// barline / markup / dynamic / harmony / pitchReset: no time
+	}
+	return cursor;
+};
+
+/**
+ * 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 const measureOnsets = (doc: any): MeasureOnsets[] => {
+	let curTime: any = null;
+	const clefByVoice: { shift: number }[] = [];
+	return (doc.measures || []).map((m: any, mi: number): MeasureOnsets => {
+		if (m.timeSig) curTime = m.timeSig;
+		const notes: NoteOnset[] = [];
+		let maxCursor = 0;
+		let vIndex = 0;
+		// a \partial anywhere in the measure (any voice's leading contextChange) shortens the bar.
+		let partial: any = null;
+		for (const part of m.parts || []) {
+			for (const voice of part.voices || []) {
+				if (!clefByVoice[vIndex]) clefByVoice[vIndex] = { shift: 0 };
+				for (const ev of voice.events || []) {
+					if (ev.type === "context" && ev.partial) { partial = ev.partial; break; }
+					if (ev.type === "note" || ev.type === "rest" || ev.type === "tuplet"
+						|| ev.type === "times" || ev.type === "tremolo") break;	// partial must precede notes
+				}
+				const end = walkVoice(voice.events || [], voice.staff ?? 1, vIndex, 1, 0, clefByVoice[vIndex], notes);
+				maxCursor = Math.max(maxCursor, end);
+				vIndex += 1;
+			}
+		}
+		// bar length: \partial value if the bar is incomplete, else the full time-signature bar,
+		// else (no time sig) the longest voice cursor.
+		const fullBar = curTime ? RES * 4 * curTime.numerator / curTime.denominator : maxCursor;
+		const barDiv = partial ? calculateDuration(partial, RES) : fullBar;
+		const span = barDiv > 0 ? barDiv : (maxCursor > 0 ? maxCursor : 1);
+		for (const n of notes)
+			n.onsetNorm = n.onset / span;
+		return {
+			index: mi + 1,
+			timeSig: curTime ? { numerator: curTime.numerator, denominator: curTime.denominator } : null,
+			measureDivisions: span,
+			notes,
+		};
+	});
+};