linked-rolls 0.0.1

package/lib/Stage.js

@@ -0,0 +1,165 @@
+import { v4 } from "uuid";
+import { flat } from "./EditorialAssumption";
+import { dimensionOf } from "./Symbol";
+const versionType = [
+    /**
+     * The roll is in a state where it is used as
+     * the master roll for several new reproductions.
+     */
+    'edition',
+    /**
+     * This denotes a stage which is specific to (early)
+     * Welte-Mignon piano rolls, where rolls inteded to
+     * be pulished are revised by a controller first. These
+     * rolls typically carry a "controlliert" stamp. The
+     * revision is done on the same date as the perforation
+     * and the date is written on the roll towards its end.
+     */
+    'authorised-revision',
+    /**
+     * Unauthorised revisions are those, which cannot be linked
+     * to a specific controller and are likely done by
+     * a later, anonymous hand.
+     */
+    'unauthorised-revision',
+    /**
+     * In the case of Welte Mignon rolls, glosses are
+     * typically comments about the roll's condition, added
+     * e.g. by the collector.
+     */
+    'gloss'
+];
+export const traverseStages = (stage, callback) => {
+    callback(stage);
+    if (stage.basedOn) {
+        traverseStages(flat(stage.basedOn), callback);
+    }
+};
+export const getSnapshot = (stage) => {
+    const snapshot = [];
+    const toDelete = [];
+    traverseStages(stage, s => {
+        snapshot.push(...s.edits.flatMap(edit => edit.insert || []));
+        // as we travel further up, remove symbols that are 
+        // deleted in the stages further down
+        const deleted = [];
+        for (const toRemove of toDelete) {
+            const index = snapshot.findIndex(s => s === toRemove);
+            if (index !== -1) {
+                snapshot.splice(index, 1);
+                deleted.push(toRemove);
+            }
+        }
+        for (const del of deleted) {
+            toDelete.splice(toDelete.indexOf(del), 1);
+        }
+        // collect symbols that are deleted in the current stage
+        toDelete.push(...s.edits.flatMap(edit => edit.delete || []));
+    });
+    return snapshot.sort((a, b) => {
+        const aDimension = dimensionOf(a);
+        const bDimension = dimensionOf(b);
+        return aDimension.horizontal.from - bDimension.horizontal.from;
+    });
+};
+const isCollatable = (symbolA, symbolB) => {
+    // two symbols are collatible if they share the same 
+    // symbol characteristics (pitch, expression type etc.)
+    // and occur in the same horizontal position.
+    if (symbolA.type === 'note' && symbolB.type === 'note') {
+        if (symbolA.pitch !== symbolB.pitch)
+            return false;
+    }
+    else if (symbolA.type === 'expression' && symbolB.type === 'expression') {
+        if (symbolA.expressionType !== symbolB.expressionType)
+            return false;
+        if (symbolA.scope !== symbolB.scope)
+            return false;
+    }
+    const dimensionA = dimensionOf(symbolA);
+    const dimensionB = dimensionOf(symbolB);
+    const distanceStart = Math.abs(dimensionA.horizontal.from - dimensionB.horizontal.from);
+    const distanceEnd = Math.abs(dimensionA.horizontal.to - dimensionB.horizontal.to);
+    if (distanceStart > 5 || distanceEnd > 5) {
+        // the symbols are too far apart to be collated
+        return false;
+    }
+    return true;
+};
+const overlaps = (a, b) => {
+    const overlapsDimension = (a, b) => (a.from ?? 0) < (b.to ?? Infinity) && (b.from ?? 0) < (a.to ?? Infinity);
+    return overlapsDimension(a.horizontal, b.horizontal) && overlapsDimension(a.vertical, b.vertical);
+};
+/**
+ * Walks through the stages. If it finds a symbol that is still
+ * part of the tradition (i.e. it is included in the current snapshot)
+ * and is equivalent with the given symbol, it will add the feature
+ * carrying the symbol to the collated symbol. Otherwise, the
+ * given symbol will be added to the current stage's insertions.
+ *
+ * All symbols of the tradition that are not included in the given
+ * symbols are considered to be deleted.
+ *
+ * @param creation
+ * @param symbols
+ * @returns
+ */
+export function fillEdits(currentStage, symbols) {
+    const snapshot = getSnapshot(currentStage);
+    const treatedSymbols = [];
+    // can it be collated with any of the symbols of 
+    // included in the current snapshot?
+    const insertions = [...symbols];
+    for (const symbol of symbols) {
+        snapshot
+            .filter(toCompare => isCollatable(symbol, toCompare))
+            .forEach(corresp => {
+            corresp.carriers.push(...symbol.carriers);
+            insertions.splice(insertions.indexOf(symbol), 1);
+            treatedSymbols.push(corresp);
+        });
+    }
+    // special treatment for covers
+    const covers = insertions.filter(symbol => symbol.type === 'cover');
+    for (const cover of covers) {
+        // find perforations in the snapshot that 
+        // overlap with the cover
+        snapshot
+            .filter(symbol => symbol.type === 'note' || symbol.type === 'expression')
+            .map(dimensionOf)
+            .filter(dimension => overlaps(dimension, dimensionOf(cover)))
+            .forEach(dimension => {
+            const coverDimension = dimensionOf(cover);
+            // check if the cover partially covers the beginning
+            if (dimension.horizontal.from >= coverDimension.horizontal.from &&
+                dimension.horizontal.from <= coverDimension.horizontal.to) {
+                // the note starts where the cover ends
+                dimension.horizontal.from = coverDimension.horizontal.to;
+            }
+            // check if the cover partially covers the ending
+            if (dimension.horizontal.to >= coverDimension.horizontal.from &&
+                dimension.horizontal.to <= coverDimension.horizontal.to) {
+                // the note ends where the cover starts
+                dimension.horizontal.to = coverDimension.horizontal.from;
+            }
+        });
+        insertions.splice(insertions.indexOf(cover), 1);
+    }
+    currentStage.edits.push(...insertions.map((symbol) => {
+        return {
+            insert: [symbol],
+            delete: [],
+            id: v4(),
+        };
+    }));
+    const deletions = snapshot.filter(sym => {
+        return !treatedSymbols.includes(sym);
+    });
+    for (const symbol of deletions) {
+        currentStage.edits.push({
+            insert: [],
+            delete: [symbol],
+            id: v4(),
+        });
+    }
+}

package/lib/Symbol.d.ts

@@ -0,0 +1,62 @@
+import { EditorialAssumption } from "./EditorialAssumption";
+import { HorizontalSpan, RollFeature, VerticalSpan } from "./Feature";
+import { WithId } from "./WithId";
+/**
+ * @todo Should this be called Transcription?
+ */
+export type CarrierAssignment = EditorialAssumption<'carrierAssignment', RollFeature>;
+export interface Symbol<T extends string> extends WithId {
+    type: T;
+    carriers: CarrierAssignment[];
+}
+export declare const isSymbol: (object: any) => object is AnySymbol;
+export interface Perforation<T extends string> extends Symbol<T> {
+    accelerating?: boolean;
+}
+export interface Note extends Perforation<'note'> {
+    pitch: number;
+}
+export type ExpressionScope = 'bass' | 'treble';
+export type ExpressionType = 'SustainPedalOn' | 'SustainPedalOff' | 'SoftPedalOn' | 'SoftPedalOff' | 'MezzoforteOff' | 'MezzoforteOn' | 'SlowCrescendoOn' | 'SlowCrescendoOff' | 'ForzandoOn' | 'ForzandoOff' | 'MotorOff' | 'MotorOn' | 'Rewind' | 'ElectricCutOff';
+export interface Expression extends Perforation<'expression'> {
+    scope: ExpressionScope;
+    expressionType: ExpressionType;
+}
+/**
+ * This denotes perforations that are covered by an editor.
+ * The covered perforation is not considered to be part
+ * of the original note or expression hole anymore.
+ */
+export interface Cover extends Symbol<'cover'> {
+    /**
+     * This property can be used to indicate e.g. the
+     * color or material of the cover.
+     */
+    note?: string;
+}
+export interface Text<T extends string> extends Symbol<T> {
+    text: string;
+    rotation?: number;
+}
+/**
+ * For handwritten insertions like e. g. the
+ * perforation date in the end of a roll.
+ */
+export interface HandwrittenText extends Text<'handwrittenText'> {
+    pen?: 'ink' | 'pencil' | 'crayon';
+}
+/**
+ * This type can be used to indicate stamps like e. g. the
+ * "controlliert" stamp in the beginning of rolls or the
+ * date at the end of (later) Welte rolls.
+ */
+export interface Stamp extends Text<'stamp'> {
+}
+export interface RollLabel extends Text<'rollLabel'> {
+    signed: boolean;
+}
+export type AnySymbol = Note | Expression | HandwrittenText | Stamp | Cover | RollLabel;
+export declare const dimensionOf: (symbol: AnySymbol) => {
+    horizontal: HorizontalSpan;
+    vertical: VerticalSpan;
+};

package/lib/Symbol.js

@@ -0,0 +1,29 @@
+import { flat } from "./EditorialAssumption";
+export const isSymbol = (object) => {
+    return 'carriers' in object;
+};
+export const dimensionOf = (symbol) => {
+    if (symbol.carriers.length === 0) {
+        return {
+            horizontal: { unit: 'mm', from: 0, to: 0 },
+            vertical: { unit: 'track', from: 0, to: 0 }
+        };
+    }
+    const horizontalFrom = flat(symbol.carriers)
+        .reduce((hAcc, h) => hAcc + h.horizontal.from, 0) / symbol.carriers.length;
+    const horizontalTo = flat(symbol.carriers)
+        .reduce((hAcc, h) => hAcc + h.horizontal.to, 0) / symbol.carriers.length;
+    const verticalFrom = flat(symbol.carriers)
+        .reduce((vAcc, v) => vAcc + v.vertical.from, 0) / symbol.carriers.length;
+    const definedVerticalTo = flat(symbol.carriers)
+        .filter(v => v.vertical.to !== undefined);
+    let verticalTo = undefined;
+    if (definedVerticalTo.length > 0) {
+        verticalTo = definedVerticalTo
+            .reduce((vAcc, v) => vAcc + v.vertical.to, 0) / definedVerticalTo.length;
+    }
+    return {
+        horizontal: { unit: 'mm', from: horizontalFrom, to: horizontalTo },
+        vertical: { unit: 'track', from: verticalFrom, to: verticalTo }
+    };
+};

package/lib/TrackerBar.d.ts

@@ -0,0 +1,8 @@
+import { Expression, Note } from "./Symbol";
+export declare abstract class TrackerBar {
+    abstract meaningOf(track: number): Partial<Note> | Partial<Expression>;
+}
+export declare class WelteT100 {
+    meaningOf(track: number): Pick<Note, 'type' | 'pitch'> | Pick<Expression, 'type' | 'expressionType' | 'scope'>;
+    width: number;
+}

package/lib/TrackerBar.js

@@ -0,0 +1,53 @@
+export class TrackerBar {
+}
+export class WelteT100 {
+    constructor() {
+        Object.defineProperty(this, "width", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 328
+        }); // in mm, cf. Hagmann, p. 75
+    }
+    meaningOf(track) {
+        if (track <= 0 || track > 100) {
+            throw new Error('Track out of range');
+        }
+        // Cf. Hagmann, p. 178
+        const expressionMap = new Map([
+            [1, 'MezzoforteOff'],
+            [2, 'MezzoforteOn'],
+            [3, 'SlowCrescendoOff'],
+            [4, 'SlowCrescendoOn'],
+            [5, 'ForzandoOff'],
+            [6, 'ForzandoOn'],
+            [7, 'SoftPedalOff'],
+            [8, 'SoftPedalOn'],
+            [9, 'MotorOff'],
+            [10, 'MotorOn'],
+            [91, 'Rewind'],
+            [92, 'ElectricCutOff'],
+            [93, 'SustainPedalOn'],
+            [94, 'SustainPedalOff'],
+            [95, 'ForzandoOn'],
+            [96, 'ForzandoOff'],
+            [97, 'SlowCrescendoOn'],
+            [98, 'SlowCrescendoOff'],
+            [99, 'MezzoforteOn'],
+            [100, 'MezzoforteOff']
+        ]);
+        if (track <= 10 || track >= 91) {
+            const scope = track <= 10 ? 'bass' : 'treble';
+            return {
+                expressionType: expressionMap.get(track),
+                scope,
+                type: 'expression'
+            };
+        }
+        // C1-G4 = track 11-90 = 24-103 in MIDI keys
+        return {
+            pitch: track + 13,
+            type: 'note',
+        };
+    }
+}

package/lib/Transcription.d.ts

@@ -0,0 +1,7 @@
+import { Observation } from "./EditorialAssumption";
+/**
+ * Every transcription is an I1 Argumentation.
+ */
+export interface Transcription extends Observation {
+    software?: string;
+}

package/lib/Transcription.js

@@ -0,0 +1,9 @@
+export {};
+// Example:
+// Edit -> carried out by -> "Anonym"
+// Edit -> concluded by -> Observation: der äußeren Erscheinung nach eine spätere Hinzufügung von unbekanntere Hand
+// Edit -> insert -> Symbol
+// Symbol -> is carried by -> Roll Feature -> condition -> damaged
+// Symbol -> concludedBy -> Transcription -> Die Perforationen wurden nicht präzise an die richtige Stelle gesetzt. 
+//                                           Wir gehen davon aus, dass sie jeweils auf der darüberliegenden Linie
+//                                           platziert werden sollten.

package/lib/Version.d.ts

@@ -0,0 +1,42 @@
+import { ActorAssignment, Edit } from "./Edit";
+import { EditorialAssumption, Motivation } from "./EditorialAssumption";
+import { AnySymbol } from "./Symbol";
+import { CollationTolerance } from "./Collation";
+export type Derivation = EditorialAssumption<'derivation', Version>;
+export declare const versionTypes: readonly ["edition", "authorised-revision", "unauthorised-revision", "gloss"];
+export type VersionType = typeof versionTypes[number];
+/**
+ * Version + Version Creation
+ */
+export interface Version {
+    id: string;
+    siglum: string;
+    actor?: ActorAssignment;
+    basedOn?: Derivation;
+    edits: Edit[];
+    motivations: Motivation<string>[];
+    type: VersionType;
+}
+export declare const traverseVersions: (version: Version, callback: (version: Version) => void) => void;
+export declare const getSnapshot: (version: Version) => AnySymbol[];
+/**
+ * Walks through the versions. If it finds a symbol that is still
+ * part of the tradition (i.e. it is included in the current snapshot)
+ * and is equivalent with the given symbol, it will add the feature
+ * carrying the symbol to the collated symbol. Otherwise, the
+ * given symbol will be added to the current version's insertions.
+ *
+ * All symbols of the tradition that are not included in the given
+ * symbols are considered to be deleted.
+ *
+ * @param creation
+ * @param symbols
+ * @returns
+ */
+export declare function fillEdits(currentVersion: Version, symbols: AnySymbol[], tolerance?: CollationTolerance): void;
+/**
+ * Assigns a generation (depth) to every node.
+ */
+export declare function assignGenerations(versions: Version[]): Array<Version & {
+    generation: number;
+}>;

package/lib/Version.js

@@ -0,0 +1,217 @@
+import { v4 } from "uuid";
+import { flat } from "./EditorialAssumption";
+import { dimensionOf } from "./Symbol";
+export const versionTypes = [
+    /**
+     * The roll is in a state where it is used as
+     * the master roll for several new reproductions.
+     */
+    'edition',
+    /**
+     * This denotes a version which is specific to (early)
+     * Welte-Mignon piano rolls, where rolls inteded to
+     * be pulished are revised by a controller first. These
+     * rolls typically carry a "controlliert" stamp. The
+     * revision is done on the same date as the perforation
+     * and the date is written on the roll towards its end.
+     */
+    'authorised-revision',
+    /**
+     * Unauthorised revisions are those, which cannot be linked
+     * to a specific controller and are likely done by
+     * a later, anonymous hand.
+     */
+    'unauthorised-revision',
+    /**
+     * In the case of Welte Mignon rolls, glosses are
+     * typically comments about the roll's condition, added
+     * e.g. by the collector.
+     */
+    'gloss'
+];
+export const traverseVersions = (version, callback) => {
+    callback(version);
+    if (version.basedOn) {
+        traverseVersions(flat(version.basedOn), callback);
+    }
+};
+export const getSnapshot = (version) => {
+    const snapshot = [];
+    const toDelete = [];
+    traverseVersions(version, s => {
+        snapshot.push(...s.edits.flatMap(edit => edit.insert || []));
+        // as we travel further up, remove symbols that are 
+        // deleted in the versions further down
+        const deleted = [];
+        for (const toRemove of toDelete) {
+            const index = snapshot.findIndex(s => s === toRemove);
+            if (index !== -1) {
+                snapshot.splice(index, 1);
+                deleted.push(toRemove);
+            }
+        }
+        for (const del of deleted) {
+            toDelete.splice(toDelete.indexOf(del), 1);
+        }
+        // collect symbols that are deleted in the current version
+        toDelete.push(...s.edits.flatMap(edit => edit.delete || []));
+    });
+    return snapshot.sort((a, b) => {
+        const aDimension = dimensionOf(a);
+        const bDimension = dimensionOf(b);
+        return aDimension.horizontal.from - bDimension.horizontal.from;
+    });
+};
+const isCollatable = (symbolA, symbolB, tolerance = {
+    toleranceEnd: 5,
+    toleranceStart: 5
+}) => {
+    // two symbols are collatible if they share the same 
+    // symbol characteristics (pitch, expression type etc.)
+    // and occur in the same horizontal position.
+    if (symbolA.type === 'note' && symbolB.type === 'note') {
+        if (symbolA.pitch !== symbolB.pitch)
+            return false;
+    }
+    else if (symbolA.type === 'expression' && symbolB.type === 'expression') {
+        if (symbolA.expressionType !== symbolB.expressionType)
+            return false;
+        if (symbolA.scope !== symbolB.scope)
+            return false;
+    }
+    const dimensionA = dimensionOf(symbolA);
+    const dimensionB = dimensionOf(symbolB);
+    const distanceStart = Math.abs(dimensionA.horizontal.from - dimensionB.horizontal.from);
+    const distanceEnd = Math.abs(dimensionA.horizontal.to - dimensionB.horizontal.to);
+    if (distanceStart > tolerance.toleranceStart
+        || distanceEnd > tolerance.toleranceEnd) {
+        // the symbols are too far apart to be collated
+        return false;
+    }
+    return true;
+};
+const overlaps = (a, b) => {
+    const overlapsDimension = (a, b) => (a.from ?? 0) < (b.to ?? Infinity) && (b.from ?? 0) < (a.to ?? Infinity);
+    return overlapsDimension(a.horizontal, b.horizontal) && overlapsDimension(a.vertical, b.vertical);
+};
+/**
+ * Walks through the versions. If it finds a symbol that is still
+ * part of the tradition (i.e. it is included in the current snapshot)
+ * and is equivalent with the given symbol, it will add the feature
+ * carrying the symbol to the collated symbol. Otherwise, the
+ * given symbol will be added to the current version's insertions.
+ *
+ * All symbols of the tradition that are not included in the given
+ * symbols are considered to be deleted.
+ *
+ * @param creation
+ * @param symbols
+ * @returns
+ */
+export function fillEdits(currentVersion, symbols, tolerance = {
+    toleranceEnd: 5,
+    toleranceStart: 5
+}) {
+    const snapshot = getSnapshot(currentVersion);
+    const treatedSymbols = [];
+    // can it be collated with any of the symbols of 
+    // included in the current snapshot?
+    const insertions = [...symbols];
+    for (const symbol of symbols) {
+        snapshot
+            .filter(toCompare => isCollatable(symbol, toCompare, tolerance))
+            .forEach(corresp => {
+            corresp.carriers.push(...symbol.carriers);
+            insertions.splice(insertions.indexOf(symbol), 1);
+            treatedSymbols.push(corresp);
+        });
+    }
+    // special treatment for covers
+    const covers = insertions.filter(symbol => symbol.type === 'cover');
+    for (const cover of covers) {
+        // find perforations in the snapshot that 
+        // overlap with the cover
+        snapshot
+            .filter(symbol => symbol.type === 'note' || symbol.type === 'expression')
+            .map(dimensionOf)
+            .filter(dimension => overlaps(dimension, dimensionOf(cover)))
+            .forEach(dimension => {
+            const coverDimension = dimensionOf(cover);
+            // check if the cover partially covers the beginning
+            if (dimension.horizontal.from >= coverDimension.horizontal.from &&
+                dimension.horizontal.from <= coverDimension.horizontal.to) {
+                // the note starts where the cover ends
+                dimension.horizontal.from = coverDimension.horizontal.to;
+            }
+            // check if the cover partially covers the ending
+            if (dimension.horizontal.to >= coverDimension.horizontal.from &&
+                dimension.horizontal.to <= coverDimension.horizontal.to) {
+                // the note ends where the cover starts
+                dimension.horizontal.to = coverDimension.horizontal.from;
+            }
+        });
+        insertions.splice(insertions.indexOf(cover), 1);
+    }
+    currentVersion.edits.push(...insertions.map((symbol) => {
+        return {
+            insert: [symbol],
+            delete: [],
+            id: v4(),
+        };
+    }));
+    const deletions = snapshot.filter(sym => {
+        return !treatedSymbols.includes(sym);
+    });
+    for (const symbol of deletions) {
+        currentVersion.edits.push({
+            insert: [],
+            delete: [symbol],
+            id: v4(),
+        });
+    }
+}
+/**
+ * Assigns a generation (depth) to every node.
+ */
+export function assignGenerations(versions) {
+    const byId = new Map();
+    for (const n of versions)
+        byId.set(n.id, n);
+    const memo = new Map(); // id -> generation
+    const inStack = new Set(); // for cycle detection
+    const computeGen = (id) => {
+        if (memo.has(id))
+            return memo.get(id);
+        if (inStack.has(id)) {
+            throw new Error(`Cycle detected involving node '${id}'. Check parentId links.`);
+        }
+        const node = byId.get(id);
+        if (!node) {
+            // If you ever call computeGen on a missing id, treat as root.
+            memo.set(id, 0);
+            return 0;
+        }
+        inStack.add(id);
+        let gen;
+        const p = node.basedOn?.assigned.id;
+        if (p === undefined) {
+            gen = 0; // root
+        }
+        else if (!byId.has(p)) {
+            // Orphaned parent reference — treat boundary as root
+            gen = 0;
+        }
+        else {
+            gen = 1 + computeGen(p);
+        }
+        inStack.delete(id);
+        memo.set(id, gen);
+        return gen;
+    };
+    // Compute for all nodes (order doesn’t matter)
+    const withGen = versions.map(n => ({
+        ...n,
+        generation: computeGen(n.id),
+    }));
+    return withGen;
+}

package/lib/WithId.d.ts

@@ -0,0 +1,3 @@
+export interface WithId {
+    'id': string;
+}

package/lib/WithId.js

@@ -0,0 +1 @@
+export {};

package/lib/alignFeatures.d.ts

@@ -0,0 +1,11 @@
+import { RollFeature } from "./Feature";
+type AlignmentResult = {
+    shift: number;
+    stretch: number;
+};
+/**
+ * Align two rolls by computing independent linear fits of each roll's note-onset positions
+ * using only the first and last segments, then deriving a transform x2 = (x1 + shift) * stretch.
+ */
+export declare function alignFeatures(rollA: RollFeature[], rollB: RollFeature[]): AlignmentResult;
+export {};

package/lib/alignFeatures.js

@@ -0,0 +1,54 @@
+import { WelteT100 } from "./TrackerBar";
+const isNote = (feature) => {
+    return new WelteT100().meaningOf(feature.vertical.from).type === 'note';
+};
+/**
+ * Fit a line: position = alpha * index + beta via least squares.
+ */
+function fitIndexToPosition(indices, positions) {
+    const n = indices.length;
+    const meanIdx = indices.reduce((s, i) => s + i, 0) / n;
+    const meanPos = positions.reduce((s, p) => s + p, 0) / n;
+    let num = 0;
+    let den = 0;
+    for (let i = 0; i < n; i++) {
+        const d = indices[i] - meanIdx;
+        num += d * (positions[i] - meanPos);
+        den += d * d;
+    }
+    const alpha = den === 0 ? 1 : num / den;
+    const beta = meanPos - alpha * meanIdx;
+    return { alpha, beta };
+}
+/**
+ * Selects the first and last N elements of an array (or fewer if length is smaller).
+ */
+function selectEnds(arr, count) {
+    const n = arr.length;
+    if (count * 2 >= n)
+        return arr.slice();
+    return arr.slice(0, count).concat(arr.slice(n - count, n));
+}
+/**
+ * Align two rolls by computing independent linear fits of each roll's note-onset positions
+ * using only the first and last segments, then deriving a transform x2 = (x1 + shift) * stretch.
+ */
+export function alignFeatures(rollA, rollB) {
+    // 1. Extract note-onset positions
+    const allXA = rollA.filter(isNote).map(f => f.horizontal.from);
+    const allXB = rollB.filter(isNote).map(f => f.horizontal.from);
+    // 2. Determine segment size (e.g. 10% of notes, min 5)
+    const segCount = Math.max(5, Math.floor(allXA.length * 0.1));
+    // 3. Select only first and last segments
+    const XA = selectEnds(allXA, segCount);
+    const idxA = XA.map((_, i) => i);
+    const XB = selectEnds(allXB, segCount);
+    const idxB = XB.map((_, i) => i);
+    // 4. Fit index->position for each roll on selected ends
+    const { alpha: alphaA, beta: betaA } = fitIndexToPosition(idxA, XA);
+    const { alpha: alphaB, beta: betaB } = fitIndexToPosition(idxB, XB);
+    // 5. Derive stretch and shift such that x2 = (x1 + shift) * stretch
+    const stretch = alphaB / alphaA;
+    const shift = betaB / stretch - betaA;
+    return { stretch, shift };
+}

package/lib/alignRolls.d.ts

@@ -0,0 +1,7 @@
+import { AnySymbol } from "./Symbol";
+type AlignmentResult = {
+    shift: number;
+    stretch: number;
+};
+export declare function alignSymbols(rollA: AnySymbol[], rollB: AnySymbol[]): AlignmentResult;
+export {};