---

name: blibliki-engine description: Use when working with Blibliki's packages/engine - creating modules, modifying engine code, debugging MIDI/audio issues, or when changes in engine package don't appear in grid app

Blibliki Engine

Overview

The Blibliki engine (packages/engine) is a TypeScript audio synthesis framework built on Web Audio API. Critical: Apps consume BUILT packages from dist/, not source files. Changes require rebuilding before they appear in apps.

Monorepo Build Workflow

The #1 mistake: Modifying engine source and expecting apps to pick it up without rebuilding.

Copydigraph build_workflow {
    "Modifying engine code?" [shape=diamond];
    "Edit packages/engine/src/" [shape=box];
    "Run: pnpm build:packages" [shape=box, style=filled, fillcolor=yellow];
    "Edit apps/grid/src/" [shape=box];
    "Run: pnpm dev to test" [shape=box];
    "Just reading/understanding?" [shape=diamond];
    "Read code directly" [shape=box];

    "Modifying engine code?" -> "Edit packages/engine/src/" [label="yes"];
    "Edit packages/engine/src/" -> "Run: pnpm build:packages";
    "Run: pnpm build:packages" -> "Edit apps/grid/src/" [label="if updating UI"];
    "Edit apps/grid/src/" -> "Run: pnpm dev to test";
    "Modifying engine code?" -> "Just reading/understanding?" [label="no"];
    "Just reading/understanding?" -> "Read code directly" [label="yes"];
}

Why this matters:

• Apps import from packages/engine/dist/ (built artifacts), not src/
• pnpm test validates source but doesn't build
• Without rebuild, apps use stale code

Commands:

• pnpm dev - Start dev servers with watch mode (RECOMMENDED - auto-rebuilds on save)
• pnpm build:packages - Rebuild all packages (use when working without pnpm dev)
• pnpm test - Run tests (validates source, doesn't build)
• pnpm tsc - Type checking

When to rebuild:

• Using pnpm dev: No manual rebuild needed - changes auto-rebuild on save. Check terminal for build errors.
• Not using pnpm dev: Must run pnpm build:packages manually after engine changes before testing in apps.

Module Implementation Patterns

Constructor Signature

CRITICAL: Module constructor signature is fixed.

Copy// ✅ CORRECT - Mono module
class MonoGain extends Module<ModuleType.Gain> {
  constructor(engineId: string, params: ICreateModule<ModuleType.Gain>) {
    const props = { ...DEFAULT_PROPS, ...params.props };
    const audioNodeConstructor = (context: Context) =>
      new GainNode(context.audioContext);

    super(engineId, { ...params, audioNodeConstructor, props });
    this.registerDefaultIOs();
  }
}

// ❌ WRONG - Different signature
constructor(engine: Engine, id: string, props?: any)

Registering IOs

Use register* helper methods, NOT direct AudioIO construction.

Copy// ✅ CORRECT - AudioParam modulation input
this.registerAudioInput({
  name: "gain",
  getAudioNode: () => this.audioNode.gain,  // Returns AudioParam
});

// ✅ CORRECT - MIDI input
this.registerMidiInput({
  name: "midi in",
  onMidiEvent: this.onMidiEvent,
});

// ❌ WRONG - Don't construct AudioIO directly
this.inputs = {
  gain: new AudioIO(this, 'gain', 'input', this.audioNode.gain)
};

Quick reference:

• registerAudioInput(props) - Audio/AudioParam inputs
• registerAudioOutput(props) - Audio outputs
• registerMidiInput(props) - MIDI inputs with event handler
• registerMidiOutput(props) - MIDI outputs
• registerDefaultIOs() - Auto-registers standard "in"/"out" + "midi in"

Module Props Schema

CRITICAL: Schema is a TypeScript type, not a function. Use kind not type.

Copy// ✅ CORRECT
export type IGainProps = { gain: number };

export const gainPropSchema: ModulePropSchema<IGainProps> = {
  gain: {
    kind: "number",  // kind, not type
    min: 0,
    max: 2,
    step: 0.01,
    label: "Gain",
  },
};

// ❌ WRONG
modulePropSchema({ gain: { type: 'number', ... }})

Applying Props with Setter Hooks

Props don't automatically update Web Audio nodes. Use setter hooks.

Copyclass MonoGain extends Module<ModuleType.Gain>
  implements Pick<SetterHooks<IGainProps>, "onAfterSetGain">
{
  // ✅ CORRECT - Hook called when props.gain changes
  onAfterSetGain: SetterHooks<IGainProps>["onAfterSetGain"] = (value) => {
    this.audioNode.gain.value = value;
  };
}

// Available hooks per prop:
// - onSetPropName(value) - Transform before setting (return new value)
// - onAfterSetPropName(value) - Side effect after setting (void)

PolyModule Pattern

CRITICAL: PolyModule takes monoModuleConstructor, not pre-allocated voices.

Copy// ✅ CORRECT - Poly module
export default class Gain extends PolyModule<ModuleType.Gain> {
  constructor(engineId: string, params: IPolyModuleConstructor<ModuleType.Gain>) {
    const props = { ...DEFAULT_PROPS, ...params.props };

    // Pass constructor function for mono voices
    const monoModuleConstructor = (
      engineId: string,
      params: IModuleConstructor<ModuleType.Gain>
    ) => new MonoGain(engineId, params);

    super(engineId, { ...params, props, monoModuleConstructor });
    this.registerDefaultIOs();
  }
}

// ❌ WRONG - Don't pre-allocate voice instances
this.voices = Array.from({ length: 8 }, () => new Voice());

Module Registration Checklist

When creating a new module, update FIVE locations:

1. Create module class: packages/engine/src/modules/YourModule.ts
2. Export schema: packages/engine/src/modules/index.ts
3. Add to ModuleType enum: packages/engine/src/types.ts
4. Create UI component: apps/grid/src/components/AudioModule/YourModule.tsx
5. Register in UI mapping: apps/grid/src/components/AudioModule/index.tsx

After registration: Run pnpm build:packages before testing in grid app.

Common Workflows

Debugging "Changes Don't Appear"

If engine changes don't appear in grid app:

1. Did you run pnpm build:packages? ← Most common cause
2. Check packages/engine/dist/ has updated files
3. Check browser console for import errors
4. Restart dev server if needed
5. If using pnpm dev, it auto-rebuilds (check for build errors in terminal)

Debugging MIDI Routing

MIDI flow: MidiDevice → MidiSelector → VirtualMidi → Module.onMidiEvent

Files to check:

• packages/engine/src/modules/MidiSelector.ts - Routes MIDI from devices
• packages/engine/src/modules/VirtualMidi.ts - Programmatic MIDI generation
• apps/grid/src/lib/MidiDevice*.ts - Device management
• Your module's onMidiEvent handler and registered MidiIO inputs

Common issues:

• MidiSelector not routing to correct module
• PolyModule voices not created before IOs registered (constructor timing)
• MIDI input not registered via registerMidiInput()

Converting to Polyphonic

1. Read packages/engine/src/core/module/PolyModule.ts first
2. Create mono version of module (handles one voice)
3. Change base class from Module<T> to PolyModule<T>
4. Pass monoModuleConstructor: () => new MonoYourModule(...) to super
5. Voices created automatically by PolyModule base class
6. Build and test with multiple simultaneous notes

Before Finishing

When completing engine work, verify ALL of these:

• Engine source changes complete
• Module schema updated if needed
• Verified packages rebuilt (check terminal if using pnpm dev, or run pnpm build:packages)
• UI components updated if needed
• Ran pnpm test (all tests pass)
• Ran pnpm tsc (type checking passes)
• Ran pnpm lint (no linting errors)
• Tested integration in grid app (with pnpm dev running)
• Verified feature works end-to-end in browser

Most commonly missed: Verifying packages are rebuilt before testing in app.

Common Mistakes

File Locations

When implementing features, reference these files:

• Example modules: packages/engine/src/modules/Gain.ts, Oscillator.ts
• Module base: packages/engine/src/core/module/Module.ts
• PolyModule base: packages/engine/src/core/module/PolyModule.ts
• IO system: packages/engine/src/core/IO/AudioIO.ts, MidiIO.ts
• Schema types: packages/engine/src/core/schema.ts