@libraz/libcantus 0.9.3 → 0.9.5

package/dist/{types-MGP29r3t.d.ts → types-BN6_Q9Kl.d.ts}

@@ -4,6 +4,8 @@
  * `modeMask12` is a 12-bit mask where bit `n` set means the pitch class
  * `(rootPc + n) % 12` belongs to the scale. Bit 0 (the root) is always set;
  * {@link maskFromOffsets} enforces this so the root is always a scale tone.
+ *
+ * @category Core
  */
 type KeyScale = {
     rootPc: number;
@@ -15,11 +17,18 @@ type KeyScale = {
  * velocity. This is the library-wide interchange shape for note events read
  * from or written to a DAW/MIDI track; the harmonizer's `MelodyNote` and the
  * analysis `VoiceNote` are specializations of it.
+ *
+ * @category Core
  */
 type NoteEvent = {
-    /** MIDI pitch (middle C = 60). */
+    /** MIDI pitch in [0, 127] (middle C = 60). */
     pitch: number;
-    /** Onset in quarter-note beats, absolute from the start of the timeline. */
+    /**
+     * Onset in quarter-note beats, absolute from the start of the timeline, and
+     * never negative: beat 0 is the start of the music, so a pickup bar is
+     * written as the first bar rather than as negative time. Shift the whole
+     * timeline if the downbeat needs to land later.
+     */
     startBeat: number;
     /** Duration in quarter-note beats. */
     durationBeat: number;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@libraz/libcantus",
-  "version": "0.9.3",
-  "description": "Pure-TypeScript music-theory and composition primitives (intervals, scales, chords).",
+  "version": "0.9.5",
+  "description": "Pure-TypeScript music theory engine: harmonic analysis, chord and scale vocabulary, voicing, reharmonization, and seeded part generation over MIDI note events.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "libraz",
@@ -20,16 +20,18 @@
     "scales",
     "intervals",
     "harmony",
-    "composition"
+    "composition",
+    "midi",
+    "chord-detection",
+    "voicing",
+    "reharmonization",
+    "arrangement",
+    "generative-music"
   ],
   "engines": {
     "node": ">=22 <23"
   },
-  "packageManager": "yarn@4.17.0",
-  "volta": {
-    "node": "22.22.3",
-    "yarn": "4.17.0"
-  },
+  "packageManager": "yarn@4.18.0",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -93,13 +95,32 @@
         "types": "./dist/model/index.d.cts",
         "default": "./dist/model/index.cjs"
       }
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "core": [
+        "./dist/core/index.d.ts"
+      ],
+      "theory": [
+        "./dist/theory/index.d.ts"
+      ],
+      "analyze": [
+        "./dist/analyze/index.d.ts"
+      ],
+      "generate": [
+        "./dist/generate/index.d.ts"
+      ],
+      "model": [
+        "./dist/model/index.d.ts"
+      ]
     }
   },
   "files": [
     "dist",
-    "src",
-    "tsconfig.json",
     "README.md",
+    "README_ja.md",
     "LICENSE"
   ],
   "sideEffects": false,
@@ -119,14 +140,14 @@
     "prepublishOnly": "yarn build"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.2",
+    "@biomejs/biome": "2.5.6",
     "@libraz/typedoc-theme": "^0.1.1",
-    "@vitest/coverage-v8": "4.1.9",
+    "@vitest/coverage-v8": "4.1.10",
     "tsup": "8.5.1",
     "typedoc": "0.28.20",
     "typedoc-plugin-extras": "4.0.1",
     "typedoc-plugin-mdn-links": "5.1.1",
     "typescript": "6.0.3",
-    "vitest": "4.1.9"
+    "vitest": "4.1.10"
   }
 }

package/dist/chunk-2ZWMSJH6.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/theory/harmony/index.ts"],"sourcesContent":["import { type Chord, chordToneRole } from '../chord/index.js';\n\n/**\n * Harmonic role a pitch plays within a chord.\n *\n * @category Functional Harmony\n */\nexport type HarmonyRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | 'tension' | 'doubling';\n\n/**\n * How firmly a pitch is locked to the chord's identity.\n *\n * - `identity`: moving it produces a different chord (the root).\n * - `quality`: moving it flips the chord quality (the third).\n * - `voicing`: it can move freely without changing chord identity or quality.\n *\n * @category Functional Harmony\n */\nexport type LockLevel = 'identity' | 'quality' | 'voicing';\n\n/**\n * A pitch's role, lock level, and owning chord.\n *\n * @category Functional Harmony\n */\nexport type VoicedRole = {\n  role: HarmonyRole;\n  lock: LockLevel;\n  belongsToChordId: number;\n};\n\n/**\n * Classify a pitch's harmonic role and lock level within a chord.\n *\n * The role comes from the pitch's interval class above the chord root: root (0),\n * third (3/4), fifth (6/7/8), seventh (10/11), and 9/11/13 tensions (2/5/9, and\n * the flat ninth 1). The root locks the chord identity, the third locks its\n * quality, and everything else is free voicing. In a suspended chord (a chord\n * whose intervals include a 4th (5) or 2nd (2) but no third), the suspended tone\n * takes the third's place as the quality-defining tone and is locked to\n * `quality`, since moving it changes the chord. Detecting an octave doubling\n * requires the surrounding voicing, which this single-pitch query does not carry,\n * so `doubling` is part of the type but not returned here.\n *\n * @param pitch MIDI pitch or bare pitch class.\n * @param chord The chord providing the root reference.\n * @param chordId Identifier stored on the result (defaults to 0).\n * @returns The pitch's role, lock level, and owning chord id.\n * @example\n * ```ts\n * import { roleOf, makeChord } from '@libraz/libcantus';\n * roleOf(64, makeChord(0, 'maj')); // E over C major\n * // { role: 'third', lock: 'quality', belongsToChordId: 0 }\n * ```\n * @category Functional Harmony\n */\nexport function roleOf(pitch: number, chord: Chord, chordId = 0): VoicedRole {\n  const interval = (((Math.trunc(pitch) - chord.rootPc) % 12) + 12) % 12;\n  const tones = new Set(chord.intervals.map((i) => ((i % 12) + 12) % 12));\n  const hasThird = tones.has(3) || tones.has(4);\n  const isSuspendedTone =\n    !hasThird && ((interval === 5 && tones.has(5)) || (interval === 2 && tones.has(2)));\n  const chordRole = chordToneRole(pitch, chord);\n  let role: HarmonyRole;\n  let lock: LockLevel;\n  if (isSuspendedTone) {\n    role = 'third'; // suspended tone occupies the third's quality-defining slot\n    lock = 'quality';\n  } else if (chordRole !== null) {\n    role = chordRole;\n    lock = chordRole === 'root' ? 'identity' : chordRole === 'third' ? 'quality' : 'voicing';\n  } else {\n    role = 'tension';\n    lock = 'voicing';\n  }\n  return { role, lock, belongsToChordId: chordId };\n}\n"],"mappings":";;;;;AAwDO,SAAS,OAAO,OAAe,OAAc,UAAU,GAAe;AAC3E,QAAM,aAAc,KAAK,MAAM,KAAK,IAAI,MAAM,UAAU,KAAM,MAAM;AACpE,QAAM,QAAQ,IAAI,IAAI,MAAM,UAAU,IAAI,CAAC,OAAQ,IAAI,KAAM,MAAM,EAAE,CAAC;AACtE,QAAM,WAAW,MAAM,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC;AAC5C,QAAM,kBACJ,CAAC,aAAc,aAAa,KAAK,MAAM,IAAI,CAAC,KAAO,aAAa,KAAK,MAAM,IAAI,CAAC;AAClF,QAAM,YAAY,cAAc,OAAO,KAAK;AAC5C,MAAI;AACJ,MAAI;AACJ,MAAI,iBAAiB;AACnB,WAAO;AACP,WAAO;AAAA,EACT,WAAW,cAAc,MAAM;AAC7B,WAAO;AACP,WAAO,cAAc,SAAS,aAAa,cAAc,UAAU,YAAY;AAAA,EACjF,OAAO;AACL,WAAO;AACP,WAAO;AAAA,EACT;AACA,SAAO,EAAE,MAAM,MAAM,kBAAkB,QAAQ;AACjD;","names":[]}