@blibliki/engine 0.3.7 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blibliki/engine",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "type": "module",
   "source": "src/index.ts",
   "main": "dist/index.cjs",
@@ -20,8 +20,8 @@
     "es-toolkit": "^1.41.0",
     "node-web-audio-api": "^1.0.3",
     "webmidi": "^3.1.14",
-    "@blibliki/transport": "^0.3.7",
-    "@blibliki/utils": "^0.3.7"
+    "@blibliki/transport": "^0.3.8",
+    "@blibliki/utils": "^0.3.8"
   },
   "scripts": {
     "build": "tsup",

package/src/Engine.ts

@@ -1,4 +1,5 @@
 import {
+  BPM,
   ContextTime,
   Ticks,
   TimeSignature,
@@ -12,7 +13,14 @@ import {
   pick,
   uuidv4,
 } from "@blibliki/utils";
-import { IRoute, Routes, MidiDeviceManager, IModule, MidiEvent } from "@/core";
+import {
+  IRoute,
+  Routes,
+  MidiDeviceManager,
+  IModule,
+  MidiEvent,
+  IModuleSerialize,
+} from "@/core";
 import {
   ICreateModule,
   ModuleParams,
@@ -20,7 +28,11 @@ import {
   ModuleTypeToModuleMapping,
   createModule,
 } from "@/modules";
-import { IPolyModule, PolyModule } from "./core/module/PolyModule";
+import {
+  IPolyModule,
+  IPolyModuleSerialize,
+  PolyModule,
+} from "./core/module/PolyModule";
 import { loadProcessors } from "./processors";
 
 export type IUpdateModule<T extends ModuleType> = {
@@ -33,6 +45,13 @@ export type IUpdateModule<T extends ModuleType> = {
 
 export type ICreateRoute = Optional<IRoute, "id">;
 
+export interface IEngineSerialize {
+  bpm: BPM;
+  timeSignature: TimeSignature;
+  modules: (IModuleSerialize<ModuleType> | IPolyModuleSerialize<ModuleType>)[];
+  routes: IRoute[];
+}
+
 export class Engine {
   private static _engines = new Map<string, Engine>();
   private static _currentId: string | undefined;
@@ -65,6 +84,24 @@ export class Engine {
     return this.getById(this._currentId);
   }
 
+  static async load(data: IEngineSerialize): Promise<Engine> {
+    const { bpm, timeSignature, modules, routes } = data;
+    const context = new Context();
+    const engine = new Engine(context);
+    await engine.initialize();
+
+    engine.timeSignature = timeSignature;
+    engine.bpm = bpm;
+    modules.forEach((m) => {
+      engine.addModule(m);
+    });
+    routes.forEach((r) => {
+      engine.addRoute(r);
+    });
+
+    return engine;
+  }
+
   constructor(context: Context) {
     this.id = uuidv4();
 
@@ -201,6 +238,15 @@ export class Engine {
     this.modules.clear();
   }
 
+  serialize(): IEngineSerialize {
+    return {
+      bpm: this.bpm,
+      timeSignature: this.timeSignature,
+      modules: Array.from(this.modules.values()).map((m) => m.serialize()),
+      routes: this.routes.serialize(),
+    };
+  }
+
   findModule(
     id: string,
   ): ModuleTypeToModuleMapping[keyof ModuleTypeToModuleMapping] {
@@ -219,6 +265,10 @@ export class Engine {
     return this.midiDeviceManager.find(id);
   }
 
+  findMidiDeviceByName(name: string) {
+    return this.midiDeviceManager.findByName(name);
+  }
+
   onPropsUpdate(
     callback: <T extends ModuleType>(
       params: IModule<T> | IPolyModule<T>,

package/src/core/Route.ts

@@ -37,9 +37,21 @@ export class Routes {
   }
 
   clear() {
-    for (const id in this.routes) {
+    this.routes.forEach((_, id) => {
       this.removeRoute(id);
-    }
+    });
+  }
+
+  replug() {
+    this.routes.forEach((_, id) => {
+      const { sourceIO, destinationIO } = this.getIOs(id);
+      sourceIO.rePlugAll();
+      destinationIO.rePlugAll();
+    });
+  }
+
+  serialize(): IRoute[] {
+    return Array.from(this.routes.values());
   }
 
   private plug(id: string) {

package/src/core/midi/MidiDeviceManager.ts

@@ -27,6 +27,10 @@ export default class MidiDeviceManager {
     return this.devices.get(id);
   }
 
+  findByName(name: string): MidiDevice | ComputerKeyboardDevice | undefined {
+    return Array.from(this.devices.values()).find((d) => d.name === name);
+  }
+
   addListener(callback: ListenerCallback) {
     this.listeners.push(callback);
   }

package/src/core/module/Module.ts

@@ -35,41 +35,6 @@ export type IModuleConstructor<T extends ModuleType> = Optional<
   audioNodeConstructor?: (context: Context) => AudioNode;
 };
 
-/**
- * Helper type for type-safe property lifecycle hooks.
- *
- * Hooks are completely optional - only define the ones you need.
- * Use explicit type annotation for automatic type inference.
- *
- * @example
- * ```typescript
- * export type IGainProps = {
- *   gain: number;
- *   muted: boolean;
- * };
- *
- * export class MonoGain extends Module<ModuleType.Gain> {
- *   // ✅ Define only the hooks you need with type annotation
- *   // value type is automatically inferred as number!
- *   onSetGain: SetterHooks<IGainProps>["onSetGain"] = (value) => {
- *     this.audioNode.gain.value = value;
- *     return value; // optional: return modified value
- *   };
- *
- *   // ✅ onAfterSet is called after prop is set
- *   onAfterSetMuted: SetterHooks<IGainProps>["onAfterSetMuted"] = (value) => {
- *     if (value) this.audioNode.gain.value = 0;
- *   };
- *
- *   // ✅ You can omit hooks you don't need - they're optional!
- *   // No need to define onSetMuted if you don't need it
- *
- *   // ❌ This would cause a type error:
- *   // onSetGain: SetterHooks<IGainProps>["onSetGain"] = (value: string) => value;
- *   //                                                            ^^^^^^ Error!
- * }
- * ```
- */
 export type SetterHooks<P> = {
   [K in keyof P as `onSet${Capitalize<string & K>}`]: (value: P[K]) => P[K];
 } & {
@@ -88,7 +53,6 @@ export abstract class Module<T extends ModuleType> implements IModule<T> {
   inputs: InputCollection;
   outputs: OutputCollection;
   protected _props!: ModuleTypeToPropsMapping[T];
-  protected superInitialized = false;
   protected activeNotes: Note[];
   private pendingUIUpdates = false;
 
@@ -108,8 +72,6 @@ export abstract class Module<T extends ModuleType> implements IModule<T> {
     this.inputs = new InputCollection(this);
     this.outputs = new OutputCollection(this);
 
-    this.superInitialized = true;
-
     // Defer hook calls until after subclass is fully initialized
     queueMicrotask(() => {
       this.props = props;

package/src/core/module/PolyModule.ts

@@ -44,7 +44,6 @@ export abstract class PolyModule<T extends ModuleType>
   outputs: OutputCollection;
   protected monoModuleConstructor: IPolyModuleConstructor<T>["monoModuleConstructor"];
   protected _props!: ModuleTypeToPropsMapping[T];
-  protected superInitialized = false;
   private _voices!: number;
   private _name!: string;
   private pendingUIUpdates = false;
@@ -60,7 +59,6 @@ export abstract class PolyModule<T extends ModuleType>
     this.engineId = engineId;
     this.name = name;
     this.moduleType = moduleType;
-    this.voices = voices || 1;
     this._props = props;
 
     this.inputs = new InputCollection(
@@ -70,10 +68,9 @@ export abstract class PolyModule<T extends ModuleType>
       this as unknown as PolyModule<ModuleType>,
     );
 
-    this.superInitialized = true;
-
     // Defer hook calls until after subclass is fully initialized
     queueMicrotask(() => {
+      this.voices = voices || 1;
       this.props = props;
     });
   }
@@ -146,8 +143,6 @@ export abstract class PolyModule<T extends ModuleType>
   }
 
   rePlugAll(callback?: () => void) {
-    if (!this.superInitialized) return;
-
     this.inputs.rePlugAll(callback);
     this.outputs.rePlugAll(callback);
   }

package/src/index.ts

@@ -1,5 +1,5 @@
 export { Engine } from "./Engine";
-export type { ICreateRoute, IUpdateModule } from "./Engine";
+export type { ICreateRoute, IUpdateModule, IEngineSerialize } from "./Engine";
 
 export type {
   IRoute,

package/src/modules/MidiSelector.ts

@@ -1,4 +1,5 @@
-import { IModule, Module, MidiOutput, SetterHooks } from "@/core";
+import { IModule, Module, MidiOutput, SetterHooks, MidiDevice } from "@/core";
+import ComputerKeyboardInput from "@/core/midi/ComputerKeyboardDevice";
 import MidiEvent from "@/core/midi/MidiEvent";
 import { ModulePropSchema } from "@/core/schema";
 import { ICreateModule, ModuleType } from ".";
@@ -6,6 +7,7 @@ import { ICreateModule, ModuleType } from ".";
 export type IMidiSelector = IModule<ModuleType.MidiSelector>;
 export type IMidiSelectorProps = {
   selectedId: string | undefined | null;
+  selectedName: string | undefined | null;
 };
 
 export const midiSelectorPropSchema: ModulePropSchema<IMidiSelectorProps> = {
@@ -13,9 +15,16 @@ export const midiSelectorPropSchema: ModulePropSchema<IMidiSelectorProps> = {
     kind: "string",
     label: "Midi device ID",
   },
+  selectedName: {
+    kind: "string",
+    label: "Midi device name",
+  },
 };
 
-const DEFAULT_PROPS: IMidiSelectorProps = { selectedId: undefined };
+const DEFAULT_PROPS: IMidiSelectorProps = {
+  selectedId: undefined,
+  selectedName: undefined,
+};
 
 export default class MidiSelector
   extends Module<ModuleType.MidiSelector>
@@ -36,7 +45,15 @@ export default class MidiSelector
       props,
     });
 
-    this.addEventListener(this.props.selectedId);
+    const midiDevice =
+      (this.props.selectedId &&
+        this.engine.findMidiDevice(this.props.selectedId)) ??
+      (this.props.selectedName &&
+        this.engine.findMidiDeviceByName(this.props.selectedName));
+
+    if (midiDevice) {
+      this.addEventListener(midiDevice);
+    }
 
     this.registerOutputs();
   }
@@ -45,7 +62,13 @@ export default class MidiSelector
     value,
   ) => {
     this.removeEventListener();
-    this.addEventListener(value);
+    if (!value) return value;
+
+    const midiDevice = this.engine.findMidiDevice(value);
+    if (!midiDevice) return value;
+
+    this.props = { selectedName: midiDevice.name };
+    this.addEventListener(midiDevice);
 
     return value;
   };
@@ -60,11 +83,8 @@ export default class MidiSelector
     return this._forwardMidiEvent;
   }
 
-  private addEventListener(midiId: string | undefined | null) {
-    if (!midiId) return;
-
-    const midiDevice = this.engine.findMidiDevice(midiId);
-    midiDevice?.addEventListener(this.forwardMidiEvent);
+  private addEventListener(midiDevice: MidiDevice | ComputerKeyboardInput) {
+    midiDevice.addEventListener(this.forwardMidiEvent);
   }
 
   private removeEventListener() {

package/src/modules/Oscillator.ts

@@ -108,7 +108,7 @@ export class MonoOscillator
 {
   declare audioNode: OscillatorNode;
   isStated = false;
-  lowOutputGain: GainNode;
+  outputGain: GainNode;
   detuneGain!: GainNode;
 
   constructor(engineId: string, params: ICreateModule<ModuleType.Oscillator>) {
@@ -122,7 +122,7 @@ export class MonoOscillator
       audioNodeConstructor,
     });
 
-    this.lowOutputGain = new GainNode(this.context.audioContext, {
+    this.outputGain = new GainNode(this.context.audioContext, {
       gain: dbToGain(LOW_GAIN),
     });
 
@@ -152,8 +152,8 @@ export class MonoOscillator
     this.updateFrequency();
   };
 
-  onAfterSetLowGain: OscillatorSetterHooks["onAfterSetLowGain"] = () => {
-    this.rePlugAll();
+  onAfterSetLowGain: OscillatorSetterHooks["onAfterSetLowGain"] = (lowGain) => {
+    this.outputGain.gain.value = lowGain ? dbToGain(LOW_GAIN) : 1;
   };
 
   start(time: ContextTime) {
@@ -218,7 +218,7 @@ export class MonoOscillator
   }
 
   private applyOutputGain() {
-    this.audioNode.connect(this.lowOutputGain);
+    this.audioNode.connect(this.outputGain);
   }
 
   private initializeGainDetune() {
@@ -236,8 +236,7 @@ export class MonoOscillator
   private registerOutputs() {
     this.registerAudioOutput({
       name: "out",
-      getAudioNode: () =>
-        this.props.lowGain ? this.lowOutputGain : this.audioNode,
+      getAudioNode: () => this.outputGain,
     });
   }
 }