linked-rolls 0.31.0 → 0.32.0

package/lib/Version.d.ts

@@ -59,21 +59,21 @@ export interface VersionCreation {
     procedure?: Concept;
 }
 /**
- * A version is defined by the sum of edits applied
- * to the version it is based on. For simple identification,
- * a siglum is given to each version.
+ * A version is defined by the sum of edits applied to the version it is
+ * based on. What it is called is not stored with it: `siglaOf` reads the
+ * sigla off the stemma, so that a label never outlives the arrangement
+ * it describes.
  * @see lrmoo:F2 Expression
  */
 export interface Version extends WithId, WithType<'Version'> {
     /**
-     * A short siglum to identify the version, e.g. "A" or "B2". A siglum
-     * is given once and not changed: its letter names the line the version
-     * was first recognised in, its number counts the versions admitted to
-     * that line. Where later work places the version elsewhere in the
-     * stemma, `basedOn` changes and the siglum stays.
+     * A label a document carries from before the sigla were computed.
+     * Nothing should write one here and nothing should show one: what a
+     * version is called comes from `siglaOf`.
+     * @deprecated
      * @see reo:siglum
      */
-    siglum: string;
+    siglum?: string;
     /**
      * The reproducing system this version is coded for. One roll was
      * often issued for several of them, and a version is a reading in

package/lib/editionOps.d.ts

@@ -21,7 +21,7 @@ export type EditionOp = (draft: Draft<Edition>) => void;
  * version is a reading in that system's words, so it is coded for the
  * system the copy was cut for.
  */
-export declare const createVersion: (siglum: string, copy: RollCopy) => EditionOp;
+export declare const createVersion: (copy: RollCopy) => EditionOp;
 /**
  * Puts the copy into the edition without a version of its own, as for a
  * copy whose features are not read into symbols: one known only from a

package/lib/editionOps.js

@@ -75,13 +75,12 @@ const dropInsertions = (version, symbolIds) => {
  * version is a reading in that system's words, so it is coded for the
  * system the copy was cut for.
  */
-export const createVersion = (siglum, copy) => draft => {
+export const createVersion = (copy) => draft => {
     const bar = barOf(copy);
     draft.copies.push(copy);
     draft.versions.push({
         type: 'Version',
         id: v4(),
-        siglum,
         system: systemOf(bar),
         edits: asSymbols(copy.features, bar).map(insertion),
         motivations: []
@@ -637,19 +636,6 @@ export const removeVersion = (view, versionId) => {
 };
 /** Takes the symbols out of the version's own insertions, and the edits that had nothing else. */
 export const removeSymbols = (versionId, symbolIds) => onVersion(versionId, version => dropInsertions(version, new Set(symbolIds)));
-/**
- * The siglum for a version derived from this one: the line the siglum
- * names, and the next number free in it. A number already given stays
- * given, whatever the stemma does later.
- */
-const nextInLine = (versions, siglum) => {
-    const [line] = siglum.match(/^\D*/) ?? [siglum];
-    const numbers = versions.flatMap(other => {
-        const match = other.siglum.match(/^(\D*)(\d*)$/);
-        return match && match[1] === line ? [Number(match[2] || 1)] : [];
-    });
-    return `${line}${Math.max(1, ...numbers) + 1}`;
-};
 /** Moves the edits into a new version based on this one. */
 export const deriveVersion = (versionId, editIds) => onVersion(versionId, (version, draft) => {
     const chosen = new Set(editIds);
@@ -659,7 +645,6 @@ export const deriveVersion = (versionId, editIds) => onVersion(versionId, (versi
     draft.versions.push({
         type: 'Version',
         id: v4(),
-        siglum: nextInLine(draft.versions, version.siglum),
         system: stateOf(version).system,
         basedOn: [assignReference(versionId)],
         edits: moved,

package/lib/index.d.ts

@@ -28,6 +28,8 @@ export * from './validate';
 export * from './constraints';
 export * from './substitution';
 export * from './context';
+export * from './sigla';
+export * from './notes';
 export * from './asJsonLd';
 export * from './importJsonLd';
 export * from './migrate';

package/lib/index.js

@@ -28,6 +28,8 @@ export * from './validate';
 export * from './constraints';
 export * from './substitution';
 export * from './context';
+export * from './sigla';
+export * from './notes';
 export * from './asJsonLd';
 export * from './importJsonLd';
 export * from './migrate';

package/lib/notes.d.ts

@@ -0,0 +1,17 @@
+export type NotePart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'reference';
+    id: string;
+};
+/** The note in the pieces it is shown in: stretches of text and what they refer to. */
+export declare const partsOfNote: (note: string) => NotePart[];
+/** The ids a note refers to, in the order it names them. */
+export declare const referencesInNote: (note: string) => string[];
+/**
+ * The note as it reads, with every reference resolved to the name the
+ * edition gives that entity. A reference nothing answers to keeps its id,
+ * so that the gap is visible rather than silent.
+ */
+export declare const resolveNote: (note: string, nameOf: (id: string) => string | undefined) => string;

package/lib/notes.js

@@ -0,0 +1,32 @@
+/**
+ * A note refers to a version or a copy instead of naming it, so that a
+ * label the stemma decides is never written into the prose. A reference
+ * reads `{{<id>}}`, where the id is the entity's, and is resolved when
+ * the note is shown.
+ */
+const reference = /\{\{\s*([^{}\s]+)\s*\}\}/g;
+/** The note in the pieces it is shown in: stretches of text and what they refer to. */
+export const partsOfNote = (note) => {
+    const parts = [];
+    let read = 0;
+    for (const match of note.matchAll(reference)) {
+        const at = match.index ?? 0;
+        if (at > read)
+            parts.push({ type: 'text', text: note.slice(read, at) });
+        parts.push({ type: 'reference', id: match[1] });
+        read = at + match[0].length;
+    }
+    if (read < note.length)
+        parts.push({ type: 'text', text: note.slice(read) });
+    return parts;
+};
+/** The ids a note refers to, in the order it names them. */
+export const referencesInNote = (note) => partsOfNote(note).flatMap(part => part.type === 'reference' ? [part.id] : []);
+/**
+ * The note as it reads, with every reference resolved to the name the
+ * edition gives that entity. A reference nothing answers to keeps its id,
+ * so that the gap is visible rather than silent.
+ */
+export const resolveNote = (note, nameOf) => partsOfNote(note)
+    .map(part => part.type === 'text' ? part.text : nameOf(part.id) ?? part.id)
+    .join('');

package/lib/schema.json

@@ -2482,7 +2482,7 @@
             "type": "object"
         },
         "Version": {
-            "description": "A version is defined by the sum of edits applied to the version it is based on. For simple identification, a siglum is given to each version.",
+            "description": "A version is defined by the sum of edits applied to the version it is based on. What it is called is not stored with it: `siglaOf` reads the sigla off the stemma, so that a label never outlives the arrangement it describes.",
             "properties": {
                 "basedOn": {
                     "description": "The versions this one is held to derive from, each under the belief it rests on. The text is read against the principal one (`principalDerivationOf`); the others stand as hypotheses, such as a contamination. A version that names none represents the mother roll.",
@@ -2513,7 +2513,8 @@
                     "type": "array"
                 },
                 "siglum": {
-                    "description": "A short siglum to identify the version, e.g. \"A\" or \"B2\". A siglum is given once and not changed: its letter names the line the version was first recognised in, its number counts the versions admitted to that line. Where later work places the version elsewhere in the stemma, `basedOn` changes and the siglum stays.",
+                    "deprecated": true,
+                    "description": "A label a document carries from before the sigla were computed. Nothing should write one here and nothing should show one: what a version is called comes from `siglaOf`.",
                     "type": "string",
                     "ontology": "reo:siglum"
                 },
@@ -2536,7 +2537,6 @@
             "required": [
                 "@id",
                 "motivations",
-                "siglum",
                 "system",
                 "@type"
             ],

package/lib/sigla.d.ts

@@ -0,0 +1,19 @@
+import { Edition } from './Edition';
+/**
+ * The siglum of every version, as the stemma stands. The letter names the
+ * reproducing system a version is coded for, the number counts the
+ * generations within that system, and a number after a dot marks a branch
+ * that leaves a generation. A version coded for another system than the
+ * one it derives from starts that system's next number, since nothing in
+ * that system precedes it.
+ *
+ * The main line runs through the child that has descendants of its own;
+ * where several have, the one with the most, and where none has, the line
+ * ends and the children hang off it as branches. So a siglum says where a
+ * version sits in this stemma, and it is computed anew when the stemma
+ * changes. Nothing should cite one without saying which state it belongs
+ * to.
+ */
+export declare const siglaOf: (edition: Pick<Edition, 'versions'>) => ReadonlyMap<string, string>;
+/** The siglum of one version as the stemma stands, or nothing where the edition holds no such version. */
+export declare const siglumOf: (edition: Pick<Edition, 'versions'>, versionId: string) => string | undefined;

package/lib/sigla.js

@@ -0,0 +1,98 @@
+import { idOf } from './Assumption';
+import { systemIdOf } from './TrackerBar';
+import { trackerBarOf } from './systems';
+import { principalDerivationOf } from './Version';
+/** The letter the versions of a system are labelled with. */
+const letters = new Map([
+    ['welte-t100', 'R'],
+    ['welte-green', 'G'],
+    ['welte-licensee', 'L']
+]);
+/** The letter of a version's system, from the systems the library knows, else from the system's name. */
+const letterOf = (version) => {
+    const bar = trackerBarOf(version.system);
+    const known = bar && letters.get(bar.id);
+    if (known)
+        return known;
+    const name = (bar?.name ?? version.system?.name ?? '').replace(/[^A-Za-z]/g, '');
+    return (name.charAt(0) || 'X').toUpperCase();
+};
+/**
+ * The siglum of every version, as the stemma stands. The letter names the
+ * reproducing system a version is coded for, the number counts the
+ * generations within that system, and a number after a dot marks a branch
+ * that leaves a generation. A version coded for another system than the
+ * one it derives from starts that system's next number, since nothing in
+ * that system precedes it.
+ *
+ * The main line runs through the child that has descendants of its own;
+ * where several have, the one with the most, and where none has, the line
+ * ends and the children hang off it as branches. So a siglum says where a
+ * version sits in this stemma, and it is computed anew when the stemma
+ * changes. Nothing should cite one without saying which state it belongs
+ * to.
+ */
+export const siglaOf = (edition) => {
+    const versions = edition.versions;
+    const byId = new Map(versions.map(version => [version.id, version]));
+    const parentOf = (version) => {
+        const principal = principalDerivationOf(version);
+        const parent = principal && byId.get(idOf(principal));
+        return parent === version ? undefined : parent;
+    };
+    const children = new Map();
+    const roots = [];
+    for (const version of versions) {
+        const parent = parentOf(version);
+        if (!parent)
+            roots.push(version);
+        else
+            children.set(parent.id, [...(children.get(parent.id) ?? []), version]);
+    }
+    const counted = new Map();
+    const descendants = (version) => {
+        const known = counted.get(version.id);
+        if (known !== undefined)
+            return known;
+        counted.set(version.id, 0);
+        const count = (children.get(version.id) ?? []).reduce((sum, child) => sum + 1 + descendants(child), 0);
+        counted.set(version.id, count);
+        return count;
+    };
+    /** The child the main line runs through: the one of the same system carrying most of the stemma. */
+    const mainChildOf = (version) => (children.get(version.id) ?? [])
+        .filter(child => systemIdOf(child.system) === systemIdOf(version.system))
+        .sort((one, other) => descendants(other) - descendants(one))[0];
+    const sigla = new Map();
+    const taken = new Map();
+    const branches = new Map();
+    const nextIn = (letter) => {
+        const number = (taken.get(letter) ?? 0) + 1;
+        taken.set(letter, number);
+        return `${letter}${number}`;
+    };
+    const branchOf = (version) => {
+        const number = (branches.get(version.id) ?? 0) + 1;
+        branches.set(version.id, number);
+        return `${sigla.get(version.id)}.${number}`;
+    };
+    const queue = roots.map(version => {
+        sigla.set(version.id, nextIn(letterOf(version)));
+        return { version, onMainLine: true };
+    });
+    while (queue.length > 0) {
+        const { version, onMainLine } = queue.shift();
+        const main = mainChildOf(version);
+        for (const child of children.get(version.id) ?? []) {
+            if (sigla.has(child.id))
+                continue;
+            const entersSystem = systemIdOf(child.system) !== systemIdOf(version.system);
+            const continuesLine = onMainLine && child === main;
+            sigla.set(child.id, entersSystem || continuesLine ? nextIn(letterOf(child)) : branchOf(version));
+            queue.push({ version: child, onMainLine: continuesLine });
+        }
+    }
+    return sigla;
+};
+/** The siglum of one version as the stemma stands, or nothing where the edition holds no such version. */
+export const siglumOf = (edition, versionId) => siglaOf(edition).get(versionId);

package/lib/systems/welteT98/system.d.ts

@@ -18,11 +18,19 @@ export type { WelteT98Instrument, WelteT98InstrumentName } from "welte-mignon-em
  * difference between the two, in the printed ordinate both scales share, is how
  * far the transfer of a red reading onto the green mechanism succeeded.
  *
- * Neither has been fitted yet, so both groups are empty and what a playback runs
- * on until then is the third group: the **unfitted** starting values, arithmetic
- * from Welte's regulation controls and the T-100 consensus with no green roll
- * behind any of it. A curve produced with them says so in its own `instrument`
- * field, and nothing should be published from them.
+ * Both are now fitted, on `welte-mignon-emulator` 1.1.0: five genuine
+ * instruments, one per lined green roll that could be read, a consensus across
+ * them, and the derived instrument for the one recording issued on both scales.
+ * The **unfitted** starting values remain as a third group, arithmetic from
+ * Welte's regulation controls with no green roll behind any of it, and a curve
+ * produced with them says so in its own `instrument` field.
+ *
+ * **Prefer a roll's own instrument where the roll is one of the five.** The
+ * green instruments disagree with one another far more than the red ones do:
+ * the consensus is held out at 0.121 on the bass where the per-roll instruments
+ * are 0.029 to 0.066, because a shared mechanism describes none of them well.
+ * That spread is a property of the instruments rather than of the fit, and
+ * Gottschewski's finding that they were out of regulation is visible in it.
  */
 export declare const instruments: {
     genuine: Readonly<Partial<Record<"consensus" | import("welte-mignon-emulator/t98").GenuineRoll, import("welte-mignon-emulator/t98").WelteT98Instrument>>>;
@@ -112,8 +120,9 @@ export declare const secondsAt: (spool: Spool, place: Millimeters) => Seconds;
  * permanently open bore 100, and a long perforation on the bass sforzando-piano
  * line sends the roll back.
  *
- * Its constants are **not fitted**. `instruments.genuine` and
- * `instruments.derived` are empty until their fits run, and what a playback runs
- * on until then is the unfitted starting values, which every curve says.
+ * Its constants are fitted to the drawn nuance lines of five green rolls, and a
+ * playback runs on the consensus across them unless the caller names another
+ * instrument. Where the roll being played is one of the five, its own instrument
+ * is the better choice and `instruments.genuine` carries it.
  */
 export declare const welteT98System: ReproducingSystem<WelteT98Options>;

package/lib/systems/welteT98/system.js

@@ -17,11 +17,19 @@ import { defaultVelocityMap, velocityOf } from "../velocity";
  * difference between the two, in the printed ordinate both scales share, is how
  * far the transfer of a red reading onto the green mechanism succeeded.
  *
- * Neither has been fitted yet, so both groups are empty and what a playback runs
- * on until then is the third group: the **unfitted** starting values, arithmetic
- * from Welte's regulation controls and the T-100 consensus with no green roll
- * behind any of it. A curve produced with them says so in its own `instrument`
- * field, and nothing should be published from them.
+ * Both are now fitted, on `welte-mignon-emulator` 1.1.0: five genuine
+ * instruments, one per lined green roll that could be read, a consensus across
+ * them, and the derived instrument for the one recording issued on both scales.
+ * The **unfitted** starting values remain as a third group, arithmetic from
+ * Welte's regulation controls with no green roll behind any of it, and a curve
+ * produced with them says so in its own `instrument` field.
+ *
+ * **Prefer a roll's own instrument where the roll is one of the five.** The
+ * green instruments disagree with one another far more than the red ones do:
+ * the consensus is held out at 0.121 on the bass where the per-roll instruments
+ * are 0.029 to 0.066, because a shared mechanism describes none of them well.
+ * That spread is a property of the instruments rather than of the fit, and
+ * Gottschewski's finding that they were out of regulation is visible in it.
  */
 export const instruments = { genuine: GENUINE, derived: DERIVED, unfitted: { 'starting-values': STARTING_VALUES } };
 export const instrumentNames = [
@@ -51,8 +59,8 @@ export const pedalPresets = {
 export const pedalPresetOf = (pedals) => Object.keys(pedalPresets).find(name => sameParameters(pedalPresets[name], pedals));
 export const defaultWelteT98Options = {
     spool: WELTE_T98_SPOOL,
-    nuance: nuanceOf(STARTING_VALUES),
-    instrument: { unfitted: 'starting-values' },
+    nuance: nuanceOf(GENUINE.consensus),
+    instrument: { genuine: 'consensus' },
     pedals: pedalPresets.damping,
     velocity: defaultVelocityMap,
     pedalMode: 'continuous',
@@ -233,9 +241,10 @@ const perform = (events, options, roll) => {
  * permanently open bore 100, and a long perforation on the bass sforzando-piano
  * line sends the roll back.
  *
- * Its constants are **not fitted**. `instruments.genuine` and
- * `instruments.derived` are empty until their fits run, and what a playback runs
- * on until then is the unfitted starting values, which every curve says.
+ * Its constants are fitted to the drawn nuance lines of five green rolls, and a
+ * playback runs on the consensus across them unless the caller names another
+ * instrument. Where the roll being played is one of the five, its own instrument
+ * is the better choice and `instruments.genuine` carries it.
  */
 export const welteT98System = {
     name: 'Welte-Mignon T98',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {
@@ -51,10 +51,10 @@
     "typescript": "^7.0.2",
     "vite": "^8.2.2",
     "vitest": "^5.0.0",
-    "welte-mignon-emulator": "^1.0.0"
+    "welte-mignon-emulator": "^1.1.0"
   },
   "peerDependencies": {
-    "welte-mignon-emulator": "^1.0.0"
+    "welte-mignon-emulator": "^1.1.0"
   },
   "peerDependenciesMeta": {
     "welte-mignon-emulator": {