node-gtk 2.2.0 → 4.0.0

package/README.md

@@ -2,7 +2,7 @@
     <a>
       <img
         alt="NODE-GTK"
-        width="250"
+        width="200"
         src="https://raw.githubusercontent.com/romgrk/node-gtk/master/img/node-gtk-logo.svg?sanitize=true"
       />
     </a>
@@ -12,205 +12,89 @@
 <p align="center">
   <b>GTK bindings for NodeJS</b>
   <br/>
-  <img src="https://img.shields.io/npm/v/node-gtk" alt="Package Version" />
 </p>
 
-`node-gtk` is a [gobject-introspection](https://gi.readthedocs.io/en/latest) library 
-for nodejs. It makes it possible to use any introspected C library, such as GTK, 
-usable. It is similar in essence to [GJS](https://wiki.gnome.org/action/show/Projects/Gjs) 
-or [PyGObject](https://pygobject.readthedocs.io). Please note this project is 
-currently in a _alpha_ state.
-
-Supported Node.js versions: **20**, **22**, **24** (other versions may work but are untested)<br>
-Supported platforms:
-- **Linux** — prebuilt binaries available
-- **macOS** — prebuilt binaries available
-- **Windows** — prebuilt binaries available (but read [Windows](#windows))
-
-
-### Table of contents
-
-- [Usage](#usage)
-- [ES modules](#es-modules)
-- [Documentation](#documentation)
-- [TypeScript](#typescript)
-- [Installing](#installing)
-- [Contributing](#contributing)
-
-## Usage
-
-Below is a [minimal example](./examples/hello-world.js) of how to use node-gtk:
-
-```javascript
-const gi = require('node-gtk');
-const GLib = gi.require('GLib', '2.0');
-const Gtk = gi.require('Gtk', '4.0');
-const Adw = gi.require('Adw', '1');
-
-const loop = GLib.MainLoop.new(null, false);
-const app = new Adw.Application('com.github.romgrk.node-gtk.hello', 0);
-
-app.on('activate', () => {
-  const content = new Gtk.Box({ orientation: Gtk.Orientation.VERTICAL });
-  content.append(new Adw.HeaderBar());
-  content.append(new Gtk.Label({ label: 'Hello Adwaita!', vexpand: true }));
-
-  const window = new Adw.ApplicationWindow(app);
-  window.setTitle('node-gtk');
-  window.setDefaultSize(300, 120);
-  window.setContent(content);
-  window.on('close-request', () => (loop.quit(), app.quit(), false));
-  window.present();
-
-  gi.startLoop();
-  loop.run();
-});
-
-process.exit(app.run([]));
-```
-
 <p align="center">
-  <img src="./img/hello-world.png" style="width: 290px; height: auto;"/>
+  <a href="#usage">Usage</a> · <a href="#installing">Installing</a> · <a href="./doc/index.md">Documentation</a> · <a href="#contributing">Contributing</a>
 </p>
 
-You can also easily create custom applications:
-
-[A web browser (using WebKit2GTK)](./examples/browser.js)
-
-<p align="center">
-  <img src="./img/browser.png" style="max-width: 500px; height: auto;"/>
-</p>
+<br />
 
-[A system monitor](./examples/system-monitor.js)
+`node-gtk` lets you build native GTK apps on **linux**, **macOS** and  **windows**
+with full **ESM**, **TypeScript** and **CSS hot-reload** support. Prebuilt binaries 
+are available for Node.js versions **22**, **24** and **26**.
 
 <p align="center">
-  <img src="./img/system-monitor.png" style="width: 400px; height: auto;"/>
+  <img src="./img/browser.png" style="max-width: 500px; height: auto;" alt="A web browser build with node-gtk" />
 </p>
 
-## ES modules
-
-The Usage example above is CommonJS. node-gtk also works under ESM, but the
-blocking main-loop calls (`GLib.MainLoop.run`, `Gio`/`Gtk.Application.run`,
-`Gtk.main`) **return immediately** instead of blocking and **don't return a
-value** — so make the run call the last statement and exit from your handler:
-
-```javascript
-app.on('activate', () => {
-  // ...build the window...
-  window.on('close-request', () => (loop.quit(), app.quit(), false));
-  window.present();
-
-  gi.startLoop();
-  loop.run();      // returns immediately under ESM; do cleanup/exit in the handler
-});
-
-app.run([]);       // not `process.exit(app.run([]))` — the return value is unavailable
-```
-
-CommonJS (and signal callbacks) are unaffected. For the why and the design
-trade-off, see [#449](https://github.com/romgrk/node-gtk/issues/449).
-
-## Documentation
-
-[Read our documentation here](./doc/index.md)
-
-## TypeScript
+## Usage
 
-node-gtk can generate TypeScript declarations for the libraries you use,
-straight from the GObject-Introspection typelibs installed on your machine — so
-the types always match your actual library versions and node-gtk's own runtime
-shape (camelCase methods, signal callbacks, nullability, etc.).
+The **create** tool generates a complete, ready-to-run GTK/Adwaita project, so you
+can start building immediately after [installing GTK4](#installing):
 
 ```sh
-# generates ./node_modules/.node-gtk-types (a hidden, git-ignored cache)
-npx node-gtk generate-types Gtk-4.0 Adw-1
-```
-
-The command emits one declaration file per namespace (plus the full dependency
-closure) and a `node-gtk.d.ts` shim. Point your `tsconfig.json` at it:
-
-```jsonc
-{
-  "compilerOptions": {
-    "moduleResolution": "node16",
-    "paths": { "node-gtk": ["./node_modules/.node-gtk-types/node-gtk.d.ts"] }
-  }
-}
-```
-
-Then `gi.require` is fully typed — the namespace is inferred from the string
-arguments:
-
-```ts
-import * as gi from 'node-gtk'
-
-const Gtk = gi.require('Gtk', '4.0')   // typed as the Gtk-4.0 namespace
-const win = new Gtk.ApplicationWindow({ title: 'Hello', defaultWidth: 400 })
-win.on('close-request', () => false)   // signal name + callback are typed
+npx node-gtk create <your-app>
 ```
 
-You get typed constructor properties (including inherited and interface ones),
-camelCase methods with real return types, GI nullability, typed signal
-overloads, enums, `bigint` for 64-bit integers, out-parameters surfaced as the
-return value, and cross-namespace types. GNOME's API documentation is included
-as JSDoc (with `@param`/`@returns`), so editors show it on hover — this reads the
-`.gir` files installed by the libraries' `-dev`/`-devel` packages; pass
-`--no-docs` for leaner output if they aren't installed or you don't want them.
-
-Because the output is a generated cache under `node_modules`, add a `postinstall`
-script so it regenerates on install:
-
-```json
-{ "scripts": { "postinstall": "node-gtk generate-types Gtk-4.0 Adw-1" } }
-```
+<p align="center">
+  <img src="./img/create-app-example.png" style="width: 500px; height: auto;"/>
+</p>
 
-Run `npx node-gtk generate-types --help` for options.
+Also see our [hello world](./examples/hello-world.mjs), [web browser](./examples/browser.mjs)
+or [system monitor](./examples/system-monitor.mjs) examples.
 
 ## Installing
 
-1. Install `node-gtk` itself
-2. Install the native libraries you use (see examples per platform below)
+There are two steps:
 
-```sh
-npm install node-gtk
-
-# This installs a prebuilt binary when one is available for your platform and
-# Node.js version, otherwise it falls back to building from source.
-```
+1. Install `node-gtk` itself (*done by the create tool*)
+2. Install the native libraries you use (see examples per platform below)
 
 #### Linux
 
 ```sh
 # archlinux
-pacman -S gtk4
+pacman -S gtk4 libadwaita
+
+# fedora
+dnf install gtk4 libadwaita
 
 # ubuntu
-apt install libgtk-4-1
+# Already installed :)
 ```
 
 #### macOS
 
 ```sh
-brew install gtk4
+brew install gtk4 libadwaita adwaita-icon-theme
 ```
 
 #### Windows
 
-Windows doesn't have the dependencies we need in a package manager, therefore 
-`node-gtk` ships prebuilt versions of GTK 4 / Adwaita runtime (DLLs, typelibs, 
-icons), so `npm install node-gtk` is all you need **if** your dependency is in 
-our [list of prebuilt libraries](./windows/runtime-libraries.txt).
+```sh
+# Already installed :)
+```
+
+> [!NOTE]
+> Windows doesn't have the dependencies we need in a package manager, therefore
+> `node-gtk` ships prebuilt versions of GTK 4 / Adwaita, so `npm install node-gtk`
+> is all you need **if** your dependency is in our 
+> [list of prebuilt libraries](./windows/runtime-libraries.txt).
 
 ### build from source
 
-Building from source, or contributing? See [Building from source](./doc/building.md).
+Building from source, or [contributing](./doc/contributing.md)? See [Building from source](./doc/building.md).
 
-## Contributing
+## Documentation
+
+[Read our documentation here](./doc/index.md)
+
+## Other notes
 
-If you'd like to help, we'd be more than happy to have support. To setup your development environment, you can
-run `npm run configure`. You can then build the project with `npm run build`. To generate the `compile_commands.json`
-for LSP to work nicely, you can use [bear](https://github.com/rizsotto/Bear) as `bear -- npm run build`.
+`node-gtk` is a [gobject-introspection](https://gi.readthedocs.io/en/latest) library 
+for nodejs. It makes it possible to use any introspected C library, such as GTK, 
+usable. It is similar in essence to [GJS](https://wiki.gnome.org/action/show/Projects/Gjs) 
+or [PyGObject](https://pygobject.readthedocs.io).
 
-- https://developer.gnome.org/gi/stable/index.html
-- https://v8docs.nodesource.com/
-- https://github.com/nodejs/nan#api
+[MIT License](./LICENSE)

package/bin/node-gtk.js

@@ -4,6 +4,8 @@
  *
  * Subcommands:
  *   generate-types   Generate TypeScript declarations from the installed typelibs.
+ *   create           Create a new GTK/Adwaita application.
+ *   list             List the GObject-Introspection libraries available locally.
  */
 
 const cmd = process.argv[2]
@@ -12,6 +14,13 @@ switch (cmd) {
   case 'generate-types':
     require('../tools/generate-types.js').run(process.argv.slice(3))
     break
+  case 'create':
+    require('../tools/create-app.js').run(process.argv.slice(3))
+    break
+  case 'list':
+  case 'list-libraries':
+    require('../tools/list-libraries.js').run(process.argv.slice(3))
+    break
   case undefined:
   case '-h':
   case '--help':
@@ -20,9 +29,11 @@ switch (cmd) {
 Usage: node-gtk <command> [options]
 
 Commands:
+  create <directory>                         Create a new GTK/Adwaita app
   generate-types <Namespace-Version> [...]   Generate TypeScript types (.d.ts)
+  list [filter]                              List available libraries & versions
 
-Run \`node-gtk generate-types --help\` for details.`)
+Run \`node-gtk <command> --help\` for details.`)
     process.exit(cmd ? 0 : 1)
     break
   default:

package/binding.gyp

@@ -1,4 +1,24 @@
 {
+    # Node 26's official Windows binary is built with ClangCL + ThinLTO, so its
+    # common.gypi injects `-flto=thin` and `/opt:lldltojobs=N` into the MSVC
+    # AdditionalOptions of every target. MSVC's link.exe rejects those
+    # Clang/lld-only options (LNK1117), which breaks the build on Windows +
+    # Node 26. Strip them with gyp's list-exclusion filter. This lives under
+    # msvs_settings, so it is inert on the make/xcode generators (Linux/macOS).
+    "target_defaults": {
+        "configurations": {
+            "Release": {
+                "msvs_settings": {
+                    "VCCLCompilerTool": {
+                        "AdditionalOptions/": [ ["exclude", "flto"] ]
+                    },
+                    "VCLinkerTool": {
+                        "AdditionalOptions/": [ ["exclude", "flto"], ["exclude", "lldltojobs"] ]
+                    }
+                }
+            }
+        }
+    },
     "targets": [
         {
             "target_name": "node_gtk",
@@ -11,6 +31,7 @@
                 "src/debug.cc",
                 "src/error.cc",
                 "src/function.cc",
+                "src/fundamental.cc",
                 "src/gi.cc",
                 "src/gobject.cc",
                 "src/loop.cc",

package/lib/bootstrap.js

@@ -292,23 +292,55 @@ function makeObject(info) {
    */
 
   forLoopFn(info, GI.object_info_get_n_interfaces, GI.object_info_get_interface, (interfaceInfo) => {
-    const interface_ = getInterface(interfaceInfo)
-
-    interface_._properties.forEach(description => {
-      define(constructor, description)
-    })
-    interface_._methods.forEach(description => {
-      define(constructor, description)
-    })
-    interface_._constants.forEach(description => {
-      define(constructor, description)
-    })
+    applyInterface(constructor, getInterface(interfaceInfo))
   })
 
 
   return constructor;
 }
 
+/*
+ * Mix an interface's properties/methods/constants (as prepared by
+ * makeInterface) into a class constructor. Shared by makeObject() and the
+ * `applyInterfaceMethods` callback below.
+ */
+function applyInterface(constructor, interface_) {
+  interface_._properties.forEach(description => define(constructor, description))
+  interface_._methods.forEach(description => define(constructor, description))
+  interface_._constants.forEach(description => define(constructor, description))
+}
+
+/*
+ * Called from C++ (GetClassTemplate) the first time a private/non-introspectable
+ * concrete type is wrapped, to install the methods of the interfaces it
+ * implements onto its prototype. makeObject() never runs for such types, so
+ * without this their instances would only expose the base GObject methods
+ * (issue #441). `interfaceRefs` is an array of { namespace, name }.
+ */
+function applyInterfaceMethods(constructor, interfaceRefs) {
+  const repo = GI.Repository_get_default()
+
+  interfaceRefs.forEach(({ namespace, name }) => {
+    const cache = moduleCache[namespace]
+    // The interface's module must be loaded for its constructor to exist; if it
+    // isn't, there is nothing meaningful to install.
+    if (!cache)
+      return
+
+    let interface_ = cache[name]
+    if (!interface_) {
+      const info = GI.Repository_find_by_name.call(repo, namespace, name)
+      if (!info)
+        return
+      interface_ = getInterface(info)
+    }
+
+    applyInterface(constructor, interface_)
+  })
+}
+
+internal.SetInterfaceMethodsApplier(applyInterfaceMethods)
+
 function makeBoxed(info) {
   if (getType(info) == GI.InfoType.UNION) {
     return makeUnion(info)

package/lib/esm/hooks.mjs

@@ -0,0 +1,49 @@
+/*
+ * hooks.mjs — Node.js ESM module-customization hooks for the `gi:` scheme.
+ *
+ * Enables `import Gtk from 'gi:Gtk-4.0'`, where the default export is the
+ * namespace object returned by node-gtk's `gi.require('Gtk', '4.0')`. Members are
+ * read off that object: `const { Box, Label } = Gtk`.
+ *
+ * Install them with `node --import node-gtk/register app.mjs` (see register.mjs).
+ *
+ * The hooks run on a separate loader thread, so they do NO native work: `load`
+ * only emits a tiny synthetic ES module whose body calls `gi.require` on the
+ * main thread when the module is evaluated. Requires Node >= 20.6 (module.register).
+ */
+
+const PREFIX = 'gi:'
+
+/* Absolute file:// URL to lib/index.js, embedded into the generated source. The
+ * synthetic module's parent URL is the schemeless `gi:` URL, which has no
+ * filesystem base, so a bare `import 'node-gtk'` could not be resolved from it —
+ * the absolute URL sidesteps resolution entirely. */
+const INDEX_URL = new URL('../index.js', import.meta.url).href
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier.startsWith(PREFIX))
+    return { url: specifier, shortCircuit: true }
+  return nextResolve(specifier, context)
+}
+
+export async function load(url, context, nextLoad) {
+  if (!url.startsWith(PREFIX))
+    return nextLoad(url, context)
+
+  // `gi:Gtk-4.0` -> ('Gtk', '4.0'); `gi:Adw-1` -> ('Adw', '1'); `gi:cairo` -> ('cairo', null).
+  // Split on the first '-' only: GI namespace names never contain '-', versions may.
+  const spec = url.slice(PREFIX.length)
+  const dash = spec.indexOf('-')
+  const name = dash === -1 ? spec : spec.slice(0, dash)
+  const version = dash === -1 ? null : spec.slice(dash + 1)
+
+  const call = version === null
+    ? `gi.require(${JSON.stringify(name)})`
+    : `gi.require(${JSON.stringify(name)}, ${JSON.stringify(version)})`
+
+  const source =
+    `import gi from ${JSON.stringify(INDEX_URL)};\n` +
+    `export default ${call};\n`
+
+  return { format: 'module', shortCircuit: true, source }
+}

package/lib/esm/register.mjs

@@ -0,0 +1,17 @@
+/*
+ * register.mjs — install the `gi:` import hooks.
+ *
+ * Usage:  node --import node-gtk/register app.mjs
+ *
+ * Then, in app.mjs:
+ *     import Gtk from 'gi:Gtk-4.0'
+ *     const { Box, Label } = Gtk
+ *
+ * Note: hooks only affect imports evaluated *after* registration. To use a static
+ * `import ... from 'gi:...'` in your entry module, register via the `--import`
+ * flag above (not a programmatic `import 'node-gtk/register'` in that same file).
+ */
+
+import { register } from 'node:module'
+
+register(new URL('./hooks.mjs', import.meta.url))

package/lib/index.js

@@ -8,7 +8,7 @@ const moduleCache = internal.GetModuleCache()
 // Must be loaded first, to setup the GI functions
 const bootstrap = require('./bootstrap.js')
 const module_ = require('./module.js')
-const loop = require('./loop.js')
+require('./loop.js') // installs the automatic main-loop integration
 const registerClass = require('./register-class.js')
 
 /**
@@ -42,7 +42,6 @@ function getGType(value) {
 module.exports = {
   // Public API
   ...module_,
-  startLoop: loop.start,
   registerClass: registerClass,
   getGType: getGType,
   System: internal.System,

package/lib/index.mjs

@@ -0,0 +1,25 @@
+/*
+ * index.mjs
+ *
+ * ESM facade over the CommonJS entry (index.js), so that named imports work:
+ *
+ *     import gi, { require, registerClass } from 'node-gtk'
+ *
+ * Node's CommonJS-to-ESM named-export detection (cjs-module-lexer) cannot see
+ * through index.js's computed `module.exports`, so we re-export explicitly here.
+ * Both this file and `require('node-gtk')` share the same underlying index.js
+ * instance (Node caches it by path), so there is no duplicated state.
+ */
+
+import gi from './index.js'
+
+export default gi
+
+export const require = gi.require
+export const isLoaded = gi.isLoaded
+export const prependSearchPath = gi.prependSearchPath
+export const prependLibraryPath = gi.prependLibraryPath
+export const listAvailableModules = gi.listAvailableModules
+export const registerClass = gi.registerClass
+export const getGType = gi.getGType
+export const System = gi.System

package/lib/inspect.js

@@ -3,7 +3,7 @@ const chalk = require('chalk')
 
 const internal = require('./native.js')
 const gi = require('../lib/index');
-gi.startLoop();
+require('./loop.js').start();
 
 const infos = []
 

package/lib/loop.js

@@ -58,6 +58,11 @@ function start() {
  * @returns {*} the native return value, or undefined when deferred
  */
 function runLoopEntry(run) {
+  // The loop integration must be active before we block in a native main loop,
+  // so start it automatically on the first run. Calling startLoop() explicitly
+  // still works and is no longer required (start() is idempotent).
+  start()
+
   if (internal.IsRunningMicrotasks()) {
     setImmediate(run)
     return undefined

package/lib/module.js

@@ -129,6 +129,12 @@ function listAvailableModules() {
 // Helpers
 
 function parseModuleFilename(filename) {
-  const [name, version] = filename.replace('.typelib', '').split('-')
-  return { name, version }
+  // Typelibs are named `Name-Version.typelib`; the version is the trailing
+  // `-X.Y`, so split on the LAST dash — namespaces themselves may contain dashes
+  // (e.g. `GUPnP-DLNA-2.0` -> name `GUPnP-DLNA`, version `2.0`).
+  const base = filename.replace(/\.typelib$/, '')
+  const dash = base.lastIndexOf('-')
+  if (dash === -1)
+    return { name: base, version: '' }
+  return { name: base.slice(0, dash), version: base.slice(dash + 1) }
 }

package/lib/overrides/Gtk-4.0.js

@@ -2,10 +2,6 @@
  * Gtk-4.0.js
  */
 
-const internal = require('../native.js')
-const Module = require('../module')
-const Gio = Module.require('Gio')
-
 exports.apply = (Gtk) => {
 
   Gtk.EVENT_CONTINUE = false
@@ -104,29 +100,12 @@ exports.apply = (Gtk) => {
     return tickId
   }
 
-  const originalGetFile = Gtk.FileChooser.prototype.getFile
-
-  /**
-   * Gtk.FileChooserDialog.prototype.getFile
-   * @returns {GFile} - The file
-   */
-  Gtk.FileChooserDialog.prototype.getFile = function getFile() {
-    const file = originalGetFile.call(this)
-    if (file)
-      file.__proto__= Gio.File.prototype
-    return file
-  }
-
-  /**
-   * Gtk.FileChooserWidget.prototype.getFile
-   * @returns {GFile} - The file
-   */
-  Gtk.FileChooserWidget.prototype.getFile = function getFile() {
-    const file = originalGetFile.call(this)
-    if (file)
-      file.__proto__= Gio.File.prototype
-    return file
-  }
+  /* getFile() used to need a manual `file.__proto__ = Gio.File.prototype` fixup
+   * because the returned GLocalFile is a private type whose GFile interface
+   * methods weren't mixed into its prototype. That is now handled generically
+   * for every private type at wrap time (see issue #441), so the override is no
+   * longer necessary — the introspected getFile() returns a fully-usable file
+   * (or null when nothing is selected). */
 }
 
 function easeOutCubic(t) {