@k-l-lambda/lilylet 0.1.69 → 0.1.71

package/lib/lilylet/staffLayout.js

@@ -0,0 +1,288 @@
+/**
+ * Staff-layout parser, ported from FindLab starry (app/staffLayout/).
+ *
+ * The layout string uses STAFF as the leaf unit (distinct from ABC's %%score,
+ * which is voice-leaf). Brackets group staves: `{}` = Brace (grand staff),
+ * `<>` = Bracket, `[]` = Square; conjunctions between consecutive staves:
+ * `,` = Blank, `-` = Solid, `.` = Dashed. Staff ids are [a-zA-Z_0-9]+; a slot
+ * with no id is an anonymous staff (auto-named "1","2",…).
+ *
+ * Example: "<[v1-v2].va> {pl-pr} <b>" → 6 staves v1,v2,va,pl,pr,b grouped as
+ * a Bracket over { a Square [v1-v2] dashed-joined to va }, a Brace {pl-pr},
+ * and a Bracket <b>.
+ */
+export var StaffGroupType;
+(function (StaffGroupType) {
+    StaffGroupType[StaffGroupType["Default"] = 0] = "Default";
+    StaffGroupType[StaffGroupType["Brace"] = 1] = "Brace";
+    StaffGroupType[StaffGroupType["Bracket"] = 2] = "Bracket";
+    StaffGroupType[StaffGroupType["Square"] = 3] = "Square";
+})(StaffGroupType || (StaffGroupType = {}));
+export var StaffConjunctionType;
+(function (StaffConjunctionType) {
+    StaffConjunctionType[StaffConjunctionType["Blank"] = 0] = "Blank";
+    StaffConjunctionType[StaffConjunctionType["Dashed"] = 1] = "Dashed";
+    StaffConjunctionType[StaffConjunctionType["Solid"] = 2] = "Solid";
+})(StaffConjunctionType || (StaffConjunctionType = {}));
+const singleGroup = (id) => ({ type: StaffGroupType.Default, staff: id });
+const BOUNDS_TO_GROUPTYPE = {
+    "{": StaffGroupType.Brace,
+    "}": StaffGroupType.Brace,
+    "<": StaffGroupType.Bracket,
+    ">": StaffGroupType.Bracket,
+    "[": StaffGroupType.Square,
+    "]": StaffGroupType.Square,
+};
+const OPEN_BOUNDS = "{<[";
+const CLOSE_BOUNDS = "}>]";
+const CONJUNCTIONS_MAP = {
+    ",": StaffConjunctionType.Blank,
+    "-": StaffConjunctionType.Solid,
+    ".": StaffConjunctionType.Dashed,
+};
+// MEI staffGrp @symbol by StaffGroupType (Default → none). MEI's allowed values
+// are brace | bracket | bracketsq | line | none — note the square variant is
+// "bracketsq", NOT "square" (the latter is MusicXML's <group-symbol> value).
+const GROUP_SYMBOLS_MEI = [null, "brace", "bracket", "bracketsq"];
+const randomB64 = () => {
+    const code = Buffer.from(Math.random().toString().slice(2)).toString("base64").replace(/=/g, "");
+    return code.split("").reverse().slice(0, 6).join("");
+};
+const makeUniqueName = (set, index, prefix) => {
+    let name = prefix;
+    if (!name)
+        name = index.toString();
+    else if (set.has(name))
+        name += "_" + index.toString();
+    while (set.has(name))
+        name = (prefix ? prefix + "_" : "") + randomB64();
+    return name;
+};
+// Tokenize a layout string into RawItem[] (one per staff slot). Lexer: whitespace
+// skipped, single chars [-,.{}<>[]] are bounds/conjunctions, [a-zA-Z_0-9]+ is an id.
+// An item accumulates leading open-bounds (leftBounds), an optional id, trailing
+// close-bounds (rightBounds); a conjunction terminates the item and starts the next.
+const tokenize = (code) => {
+    const tokens = code.match(/[A-Za-z0-9_]+|[-,.{}<>\[\]]/g) || [];
+    const items = [];
+    let cur = { id: null, leftBounds: [], rightBounds: [], conjunction: null };
+    let seenId = false; // id slot filled for the current item
+    let seenRight = false; // started collecting right bounds / closing
+    const pushItem = () => {
+        items.push(cur);
+        cur = { id: null, leftBounds: [], rightBounds: [], conjunction: null };
+        seenId = false;
+        seenRight = false;
+    };
+    for (const tok of tokens) {
+        if (tok in CONJUNCTIONS_MAP) {
+            cur.conjunction = tok;
+            pushItem();
+            continue;
+        }
+        if (OPEN_BOUNDS.includes(tok)) {
+            // An open bound after the id/closing starts a fresh item's left bounds.
+            if (seenId || seenRight)
+                pushItem();
+            cur.leftBounds.push(tok);
+            continue;
+        }
+        if (CLOSE_BOUNDS.includes(tok)) {
+            cur.rightBounds.push(tok);
+            seenRight = true;
+            continue;
+        }
+        // id token
+        if (seenId || seenRight)
+            pushItem();
+        cur.id = tok;
+        seenId = true;
+    }
+    // Flush the final item if it carries any content.
+    if (cur.id !== null || cur.leftBounds.length || cur.rightBounds.length)
+        pushItem();
+    return items;
+};
+const makeGroupsFromRaw = (parent, seq) => {
+    let remains = seq;
+    while (remains.length) {
+        const word = remains.shift();
+        const bound = BOUNDS_TO_GROUPTYPE[word];
+        if (bound !== undefined) {
+            if (CLOSE_BOUNDS.includes(word) && bound === parent.type)
+                break;
+            if (OPEN_BOUNDS.includes(word)) {
+                const group = { type: bound, level: Number.isFinite(parent.level) ? parent.level + 1 : 0 };
+                remains = makeGroupsFromRaw(group, remains);
+                parent.subs = parent.subs || [];
+                parent.subs.push(group);
+            }
+        }
+        else {
+            parent.subs = parent.subs || [];
+            parent.subs.push(singleGroup(word));
+        }
+    }
+    while (parent.type === StaffGroupType.Default && parent.subs && parent.subs.length === 1) {
+        const sub = parent.subs[0];
+        parent.type = sub.type;
+        parent.subs = sub.subs;
+        parent.staff = sub.staff;
+        parent.level = sub.level;
+    }
+    while (parent.subs && parent.subs.length === 1 && parent.subs[0].type === StaffGroupType.Default) {
+        const sub = parent.subs[0];
+        parent.subs = sub.subs;
+        parent.staff = sub.staff;
+    }
+    parent.grand = parent.type === StaffGroupType.Brace && !!parent.subs && parent.subs.every(sub => !!sub.staff);
+    return remains;
+};
+const groupHead = (group) => {
+    if (group.staff)
+        return group.staff;
+    else if (group.subs)
+        return groupHead(group.subs[0]);
+};
+const groupTail = (group) => {
+    if (group.staff)
+        return group.staff;
+    else if (group.subs)
+        return groupTail(group.subs[group.subs.length - 1]);
+};
+export const groupKey = (group) => {
+    if (group.staff)
+        return group.staff;
+    else if (group.subs)
+        return `${groupHead(group)}-${groupTail(group)}`;
+};
+const groupDict = (group, dict) => {
+    const key = groupKey(group);
+    if (key !== undefined)
+        dict[key] = group;
+    if (group.subs)
+        group.subs.forEach(sub => groupDict(sub, dict));
+};
+export class StaffLayout {
+    staffIds;
+    conjunctions;
+    group;
+    groups;
+    constructor(raw) {
+        // make unique ids (anonymous slots get "1","2",… ; named collisions disambiguated)
+        const ids = new Set();
+        raw.forEach((item, i) => {
+            item.id = makeUniqueName(ids, i + 1, item.id || undefined);
+            ids.add(item.id);
+        });
+        this.staffIds = raw.map(item => item.id);
+        this.conjunctions = raw.slice(0, raw.length - 1).map(item => item.conjunction ? CONJUNCTIONS_MAP[item.conjunction] : StaffConjunctionType.Blank);
+        // make groups
+        const seq = [].concat(...raw.map(item => [...item.leftBounds, item.id, ...item.rightBounds]));
+        this.group = { type: StaffGroupType.Default };
+        makeGroupsFromRaw(this.group, seq);
+        const dict = {};
+        groupDict(this.group, dict);
+        this.groups = Object.entries(dict).map(([key, group]) => {
+            let ids = key.split("-");
+            if (ids.length === 1)
+                ids = [ids[0], ids[0]];
+            const range = ids.map(id => this.staffIds.indexOf(id));
+            const cons = this.conjunctions.slice(range[0], range[1]);
+            const bar = cons.length ? Math.min(...cons) : 0;
+            group.key = key;
+            group.bar = bar;
+            return { group, range, key };
+        });
+    }
+    get stavesCount() {
+        return this.staffIds.length;
+    }
+}
+export const parseStaffLayout = (code) => new StaffLayout(tokenize(code));
+// ── Staff-layout serialization (inverse of parseStaffLayout) ──
+// Reconstruct a layout string from a parsed StaffLayout by walking the group tree,
+// so every staff slot and conjunction is preserved structurally (a regex strip of the
+// ids would drop a BARE anonymous leaf — its empty token gets swallowed by whitespace).
+//
+// `anonymous` emits empty ids (the parser re-auto-names slots "1","2",… by position).
+// `idMap` optionally overrides individual staff ids by their original id.
+//
+// Conjunction rendering: Solid → "-", Dashed → ".", Blank → " " ONLY when both sides
+// are bracketed groups (the brackets self-delimit the slots); otherwise Blank → ","
+// so an adjacent empty/bare leaf still tokenizes as its own slot.
+const CONJ_CHAR = {
+    [StaffConjunctionType.Solid]: "-",
+    [StaffConjunctionType.Dashed]: ".",
+    [StaffConjunctionType.Blank]: ",",
+};
+export const serializeStaffLayout = (layout, options = {}) => {
+    const { anonymous = false, idMap } = options;
+    const isGrouped = (group) => group.type !== StaffGroupType.Default && !!group.subs;
+    const leafText = (id) => (anonymous ? "" : idMap ? idMap(id) : id);
+    // flat leaf index of a group's first / last staff (for the inter-child conjunction).
+    const firstLeafIndex = (group) => layout.staffIds.indexOf(groupHead(group));
+    const lastLeafIndex = (group) => layout.staffIds.indexOf(groupTail(group));
+    const sep = (conj, left, right) => {
+        if (conj !== StaffConjunctionType.Blank)
+            return CONJ_CHAR[conj];
+        // Blank: a space is safe only when both neighbours are bracketed (self-delimiting).
+        return isGrouped(left) && isGrouped(right) ? " " : ",";
+    };
+    const emit = (group) => {
+        if (!group.subs)
+            return leafText(group.staff); // Default leaf
+        const open = group.type === StaffGroupType.Brace ? "{" : group.type === StaffGroupType.Bracket ? "<" : group.type === StaffGroupType.Square ? "[" : "";
+        const close = group.type === StaffGroupType.Brace ? "}" : group.type === StaffGroupType.Bracket ? ">" : group.type === StaffGroupType.Square ? "]" : "";
+        let inner = "";
+        group.subs.forEach((sub, i) => {
+            inner += emit(sub);
+            if (i < group.subs.length - 1) {
+                const next = group.subs[i + 1];
+                const conj = layout.conjunctions[lastLeafIndex(sub)] ?? StaffConjunctionType.Blank;
+                inner += sep(conj, sub, next);
+                void firstLeafIndex; // (lastLeafIndex(sub) === firstLeafIndex(next) - 1)
+            }
+        });
+        return open + inner + close;
+    };
+    let out = emit(layout.group);
+    // A TRAILING bare anonymous leaf emits "" with nothing after it to delimit the slot
+    // (a leaf before a closing bracket is fine — the bracket gives it bounds; an internal
+    // one is flushed by the next separator). The tokenizer only flushes a final empty item
+    // if it carries bounds, so append one "," to materialize that last empty slot. This only
+    // arises when the OUTERMOST container is the Default sequence (no enclosing bracket) and
+    // its last child is a bare leaf; if the whole layout is wrapped in a bracket, the closing
+    // bracket already delimits the final leaf. The trailing conjunction is dropped on re-parse
+    // (conjunctions = items[0..n-1]), so it is harmless. Anonymous output only.
+    if (anonymous && layout.group.type === StaffGroupType.Default && layout.group.subs) {
+        const lastTop = layout.group.subs[layout.group.subs.length - 1];
+        if (!lastTop.subs && lastTop.staff !== undefined)
+            out += ",";
+    }
+    return out;
+};
+// ── MEI staffGrp encoding (ported from FindLab staffLayout/encoding.js encodeMEI) ──
+// Recursively emit nested <staffGrp> with symbol (brace/bracket/square) and bar.thru,
+// with <staffDef n="..."> leaves keyed by staff index. nameDict maps a group key to a
+// label. Returns the inner XML (no <scoreDef> wrapper); the caller positions it.
+const bool = (x) => (x ? "true" : "false");
+const stateMEIGroup = (statements, group, nameDict, ids, indent, tab) => {
+    const pad = tab.repeat(indent);
+    const name = group.key !== undefined ? nameDict[group.key] : undefined;
+    if (group.subs) {
+        const symbol = GROUP_SYMBOLS_MEI[group.type] ? ` symbol="${GROUP_SYMBOLS_MEI[group.type]}"` : "";
+        statements.push(`${pad}<staffGrp bar.thru="${bool((group.bar ?? 0) > 1)}"${symbol}>`);
+        if (name)
+            statements.push(`${pad}${tab}<label>${name}</label>`);
+        group.subs.forEach(sub => stateMEIGroup(statements, sub, nameDict, ids, indent + 1, tab));
+        statements.push(`${pad}</staffGrp>`);
+    }
+    if (group.staff)
+        statements.push(`${pad}<staffDef n="${ids.indexOf(group.staff) + 1}">`);
+};
+export const encodeStaffLayoutMEI = (layout, nameDict = {}, indent = 0, tab = "\t") => {
+    const statements = [];
+    stateMEIGroup(statements, layout.group, nameDict, layout.staffIds, indent, tab);
+    return statements.join("\n");
+};

package/lib/lilylet/types.d.ts

@@ -239,8 +239,16 @@ export interface Metadata {
     opus?: string;
     instrument?: string;
     genre?: string;
+    staves?: string;
+    instruments?: {
+        [key: string]: InstrumentName;
+    };
     autoBeam?: 'auto' | 'on' | 'off';
 }
+export interface InstrumentName {
+    name: string;
+    shortName?: string;
+}
 export interface Part {
     name?: string;
     voices: Voice[];

package/lib/staffLayout.d.ts

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

package/lib/staffLayout.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "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",

package/source/abc/abc.jison

@@ -361,7 +361,7 @@ staff_layout
 staff_layout_items
 	: staff_layout_item						-> [$1]
 	| staff_layout_items staff_layout_item	-> [...$1, $2]
-	| staff_layout_items '|'				-> $1
+	| staff_layout_items '|'				{ if ($1.length) $1[$1.length - 1].barThruAfter = true; $$ = $1; }
 	;
 
 staff_layout_item

package/source/abc/abc.ts

@@ -130,6 +130,7 @@ namespace ABC {
 	export interface StaffGroup {
 		items: (StaffGroup | string)[];
 		bound?: 'arc' | 'square' | 'curly';
+		barThruAfter?: boolean;   // a '|' followed this sibling in %%score (barlines run through)
 	};
 
 

package/source/abc/grammar.jison.js

@@ -95,7 +95,7 @@ break;
 case 4:
 this.$ = tune($$[$0-1], $$[$0]);
 break;
-case 11: case 12: case 13: case 14: case 16: case 20: case 67: case 101: case 104: case 105: case 106: case 107: case 136: case 137: case 163: case 164: case 222:
+case 11: case 12: case 13: case 14: case 16: case 67: case 101: case 104: case 105: case 106: case 107: case 136: case 137: case 163: case 164: case 222:
 this.$ = $$[$0-1];
 break;
 case 15:
@@ -104,6 +104,9 @@ break;
 case 17:
 this.$ = ({staffLayout: $$[$0]});
 break;
+case 20:
+ if ($$[$0-1].length) $$[$0-1][$$[$0-1].length - 1].barThruAfter = true; this.$ = $$[$0-1]; 
+break;
 case 21:
 this.$ = staffGroup([$$[$0]]);
 break;

package/source/lilylet/abcDecoder.ts

@@ -37,7 +37,9 @@ import {
 	MarkupEvent,
 	DynamicEvent,
 	Placement,
+	InstrumentName,
 } from "./types";
+import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
 
 
 // ============ Constants ============
@@ -395,6 +397,9 @@ const convertClef = (clefStr: string): Clef | undefined => {
 	// Split off an optional ABC octave shift suffix: "treble-8", "bass+8", "treble-15".
 	// ABC: "-N" lowers the sounding pitch (small N drawn below), "+N" raises it.
 	// LilyPond/Lilylet: "_N" = below, "^N" = above. Translate the sign accordingly.
+	// (Only octave amounts 8/15 are handled here; the Lilylet "_N"/"^N" clef suffix
+	// itself accepts arbitrary diatonic intervals — see meiEncoder.resolveClef — and a
+	// voice's transpose= property is folded into the same suffix via transposeClefSuffix.)
 	const shift = clefStr?.match(/^(.*?)([+-])(8|15)$/);
 	const base = shift ? shift[1] : clefStr;
 	let resolved: string | undefined;
@@ -408,6 +413,29 @@ const convertClef = (clefStr: string): Clef | undefined => {
 	return resolved as Clef;
 };
 
+/**
+ * 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.
+ */
+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;
+};
+
 /**
  * Convert ABC barline to Lilylet barline style
  */
@@ -516,6 +544,168 @@ const parseScoreLayout = (
 };
 
 
+/**
+ * Translate an ABC %%score layout into the equivalent lilylet staves expression.
+ *
+ * The two models differ in their leaf unit: ABC %%score is VOICE-leaf (an arc `( … )`
+ * collapses several voices onto one staff), whereas lilylet staves is STAFF-leaf. So
+ * each ABC staff becomes exactly one lilylet staff id, named (per spec) by the FIRST
+ * voice token inside its arc.
+ *
+ * Bracket mapping (ABC → lilylet):
+ *   ( … )  arc    → one staff leaf (id = first voice)         e.g. (1 3) → "1"
+ *   bare   leaf   → one staff leaf (id = that voice)          e.g. 7     → "7"
+ *   { … }  curly  → brace (grand staff)                       → { … }
+ *   [ … ]  square → bracket (orchestral)                      → < … >
+ *
+ * Conjunction between two siblings: a trailing `|` in %%score means barlines run through
+ * the two staves, mapped to the solid conjunction `-`; otherwise the blank `,` is used.
+ */
+const abcLayoutToStaves = (layout: ABC.StaffGroup[]): string | null => {
+	// First voice token under a node (the staff's lilylet id).
+	const firstVoice = (node: ABC.StaffGroup | string): string | null => {
+		if (typeof node === "string") return node;
+		for (const item of node.items || []) {
+			const v = firstVoice(item);
+			if (v !== null) return v;
+		}
+		return null;
+	};
+
+	// A node is a single staff (an arc, or a bare leaf) iff it has no curly/square nesting.
+	const isStaffLeaf = (node: ABC.StaffGroup | string): boolean => {
+		if (typeof node === "string") return true;
+		if (node.bound === "curly" || node.bound === "square") return false;
+		// arc or unbounded: a staff only if every descendant is too (no nested groups)
+		return (node.items || []).every(isStaffLeaf);
+	};
+
+	// A square group maps to lilylet Bracket `<>` at the TOP level, but to lilylet Square
+	// `[]` when nested inside another group — e.g. ABC `[[1 2] 3 | 4]` → `<[1,2]3-4>`.
+	// A curly group always maps to Brace `{}`. `nested` is false for a top-level entry.
+	const emit = (node: ABC.StaffGroup | string, nested: boolean): string => {
+		if (isStaffLeaf(node)) return firstVoice(node) || "";
+
+		const group = node as ABC.StaffGroup;
+		const open = group.bound === "curly" ? "{" : (group.bound === "square" && nested) ? "[" : "<";
+		const close = group.bound === "curly" ? "}" : (group.bound === "square" && nested) ? "]" : ">";
+
+		const items = group.items || [];
+		let inner = "";
+		items.forEach((item, i) => {
+			inner += emit(item, true);
+			if (i < items.length - 1) {
+				// A Blank separator (',') is only needed between two bare staff leaves; a
+				// grouped neighbour's bracket already delimits the slot, so suppress it there
+				// (giving `[1,2]3` not `[1,2],3`). A Solid join ('-', barThru) is always kept.
+				const next = items[i + 1];
+				if ((item as ABC.StaffGroup).barThruAfter) inner += "-";
+				else if (isStaffLeaf(item) && isStaffLeaf(next)) inner += ",";
+			}
+		});
+		return `${open}${inner}${close}`;
+	};
+
+	const tops = layout.map((top, i) => {
+		let s = emit(top, false);
+		// A bare top-level staff leaf (e.g. the `9` in `[ … ] 9 [ … ]`) still occupies a slot;
+		// emit() already yields its id with no wrapper, which is the desired output.
+		return { s, barThru: !!top.barThruAfter, isLast: i === layout.length - 1 };
+	});
+
+	let out = "";
+	tops.forEach((t, i) => {
+		out += t.s;
+		if (i < tops.length - 1) out += t.barThru ? " - " : " ";
+	});
+
+	out = out.trim();
+	return out.length > 0 ? out : null;
+};
+
+
+/**
+ * Translate ABC voice instrument names (V:n nm="…" snm="…") into a lilylet `instruments`
+ * map keyed by staff-layout group key.
+ *
+ * ABC names sit on individual voices; lilylet staves are staff-leaf (an arc's first voice
+ * is the staff id). So we first collect a per-staff name from the staff-id voice. Then,
+ * per the user's rule: if a GROUP carries an instrument only on its first staff and the
+ * rest of the group is unnamed, the name belongs to the whole group — hoist it to the
+ * group key and drop it from the leaf. This matches engraving convention (one bracketed
+ * section, e.g. "Violini", named once for the group rather than on its top staff).
+ *
+ * `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.
+ */
+const abcInstrumentsToLilylet = (
+	stavesCode: string,
+	voiceInstr: Map<number, InstrumentName>,
+): { [key: string]: InstrumentName } | null => {
+	const layout = parseStaffLayout(stavesCode);
+	const result: { [key: string]: InstrumentName } = {};
+
+	// Per-staff instrument, keyed by staff id (the arc-first voice number as a string).
+	const staffInstr = new Map<string, InstrumentName>();
+	for (const id of layout.staffIds) {
+		const v = parseInt(id, 10);
+		if (!isNaN(v) && voiceInstr.has(v)) staffInstr.set(id, voiceInstr.get(v)!);
+	}
+
+	// First staff id under a group (in layout order).
+	const firstStaffId = (group: StaffGroup): string | undefined => {
+		if (group.staff) return group.staff;
+		for (const sub of group.subs || []) {
+			const id = firstStaffId(sub);
+			if (id !== undefined) return id;
+		}
+		return undefined;
+	};
+
+	// All staff ids under a group except the first.
+	const restStaffIds = (group: StaffGroup): string[] => {
+		const all: string[] = [];
+		const collect = (g: StaffGroup) => {
+			if (g.staff) all.push(g.staff);
+			(g.subs || []).forEach(collect);
+		};
+		collect(group);
+		return all.slice(1);
+	};
+
+	// Walk groups top-down; hoist a first-staff-only name onto the group, else keep leaves.
+	const walk = (group: StaffGroup) => {
+		const isLeaf = !!group.staff && (!group.subs || group.subs.length === 0);
+		if (isLeaf) {
+			// A plain leaf keeps its own name (assigned in the flush pass below).
+			return;
+		}
+
+		const first = firstStaffId(group);
+		const firstInstr = first !== undefined ? staffInstr.get(first) : undefined;
+		const rest = restStaffIds(group);
+		const restNamed = rest.some(id => staffInstr.has(id));
+
+		// Group with a real grouping symbol, named only on its first staff → hoist.
+		const hasSymbol = group.type !== StaffGroupType.Default;
+		if (hasSymbol && firstInstr && !restNamed && group.key !== undefined) {
+			result[group.key] = firstInstr;
+			staffInstr.delete(first!);  // consumed by the group
+			return;  // children below the hoisted name carry nothing
+		}
+
+		for (const sub of group.subs || []) walk(sub);
+	};
+
+	walk(layout.group);
+
+	// Flush any per-staff names that weren't hoisted onto a group.
+	for (const [id, instr] of staffInstr) result[id] = instr;
+
+	return Object.keys(result).length > 0 ? result : null;
+};
+
+
 // ============ Marks/Decorations Conversion ============
 
 const convertArticulationMark = (artName: string): Mark | undefined => {
@@ -1103,7 +1293,17 @@ const decodeTune = (tune: ABC.Tune, options: DecodeOptions = {}): LilyletDoc =>
 						properties: voiceValue?.properties,
 					});
 					if (clefStr) {
-						const clef = convertClef(clefStr);
+						let clef = convertClef(clefStr);
+						// Fold a voice transpose= (semitones) into the clef suffix so it
+						// survives to MEI as trans.diat/trans.semi (transposing instruments
+						// like "Clarinet transpose=-2", "Horn transpose=-9").
+						const transposeRaw = (voiceValue as any)?.properties?.transpose;
+						const transposeSemi = typeof transposeRaw === "number"
+							? transposeRaw
+							: (transposeRaw != null ? Number(transposeRaw) : NaN);
+						if (clef && Number.isFinite(transposeSemi) && transposeSemi !== 0) {
+							clef = transposeClefSuffix(clef, transposeSemi);
+						}
 						if (clef) voiceClefs.set(voiceId, clef);
 					}
 				}
@@ -1115,6 +1315,36 @@ const decodeTune = (tune: ABC.Tune, options: DecodeOptions = {}): LilyletDoc =>
 	// Parse score layout
 	const scoreLayout = parseScoreLayout(headers);
 
+	// Translate the ABC %%score layout into a lilylet staves expression (staff-leaf model).
+	const layoutHeader = headers.find((h: any) => h.staffLayout);
+	if (layoutHeader) {
+		const staves = abcLayoutToStaves((layoutHeader as any).staffLayout);
+		if (staves) metadata.staves = staves;
+
+		// Translate per-voice nm/snm into a lilylet instruments map. Collect names by ABC
+		// voice number (the staff id is the arc-first voice), then let abcInstrumentsToLilylet
+		// apply the first-staff-only → whole-group hoisting rule.
+		if (metadata.staves) {
+			const voiceInstr = new Map<number, InstrumentName>();
+			for (const [vid, config] of voiceConfigs) {
+				const props = config.properties;
+				if (!props) continue;
+				const name = props.nm ?? props.name;
+				if (typeof name !== "string" || !name.length) continue;
+				const v = typeof vid === "number" ? vid : parseInt(String(vid), 10);
+				if (isNaN(v)) continue;
+				const short = props.snm ?? props.sname;
+				voiceInstr.set(v, typeof short === "string" && short.length
+					? { name, shortName: short }
+					: { name });
+			}
+			if (voiceInstr.size > 0) {
+				const instruments = abcInstrumentsToLilylet(metadata.staves, voiceInstr);
+				if (instruments) metadata.instruments = instruments;
+			}
+		}
+	}
+
 	// Group measures by voice
 	// ABC measures contain BarPatches, each with a voice control V:n
 	const measures = body.measures;