linked-rolls 0.70.0 → 0.72.0

package/lib/ops/versions.js

@@ -30,6 +30,7 @@ const dropDerivations = (version, matches) => {
  * Makes the version stand on its own: what it inherited becomes its
  * own insertions, and its derivations go, the hypotheses among them,
  * with the motivations that belonged to them.
+ * @category Operations
  */
 export const detachVersion = (versionId) => reading(edition => {
     const edits = snapshotOf(edition, versionId).map(insertion);
@@ -43,6 +44,7 @@ export const detachVersion = (versionId) => reading(edition => {
  * Takes the version out. Whatever read its text against it comes to
  * stand on its own, a hypothesis that something derives from it goes,
  * and so does a copy's statement that it carries the version.
+ * @category Operations
  */
 export const removeVersion = (versionId) => reading(edition => {
     const detachments = edition.versions
@@ -56,9 +58,15 @@ export const removeVersion = (versionId) => reading(edition => {
         draft.versions = without(draft.versions, version => version.id === versionId);
     };
 });
-/** Takes the symbols out of the version's own insertions, and the edits that had nothing else. */
+/**
+ * Takes the symbols out of the version's own insertions, and the edits that had nothing else.
+ * @category Operations
+ */
 export const removeSymbols = (versionId, symbolIds) => onVersion(versionId, version => dropInsertions(version, new Set(symbolIds)));
-/** Moves the edits into a new version based on this one. */
+/**
+ * Moves the edits into a new version based on this one.
+ * @category Operations
+ */
 export const deriveVersion = (versionId, editIds) => onVersion(versionId, (version, draft) => {
     const chosen = new Set(editIds);
     const moved = editsOf(version).filter(edit => chosen.has(edit.id));
@@ -79,6 +87,7 @@ export const deriveVersion = (versionId, editIds) => onVersion(versionId, (versi
  * unless the belief holds this one more certain. A version derives from
  * itself, twice from one parent, or from one of its own descendants in
  * no statement.
+ * @category Operations
  */
 export const stateDerivation = (versionId, parentId, belief) => onVersion(versionId, (version, draft) => {
     const derivations = stateOf(version).basedOn ?? [];
@@ -88,7 +97,10 @@ export const stateDerivation = (versionId, parentId, belief) => onVersion(versio
         return;
     version.basedOn = [...derivations, referenceHeld(parentId, belief)];
 });
-/** Takes back the hypothesis that the version derives from the parent; the principal derivation goes with `detachVersion`. */
+/**
+ * Takes back the hypothesis that the version derives from the parent; the principal derivation goes with `detachVersion`.
+ * @category Operations
+ */
 export const clearDerivation = (versionId, parentId) => onVersion(versionId, version => {
     if (readsAgainst(stateOf(version), parentId))
         return;

package/lib/readers/phillipsEroll.d.ts

@@ -49,8 +49,15 @@ import { Millimeters, Seconds } from "../model/Quantity.js";
  * The two rules collide on one number, the lowest note of the T-100
  * sharing 24 with the tenth position. Notes win there, the note block
  * being the larger claim; none of his samples uses the number at all.
+ * @category Sources
  */
 export declare const CONTROL_OFFSET: Readonly<Record<string, number>>;
+/**
+ * How `readFromPhillipsEroll` reads a file: the bar it numbers its
+ * positions by, where its expression numbers sit, how time is put back
+ * onto the paper, and what the reader added to the chains.
+ * @category Sources
+ */
 export interface PhillipsErollOptions {
     /**
      * The bar the file numbers its positions by, which is the bar of
@@ -87,7 +94,11 @@ export interface PhillipsErollOptions {
  * Reads one of his e-roll files as a copy of the roll, in millimetres
  * of paper, on the bar it was cut for and in that bar's numbering. A
  * position the bar does not read is left out, as the bar would leave it.
+ * @category Sources
  */
 export declare function readFromPhillipsEroll(buffer: ArrayBuffer, { system, controlOffset, placeAt, extension }?: PhillipsErollOptions): RollCopy;
-/** The bars his files are known to be numbered by. */
+/**
+ * The bars his files are known to be numbered by.
+ * @category Sources
+ */
 export declare const phillipsSystems: readonly TrackerBar[];

package/lib/readers/phillipsEroll.js

@@ -54,6 +54,7 @@ import { inMetersPerMinute, mm, seconds, track } from "../model/Quantity.js";
  * The two rules collide on one number, the lowest note of the T-100
  * sharing 24 with the tenth position. Notes win there, the note block
  * being the larger claim; none of his samples uses the number at all.
+ * @category Sources
  */
 export const CONTROL_OFFSET = {
     'welte-t100': 14,
@@ -133,6 +134,7 @@ const controlOffsetOf = (system, given) => {
  * Reads one of his e-roll files as a copy of the roll, in millimetres
  * of paper, on the bar it was cut for and in that bar's numbering. A
  * position the bar does not read is left out, as the bar would leave it.
+ * @category Sources
  */
 export function readFromPhillipsEroll(buffer, { system = welteT100, controlOffset, placeAt, extension } = {}) {
     const file = read(new Uint8Array(buffer));
@@ -173,5 +175,8 @@ export function readFromPhillipsEroll(buffer, { system = welteT100, controlOffse
         shortenChains(extension, copy);
     return copy;
 }
-/** The bars his files are known to be numbered by. */
+/**
+ * The bars his files are known to be numbered by.
+ * @category Sources
+ */
 export const phillipsSystems = [welteT100, welteLicensee];

package/lib/readers/spencerBar.d.ts

@@ -6,8 +6,14 @@ import { TrackerBar } from "../systems/TrackerBar.js";
  * 640 Hz), and the tempo counts tenths of a foot per minute, which puts
  * 400 rows on an inch. This is the file's own calibration; whether the
  * scanner kept it is for an alignment with other copies to tell.
+ * @category Sources
  */
 export declare const SPENCER_ROWS_PER_INCH = 400;
+/**
+ * How `readFromSpencerBar` reads a file: the rows of its image on an
+ * inch of paper, and the bar it numbers its positions by.
+ * @category Sources
+ */
 export interface SpencerBarOptions {
     /** Rows of the image on an inch of paper. */
     rowsPerInch?: number;
@@ -21,13 +27,18 @@ export interface SpencerBarOptions {
  * Reads the copy on the bar it was cut for, whose numbering it keeps.
  * A chain on a position that bar does not read is left out, as the bar
  * would leave it.
+ * @category Sources
  */
 export declare function readFromSpencerBar(buffer: ArrayBuffer, { rowsPerInch, system }?: SpencerBarOptions): RollCopy;
 /**
  * The `.ann` file beside a `.bar` holds the player's settings for the
  * roll as lines of "/key:   value": title, composer, pianist, roll
  * number and class, and the tempo the roll is played at.
+ * @category Sources
  */
 export declare const readSpencerAnn: (text: string) => ReadonlyMap<string, string>;
-/** The paper speed a `.ann` states through its roll tempo, where it states one. */
+/**
+ * The paper speed a `.ann` states through its roll tempo, where it states one.
+ * @category Sources
+ */
 export declare const paperSpeedOfSpencerAnn: (ann: ReadonlyMap<string, string>) => PaperSpeed | undefined;

package/lib/readers/spencerBar.js

@@ -22,6 +22,7 @@ const END_OF_EVENTS = 0xFF;
  * 640 Hz), and the tempo counts tenths of a foot per minute, which puts
  * 400 rows on an inch. This is the file's own calibration; whether the
  * scanner kept it is for an alignment with other copies to tell.
+ * @category Sources
  */
 export const SPENCER_ROWS_PER_INCH = 400;
 const byteAt = (bytes, at) => {
@@ -82,6 +83,7 @@ const holesOf = (events) => {
  * Reads the copy on the bar it was cut for, whose numbering it keeps.
  * A chain on a position that bar does not read is left out, as the bar
  * would leave it.
+ * @category Sources
  */
 export function readFromSpencerBar(buffer, { rowsPerInch = SPENCER_ROWS_PER_INCH, system = welteLicensee } = {}) {
     const bytes = new Uint8Array(buffer);
@@ -121,6 +123,7 @@ export function readFromSpencerBar(buffer, { rowsPerInch = SPENCER_ROWS_PER_INCH
  * The `.ann` file beside a `.bar` holds the player's settings for the
  * roll as lines of "/key:   value": title, composer, pianist, roll
  * number and class, and the tempo the roll is played at.
+ * @category Sources
  */
 export const readSpencerAnn = (text) => new Map(text.split(/\r?\n/)
     .map(line => line.match(/^\/(\w+):\s*(.*?)\s*$/))
@@ -128,7 +131,10 @@ export const readSpencerAnn = (text) => new Map(text.split(/\r?\n/)
     .map(([, key, value]) => [key, value]));
 /** A roll tempo counts tenths of a foot per minute: tempo 83 runs the roll at 8.3 feet a minute. */
 const TEMPO_PER_FOOT_PER_MINUTE = 10;
-/** The paper speed a `.ann` states through its roll tempo, where it states one. */
+/**
+ * The paper speed a `.ann` states through its roll tempo, where it states one.
+ * @category Sources
+ */
 export const paperSpeedOfSpencerAnn = (ann) => {
     const tempo = parseFloat(ann.get('roll_tempo') ?? '');
     if (isNaN(tempo) || tempo <= 0)

package/lib/readers/stanfordAton.d.ts

@@ -1,6 +1,12 @@
 import { RollCopy } from "../model/RollCopy.js";
 import { TrackerBar } from "../systems/TrackerBar.js";
 import { Track } from "../model/Quantity.js";
+/**
+ * How `readFromStanfordAton` reads an analysis file: how its hole
+ * numbering is shifted onto the tracker bar, which bar the roll was cut
+ * for, and where its scan can be seen.
+ * @category Sources
+ */
 export interface StanfordAtonOptions {
     /**
      * Added to the scanning software's hole numbering to reach the
@@ -21,4 +27,13 @@ export interface StanfordAtonOptions {
      */
     scan?: string;
 }
+/**
+ * Reads a hole analysis of a scan, in the ATON format of Stanford's
+ * SUPRA collection, as a copy of the roll: its chains of holes in
+ * millimetres of paper on the bar it was cut for, its edge tears, its
+ * dimensions and hole separation as the analysis measured them, and how
+ * the scan relates to the bar. A position the bar does not read is left
+ * out, as the bar would leave it.
+ * @category Sources
+ */
 export declare function readFromStanfordAton(atonString: string, { trackShift, system, scan }?: StanfordAtonOptions): RollCopy;

package/lib/readers/stanfordAton.js

@@ -139,6 +139,15 @@ const measurementOf = (rollinfo) => {
 const takenBy = (measurement) => (value) => measurement
     ? { ...value, '@annotation': { id: v4(), belief: { type: 'belief', id: v4(), certainty: 'true', reasons: [measurement] } } }
     : value;
+/**
+ * Reads a hole analysis of a scan, in the ATON format of Stanford's
+ * SUPRA collection, as a copy of the roll: its chains of holes in
+ * millimetres of paper on the bar it was cut for, its edge tears, its
+ * dimensions and hole separation as the analysis measured them, and how
+ * the scan relates to the bar. A position the bar does not read is left
+ * out, as the bar would leave it.
+ * @category Sources
+ */
 export function readFromStanfordAton(atonString, { trackShift, system = welteT100, scan } = {}) {
     const parser = new AtonParser();
     const json = parser.parse(atonString);

package/lib/schema.json

@@ -490,6 +490,7 @@
             "ontology": "lrmoo:R76 is derivative of"
         },
         "DriveId": {
+            "description": "The IRI of a drive the type vocabulary declares.",
             "enum": [
                 "https://w3id.org/reo/type/drive/ram-head",
                 "https://w3id.org/reo/type/drive/asynchronous"
@@ -927,6 +928,14 @@
                     "description": "The person who carried out this activity.",
                     "ontology": "crm:P14 carried out by"
                 },
+                "applies": {
+                    "description": "The rules the inference draws its conclusion by, by IRI: a regularity of how the rolls were edited, such as that the same addition at the same place is not made twice independently, a default, such as that copies were not made from two exemplars, or a method, such as how the tolerance of a collation is found. The rules are stated once where they are published, and each inference names those it follows, so that a reader can see what a conclusion rests on besides its premises, and which conclusions rest on a rule.",
+                    "items": {
+                        "type": "string"
+                    },
+                    "type": "array",
+                    "ontology": "crminf:J3 applied"
+                },
                 "note": {
                     "description": "A free-text note providing additional context.",
                     "type": "string",
@@ -3396,6 +3405,7 @@
             "ontology": "crmdig:D14 Software"
         },
         "SourceKind": {
+            "description": "A kind of source a copy's features can be read from, from the paper itself to a sound recording of the copy being played.",
             "enum": [
                 "roll",
                 "scan",

package/lib/shared/utils.d.ts

@@ -1,4 +1,8 @@
 export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * An object that says by its type which kind of entity it is.
+ * @category Format types
+ */
 export type WithType<T extends string> = {
     /**
      * The type discriminator for this object.
@@ -6,6 +10,10 @@ export type WithType<T extends string> = {
      */
     readonly type: T;
 };
+/**
+ * An object the edition identifies, so that others can refer to it.
+ * @category Format types
+ */
 export type WithId = {
     /**
      * A unique identifier for this object.
@@ -16,6 +24,10 @@ export type WithId = {
 export declare const isDateString: (value: unknown) => value is string;
 /** The items by the key each of them gives, every group in the order its first item came in. */
 export declare const groupBy: <T>(items: readonly T[], keyOf: (item: T) => string) => Map<string, T[]>;
+/**
+ * An object that may carry a note in free text.
+ * @category Format types
+ */
 export type WithNote = {
     /**
      * A free-text note providing additional context.

package/lib/spec/context.json

@@ -65,6 +65,10 @@
                 "used": {
                     "@id": "crm:P16_used_specific_object",
                     "@type": "@id"
+                },
+                "applies": {
+                    "@id": "crminf:J3_applied",
+                    "@type": "@id"
                 }
             }
         },

package/lib/systems/ReproducingSystem.d.ts

@@ -6,6 +6,7 @@ import { MetersPerMinute, Millimeters, Seconds } from "../model/Quantity.js";
  * A note or expression of a version with the dimensions of its carriers
  * averaged in and the editorial assumptions applied, which is all a
  * performance needs to know of a symbol.
+ * @category Systems and emulation
  */
 export type NegotiatedEvent = Omit<Note | Expression, 'carriers'> & Pick<HoleChain, 'horizontal' | 'vertical'>;
 interface PerformedRollFeature<T> {
@@ -18,21 +19,41 @@ interface PerformedNoteEvent<T> extends PerformedRollFeature<T> {
     pitch: number;
     velocity: number;
 }
+/**
+ * A note struck, at the velocity the performance gives it.
+ * @category Systems and emulation
+ */
 export interface PerformedNoteOnEvent extends PerformedNoteEvent<'noteOn'> {
 }
+/**
+ * A note released.
+ * @category Systems and emulation
+ */
 export interface PerformedNoteOffEvent extends PerformedNoteEvent<'noteOff'> {
 }
 /**
  * One step of a pedal. A pedal driven by a bellows takes time to travel,
  * so a single command results in a run of these; `performs` is the
  * command whose reading the step follows from.
+ * @category Systems and emulation
  */
 export interface PerformedPedalEvent extends PerformedRollFeature<'damper' | 'hammerRail'> {
     /** 0 with the pedal up and 127 with it fully down. */
     value: number;
 }
+/**
+ * What a performance does at a moment: a note struck or released, or a
+ * step of a pedal.
+ * @category Systems and emulation
+ */
 export type AnyPerformedRollFeature = PerformedNoteOnEvent | PerformedNoteOffEvent | PerformedPedalEvent;
-interface CurveSamples {
+/**
+ * A curve sampled along the roll: where each sample lies on the paper,
+ * when it passes the tracker bar, and how far the bellows or the pedal
+ * has travelled there.
+ * @category Systems and emulation
+ */
+export interface CurveSamples {
     readonly name: string;
     /** Paper position of each sample, in mm from the beginning of the roll. */
     readonly place: Float64Array;
@@ -53,7 +74,10 @@ interface CurveSamples {
      */
     readonly travel: Float64Array;
 }
-/** The dynamics of one part of the keyboard, with the velocity the travel maps onto. */
+/**
+ * The dynamics of one part of the keyboard, with the velocity the travel maps onto.
+ * @category Systems and emulation
+ */
 export type DynamicsCurve = CurveSamples & {
     readonly kind: 'dynamics';
     readonly velocity: Float64Array;
@@ -66,11 +90,24 @@ export type DynamicsCurve = CurveSamples & {
      */
     readonly instrument: string;
 };
+/**
+ * How far one pedal has travelled along the roll, 0 with it up and 1
+ * with it down.
+ * @category Systems and emulation
+ */
 export type PedalCurve = CurveSamples & {
     readonly kind: 'pedal';
 };
+/**
+ * A curve a performance yields: the dynamics of one half of the
+ * keyboard, or the travel of a pedal.
+ * @category Systems and emulation
+ */
 export type EmulatedCurve = DynamicsCurve | PedalCurve;
-/** What the edition records about the roll that a mechanism may want to know. */
+/**
+ * What the edition records about the roll that a mechanism may want to know.
+ * @category Systems and emulation
+ */
 export type RollProperties = {
     /** Diameter of the punches, where the copies record it. */
     punchDiameter?: Millimeters;
@@ -114,6 +151,11 @@ export type RollProperties = {
      */
     toOwnPaper?: number;
 };
+/**
+ * What a reproducing system made of the events of a version: the events
+ * it performed, and the curves of its dynamics and pedals.
+ * @category Systems and emulation
+ */
 export type Performance = {
     readonly events: readonly AnyPerformedRollFeature[];
     readonly curves: readonly EmulatedCurve[];
@@ -124,6 +166,7 @@ export type Performance = {
  * Implementations live outside the core of this library, so that it does
  * not depend on any one instrument's model; `linked-rolls/welte-t100` is
  * the first.
+ * @category Systems and emulation
  */
 export interface ReproducingSystem<Options extends object> {
     readonly name: string;

package/lib/systems/TrackerBar.d.ts

@@ -4,11 +4,13 @@ import { Millimeters, SpeedMeasure, Track } from "../model/Quantity.js";
 /**
  * What a tracker bar position does: sound a note, or operate one of
  * the expression valves on the bass or the treble side.
+ * @category Systems and emulation
  */
 export type TrackRole = 'bass-expression' | 'note' | 'treble-expression';
 /**
  * A contiguous block of tracker bar positions serving one role.
  * Both bounds are inclusive.
+ * @category Systems and emulation
  */
 export interface TrackArea {
     readonly role: TrackRole;
@@ -18,11 +20,13 @@ export interface TrackArea {
 /**
  * How a scale words a function: as a command that turns it on, one that
  * cancels it, or one that holds it for as long as it lasts.
+ * @category Systems and emulation
  */
 export type Spelling = 'on' | 'off' | 'held';
 /**
  * What a word of a scale operates, rather than the word itself, so that
  * two scales can be compared at all.
+ * @category Systems and emulation
  */
 export interface Operation {
     /** The function operated, named the same wherever a scale has it. */
@@ -36,8 +40,21 @@ export interface Operation {
      */
     sided: boolean;
 }
+/**
+ * What a position in the note block reads: a note of one pitch.
+ * @category Systems and emulation
+ */
 export type NoteMeaning = Pick<Note, 'type' | 'pitch'>;
+/**
+ * What an expression position reads: an expression type, on the side of
+ * the keyboard the position serves.
+ * @category Systems and emulation
+ */
 export type ExpressionMeaning = Pick<Expression, 'type' | 'expressionType' | 'scope'>;
+/**
+ * What a position of the bar reads: a note or an expression.
+ * @category Systems and emulation
+ */
 export type TrackMeaning = NoteMeaning | ExpressionMeaning;
 /**
  * Describes a tracker bar. Track numbers are 1-based and count from
@@ -48,6 +65,7 @@ export type TrackMeaning = NoteMeaning | ExpressionMeaning;
  * Anything that needs to know where the note block ends, which side
  * an expression belongs to, or how a track maps to a pitch, should
  * ask the tracker bar rather than repeat the boundaries.
+ * @category Systems and emulation
  */
 export interface TrackerBar {
     /**
@@ -129,13 +147,23 @@ export interface TrackerBar {
  * What a position says, as a key. Two bars read the same thing exactly
  * where their keys agree, which is what lets a symbol cross from one
  * system to another and what decides whether two symbols collate.
+ * @category Systems and emulation
  */
 export declare const keyOf: (meaning: TrackMeaning) => string;
-/** The roll system a tracker bar belongs to, as the roll metadata states it. */
+/**
+ * The roll system a tracker bar belongs to, as the roll metadata states it.
+ * @category Vocabulary
+ */
 export declare const systemOf: (bar: TrackerBar) => Concept;
-/** The identifier of a system the type vocabulary knows, from the IRI naming it. */
+/**
+ * The identifier of a system the type vocabulary knows, from the IRI naming it.
+ * @category Vocabulary
+ */
 export declare const systemIdIn: (id: string | undefined) => string | undefined;
-/** The identifier of a system the type vocabulary knows, from its concept. */
+/**
+ * The identifier of a system the type vocabulary knows, from its concept.
+ * @category Vocabulary
+ */
 export declare const systemIdOf: (system: Concept | undefined) => string | undefined;
 /**
  * Where a roll's own content ends, as far as its perforations say.
@@ -144,12 +172,16 @@ export declare const systemIdOf: (system: Concept | undefined) => string | undef
  * the rewind is *punched*, not when the rewind pneumatic takes hold. The second
  * is a matter of valve lift and belongs to whatever performs the roll. Keeping
  * them apart is what lets collation and counting ask this without an emulator.
+ * @category Systems and emulation
  */
 export type RollEnd = {
     readonly at: Millimeters;
     readonly because: 'rewind';
 };
-/** Anything carrying a place on the roll and a position on the bar. */
+/**
+ * Anything carrying a place on the roll and a position on the bar.
+ * @category Systems and emulation
+ */
 export type PlacedOnBar = {
     readonly horizontal: {
         readonly from: Millimeters;
@@ -163,6 +195,7 @@ export type PlacedOnBar = {
  * Where a feature lies across the bar: one place, or a run of them where
  * `to` is given. Structural, so a feature's `vertical` passes as it is and
  * this module need know nothing about features.
+ * @category Systems and emulation
  */
 export type OnBar = {
     readonly from: Track;
@@ -172,6 +205,7 @@ export type OnBar = {
  * A tracker bar as written down, with its positions as plain numbers
  * in the bar's own 1-based numbering; `describeTrackerBar` gives them
  * their type.
+ * @category Systems and emulation
  */
 export interface TrackerBarSpec {
     id: string;
@@ -211,11 +245,18 @@ export interface TrackerBarSpec {
     /** How the system spells a single added accent; see `TrackerBar.accents`. */
     accents?: readonly (readonly string[])[];
 }
+/**
+ * The tracker bar a description gives, its positions typed and its
+ * readings worked out. Throws where the description names no rewind
+ * position, or names expression types its bar does not read.
+ * @category Systems and emulation
+ */
 export declare const describeTrackerBar: (spec: TrackerBarSpec) => TrackerBar;
 /**
  * Puts a position of one bar onto the position of another that reads
  * the same thing, or nowhere when the other bar does not read it. This
  * is how a copy read in one system's numbering is put into another's,
  * as the migration does for a Licensee copy stored on T-100 tracks.
+ * @category Systems and emulation
  */
 export declare const translationBetween: (from: TrackerBar, to: TrackerBar) => (position: Track) => Track | undefined;

package/lib/systems/TrackerBar.js

@@ -3,16 +3,26 @@ import { mm, track } from "../model/Quantity.js";
  * What a position says, as a key. Two bars read the same thing exactly
  * where their keys agree, which is what lets a symbol cross from one
  * system to another and what decides whether two symbols collate.
+ * @category Systems and emulation
  */
 export const keyOf = (meaning) => meaning.type === 'note'
     ? `note ${meaning.pitch}`
     : `expression ${meaning.scope} ${meaning.expressionType}`;
 const SYSTEM_IRI = 'https://w3id.org/reo/type/system/';
-/** The roll system a tracker bar belongs to, as the roll metadata states it. */
+/**
+ * The roll system a tracker bar belongs to, as the roll metadata states it.
+ * @category Vocabulary
+ */
 export const systemOf = (bar) => ({ id: SYSTEM_IRI + bar.id, name: bar.name, sameAs: [] });
-/** The identifier of a system the type vocabulary knows, from the IRI naming it. */
+/**
+ * The identifier of a system the type vocabulary knows, from the IRI naming it.
+ * @category Vocabulary
+ */
 export const systemIdIn = (id) => id?.startsWith(SYSTEM_IRI) ? id.slice(SYSTEM_IRI.length) : undefined;
-/** The identifier of a system the type vocabulary knows, from its concept. */
+/**
+ * The identifier of a system the type vocabulary knows, from its concept.
+ * @category Vocabulary
+ */
 export const systemIdOf = (system) => systemIdIn(system?.id);
 const areasOf = ({ notes, trackCount }) => [
     { role: 'bass-expression', from: track(1), to: track(notes.from - 1) },
@@ -32,6 +42,12 @@ const positionsBetween = (span) => {
     const [first, last] = [Math.min(...ends), Math.max(...ends)];
     return Array.from({ length: last - first + 1 }, (_, step) => track(first + step));
 };
+/**
+ * The tracker bar a description gives, its positions typed and its
+ * readings worked out. Throws where the description names no rewind
+ * position, or names expression types its bar does not read.
+ * @category Systems and emulation
+ */
 export const describeTrackerBar = (spec) => {
     const areas = areasOf(spec);
     const areaAt = (position) => areas.find(area => position >= area.from && position <= area.to)?.role;
@@ -108,6 +124,7 @@ export const describeTrackerBar = (spec) => {
  * the same thing, or nowhere when the other bar does not read it. This
  * is how a copy read in one system's numbering is put into another's,
  * as the migration does for a Licensee copy stored on T-100 tracks.
+ * @category Systems and emulation
  */
 export const translationBetween = (from, to) => (position) => {
     const meaning = from.meaningOf(position);

package/lib/systems/index.d.ts

@@ -1,12 +1,19 @@
 import { Concept } from "../model/Agent.js";
 import { TrackerBar } from "./TrackerBar.js";
-/** The tracker bars the library knows, the T-100 first as the usual one. */
+/**
+ * The tracker bars the library knows, the T-100 first as the usual one.
+ * @category Systems and emulation
+ */
 export declare const trackerBars: readonly TrackerBar[];
-/** The bar of a system the type vocabulary knows, from its concept. */
+/**
+ * The bar of a system the type vocabulary knows, from its concept.
+ * @category Systems and emulation
+ */
 export declare const trackerBarOf: (system: Concept | undefined) => TrackerBar | undefined;
 /**
  * The bar a copy is read by where it names no system of its own: every
  * copy was read by the T-100's before the systems were told apart, and
  * `reservationsAbout` reports a copy that still relies on this.
+ * @category Systems and emulation
  */
 export declare const defaultTrackerBar: TrackerBar;

package/lib/systems/index.js

@@ -2,9 +2,15 @@ import { systemIdOf } from "./TrackerBar.js";
 import { welteT100 } from "./welteT100/bar.js";
 import { welteLicensee } from "./welteLicensee/bar.js";
 import { welteT98 } from "./welteT98/bar.js";
-/** The tracker bars the library knows, the T-100 first as the usual one. */
+/**
+ * The tracker bars the library knows, the T-100 first as the usual one.
+ * @category Systems and emulation
+ */
 export const trackerBars = [welteT100, welteLicensee, welteT98];
-/** The bar of a system the type vocabulary knows, from its concept. */
+/**
+ * The bar of a system the type vocabulary knows, from its concept.
+ * @category Systems and emulation
+ */
 export const trackerBarOf = (system) => {
     const id = systemIdOf(system);
     return trackerBars.find(bar => bar.id === id);
@@ -13,5 +19,6 @@ export const trackerBarOf = (system) => {
  * The bar a copy is read by where it names no system of its own: every
  * copy was read by the T-100's before the systems were told apart, and
  * `reservationsAbout` reports a copy that still relies on this.
+ * @category Systems and emulation
  */
 export const defaultTrackerBar = welteT100;

package/lib/systems/velocity.d.ts

@@ -19,6 +19,7 @@
  * suction-to-velocity relation "essentially logarithmic" (pp. 215 f.). The
  * default should change only once a red/green comparison has been run both ways
  * and the difference measured, and then for both systems at once.
+ * @category Systems and emulation
  */
 export type VelocityMap = {
     piano: number;

package/lib/systems/velocity.js

@@ -19,6 +19,7 @@
  * suction-to-velocity relation "essentially logarithmic" (pp. 215 f.). The
  * default should change only once a red/green comparison has been run both ways
  * and the difference measured, and then for both systems at once.
+ * @category Systems and emulation
  */
 /** midi2exp's three velocities, which is what the T-100's published results used. */
 export const defaultVelocityMap = { piano: 35, mezzoforte: 60, forte: 90 };