@k-l-lambda/lilylet 0.1.88 → 0.1.89

package/lib/clefTransposition.d.ts

@@ -0,0 +1 @@
+export * from "./lilylet/clefTransposition.js";

package/lib/clefTransposition.js

@@ -0,0 +1 @@
+export * from "./lilylet/clefTransposition.js";

package/lib/lilylet/abcDecoder.js

@@ -7,6 +7,7 @@ import parse from "../abc/parser.js";
 import { Phonet, Accidental, ArticulationType, OrnamentType, DynamicType, HairpinType, PedalType, NavigationMarkType, Placement, } from "./types.js";
 import { parseStaffLayout, StaffGroupType } from "./staffLayout.js";
 import { buildMeasureLayout, applyNavText } from "./measureLayoutFromXml.js";
+import { parseClefSuffix, withClefTransposition } from "./clefTransposition.js";
 // ============ Constants ============
 // NotaGen catalog tags appear as leading single-% comments in ABC files,
 // in the order: period, composer, instrumentation. They are mapped to
@@ -426,28 +427,34 @@ const convertClef = (clefStr) => {
 };
 /**
  * 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, semitones) => {
     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))
+    // 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))
         return clef;
-    const steps = Math.round((semitones * 7) / 12);
-    if (steps === 0)
+    const transposed = withClefTransposition(clef, semitones);
+    if (transposed === undefined) {
+        console.warn(`abcDecoder: transpose=${semitones} has no exact clef suffix; transposition dropped for clef "${clef}"`);
         return clef;
-    const num = Math.abs(steps) + 1;
-    const suffix = (steps < 0 ? "_" : "^") + num;
-    return (clef + suffix);
+    }
+    return transposed;
 };
 /**
  * Convert ABC barline to Lilylet barline style
@@ -1450,6 +1457,14 @@ const decodeTune = (tune, options = {}) => {
     // [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;
+    // 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();
     for (let mi = 0; mi < measures.length; mi++) {
         const abcMeasure = measures[mi];
         // Group patches by voice number
@@ -1585,29 +1600,39 @@ const decodeTune = (tune, options = {}) => {
         for (const pi of sortedPartIndices) {
             const voicesMap = partVoicesMap.get(pi);
             const voices = [];
+            // 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();
             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 = { 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 });
-                                    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 });
+                emittedClefVoices.add(vn);
             }
             parts.push(part);
         }

package/lib/lilylet/clefTransposition.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+/** 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;
+}
+/**
+ * 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 declare const parseClefSuffix: (clefStr: string) => ClefSuffix | undefined;
+/** The clef name with any transposition suffix stripped. */
+export declare const clefBaseName: (clefStr: string) => string;
+/**
+ * The written→sounding semitone shift a clef string declares; 0 when it declares
+ * none (no suffix, or a suffix that cannot be interpreted).
+ */
+export declare const clefSuffixSemitones: (clefStr: string) => number;
+/**
+ * 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 declare const clefSuffixTransposition: (clefStr: string) => {
+    diat: number;
+    semi: number;
+} | undefined;
+/**
+ * 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 declare const semitonesToClefSuffix: (semitones: number) => string | 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 declare const withClefTransposition: (base: string, semitones: number) => string | undefined;

package/lib/lilylet/clefTransposition.js

@@ -0,0 +1,133 @@
+/**
+ * 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]);
+// `_`/`^`, 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, minor) => {
+    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) => {
+    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) => 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) => {
+    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) => {
+    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) => {
+    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, semitones) => {
+    if (semitones === 0)
+        return base;
+    const suffix = semitonesToClefSuffix(semitones);
+    return suffix === undefined ? undefined : base + suffix;
+};

package/lib/lilylet/index.d.ts

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

package/lib/lilylet/index.js

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

package/lib/lilylet/meiEncoder.js

@@ -2,6 +2,7 @@ import { Clef, Accidental, OrnamentType, StemDirection, HairpinType, PedalType,
 import { parseStaffLayout, StaffGroupType } from "./staffLayout.js";
 import { gmProgramOf } from "./gmInstruments.js";
 import { parseMeasureLayout, expandMeasureLayout, decomposeToSegments } from "./measureLayout.js";
+import { clefBaseName, clefSuffixTransposition } from "./clefTransposition.js";
 // MEI key signatures: positive = sharps, negative = flats
 const KEY_SIGS = {
     0: "0",
@@ -49,36 +50,27 @@ const CLEF_SHAPES = {
 };
 // 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,
 // 5 = 5th, 8 = octave, 15 = two octaves); "_" lowers the sounding pitch, "^"
 // 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, up) => {
-    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) => {
-    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 } : {}),
     };
 };
 // Attributes for a standalone <clef> element (mid-measure clef change).

package/lib/lilylet/onsets.d.ts

@@ -9,10 +9,11 @@
  * 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.
+ * The written->sounding semitone shift a clef string declares. A "_N"/"^N" suffix transposes
+ * DOWN/UP by the diatonic interval N ("treble_8" = octave down, -12; "treble_5" = fifth down,
+ * -7), and an "m" before the number selects that interval's MINOR form ("treble_m3" = minor
+ * third down, -3). A plain clef declares 0. See clefTransposition.ts for the grammar; this is
+ * a thin alias kept because clefShift is the name the onset API and its tests already use.
  */
 export declare const clefShift: (clefStr: string) => number;
 /**

package/lib/lilylet/onsets.js

@@ -10,6 +10,7 @@
  */
 import { calculateDuration } from "./musicXmlUtils.js";
 import { Accidental } from "./types.js";
+import { clefSuffixSemitones } from "./clefTransposition.js";
 // 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
@@ -21,22 +22,14 @@ const ACCIDENTAL_SEMITONE = {
     [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.
+ * The written->sounding semitone shift a clef string declares. A "_N"/"^N" suffix transposes
+ * DOWN/UP by the diatonic interval N ("treble_8" = octave down, -12; "treble_5" = fifth down,
+ * -7), and an "m" before the number selects that interval's MINOR form ("treble_m3" = minor
+ * third down, -3). A plain clef declares 0. See clefTransposition.ts for the grammar; this is
+ * a thin alias kept because clefShift is the name the onset API and its tests already use.
  */
-export const clefShift = (clefStr) => {
-    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;
-};
+export const clefShift = (clefStr) => clefSuffixSemitones(clefStr);
 /**
  * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.88",
+  "version": "0.1.89",
   "description": "Lilylet is a lilyopnd-like sheet music language designed for Markdown rendering and symbolic music representation in AIGC applications.",
   "type": "module",
   "main": "lib/index.js",
@@ -55,6 +55,8 @@
     "test:abc-instrument": "tsx ./tests/unit/abcInstrumentName.test.ts",
     "test:abc-partial": "tsx ./tests/unit/abcPartialPickup.test.ts",
     "test:clef-onset": "tsx ./tests/unit/clefOnsetTranspose.test.ts",
+    "test:abc-transpose": "tsx ./tests/unit/abcTransposingClef.test.ts",
+    "test:clef-transposition": "tsx ./tests/unit/clefTransposition.test.ts",
     "test:fine-rhythm-onset": "tsx ./tests/unit/fineRhythmOnset.test.ts",
     "test:transpose": "tsx ./tests/unit/astTranspose.test.ts",
     "build:tests": "tsc -p tsconfig.tests.json; cp source/lilylet/grammar.jison.js lib-tests/source/lilylet/ && cp source/abc/grammar.jison.js lib-tests/source/abc/ && node tools/fixEsmExtensions.cjs lib-tests && ln -sfn ../../tests/assets lib-tests/tests/assets",

package/source/abc/abc.jison

@@ -213,6 +213,7 @@ SPECIAL								[:!^_,'/<>={}()\[\]|.\-+~&]
 
 ^[T][:][\s]*						{ var pre = this.matched.slice(0, this.matched.length - yytext.length); if (pre === '' || pre.slice(-1) === '\n') { this.pushState('title_string'); return 'T:'; } this.unput(yytext.slice(1)); yytext = 'T'; return 'T'; }
 ^[C][:][\s]*						{ var pre = this.matched.slice(0, this.matched.length - yytext.length); if (pre === '' || pre.slice(-1) === '\n') { this.pushState('title_string'); return 'C:'; } this.unput(yytext.slice(1)); yytext = 'C'; return 'A'; }
+^[ABDFGHINORSWZ][:](?![|])[ \t]*	{ var pre = this.matched.slice(0, this.matched.length - yytext.length); if (pre === '' || pre.slice(-1) === '\n') { this.pushState('title_string'); yytext = yytext[0]; return 'TEXT_FIELD'; } this.unput(yytext.slice(1)); yytext = yytext[0]; return 'H'; }
 <title_string>\n					{ this.popState(); }
 <title_string>[^\n]+				return 'STR_CONTENT'
 
@@ -379,6 +380,7 @@ head_line
 	| 'K:' key_signature				-> header('K', $2)
 	| 'V:' header_value					-> header('V', $2)
 	| H ':' header_value				-> header($1, $3)
+	| TEXT_FIELD string_content			-> header($1, $2)
 	;
 
 header_value