@devscholar/node-with-gjs 0.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) DevScholar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# Node with GJS
+
+⚠️ This project is still in pre-alpha stage, and API is subject to change.
+
+This is a project that brings GNOME's GJS (GObject Introspection JavaScript runtime) to Node.js, allowing you to use GTK4 and WebKit from JavaScript/TypeScript with a Node.js-like API. Since this project uses IPC instead of C++ Addon, it is compatible not only with Node but also with Deno and Bun.
+
+# Requirements
+
+- Linux with GTK4 and WebKitGTK 6.0 installed
+- Node.js 22+ (or Deno/Bun)
+- bash (for Unix pipe IPC)
+
+## Installation
+
+Note: These packages are supposed to be pre-installed with GNOME-based Linux distros:
+
+For Ubuntu/Debian:
+```bash
+apt install libgtk-4-1 libwebkitgtk-6.0-0 gjs
+```
+
+For Fedora:
+```bash
+dnf install gtk4 webkitgtk6.0 gjs
+```
+
+For Arch Linux:
+```bash
+pacman -S gtk4 webkitgtk-6.0 gjs
+```
+
+# Usage
+
+## Runtime Support
+
+| Runtime | `gi://` URL Syntax | Loader Hooks |
+|---------|-------------------|--------------|
+| Node.js | ✅ Supported | ✅ `--experimental-loader` |
+| Bun | ❌ Not supported | ❌ No hooks mechanism |
+| Deno | ❌ Not supported | ❌ No hooks mechanism |
+
+## Node.js
+
+Node.js supports the `gi://` URL syntax, which is consistent with GJS:
+
+```typescript
+import Gtk from 'gi://Gtk?version=4.0';
+import WebKit from 'gi://WebKit?version=6.0';
+
+const app = new Gtk.Application({ application_id: 'org.example.app' });
+// ...
+```
+
+## Bun / Deno
+
+Bun and Deno do not support Node.js loader hooks, so you need to use the `loadGi` function instead:
+
+```typescript
+import { loadGi } from './gi-loader.ts';
+
+const Gtk = loadGi('Gtk', '4.0');
+const WebKit = loadGi('WebKit', '6.0');
+
+const app = new Gtk.Application({ application_id: 'org.example.app' });
+// ...
+```
+
+**Note:** The `loadGi` function also works with Node.js, useful for older Node.js versions or when not using experimental loader flags.
+
+# Examples
+
+## Console Apps
+
+### Console Input App
+
+```bash
+node start.js examples/console/console-input/console-input.ts
+```
+
+### Await Delay App
+
+```bash
+node start.js examples/console/await-delay/await-delay.ts
+```
+
+## GUI Apps
+
+### GTK4 Counter App
+
+```bash
+node start.js examples/gtk/counter/counter.ts
+```
+
+### GTK4 Drag Box App
+
+A drag box example that demonstrates high frequency IPC.
+
+```bash
+node start.js examples/gtk/drag-box/drag-box.ts
+```
+
+### GTK4 WebKit Counter App
+
+```bash
+node start.js examples/gtk-webkit/counter/counter.ts
+```
+
+### Adwaita Counter App (libadwaita)
+
+A counter example based on [libadwaita](https://gnome.pages.gitlab.gnome.org/libadwaita/), demonstrating how to use Adwaita-specific components like `Adw.ApplicationWindow` and `Adw.Clamp`.
+
+```bash
+node start.js examples/adwaita/counter/counter.ts
+```
+
+# License
+
+This project is licensed under the MIT License.

package/deno.json

@@ -0,0 +1,8 @@
+{
+  "tasks": {
+    "start": "deno run --allow-all --config deno.json"
+  },
+  "compilerOptions": {
+    "lib": ["deno.window"]
+  }
+}

package/examples/adwaita/counter/counter.ts

@@ -0,0 +1,66 @@
+// Run: node start.js examples/adwaita/counter/counter.ts
+import { loadGi } from '../../../gi-loader.ts';
+
+const Gtk = loadGi('Gtk', '4.0');
+const Adw = loadGi('Adw', '1');
+
+let clickCount = 0;
+
+console.log("--- Adwaita Counter ---");
+
+const app = new Adw.Application({ application_id: 'org.adwaita.counter' });
+
+app.connect('activate', () => {
+    const window = new Adw.ApplicationWindow({
+        application: app,
+        title: 'Adwaita Counter App',
+        default_width: 400,
+        default_height: 300
+    });
+
+    const toolbarView = new Adw.ToolbarView();
+
+    const headerBar = new Adw.HeaderBar({
+        title_widget: new Gtk.Label({ label: 'Adwaita Counter App' })
+    });
+    toolbarView.add_top_bar(headerBar);
+
+    const box = new Gtk.Box({
+        orientation: Gtk.Orientation.VERTICAL,
+        spacing: 10,
+        halign: Gtk.Align.CENTER,
+        valign: Gtk.Align.CENTER
+    });
+    box.set_margin_start(20);
+    box.set_margin_end(20);
+    box.set_margin_top(20);
+    box.set_margin_bottom(20);
+
+    const label = new Gtk.Label({
+        label: 'Clicks: 0',
+        css_classes: ['title-1']
+    });
+
+    const button = new Gtk.Button({
+        label: 'Click to Add',
+        css_classes: ['suggested-action']
+    });
+
+    button.connect('clicked', () => {
+        clickCount++;
+        const message = `Clicked ${clickCount} times`;
+        label.set_label(message);
+        console.log(message);
+    });
+
+    box.append(label);
+    box.append(button);
+
+    toolbarView.set_content(box);
+    window.set_content(toolbarView);
+    window.present();
+
+    console.log("Click the button to increase the counter...");
+});
+
+app.run([]);

package/examples/console/await-delay/await-delay.ts

@@ -0,0 +1,11 @@
+// Run: node start.js examples/console/await-delay/await-delay.ts
+import { loadGi } from '../../../gi-loader.ts';
+
+loadGi('GLib', '2.0');
+
+print('0s');
+await new Promise(resolve => setTimeout(resolve, 1000));
+print("1s");
+await new Promise(resolve => setTimeout(resolve, 1000));
+print("2s");
+await new Promise(resolve => setTimeout(resolve, 1000));

package/examples/console/console-input/console-input.ts

@@ -0,0 +1,27 @@
+// Run: node start.js examples/console/console-input/console-input.ts
+import { loadGi } from '../../../gi-loader.ts';
+
+const Gio = loadGi('Gio', '2.0');
+
+let GioUnix;
+try {
+    GioUnix = loadGi('GioUnix', '2.0');
+} catch {
+    GioUnix = Gio;
+}
+
+print("=== Greeting Program ===");
+print("Please enter your name: ");
+
+const stdin = new GioUnix.InputStream({ fd: 0, close_fd: false });
+const dataInput = new Gio.DataInputStream({ base_stream: stdin });
+
+const [name] = dataInput.read_line_utf8(null);
+
+if (name && name.trim() !== "") {
+    print(`Hello, ${name}! Welcome to this program!`);
+} else {
+    print("Hello, friend! Welcome to this program!");
+}
+
+print("Program ended.");

package/examples/gtk/counter/counter.ts

@@ -0,0 +1,62 @@
+// Run: node start.js examples/gtk/counter/counter.ts
+import { loadGi } from '../../../gi-loader.ts';
+
+const Gtk = loadGi('Gtk', '4.0');
+
+let clickCount = 0;
+
+console.log("--- GTK4 Counter ---");
+
+const app = new Gtk.Application({ application_id: 'org.gtk.counter' });
+
+app.connect('activate', () => {
+    const window = new Gtk.ApplicationWindow({
+        application: app,
+        title: 'GTK Counter App',
+        default_width: 400,
+        default_height: 300
+    });
+
+    window.connect('close-request', () => {
+        app.quit();
+        return false;
+    });
+
+    const box = new Gtk.Box({
+        orientation: Gtk.Orientation.VERTICAL,
+        spacing: 10,
+        halign: Gtk.Align.CENTER,
+        valign: Gtk.Align.CENTER
+    });
+    box.set_margin_start(20);
+    box.set_margin_end(20);
+    box.set_margin_top(20);
+    box.set_margin_bottom(20);
+
+    const label = new Gtk.Label({
+        label: 'Clicks: 0',
+        css_classes: ['title-1']
+    });
+
+    const button = new Gtk.Button({
+        label: 'Click to Add',
+        css_classes: ['suggested-action']
+    });
+
+    button.connect('clicked', () => {
+        clickCount++;
+        const message = `Clicked ${clickCount} times`;
+        label.set_label(message);
+        console.log(message);
+    });
+
+    box.append(label);
+    box.append(button);
+
+    window.set_child(box);
+    window.present();
+
+    console.log("Click the button to increase the counter...");
+});
+
+app.run([]);

package/examples/gtk/drag-box/drag-box.ts

@@ -0,0 +1,77 @@
+// Run: node start.js examples/gtk/drag-box/drag-box.ts
+import { loadGi } from '../../../gi-loader.ts';
+
+const Gtk = loadGi('Gtk', '4.0');
+
+console.log("--- GTK4 Flicker-free Draggable Square (Cairo) ---");
+
+const app = new Gtk.Application({ application_id: 'org.gtk.dragbox' });
+
+app.connect('activate', () => {
+    const window = new Gtk.ApplicationWindow({
+        application: app,
+        title: 'Drag Example (High Frequency IPC) ',
+        default_width: 600,
+        default_height: 400
+    });
+
+    const fixed = new Gtk.Fixed();
+    fixed.set_hexpand(true);
+    fixed.set_vexpand(true);
+
+    const squareSize = 80;
+    const drawingArea = new Gtk.DrawingArea();
+    drawingArea.set_size_request(squareSize, squareSize);
+
+    const drawFunction = (area: any, cr: any, width: number, height: number) => {
+        cr.setSourceRGB(1.0, 0.2, 0.2);
+        cr.rectangle(0, 0, width, height);
+        cr.fill();
+    };
+
+    drawingArea.set_draw_func(drawFunction);
+
+    let currentX = 260;
+    let currentY = 160;
+    fixed.put(drawingArea, currentX, currentY);
+
+    const drag = new Gtk.GestureDrag();
+    
+    let isDragging = false;
+    let dragStartX = 0;
+    let dragStartY = 0;
+
+    drag.connect('drag-begin', (gesture: any, startX: number, startY: number) => {
+        if (startX >= currentX && startX <= currentX + squareSize &&
+            startY >= currentY && startY <= currentY + squareSize) {
+            isDragging = true;
+            dragStartX = currentX;
+            dragStartY = currentY;
+            console.log(`✅ Drag started at: (${startX}, ${startY})`);
+        }
+    });
+
+    drag.connect('drag-update', (gesture: any, offsetX: number, offsetY: number) => {
+        if (!isDragging) return;
+        const newX = dragStartX + offsetX;
+        const newY = dragStartY + offsetY;
+        fixed.move(drawingArea, newX, newY);
+    });
+
+    drag.connect('drag-end', (gesture: any, offsetX: number, offsetY: number) => {
+        if (!isDragging) return;
+        isDragging = false;
+        currentX = dragStartX + offsetX;
+        currentY = dragStartY + offsetY;
+        console.log(`🛑 Drag ended at position: (${currentX}, ${currentY})`);
+    });
+
+    fixed.add_controller(drag);
+
+    window.set_child(fixed);
+    window.present();
+
+    console.log("Window loaded. Try dragging the red square smoothly!");
+});
+
+app.run([]);

package/examples/gtk-webkit/counter/counter.html

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Counter</title>
+    <meta charset="UTF-8">
+    <style>
+        body { font-family: Arial, sans-serif; padding: 20px; text-align: center; }
+        h1 { color: #333; }
+        #display { font-size: 24px; margin: 20px 0; }
+        button { padding: 10px 20px; font-size: 16px; cursor: pointer; }
+    </style>
+    <script>
+        (function() {
+            const originalConsole = window.console;
+            window.console = {
+                log: function(...args) {
+                    window.webkit.messageHandlers.console.postMessage(args.join(' '));
+                },
+                error: function(...args) {
+                    window.webkit.messageHandlers.console.postMessage('[ERROR] ' + args.join(' '));
+                },
+                warn: function(...args) {
+                    window.webkit.messageHandlers.console.postMessage('[WARN] ' + args.join(' '));
+                }
+            };
+        })();
+    </script>
+</head>
+<body>
+    <h1>Counter App (WebKit)</h1>
+    <p id="display">Clicks: 0</p>
+    <button id="btn">Click to Add</button>
+
+    <script>
+        let clickCount = 0;
+        const display = document.getElementById('display');
+        const button = document.getElementById('btn');
+
+        button.addEventListener('click', function() {
+            clickCount++;
+            const message = 'Button clicked ' + clickCount + ' times';
+            display.textContent = message;
+            console.log(message);
+        });
+    </script>
+</body>
+</html>

package/examples/gtk-webkit/counter/counter.ts

@@ -0,0 +1,101 @@
+// Run: node start.js examples/gtk-webkit/counter/counter.ts
+import { loadGi } from '../../../gi-loader.ts';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const Gtk = loadGi('Gtk', '4.0');
+const WebKit = loadGi('WebKit', '6.0');
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+console.log('--- GTK4 WebKit Counter ---');
+
+const app = new Gtk.Application({ application_id: 'org.gtk.webkitcounter' });
+
+app.connect('activate', () => {
+    const window = new Gtk.ApplicationWindow({
+        application: app,
+        title: 'WebKit Counter App',
+        default_width: 500,
+        default_height: 400
+    });
+
+    const box = new Gtk.Box({
+        orientation: Gtk.Orientation.VERTICAL,
+        spacing: 0
+    });
+
+    const toolbar = new Gtk.Box({
+        orientation: Gtk.Orientation.HORIZONTAL,
+        spacing: 5
+    });
+    toolbar.set_margin_start(5);
+    toolbar.set_margin_end(5);
+    toolbar.set_margin_top(5);
+    toolbar.set_margin_bottom(5);
+
+    const htmlPath = path.join(__dirname, 'counter.html');
+    const htmlUri = 'file://' + htmlPath;
+
+    const backButton = new Gtk.Button({ label: '← Back' });
+    const forwardButton = new Gtk.Button({ label: 'Forward →' });
+    const urlEntry = new Gtk.Entry({
+        placeholder_text: 'Enter URL or use default',
+        text: htmlUri,
+        hexpand: true
+    });
+
+    toolbar.append(backButton);
+    toolbar.append(forwardButton);
+    toolbar.append(urlEntry);
+
+    const contentManager = new WebKit.UserContentManager();
+    
+    contentManager.connect('script-message-received', (manager, value) => {
+        const message = value.to_string();
+        if (message) print(`[WebView] ${message}`);
+    });
+    contentManager.register_script_message_handler('console', null);
+
+    const webView = new WebKit.WebView({
+        vexpand: true,
+        hexpand: true,
+        user_content_manager: contentManager
+    });
+
+    webView.load_uri(htmlUri);
+
+    webView.connect('load-changed', (webview, loadEvent) => {
+        if (loadEvent === WebKit.LoadEvent.FINISHED) {
+            console.log('Page Loaded Successfully');
+            urlEntry.set_text(webview.get_uri() || '');
+        }
+    });
+
+    backButton.connect('clicked', () => {
+        if (webView.can_go_back()) webView.go_back();
+    });
+
+    forwardButton.connect('clicked', () => {
+        if (webView.can_go_forward()) webView.go_forward();
+    });
+
+    urlEntry.connect('activate', () => {
+        let uri = urlEntry.get_text();
+        if (!uri.startsWith('http://') && !uri.startsWith('https://') && !uri.startsWith('file://')) {
+            uri = 'https://' + uri;
+        }
+        webView.load_uri(uri);
+    });
+
+    box.append(toolbar);
+    box.append(webView);
+
+    window.set_child(box);
+    window.present();
+
+    console.log("Click the button in the web view to increase the counter...");
+});
+
+app.run([]);

package/gi-loader.ts

@@ -0,0 +1,13 @@
+// gi-loader.ts
+// Universal GI namespace loader for Node.js, Bun, and Deno
+// Usage:
+//   import { loadGi } from './gi-loader.ts';
+//   const Gtk = loadGi('Gtk', '4.0');
+
+import { init, loadGiNamespace } from './src/index.ts';
+
+init();
+
+export function loadGi(namespace: string, version: string = '') {
+    return loadGiNamespace(namespace, version);
+}

package/hook.js

@@ -0,0 +1,42 @@
+// hook.js
+export async function resolve(specifier, context, nextResolve) {
+    if (specifier.startsWith('gi://')) {
+        return {
+            url: specifier,
+            shortCircuit: true,
+            format: 'module'
+        };
+    }
+    return nextResolve(specifier, context);
+}
+
+export async function load(url, context, nextLoad) {
+    if (url.startsWith('gi://')) {
+        // Safely parse 'gi://Gtk?version=4.0'
+        const bareUrl = url.replace('gi://', '');
+        const [namespacePart, queryPart] = bareUrl.split('?');
+        
+        const namespace = namespacePart;
+        let version = '';
+        
+        if (queryPart) {
+            const params = new URLSearchParams(queryPart);
+            version = params.get('version') || '';
+        }
+
+        const coreUrl = new URL('./src/index.ts', import.meta.url).href;
+        
+        const source = `
+            import { init, loadGiNamespace } from '${coreUrl}';
+            init();
+            export default loadGiNamespace('${namespace}', '${version}');
+        `;
+        
+        return {
+            format: 'module',
+            shortCircuit: true,
+            source: source
+        };
+    }
+    return nextLoad(url, context);
+}

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@devscholar/node-with-gjs",
+  "version": "0.0.0",
+  "description": "Node.js IPC Bridge for GJS",
+  "main": "start.js",
+  "type": "module",
+  "scripts": {
+
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/scripts/host.js

@@ -0,0 +1,162 @@
+// scripts/host.js
+import Gio from 'gi://Gio';
+import GLib from 'gi://GLib';
+import System from 'system';
+
+let InputStream, OutputStream;
+try {
+    const GioUnix = imports.gi.GioUnix;
+    InputStream = GioUnix.InputStream;
+    OutputStream = GioUnix.OutputStream;
+} catch (e) {
+    InputStream = Gio.UnixInputStream;
+    OutputStream = Gio.UnixOutputStream;
+}
+
+if (!InputStream || !OutputStream) {
+    console.error("Critical: Cannot find UnixInputStream/UnixOutputStream in this GJS environment.");
+    System.exit(1);
+}
+
+const inStream = new InputStream({ fd: 3, close_fd: false });
+const outStream = new OutputStream({ fd: 4, close_fd: false });
+
+const dataIn = new Gio.DataInputStream({ base_stream: inStream });
+const dataOut = new Gio.DataOutputStream({ base_stream: outStream });
+
+const objectStore = new Map();
+let nextObjectId = 1;
+
+function ConvertToProtocol(obj) {
+    if (obj === null || obj === undefined) return { type: 'null' };
+    const t = typeof obj;
+    if (t === 'string' || t === 'number' || t === 'boolean') {
+        return { type: 'primitive', value: obj };
+    }
+    if (Array.isArray(obj)) {
+        return { type: 'array', value: obj.map(ConvertToProtocol) };
+    }
+    const id = `gobj_${nextObjectId++}`;
+    objectStore.set(id, obj);
+    return { type: 'ref', id: id };
+}
+
+function processNestedCommands() {
+    while (true) {
+        const [line] = dataIn.read_line_utf8(null);
+        if (!line) System.exit(0);
+        const cmd = JSON.parse(line);
+        if (cmd.type === 'reply') return cmd;
+        let response;
+        try { response = executeCommand(cmd); } 
+        catch (e) { response = { type: 'error', message: e.toString() }; }
+        dataOut.put_string(JSON.stringify(response) + '\n', null);
+    }
+}
+
+function ResolveArg(arg) {
+    if (arg.type === 'null') return null;
+    if (arg.type === 'primitive') return arg.value;
+    
+    if (arg.type === 'uint8array') {
+        return new Uint8Array(arg.value);
+    }
+    
+    if (arg.type === 'ref') return objectStore.get(arg.id);
+    if (arg.type === 'array') return arg.value.map(a => ResolveArg(a));
+    if (arg.type === 'object') {
+        const obj = {};
+        for (let k in arg.value) obj[k] = ResolveArg(arg.value[k]);
+        return obj;
+    }
+    if (arg.type === 'callback') {
+        return (...cbArgs) => {
+            const mappedArgs = cbArgs.map(ConvertToProtocol);
+            const msg = { type: 'event', callbackId: arg.callbackId, args: mappedArgs };
+            dataOut.put_string(JSON.stringify(msg) + '\n', null);
+            const res = processNestedCommands();
+            if (res.result && res.result.type === 'primitive') return res.result.value;
+            return null;
+        };
+    }
+}
+
+function executeCommand(cmd) {
+    if (cmd.action === 'LoadNamespace') {
+        imports.gi.versions[cmd.namespace] = cmd.version;
+        const ns = imports.gi[cmd.namespace];
+        return ConvertToProtocol(ns);
+    }
+    // Instantiate from direct TypeId
+    if (cmd.action === 'New') {
+        const Type = objectStore.get(cmd.typeId);
+        const argsArray = (cmd.args || []).map(a => ResolveArg(a));
+        const instance = new Type(...argsArray);
+        return ConvertToProtocol(instance);
+    }
+    // Instantiate a property belonging to a namespace/object: e.g. new Gtk.Application() 
+    if (cmd.action === 'NewProp') {
+        const target = objectStore.get(cmd.targetId);
+        const Type = target[cmd.property];
+        if (!Type) throw new Error("Constructor not found: " + cmd.property);
+        const argsArray = (cmd.args || []).map(a => ResolveArg(a));
+        const instance = new Type(...argsArray);
+        return ConvertToProtocol(instance);
+    }
+    if (cmd.action === 'Get') {
+        const target = objectStore.get(cmd.targetId);
+        let val;
+        try { val = target[cmd.property]; } catch(e) { return { type: 'null' }; }
+        if (typeof val === 'function') return { type: 'function' };
+        return ConvertToProtocol(val);
+    }
+    if (cmd.action === 'Invoke') {
+        const target = objectStore.get(cmd.targetId);
+        const argsArray = (cmd.args || []).map(a => ResolveArg(a));
+        const func = target[cmd.methodName];
+        if (!func) throw new Error("Method not found: " + cmd.methodName);
+        const res = func.apply(target, argsArray);
+        return ConvertToProtocol(res);
+    }
+    if (cmd.action === 'Set') {
+        const target = objectStore.get(cmd.targetId);
+        target[cmd.property] = ResolveArg(cmd.value);
+        return { type: 'void' };
+    }
+    if (cmd.action === 'Release') {
+        objectStore.delete(cmd.targetId);
+        return { type: 'void' };
+    }
+    if (cmd.action === 'Print') {
+        print(...cmd.args.map(a => ResolveArg(a)));
+        return { type: 'void' };
+    }
+    throw new Error(`Unknown Action ${cmd.action}`);
+}
+
+function bindIPCEvent() {
+    const channel = GLib.IOChannel.unix_new(3);
+    GLib.io_add_watch(channel, GLib.PRIORITY_DEFAULT, GLib.IOCondition.IN, (channel, condition) => {
+        try {
+            const [line] = dataIn.read_line_utf8(null);
+            if (!line) {
+                System.exit(0);
+                return GLib.SOURCE_REMOVE;
+            }
+            const cmd = JSON.parse(line);
+            
+            let response;
+            try { response = executeCommand(cmd); } 
+            catch (e) { response = { type: 'error', message: e.toString() }; }
+            
+            dataOut.put_string(JSON.stringify(response) + '\n', null);
+        } catch (e) {}
+        return GLib.SOURCE_CONTINUE;
+    });
+}
+
+print("GJS IPC Host: Initialization Complete.");
+bindIPCEvent();
+
+const mainLoop = GLib.MainLoop.new(null, false);
+mainLoop.run();

package/src/index.ts

@@ -0,0 +1,180 @@
+// src/index.ts
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as cp from 'node:child_process';
+import * as os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { IpcSync } from './ipc.ts';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const gcRegistry = new FinalizationRegistry((id: string) => {
+    try { if (ipc) ipc.send({ action: 'Release', targetId: id }); } catch {}
+});
+
+const callbackRegistry = new Map<string, Function>();
+
+let ipc: IpcSync | null = null;
+let proc: cp.ChildProcess | null = null;
+let initialized = false;
+let reqPath = '';
+let resPath = '';
+
+function cleanup() {
+    if (!initialized) return;
+    initialized = false;
+    
+    if (ipc) try { ipc.close(); } catch {}
+    if (proc && !proc.killed) try { proc.kill('SIGKILL'); } catch {}
+    if (fs.existsSync(reqPath)) try { fs.unlinkSync(reqPath); } catch {}
+    if (fs.existsSync(resPath)) try { fs.unlinkSync(resPath); } catch {}
+    
+    proc = null;
+    ipc = null;
+}
+
+function findGjsPath(): string {
+    try {
+        const result = cp.execSync('which gjs', { encoding: 'utf-8' }).trim();
+        return result || 'gjs';
+    } catch {
+        return 'gjs';
+    }
+}
+
+function initialize() {
+    if (initialized) return;
+    
+    const token = `${process.pid}-${Date.now()}`;
+    reqPath = path.join(os.tmpdir(), `gjs-req-${token}.pipe`);
+    resPath = path.join(os.tmpdir(), `gjs-res-${token}.pipe`);
+
+    try {
+        cp.execSync(`mkfifo "${reqPath}"`);
+        cp.execSync(`mkfifo "${resPath}"`);
+    } catch(e) {
+        console.error("Failed to create Unix FIFOs");
+        process.exit(1);
+    }
+
+    const scriptPath = path.join(__dirname, '..', 'scripts', 'host.js');
+    const gjsPath = findGjsPath();
+    proc = cp.spawn('bash', ['-c', `exec "${gjsPath}" -m "${scriptPath}" 3<"${reqPath}" 4>"${resPath}"`], {
+        stdio: 'inherit',
+        env: process.env
+    });
+
+    proc.unref();
+
+    process.on('beforeExit', () => { cleanup(); process.exit(0); });
+    process.on('exit', cleanup);
+    process.on('SIGINT', () => { cleanup(); process.exit(0); });
+    process.on('uncaughtException', (err) => {
+        console.error('Node.js Exception:', err);
+        cleanup();
+        process.exit(1);
+    });
+
+    const fdWrite = fs.openSync(reqPath, 'w');
+    const fdRead = fs.openSync(resPath, 'r');
+
+    ipc = new IpcSync(fdRead, fdWrite, (res: any) => {
+        const cb = callbackRegistry.get(res.callbackId!);
+        if (cb) {
+            const wrappedArgs = (res.args || []).map((arg: any) => createProxy(arg));
+            return cb(...wrappedArgs);
+        }
+        return null;
+    });
+
+    (globalThis as any).print = (...args: any[]) => {
+        ipc!.send({ action: 'Print', args: args.map(wrapArg) });
+    };
+
+    initialized = true;
+}
+
+function wrapArg(arg: any): any {
+    if (arg === null || arg === undefined) return { type: 'null' };
+    if (arg.__ref) return { type: 'ref', id: arg.__ref };
+    
+    if (arg instanceof Uint8Array) {
+        return { type: 'uint8array', value: Array.from(arg) };
+    }
+    
+    if (typeof arg === 'function') {
+        const cbId = `cb_${Date.now()}_${Math.random()}`;
+        callbackRegistry.set(cbId, arg);
+        return { type: 'callback', callbackId: cbId };
+    }
+    
+    if (Array.isArray(arg)) return { type: 'array', value: arg.map(wrapArg) };
+    
+    if (typeof arg === 'object') {
+        const plainObj: any = {};
+        for (let k in arg) plainObj[k] = wrapArg(arg[k]);
+        return { type: 'object', value: plainObj };
+    }
+    
+    return { type: 'primitive', value: arg };
+}
+
+function createProxy(meta: any): any {
+    if (meta.type === 'primitive' || meta.type === 'null') return meta.value;
+    if (meta.type === 'array') return meta.value.map((item: any) => createProxy(item));
+    if (meta.type !== 'ref') return undefined;
+
+    const id = meta.id!;
+    const stub = function() {};
+
+    const proxy = new Proxy(stub, {
+        get: (target: any, prop: string | symbol) => {
+            if (prop === '__ref') return id;
+            if (typeof prop !== 'string') return undefined;
+
+            const val = ipc!.send({ action: 'Get', targetId: id, property: prop });
+            
+            if (val && val.type === 'function') {
+                return new Proxy(function() {}, {
+                    apply: (t, thisArg, args) => {
+                        const netArgs = args.map(wrapArg);
+                        const res = ipc!.send({ action: 'Invoke', targetId: id, methodName: prop, args: netArgs });
+                        return createProxy(res);
+                    },
+                    construct: (t, args) => {
+                        const netArgs = args.map(wrapArg);
+                        const res = ipc!.send({ action: 'NewProp', targetId: id, property: prop, args: netArgs });
+                        return createProxy(res);
+                    }
+                });
+            }
+            return createProxy(val);
+        },
+
+        set: (target: any, prop: string | symbol, value: any) => {
+            if (typeof prop !== 'string') return false;
+            ipc!.send({ action: 'Set', targetId: id, property: prop, value: wrapArg(value) });
+            return true;
+        },
+
+        construct: (target: any, args: any[]) => {
+            const netArgs = args.map(wrapArg);
+            const res = ipc!.send({ action: 'New', typeId: id, args: netArgs });
+            return createProxy(res);
+        }
+    });
+
+    gcRegistry.register(proxy, id);
+    return proxy;
+}
+
+export function init() {
+    initialize();
+}
+
+export function loadGiNamespace(namespace: string, version: string) {
+    initialize();
+    const res = ipc!.send({ action: 'LoadNamespace', namespace, version });
+    return createProxy(res);
+}

package/src/ipc.ts

@@ -0,0 +1,99 @@
+// src/ipc.ts
+import * as fs from 'node:fs';
+
+// Use a global/shared read buffer to handle redundant data across calls
+let readBuffer = Buffer.alloc(0);
+
+export function readLineSync(fd: number): string | null {
+    while (true) {
+        // 1. If the buffer already contains a complete line, extract and return it with minimal overhead
+        const newlineIdx = readBuffer.indexOf(10); // 10 is the ASCII code for \n
+        if (newlineIdx !== -1) {
+            const line = readBuffer.subarray(0, newlineIdx).toString('utf8');
+            readBuffer = readBuffer.subarray(newlineIdx + 1);
+            return line;
+        }
+
+        // 2. Otherwise, try to read a large chunk from the pipe
+        const chunk = Buffer.alloc(8192); // Attempt to read 8KB each time
+        let bytesRead = 0;
+        try {
+            bytesRead = fs.readSync(fd, chunk, 0, 8192, null);
+        } catch (e) {
+            return null;
+        }
+
+        if (bytesRead === 0) {
+            if (readBuffer.length === 0) return null;
+            const line = readBuffer.toString('utf8');
+            readBuffer = Buffer.alloc(0);
+            return line;
+        }
+
+        // 3. Append the newly read data to the buffer
+        readBuffer = Buffer.concat([readBuffer, chunk.subarray(0, bytesRead)]);
+    }
+}
+
+export class IpcSync {
+    private exited: boolean = false;
+
+    constructor(
+        private fdRead: number,
+        private fdWrite: number,
+        private onEvent: (msg: any) => any 
+    ) {}
+
+    send(cmd: any): any {
+        if (this.exited) return { type: 'exit' };
+
+        try {
+            fs.writeSync(this.fdWrite, JSON.stringify(cmd) + '\n');
+        } catch (e) {
+            throw new Error("Pipe closed (Write failed)");
+        }
+
+        while (true) {
+            const line = readLineSync(this.fdRead);
+            if (line === null) throw new Error("Pipe closed (Read EOF)");
+            if (!line.trim()) continue;
+
+            let res: any;
+            try {
+                res = JSON.parse(line);
+            } catch (e) {
+                throw new Error(`Invalid JSON from host: ${line}`);
+            }
+
+            if (res.type === 'event') {
+                let result = null;
+                try {
+                    result = this.onEvent(res);
+                } catch (e) {
+                    console.error("Callback Error:", e);
+                }
+                
+                const reply = { type: 'reply', result: result };
+                try {
+                    fs.writeSync(this.fdWrite, JSON.stringify(reply) + '\n');
+                } catch {}
+                continue; 
+            }
+
+            if (res.type === 'error') throw new Error(`GJS Host Error: ${res.message}`);
+            
+            if (res.type === 'exit') {
+                this.exited = true;
+                return res;
+            }
+            
+            return res;
+        }
+    }
+
+    close() {
+        this.exited = true;
+        if (this.fdRead) try { fs.closeSync(this.fdRead); } catch {}
+        if (this.fdWrite) try { fs.closeSync(this.fdWrite); } catch {}
+    }
+}

package/start.js

@@ -0,0 +1,105 @@
+// start.js
+import { spawn } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+    console.error('Usage: node start.js <script.ts> [--runtime=node|bun|deno]');
+    console.error('       bun start.js <script.ts> [--runtime=node|bun|deno]');
+    console.error('       deno run start.js <script.ts> [--runtime=node|bun|deno]');
+    process.exit(1);
+}
+
+let runtime = null;
+let targetScript = null;
+
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--runtime' && args[i + 1]) {
+        runtime = args[i + 1].toLowerCase();
+        i++;
+    } else if (!args[i].startsWith('--')) {
+        targetScript = args[i];
+    }
+}
+
+if (!targetScript) {
+    console.error('Error: No script specified');
+    process.exit(1);
+}
+
+targetScript = path.resolve(targetScript);
+const hookUrl = new URL('./hook.js', import.meta.url).href;
+
+if (!runtime) {
+    runtime = detectRuntime();
+}
+
+const validRuntimes = ['node', 'bun', 'deno'];
+if (!validRuntimes.includes(runtime)) {
+    console.error(`Error: Invalid runtime "${runtime}". Must be one of: ${validRuntimes.join(', ')}`);
+    process.exit(1);
+}
+
+console.log(`Starting ${runtime.charAt(0).toUpperCase() + runtime.slice(1)}-GJS execution context...`);
+
+let proc;
+
+switch (runtime) {
+    case 'bun':
+        proc = spawnBun(targetScript);
+        break;
+    case 'deno':
+        proc = spawnDeno(targetScript);
+        break;
+    case 'node':
+    default:
+        proc = spawnNode(targetScript, hookUrl);
+        break;
+}
+
+proc.on('exit', (code) => {
+    process.exit(code || 0);
+});
+
+function detectRuntime() {
+    if (typeof Bun !== 'undefined') return 'bun';
+    if (typeof Deno !== 'undefined') return 'deno';
+    return 'node';
+}
+
+function spawnNode(targetScript, hookUrl) {
+    return spawn(process.execPath, [
+        '--no-warnings', 
+        '--experimental-loader', hookUrl,
+        '--experimental-transform-types', 
+        targetScript
+    ], {
+        stdio: 'inherit',
+        env: process.env
+    });
+}
+
+function spawnBun(targetScript) {
+    return spawn('bun', [
+        'run',
+        targetScript
+    ], {
+        stdio: 'inherit',
+        env: process.env
+    });
+}
+
+function spawnDeno(targetScript) {
+    return spawn('deno', [
+        'run',
+        '--allow-all',
+        targetScript
+    ], {
+        stdio: 'inherit',
+        env: process.env
+    });
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}