@blibliki/engine 0.4.2 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blibliki/engine",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "type": "module",
   "exports": {
     ".": {
@@ -22,8 +22,8 @@
   "dependencies": {
     "@julusian/midi": "^3.6.1",
     "es-toolkit": "^1.41.0",
-    "@blibliki/transport": "^0.4.2",
-    "@blibliki/utils": "^0.4.2"
+    "@blibliki/transport": "^0.5.1",
+    "@blibliki/utils": "^0.5.1"
   },
   "scripts": {
     "build": "tsup",

package/src/Engine.ts

@@ -269,6 +269,10 @@ export class Engine {
     return this.midiDeviceManager.findByName(name);
   }
 
+  findMidiDeviceByFuzzyName(name: string, threshold?: number) {
+    return this.midiDeviceManager.findByFuzzyName(name, threshold);
+  }
+
   onPropsUpdate(
     callback: <T extends ModuleType>(
       params: IModule<T> | IPolyModule<T>,

package/src/core/Note/index.ts

@@ -37,8 +37,15 @@ export default class Note implements INote {
   }
 
   static fromEvent(message: Message) {
-    const name = Notes[message.data[1] % 12];
-    const octave = Math.floor(message.data[1] / 12) - 2;
+    const dataByte = message.data[1];
+    if (dataByte === undefined) {
+      throw new Error("Invalid MIDI message: missing data byte");
+    }
+    const name = Notes[dataByte % 12];
+    if (!name) {
+      throw new Error(`Invalid MIDI note number: ${dataByte}`);
+    }
+    const octave = Math.floor(dataByte / 12) - 2;
 
     return new Note(`${name}${octave}`);
   }
@@ -95,9 +102,17 @@ export default class Note implements INote {
   }
 
   private fromString(string: string) {
-    const matches = /(\w#?)(\d)?/.exec(string) ?? [];
+    const matches = /(\w#?)(\d)?/.exec(string);
+    if (!matches) {
+      throw new Error(`Invalid note string: ${string}`);
+    }
+
+    const name = matches[1];
+    if (!name) {
+      throw new Error(`Invalid note name in: ${string}`);
+    }
 
-    this.name = matches[1];
+    this.name = name;
     this.octave = matches[2] ? parseInt(matches[2]) : 1;
   }
 

package/src/core/index.ts

@@ -3,6 +3,7 @@ export type {
   IModule,
   IModuleSerialize,
   IPolyModuleSerialize,
+  IAnyModuleSerialize,
   SetterHooks,
 } from "./module";
 
@@ -15,6 +16,12 @@ export { default as MidiDeviceManager } from "./midi/MidiDeviceManager";
 export { default as MidiDevice, MidiPortState } from "./midi/MidiDevice";
 export type { IMidiDevice } from "./midi/MidiDevice";
 export { default as MidiEvent, MidiEventType } from "./midi/MidiEvent";
+export {
+  normalizeDeviceName,
+  extractCoreTokens,
+  calculateSimilarity,
+  findBestMatch,
+} from "./midi/deviceMatcher";
 
 export type {
   MidiOutput,

package/src/core/midi/Message.ts

@@ -21,6 +21,7 @@ export default class Message {
    */
   get type(): string {
     const statusByte = this.data[0];
+    if (statusByte === undefined) return "unknown";
     const messageType = statusByte & 0xf0;
 
     switch (messageType) {

package/src/core/midi/MidiDeviceManager.ts

@@ -2,6 +2,7 @@ import { Context } from "@blibliki/utils";
 import ComputerKeyboardDevice from "./ComputerKeyboardDevice";
 import MidiDevice from "./MidiDevice";
 import { createMidiAdapter, type IMidiAccess } from "./adapters";
+import { findBestMatch } from "./deviceMatcher";
 
 type ListenerCallback = (device: MidiDevice) => void;
 
@@ -33,6 +34,30 @@ export default class MidiDeviceManager {
     return Array.from(this.devices.values()).find((d) => d.name === name);
   }
 
+  /**
+   * Finds a device using fuzzy name matching
+   * Useful for matching devices across browser/Node.js environments where names differ
+   *
+   * @param targetName - The device name to match
+   * @param threshold - Minimum similarity score (0-1, default: 0.6)
+   * @returns The best matching device and confidence score, or null
+   */
+  findByFuzzyName(
+    targetName: string,
+    threshold = 0.6,
+  ): { device: MidiDevice | ComputerKeyboardDevice; score: number } | null {
+    const deviceEntries = Array.from(this.devices.values());
+    const candidateNames = deviceEntries.map((d) => d.name);
+
+    const match = findBestMatch(targetName, candidateNames, threshold);
+
+    if (!match) return null;
+
+    const device = deviceEntries.find((d) => d.name === match.name);
+
+    return device ? { device, score: match.score } : null;
+  }
+
   addListener(callback: ListenerCallback) {
     this.listeners.push(callback);
   }

package/src/core/midi/deviceMatcher.ts

@@ -0,0 +1,203 @@
+/**
+ * Utilities for fuzzy matching MIDI device names across different platforms
+ *
+ * MIDI devices can have different names in browser vs Node.js:
+ * - Browser: "Launchkey Mini MK3 MIDI 1"
+ * - Node.js: "Launchkey Mini MK3:Launchkey Mini MK3 MIDI 1 20:0"
+ *
+ * This module provides fuzzy matching to find the same physical device
+ * across platforms based on name similarity.
+ */
+
+/**
+ * Normalizes a MIDI device name by:
+ * - Converting to lowercase
+ * - Removing common suffixes/prefixes
+ * - Removing port numbers and ALSA identifiers
+ * - Removing extra whitespace
+ * - Removing special characters
+ */
+export function normalizeDeviceName(name: string): string {
+  let normalized = name.toLowerCase();
+
+  // First, remove ALSA port numbers (e.g., "20:0" at the very end)
+  // Do this BEFORE splitting by colons
+  normalized = normalized.replace(/\s+\d+:\d+\s*$/g, "");
+
+  // Remove colon-separated duplicates (Node.js format: "Device:Device Port")
+  const parts = normalized.split(":");
+  if (parts.length > 1) {
+    // Take the longest part as it usually has more info
+    normalized = parts.reduce((longest, current) =>
+      current.length > longest.length ? current : longest,
+    );
+  }
+
+  // Remove common port descriptors (but keep the number if it's part of the device name)
+  // This regex only matches MIDI/Input/Output/Port at the END of the string
+  normalized = normalized.replace(
+    /\s+(midi|input|output|port)(\s+\d+)?$/gi,
+    "",
+  );
+
+  // Remove "device" prefix if present at the start
+  normalized = normalized.replace(/^device\s+/gi, "");
+
+  // Remove multiple spaces
+  normalized = normalized.replace(/\s+/g, " ").trim();
+
+  return normalized;
+}
+
+/**
+ * Extracts core device name tokens for matching
+ * Removes generic words and focuses on manufacturer/model identifiers
+ */
+export function extractCoreTokens(name: string): string[] {
+  const normalized = normalizeDeviceName(name);
+
+  // Split into tokens
+  const tokens = normalized.split(/[\s\-_:]+/);
+
+  // Filter out very short tokens and common generic words
+  const genericWords = new Set([
+    "midi",
+    "input",
+    "output",
+    "port",
+    "device",
+    "in",
+    "out",
+  ]);
+
+  return tokens.filter((token) => token.length > 1 && !genericWords.has(token));
+}
+
+/**
+ * Calculates Levenshtein distance between two strings
+ * Used for fuzzy string matching
+ */
+function levenshteinDistance(str1: string, str2: string): number {
+  const len1 = str1.length;
+  const len2 = str2.length;
+  const matrix: number[][] = [];
+
+  // Initialize matrix
+  for (let i = 0; i <= len1; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0; j <= len2; j++) {
+    if (matrix[0]) {
+      matrix[0][j] = j;
+    }
+  }
+
+  // Fill matrix
+  for (let i = 1; i <= len1; i++) {
+    for (let j = 1; j <= len2; j++) {
+      const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
+      const prevRow = matrix[i - 1];
+      const currRow = matrix[i];
+      const prevCell = currRow?.[j - 1];
+      const diagCell = prevRow?.[j - 1];
+
+      const prevCellInRow = prevRow?.[j];
+      if (
+        currRow &&
+        prevCellInRow !== undefined &&
+        prevCell !== undefined &&
+        diagCell !== undefined
+      ) {
+        currRow[j] = Math.min(
+          prevCellInRow + 1, // deletion
+          prevCell + 1, // insertion
+          diagCell + cost, // substitution
+        );
+      }
+    }
+  }
+
+  const lastRow = matrix[len1];
+  return lastRow?.[len2] ?? 0;
+}
+
+/**
+ * Calculates similarity score between two device names
+ * Returns a score between 0 (no match) and 1 (perfect match)
+ *
+ * Uses multiple strategies:
+ * 1. Exact normalized match (score: 1.0)
+ * 2. Token overlap (Jaccard similarity)
+ * 3. String similarity (based on Levenshtein distance)
+ * 4. Substring matching
+ */
+export function calculateSimilarity(name1: string, name2: string): number {
+  const normalized1 = normalizeDeviceName(name1);
+  const normalized2 = normalizeDeviceName(name2);
+
+  // Exact match after normalization
+  if (normalized1 === normalized2) {
+    return 1.0;
+  }
+
+  const tokens1 = new Set(extractCoreTokens(name1));
+  const tokens2 = new Set(extractCoreTokens(name2));
+
+  // If no tokens extracted, fall back to pure string similarity
+  if (tokens1.size === 0 || tokens2.size === 0) {
+    const maxLen = Math.max(normalized1.length, normalized2.length);
+    if (maxLen === 0) return 0;
+    const distance = levenshteinDistance(normalized1, normalized2);
+    return 1 - distance / maxLen;
+  }
+
+  // Calculate Jaccard similarity for tokens
+  const intersection = new Set([...tokens1].filter((x) => tokens2.has(x)));
+  const union = new Set([...tokens1, ...tokens2]);
+  const jaccardScore = intersection.size / union.size;
+
+  // Calculate string similarity
+  const maxLen = Math.max(normalized1.length, normalized2.length);
+  const distance = levenshteinDistance(normalized1, normalized2);
+  const stringScore = 1 - distance / maxLen;
+
+  // Check for substring matches
+  const substringScore =
+    normalized1.includes(normalized2) || normalized2.includes(normalized1)
+      ? 0.8
+      : 0;
+
+  // Weighted combination of scores
+  // Token overlap is most important, then string similarity, then substring
+  const finalScore =
+    jaccardScore * 0.5 + stringScore * 0.3 + substringScore * 0.2;
+
+  return finalScore;
+}
+
+/**
+ * Finds the best matching device name from a list of candidates
+ * Returns the best match and its confidence score
+ *
+ * @param targetName - The name to match against
+ * @param candidateNames - List of possible matches
+ * @param threshold - Minimum similarity score to consider a match (default: 0.6)
+ * @returns Best match and score, or null if no match above threshold
+ */
+export function findBestMatch(
+  targetName: string,
+  candidateNames: string[],
+  threshold = 0.6,
+): { name: string; score: number } | null {
+  let bestMatch: { name: string; score: number } | null = null;
+
+  for (const candidateName of candidateNames) {
+    const score = calculateSimilarity(targetName, candidateName);
+
+    if (score >= threshold && (!bestMatch || score > bestMatch.score)) {
+      bestMatch = { name: candidateName, score };
+    }
+  }
+
+  return bestMatch;
+}

package/src/core/module/Module.ts

@@ -1,5 +1,11 @@
 import { ContextTime } from "@blibliki/transport";
-import { Context, Optional, upperFirst, uuidv4 } from "@blibliki/utils";
+import {
+  Context,
+  Optional,
+  upperFirst,
+  uuidv4,
+  requestAnimationFrame,
+} from "@blibliki/utils";
 import { Engine } from "@/Engine";
 import { AnyModule, ModuleType, ModuleTypeToPropsMapping } from "@/modules";
 import {

package/src/core/module/PolyModule.ts

@@ -1,5 +1,10 @@
 import { ContextTime } from "@blibliki/transport";
-import { deterministicId, Optional, uuidv4 } from "@blibliki/utils";
+import {
+  deterministicId,
+  Optional,
+  uuidv4,
+  requestAnimationFrame,
+} from "@blibliki/utils";
 import { Engine } from "@/Engine";
 import { ModuleType, ModuleTypeToPropsMapping } from "@/modules";
 import {

package/src/core/module/VoiceScheduler.ts

@@ -102,9 +102,15 @@ export default class VoiceScheduler extends PolyModule<ModuleType.VoiceScheduler
     let voice = this.audioModules.find((v) => !v.activeNote);
 
     // If no available voice, get the one with the lowest triggeredAt
-    voice ??= this.audioModules.sort((a, b) => {
-      return a.triggeredAt - b.triggeredAt;
-    })[0];
+    if (!voice) {
+      const sorted = this.audioModules.sort((a, b) => {
+        return a.triggeredAt - b.triggeredAt;
+      });
+      voice = sorted[0];
+      if (!voice) {
+        throw new Error("No voices available in voice scheduler");
+      }
+    }
 
     return voice;
   }

package/src/core/module/index.ts

@@ -1,3 +1,11 @@
+import { ModuleType } from "@/modules";
+import { IModuleSerialize } from "./Module";
+import { IPolyModuleSerialize } from "./PolyModule";
+
 export { Module } from "./Module";
 export type { IModule, IModuleSerialize, SetterHooks } from "./Module";
 export type { IPolyModule, IPolyModuleSerialize } from "./PolyModule";
+
+export type IAnyModuleSerialize =
+  | IModuleSerialize<ModuleType>
+  | IPolyModuleSerialize<ModuleType>;

package/src/index.ts

@@ -7,6 +7,7 @@ export type {
   IModule,
   IModuleSerialize,
   IPolyModuleSerialize,
+  IAnyModuleSerialize,
   IMidiDevice,
   ModulePropSchema,
   PropSchema,

package/src/modules/Inspector.ts

@@ -60,7 +60,8 @@ export default class Inspector
   }
 
   getValue(): number {
-    return this.getValues()[0];
+    const value = this.getValues()[0];
+    return value ?? 0;
   }
 
   getValues(): Float32Array {

package/src/modules/MidiMapper.ts

@@ -125,6 +125,7 @@ export default class MidiMapper
     this.checkAutoAssign(event);
 
     const activePage = this.props.pages[this.props.activePage];
+    if (!activePage) return;
 
     [
       ...this.props.globalMappings.filter((m) => m.cc === event.cc),
@@ -245,6 +246,8 @@ export default class MidiMapper
     if (event.cc === undefined) return;
 
     const activePage = this.props.pages[this.props.activePage];
+    if (!activePage) return;
+
     const hasGlobalAutoAssign = this.props.globalMappings.some(
       ({ autoAssign }) => autoAssign,
     );

package/src/modules/MidiSelector.ts

@@ -45,11 +45,32 @@ export default class MidiSelector
       props,
     });
 
-    const midiDevice =
-      (this.props.selectedId &&
-        this.engine.findMidiDevice(this.props.selectedId)) ??
-      (this.props.selectedName &&
-        this.engine.findMidiDeviceByName(this.props.selectedName));
+    // Try to find device in order of preference:
+    // 1. By exact ID match
+    // 2. By exact name match
+    // 3. By fuzzy name match (for cross-platform compatibility)
+    let midiDevice =
+      this.props.selectedId &&
+      this.engine.findMidiDevice(this.props.selectedId);
+
+    if (!midiDevice && this.props.selectedName) {
+      midiDevice = this.engine.findMidiDeviceByName(this.props.selectedName);
+
+      // If exact name match fails, try fuzzy matching
+      if (!midiDevice) {
+        const fuzzyMatch = this.engine.findMidiDeviceByFuzzyName(
+          this.props.selectedName,
+          0.6, // 60% similarity threshold
+        );
+
+        if (fuzzyMatch) {
+          midiDevice = fuzzyMatch.device;
+          console.log(
+            `MIDI device fuzzy matched: "${this.props.selectedName}" -> "${midiDevice.name}" (confidence: ${Math.round(fuzzyMatch.score * 100)}%)`,
+          );
+        }
+      }
+    }
 
     if (midiDevice) {
       this.addEventListener(midiDevice);

package/src/processors/filter-processor.ts

@@ -37,29 +37,39 @@ export const filterProcessorURL = URL.createObjectURL(
           ): boolean {
             const input = inputs[0];
             const output = outputs[0];
+            if (!input || !output) return true;
 
             const cutoff = parameters.cutoff;
             const resonance = parameters.resonance;
+            if (!cutoff || !resonance) return true;
 
             for (let channelNum = 0; channelNum < input.length; channelNum++) {
               const inputChannel = input[channelNum];
               const outputChannel = output[channelNum];
+              if (!inputChannel || !outputChannel) continue;
 
               for (let i = 0; i < inputChannel.length; i++) {
                 const s = inputChannel[i];
+                if (s === undefined) continue;
+
                 // Convert Hz to normalized frequency using logarithmic scale
                 // This better matches human hearing perception
-                const cutoffHz = cutoff.length > 1 ? cutoff[i] : cutoff[0];
+                const cutoffHz =
+                  cutoff.length > 1 ? (cutoff[i] ?? cutoff[0]) : cutoff[0];
+                if (cutoffHz === undefined) continue;
+
                 const clampedHz = Math.max(20, Math.min(20000, cutoffHz));
                 const normalizedCutoff =
                   Math.log(clampedHz / 20) / Math.log(20000 / 20);
                 const c = Math.pow(0.5, (1 - normalizedCutoff) / 0.125);
-                const r = Math.pow(
-                  0.5,
-                  ((resonance.length > 1 ? resonance[i] : resonance[0]) +
-                    0.125) /
-                    0.125,
-                );
+
+                const resonanceValue =
+                  resonance.length > 1
+                    ? (resonance[i] ?? resonance[0])
+                    : resonance[0];
+                if (resonanceValue === undefined) continue;
+
+                const r = Math.pow(0.5, (resonanceValue + 0.125) / 0.125);
                 const mrc = 1 - r * c;
 
                 this.s0 = mrc * this.s0 - c * this.s1 + c * s;

package/src/processors/scale-processor.ts

@@ -28,17 +28,20 @@ export const scaleProcessorURL = URL.createObjectURL(
           ) {
             const input = inputs[0];
             const output = outputs[0];
+            if (!input || !output) return true;
 
             const minValues = parameters.min;
             const maxValues = parameters.max;
             const currentValues = parameters.current;
+            if (!minValues || !maxValues || !currentValues) return true;
 
-            if (!input.length || input[0].length === 0) {
+            const firstInput = input[0];
+            if (!firstInput || firstInput.length === 0) {
               for (const outputChannel of output) {
                 const current =
-                  parameters.current.length > 1
-                    ? parameters.current[0]
-                    : parameters.current[0];
+                  currentValues.length > 1
+                    ? (currentValues[0] ?? 0.5)
+                    : (currentValues[0] ?? 0.5);
 
                 outputChannel.fill(current);
               }
@@ -49,17 +52,32 @@ export const scaleProcessorURL = URL.createObjectURL(
             for (let channel = 0; channel < input.length; channel++) {
               const inputChannel = input[channel];
               const outputChannel = output[channel];
+              if (!inputChannel || !outputChannel) continue;
 
               for (let i = 0; i < inputChannel.length; i++) {
                 const x = inputChannel[i];
+                if (x === undefined) continue;
 
-                const min = minValues.length > 1 ? minValues[i] : minValues[0];
-                const max = maxValues.length > 1 ? maxValues[i] : maxValues[0];
+                const min =
+                  minValues.length > 1
+                    ? (minValues[i] ?? minValues[0])
+                    : minValues[0];
+                const max =
+                  maxValues.length > 1
+                    ? (maxValues[i] ?? maxValues[0])
+                    : maxValues[0];
                 const current =
                   currentValues.length > 1
-                    ? currentValues[i]
+                    ? (currentValues[i] ?? currentValues[0])
                     : currentValues[0];
 
+                if (
+                  min === undefined ||
+                  max === undefined ||
+                  current === undefined
+                )
+                  continue;
+
                 if (x < 0) {
                   outputChannel[i] = current * Math.pow(min / current, -x);
                 } else {