@k-l-lambda/lilylet 0.1.74 → 0.1.75

package/lib/lilylet/highlight.js

@@ -21,6 +21,7 @@ export const HIGHLIGHT_RULES = [
     { re: /(?:\[instrument\b)/iy, scope: "header" },
     { re: /(?:\[genre\b)/iy, scope: "header" },
     { re: /(?:\[staves\b)/iy, scope: "header" },
+    { re: /(?:\[measures\b)/iy, scope: "header" },
     { re: /(?:\[auto-beam\b)/iy, scope: "header" },
     { re: /(?:\])/iy, scope: "squareBracket" },
     { re: /(?:"[^"]*")/iy, scope: "string" },

package/lib/lilylet/index.d.ts

@@ -2,6 +2,7 @@ export * from "./types";
 export * from "./parser";
 export * from "./serializer";
 export * from "./staffLayout";
+export * from "./measureLayout";
 import * as meiEncoder from "./meiEncoder";
 import * as musicXmlDecoder from "./musicXmlDecoder";
 import * as lilypondEncoder from "./lilypondEncoder";

package/lib/lilylet/index.js

@@ -2,6 +2,7 @@ export * from "./types.js";
 export * from "./parser.js";
 export * from "./serializer.js";
 export * from "./staffLayout.js";
+export * from "./measureLayout.js";
 import * as meiEncoder from "./meiEncoder.js";
 import * as musicXmlDecoder from "./musicXmlDecoder.js";
 import * as lilypondEncoder from "./lilypondEncoder.js";

package/lib/lilylet/measureLayout.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Measure-layout (performance / repeat order) parser + expander, ported from
+ * lotus (`jison/measureLayout.jison` + `inc/measureLayout.ts`).
+ *
+ * A measure-layout string encodes the order in which notated measures are
+ * PLAYED — repeats, voltas, da-capo / ABA — independently of the notated
+ * sequence. It compiles to MEI `<expansion plist="#m1 #m2 #m1 …">`, which is
+ * what verovio's `expand` option unfolds for MIDI / time-map output.
+ *
+ * Two modes:
+ *   - index-wise (`i:`, the default): leaves are 1-based measure INDICES.
+ *       e.g. "2*[1..8]{9,10}, 11..16"
+ *   - segment-wise (`s:`): leaves are segment LENGTHS; measures are
+ *       auto-numbered left-to-right from 1.  e.g. "s: 4 <2 6> 2"
+ *
+ * Constructs (both modes): `N` single, `A..B` inclusive range (index-wise
+ * only), `[ … ]` block, `N*[ … ]{ alt1, alt2 }` volta with alternate endings,
+ * `< main, rest >` ABA / da-capo (play `main rest main`).
+ *
+ * Expansion semantics mirror lotus `LayoutType`: `Full` unfolds every repeat
+ * (volta body repeated once per pass with each alternate ending; ABA → A B A) —
+ * this is the form used for MIDI unfolding.
+ */
+export declare enum LayoutType {
+    Ordinary = "ordinary",// volta body once + all alternates appended; ABA → A B
+    Full = "full",// every repeat unfolded; ABA → A B A
+    Conservative = "conservative",
+    Once = "once"
+}
+export interface SingleMLayout {
+    kind: "single";
+    measure: number;
+}
+export interface BlockMLayout {
+    kind: "block";
+    seq: MeasureLayout[];
+}
+export interface VoltaMLayout {
+    kind: "volta";
+    times: number;
+    body: MeasureLayout[];
+    alternates: MeasureLayout[][] | null;
+}
+export interface ABAMLayout {
+    kind: "aba";
+    main: MeasureLayout;
+    rest: MeasureLayout[];
+}
+export type MeasureLayout = SingleMLayout | BlockMLayout | VoltaMLayout | ABAMLayout;
+/**
+ * Parse a measure-layout string into its AST. The optional `i:` / `s:` prefix
+ * selects index-wise (default) or segment-wise mode; segment-wise leaves are
+ * resolved to 1-based indices here, so the returned AST is mode-agnostic.
+ */
+export declare const parseMeasureLayout: (code: string) => MeasureLayout;
+/**
+ * Expand a measure-layout AST to the performed order as 1-based measure
+ * indices. `LayoutType.Full` (the default) unfolds every repeat — the form
+ * used to build an MEI `<expansion>` for MIDI playback.
+ */
+export declare const expandMeasureLayout: (layout: MeasureLayout, type?: LayoutType) => number[];
+export interface VoltaEndingSpan {
+    number: number;
+    measures: number[];
+}
+export declare const collectVoltaSpans: (layout: MeasureLayout) => VoltaEndingSpan[];
+/** Serialize an AST back to the canonical index-wise DSL string. */
+export declare const serializeMeasureLayout: (layout: MeasureLayout) => string;

package/lib/lilylet/measureLayout.js

@@ -0,0 +1,412 @@
+/**
+ * Measure-layout (performance / repeat order) parser + expander, ported from
+ * lotus (`jison/measureLayout.jison` + `inc/measureLayout.ts`).
+ *
+ * A measure-layout string encodes the order in which notated measures are
+ * PLAYED — repeats, voltas, da-capo / ABA — independently of the notated
+ * sequence. It compiles to MEI `<expansion plist="#m1 #m2 #m1 …">`, which is
+ * what verovio's `expand` option unfolds for MIDI / time-map output.
+ *
+ * Two modes:
+ *   - index-wise (`i:`, the default): leaves are 1-based measure INDICES.
+ *       e.g. "2*[1..8]{9,10}, 11..16"
+ *   - segment-wise (`s:`): leaves are segment LENGTHS; measures are
+ *       auto-numbered left-to-right from 1.  e.g. "s: 4 <2 6> 2"
+ *
+ * Constructs (both modes): `N` single, `A..B` inclusive range (index-wise
+ * only), `[ … ]` block, `N*[ … ]{ alt1, alt2 }` volta with alternate endings,
+ * `< main, rest >` ABA / da-capo (play `main rest main`).
+ *
+ * Expansion semantics mirror lotus `LayoutType`: `Full` unfolds every repeat
+ * (volta body repeated once per pass with each alternate ending; ABA → A B A) —
+ * this is the form used for MIDI unfolding.
+ */
+export var LayoutType;
+(function (LayoutType) {
+    LayoutType["Ordinary"] = "ordinary";
+    LayoutType["Full"] = "full";
+    LayoutType["Conservative"] = "conservative";
+    LayoutType["Once"] = "once";
+})(LayoutType || (LayoutType = {}));
+const single = (measure) => ({ kind: "single", measure });
+const block = (seq) => ({ kind: "block", seq: seq });
+const volta = (times, body, alternates) => ({ kind: "volta", times, body: body, alternates: alternates });
+const aba = (main, rest) => ({ kind: "aba", main: main, rest: rest });
+const segment = (length) => ({ kind: "segment", length });
+const SYMS = new Set(["*", ",", "[", "]", "<", ">", "{", "}"]);
+const tokenize = (code) => {
+    const tokens = [];
+    let i = 0;
+    const n = code.length;
+    while (i < n) {
+        const c = code[i];
+        if (/\s/.test(c)) {
+            i++;
+            continue;
+        }
+        if (c === "." && code[i + 1] === ".") {
+            tokens.push({ t: "range" });
+            i += 2;
+            continue;
+        }
+        if (c >= "1" && c <= "9") {
+            let j = i + 1;
+            while (j < n && code[j] >= "0" && code[j] <= "9")
+                j++;
+            tokens.push({ t: "num", v: Number(code.slice(i, j)) });
+            i = j;
+            continue;
+        }
+        if (SYMS.has(c)) {
+            tokens.push({ t: "sym", v: c });
+            i++;
+            continue;
+        }
+        // mode prefix:  letters followed by ':'
+        if (/[a-z]/i.test(c)) {
+            let j = i;
+            while (j < n && /[a-z]/i.test(code[j]))
+                j++;
+            const word = code.slice(i, j);
+            if (code[j] === ":") {
+                if (word === "i" || word === "s") {
+                    tokens.push({ t: "mode", v: word });
+                    i = j + 1;
+                    continue;
+                }
+                throw new Error(`unknown measure-layout mode prefix: "${word}:"`);
+            }
+            throw new Error(`unexpected token in measure-layout: "${word}"`);
+        }
+        throw new Error(`unexpected character in measure-layout: "${c}" at ${i}`);
+    }
+    tokens.push({ t: "eof" });
+    return tokens;
+};
+// ── Recursive-descent parser ─────────────────────────────────────────────
+// Faithful to lotus's jison grammar. The two modes share the same construct
+// shapes; the only differences are: segment-wise leaves are SEGMENT LENGTHS
+// (not indices), there are no ranges in segment-wise, and the ABA separator is
+// a comma in index-wise but plain juxtaposition in segment-wise.
+class Parser {
+    tokens;
+    pos = 0;
+    segMode;
+    constructor(tokens, segMode) {
+        this.tokens = tokens;
+        this.segMode = segMode;
+    }
+    peek() { return this.tokens[this.pos]; }
+    isSym(v) {
+        const tk = this.peek();
+        return tk.t === "sym" && tk.v === v;
+    }
+    expectSym(v) {
+        if (!this.isSym(v))
+            throw new Error(`measure-layout: expected "${v}", got ${JSON.stringify(this.peek())}`);
+        this.pos++;
+    }
+    takeNum() {
+        const tk = this.peek();
+        if (tk.t !== "num")
+            throw new Error(`measure-layout: expected number, got ${JSON.stringify(tk)}`);
+        this.pos++;
+        return tk.v;
+    }
+    // top-level sequence → a Block (or the single bare block if it's the only item)
+    parseTop() {
+        const seq = this.parseSequence();
+        if (seq.length === 1 && seq[0].kind === "block")
+            return seq[0];
+        return block(seq);
+    }
+    // A comma-separated (index-wise) or juxtaposed (segment-wise) sequence of
+    // items, terminated by EOF or a closing ] > } token.
+    parseSequence() {
+        const seq = [];
+        for (;;) {
+            const tk = this.peek();
+            if (tk.t === "eof" || this.isSym("]") || this.isSym(">") || this.isSym("}"))
+                break;
+            if (!this.segMode && tk.t === "num" && this.tokens[this.pos + 1]?.t === "range") {
+                // index-wise range A..B
+                const start = this.takeNum();
+                this.pos++; // consume ".."
+                const end = this.takeNum();
+                if (!(end >= start))
+                    throw new Error(`invalid measure range: ${start}..${end}`);
+                for (let m = start; m <= end; m++)
+                    seq.push(single(m));
+            }
+            else {
+                seq.push(this.parseItem());
+            }
+            // index-wise items are comma-separated; consume an optional comma
+            if (!this.segMode && this.isSym(","))
+                this.pos++;
+        }
+        return seq;
+    }
+    parseItem() {
+        // volta:  N *[ … ]{ … }
+        if (this.peek().t === "num" && this.tokens[this.pos + 1]?.t === "sym" && this.tokens[this.pos + 1].v === "*") {
+            const times = this.takeNum();
+            this.pos++; // consume '*'
+            const body = this.parseBlock();
+            let alternates = null;
+            if (this.isSym("{"))
+                alternates = this.parseAlternates();
+            return volta(times, body, alternates);
+        }
+        // block
+        if (this.isSym("["))
+            return block(this.parseBlock());
+        // ABA  < main rest >
+        if (this.isSym("<"))
+            return this.parseAba();
+        // leaf
+        const v = this.takeNum();
+        return this.segMode ? segment(v) : single(v);
+    }
+    parseBlock() {
+        this.expectSym("[");
+        const seq = this.parseSequence();
+        this.expectSym("]");
+        return seq;
+    }
+    parseAlternates() {
+        this.expectSym("{");
+        const seq = this.parseSequence();
+        this.expectSym("}");
+        // each item becomes an ending: unwrap a block into its inner seq, wrap a
+        // bare item into a 1-element seq (lotus's `alternates` helper)
+        return seq.map(item => item.kind === "block" ? item.seq : [item]);
+    }
+    parseAba() {
+        this.expectSym("<");
+        const main = this.parseItem();
+        if (!this.segMode)
+            this.expectSym(","); // index-wise: comma between main and rest
+        const rest = this.parseSequence();
+        this.expectSym(">");
+        return aba(main, rest);
+    }
+}
+// ── Segment-wise → index assignment ──────────────────────────────────────
+// In segment-wise mode the leaves are segment lengths; measures auto-number
+// left-to-right from 1. This walk replaces each SegmentMLayout with the right
+// run of SingleMLayout, threading a shared running index (lotus's `serialize`).
+const assignIndices = (item, state) => {
+    switch (item.kind) {
+        case "single":
+            return item;
+        case "segment": {
+            // a lone segment (e.g. the `main` of a segment-wise ABA) → run of singles
+            const seq = [];
+            for (let k = 0; k < item.length; k++)
+                seq.push(single(state.index + k));
+            state.index += item.length;
+            return seq.length === 1 ? seq[0] : { kind: "block", seq };
+        }
+        case "block":
+            return { kind: "block", seq: spreadSegments(item.seq, state) };
+        case "volta":
+            return {
+                kind: "volta",
+                times: item.times,
+                body: spreadSegments(item.body, state),
+                alternates: item.alternates ? item.alternates.map(seq => spreadSegments(seq, state)) : null,
+            };
+        case "aba":
+            return {
+                kind: "aba",
+                main: assignIndices(item.main, state),
+                rest: spreadSegments(item.rest, state),
+            };
+    }
+};
+const spreadSegments = (seq, state) => {
+    const out = [];
+    for (const item of seq) {
+        if (item.kind === "segment") {
+            for (let k = 0; k < item.length; k++)
+                out.push(single(state.index + k));
+            state.index += item.length;
+        }
+        else {
+            out.push(assignIndices(item, state));
+        }
+    }
+    return out;
+};
+/**
+ * Parse a measure-layout string into its AST. The optional `i:` / `s:` prefix
+ * selects index-wise (default) or segment-wise mode; segment-wise leaves are
+ * resolved to 1-based indices here, so the returned AST is mode-agnostic.
+ */
+export const parseMeasureLayout = (code) => {
+    const tokens = tokenize(code);
+    let segMode = false;
+    let start = 0;
+    if (tokens[0].t === "mode") {
+        segMode = tokens[0].v === "s";
+        start = 1;
+    }
+    const parser = new Parser(tokens.slice(start), segMode);
+    const ast = parser.parseTop();
+    if (segMode) {
+        const state = { index: 1 };
+        return assignIndices(ast, state);
+    }
+    return ast;
+};
+// ── Expander ─────────────────────────────────────────────────────────────
+// Port of lotus's MeasureLayout.serialize(type). Returns the performed order
+// as a flat list of 1-based measure indices.
+const spreadSeq = (seq, type) => [].concat(...seq.map(item => expand(item, type)));
+const expand = (item, type) => {
+    switch (item.kind) {
+        case "single":
+            return [item.measure];
+        case "block":
+            return spreadSeq(item.seq, type);
+        case "volta": {
+            const bodySeq = spreadSeq(item.body, LayoutType.Ordinary);
+            if (item.alternates) {
+                const alternateSeqs = item.alternates.map(seq => spreadSeq(seq, LayoutType.Ordinary));
+                const lastAlternateSeq = alternateSeqs[alternateSeqs.length - 1];
+                switch (type) {
+                    case LayoutType.Ordinary:
+                        return [].concat(bodySeq, ...alternateSeqs);
+                    case LayoutType.Conservative:
+                    case LayoutType.Full: {
+                        const prior = [].concat(...Array(item.times - 1).fill(null).map((_, i) => [
+                            ...bodySeq,
+                            ...alternateSeqs[i % (item.times - 1)],
+                        ]));
+                        return [...prior, ...bodySeq, ...lastAlternateSeq];
+                    }
+                    case LayoutType.Once:
+                        return [...bodySeq, ...lastAlternateSeq];
+                }
+            }
+            else {
+                switch (type) {
+                    case LayoutType.Ordinary:
+                    case LayoutType.Conservative:
+                    case LayoutType.Once:
+                        return bodySeq;
+                    case LayoutType.Full:
+                        return [].concat(...Array(item.times).fill(null).map(() => bodySeq));
+                }
+            }
+            return bodySeq; // unreachable; keeps the type checker happy
+        }
+        case "aba": {
+            const seqA = expand(item.main, type);
+            const seqA_ = expand(item.main, LayoutType.Once);
+            const seqB = spreadSeq(item.rest, type);
+            switch (type) {
+                case LayoutType.Ordinary: // A B
+                    return [...seqA, ...seqB];
+                case LayoutType.Once: // B A'
+                    return [...seqB, ...seqA_];
+                case LayoutType.Conservative: // A B A'
+                case LayoutType.Full: // A B A'
+                    return [...seqA, ...seqB, ...seqA_];
+            }
+            return [...seqA, ...seqB, ...seqA_];
+        }
+    }
+};
+/**
+ * Expand a measure-layout AST to the performed order as 1-based measure
+ * indices. `LayoutType.Full` (the default) unfolds every repeat — the form
+ * used to build an MEI `<expansion>` for MIDI playback.
+ */
+export const expandMeasureLayout = (layout, type = LayoutType.Full) => expand(layout, type);
+export const collectVoltaSpans = (layout) => {
+    const spans = [];
+    // Indices a node covers in notation order (each measure once, ascending).
+    const indicesOf = (node) => {
+        switch (node.kind) {
+            case "single": return [node.measure];
+            case "block": return [].concat(...node.seq.map(indicesOf));
+            case "volta": return [].concat(...node.body.map(indicesOf), ...(node.alternates ? node.alternates.flat().map(indicesOf).flat() : []));
+            case "aba": return [].concat(indicesOf(node.main), ...node.rest.map(indicesOf));
+        }
+    };
+    const walk = (node) => {
+        switch (node.kind) {
+            case "block":
+                node.seq.forEach(walk);
+                break;
+            case "aba":
+                walk(node.main);
+                node.rest.forEach(walk);
+                break;
+            case "volta":
+                node.body.forEach(walk);
+                if (node.alternates) {
+                    node.alternates.forEach((alt, ai) => {
+                        const measures = [].concat(...alt.map(indicesOf)).sort((a, b) => a - b);
+                        if (measures.length)
+                            spans.push({ number: ai + 1, measures });
+                        alt.forEach(walk);
+                    });
+                }
+                break;
+            default: break;
+        }
+    };
+    walk(layout);
+    return spans;
+};
+// ── Serializer ───────────────────────────────────────────────────────────
+// Canonical index-wise form, collapsing runs of ≥3 consecutive singles into
+// "A..B" ranges (lotus's seqToCode).
+const seqToCode = (seq, withBrackets = false) => {
+    let code = "";
+    let inRange = false;
+    for (let i = 0; i < seq.length; i++) {
+        const prev = seq[i - 1], cur = seq[i], next = seq[i + 1];
+        const middle = prev?.kind === "single" && cur.kind === "single" && next?.kind === "single"
+            && prev.measure + 1 === cur.measure
+            && cur.measure + 1 === next.measure;
+        if (middle) {
+            if (!inRange) {
+                code += "..";
+                inRange = true;
+            }
+        }
+        else {
+            if (i > 0 && !inRange)
+                code += ", ";
+            inRange = false;
+            code += layoutToCode(cur);
+        }
+    }
+    return withBrackets ? `[${code}]` : code;
+};
+const layoutToCode = (item) => {
+    switch (item.kind) {
+        case "single":
+            return item.measure.toString();
+        case "block":
+            return seqToCode(item.seq, true);
+        case "volta": {
+            let code = `${item.times}*${seqToCode(item.body, true)}`;
+            if (item.alternates)
+                code += "{" + item.alternates.map(seq => seqToCode(seq, seq.length > 1)).join(", ") + "}";
+            return code;
+        }
+        case "aba":
+            return "<" + layoutToCode(item.main) + ", " + seqToCode(item.rest) + ">";
+    }
+};
+/** Serialize an AST back to the canonical index-wise DSL string. */
+export const serializeMeasureLayout = (layout) => {
+    if (layout.kind === "block")
+        return seqToCode(layout.seq);
+    return layoutToCode(layout);
+};

package/lib/lilylet/measureLayoutFromXml.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Derive a performance-order measure-layout string from a MusicXML part's
+ * repeat / volta / navigation markup.
+ *
+ * Input: the raw per-measure repeat structure collected from `<barline>`
+ * (forward/backward repeats, 1st/2nd-ending voltas) and `<direction><sound>`
+ * (D.C./D.S./Coda/Fine jumps), in 1-based measure index order (one entry per
+ * decoded lilylet measure — no merging of split bars, so indices map 1:1).
+ *
+ * Output: a lotus-style measure-layout string (e.g. "2*[1..4]",
+ * "1, 2*[2..7]{[8,9], 10}, 11..15", "1..19, 3..10, 20, 21") suitable for
+ * `metadata.measureLayout`, which the MEI encoder turns into an <expansion> and
+ * verovio unfolds for MIDI. See [[lilylet-measure-layout]].
+ *
+ * Strategy: produce the flat performed-order index sequence by simulating the
+ * repeats/jumps (this is always correct, even for D.C.-al-Fine-over-a-volta
+ * which the structured DSL can't compactly express), then COMPACT it back into
+ * the DSL via the shared serializer when the structure is a clean single
+ * repeat/volta/segno-jump. Compaction is best-effort; the flat form is the
+ * always-valid fallback.
+ */
+export interface MeasureRepeatInfo {
+    index: number;
+    repeatStart?: boolean;
+    repeatEnd?: boolean;
+    repeatTimes?: number;
+    endingStart?: number;
+    endingStop?: number;
+    segno?: boolean;
+    coda?: boolean;
+    tocoda?: boolean;
+    dacapo?: boolean;
+    dalsegno?: boolean;
+    fine?: boolean;
+}
+/**
+ * Build a measure-layout string from a part's repeat structure, or undefined if
+ * there is nothing to unfold (no repeats/voltas/navigation). The result is
+ * guaranteed to expand (via measureLayout.ts) to the simulated performed order.
+ */
+export declare const buildMeasureLayout: (infos: MeasureRepeatInfo[], totalMeasures: number) => string | undefined;
+export declare const collectRepeatInfo: (partEl: Element) => MeasureRepeatInfo[];
+/**
+ * Derive metadata.measureLayout from a <part> element, or undefined if no
+ * repeats/voltas/navigation are present. Convenience wrapper combining the
+ * collector + builder; never throws (returns undefined on any failure).
+ */
+export declare const measureLayoutFromPart: (partEl: Element) => string | undefined;