@ultrst-armada/kloks 0.0.0-stage → 1.0.0

package/packages/audio-midi/dist/index.d.ts

@@ -0,0 +1,988 @@
+import * as _dinilmusick_krnl from '@dinilmusick/krnl';
+import { ServiceDefinition, IService } from '@dinilmusick/krnl';
+import { INodeVisuals, SpaceNode, NodeConnection, MidiNote, SynthPreset, ContainerNode, PlayerNode, SamplePresetType, AudioTrackData, HardwareChannelInfo, NamedAudioBus, AudioDeviceInfo, ConnectionsConfig, MidiInputDevice, StoredPacket, RecorderNode, CurveTrackData, CurvePoint, EffectNode, CompressorEffectConfig, MultibandCompressorEffectConfig } from '@ultrst-armada/kloks/state-graph';
+
+/**
+ * Pro-Audio Hardware Input/Output Manager (Named Bus Architecture)
+ * Enforces raw pro-audio streams, channel splitting, output sink routing, and hot-plugging.
+ */
+interface AudioDeviceDescriptor {
+    deviceId: string;
+    label: string;
+    kind: MediaDeviceKind;
+    groupId: string;
+}
+interface AudioBusConfig {
+    name: string;
+    targetDeviceId?: string;
+    channelCount?: number;
+    sampleRate?: number;
+}
+interface AudioHardwareState {
+    isInitialized: boolean;
+    activeDeviceId: string | null;
+    channelCount: number;
+    availableDevices: AudioDeviceDescriptor[];
+    sampleRate: number;
+    state: AudioContextState;
+}
+type AudioStateListener = (state: AudioHardwareState) => void;
+declare class AudioInputManager$1 {
+    private audioCtx;
+    private mediaStream;
+    private sourceNode;
+    private channelSplitter;
+    private namedBuses;
+    private listeners;
+    private availableDevices;
+    private activeDeviceId;
+    private isDeviceChangeBound;
+    constructor();
+    /**
+     * Initializes audio hardware. MUST be gated behind explicit user gesture.
+     */
+    initialize(config?: AudioBusConfig): Promise<void>;
+    /**
+     * Connects raw pro-audio input stream strictly disabling consumer audio processing.
+     */
+    connectAudioStream(config: AudioBusConfig): Promise<void>;
+    /**
+     * Accesses a discrete physical channel output from the channel splitter.
+     */
+    getChannelOutput(channelIndex: number, busName?: string): AudioNode;
+    /**
+     * Routes audio element output to a specific device sinkId (monitors/headphones).
+     */
+    routeOutputSink(audioElement: HTMLMediaElement, deviceId: string): Promise<void>;
+    /**
+     * Enumerates audio input and output devices.
+     */
+    refreshDeviceList(): Promise<AudioDeviceDescriptor[]>;
+    getNamedBus(name: string): AudioNode | undefined;
+    getAudioContext(): AudioContext | null;
+    getState(): AudioHardwareState;
+    subscribe(listener: AudioStateListener): () => void;
+    dispose(): Promise<void>;
+    private handleDeviceChange;
+    private notifyListeners;
+    private assertIframePermissions;
+    private handleAudioError;
+}
+
+/**
+ * Pro-MIDI Subsystem (Reactive Port Binding & Virtual Loopback)
+ * Translates raw byte arrays into high-level MidiEventPayloads, handles hot-plugging and virtual emitting.
+ */
+type MidiCommandType = 'NOTE_ON' | 'NOTE_OFF' | 'CONTROL_CHANGE' | 'PITCH_BEND' | 'PROGRAM_CHANGE' | 'CHANNEL_PRESSURE' | 'POLY_PRESSURE' | 'CLOCK' | 'START' | 'STOP' | 'CONTINUE' | 'SYSEX' | 'UNKNOWN';
+interface MidiEventPayload$1 {
+    command: MidiCommandType;
+    channel: number;
+    note?: number;
+    velocity?: number;
+    controller?: number;
+    value?: number;
+    rawBytes: Uint8Array;
+    timestamp: number;
+    sourceId: string;
+    sourceName: string;
+}
+interface MidiPortDescriptor {
+    id: string;
+    name: string;
+    manufacturer?: string;
+    type: 'input' | 'output';
+    state: string;
+    connection: string;
+}
+interface MidiSubsystemState {
+    isSupported: boolean;
+    isInitialized: boolean;
+    inputs: MidiPortDescriptor[];
+    outputs: MidiPortDescriptor[];
+    sysexEnabled: boolean;
+}
+type MidiEventListener = (event: MidiEventPayload$1) => void;
+type MidiStateListener = (state: MidiSubsystemState) => void;
+declare class MidiManager$1 {
+    private midiAccess;
+    private eventListeners;
+    private stateListeners;
+    private boundInputs;
+    private isInitialized;
+    constructor();
+    /**
+     * Initializes Web MIDI access. MUST be gated behind explicit user gesture.
+     */
+    initialize(options?: {
+        sysex?: boolean;
+        software?: boolean;
+    }): Promise<void>;
+    /**
+     * Reactive hot-plug port binding handler.
+     */
+    private handleStateChange;
+    /**
+     * Binds all existing input ports upon initialization.
+     */
+    private bindExistingPorts;
+    /**
+     * Binds onmidimessage handler to a specific MIDIInput port.
+     */
+    bindMidiPort(port: MIDIInput): void;
+    /**
+     * Virtual MIDI Loopback: On-screen UI components (virtual keyboards, sequencers)
+     * can trigger the exact same event streams as physical hardware.
+     */
+    emitVirtualMidi(payload: Partial<MidiEventPayload$1> & {
+        command: MidiCommandType;
+    }): void;
+    /**
+     * Translates raw byte arrays into high-level MidiEventPayload.
+     */
+    parseRawMidiBytes(bytes: Uint8Array, sourceId: string, sourceName: string, timestamp: number): MidiEventPayload$1;
+    private synthesizeRawBytes;
+    subscribeEvents(listener: MidiEventListener): () => void;
+    subscribeState(listener: MidiStateListener): () => void;
+    getState(): MidiSubsystemState;
+    dispose(): void;
+    private dispatchEvent;
+    private notifyState;
+    private assertIframePermissions;
+    private handleMidiError;
+}
+
+interface AudioEngineConfig {
+    sampleRate: number;
+    bufferSize: number;
+}
+
+declare class SynthEngine {
+    private ctx;
+    private masterGain;
+    private delayNode;
+    private delayFeedback;
+    private delayGain;
+    private reverbNode;
+    private reverbGain;
+    analyser: AnalyserNode | null;
+    analyserL: AnalyserNode | null;
+    analyserR: AnalyserNode | null;
+    private analyserBuffer;
+    private analyserBufferL;
+    private analyserBufferR;
+    masterSplitter: ChannelSplitterNode | null;
+    nodeVisuals: INodeVisuals | null;
+    private isInitialized;
+    private nodeActiveUntilMap;
+    private audioEngineConfig;
+    private graphNodeMap;
+    private loadAudioConfig;
+    getAudioEngineConfig(): AudioEngineConfig;
+    updateAudioSettings(newConfig: Partial<AudioEngineConfig>): Promise<void>;
+    reinitContext(): Promise<void>;
+    activeNodes: SpaceNode[];
+    activeConnections: NodeConnection[];
+    lastPlayedMidiNote: {
+        note: number;
+        velocity: number;
+        timestamp: number;
+    } | null;
+    updateActiveGraph(nodes: SpaceNode[], connections: NodeConnection[]): void;
+    /**
+     * Evaluates reachability from a given nodeId to an active, unmuted AudioOutputNode.
+     * Traverses activeConnections, effect/routing chains, and module boundaries.
+     */
+    checkGraphReachabilityToOutput(nodeId: string): boolean;
+    /**
+     * Authority Check:
+     * Queries the BaseAudioGraphNode instance. Structural rule enforces that no node
+     * is allowed to emit sound to master unless authorized via an active connection to AudioOutputNode.
+     */
+    isNodeConnectedToOutput(nodeId: string): boolean;
+    init(forceRecreate?: boolean): void;
+    playAuditionTestPulse(): void;
+    getAudioLevel(): number;
+    getStereoLevels(): {
+        left: number;
+        right: number;
+    };
+    isNodeActive(nodeId: string): boolean;
+    markNodeActive(nodeId: string, durationSec?: number): void;
+    private audioInputLevelProvider;
+    registerAudioInputLevelProvider(provider: (busId: string) => number): void;
+    getWireSignalLevel(sourceNode: any, fromPort?: string): {
+        left: number;
+        right: number;
+    };
+    setOutputRouting(routingId: string): void;
+    setOutputDevice(deviceId: string): Promise<boolean>;
+    setMasterVolume(vol: number): void;
+    getContext(): AudioContext;
+    getMasterNode(): GainNode;
+    getGainAndPanForNode(nodeId: string): {
+        volumeScale: number;
+        panOffset: number;
+        effectIds: string[];
+    };
+    /**
+     * Chains audio through all active DSP effect nodes (EQ, Compressor, Multiband, Limiter, Reverb, Delay, Saturation)
+     * and fans out to any compressors/multiband compressors that have sidechain active with this node as source.
+     */
+    routeAudioThroughNodeEffects(audioNode: AudioNode, nodeId?: string): AudioNode;
+    playNote(note: MidiNote, preset: SynthPreset, startTimeOffset?: number, containerId?: string): void;
+    private playSamplerNote;
+    private playInstrumentNote;
+}
+declare const synthEngine: SynthEngine;
+
+declare class SequencerEngine {
+    bpm: number;
+    isPlaying: boolean;
+    currentBeat: number;
+    private timerId;
+    private lastTickTime;
+    nodeVisuals: INodeVisuals | null;
+    private activeContainerPlayheads;
+    nodes: SpaceNode[];
+    connections: NodeConnection[];
+    syncNodesAndConnections(nodes: SpaceNode[], connections: NodeConnection[]): void;
+    start(nodes: SpaceNode[], connections: NodeConnection[], onTriggerFired?: (triggerId: string, targetContainerIds: string[]) => void): void;
+    stop(): void;
+    private processStep;
+    private processTriggerWiresWithEffects;
+    handleContainerPlayStop(container: ContainerNode): void;
+    handleContainerPlayPause(container: ContainerNode): void;
+    toggleContainerRecord(container: ContainerNode): void;
+    fireTrigger(trig: SpaceNode, connections: NodeConnection[], containerMap: Map<string, ContainerNode>, onTriggerFired?: (triggerId: string, targetContainerIds: string[]) => void, allNodes?: SpaceNode[]): void;
+    handlePlayerStart(player: PlayerNode, container?: ContainerNode | null): void;
+    handlePlayerStop(player: PlayerNode): void;
+    manualTriggerContainer(container: ContainerNode): void;
+}
+declare const sequencerEngine: SequencerEngine;
+
+declare function playContainerNoteWithEffects(container: ContainerNode, note: any, nodes: SpaceNode[], connections: NodeConnection[], bpm: number, isPlaying: boolean, nodeVisuals: INodeVisuals | null): void;
+declare function processActiveContainers(activeContainerPlayheads: Map<string, {
+    startBeat: number;
+    pausedOffset?: number;
+}>, containerMap: Map<string, ContainerNode>, prevBeat: number, currBeat: number, nodes: SpaceNode[], connections: NodeConnection[], bpm: number, isPlaying: boolean, nodeVisuals: INodeVisuals | null): void;
+
+interface ActiveTrackPlayback {
+    trackId?: string;
+    source?: AudioBufferSourceNode;
+    sourceNode?: AudioBufferSourceNode;
+    gainNode?: GainNode;
+    startTime: number;
+    startSec?: number;
+    duration?: number;
+    playDuration: number;
+    secPerBeat: number;
+    loop?: boolean;
+    [key: string]: any;
+}
+interface ActiveAuditionPlayback {
+    url?: string;
+    source: AudioBufferSourceNode;
+    sourceNode?: AudioBufferSourceNode;
+    gainNode?: GainNode;
+    startTime: number;
+    duration: number;
+    [key: string]: any;
+}
+
+declare class AudioClipEngine {
+    private bufferCache;
+    private maxCacheSize;
+    private loadingPromises;
+    private activeSources;
+    private activePlaybacks;
+    private activeAudition;
+    getContext(): AudioContext;
+    private setBufferCacheEntry;
+    getOrCreatePresetBuffer(sampleType: SamplePresetType): AudioBuffer;
+    extractWaveformData(buffer: AudioBuffer, numPoints?: number): number[];
+    loadSampleFromUrl(url: string): Promise<{
+        buffer: AudioBuffer;
+        peaks: number[];
+    }>;
+    getOrLoadBuffer(sampleType: SamplePresetType, customUrl?: string): Promise<AudioBuffer>;
+    auditionSampleUrl(url: string, onEnded?: () => void): Promise<void>;
+    stopAudition(): void;
+    getAuditionProgress(): {
+        isPlaying: boolean;
+        progress: number;
+    };
+    playAudioTrack(track: AudioTrackData, bpm: number, destination?: AudioNode, containerId?: string, offsetBeats?: number, volumeScale?: number, panOffset?: number): Promise<void>;
+    getTrackPlaybackProgress(trackId: string): {
+        isPlaying: boolean;
+        progress: number;
+        currentBeat: number;
+        elapsedSec: number;
+    };
+    stopAudioTrack(trackId: string): void;
+    loadAudioFile(file: File): Promise<{
+        buffer: AudioBuffer;
+        peaks: number[];
+        url: string;
+    }>;
+    startRecording(node: any, currentBeat: number, onUpdateNode?: (updated: any) => void): void;
+    stopRecordingToContainer(node: any, targetContainer: any | any[] | null, onUpdateNode?: (updated: any) => void): void;
+}
+declare const audioClipEngine: AudioClipEngine;
+
+interface HardwareProfileResult {
+    detectedInputChannels: number;
+    detectedOutputChannels: number;
+    interfaceModelName: string;
+    isKnownInterface: boolean;
+    channelDescriptions: Record<number, string>;
+    outputDescriptions: Record<string, string>;
+}
+interface OutputChannelInfo {
+    id: string;
+    label: string;
+    shortLabel: string;
+    isStereo: boolean;
+    channels: number[];
+}
+declare function detectHardwareProfile(inputLabel: string, outputLabel: string, trackSettings?: MediaTrackSettings, trackCapabilities?: any, destMaxChannels?: number): HardwareProfileResult;
+declare function buildInputChannelList(totalChannels: number, descriptions?: Record<number, string>): HardwareChannelInfo[];
+declare function buildOutputChannelList(totalChannels: number, descriptions?: Record<string, string>): OutputChannelInfo[];
+
+declare const DEFAULT_NAMED_BUSSES: NamedAudioBus[];
+
+declare const DEFAULT_NAMED_INPUTS: NamedAudioBus[];
+declare class AudioInputManager {
+    private audioCtx;
+    mediaStream: MediaStream | null;
+    private sourceNode;
+    private busDriver;
+    private isListening;
+    private listeners;
+    namedInputs: NamedAudioBus[];
+    selectedDeviceId: string;
+    selectedOutputDeviceId: string;
+    hardwareChannelCount: number;
+    detectedTrackChannelCount: number;
+    isHardwareAutoDetected: boolean;
+    detectedInterfaceName: string;
+    activeProfile: HardwareProfileResult | null;
+    availableDevices: AudioDeviceInfo[];
+    availableOutputDevices: AudioDeviceInfo[];
+    lastError: string | null;
+    constructor();
+    private registerWithSynthEngine;
+    private initDeviceChangeListener;
+    subscribe(listener: () => void): () => void;
+    notifyListeners(): void;
+    isConnected(): boolean;
+    get isAudioActive(): boolean;
+    loadConfig(): ConnectionsConfig;
+    saveConfig(config?: Partial<ConnectionsConfig>): void;
+    enumerateAudioDevices(): Promise<{
+        inputs: AudioDeviceInfo[];
+        outputs: AudioDeviceInfo[];
+    }>;
+    refreshHardwareProfile(): void;
+    selectNativeAudioOutput(): Promise<boolean>;
+    getLastError(): string | null;
+    clearError(): void;
+    initAudioStream(deviceId?: string): Promise<boolean>;
+    reconnectStream(): Promise<void>;
+    setOutputDevice(deviceId: string): Promise<boolean>;
+    getAvailableInputChannels(): HardwareChannelInfo[];
+    getAvailableOutputChannels(): OutputChannelInfo[];
+    getActiveDeviceLabel(): string;
+    getActiveOutputDeviceLabel(): string;
+    getChannelLevel(channel: number): number;
+    syncEndpointsToRegistry(): void;
+    getBusLevel(busId: string): number;
+    getInputLevel(inputId: string): number;
+    setNamedInputs(inputs: NamedAudioBus[]): void;
+    addNamedBus(bus: NamedAudioBus): void;
+    addNamedInput(input: NamedAudioBus): void;
+    addInputBus(): NamedAudioBus;
+    addOutputBus(): NamedAudioBus;
+    updateNamedInput(updated: NamedAudioBus): void;
+    deleteNamedInput(id: string): void;
+    updateMonitoringConnections(nodes: SpaceNode[], connections: NodeConnection[]): void;
+    stopStream(): void;
+}
+declare const audioInputManager: AudioInputManager;
+
+interface MidiEventPayload {
+    type: 'noteon' | 'noteoff' | 'cc' | 'pitchbend' | 'aftertouch' | 'programchange';
+    note: number;
+    noteName: string;
+    velocity: number;
+    channel: number;
+    deviceId?: string;
+    deviceName?: string;
+    controller?: number;
+    value?: number;
+    timestamp: number;
+}
+type MidiStatus = 'uninitialized' | 'requesting' | 'connected' | 'denied' | 'unsupported';
+type MidiListener = (event: MidiEventPayload) => void;
+type DeviceListener = (devices: MidiInputDevice[]) => void;
+type StatusListener = (status: MidiStatus, message: string) => void;
+
+declare class MidiManager {
+    private midiAccess;
+    private listeners;
+    private deviceListeners;
+    private statusListeners;
+    isSupported: boolean;
+    status: MidiStatus;
+    statusMessage: string;
+    devices: MidiInputDevice[];
+    lastEvent: MidiEventPayload | null;
+    private isRequesting;
+    init(userTriggered?: boolean): Promise<boolean>;
+    refreshDevices(): void;
+    private handleMidiMessage;
+    emitVirtualMidi(payload: MidiEventPayload): void;
+    addListener(fn: MidiListener): () => void;
+    addMessageListener(fn: MidiListener): () => void;
+    sendControlChange(channel: number, controller: number, value: number, outputId?: string): void;
+    sendNoteOn(channel: number, note: number, velocity?: number, outputId?: string): void;
+    sendNoteOff(channel: number, note: number, outputId?: string): void;
+    addDeviceListener(fn: DeviceListener): () => void;
+    addStatusListener(fn: StatusListener): () => void;
+    private setStatus;
+}
+declare const midiManager: MidiManager;
+
+interface BufferedMidiEvent {
+    note: number;
+    name: string;
+    velocity: number;
+    beat: number;
+    duration: number;
+    cycleIndex: number;
+    timestamp: number;
+}
+interface BufferedAudioPeak {
+    beat: number;
+    peakL: number;
+    peakR: number;
+    cycleIndex: number;
+    timestamp: number;
+}
+interface BufferedCurvePoint {
+    id: string;
+    x: number;
+    y: number;
+    tension: number;
+    cycleIndex: number;
+    beat: number;
+}
+interface RetrospectiveCycleInfo {
+    bufferBeats: number;
+    currentCycleIndex: number;
+    beatInCurrentCycle: number;
+    cycleProgress: number;
+    captureBoundaryBeats: number;
+    captureBoundaryRatio: number;
+    isAfterBoundary: boolean;
+    targetedCycleIndex: number;
+    isPreviousCycleAvailable: boolean;
+    activeEventsInCurrentCycle: number;
+    activeEventsInPreviousCycle: number;
+}
+type SnapshotListener = (recorderId: string, packet: StoredPacket, containerId?: string) => void;
+
+declare class RetrospectiveBufferEngine {
+    private midiHistory;
+    private audioHistory;
+    private curveHistory;
+    private snapshotListeners;
+    /**
+     * Subscribes to capture snapshots for visual feedback
+     */
+    onSnapshotCaptured(listener: SnapshotListener): () => void;
+    private notifySnapshotCaptured;
+    /**
+     * Calculates effective buffer duration entirely in musical clock units:
+     * buffer_length = bars * 4 + beats + (beat_fractions / 64)
+     */
+    getEffectiveBufferLengthBeats(node: RecorderNode): number;
+    /**
+     * Calculates capture boundary in beats within a cycle
+     */
+    getCaptureBoundaryBeats(node: RecorderNode, bufferBeats: number): number;
+    /**
+     * Evaluates the rolling ring-buffer cycle state and boundary determination for a recorder
+     */
+    getCycleInfo(node: RecorderNode, currentBeat: number): RetrospectiveCycleInfo;
+    /**
+     * Ingests continuous live audio peak into the continuous rolling ring buffer
+     */
+    recordAudioPeak(recorderId: string, peakL: number, peakR: number, currentBeat: number, bufferBeats?: number): void;
+    /**
+     * Gets live audio peaks for circular ring display
+     */
+    getAudioPeaksForRecorder(recorderId: string): BufferedAudioPeak[];
+    /**
+     * Ingests a live MIDI note event into the continuous rolling ring buffer
+     */
+    recordMidiEvent(recorderId: string, evt: MidiEventPayload, currentBeat: number, durationBeats?: number, bufferBeats?: number): void;
+    /**
+     * Gets live MIDI events for circular ring display
+     */
+    getMidiEventsForRecorder(recorderId: string): BufferedMidiEvent[];
+    /**
+     * Ingests a live CV curve point into the continuous rolling ring buffer
+     */
+    recordCurvePoint(recorderId: string, value: number, currentBeat: number, bufferBeats?: number): void;
+    /**
+     * Captures a quantized snapshot take from the continuous ring buffer
+     * and pushes it to connected Containers, replacing their previous packet.
+     * Ring buffer CONTINUES operating normally without stopping or clearing.
+     */
+    captureSnapshot(node: RecorderNode, targetContainers: ContainerNode | ContainerNode[] | null, triggerBeat: number, bpm?: number, onUpdateNode?: (updated: RecorderNode) => void, onUpdateContainer?: (updated: ContainerNode) => void): {
+        packet: StoredPacket;
+        updatedNode: RecorderNode;
+        updatedContainers: ContainerNode[];
+    };
+    /**
+     * Resets buffer history for a recorder (if removed or reset manually)
+     */
+    clearBuffer(recorderId: string): void;
+}
+declare const retrospectiveBufferEngine: RetrospectiveBufferEngine;
+
+/**
+ * ============================================================================
+ * Audio Graph Node Authority & Inheritance Hierarchy
+ * ============================================================================
+ *
+ * STRICT ARCHITECTURAL INVARIANT:
+ * No individual node in the graph (MIDI Instruments, Samplers, Audio Containers,
+ * Synthesizers, Inputs, Effects) has direct access or authority to emit audio
+ * directly into the application's master audio output (speakers / AudioContext.destination).
+ *
+ * Direct emission capability is structurally disabled (`canEmitDirectlyToMaster() === false`)
+ * on the base class and all standard node subclasses.
+ *
+ * The ONLY class in this entire hierarchy permitted to emit to the hardware master output
+ * is `MasterAudioOutputGraphNode`.
+ *
+ * For all other nodes, audio emission is STRUCTURALLY IMPOSSIBLE unless an active, unmuted,
+ * valid graph path connects the node's output to an active `MasterAudioOutputGraphNode`.
+ */
+declare abstract class BaseAudioGraphNode {
+    abstract readonly id: string;
+    abstract readonly nodeType: string;
+    /**
+     * Root capability flag.
+     * By rule, base nodes CANNOT emit directly to the master output.
+     */
+    canEmitDirectlyToMaster(): boolean;
+    /**
+     * Evaluates if this node is structurally authorized to emit audio.
+     * Standard nodes must prove reachability to a MasterAudioOutputGraphNode
+     * through the active graph connection topology.
+     */
+    isAuthorizedToEmit(graphReachabilityChecker: (nodeId: string) => boolean): boolean;
+}
+/**
+ * Master Audio Output Graph Node (Output Strip)
+ * The ONLY class in the graph authorized to emit directly to master hardware output.
+ */
+declare class MasterAudioOutputGraphNode extends BaseAudioGraphNode {
+    readonly id: string;
+    active: boolean;
+    readonly nodeType = "output_strip";
+    constructor(id: string, active?: boolean);
+    canEmitDirectlyToMaster(): boolean;
+}
+/**
+ * Base class for all audio source nodes (signal producers).
+ */
+declare abstract class BaseSourceAudioGraphNode extends BaseAudioGraphNode {
+    readonly isSourceNode = true;
+}
+/**
+ * MIDI Instrument VST Node (Plugin Nexus)
+ * STRICT RULE: Cannot emit audio directly to master output without a connection to AudioOutputNode.
+ */
+declare class MidiInstrumentGraphNode extends BaseSourceAudioGraphNode {
+    readonly id: string;
+    readonly pluginId: string;
+    volume: number;
+    readonly nodeType = "instrument";
+    constructor(id: string, pluginId?: string, volume?: number);
+}
+/**
+ * Audio Container Node (Recorded / Sample Audio Clips)
+ * STRICT RULE: Cannot emit audio directly to master output without a connection to AudioOutputNode.
+ */
+declare class AudioContainerGraphNode extends BaseSourceAudioGraphNode {
+    readonly id: string;
+    readonly audioFormat: 'mono' | 'stereo';
+    readonly nodeType = "audio";
+    constructor(id: string, audioFormat?: 'mono' | 'stereo');
+}
+/**
+ * MIDI Synth Container Node
+ * STRICT RULE: Cannot emit audio directly to master output without a connection to AudioOutputNode.
+ */
+declare class MidiContainerGraphNode extends BaseSourceAudioGraphNode {
+    readonly id: string;
+    readonly nodeType = "midi";
+    constructor(id: string);
+}
+/**
+ * Base class for all audio processor / DSP nodes (Effects, Combiners, Multiplexers, Converters).
+ */
+declare abstract class BaseProcessorAudioGraphNode extends BaseAudioGraphNode {
+    readonly isProcessorNode = true;
+}
+/**
+ * Effect DSP Node (Delay, Reverb, Repeater, Gain, etc.)
+ */
+declare class EffectProcessorGraphNode extends BaseProcessorAudioGraphNode {
+    readonly id: string;
+    readonly effectType: string;
+    active: boolean;
+    readonly nodeType = "effect";
+    constructor(id: string, effectType: string, active?: boolean);
+}
+/**
+ * Signal Router Node (Combiner / Multiplexer / Converter)
+ */
+declare class SignalRouterGraphNode extends BaseProcessorAudioGraphNode {
+    readonly id: string;
+    active: boolean;
+    readonly nodeType: 'combiner' | 'multiplexer' | 'converter';
+    constructor(id: string, type: 'combiner' | 'multiplexer' | 'converter', active?: boolean);
+}
+/**
+ * Factory to construct the corresponding strongly-typed graph node instance
+ * for any generic SpaceNode.
+ */
+declare function createAudioGraphNode(node: SpaceNode): BaseAudioGraphNode;
+
+declare function generatePresetAudioBuffer(ctx: AudioContext, sampleType: SamplePresetType): AudioBuffer;
+
+declare class CurveEngine {
+    evaluateCurve(curve: CurveTrackData, currentBeat: number): number;
+    generatePresetPoints(type: 'sine' | 'triangle' | 'saw_up' | 'saw_down' | 'exp_rise' | 'exp_fall' | 'step', lengthInBeats: number): CurvePoint[];
+    applyModulation(curve: CurveTrackData, valNorm: number, nodes: SpaceNode[], onUpdateNode?: (node: SpaceNode) => void): void;
+}
+declare const curveEngine: CurveEngine;
+
+interface KnownDevicePattern {
+    pattern: RegExp;
+    name: string;
+    inChannels: number;
+    outChannels: number;
+    inNames?: Record<number, string>;
+    outNames?: Record<string, string>;
+}
+declare const KNOWN_PATTERNS: KnownDevicePattern[];
+
+declare class MultiChannelOutputRouter {
+    private ctx;
+    private mergerNode;
+    private splitterNode;
+    private routeGainL;
+    private routeGainR;
+    private currentChannelRouting;
+    private maxChannels;
+    init(ctx: AudioContext, initialChannels?: number): void;
+    private setupMerger;
+    connectInput(sourceNode: AudioNode): void;
+    setMaxChannels(channels: number): void;
+    applyRouting(routingId: string): void;
+    setOutputSinkId(deviceId: string): Promise<boolean>;
+}
+declare const multiChannelOutputRouter: MultiChannelOutputRouter;
+
+declare function createCosmicImpulseBuffer(ctx: AudioContext, duration: number, decay: number): AudioBuffer;
+declare function playSyntheticDrumVoice(ctx: AudioContext, masterGain: GainNode, noteNumber: number, vel: number, time: number): void;
+
+/**
+ * 3-Band Crossover Filter Network for Multiband Dynamic Processing
+ */
+interface CrossoverBandNodes {
+    input: GainNode;
+    lowOutput: AudioNode;
+    midOutput: AudioNode;
+    highOutput: AudioNode;
+    sumOutput: GainNode;
+    setFrequencies: (lowFreq: number, highFreq: number) => void;
+    dispose: () => void;
+}
+declare function create3BandCrossover(ctx: AudioContext, initialLowFreq?: number, initialHighFreq?: number): CrossoverBandNodes;
+
+interface AudioEffectProcessorInstance {
+    input: AudioNode;
+    output: AudioNode;
+    sidechainInput?: GainNode;
+    updateEffect: (effect: EffectNode) => void;
+    getReductionDb: () => number | {
+        low: number;
+        mid: number;
+        high: number;
+    };
+    dispose: () => void;
+}
+
+/**
+ * Unified DSP Audio Effect Processor Factory
+ * Instantiates real Web Audio graph pipelines for EQ, Compressor, Multiband, Limiter, Reverb, Delay, Saturation.
+ */
+declare function createAudioEffectProcessor(ctx: AudioContext, effect: EffectNode): AudioEffectProcessorInstance;
+
+/**
+ * Algorithmic Stereo Impulse Response Generator for ConvolverNode Reverb
+ */
+declare function generateReverbImpulse(ctx: AudioContext, durationSec?: number, decayFactor?: number, dampingFreq?: number): AudioBuffer;
+
+/**
+ * Saturation & Distortion Non-Linear Transfer Curves for Web Audio WaveShaperNode
+ */
+declare function generateSaturationCurve(type: 'tape' | 'tube' | 'soft_clip' | 'hard_clip' | 'foldback', drive?: number, samples?: number): Float32Array;
+
+/**
+ * Sidechain Compressor Engine for Web Audio
+ * Supports standard dynamic compression as well as external sidechain key ducking.
+ */
+
+interface SidechainCompressorInstance {
+    input: GainNode;
+    output: GainNode;
+    sidechainInput: GainNode;
+    compressorNode: DynamicsCompressorNode;
+    updateConfig: (config: CompressorEffectConfig) => void;
+    getReductionDb: () => number;
+    dispose: () => void;
+}
+declare function createSidechainCompressor(ctx: AudioContext, initialConfig?: CompressorEffectConfig): SidechainCompressorInstance;
+
+/**
+ * 3-Band Multiband Compressor with Frequency Crossover & Selective Sidechaining
+ */
+
+interface MultibandCompressorInstance {
+    input: GainNode;
+    output: GainNode;
+    sidechainInput: GainNode;
+    updateConfig: (config: MultibandCompressorEffectConfig) => void;
+    getReductionDb: () => {
+        low: number;
+        mid: number;
+        high: number;
+    };
+    dispose: () => void;
+}
+declare function createMultibandCompressor(ctx: AudioContext, initialConfig?: MultibandCompressorEffectConfig): MultibandCompressorInstance;
+
+interface SynthEngineState {
+    ctx: AudioContext | null;
+    masterGain: GainNode | null;
+    delayNode: DelayNode | null;
+    delayFeedback: GainNode | null;
+    delayGain: GainNode | null;
+    reverbNode: ConvolverNode | null;
+    reverbGain: GainNode | null;
+    analyser: AnalyserNode | null;
+    analyserL: AnalyserNode | null;
+    analyserR: AnalyserNode | null;
+    masterSplitter: ChannelSplitterNode | null;
+    nodeVisuals: INodeVisuals | null;
+    isInitialized: boolean;
+    nodeActiveUntilMap: Map<string, number>;
+    graphNodeMap: Map<string, BaseAudioGraphNode>;
+    activeNodes: SpaceNode[];
+    activeConnections: NodeConnection[];
+    lastPlayedMidiNote: {
+        note: number;
+        velocity: number;
+        timestamp: number;
+    } | null;
+}
+
+declare class AudioContextManager {
+    private configManager;
+    initContext(state: SynthEngineState): void;
+}
+
+declare class SynthConfigManager {
+    private config;
+    private loadAudioConfig;
+    getConfig(): AudioEngineConfig;
+    updateConfig(newConfig: Partial<AudioEngineConfig>): void;
+}
+
+declare const STORAGE_KEY_AUDIO_CONFIG = "celestial_audio_engine_config";
+declare const DEFAULT_AUDIO_CONFIG: AudioEngineConfig;
+
+/**
+ * @role skeleton
+ * AudioEffects Entity Orchestrator
+ * Groups, orchestrates, and manages audio effect DSP lifecycles and domain events.
+ */
+
+interface AudioEffectsState {
+    activeEffectIds: string[];
+    processors: Map<string, AudioEffectProcessorInstance>;
+}
+declare class AudioEffects {
+    private state;
+    private eventListeners;
+    on(event: string, listener: (payload: any) => void): () => void;
+    off(event: string, listener: (payload: any) => void): void;
+    emit(event: string, payload?: any): void;
+    getOrCreateProcessor(ctx: AudioContext, effect: EffectNode): AudioEffectProcessorInstance;
+    removeProcessor(effectId: string): void;
+    getActiveEffectIds(): string[];
+    getReductionDb(effectId: string): number | {
+        low: number;
+        mid: number;
+        high: number;
+    };
+    disposeAll(): void;
+}
+declare const audioEffectsEntity: AudioEffects;
+
+interface OscMessage {
+    address: string;
+    args: Array<number | string | boolean>;
+    timestamp: number;
+    sourceDeviceId?: string;
+    sourceDeviceName?: string;
+}
+type OscDeviceType = 'network_udp' | 'websocket_bridge' | 'touchosc' | 'lemur' | 'max_msp' | 'puredata' | 'supercollider' | 'vrchat';
+interface OscDevice {
+    id: string;
+    name: string;
+    type: OscDeviceType;
+    host: string;
+    port: number;
+    status: 'connected' | 'listening' | 'disconnected' | 'simulated';
+    enabled: boolean;
+    isCustom?: boolean;
+}
+type OscListener = (message: OscMessage) => void;
+type OscDeviceListener = (devices: OscDevice[]) => void;
+declare const DEFAULT_OSC_DEVICES: OscDevice[];
+
+declare class OscManager {
+    private listeners;
+    private addressListeners;
+    private deviceListeners;
+    devices: OscDevice[];
+    lastMessage: OscMessage | null;
+    messageLog: OscMessage[];
+    isLearning: boolean;
+    private learningCallback;
+    init(): void;
+    receiveOscMessage(message: OscMessage): void;
+    sendOscMessage(address: string, args?: Array<number | string | boolean>, targetDeviceId?: string): OscMessage;
+    startLearn(callback: (msg: OscMessage) => void): () => void;
+    addDevice(device: Omit<OscDevice, 'id'>): OscDevice;
+    updateDevice(id: string, updates: Partial<OscDevice>): void;
+    removeDevice(id: string): void;
+    toggleDevice(id: string): void;
+    addListener(fn: OscListener): () => void;
+    addAddressListener(pattern: string, fn: OscListener): () => void;
+    addDeviceListener(fn: OscDeviceListener): () => void;
+    private notifyDeviceListeners;
+    private matchesPattern;
+}
+declare const oscManager: OscManager;
+
+declare const SynthEngineServiceDefinition: ServiceDefinition;
+declare const SynthEngineServiceFacade: {
+    id: string;
+    name: string;
+    version: string;
+    runtime: "client";
+    deployment: "local";
+    definition: ServiceDefinition<Record<string, unknown>, Record<string, unknown>>;
+    engine: SynthEngine;
+    createInstance: () => _dinilmusick_krnl.ServiceInstance<Record<string, unknown>, Record<string, unknown>>;
+    execute: <TIn = unknown, TOut = unknown>(op: string, input?: TIn) => Promise<TOut>;
+};
+declare const SequencerEngineServiceDefinition: ServiceDefinition;
+declare const SequencerEngineServiceFacade: {
+    id: string;
+    name: string;
+    version: string;
+    runtime: "client";
+    deployment: "local";
+    definition: ServiceDefinition<Record<string, unknown>, Record<string, unknown>>;
+    engine: SequencerEngine;
+    createInstance: () => _dinilmusick_krnl.ServiceInstance<Record<string, unknown>, Record<string, unknown>>;
+    execute: <TIn = unknown, TOut = unknown>(op: string, input?: TIn) => Promise<TOut>;
+};
+declare const OscServiceDefinition: ServiceDefinition;
+declare const OscServiceFacade: {
+    id: string;
+    name: string;
+    version: string;
+    runtime: "client";
+    deployment: "local";
+    definition: ServiceDefinition<Record<string, unknown>, Record<string, unknown>>;
+    engine: OscManager;
+    createInstance: () => _dinilmusick_krnl.ServiceInstance<Record<string, unknown>, Record<string, unknown>>;
+    execute: <TIn = unknown, TOut = unknown>(op: string, input?: TIn) => Promise<TOut>;
+};
+
+/**
+ * @file index.ts
+ * @description kloks/audio-midi — KrnlTS-backed Pro-Audio Named Bus & Reactive Web MIDI Services.
+ * Converted from Skipo audio-midi engine into first-class KrnlTS services and orchestrators.
+ */
+
+interface AudioServiceEvents extends Record<string, unknown> {
+    stateChange: AudioHardwareState;
+}
+declare function createAudioHardwareService(manager?: AudioInputManager$1): IService<AudioHardwareState & Record<string, unknown>, AudioServiceEvents>;
+declare const AudioHardwareServiceDefinition: ServiceDefinition;
+declare const AudioHardwareServiceFacade: {
+    id: string;
+    name: string;
+    version: string;
+    runtime: "client";
+    deployment: "local";
+    definition: ServiceDefinition<Record<string, unknown>, Record<string, unknown>>;
+    createInstance: typeof createAudioHardwareService;
+    execute: <TIn = unknown, TOut = unknown>(op: string, input?: TIn) => Promise<TOut>;
+};
+interface MidiServiceEvents extends Record<string, unknown> {
+    midiEvent: MidiEventPayload$1;
+    stateChange: MidiSubsystemState;
+}
+declare function createMidiService(manager?: MidiManager$1): IService<MidiSubsystemState & Record<string, unknown>, MidiServiceEvents>;
+declare const MidiServiceDefinition: ServiceDefinition;
+declare const MidiServiceFacade: {
+    id: string;
+    name: string;
+    version: string;
+    runtime: "client";
+    deployment: "local";
+    definition: ServiceDefinition<Record<string, unknown>, Record<string, unknown>>;
+    createInstance: typeof createMidiService;
+    execute: <TIn = unknown, TOut = unknown>(op: string, input?: TIn) => Promise<TOut>;
+};
+declare const AudioMidiOrchestratorFacade: {
+    id: string;
+    name: string;
+    version: string;
+    dependencies: string[];
+    execute: (input: {
+        midiCommand: MidiCommandType;
+        note?: number;
+        velocity?: number;
+        channel?: number;
+    }) => Promise<{
+        midiEvent: MidiEventPayload$1;
+        audioState: AudioHardwareState;
+        routedAt: number;
+    }>;
+};
+
+export { type ActiveAuditionPlayback, type ActiveTrackPlayback, type AudioBusConfig, AudioClipEngine, AudioContainerGraphNode, AudioContextManager, type AudioDeviceDescriptor, type AudioEffectProcessorInstance, AudioEffects, type AudioEffectsState, type AudioEngineConfig, AudioHardwareServiceDefinition, AudioHardwareServiceFacade, type AudioHardwareState, AudioInputManager$1 as AudioInputManager, AudioMidiOrchestratorFacade, type AudioServiceEvents, type AudioStateListener, BaseAudioGraphNode, BaseProcessorAudioGraphNode, BaseSourceAudioGraphNode, type BufferedAudioPeak, type BufferedCurvePoint, type BufferedMidiEvent, type CrossoverBandNodes, CurveEngine, DEFAULT_AUDIO_CONFIG, DEFAULT_NAMED_BUSSES, DEFAULT_NAMED_INPUTS, DEFAULT_OSC_DEVICES, type DeviceListener, EffectProcessorGraphNode, type MidiEventPayload as EngineMidiEventPayload, type HardwareProfileResult, KNOWN_PATTERNS, type KnownDevicePattern, MasterAudioOutputGraphNode, type MidiCommandType, MidiContainerGraphNode, type MidiEventListener, type MidiEventPayload$1 as MidiEventPayload, MidiInstrumentGraphNode, type MidiListener, MidiManager$1 as MidiManager, type MidiPortDescriptor, MidiServiceDefinition, type MidiServiceEvents, MidiServiceFacade, type MidiStateListener, type MidiStatus, type MidiSubsystemState, MultiChannelOutputRouter, type MultibandCompressorInstance, type OscDevice, type OscDeviceListener, type OscDeviceType, type OscListener, OscManager, type OscMessage, OscServiceDefinition, OscServiceFacade, type OutputChannelInfo, RetrospectiveBufferEngine, type RetrospectiveCycleInfo, STORAGE_KEY_AUDIO_CONFIG, SequencerEngine, SequencerEngineServiceDefinition, SequencerEngineServiceFacade, type SidechainCompressorInstance, SignalRouterGraphNode, type SnapshotListener, type StatusListener, SynthConfigManager, SynthEngine, SynthEngineServiceDefinition, SynthEngineServiceFacade, type SynthEngineState, audioClipEngine, audioEffectsEntity, audioInputManager, buildInputChannelList, buildOutputChannelList, create3BandCrossover, createAudioEffectProcessor, createAudioGraphNode, createAudioHardwareService, createCosmicImpulseBuffer, createMidiService, createMultibandCompressor, createSidechainCompressor, curveEngine, detectHardwareProfile, generatePresetAudioBuffer, generateReverbImpulse, generateSaturationCurve, midiManager, multiChannelOutputRouter, oscManager, playContainerNoteWithEffects, playSyntheticDrumVoice, processActiveContainers, retrospectiveBufferEngine, sequencerEngine, synthEngine };