swing-ui 0.1.25 → 1.0.1

package/SwingUI.js

@@ -0,0 +1,2611 @@
+import {Worker, MessageChannel, receiveMessageOnPort} from "worker_threads";
+import path from "node:path";
+import fs from "node:fs";
+import zlib from "zlib"; // https://nodejs.org/api/zlib.html#class-options
+import {execFileSync} from "node:child_process";
+
+/**
+ * Main SwingUI class that handles all communication between JavaScript and GUI and provides many utility methods not related to specific GUI components.
+ * <b>NOTE:</b> Do not instantiate this class, but instead use global `ui` constant, which is an instance of this class.
+ *
+ * See usage example below.
+ *
+ * @class
+ * @global
+ * @see ui
+ * @example <h2>Usage examples:</h2>
+ * const data = ui.clipboard(); // getting clipboard data
+ * const _screens = ui.screens; // getting screens information array
+ * ui.openURL("http://swing-ui.com/");
+ */
+export class SwingUI
+{
+	/**
+	 * @internal
+	 * @private
+	 */
+	stats = {in: 0, out: 0, start: new Date()};
+	#gui_version = "0.3.1"; // (Not a module version. For internal use only.)
+	/**
+	 * @internal
+	 * @private
+	 */
+	gui_process_id = null;
+	#module_dir = undefined;
+	#root_dir = undefined;
+	#js_runtime = typeof Bun !== "undefined" ? "bun" : typeof Deno !== "undefined" ? "deno" : typeof process !== "undefined" && process.versions && process.versions.node ? "node" : "unknown";
+	#watchdog_timer = null;
+	#sleepBuffer = new Int32Array(new SharedArrayBuffer(4)); // used in ui.sleep(N)
+
+	#processingStack = false;
+	#_msg_queue = [];
+	#queue_limit = 100; // send queued messages after queue size reaches this limit (0 = no message queue)
+	#msgCompressThreshold = 1000; // compress messages longer than this
+	#textDecoder = new TextDecoder("utf8");
+
+	#jvm = {
+		stdio: {}, JBridge: null, process: null, eventListener: e =>
+		{
+		}
+	};
+	#guiManagerWorker = null; // for GUI Process manager worker
+	#exiting = false;
+
+	/**
+	 * @internal
+	 * @private
+	 */
+	callback = {
+		//Error handler function that ui.onError can override(callback)
+		onError: function(e)
+		{
+			dialog(e.message.replaceAll("<", "&lt;").replaceAll(">", "&gt;"), e.target !== undefined ? `Error with ${e.target.constructor.name}#${e.target.id}` : `GUI Error`, ["OK"], MessageIcon.Error, e.target !== undefined ? e.target.window : null);
+		}, // Replace HTML tag arrows to make sure they are not rendered as HTML in GUI dialog window
+		onAppEvents: [
+			// Event handler to handle Exit message from GUI
+			e =>
+			{
+				if(e.type === "Exit") this.exit(e.code);
+			}
+		]
+	}; // for global events
+
+	/**
+	 * @internal
+	 * @private
+	 */
+	_msg = {
+		0: "Calling a function of a destroyed UI component",
+		1: "Cannot add UI component to a not UI component",
+		2: "Argument should be UIComponent, but received 'undefined'.",
+		3: "Unidentified message type received from GUI: ",
+		4: "Unhandled Event: ",
+		5: "Invalid response to message received: ",
+		6: "Node.js Exception when processing event on ",
+		7: "Node.js Exception when processing response.",
+		8: "Application root directory could not be detected. Either start the project from the project directory, set it as a working directory, or use the --root-dir=\"DIRECTORY_PATH\" option to specify the project directory. Current working directory: ",
+		9: "Error while decoding message from GUI: ",
+		10: "Failed to set context menu. Passed parameter must be of type ContextMenu and can't be added to self",
+		11: "Failed to set menu menu. Passed parameter must be of type MenuBar()"
+	};
+
+	//region For Worker IPC only
+
+	#useWorkerThread = false;
+	#worker_port1 = null;
+	#worker_port2 = null;
+
+	/**
+	 * @internal
+	 * @private
+	 */
+	static WorkerSignalIndex = Object.freeze({
+		ExecutionControl: 0,
+		WorkerControl: 1,
+		DataLength: 2,
+		ReceivedBytes: 3,
+		SentBytes: 4
+	});
+
+	/**
+	 * @internal
+	 * @private
+	 */
+	static WorkerSignal = Object.freeze({Resume: 0, Pause: 1, SendLine: 2, Block: 3, Unblock: 4, SendBytes: 5});
+
+	#sharedBuffSignal = new Int32Array(new SharedArrayBuffer(4));
+
+	//endregion
+
+	#inputLinesBuffer = new class
+	{
+		_buff = [];
+		pos = 0;
+		max = 200;
+		timer = null;
+
+		get length()
+		{
+			return this._buff.length - this.pos;
+		}
+
+		push(val)
+		{
+			this._buff.push(val);
+		}
+
+		pull()
+		{
+			if(this.pos < this._buff.length)
+			{
+				const val = this._buff[this.pos++];
+
+				if(this.pos > this.max && this.timer === null)
+				{
+					this.timer = setTimeout(() =>
+					{
+						this._buff = this._buff.slice(this.pos);
+						this.pos = 0;
+						this.timer = null;
+					}, 1000);
+				}
+
+				return val;
+			}
+
+			return undefined;
+		}
+	}();
+
+	/**
+	 * Detects best compatible base64 decoder
+	 */
+	#decodeBase64 = typeof Uint8Array.fromBase64 === 'function' ? b64 => Uint8Array.fromBase64(b64) : typeof Buffer !== 'undefined' ? b64 => Buffer.from(b64, 'base64') : b64 => Uint8Array.from(atob(b64), c => c.charCodeAt(0));
+
+	//region Internal
+
+	/**
+	 * <b>NOTE:</b> Do not instantiate this class. It's already instantiated and assigned to a global variable `ui`.
+	 * @internal
+	 * @private
+	 */
+	constructor(module_dir, JBridge)
+	{
+		this.#module_dir = module_dir;
+		this.#jvm.JBridge = JBridge;
+		this.rootDirectory; // detect project dir now
+
+		// ensure cleanup
+		process.on("exit", this.exit.bind(this));
+		process.on("SIGINT", this.exit.bind(this, 0, "SIGINT")); //catches ctrl+c event
+
+		// catches "kill pid" (for example: nodemon restart) on some operating systems
+		process.on("SIGUSR1", this.exit.bind(this, 0, "SIGUSR1"));
+		process.on("SIGUSR2", this.exit.bind(this, 0, "SIGUSR2"));
+		process.on("SIGTERM", this.exit.bind(this, 0, "SIGTERM"));
+		process.on("SIGHUP", this.exit.bind(this, 0, "SIGHUP"));
+	}
+
+	async InitGUIProcess()
+	{
+		if(this.runtime === "bun" || this.os === "darwin") this.#useWorkerThread = true;
+
+		const env = this.env;
+
+		if(process.argv.some(arg => arg.startsWith("--java-dir="))) env.JAVA_HOME = process.argv.find(arg => arg.startsWith("--java-dir=")).split("=")[1];
+
+		if(this.#useWorkerThread)
+		{
+			this.#msgCompressThreshold = 500; // reduce the threshold
+
+			const {port1, port2} = new MessageChannel();
+			this.#worker_port1 = port1;
+			this.#worker_port2 = port2;
+
+			// start IPC Worker
+			const workerPath = path.join(this.#module_dir, "ui-process-manager.js");
+
+			// set a value for the thread to wait for the worker to start
+			Atomics.store(this.#sharedBuffSignal, SwingUI.WorkerSignalIndex.ExecutionControl, SwingUI.WorkerSignal.Block);
+
+			const options = {
+				type: "module",
+				workerData: {
+					signalBuffer: this.#sharedBuffSignal,
+					responsePort: this.#worker_port2,
+					moduleDir: this.#module_dir,
+					rootDir: this.rootDirectory,
+					debugJava: process.argv.some(arg => arg === "--debug-java"),
+					verbose: process.argv.some(arg => arg === "--v"),
+					os: this.os,
+					runtime: this.runtime
+				},
+				transferList: [this.#worker_port2],
+				stdout: true,
+				stderr: true,
+				env: env
+			};
+
+			this.#guiManagerWorker = new Worker(workerPath, options);
+
+			// forward worker logs to the main process
+			if(this.#guiManagerWorker.stdout != null) // e.g.. bun, and deno on macOS don't have stdout
+			{
+				this.#guiManagerWorker.stdout.on("data", chunk => console.log(chunk.toString()));
+				this.#guiManagerWorker.stderr.on("data", chunk => console.error(chunk.toString()));
+			}
+
+			this.#guiManagerWorker.on("message", (msg) =>
+			{
+				switch(msg.type)
+				{
+					case "data":
+					{
+						this.#inputLinesBuffer.push(msg.data);
+						if(this.#inputLinesBuffer.length < 2) queueMicrotask(() => {this.#processInputData();});
+						break;
+					}
+					case "exit":
+					{
+						this.exit(0);
+						break;
+					}
+					case "worker_log":
+					{
+						console.log(`WORKER THREAD: ${msg.data}`);
+						break;
+					}
+					case "worker_debug":
+					{
+						console.debug(`WORKER THREAD: ${msg.data}`);
+						break;
+					}
+					case "worker_warn":
+					{
+						console.warn(`WORKER THREAD: ${msg.data}`);
+						break;
+					}
+					case "worker_info":
+					{
+						console.info(`WORKER THREAD: ${msg.data}`);
+						break;
+					}
+					case "worker_error":
+					{
+						console.error(`WORKER THREAD ERROR: ${msg.data}`);
+						break;
+					}
+				}
+			});
+			this.#guiManagerWorker.on("online", () => {});
+			this.#guiManagerWorker.on("error", (err) => console.error("[SwingUI] GUI Worker error:", err));
+			this.#guiManagerWorker.on("exit", (code) =>
+			{
+				if(!this.#exiting && code !== 0) console.error(`[SwingUI] GUI Worker stopped unexpectedly (exit code ${code})`);
+				this.exit(code);
+			});
+
+			// wait for the worker to start
+			const r = Atomics.wait(this.#sharedBuffSignal, SwingUI.WorkerSignalIndex.ExecutionControl, SwingUI.WorkerSignal.Block, 10000);
+			if(r === "timed-out") throw new Error("Failed to start GUI Worker: timeout.");
+		}
+		else
+		{
+			const jvmOpts = {opts: [], env: env};
+			if(process.argv.some(arg => arg === "--debug-java")) jvmOpts.opts.push("-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005");
+			if(this.os === "linux") jvmOpts.opts.push("--add-opens=java.desktop/sun.awt.X11=ALL-UNNAMED"); // to be able to set WM_CLASS in Java GUI
+			if(this.os === "darwin")
+			{
+				jvmOpts.opts.push("-Dapple.awt.UIElement=true");
+				jvmOpts.opts.push("-Dapple.awt.headless=false"); // was supposed to help JVM on macOS, but didn't. macOS doesn't allow GUI on non-main thread.
+			}
+
+			this.#jvm.JBridge.ensureJvm(jvmOpts);
+			this.#jvm.JBridge.appendClasspath(path.join(this.#module_dir, "jar/gui-11.jar"));
+			const JBridgeProcessHandle = this.#jvm.JBridge.importClass("java.lang.ProcessHandle");
+			this.#jvm.process = await JBridgeProcessHandle.current();
+			this.gui_process_id = Number(await this.#jvm.process.pid());
+
+			// receive events from GUI
+			this.#jvm.stdio.stdout = (_, line) =>
+			{
+				line = line.trim();
+				if(!line) return;
+
+				if(line.startsWith("GUI-EVENT->"))
+				{
+					try
+					{
+						const message = this.#textDecoder.decode(this.#decodeBase64(line.substring(11)));
+						this.#inputLinesBuffer.push(message);
+					}catch(ex)
+					{
+						console.error("Failed to parse IPC event:", ex);
+					}
+				}
+				else
+				{
+					console.log(line);
+				}
+
+				this.#processInputData();
+			};
+
+			this.#jvm.stdio.stderr = (_, data) =>
+			{
+				console.error(data);
+			};
+
+			// enable STDIO redirect to our handlers
+			this.#jvm.stdio.guard = this.#jvm.JBridge.stdout.enableRedirect(this.#jvm.stdio.stdout, this.#jvm.stdio.stderr);
+
+/*
+			this.#jvm.eventListener = this.#jvm.JBridge.newProxy("SwingUI$Callback", {
+				eventCall: data =>
+				{
+					if(this.#inputLinesBuffer.length === 0) queueMicrotask(() => {this.#processInputData();});
+
+					data = this.#textDecoder.decode(this.#decodeBase64(data));
+
+					this.#inputLinesBuffer.push(data);
+				}
+			});
+*/
+
+			const ui_class = this.#jvm.JBridge.importClass("SwingUI");
+			const ops = JSON.stringify({
+				module_dir: this.#module_dir,
+				root_dir: this.rootDirectory,
+				verbose: process.argv.some(arg => arg === "--v")
+			});
+			this.#jvm.gui = new ui_class(ops);
+			//await this.#jvm.gui.setEventCallback(this.#jvm.eventListener);
+
+			// Watchdog
+			this.#watchdog_timer = setInterval(() =>
+			{
+				try
+				{
+					process.kill(this.gui_process_id, 0);
+				}catch(ex)
+				{
+					console.log("Watchdog timer says the GUI process exited, so JS can exit too.");
+					if(ex.code === "ESRCH") this.exit(1);
+				}
+			}, 5000);
+		}
+
+		// report current version of this module to UI
+		this.sendToGUI({system: "version", value: this.#gui_version, pid: this.pid}, async r =>
+		{
+			if(!r.confirmed)
+			{
+				this.sendToGUI = m =>
+				{
+				}; // stop sending messages
+				setTimeout(() =>
+				{
+					this.exit(0);
+				}, 10000); // exit automatically if not closed by parent process
+				console.error("GUI version verification failed!");
+			}
+		}, true);
+	}
+
+	#processInputData()
+	{
+		this.#processingStack++;
+
+		// process one line
+		try
+		{
+			if(this.#inputLinesBuffer.length > 0) this.#processInputLine(this.#inputLinesBuffer.pull());
+		}finally
+		{
+			this.#processingStack--;
+
+			// keep processing if there is more data
+			if(this.#inputLinesBuffer.length > 0)
+			{
+				queueMicrotask(() => {this.#processInputData();});
+			}
+		}
+	}
+
+	#processInputLine(msg, callback = null)
+	{
+		if(typeof msg !== "string" || msg.length === 0) return null;
+
+		/*try
+		 {
+		 msg = decodeURIComponent(msg).trim();
+		 }catch(ex)
+		 {
+		 console.error(this._msg[9] + msg + "\n\n" + ex.stack);
+		 console.error(ex);
+		 return null;
+		 }*/
+
+		if(msg.startsWith("{") && msg.endsWith("}"))
+		{
+			try
+			{
+				msg = JSON.parse(msg);
+			}catch(ex)
+			{
+				error(ex + "\n While parsing JSON message from GUI in ui.processInputLine(" + msg + ")\r\n" + ex.stack.toString(), false);
+				return null;
+			}
+
+			// run response callback if passed
+			if(callback !== null)
+			{
+				try
+				{
+					return callback(msg) ?? null;
+				}catch(ex)
+				{
+					error(ex + this._msg[7], false);
+					return null;
+				}
+			}
+
+			// process message
+			return this.#processJsonMessage(msg);
+		}
+		else // treat as CLI input
+		{
+			if(Array.isArray(this.callback.onCLI))
+			{
+				for(let f of this.callback.onCLI)
+				{
+					try
+					{
+						f({data: msg});
+					}catch(ex)
+					{
+						error(`${ex.name} occurred in one of onCLI(callback) event handlers:\n\n${ex.stack}`, false);
+					}
+				}
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * @param {Object} msg
+	 * @return {any}
+	 */
+	#processJsonMessage(msg)
+	{
+		// check for events
+		if(msg.event !== undefined)
+		{
+			try
+			{
+				return this.#processEvent(msg);
+			}catch(ex)
+			{
+				error(`Your ${msg.event}(event) handler has an error:\n\n${ex.stack} \n\nEvent ${stringify(ex)}`, false);
+			}
+		}
+		else if("heartbeat" in msg)
+		{
+			// do nothing
+		}
+		else
+		{
+			alert(this._msg[3] + JSON.stringify(msg));
+			return false;
+		}
+	}
+
+	#processEvent(e)
+	{
+		try
+		{
+			if(e.id === undefined) // check if event has a component ID
+			{
+				return (e.event === "onError") ? this.callback.onError(e) : null; // handle general errors not related to a specific component
+			}
+			else if(e.id === 0) // for global events
+			{
+				e.target = this;
+				delete e.id;
+			}
+			else
+			{
+				e.target = UIComponent.get(e.id); // get target control
+				if(e.target === undefined || e.target.destroyed) return; // don't process events for destroyed components
+				delete e.id;
+			}
+
+			// checks if target was already destroyed
+			if(e.target == null || e.target.callback == null) return;
+
+			e.time = new Date();
+
+			// Update some value in event
+			switch(e.event)
+			{
+				case "onPropertyChange":
+				{
+					if(e.property === "ancestor")
+					{
+						// convert component IDs to Objects
+						if(e.oldValue !== undefined) e.oldValue = UIComponent.get(e.oldValue);
+						if(e.newValue !== undefined) e.newValue = UIComponent.get(e.newValue);
+						e.handled = true;
+					}
+					break;
+				}
+				case "onComponentEvents":
+				{
+					// update size and location of component locally
+					if(e.type === "resize")
+					{
+						e.target.emit("onRectangleUpdate", {
+							target: e.target,
+							type: e.type,
+							width: e.width,
+							height: e.height
+						});
+						e.handled = true;
+					}
+					else if(e.type === "move")
+					{
+						e.target.emit("onRectangleUpdate", {
+							target: e.target,
+							type: e.type,
+							x: e.x,
+							y: e.y
+						});
+						e.handled = true;
+						if("invoker" in e) e.target.prop.invoker = e.invoker == null ? null : UIComponent.get(e.invoker); // for context menu only
+					}
+					break;
+				}
+				case "onAncestorEvents":
+				{
+					if(e.ancestor !== undefined) e.ancestor = UIComponent.get(e.ancestor);
+					if(e.ancestorParent !== undefined) e.ancestorParent = UIComponent.get(e.ancestorParent);
+
+					if(e.type.startsWith("removed") && e.skipCallback) // this component was removed from it's parent in GUI, such as JInternalFrame when it's closed, and needs to be removed from parent here
+					{
+						return e.target.remove();
+					}
+					e.handled = true;
+					break;
+				}
+				case "onWindowEvents":
+				{
+					if(e.type === "close" && e.destroy) // if Window is closed, destroy it, because it's no longer reusable
+					{
+						queueMicrotask(() =>
+						{
+							e.target.destroy();
+						});
+						if(e.skipCallback) e.handled = true; // we don't continue, because there will be another event with type "closed" emitted.
+					}
+					break;
+				}
+				case "onPopupEvents":
+				{
+					if(e.target instanceof ContextMenu) // for ContextMenu to get invoker component
+					{
+						if("invoker" in e) // set new invoker
+						{
+							e.target.prop.invoker = e.invoker == null ? null : UIComponent.get(e.invoker);
+							delete e.invoker;
+						}
+						if(e.x != null && e.y != null) // set new location of context menu
+						{
+							e.target.prop.location = {x: e.x, y: e.y};
+							delete e.x;
+							delete e.y;
+						}
+					}
+					break;
+				}
+				case "onItemsDropEvents":
+				case "onDropEvents":
+				{
+					if("overComponent" in e) e.overComponent = UIComponent.get(e.overComponent); // convert id to component
+
+					// update data types of dropped data
+					if(typeof e.data === "object")
+					{
+						// find first valid event source component
+						for(let key of Object.keys(e.data))
+						{
+							try
+							{
+								if(key.startsWith("component/"))
+								{
+									let source = UIComponent.get(e.data[key]);
+
+									// verify the type of source component and if drag is enabled
+									if(source && key.endsWith("component/" + source.constructor.name.toLowerCase()) && source.prop.dragAction !== DragDropAction.None)
+									{
+										e.source = source;
+									}
+
+									delete e.data[key]; // remove component ID
+								}
+								else if(key === "URIList" && typeof e.data[key] === "string") // for compatibility
+								{
+									e.data["URIList"] = e.data["URIList"].split("\n");
+								}
+								else if(key === "Files" && typeof e.data[key] === "string") // for compatibility
+								{
+									e.data.Files = e.data.Files.split("\n");
+								}
+								else if(key === "JSON" && typeof e.data[key] === "string") // for compatibility
+								{
+									e.data["JSON"] = JSON.parse(e.data["JSON"]); // parse object's json data
+								}
+							}catch(ex)
+							{
+							}
+						}
+					}
+					break;
+				}
+				case "onShapeEvents":
+				{
+					e.shape = e.target.shape?.(e.shapeIndex);
+					break;
+				}
+			}
+
+			if(Array.isArray(e.target.callback[e.event])) // Catch-All event handler
+			{
+				for(const callback of e.target.callback[e.event])
+				{
+					try
+					{
+						callback.call(e.target, e);
+					}catch(ex)
+					{
+						let comp_name = e.target.constructor.name;
+						e.target = `${comp_name}{...}`; // make it shorter by hiding internals of component
+						if(e.source != null) e.source = `${e.source.constructor.name}{...}`; // make it shorter by hiding internals of component
+						error(`${this._msg[6]}${comp_name}: ${e.event} \n\n${ex.stack}\n\nEvent ${stringify(e)}`, false);
+					}
+				}
+			}
+			else if(typeof e.target.callback[e.event] === "function") // if callback is a function, not array of functions
+			{
+				// call the handler
+				e.target.callback[e.event].call(e.target, e);
+			}
+			else if(e.type !== undefined && typeof e.target.callback[e.type] === "function")
+			{
+				e.target.callback[e.type].call(e.target, e);
+			}
+			else if(!e.handled) // if event was not handled
+			{
+				//if(e.target !== undefined) e.target = (e.target instanceof UIComponent) ? "object of type " + e.target.prop.type : typeof e.target;
+				//alert(this._msg[4] + e.event + "\n\n" + stringify(e));
+			}
+		}catch(ex)
+		{
+			error(`${this._msg[6]}${e.id}: ${e.event} \n\n${ex.stack}\n\nEvent ${stringify(e)}`, false);
+		}
+	}
+
+	/**
+	 * Send a messages to GUI process via STD out. Use internally for communication only.
+	 * @param {Object} msg - JSON Object message to send to GUI.
+	 * @param {function(any):any} [callback] - Only pass callback to block event loop and wait for response
+	 * @return {any|void} Returns response from GUI or undefined.
+	 * @internal
+	 * @ignore
+	 */
+	sendToGUI(msg, callback = null)
+	{
+		// create default callback for "get" messages
+		if(callback === null && msg.get !== undefined)
+		{
+			callback = r =>
+			{
+				return r.value;
+			};
+		}
+
+		// If no callback is needed, then we can stack up messages and send them together
+		if(callback != null)
+		{
+			// Send accumulated messages first
+			this.sendMessageQueue();
+
+			let msgs = JSON.stringify([msg]);
+			this.stats.out += msgs.length;
+
+			let response;
+
+			if(this.#useWorkerThread)
+			{
+				response = this.#sendMessagesViaWorker("b64:" + Buffer.from(msgs, "utf-8").toString("base64"), true);
+			}
+			else
+			{
+				response = this.#jvm.gui.receiveDirectMessagesSync("b64:" + Buffer.from(msgs, "utf-8").toString("base64"));
+				if(response != null) response = this.#textDecoder.decode(this.#decodeBase64(response));
+			}
+
+			if(response != null && typeof response === "string") response = JSON.parse(response);
+
+			if(response != null && "get" in msg)
+			{
+				if(msg.get === response.response && msg.control === response.control) return callback(response);
+				throw new Error("Response doesn't match request message.");
+			}
+
+			return callback(response);
+		}
+		else
+		{
+			this.#_msg_queue.push(structuredClone(msg)); // clone original object to preserve values in case they change before we send the message to GUI
+
+			if(this.#_msg_queue.length >= this.#queue_limit)
+			{
+				this.sendMessageQueue();
+			}
+			else if(this.#_msg_queue.length === 1) // schedule to send messages when event loop gets free
+			{
+				queueMicrotask(() =>
+				{
+					this.sendMessageQueue();
+				});
+			}
+		}
+	}
+
+	/**
+	 * Immediately sends all queued messages to GUI without waiting for queue threshold or execution end. It's similar to flush() function in data streams.
+	 * It can be used to force messages to be sent imedietly instead of waiting for message queue to be full, if it's important to update some UI component or content right away.
+	 * It may improve performance to set `compress` to `false` to skip compression for already compressed data, such as UI component's background image or large icon.
+	 *
+	 * @param {boolean} [compress=true] - Whether to compress messages before sending.
+	 * @return {this} Returns `this` instance for chaining.
+	 * @example <h2>Sending queued messages before proceeding:</h2>
+	 * ui.sendMessageQueue();
+	 *
+	 * @example <h2>Sending queued messages without compressing:</h2>
+	 * ui.sendMessageQueue(false);
+	 */
+	sendMessageQueue(compress = true)
+	{
+		if(this.#_msg_queue.length < 1) return this;
+
+		let msgs = JSON.stringify(this.#_msg_queue);
+
+		// compress messages if more than one message and long enough
+		if(compress && this.#_msg_queue.length > 1 && msgs.length > this.#msgCompressThreshold)
+		{
+			msgs = "gzip64:" + zlib.gzipSync(msgs, {
+				level: zlib.constants.Z_BEST_COMPRESSION,
+				strategy: zlib.constants.Z_DEFAULT_STRATEGY
+			}).toString("base64");
+		}
+		else // convert to base64 to make sure non-ASCII characters are transmitted correctly
+		{
+			msgs = "b64:" + Buffer.from(msgs, "utf-8").toString("base64");
+		}
+
+		this.stats.out += msgs.length;
+		this.#_msg_queue = []; // clear queue
+
+		if(this.#guiManagerWorker != null)
+		{
+			this.#sendMessagesViaWorker(msgs, false);
+		}
+		else if(this.#exiting) // when exiting, don't wait for response
+		{
+			this.#jvm.gui.receiveDirectMessages(msgs);
+		}
+		else
+		{
+			this.#jvm.gui.receiveDirectMessagesSync(msgs);
+		}
+
+		return this;
+	}
+
+	#sendMessagesViaWorker(data, get_response = false)
+	{
+		if(get_response) Atomics.store(this.#sharedBuffSignal, SwingUI.WorkerSignalIndex.ExecutionControl, SwingUI.WorkerSignal.Block);
+
+		this.#guiManagerWorker.postMessage({data: data, respond: get_response});
+
+		if(get_response)
+		{
+			// Block until worker signals
+			Atomics.wait(this.#sharedBuffSignal, SwingUI.WorkerSignalIndex.ExecutionControl, SwingUI.WorkerSignal.Block);
+
+			// Pull the message off the port synchronously
+			return receiveMessageOnPort(this.#worker_port1).message;
+		}
+	}
+
+	//endregion
+
+	//region read-only Getters
+
+	/**
+	 * Returns a detected or specified application root directory.
+	 *
+	 * @readonly
+	 * @type {string}
+	 */
+	get rootDirectory()
+	{
+		if(this.#root_dir !== undefined) return this.#root_dir;
+
+		// detect project directory
+		let dir = process.argv.find(arg => arg.startsWith("--root-dir="));
+
+		if(dir !== undefined)
+		{
+			dir = dir.substring(dir.indexOf("=") + 1).replace(/^"|"$/g, "");
+		}
+		else
+		{
+			dir = this.cwd();
+		}
+
+		while(true)
+		{
+			if(this.fileExists(path.join(dir, "package.json")) || this.fileExists(path.join(dir, "node_modules")) || this.fileExists(path.join(dir, "deno.json")))
+			{
+				this.#root_dir = dir;
+				return dir;
+			}
+			// go up one level
+			const parent = path.dirname(dir);
+			if(parent === dir) throw new Error(`${this._msg[8]} ${this.cwd()}`);
+			dir = parent;
+		}
+	}
+
+	/**
+	 * Gets the JavaScript runtime name ("node", "bun", "deno", or "unknown"). Useful when building an application compatible with multiple JavaScript runtimes.
+	 * @type {string}
+	 * @readonly
+	 * @example <h2>Getting current JavaScript runtime:</h2>
+	 * console.log(ui.runtime);
+	 * // prints "node", or what ever your runtime is.
+	 */
+	get runtime()
+	{
+		return this.#js_runtime;
+	}
+
+	/**
+	 * Returns a short identifier of an operating system on current machine. Possible values: "windows", "linux", "darwin" (for MacOS), "freebsd", "openbsd", "sunos", and "android".
+	 * @type {string}
+	 * @readonly
+	 * @example <h2>Getting a short identifier of an operating system:</h2>
+	 * console.log(ui.os); // e.g., prints "windows"
+	 */
+	get os()
+	{
+		let os = "";
+
+		if(this.runtime === "deno")
+		{
+			os = Deno.build.os;
+		}
+		else
+		{
+			os = process.platform;
+		}
+
+		if(os === "win32") os = "windows";
+
+		return os;
+	}
+
+	/**
+	 * Getter property that returns an array of available UI look and feel IDs on your system. For example Windows OS can have a Windows look and feel that linux doesn't have. Use them to set the desired look and feel using ui.ui(id) method.
+	 *
+	 * @readonly
+	 * @see {@link SwingUI#ui|ui.ui(id)}
+	 * @type {string[]}
+	 */
+	get list()
+	{
+		return /** @type {string[]} */ this.sendToGUI({java: "list"}, r =>
+		{
+			return r.list;
+		});
+	}
+
+	/**
+	 * Returns an array of screen objects [{x,y,width,height}] that are configured on this computer. X and Y is the position of screens relative to one virtual screen. It's useful when you have multiple screens.
+	 *
+	 * @readonly
+	 * @type {Object[]}
+	 * @example <h2>Getting a list of screens:</h2>
+	 * console.debug(ui.screens);
+	 *
+	 * // Example of returned array:
+	 * [
+	 *   {
+	 *     default: true,
+	 *     id: '\\Display0',
+	 *     description: 'Win32GraphicsDevice[screen=0]',
+	 *     x: 0,
+	 *     y: 0,
+	 *     width: 2560,
+	 *     height: 1080,
+	 *     refresh_rate: 59,
+	 *     bit_depth: 32,
+	 *     type: 'screen'
+	 *   },
+	 *   {
+	 *     default: false,
+	 *     id: '\\Display1',
+	 *     description: 'Win32GraphicsDevice[screen=1]',
+	 *     x: -1280,
+	 *     y: 255,
+	 *     width: 1280,
+	 *     height: 1024,
+	 *     refresh_rate: 60,
+	 *     bit_depth: 32,
+	 *     type: 'screen'
+	 *   }
+	 * ]
+	 */
+	get screens()
+	{
+		return /** @type {Object[]} */ this.sendToGUI({system: "screens"}, r =>
+		{
+			return r.list;
+		});
+	}
+
+	/**
+	 * Checks if current operating system supports system tray icons.
+	 *
+	 * @readonly
+	 * @type {boolean}
+	 */
+	get systemTraySupported()
+	{
+		return /** @type {boolean} */ this.sendToGUI({system: "systemTraySupported"}, r =>
+		{
+			return r.value;
+		});
+	}
+
+	/**
+	 * Gets a GUI software license information stored in the package.json file of your project.
+	 *
+	 * @readonly
+	 * @type {Object}
+	 */
+	get license()
+	{
+		return /** @type {Object} */ this.sendToGUI({system: "getLicense"}, r =>
+		{
+			return r.value;
+		});
+	}
+
+	/**
+	 * Gets and returns a swing-ui module version from package.json file.
+	 *
+	 * @readonly
+	 * @type {string}
+	 */
+	get version()
+	{
+		try
+		{
+			return JSON.parse(this.readFile(`${this.#module_dir}/package.json`, "string", "utf8")).version;
+		}catch(ex)
+		{
+			return "<unknown>";
+		}
+	}
+
+	/**
+	 * Returns details of memory usage by GUI process.
+	 *
+	 * @readonly
+	 * @type {Object}
+	 * @example <h2>Getting RAM details about the GUI process:</h2>
+	 * console.log(ui.memoryUsage);
+	 *
+	 * // Example output
+	 * {
+	 *   total: 268435456,
+	 *   max: 4263510016,
+	 *   max_heap: 4263510016,
+	 *   used: 23540264,
+	 *   non_heap: 39226904,
+	 *   free: 244895192,
+	 *   heap: 21443112
+	 * }
+	 */
+	get memoryUsage()
+	{
+		return this.sendToGUI({java: "ram"}, r =>
+		{
+			return r.value;
+		});
+	}
+
+	/**
+	 * Returns an array of fonts installed on the system.
+	 *
+	 * @readonly
+	 * @type {string[]}
+	 * @example <h2>Getting a list of fonts installed on the system:</h2>
+	 * console.log(ui.fonts);
+	 *
+	 * // example output:
+	 * [
+	 *   'Adobe Arabic',
+	 *   'Adobe Caslon Pro',
+	 *   'Adobe Caslon Pro Bold',
+	 *   ...
+	 * ]
+	 */
+	get fonts()
+	{
+		return /** @type {string[]} */ this.sendToGUI({system: "fonts"}, r =>
+		{
+			return r.value;
+		});
+	}
+
+	/**
+	 * A getter to get environment variables.
+	 *
+	 * @readonly
+	 * @type {object}
+	 */
+	get env()
+	{
+		return this.runtime === "deno" ? Deno.env.toObject() : process.env;
+	}
+
+	/**
+	 * Gets a current process ID
+	 *
+	 * @readonly
+	 * @type {number}
+	 */
+	get pid()
+	{
+		return this.runtime === "deno" ? Deno.pid : process.pid;
+	}
+
+	//endregion
+
+	//region GUI
+
+	/**
+	 * Performs garbage collection in JavaScript and GUI.
+	 * @return {SwingUI} Returns an instance of SwingUI object for method chaining.
+	 * @example <h2>Usage example:</h2>
+	 * ui.gc();
+	 */
+	gc()
+	{
+		if(global.gc) global.gc(); // Trigger garbage collection (requires Node.js started with --expose-gc)
+		this.sendToGUI({java: "gc"}); // Trigger garbage collection in GUI
+		return this;
+	}
+
+	/**
+	 * Increases and decreases default font size of all UI components.
+	 *
+	 * @param {number} by - By how many pixels to adjust font size (positive integer increases size, negative decreases)
+	 * @return {this} Returns an instance of SwingUI object for method chaining.
+	 */
+	adjustFontSize(by)
+	{
+		this.sendToGUI({java: "adjustFontSize", value: parseInt(by)});
+		return this;
+	}
+
+	/**
+	 * Increases and decreases default font size of all controls.
+	 *
+	 * @param {number} by - By how much to adjust font size (positive increases size, negative decreases)
+	 * @return {this} Returns an instance of SwingUI object for method chaining.
+	 */
+	adjustDefaultFontSize(by)
+	{
+		this.sendToGUI({java: "adjustDefaultFontSize", value: parseInt(by)});
+		return this;
+	}
+
+	/**
+	 * Sets default font to be used by all components. Any font property may be changed (name, size, bold, etc.)
+	 *
+	 * @param {Font} font - New font
+	 * @returns {this} Returns an instance of SwingUI object for method chaining.
+	 */
+	setDefaultFont(font)
+	{
+		if(typeof font !== "object") throw Error("Font argument must be an object of Font type");
+		this.sendToGUI({java: "defaultFont", value: font});
+		return this;
+	}
+
+	/**
+	 * Sets or reads clipboard content data. Data types must be values of object (enum) DataType.
+	 *
+	 * @param {object} [data] - Object ob data to be stored in a clipboard {Type: data}. See example below.
+	 * @returns {object|SwingUI} When setting arguments, `this` instance of SwingUI is returned, otherwise clipboard data object is returned.
+	 * @see DataType
+	 * @example <h2>Valid data types for the clipboard data object:</h2>
+	 * // Sets all possible data types to clipboard
+	 * ui.clipboard({
+	 *     Text: "text to copy",
+	 *     HTML: "<b>HTML Content</b>",
+	 *     JSON: object,
+	 *     Image: "base64 encoded image data",
+	 *     URIList: ["http://url_1.com", "http://url_2.com"],
+	 *     Files: ["C://my_file.txt", ...],
+	 *     URL: "http://url.com"
+	 * });
+	 * @example <h2>Setting some plain text and HTML data to clipboard:</h2>
+	 * const data = {};
+	 * data[DataType.Text] = "Plain text content";
+	 * data[DataType.HTML] = "<b>HTML Content</b>";
+	 * ui.clipboard(data);
+	 */
+	clipboard()
+	{
+		if(arguments.length > 0)
+		{
+			this.sendToGUI({
+				system: "clipboard",
+				value: (typeof arguments[0] === "string") ? {Text: arguments[0]} : arguments[0]
+			});
+			return this;
+		}
+		else
+		{
+			return this.sendToGUI({system: "clipboard"}, r =>
+			{
+				return r.value;
+			});
+		}
+	}
+
+	/**
+	 *  Sets or gets boolean whether the layout of containers is validated during resizing, or after resizing is complete.
+	 *
+	 * @param {boolean} [value] - Enables or disables dynamic layout
+	 * @return {boolean|SwingUI} When setting arguments, `this` instance of SwingUI is returned, otherwise current value is returned.
+	 */
+	dynamicLayout(...args)
+	{
+		if(args.length > 0)
+		{
+			this.sendToGUI({java: "dynamicLayout", value: (args[0] === true)});
+			return this;
+		}
+		else
+		{
+			return this.sendToGUI({java: "dynamicLayout"}, r =>
+			{
+				return r.value;
+			});
+		}
+	}
+
+	/**
+	 * Gets or sets Java's GUI look and feel ID. Obtain a list of supported UIs by the system using ui.list getter property.
+	 *
+	 * @param {string} [id] - Identifies of Java Swing's UI to be used.
+	 * @param {object} [options] - Additional look-and-feel options. Options apply only to some look-and-feels, like FlatLaf. Example: {border-radius: 5}.
+	 * @return {string|SwingUI} When setting arguments, `this` instance of SwingUI is returned, otherwise current value is returned.
+	 * @throws Error When argument is invalid.
+	 * @see SwingUI#list
+	 * @example <h2>Setting FlatDarkLaf UI with all options</h2>
+	 * ui.ui(
+	 *   "FlatDarkLaf",
+	 *   {
+	 *     borderRadius:8,
+	 *     showScrollbarButtons: true,
+	 *     scrollbarSize: 14,
+	 *     selectedTabColor: "#FFFFFF",
+	 *     scrollbarColor: "#FF7777",
+	 *     arrowType: "triangle" // "triangle" or "chevron" (default)
+	 *   }
+	 * );
+	 */
+	ui(...args)
+	{
+		if(args.length > 0)
+		{
+			const e = this.sendToGUI({
+				java: "ui",
+				value: {id: args[0], options: args[1] ?? undefined}
+			}, r => {return r.value;});
+			if(e === false) throw new Error(`Failed to set UI '${args[0]}'.`);
+			queueMicrotask(() => {this.#processEvent(e);});
+			return this;
+		}
+		else
+		{
+			return /** @type {string} */ this.sendToGUI({java: "ui"}, r =>
+			{
+				return r.value;
+			});
+		}
+	}
+
+	/**
+	 * Shows a message dialog window like alert() in web browser.
+	 *
+	 * @param {string} message
+	 * @param {string} [title] - Message window title
+	 * @param {MessageIcon} [icon] - Use: MessageIcon.[Info|Warning|Error]
+	 * @param {Window} [ownerWindow] - If set, the message dialog window will attempts to be centered at specified window
+	 * @return {void} Does not return a value.
+	 */
+	showMessage(message, title = "Message", icon = MessageIcon.Info, ownerWindow = null)
+	{
+		if(typeof message !== "string") message = stringify(message);
+		ownerWindow = (ownerWindow instanceof globalThis.Window) ? ownerWindow.id : null;
+		this.sendToGUI({
+			java: "showMessage",
+			message: message,
+			title: String(title),
+			icon: parseInt(icon),
+			owner: ownerWindow
+		}, function(r)
+		{
+			return r.value;
+		});
+	}
+
+	/**
+	 * Sets a custom Error handler when error events come if from GUI. Event object has a "e.message" parameter, and
+	 * may have "e.target" that references a component related to the error.
+	 * e:{
+	 *     message (always)
+	 *     target: (when component is related to the error)
+	 * }
+	 * @param {function(Object):any} callback - Function to be called instead of default error handling.
+	 * @return {SwingUI} Returns `this` instance of SwingUI class.
+	 */
+	onError(callback)
+	{
+		this.callback.onError = callback;
+		return this;
+	}
+
+	/**
+	 * Gets or sets text rendering mode used in UI components.
+	 *
+	 * @param {string} [mode] - Specifies font antialiasing mode to use (on|lcd|gasp|off) (NOT IMPLEMENTED YET).
+	 * @returns {string|null} Returns font antialiasing mode: `on`, `lcd`, `gasp`, `off`, or `null` object if font antialiasing could not be detected.
+	 */
+	fontAntialiasing(...args)
+	{
+		if(args.length > 0)
+		{
+			throw new Error(`Settings text rendering mode is not implemented yet.`);
+		}
+		else
+		{
+			return this.sendToGUI({system: "fontAntialiasing"}, r => {return r.value;});
+		}
+	}
+
+	/**
+	 *  Gets or sets the event throttle interval for high-frequency events, like mouse motion or resizing. Value is in milliseconds, so 100 means no more than 10 same type of events per component per second.
+	 *  Applies only to some high frequency events, such as resizing and moving.
+	 *
+	 * @param {number} [ms] - Minimum amount of time (in milliseconds) between same type of events per component.
+	 * @return {SwingUI|number} When setting arguments, `this` instance of SwingUI is returned, otherwise current value is returned.
+	 * @example <h2>Setting and getting examples:</h2>
+	 * ui.eventThrottle(10); // Sets new value
+	 * console.debug(ui.eventThrottle()); // prints current value
+	 */
+	eventThrottle(...args)
+	{
+		if(args.length > 0)
+		{
+			this.sendToGUI({java: "eventThrottle", value: parseInt(args[0])});
+			return this;
+		}
+		else
+		{
+			return /** @type {number} */ this.sendToGUI({java: "eventThrottle"}, r =>
+			{
+				return r.value;
+			});
+		}
+	}
+
+	/**
+	 * Adjusts or retrieves the thread pool size and keep-alive time for image loading tasks.
+	 * Each argument is optional. Setting `null` to any argument will not change it's value.
+	 * Returns current configuration if no arguments are specified.
+	 *
+	 * @param {number} [min] - The minimum number of threads to keep alive (core pool size). Default is 1.
+	 * @param {number} [max] - The maximum number of threads allowed (max pool size). Default is 5.
+	 * @param {number} [keep_alive] - The idle time (in seconds) before excess threads are terminated when idle. Default is 5 seconds.
+	 * @return {object|SwingUI}  When setting arguments, `this` instance of SwingUI is returned, otherwise current value is returned.
+	 */
+	iconLoadingThreads(...args)
+	{
+		if(args.length === 0)
+		{
+			return this.sendToGUI({java: "iconLoadingThreads"}, r =>
+			{
+				return r.value;
+			});
+		}
+		else
+		{
+			const opt = {min: parseInt(args[0])};
+			if(args.length > 1) opt.max = parseInt(args[1]);
+			if(args.length > 2) opt.keep_alive = parseInt(args[2]);
+
+			this.sendToGUI({java: "iconLoadingThreads", ...opt});
+			return this;
+		}
+	}
+
+	/**
+	 * Requests operating system to move top-most window of this application (or all windows) to foreground before other windows. Operating may refuse to do it.
+	 * To forcefully bring a specific Window to the front you can set window.alwaysOnTop(true), and then window.alwaysOnTop(false), but it should not be abused in order to maintain a positive user experience.
+	 *
+	 * @param {boolean} [all_windows=false] - Move all windows of this application to foreground instead of just top-most window.
+	 * @returns {SwingUI} returns `this` ui object for chaining.
+	 */
+	requestForeground(all_windows = false)
+	{
+		this.sendToGUI({system: "requestForeground", value: all_windows === true});
+		return this;
+	}
+
+	/**
+	 * Sets or gets a default menu bar that should be used by macOS at the top of the screen. If the specified menu bar was added to any parent component, it will be removed from that component.
+	 * This is supported only on macOS.
+	 *
+	 * @param {MenuBar|null} [menu_bar] - MenuBar component. Set to `null` to remove default menu bar.
+	 * @return {MenuBar|boolean} If called without parameters, a default `Menubar` component is returned or `null` of it was never set; otherwise `boolean` is returned indicating if the operation was accepted by the operating system.
+	 * @throws {Error} When passed argument is not a {@link MenuBar} object.
+	 */
+	defaultMenuBar(...args)
+	{
+		if(args[0] != null && !(args[0] instanceof MenuBar)) throw new Error(`Invalid argument in ui.defaultMenuBar(menu_bar). Expected 'MenuBar' object, but received ${typeof args[0]}.`);
+
+		if(args.length > 0)
+		{
+			if(args[0] != null) args[0].remove(); // remove from previous parents (or else GUI will anyway).
+
+			return this.sendToGUI({
+				system: "defaultMenuBar",
+				value: args[0] instanceof MenuBar ? args[0].id : null
+			}, r =>
+			{
+				return r.value;
+			});
+		}
+		else
+		{
+			return this.sendToGUI({system: "defaultMenuBar"}, r =>
+			{
+				return r.value;
+			});
+		}
+	}
+
+	/**
+	 * Gracefully exits the application with specified exit code (status code) and optional exit signal. Emits onExit() event handlers, closes connection to GUI and notifies GUI to gracefully exit. This is a recommended way to exit the application.
+	 *
+	 * @param {number} [exitCode] - Exit code.
+	 * @param {string} [signal] - One of received exit signals: `SIGINT`, `SIGUSR1`, `SIGUSR2`, `SIGTERM`, `SIGHUP`.
+	 * @return {void} Does not return a value.
+	 * @example <h2>Exiting the app gracefully:</h2>
+	 * ui.exit();
+	 * ui.exit(10); // existing with exit code 10
+	 * @see SwingUI#onExit
+	 */
+	exit(exitCode = 0, signal = undefined)
+	{
+		if(this.#exiting) return;
+		this.#exiting = true;
+
+		// emit the event
+		const e = {event: "onExit", type: "exit", id: 0, code: exitCode};
+		if(signal !== undefined) e.signal = signal;
+		this.#processEvent(e);
+
+		this.#exitJava(exitCode);
+		clearInterval(this.#watchdog_timer);
+
+		setTimeout(() =>
+		{
+			if(ui.runtime === "deno")
+			{
+				Deno.exit(exitCode);
+			}
+			else
+			{
+				process.exit(exitCode);
+			}
+		}, 100); // Giving some time for Java to receive the signal and process cleaning
+	}
+
+	#exitJava(exitCode = 0)
+	{
+		this.sendToGUI({java: "exit", code: exitCode});
+
+		try
+		{
+			//this.#jvm.eventListener.reset();
+		}catch(_)
+		{
+		}
+		try
+		{
+			this.#jvm.stdio.guard.release();
+		}catch(_)
+		{
+		}
+
+		setTimeout(() =>
+		{
+			if(this.#guiManagerWorker != null)
+			{
+				this.#guiManagerWorker.postMessage({
+					type: "__shutdown",
+					code: exitCode
+				});
+			}
+
+		}, 10);
+	}
+
+	//endregion
+
+	//region Utility Functions
+
+	/**
+	 * Sets and gets locking keys state (Caps lock key, Num lock key, and Scroll lock key) to ON and OFF.
+	 *
+	 * @param {Object} [keys] - Keys object example {caps_lock: false, num_lock: true, scroll_lock: false}. Only set keys you want to change.
+	 * @return {Object|SwingUI} When setting arguments, `this` instance of SwingUI is returned, otherwise current value is returned.
+	 * @example <h2>Setting Caps Lock to ON</h2>
+	 * ui.lockingKeys({caps_lock: true});
+	 */
+	lockingKeys()
+	{
+		if(arguments.length > 0)
+		{
+			this.sendToGUI({system: "lockingKeys", value: arguments[0]});
+			return this;
+		}
+		else
+		{
+			return this.sendToGUI({system: "lockingKeys"}, r =>
+			{
+				return r.value;
+			});
+		}
+	}
+
+	/**
+	 * Gets or sets a position of a pointing device. If "screen" is specified,
+	 * the {x,y} position will be relative to the specified screen, otherwise
+	 * the position will be set relative to screen at index 0 (default screen).
+	 * You can get a list of screens with ui.screens getter.
+	 *
+	 * @param {number} [x] - Use only to set pointer location
+	 * @param {number} [y] - required if x is specified
+	 * @param {number} [screen]
+	 * @return {Object | SwingUI} When setting arguments, `this` instance of SwingUI is returned, otherwise current value is returned.
+	 */
+	mouseLocation()
+	{
+		if(arguments.length > 1)
+		{
+			this.sendToGUI({
+				system: "mouseLocation",
+				value: {
+					x: parseInt(arguments[0]),
+					y: parseInt(arguments[1]),
+					screen: arguments.length > 2 ? Math.abs(parseInt(arguments[2])) : undefined // don't set default screen index here, it may not be 0
+				}
+			});
+			this.sendMessageQueue(); // important, helps for mouse event to be detected
+			return this;
+		}
+		else
+		{
+			return this.sendToGUI({system: "mouseLocation"}, r =>
+			{
+				return r.value;
+			});
+		}
+	}
+
+	/**
+	 * Performs mouse button action or mouse wheel scrolling action.
+	 *
+	 * @param {MouseAction} action - MouseAction.[Press, Release, Click, DoubleClick, VerticalScroll, HorizontalScroll]
+	 * @param {MouseButton|number} button_or_scrolls - MouseButton.[Left, Right, Middle] OR integer for scroll amount if action is MouseAction.VerticalScroll or MouseAction.HorizontalScroll
+	 * @return {SwingUI} Returns `this` instance of SwingUI class.
+	 * @see MouseAction
+	 */
+	mouseAction(action, button_or_scrolls)
+	{
+		let data = {action: parseInt(action)};
+
+		if(data.action === MouseAction.VerticalScroll || data.action === MouseAction.HorizontalScroll)
+		{
+			data.scroll = button_or_scrolls;
+		}
+		else
+		{
+			data.button = button_or_scrolls;
+		}
+
+		this.sendToGUI({system: "mouseAction", value: data});
+		return this;
+	}
+
+	/**
+	 * Performs a key press, key release, or key type operation. For value use one character string when using "Press" or "Release" action, or a string of text to be typed when using "Type" action.
+	 *
+	 * @param {KeyAction} action - KeyAction.[Press|Release|Type]
+	 * @param {number|number[]|string} key_code_or_string - Key code, array of key codes, or a string, which will be converted to an array of key codes.
+	 * @return {SwingUI} Returns `this` instance of SwingUI class.
+	 * @see KeyAction
+	 * @example <h2>Performing a key type action:</h2>
+	 * ui.keyboardAction(KeyAction.Type, "A");
+	 */
+	keyboardAction(action, key_code_or_string)
+	{
+		if(arguments.length < 2) return this;
+
+		let data = {action: action};
+
+		if(typeof key_code_or_string === "number")
+		{
+			data.keyCodes = [key_code_or_string];
+		}
+		else if(Array.isArray(key_code_or_string))
+		{
+			data.keyCodes = key_code_or_string;
+		}
+		else if(typeof key_code_or_string === "string")
+		{
+			data.text = key_code_or_string;
+		}
+
+		this.sendToGUI({system: "keyboardAction", value: data});
+		return this;
+	}
+
+	/**
+	 * Returns the index of the screen whose bounds contain the given coordinate, or -1 if the point does not fall within any configured screen.
+	 *
+	 * Accepts either:
+	 * - Separate numeric coordinates (x, y), or
+	 * - A point-like object with numeric `x` and `y` properties.
+	 *
+	 * @param {number|Object} xOrPoint - Either the X coordinate or a point object containing {x, y}.
+	 * @param {number} [y] - The Y coordinate (required if xOrPoint is a number).
+	 * @returns {number} The index of the matching screen, or -1 if none matched.
+	 * @throws {Error} If the input is invalid (object is missing `x` or `y` properties) or coordinates are not finite numbers.
+	 *
+	 * @example <h2>Using separate x and y coordinates</h2>
+	 * const screenIndex = ui.screenIndexAt(1920, 540);
+	 * console.log(screenIndex); // e.g. 1, or -1 if not within any screen
+	 *
+	 * @example <h2>Using a point object</h2>
+	 * const cursor = { x: 3440, y: 1080 };
+	 * const screenIndex = ui.screenIndexAt(cursor);
+	 * console.log(screenIndex); // e.g. 2, or -1 if not within any screen
+	 */
+	screenIndexAt(xOrPoint, y = undefined)
+	{
+		let px, py;
+
+		if(typeof xOrPoint === 'object')
+		{
+			if(xOrPoint == null || !("x" in xOrPoint) || !("y" in xOrPoint)) throw new Error(`Invalid point object. Point object must be an object with "x" and "y" integer properties.`);
+			px = xOrPoint.x;
+			py = xOrPoint.y;
+		}
+		else
+		{
+			px = xOrPoint;
+			py = y;
+		}
+
+		if(!Number.isFinite(px) || !Number.isFinite(py)) throw new Error(`Invalid x or y arguments.`);
+
+		return this.screens.findIndex(s => px >= s.x && px < s.x + s.width && py >= s.y && py < s.y + s.height);
+	}
+
+	/**
+	 * Opens provided URL in a default web browser.
+	 *
+	 * @param {string} url - Website address to open.
+	 * @return {this} Returns `this` instance of SwingUI class.
+	 */
+	openURL(url)
+	{
+		this.sendToGUI({system: "openURL", value: url});
+		return this;
+	}
+
+	/**
+	 * Opens file or a folder with a default application associated the file type, or inside a file manager application (is specified).
+	 *
+	 * @param {string} path - Absolute path of a local file or directory.
+	 * @param {boolean} [in_file_manager=false] - Indicates if the file should be open inside a default file manager application instead of a default application associated with that file type.
+	 * @return {boolean} Returns `true` if the path exists and this operation is supported by the operating system; otherwise returns `false`.
+	 */
+	openPath(path, in_file_manager = false)
+	{
+		return this.sendToGUI({system: "openPath", value: {path: path, in_folder: in_file_manager}}, r =>
+		{
+			return r.value;
+		});
+	}
+
+	/**
+	 * Tells operating system to print a file using default file printing dialog window.
+	 *
+	 * @param {String} path - Absolute path of a local file to print.
+	 * @return {boolean} Returns `true` if the file exists and this operation is supported by the operating system; otherwise returns `false`.
+	 */
+	printFile(path)
+	{
+		return this.sendToGUI({system: "print", value: path}, r =>
+		{
+			return r.value;
+		});
+	}
+
+	/**
+	 * Opens the default mail client’s compose window with fields pre-filled according to a `mailto:` URI.
+	 * The `mailto:` URI can include message fields such as `to`, `cc`, `subject`, `body`, etc.
+	 * For details, see [RFC 2368](https://www.rfc-editor.org/rfc/rfc2368) (The mailto URL scheme).
+	 * In some cases an error message may provide details as to why starting the application failed.
+	 *
+	 * @param {string} [mailto_uri=""] - A `mailto:` URI. Leave empty to simply open the compose window without any fields filled in.
+	 * @returns {boolean} Returns `true` if this action is supported by the operating system and the default mail application compose window starts successfully; otherwise returns `false`.
+	 */
+	mail(mailto_uri = "")
+	{
+		return this.sendToGUI({system: "mail", value: mailto_uri}, r =>
+		{
+			return r.value;
+		});
+	}
+
+	/**
+	 * Synchronously pauses main thread code execution for a specified amount of milliseconds.
+	 *
+	 * @param {number} ms - Amount of milliseconds to sleep.
+	 * @returns {boolean} Returns `true` when code execution resumed because of specified timeout, `false` for any other reason.
+	 */
+	sleep(ms)
+	{
+		return (Atomics.wait(this.#sleepBuffer, 0, 0, ms) === "timed-out");
+	}
+
+	//endregion
+
+	//region File System Methods
+
+	/**
+	 * Synchronously checks if the file or directory exist.
+	 *
+	 * @param {string|URL} file_path - File or directory path to check
+	 * @returns {boolean} Returns `true` if the file or directory exist; otherwise returns `false`.
+	 * @throws {Error} When the file path is invalid.
+	 */
+	fileExists(file_path)
+	{
+		if(!(typeof file_path === "string")) throw new Error(`Invalid "file_path" argument: ${typeof file_path}`);
+
+		try
+		{
+			return (this.runtime === "deno") ? (Deno.statSync(file_path) != null) : fs.existsSync(file_path);
+		}catch(ex)
+		{
+			if(ex instanceof Deno.errors.NotFound) return false;
+			throw ex;
+		}
+	}
+
+	/**
+	 * Synchronously reads a local file and returns its data.
+	 * NOTE: Memory limit set by JavaScript runtime and operating system limits the file size that can be read.
+	 *
+	 * @param {string} file_path
+	 * @param {string} [data_type="string"] - Desired return data type: `string`, `Uint8Array`, `ArrayBuffer`, `Buffer`. NOTE: `Buffer` may not be supported in all JavaScript runtimes and exception may occur.
+	 * @param {string} [encoding="utf-8"] - Text encoding to use. Only applies when `data_type` argument is "string".
+	 * @returns {string|Uint8Array|ArrayBuffer|Buffer} Returns the data in specified data type.
+	 * @throws {Error} When the file path is invalid.
+	 * @throws {Error} When file doesn't exist.
+	 * @throws {Error} When file cannot be read.
+	 * @throws {Error} When `data_type` parameter is invalid.
+	 */
+	readFile(file_path, data_type = "string", encoding = "utf-8")
+	{
+		if(!(typeof file_path === "string")) throw new Error(`Invalid "file_path" argument: ${typeof file_path}`);
+
+		if(!this.fileExists(file_path)) throw new Error(`File not found: ${file_path}`);
+
+		if(!this.canReadFile(file_path)) throw new Error(`Failed to read file: Access Denied`);
+
+		let data = null; // originally should start with Uint8Array
+
+		try
+		{
+			if(this.runtime === "deno" && Deno.readFileSync)
+			{
+				data = Deno.readFileSync(file_path);
+			}
+			else
+			{
+				data = fs.readFileSync(file_path);
+			}
+		}catch(ex)
+		{
+			throw new Error(`Failed to read file: ${ex.message}`);
+		}
+
+		switch(data_type)
+		{
+			case "string":
+			{
+				return new TextDecoder(encoding).decode(data);
+			}
+			case "Uint8Array":
+			{
+				return (Buffer !== undefined && data instanceof Buffer) ? new Uint8Array(data) : data;
+			}
+			case "ArrayBuffer":
+			{
+				return (Buffer !== undefined && data instanceof Buffer) ? data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) : data.buffer;
+			}
+			case "Buffer":
+			{
+				return Buffer.from(data);
+			}
+			default:
+			{
+				throw new Error(`Invalid "format" argument specified: ${data_type}. Expected "string", "Uint8Array", "ArrayBuffer", or "Buffer".`);
+			}
+		}
+	}
+
+	/**
+	 * Writes data to a file synchronously.
+	 *
+	 * @param {string|URL} file_path - Local destination file path.
+	 * @param {string|ArrayBuffer|Uint8Array|Buffer} data - Data to write to a file.
+	 * @param {string} [mode="write"] - "write" or "append"
+	 * @param {boolean} [overwrite=true] - `true` to overwrite existing file with the same path. `false` to fail and return `false` if a file with the same path already exists.
+	 * @param {boolean} [create_dir=false] - `true` to create directory if it doesn't exist. `false` is default. If `false` and directory doesn't exist, an Errow will be thrown.
+	 * @returns {boolean} Returns `true` on success, or throws an Error on failure.
+	 * @throws {Error} When the file path is invalid.
+	 * @throws {Error} When the file exists and `overwrite` argument is not `true`.
+	 * @throws {Error} When access to the file is denied.
+	 * @throws {Error} When directory to the specified file failed to be automatically created.
+	 * @throws {Error} When the directory of the file path doesn't exist and `create_dir` argument is not true.
+	 * @throws {Error} When failed to write the file.
+	 */
+	writeFile(file_path, data, mode = "write", overwrite = true, create_dir = false)
+	{
+		// validate path type
+		if(!(typeof file_path === "string")) throw new Error(`Invalid "file_path" argument: ${typeof file_path}`);
+
+		// validate data type
+		if(!(typeof data === "string") && !(data instanceof ArrayBuffer) && !(data instanceof Uint8Array) && !(Buffer !== undefined && data instanceof Buffer)) throw new Error(`Invalid "data" argument type: ${typeof file_path}. Expected string, ArrayBuffer, Buffer or Uint8Array.`);
+
+		if(overwrite !== true && this.fileExists(file_path)) throw new Error(`File already exists. To overwrite the file set "overwrite" argument to true.`);
+
+		if(mode === "append" && this.fileExists(file_path) && !this.canWriteFile(file_path)) throw new Error(`Failed to write file: Access Denied`);
+
+		if(typeof data === "string") data = new TextEncoder().encode(data); // convert string to Uint8Array
+
+		try
+		{
+			if(!ui.fileExists(path.dirname(file_path)))
+			{
+				if(create_dir)
+				{
+					try
+					{
+						ui.makeDirectory(path.dirname(file_path), true);
+					}catch(ex)
+					{
+						throw new Error(`Failed to create a directory that doesn't exist: ${path.dirname(file_path)}:\n${ex.message}`);
+					}
+				}
+				else
+				{
+					throw new Error(`Directory doesn't exist: ${path.dirname(file_path)}`);
+				}
+			}
+
+			if(this.runtime === "deno")
+			{
+				Deno.writeFileSync(file_path, (data instanceof Uint8Array) ? data : new Uint8Array(data), {append: mode === "append"});
+			}
+			else
+			{
+				const flag = mode === "append" ? "a" : "w";
+				fs.writeFileSync(file_path, (data instanceof ArrayBuffer) ? Buffer.from(data) : data, {flag: flag});
+			}
+
+			return true;
+		}catch(err)
+		{
+			throw new Error(`Failed to write file ${file_path}: \n\nError: ${err.message}`);
+		}
+	}
+
+	/**
+	 * Gets information about a file or directory, like times, size, if it's a file or directory, etc.
+	 *
+	 * @param {string|URL} file_path - Local file or directory path.
+	 * @param {boolean} [about_link=false] - `true` makes the method return information about the symbolic link itself instead of the path the link redirects to. Only applies to symbolic links.
+	 * @returns {FileStat} Returns information about specified file or directory, or throws an Error if it doesn't exist, access is denied, or argument is invalid.
+	 * @throws {Error} When the file path is invalid.
+	 * @throws {Error} When the file is not found.
+	 * @see FileStat
+	 */
+	fileStat(file_path, about_link = false)
+	{
+		if(!(typeof file_path === "string")) throw new Error(`Invalid "file_path" argument: ${typeof file_path}`);
+		if(!this.fileExists(file_path)) throw new Error(`File not found: ${file_path}`);
+
+		let stat = null;
+
+		if(about_link)
+		{
+			stat = (this.runtime === "deno") ? Deno.lstatSync(file_path) : fs.lstatSync(file_path);
+		}
+		else
+		{
+			stat = (this.runtime === "deno") ? Deno.statSync(file_path) : fs.statSync(file_path);
+		}
+
+		return {
+			isFile: (typeof stat.isFile === "function") ? stat.isFile() : stat.isFile,
+			isDirectory: (typeof stat.isDirectory === "function") ? stat.isDirectory() : stat.isDirectory,
+			isSymlink: (typeof stat.isSymbolicLink === "function") ? stat.isSymbolicLink() : stat.isSymlink,
+			dev: stat.dev,
+			rdev: stat.rdev,
+			nlink: stat.nlink,
+			user: stat.uid,
+			group: stat.gid,
+			size: stat.size,
+			mode: stat.mode,
+			atime: stat.atime,
+			mtime: stat.mtime,
+			ctime: stat.ctime,
+			birthtime: stat.birthtime
+		};
+	}
+
+	/**
+	 * Deletes a file or moves it to trash synchronously.
+	 *
+	 * @param {string} file_path - Path to the file to delete
+	 * @param {boolean} [move_to_trash=false] - Move file to trash instead of completely deleting it.
+	 * @returns {boolean} - Returns `true` on success or if the file didn't exist; otherwise returns `false` on failure
+	 * @throws {Error} When the file path is invalid.
+	 * @throws {Error} When the file path is a directory.
+	 */
+	deleteFile(file_path, move_to_trash = false)
+	{
+		if(!(typeof file_path === "string")) throw new Error(`Invalid "file_path" argument: ${typeof file_path}`);
+		if(!this.fileExists(file_path)) return true;
+		if(!this.fileStat(file_path).isFile) throw new Error(`Failed to delete file: Provided path is a directory. Use ui.deleteDirectory() instead.`);
+
+		if(move_to_trash)
+		{
+			return this.sendToGUI({system: "moveToTrash", value: file_path}, r =>
+			{
+				return r.value;
+			});
+		}
+
+		try
+		{
+			if(this.runtime === "deno")
+			{
+				Deno.removeSync(file_path);
+			}
+			else
+			{
+				fs.unlinkSync(file_path);
+			}
+			return true;
+		}catch(err)
+		{
+			throw err;
+		}
+	}
+
+	/**
+	 * Deletes a directory synchronously.
+	 *
+	 * @param {string} dir_path - Path to the directory to delete
+	 * @param {boolean} [recursive=false] - Delete directory and its contents. (only has effect if `move_to_trash` parameter is false.
+	 * @param {boolean} [move_to_trash=false] - Move file to trash instead of completely deleting it.
+	 * @returns {boolean} - Returns true on success, or throws error on failure
+	 * @throws {Error} When the directory path is invalid.
+	 * @throws {Error} When the path is not a directory.
+	 * @throws {Error} When the directory is not empty and `recursive=false`.
+	 * @throws {Error} When failed to delete the directory.
+	 */
+	deleteDirectory(dir_path, recursive = false, move_to_trash = false)
+	{
+		if(!(typeof dir_path === "string")) throw new Error(`Invalid "dir_path" argument: ${typeof dir_path}`);
+		if(!this.fileExists(dir_path)) return true;
+		if(!this.fileStat(dir_path).isDirectory) throw new Error(`Failed to delete the directory: Provided path is not a directory. Use ui.deleteFile() instead.`);
+
+		if(move_to_trash)
+		{
+			return this.sendToGUI({system: "moveToTrash", value: dir_path}, r =>
+			{
+				return r.value;
+			});
+		}
+
+		try
+		{
+			// delete the main directory
+			if(this.runtime === "deno")
+			{
+				Deno.removeSync(dir_path, {recursive: recursive === true});
+			}
+			else
+			{
+				if(recursive)
+				{
+					fs.rmSync(dir_path, {recursive: true, force: true});
+				}
+				else
+				{
+					fs.rmdirSync(dir_path);
+				}
+			}
+			return true;
+		}catch(err)
+		{
+			if(this.os === "darwin" && (err.code === "EACCES" || err.code === "ENOTEMPTY"))
+			{
+				try
+				{
+					const script = `do shell script "rm -rf '${dir_path.replace(/'/g, "'\"'\"'")}'" with administrator privileges with prompt "Your permission is needed to delete directory: ${dir_path}"`;
+
+					execFileSync("osascript", ["-e", script]);
+					return true;
+				}catch(err2)
+				{
+					throw err2;
+				}
+			}
+			else
+			{
+				throw err;
+			}
+		}
+	}
+
+	/**
+	 * Deletes a file or directory synchronously.
+	 *
+	 * @param {string} path - Path to the directory to delete
+	 * @param {boolean} [recursive=false] - Delete directory and its contents. (only has effect if `move_to_trash` parameter is false.
+	 * @param {boolean} [move_to_trash=false] - Move file to trash instead of completely deleting it.
+	 * @returns {boolean} - Returns true on success, or throws error on failure
+	 * @throws {Error} When the file path is invalid.
+	 * @throws {Error} When access is denied.
+	 * @throws {Error} When failed to delete the file or directory.
+	 */
+	deleteAny(path, recursive = false, move_to_trash = false)
+	{
+		if(!(typeof path === "string")) throw new Error(`Invalid "path" argument: ${typeof path}`);
+		if(!this.fileExists(path)) return true;
+
+		if(this.fileStat(path).isDirectory)
+		{
+			return this.deleteDirectory(path, recursive, move_to_trash);
+		}
+		else
+		{
+			return this.deleteFile(path, move_to_trash);
+		}
+	}
+
+	/**
+	 * Synchronously checks if a file can be read.
+	 *
+	 * @param {string|URL} file_path - Path to the file to check
+	 * @returns {boolean} - Returns true if file can be read, false otherwise
+	 * @throws {Error} When the file path is invalid.
+	 */
+	canReadFile(file_path)
+	{
+		if(!(typeof file_path === "string")) throw new Error(`Invalid "file_path" argument: ${typeof file_path}`);
+
+		try
+		{
+			if(this.runtime === "deno")
+			{
+				const stat = Deno.statSync(file_path);
+				return stat.isFile || stat.isDirectory;
+			}
+			else
+			{
+				fs.accessSync(file_path, fs.constants.R_OK);
+				return true;
+			}
+		}catch(err)
+		{
+			return false;
+		}
+	}
+
+	/**
+	 * Synchronously checks if a file can be written to.
+	 *
+	 * @param {string|URL} file_path - Path to the file to check
+	 * @returns {boolean} - Returns true if file can be written to, false otherwise
+	 * @throws {Error} When the file path is invalid.
+	 */
+	canWriteFile(file_path)
+	{
+		if(!(typeof file_path === "string")) throw new Error(`Invalid "file_path" argument: ${typeof file_path}`);
+		try
+		{
+			if(this.runtime === "deno")
+			{
+				// Check if file exists and is writable
+				const fileInfo = Deno.statSync(file_path);
+				if(!fileInfo.isFile) return false;
+
+				// Try to open with write access
+				const file = Deno.openSync(file_path, {write: true});
+				file.close();
+				return true;
+			}
+			else
+			{
+				fs.accessSync(file_path, fs.constants.W_OK);
+				return true;
+			}
+		}catch(err)
+		{
+			return false;
+		}
+	}
+
+	/**
+	 * Creates a directory synchronously.
+	 *
+	 * @param {string} dir_path - Path to the directory to create
+	 * @param {boolean} [recursive=false] - Create parent directories if they don't exist
+	 * @returns {boolean} - Returns `true` on success or throws error on failure
+	 * @throws {Error} When the directory path is invalid.
+	 * @throws {Error} When the directory already exists.
+	 * @throws {Error} When failed to create the directory.
+	 */
+	makeDirectory(dir_path, recursive = false)
+	{
+		if(!(typeof dir_path === "string")) throw new Error(`Invalid "dir_path" argument: ${typeof dir_path}`);
+
+		if(this.fileExists(dir_path))
+		{
+			if(this.fileStat(dir_path).isDirectory) return true;
+			throw new Error(`Failed to create directory: Path already exists as a file: ${dir_path}`);
+		}
+
+		try
+		{
+			if(this.runtime === "deno")
+			{
+				Deno.mkdirSync(dir_path, {recursive: recursive === true});
+			}
+			else
+			{
+				fs.mkdirSync(dir_path, {recursive: recursive === true});
+			}
+			return true;
+		}catch(err)
+		{
+			throw err;
+		}
+	}
+
+	/**
+	 * Moves or copies a file synchronously. If the destination directory doesn't exist, the operation may fail.
+	 *
+	 * @param {string} from_file_path - Source file path
+	 * @param {string} to_file_path - Destination file path
+	 * @param {boolean} [copy=false] - Copy instead of move
+	 * @returns {boolean} - Returns true on success, or throws an error on failure
+	 * @throws {Error} On failure to move or copy the file.
+	 */
+	moveFile(from_file_path, to_file_path, copy = false)
+	{
+		if(!(typeof from_file_path === "string")) throw new Error(`Invalid "from_file_path" argument: ${typeof from_file_path}`);
+		if(!(typeof to_file_path === "string")) throw new Error(`Invalid "to_file_path" argument: ${typeof to_file_path}`);
+		if(!this.fileExists(from_file_path)) throw new Error(`Source file not found: ${from_file_path}`);
+		if(!this.fileStat(from_file_path).isFile) throw new Error(`Source path is not a file: ${from_file_path}`);
+
+		try
+		{
+			if(this.runtime === "deno")
+			{
+				if(copy)
+				{
+					Deno.copyFileSync(from_file_path, to_file_path);
+				}
+				else
+				{
+					Deno.renameSync(from_file_path, to_file_path);
+				}
+			}
+			else
+			{
+				if(copy)
+				{
+					fs.copyFileSync(from_file_path, to_file_path);
+				}
+				else
+				{
+					fs.renameSync(from_file_path, to_file_path);
+				}
+			}
+			return true;
+		}catch(err)
+		{
+			throw err;
+		}
+	}
+
+	/**
+	 * Moves or copies a directory synchronously. If the destination  parent directory doesn't exist, the operation may fail.
+	 *
+	 * @param {string} from_dir_path - Source directory path
+	 * @param {string} to_dir_path - Destination directory path
+	 * @param {boolean} [copy=false] - Copy instead of move
+	 * @returns {boolean} - Returns true on success, or throws an error on failure
+	 * @throws {Error} On failure to move or copy the file.
+	 */
+	moveDirectory(from_dir_path, to_dir_path, copy = false)
+	{
+		if(!(typeof from_dir_path === "string")) throw new Error(`Invalid "from_dir_path" argument: ${typeof from_dir_path}`);
+		if(!(typeof to_dir_path === "string")) throw new Error(`Invalid "to_dir_path" argument: ${typeof to_dir_path}`);
+		if(!this.fileExists(from_dir_path)) throw new Error(`Source directory not found: ${from_dir_path}`);
+		if(!this.fileStat(from_dir_path).isDirectory) throw new Error(`Source path is not a directory: ${from_dir_path}`);
+
+		try
+		{
+			if(this.runtime === "deno")
+			{
+				if(copy)
+				{
+					Deno.copySync(from_dir_path, to_dir_path);
+				}
+				else
+				{
+					Deno.renameSync(from_dir_path, to_dir_path);
+				}
+			}
+			else
+			{
+				if(copy)
+				{
+					fs.cpSync(from_dir_path, to_dir_path, {recursive: true});
+				}
+				else
+				{
+					fs.renameSync(from_dir_path, to_dir_path);
+				}
+			}
+			return true;
+		}catch(err)
+		{
+			throw err;
+		}
+	}
+
+	/**
+	 * Reads the contents of a directory synchronously and returns an Array of files and directories.
+	 *
+	 * @param {string} dir_path - Path to the directory to read
+	 * @returns {Array<string>} - Returns an Array of filenames/directory names in the directory.
+	 * @throws {Error} When the directory path is invalid.
+	 * @throws {Error} When the directory is not found.
+	 * @throws {Error} When specified path is not a directory.
+	 * @throws {Error} When access is denied.
+	 * @throws {Error} When failed to read the directory.
+	 */
+	listDirectory(dir_path)
+	{
+		if(!(typeof dir_path === "string")) throw new Error(`Invalid argument: ${typeof dir_path}`);
+		if(!this.fileExists(dir_path)) throw new Error(`Directory not found: ${dir_path}`);
+		if(!this.fileStat(dir_path).isDirectory) throw new Error(`Path is not a directory: ${dir_path}`);
+		if(!this.canReadFile(dir_path)) throw new Error(`Failed to read directory, access is denied: ${dir_path}`);
+
+		try
+		{
+			if(this.runtime === "deno")
+			{
+				const entries = [];
+				for(const entry of Deno.readDirSync(dir_path))
+				{
+					entries.push(entry.name);
+				}
+				return entries;
+			}
+			else
+			{
+				return fs.readdirSync(dir_path);
+			}
+		}catch(err)
+		{
+			throw new Error(`Failed to read directory: ${dir_path}`);
+		}
+	}
+
+	/**
+	 * Sets or gets a current working directory.
+	 *
+	 * @param {string} [dir=undefined] - New directory (omit when getting a directory).
+	 * @returns {string} Returns current working directory. Throws error if the directory cannot be found or the user doesn't have permissions to access the specified directory when getting.
+	 * @throws {Error} When setting working directory failed because it doesn't exist.
+	 */
+	cwd(dir = undefined)
+	{
+		if(dir != null && !this.fileExists(dir)) throw new Error(`Directory is not found: ${dir}`);
+
+		if(this.runtime === "deno")
+		{
+			if(dir != null) Deno.chdir(dir);
+			return Deno.cwd();
+		}
+		else
+		{
+			if(dir != null) process.chdir(dir);
+			return process.cwd();
+		}
+	}
+
+	//endregion
+
+	//region Events
+
+	/**
+	 * Registering and removing global UI events.
+	 *
+	 * @internal
+	 * @param {string} name
+	 * @param {function(any):any|null|undefined} [callback]
+	 * @param {boolean} [remove]
+	 * @return {this|function[]}
+	 */
+	#globalEvent(name, callback = undefined, remove = false)
+	{
+		// return callbacks
+		if(callback === undefined) return Array.isArray(this.callback[name]) ? [...this.callback[name]] : [];
+
+		// remove callback
+		if(remove === true || callback === null)
+		{
+			if(!Array.isArray(this.callback[name])) return this;
+
+			if(callback === null)
+			{
+				this.callback[name].length = 0;
+			}
+			else
+			{
+				const i = this.callback[name].indexOf(callback); // find callback
+				if(i === -1) return this;
+				this.callback[name].splice(i, 1); // remove it
+			}
+
+			if(this.callback[name] != null && this.callback[name].length === 0)
+			{
+				delete this.callback[name]; // delete array
+				this.sendToGUI({java: "globalEvent", remove: name}); // notify GUI
+			}
+		}
+		// add callback
+		else
+		{
+			if(typeof callback !== "function") throw new Error(`Invalid argument for callback function. Must be a "function" type.`);
+
+			if(!Array.isArray(this.callback[name]))
+			{
+				this.callback[name] = []; // create array
+				this.sendToGUI({java: "globalEvent", add: name}); // notify GUI
+			}
+
+			this.callback[name].push(callback);
+		}
+
+		return this;
+	}
+
+	/**
+	 * Registers java-wide {@link MouseEvent} event handler that works in all Java apps (but not outside of Java applications).
+	 *
+	 * @param {function(MouseEvent):any} [callback=undefined] - Function to handle the event
+	 * @param {boolean} [remove=false] - Remove the callback from this event
+	 * @return {SwingUI|function[]} When called with arguments, returns `this` instance of SwingUI class, otherwise returns an array of current callbacks.
+	 * @see MouseEvent
+	 */
+	onMouseEvents(callback = undefined, remove = false)
+	{
+		return this.#globalEvent("onMouseEvents", callback, remove === true);
+	}
+
+	/**
+	 * Registers java-wide {@link MouseMotionEvent} event handler that works in all Java apps (but not outside of Java applications).
+	 *
+	 * @param {function(MouseMotionEvent):any} [callback=undefined] - Function to handle the event
+	 * @param {boolean} [remove=false] - Remove the callback from this event
+	 * @return {SwingUI|function[]} When called with arguments, returns `this` instance of SwingUI class, otherwise returns an array of current callbacks.
+	 * @see MouseMotionEvent
+	 */
+	onMouseMotion(callback = undefined, remove = false)
+	{
+		return this.#globalEvent("onMouseMotion", callback, remove === true);
+	}
+
+	/**
+	 * Registers java-wide {@link MouseWheelEvent} handler that works in all Java apps (but not outside of Java applications).
+	 *
+	 * @param {function(Object):any} [callback=undefined] - Function to handle the {@link MouseWheelEvent}
+	 * @param {boolean} [remove=false] - Remove the callback from this event
+	 * @return {SwingUI|function[]} When called with arguments, returns `this` instance of SwingUI class, otherwise returns an array of current callbacks.
+	 * @see MouseWheelEvent
+	 * @see UIComponent#onMouseWheel
+	 */
+	onMouseWheel(callback = undefined, remove = false)
+	{
+		return this.#globalEvent("onMouseWheel", callback, remove === true);
+	}
+
+	/**
+	 * Registers java-wide {@link KeyEvent} keyboard key event handler. Handles keyboard keys actions made anywhere on the operating system.
+	 *
+	 * @param {function(KeyEvent):any} [callback=undefined] - Function to handle the event
+	 * @param {boolean} [remove=false] - Remove the callback from this event
+	 * @returns {SwingUI|function[]} When called with arguments, returns `this` instance of SwingUI class, otherwise returns an array of current callbacks.
+	 * @see KeyEvent
+	 */
+	onKey(callback = undefined, remove = false)
+	{
+		return this.#globalEvent("onKey", callback, remove === true);
+	}
+
+	/**
+	 * Registers, gets, or unregisters event handler callbacks for application events on macOS.
+	 *
+	 * @param {function(AppEvent):any} [callback=undefined] - A callback function that receives an {@link AppEvent} object. Set to `null` to unregister all callbacks for this event. Omit to get an array of callbacks for this event.
+	 * @param {boolean} [remove=false] - Remove the callback from this event.
+	 * @returns {SwingUI|function[]} If called without parameters, an array of registered callbacks is returned; otherwise `this` instance of SwingUI class is returned.
+	 * @see AppEvent
+	 */
+	onAppEvents(callback = undefined, remove = false)
+	{
+		const name = "onAppEvents";
+
+		// return callbacks
+		if(callback === undefined) return Array.isArray(this.callback[name]) ? [...this.callback[name]] : [];
+
+		// remove callback
+		if(remove === true || callback === null)
+		{
+			if(!Array.isArray(this.callback[name])) return this;
+
+			if(callback === null)
+			{
+				this.callback[name].length = 0;
+			}
+			else
+			{
+				this.callback[name] = this.callback[name].filter(l => l !== callback);
+			}
+
+			if(this.callback[name].length === 0)
+			{
+				delete this.callback[name]; // delete array
+				this.sendToGUI({system: name, remove: true}); // notify GUI
+			}
+		}
+		// add callback
+		else
+		{
+			if(typeof callback !== "function") throw new Error(`Invalid argument for callback function. Must be a "function" type.`);
+
+			if(!Array.isArray(this.callback[name]))
+			{
+				this.callback[name] = []; // create array
+				this.sendToGUI({system: name, remove: false}); // notify GUI
+			}
+
+			this.callback[name].push(callback); // add callback (don't bind to this here, do it at call)
+		}
+
+		return this;
+	}
+
+	/**
+	 * Registers, unregisters and retrieves event handler that receive STDIN data sent by command line interface (CLI).
+	 *
+	 * @param {function(Object):any|null|undefined} [callback] - Function to handle the event, `null` to remove all handlers, or omit to retrieve an array of handlers.
+	 * @param {boolean} remove - Removed the callback from this event
+	 * @return {SwingUI|function[]} If called without parameters, an array of registered callbacks is returned; otherwise `this` instance of SwingUI class is returned.
+	 * @example <h2>Registering an event handler to receive CLI input:</h2>
+	 * ui.onCLI(e => {console.log(`Received: ${e.data}`);});
+	 */
+	onCLI(callback = undefined, remove = false)
+	{
+		const name = "onCLI";
+
+		// return callbacks
+		if(callback === undefined) return Array.isArray(this.callback[name]) ? [...this.callback[name]] : [];
+
+		// remove callback
+		if(remove === true || callback === null)
+		{
+			if(!Array.isArray(this.callback[name])) return this;
+
+			if(callback === null)
+			{
+				this.callback[name].length = 0;
+			}
+			else
+			{
+				const i = this.callback[name].indexOf(callback); // find callback
+				if(i === -1) return this;
+				this.callback[name].splice(i, 1); // remove it
+			}
+
+			if(this.callback[name].length === 0) delete this.callback[name]; // delete array
+		}
+		else // add callback
+		{
+			if(typeof callback !== "function") throw new Error(`Invalid argument for callback function. Must be a "function" type.`);
+
+			if(!Array.isArray(this.callback[name])) this.callback[name] = []; // create array
+
+			this.callback[name].push(callback); // add callback (don't bind to this here, do it at call)
+		}
+
+		return this;
+	}
+
+	/**
+	 * Registers, unregisters and retrieves event handler for an event emitted when UI look and feel is changed using ui.ui(id) method.
+	 *
+	 * @param {function(Object):any|null|undefined} [callback] - Function to handle the event, `null` to remove all handlers, or omit to retrieve an array of handlers.
+	 * @param {boolean} remove - Removed the callback from this event
+	 * @return {SwingUI|function[]} If called without parameters, an array of registered callbacks is returned; otherwise `this` instance of SwingUI class is returned.
+	 * @example <h2>Receive UI look and feel change events:</h2>
+	 * ui.onUIChange(e => {console.log(e);});
+	 *
+	 * // when UI changes, it prints the event like this:
+	 * {
+	 *   newValue: {
+	 *     name: "Metal"
+	 *     dark: false
+	 *     id: "MetalLookAndFeel"
+	 *   }
+	 *   oldValue: {
+	 *     name: "FlatLaf Dark"
+	 *     dark: true
+	 *     id: "FlatDarkLaf"
+	 *   }
+	 *   event: "onUIChange"
+	 *   type: "change"
+	 * }
+	 * @see SwingUI#list
+	 * @see SwingUI#ui
+	 */
+	onUIChange(callback = undefined, remove = false)
+	{
+		const name = "onUIChange";
+
+		// return callbacks
+		if(callback === undefined) return Array.isArray(this.callback[name]) ? [...this.callback[name]] : [];
+
+		// remove callback
+		if(remove === true || callback === null)
+		{
+			if(!Array.isArray(this.callback[name])) return this;
+
+			if(callback === null)
+			{
+				this.callback[name].length = 0;
+			}
+			else
+			{
+				this.callback[name] = this.callback[name].filter(l => l !== callback);
+			}
+
+			if(this.callback[name].length === 0)
+			{
+				delete this.callback[name]; // delete array
+				this.sendToGUI({java: name, remove: true}); // notify GUI
+			}
+		}
+		// add callback
+		else
+		{
+			if(typeof callback !== "function") throw new Error(`Invalid argument for callback function. Must be a "function" type.`);
+
+			if(!Array.isArray(this.callback[name]))
+			{
+				this.callback[name] = []; // create array
+				this.sendToGUI({java: name, remove: false}); // notify GUI
+			}
+
+			this.callback[name].push(callback); // add callback (don't bind to this here, do it at call)
+		}
+
+		return this;
+	}
+
+	/**
+	 * Registers, unregisters and retrieves event handler for exit event emitted by ui.exit() method.
+	 *
+	 * @param {function(Object):any|null|undefined} [callback] - Function to handle the event, `null` to remove all handlers, or omit to retrieve an array of handlers.
+	 * @param {boolean} remove - Removed the callback from this event
+	 * @return {SwingUI|function[]} If called without parameters, an array of registered callbacks is returned; otherwise `this` instance of SwingUI class is returned.
+	 * @example <h2>Registering exit event handler:</h2>
+	 * ui.onExit(e => {console.log(`Exiting with code: ${e.code}`);});
+	 * @see SwingUI#exit
+	 */
+	onExit(callback = undefined, remove = false)
+	{
+		const name = "onExit";
+		if(callback === undefined) return Array.isArray(this.callback[name]) ? [...this.callback[name]] : [];
+		if(callback === null)
+		{
+			delete this.callback[name];
+		}
+		else if(remove === true)
+		{
+			const i = this.callback[name].indexOf(callback); // find callback
+			if(i === -1) return this;
+			this.callback[name].splice(i, 1); // remove it
+		}
+		else
+		{
+			if(typeof callback !== "function") throw new Error(`Invalid argument for callback function. Must be a "function" type.`);
+
+			if(!Array.isArray(this.callback[name])) this.callback[name] = []; // create array
+			this.callback[name].push(callback);
+		}
+
+		return this;
+	}
+
+	//endregion
+}