@k-l-lambda/lilylet 0.1.88 → 0.1.90

package/source/lilylet/abcDecoder.ts

@@ -42,6 +42,7 @@ import {
 } from "./types";
 import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
 import { MeasureRepeatInfo, buildMeasureLayout, applyNavText } from "./measureLayoutFromXml";
+import { parseClefSuffix, withClefTransposition } from "./clefTransposition";
 
 
 // ============ Constants ============
@@ -476,25 +477,32 @@ const convertClef = (clefStr: string): Clef | undefined => {
 
 /**
  * Fold an ABC voice `transpose=N` property (a written→sounding shift in
- * SEMITONES) into the Lilylet clef-suffix form `_M` / `^M`, where M is a
- * diatonic interval number. ABC carries only semitones, so the diatonic
- * interval is approximated by the nearest scale-step count
- * (steps = round(semi * 7/12), interval number = |steps| + 1); `_` lowers,
- * `^` raises. The Lilylet→MEI encoder later expands the suffix back into
- * trans.diat / trans.semi (see meiEncoder.resolveClef). This is exact when the
- * semitone count is a major/perfect interval (e.g. -2, -9, +2, ±12) and a
- * nearest-interval approximation otherwise.
+ * SEMITONES) into the Lilylet clef suffix, which the →MEI encoder later expands
+ * into trans.diat / trans.semi (see meiEncoder.resolveClef).
+ *
+ * The conversion is EXACT: clefTransposition.semitonesToClefSuffix returns the
+ * suffix for the interval that spans exactly this many semitones, using the `m`
+ * (minor) form where the major/perfect interval does not fit — so -3 becomes
+ * `_m3` rather than the nearest major third `_3`. It previously approximated with
+ * round(semi * 7/12), which put a one-semitone error on the sounding pitch of
+ * every minor-interval transposition (-3 A clarinet, -8, -10 E-flat instruments:
+ * 37% of transposing voices in the corpora checked).
+ *
+ * A semitone count with no exact suffix (only the tritone, ±6, within an octave)
+ * is dropped with a warning rather than rounded: a silent one-semitone pitch error
+ * is worse than a visibly absent transposition.
  */
 const transposeClefSuffix = (clef: Clef | undefined, semitones: number): Clef | undefined => {
 	if (!clef || !semitones) return clef;
-	// A clef that already carries an octave suffix (treble_8 etc.) is left as-is;
-	// stacking another shift on top is not meaningful for ABC sources.
-	if (/[_^]\d+$/.test(clef as string)) return clef;
-	const steps = Math.round((semitones * 7) / 12);
-	if (steps === 0) return clef;
-	const num = Math.abs(steps) + 1;
-	const suffix = (steps < 0 ? "_" : "^") + num;
-	return (clef + suffix) as Clef;
+	// A clef that already carries a transposition suffix (treble_8 etc.) is left
+	// as-is; stacking another shift on top is not meaningful for ABC sources.
+	if (parseClefSuffix(clef as string)) return clef;
+	const transposed = withClefTransposition(clef as string, semitones);
+	if (transposed === undefined) {
+		console.warn(`abcDecoder: transpose=${semitones} has no exact clef suffix; transposition dropped for clef "${clef}"`);
+		return clef;
+	}
+	return transposed as Clef;
 };
 
 /**
@@ -1599,6 +1607,15 @@ const decodeTune = (tune: ABC.Tune, options: DecodeOptions = {}): LilyletDoc =>
 	// the pickup/anacrusis handling below the per-measure assembly).
 	let curTime: TimeSig | undefined = timeSig;
 
+	// ABC voice numbers whose declared clef has already been emitted. A voice gets its
+	// clef on the measure where it FIRST carries music, which is not always measure 0:
+	// a header field the grammar does not consume (e.g. `I:percmap`) degenerates into a
+	// phantom measure 0 holding a single patch with no voice number, and the emission
+	// was previously gated on `mi === 0`, so every real voice lost its clef — and with
+	// it its transposition. Keying on the voice number instead of the measure index
+	// makes the emission independent of what measure 0 happens to contain.
+	const emittedClefVoices = new Set<number>();
+
 	for (let mi = 0; mi < measures.length; mi++) {
 		const abcMeasure = measures[mi];
 
@@ -1745,31 +1762,39 @@ const decodeTune = (tune: ABC.Tune, options: DecodeOptions = {}): LilyletDoc =>
 		for (const pi of sortedPartIndices) {
 			const voicesMap = partVoicesMap.get(pi)!;
 			const voices: Voice[] = [];
+			// Voice -> the ABC voice number it came from, recovered from the map key
+			// (voiceKey = staffInPart * 1000 + voiceNum). Voice itself carries no voice
+			// number, and the clef below is a per-voice property, so the association has
+			// to be kept explicitly rather than searched for.
+			const voiceNumOf = new Map<Voice, number>();
 			const sortedKeys = Array.from(voicesMap.keys()).sort((a, b) => a - b);
 			for (const key of sortedKeys) {
-				voices.push(voicesMap.get(key)!);
+				const voice = voicesMap.get(key)!;
+				voices.push(voice);
+				voiceNumOf.set(voice, key % 1000);
 			}
 
 			const part: Part = { voices };
 
-			// Add clef context to first voice of each staff on first measure
-			if (mi === 0) {
-				for (const voice of voices) {
-					// Find voices for this part's staff and add initial clef
-					const voiceNums = Array.from(voicePatches.keys());
-					for (const vn of voiceNums) {
-						if (scoreLayout) {
-							const assign = scoreLayout.get(vn);
-							if (assign && assign.partIndex === pi && assign.staffInPart === voice.staff) {
-								const clef = voiceClefs.get(vn);
-								if (clef) {
-									voice.events.unshift({ type: "context", clef } as ContextChange);
-									break;
-								}
-							}
-						}
-					}
-				}
+			// Give each voice its OWN declared clef on the measure where it first
+			// appears. A clef must be per voice, not per staff: an ABC voice folds its
+			// `transpose=` into the clef suffix, so two voices sharing a staff can
+			// legitimately differ, and lilylet's model is per-voice throughout
+			// (onsets.measureOnsets tracks clefByVoice, serializer.findVoiceClef reads
+			// one clef per Voice).
+			//
+			// This used to scan for the FIRST voice whose scoreLayout assignment matched
+			// (partIndex, staff) and break, so every voice on a shared staff inherited
+			// the first one's clef — the WRONG clef, taking its transposition with it.
+			// A `%%score` arc such as `( 1 2 )` puts both voices on one staff and is
+			// exactly that shape.
+			for (const voice of voices) {
+				const vn = voiceNumOf.get(voice)!;
+				if (emittedClefVoices.has(vn)) continue;
+				const clef = voiceClefs.get(vn);
+				if (!clef) continue;
+				voice.events.unshift({ type: "context", clef } as ContextChange);
+				emittedClefVoices.add(vn);
 			}
 
 			parts.push(part);

package/source/lilylet/clefTransposition.ts

@@ -0,0 +1,197 @@
+/**
+ * The canonical grammar for Lilylet's transposing-clef suffix, and the only place
+ * that converts between a suffix and a semitone count.
+ *
+ * A Lilylet clef may carry a written→sounding transposition as a suffix:
+ *
+ *   treble_8    an octave down          (-12)
+ *   treble^2    a major second up       (+2)
+ *   treble_5    a perfect fifth down    (-7)
+ *   treble_m3   a MINOR third down      (-3)
+ *   treble_m7   a minor seventh down    (-10)
+ *
+ * `_` lowers, `^` raises, the number is a diatonic interval, and an `m` before the
+ * number selects the MINOR form of that interval. Without `m` the interval is the
+ * major/perfect one, which is what every suffix written before the `m` form existed
+ * means — so plain `_N`/`^N` keeps its original value and old documents are read
+ * exactly as before.
+ *
+ * Why `m` exists: the diatonic interval number alone cannot express a minor
+ * interval, so the semitone counts 1, 3, 8 and 10 were unreachable. Those are not
+ * exotic — a minor third is the A clarinet and a minor seventh is a common brass
+ * transposition, so an ABC `transpose=-3` had no exact suffix and was rounded to
+ * `_3` (-4), putting a one-semitone error on the sounding pitch. With `m` the only
+ * remaining gap is 6 semitones, the tritone, which is neither major/perfect nor
+ * minor (it is an augmented fourth or diminished fifth). No instrument transposes
+ * by a tritone and the shape does not occur in any corpus checked, so it is left
+ * unrepresentable rather than given a spelling that would have to be arbitrary.
+ *
+ * NOTE ON LILYPOND: LilyPond's own `\clef "treble_8"` suffix is a NOTATIONAL
+ * device — it repositions middle C on the staff and does not change sounding pitch
+ * at all (LilyPond expresses instrument transposition with the separate
+ * `\transposition <pitch>`, which takes a pitch and so reaches every semitone).
+ * Lilylet deliberately diverges: here the suffix DOES carry the sounding shift, and
+ * `m` is the extension that makes that carrying lossless. LilyPond rejects `_m3` as
+ * an unknown clef type, so a Lilylet clef using `m` is not portable to LilyPond
+ * as-is.
+ */
+
+// Semitones spanned by the MAJOR/PERFECT form of each diatonic step count
+// (0 = unison, 1 = second, … 6 = seventh).
+const DIATONIC_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
+
+// Diatonic step counts that have a minor form: seconds, thirds, sixths, sevenths.
+// Unison, fourth and fifth are perfect and take no `m`.
+const MINOR_CAPABLE_STEPS = new Set([1, 2, 5, 6]);
+
+/** A parsed transposing-clef suffix. */
+export interface ClefSuffix {
+	/** The clef name with the suffix removed, e.g. "treble". */
+	base: string;
+	/** Diatonic interval number as written: 8 for an octave, 3 for a third. */
+	interval: number;
+	/** True when the suffix selected the minor form (`m` present). */
+	minor: boolean;
+	/** true = `^` (up), false = `_` (down). */
+	up: boolean;
+}
+
+// `_`/`^`, an optional `m`, then a positive interval number with no leading zero.
+const SUFFIX_RE = /^(.*?)([_^])(m?)([1-9][0-9]*)$/;
+
+/** Semitones spanned by a diatonic interval number, or undefined if `m` is invalid for it. */
+const intervalSemitones = (interval: number, minor: boolean): number | undefined => {
+	const steps = interval - 1;						// diatonic steps above unison
+	const within = steps % 7;
+	if (minor && !MINOR_CAPABLE_STEPS.has(within)) return undefined;
+	const semis = DIATONIC_SEMITONES[within] + 12 * Math.floor(steps / 7);
+	return minor ? semis - 1 : semis;
+};
+
+/**
+ * Parse a clef string into its base name and transposition suffix.
+ * Returns undefined when the clef carries no suffix, or when the suffix is
+ * malformed (including `m` on a perfect interval such as `_m4`).
+ */
+export const parseClefSuffix = (clefStr: string): ClefSuffix | undefined => {
+	const match = SUFFIX_RE.exec(clefStr || "");
+	if (!match) return undefined;
+	const interval = parseInt(match[4], 10);
+	const minor = match[3] === "m";
+	// Reject a suffix we cannot interpret rather than silently mis-reading it.
+	if (intervalSemitones(interval, minor) === undefined) return undefined;
+	return { base: match[1], interval, minor, up: match[2] === "^" };
+};
+
+/** The clef name with any transposition suffix stripped. */
+export const clefBaseName = (clefStr: string): string =>
+	parseClefSuffix(clefStr)?.base ?? clefStr;
+
+/**
+ * The written→sounding semitone shift a clef string declares; 0 when it declares
+ * none (no suffix, or a suffix that cannot be interpreted).
+ */
+export const clefSuffixSemitones = (clefStr: string): number => {
+	const parsed = parseClefSuffix(clefStr);
+	if (!parsed) return 0;
+	const semis = intervalSemitones(parsed.interval, parsed.minor)!;
+	return parsed.up ? semis : -semis;
+};
+
+/**
+ * The written→sounding transposition as MEI's att.transposition pair, in the
+ * `{diat, semi}` form: diatonic steps and semitones, both signed. A minor third
+ * down is `{diat: -2, semi: -3}` — the two differ, which is exactly the
+ * information the diatonic number alone cannot carry.
+ */
+export const clefSuffixTransposition = (clefStr: string): { diat: number; semi: number } | undefined => {
+	const parsed = parseClefSuffix(clefStr);
+	if (!parsed) return undefined;
+	const semis = intervalSemitones(parsed.interval, parsed.minor)!;
+	const sign = parsed.up ? 1 : -1;
+	return { diat: sign * (parsed.interval - 1), semi: sign * semis };
+};
+
+/**
+ * The suffix that expresses `semitones` EXACTLY, or undefined when no suffix can.
+ * Never approximates: a caller that gets undefined must handle the gap rather than
+ * emit a shift it cannot honour. The only unrepresentable interval within an octave
+ * is 6 semitones (the tritone) — see the module comment.
+ *
+ * Returns the suffix alone (e.g. "_m3"), to be appended to a clef base name.
+ */
+export const semitonesToClefSuffix = (semitones: number): string | undefined => {
+	if (!Number.isInteger(semitones) || semitones === 0) return undefined;
+	const magnitude = Math.abs(semitones);
+	const sign = semitones < 0 ? "_" : "^";
+	// Search interval numbers covering the requested magnitude; octaves shift by 7
+	// diatonic steps, so an octave-and-a-bit needs interval numbers beyond 8.
+	const maxInterval = Math.floor(magnitude / 12) * 7 + 8;
+	for (let interval = 1; interval <= maxInterval; interval++) {
+		for (const minor of [false, true]) {
+			if (intervalSemitones(interval, minor) === magnitude)
+				return `${sign}${minor ? "m" : ""}${interval}`;
+		}
+	}
+	return undefined;
+};
+
+/**
+ * Apply a semitone transposition to a clef name, returning the suffixed clef.
+ * Returns undefined when the shift has no exact suffix, so the caller can decide
+ * between dropping the transposition and reporting it — silently rounding is what
+ * produced wrong sounding pitches before this module existed.
+ */
+export const withClefTransposition = (base: string, semitones: number): string | undefined => {
+	if (semitones === 0) return base;
+	const suffix = semitonesToClefSuffix(semitones);
+	return suffix === undefined ? undefined : base + suffix;
+};
+
+
+/**
+ * Whether LilyPond itself accepts this suffix on a clef name. LilyPond's grammar is
+ * `([_^])([^0-9a-zA-Z]*)([1-9][0-9]*)` — a sign then a bare number — so it has no
+ * place for the `m` that selects a minor interval, and `\clef "treble_m3"` is
+ * rejected outright as an unknown clef type.
+ */
+export const isLilyPondClefSuffix = (clefStr: string): boolean => {
+	const parsed = parseClefSuffix(clefStr);
+	return parsed !== undefined && !parsed.minor;
+};
+
+// Note names for the twelve semitones above c, in ENGLISH spelling (`bf`, not Dutch
+// `bes`) — lilypondEncoder emits `\language "english"`, under which a Dutch name is
+// rejected as "wrong type for argument 1, expecting pitch". Flats throughout: a
+// transposing instrument is named by its flat spelling.
+const ENGLISH_PITCH_NAMES = ["c", "df", "d", "ef", "e", "f", "gf", "g", "af", "a", "bf", "b"];
+
+
+/**
+ * The LilyPond `\transposition` pitch that declares a written→sounding shift of
+ * `semitones`, or undefined when the shift is beyond the two octaves either side of
+ * c' that instrument transpositions occupy.
+ *
+ * This is the mechanism that carries sounding pitch in LilyPond: `\transposition`
+ * takes a pitch, reaches every semitone, and DOES move MIDI, while the clef suffix
+ * is purely notational and moves nothing. The two are orthogonal, so a lilylet clef
+ * whose suffix means a sounding shift translates to BOTH — the suffix for the glyph
+ * (when LilyPond accepts it) and `\transposition` for the sound.
+ *
+ * The pitch is spelled relative to c', the no-transposition reference: an octave
+ * mark `'` per octave above, a `,` per octave below. Compound intervals are real —
+ * a major ninth down (-14) is the written form of some orchestral parts — so the
+ * range is not limited to a single octave.
+ */
+export const lilyPondTranspositionPitch = (semitones: number): string | undefined => {
+	if (!Number.isInteger(semitones) || Math.abs(semitones) > 24) return undefined;
+
+	// Reduce to a pitch class plus an octave count, measuring from c'.
+	const within = ((semitones % 12) + 12) % 12;
+	const octaves = Math.floor(semitones / 12);
+	const name = ENGLISH_PITCH_NAMES[within];
+
+	// c' is the reference and carries one `'`; each octave adds or removes one.
+	const marks = 1 + octaves;
+	return name + (marks >= 0 ? "'".repeat(marks) : ",".repeat(-marks));
+};

package/source/lilylet/index.ts

@@ -5,6 +5,7 @@ export * from "./serializer";
 export * from "./staffLayout";
 export * from "./measureLayout";
 export * from "./onsets";
+export * from "./clefTransposition";
 export * from "./transposition";
 
 import * as meiEncoder from "./meiEncoder";

package/source/lilylet/lilypondDecoder.ts

@@ -43,6 +43,8 @@ import {
 	Tempo,
 } from "./types";
 
+import { clefBaseName, parseClefSuffix, withClefTransposition } from "./clefTransposition";
+
 
 // Phonet names mapping
 const PHONET_NAMES: Record<number, Phonet> = {
@@ -77,6 +79,72 @@ const LILYPOND_CLEF_MAP: Record<string, Clef> = {
 };
 
 
+/**
+ * Fold a standing `\transposition` shift onto a clef as a lilylet suffix.
+ *
+ * The two carry different things in LilyPond and must not be added: a clef suffix
+ * there is notational and moves no pitch, while `\transposition` moves pitch and
+ * draws nothing. lilylet's suffix means sounding shift, so `\transposition` is the
+ * authority whenever it is present — a file with BOTH `\clef "treble_8"` and
+ * `\transposition c` (which is what lilypondEncoder emits for an octave clef) states
+ * one octave, not two.
+ *
+ * With no `\transposition`, a suffix already on the clef is kept as-is: that is the
+ * plain octave-clef part, where the notation is taken to imply its own shift.
+ */
+const applyTransposition = (clef: Clef | undefined, semitones: number): Clef | undefined => {
+	if (!clef || semitones === 0) return clef;
+	const base = clefBaseName(clef as string);
+	const shifted = withClefTransposition(base, semitones);
+	if (shifted === undefined) {
+		console.warn(`lilypondDecoder: \\transposition of ${semitones} semitones has no exact clef suffix; dropped for clef "${clef}"`);
+		return clef;
+	}
+	return shifted as Clef;
+};
+
+// Semitones above c for each diatonic step index (0 = c ... 6 = b).
+const PHONET_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
+
+/**
+ * Semitone offset from c' of a `\transposition` pitch term, which is how LilyPond
+ * states a transposing instrument's written->sounding shift (the clef suffix there is
+ * notational and states nothing). Returns 0 for a pitch that cannot be read.
+ */
+const transpositionSemitones = (term: any): number => {
+	const el = term?.args?.[0];
+	if (!el) return 0;
+	const step = el.phonetStep;
+	const octave = el.absolutePitch?.octave;
+	if (typeof step !== 'number' || typeof octave !== 'number') return 0;
+	// c' is the no-transposition reference, and sits at 12 in this scale.
+	return (PHONET_SEMITONES[step] + (el.alterValue || 0) + 12 * octave) - 12;
+};
+
+/**
+ * A LilyPond clef name to a lilylet Clef, keeping any transposing suffix.
+ *
+ * The map is keyed on BASE names, so looking up the whole string missed every
+ * suffixed clef ("treble_8" is not a key) and `if (clef)` then dropped the clef
+ * event altogether — the transposition went with it. Resolve the base through the
+ * map and reattach the suffix, which is the form lilylet's own model uses.
+ *
+ * A suffix LilyPond cannot write (the `m` minor-interval form) cannot appear in
+ * LilyPond input, so nothing here has to handle it; parseClefSuffix simply returns
+ * undefined for an unsuffixed name and the base is used as-is.
+ */
+const resolveLilyPondClef = (clefName: string): Clef | undefined => {
+	const direct = LILYPOND_CLEF_MAP[clefName];
+	if (direct) return direct;
+
+	const parsed = parseClefSuffix(clefName);
+	if (!parsed) return undefined;
+	const base = LILYPOND_CLEF_MAP[parsed.base];
+	if (!base) return undefined;
+	return (base + clefName.slice(parsed.base.length)) as Clef;
+};
+
+
 // Key signature fifths to pitch/accidental mapping
 const KEY_FIFTHS_MAP: Record<number, { pitch: Phonet; accidental?: Accidental; mode: 'major' | 'minor' }> = {
 	[-7]: { pitch: Phonet.c, accidental: Accidental.flat, mode: 'major' },
@@ -569,6 +637,9 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 		let lastKey: number | undefined = undefined;  // Track value changes (key fifths)
 		let lastTimeSig: string | undefined = undefined;  // Track value changes (as string for comparison)
 		let lastClef: Clef | undefined = undefined;  // Track value changes
+		// \transposition is a standing declaration: it applies to every clef emitted
+		// after it, and lilylet folds the shift into the clef suffix.
+		let transposeSemis = 0;
 		let lastOttava: number | undefined = undefined;  // Track value changes
 		let lastStemDirection: string | undefined = undefined;  // Track value changes
 		let partialEmitted = false;  // Emit \partial context once per track
@@ -669,7 +740,7 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 
 					// Handle clef context change (emit when value changes)
 					if (context.clef) {
-						const clef = LILYPOND_CLEF_MAP[context.clef.clefName];
+						const clef = applyTransposition(resolveLilyPondClef(context.clef.clefName), transposeSemis);
 						if (clef && clef !== lastClef) {
 							voice.events.push({
 								type: 'context',
@@ -796,9 +867,25 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 						}
 					}
 				}
+				else if (term instanceof lilyParser.LilyTerms.Transposition) {
+					const semis = transpositionSemitones(term);
+					if (semis !== transposeSemis) {
+						transposeSemis = semis;
+						// A `\transposition` AFTER the clef still governs it, so re-emit the
+						// clef with the shift folded in rather than let the already-emitted
+						// plain clef stand. Order between the two is not fixed in the wild.
+						if (lastClef) {
+							const corrected = applyTransposition(clefBaseName(lastClef as string) as Clef, transposeSemis);
+							if (corrected && corrected !== lastClef) {
+								voice.events.push({ type: 'context', clef: corrected });
+								lastClef = corrected;
+							}
+						}
+					}
+				}
 				// Handle standalone clef (emit when value changes)
 				else if (term instanceof lilyParser.LilyTerms.Clef) {
-					const clef = LILYPOND_CLEF_MAP[term.clefName];
+					const clef = applyTransposition(resolveLilyPondClef(term.clefName), transposeSemis);
 					if (clef && clef !== lastClef) {
 						voice.events.push({
 							type: 'context',

package/source/lilylet/lilypondEncoder.ts

@@ -38,6 +38,8 @@ import {
 	Placement,
 } from "./types";
 
+import { clefBaseName, clefSuffixSemitones, isLilyPondClefSuffix, lilyPondTranspositionPitch } from "./clefTransposition";
+
 
 // === Constants and Mappings ===
 
@@ -306,10 +308,42 @@ const encodeTimeSig = (timeSig: { numerator: number; denominator: number; symbol
 
 
 /**
- * Encode clef to LilyPond
+ * Encode clef to LilyPond.
+ *
+ * A lilylet clef suffix carries a written→sounding shift; LilyPond's does not —
+ * there the suffix only repositions middle C on the staff and MIDI is untouched,
+ * and sounding pitch comes from the separate `\transposition <pitch>`. The two are
+ * orthogonal, so a transposing clef translates to BOTH: the suffix for the glyph,
+ * `\transposition` for the sound. Emitting only the suffix (what this did before)
+ * produced a file whose notation was right and whose MIDI was a transposition out.
+ *
+ * The clef string is quoted. LilyPond accepts a bare name unquoted, but `_m3`
+ * lexes as `_` followed by `m3` and breaks the parse; quoting is valid for every
+ * form. A `m` suffix has no LilyPond glyph at all (unknown clef type), so the base
+ * clef is emitted and the shift rides entirely on `\transposition`.
  */
 const encodeClef = (clef: Clef): string => {
-	return `\\clef ${CLEF_MAP[clef] || clef}`;
+	const clefStr = clef as string;
+	const shift = clefSuffixSemitones(clefStr);
+
+	// Keep the suffix only when LilyPond can render it; otherwise fall back to the
+	// base name rather than emit a clef LilyPond rejects.
+	const name = (shift === 0 || isLilyPondClefSuffix(clefStr)) ? clefStr : clefBaseName(clefStr);
+	const mapped = CLEF_MAP[name] || name;
+	const parts: string[] = [];
+
+	// \transposition comes FIRST so that a reader tracking it as a standing
+	// declaration has the shift in hand by the time the clef arrives.
+	if (shift !== 0) {
+		const pitch = lilyPondTranspositionPitch(shift);
+		if (pitch)
+			parts.push(`\\transposition ${pitch}`);
+		else
+			console.warn(`lilypondEncoder: clef "${clefStr}" shift ${shift} has no \\transposition pitch; sounding pitch not declared`);
+	}
+	parts.push(`\\clef "${mapped}"`);
+
+	return parts.join(' ');
 };
 
 

package/source/lilylet/meiEncoder.ts

@@ -32,6 +32,7 @@ import {
 import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
 import { gmProgramOf } from "./gmInstruments";
 import { parseMeasureLayout, expandMeasureLayout, decomposeToSegments } from "./measureLayout";
+import { clefBaseName, clefSuffixTransposition } from "./clefTransposition";
 
 
 // MEI key signatures: positive = sharps, negative = flats
@@ -88,7 +89,7 @@ const CLEF_SHAPES: Record<string, { shape: string; line: number }> = {
 
 // Semitone offsets of the major/perfect intervals within one diatonic octave,
 // indexed by diatonic step (0 = unison, 1 = 2nd, … 6 = 7th).
-const DIATONIC_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
+
 
 // Convert a LilyPond clef interval-number suffix into an MEI written→sounding
 // transposition. The number N is a diatonic interval number (2 = 2nd, 3 = 3rd,
@@ -96,29 +97,23 @@ const DIATONIC_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
 // raises it. Returns { diat, semi } where diat is the diatonic step shift
 // (N - 1, signed) and semi is the corresponding chromatic shift in semitones,
 // extended octave-wise for compound intervals.
-const clefTransposition = (intervalNumber: number, up: boolean): { diat: number; semi: number } => {
-	const k = intervalNumber - 1;					// diatonic steps
-	const semis = DIATONIC_SEMITONES[k % 7] + 12 * Math.floor(k / 7);
-	const sign = up ? 1 : -1;
-	return { diat: sign * k, semi: sign * semis };
-};
+
 
 // Resolve a clef string into MEI shape/line plus optional written→sounding
-// transposition. Per the LilyPond convention a "_N"/"^N" suffix transposes the
-// clef down/up by the diatonic interval N (e.g. "treble_8" octave down,
-// "treble_5" fifth down, "treble^3" third up). MEI's clef.dis only covers octave
-// displacement (8|15|22), so all clef transposition — octaves included — is
-// encoded uniformly via att.transposition (trans.diat / trans.semi) on staffDef.
+// transposition. A "_N"/"^N" suffix transposes the clef down/up by the diatonic
+// interval N ("treble_8" octave down, "treble_5" fifth down), and "_mN"/"^mN"
+// selects that interval's minor form ("treble_m3" = minor third down) — see
+// clefTransposition.ts. MEI's clef.dis only covers octave displacement
+// (8|15|22), so all clef transposition — octaves included — is encoded uniformly
+// via att.transposition (trans.diat / trans.semi) on staffDef. A minor interval is
+// exactly why both fields are needed: a minor third is {diat:-2, semi:-3}.
 const resolveClef = (clefStr: string): { shape: string; line: number; trans?: { diat: number; semi: number } } => {
-	const match = clefStr.match(/^(.*?)([_^])(\d+)$/);
-	const base = match ? match[1] : clefStr;
-	const clefInfo = CLEF_SHAPES[base] || CLEF_SHAPES.treble;
-	if (!match) return { shape: clefInfo.shape, line: clefInfo.line };
-	const trans = clefTransposition(Number(match[3]), match[2] === "^");
+	const clefInfo = CLEF_SHAPES[clefBaseName(clefStr)] || CLEF_SHAPES.treble;
+	const trans = clefSuffixTransposition(clefStr);
 	return {
 		shape: clefInfo.shape,
 		line: clefInfo.line,
-		trans,
+		...(trans ? { trans } : {}),
 	};
 };