node-gtk 2.1.0 → 3.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>
@@ -10,191 +10,91 @@
 
 <h1 align="center">node-gtk</h1>
 <p align="center">
-  <b>GNOME Gtk+ bindings for NodeJS</b>
+  <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 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 _beta_ state and is being developed. Any contributors willing to help
-will be welcomed.
-
-Supported Node.js versions: **20**, **22**, **24** (other versions may work but are untested)<br>
-Pre-built binaries available for: **Linux**, **macOS**
-
-### Table of contents
-
-- [Usage](#usage)
-- [Documentation](#documentation)
-- [TypeScript](#typescript)
-- [Installing and building](#installing-and-building)
-- [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 }));
+<p align="center">
+  <a href="#usage">Usage</a> · <a href="#installing">Installing</a> · <a href="./doc/index.md">Documentation</a> · <a href="#contributing">Contributing</a>
+</p>
 
-  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();
+<br />
 
-  gi.startLoop();
-  loop.run();
-});
-
-process.exit(app.run([]));
-```
+`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 **20**, **22** and **24**.
 
 <p align="center">
-  <img src="./img/hello-world.png" style="width: 290px; 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 example above is CommonJS. node-gtk also works under ES modules, but with one
-behavioral difference around the blocking main-loop calls (`GLib.MainLoop.run`,
-`Gio`/`Gtk.Application.run`, `Gtk.main`).
-
-Under ESM, a module's top-level body runs as a V8 *microtask*. If a blocking
-loop call ran synchronously from there, it would nest inside V8's microtask
-drain and starve every `Promise`/`async` continuation (so `await fetch(...)`,
-`fs/promises`, etc. would never settle) for the entire lifetime of the loop —
-see [#442](https://github.com/romgrk/node-gtk/issues/442). To avoid this,
-node-gtk defers the blocking call to the next event-loop tick when it detects it
-is being invoked from within a microtask. Two consequences for ESM code:
-
-- The run call **returns immediately** instead of blocking until quit, so any
-  code placed *after* it executes *before* the loop. Make the run call the last
-  statement, and do cleanup/exit from your quit/`close-request` handler.
-- Its **return value is not available** (e.g. the application's exit status), so
-  don't wrap it like `process.exit(app.run([]))` — call `app.run([])` on its own
-  and exit from the handler instead.
-
-Under CommonJS (and inside signal callbacks) nothing changes: the run calls block
-synchronously and return their value exactly as before.
-
-> **Design note (may be reconsidered).** Two approaches were considered for #442:
->
-> - **Transparent auto-defer (chosen).** node-gtk detects the microtask context
->   and defers the blocking call automatically, so existing ESM code keeps
->   working with no changes. The cost is the leaky behavior above: under ESM the
->   run call no longer blocks, which is surprising and silently breaks idioms
->   like `process.exit(app.run([]))`.
-> - **Explicit async API (alternative).** Keep the blocking calls strictly
->   synchronous and add awaitable variants (e.g. `await loop.runAsync()`),
->   leaving ESM users to opt in. This has clean, predictable semantics and no
->   hidden return-immediately behavior, but it does *not* transparently fix
->   existing ESM code — users must change their code, and plain `loop.run()`
->   would still starve microtasks under ESM (or would need to throw/warn).
->
-> The transparent approach was chosen to fix existing code out of the box, but
-> given the leaky semantics this trade-off may be revisited — possibly moving to
-> (or also offering) the explicit async API.
-
-You can also easily create custom applications:
-
-[A web browser (using WebKit2GTK)](./examples/browser.js)
+## Usage
 
-<p align="center">
-  <img src="./img/browser.png" style="max-width: 500px; height: auto;"/>
-</p>
+The **create** tool generates a complete, ready-to-run GTK/Adwaita project, so you
+can start building immediately after [installing GTK4](#installing):
 
-[A system monitor](./examples/system-monitor.js)
+```sh
+npx node-gtk create <your-app>
+```
 
 <p align="center">
-  <img src="./img/system-monitor.png" style="width: 400px; height: auto;"/>
+  <img src="./img/create-app-example.png" style="width: 500px; height: auto;"/>
 </p>
 
-#### Other projects
+Also see our [hello world](./examples/hello-world.mjs), [web browser](./examples/browser.mjs)
+or [system monitor](./examples/system-monitor.mjs) examples.
 
-The [react-gtk](https://github.com/codejamninja/react-gtk) project may also allow you to use GTK via React (unmaintained).
+## Installing
 
-## Documentation
+There are two steps:
 
-[Read our documentation here](./doc/index.md)
-
-## TypeScript
+1. Install `node-gtk` itself (*done by the create tool*)
+2. Install the native libraries you use (see examples per platform below)
 
-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.).
+#### Linux
 
 ```sh
-# generates ./node_modules/.node-gtk-types (a hidden, git-ignored cache)
-npx node-gtk generate-types Gtk-4.0 Adw-1
-```
+# archlinux
+pacman -S gtk4 libadwaita
 
-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:
+# fedora
+dnf install gtk4 libadwaita
 
-```jsonc
-{
-  "compilerOptions": {
-    "moduleResolution": "node16",
-    "paths": { "node-gtk": ["./node_modules/.node-gtk-types/node-gtk.d.ts"] }
-  }
-}
+# ubuntu
+# Already installed :)
 ```
 
-Then `gi.require` is fully typed — the namespace is inferred from the string
-arguments:
+#### macOS
 
-```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
+```sh
+brew install gtk4 libadwaita adwaita-icon-theme
 ```
 
-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.
+#### Windows
 
-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" } }
+```sh
+# Already installed :)
 ```
 
-Run `npx node-gtk generate-types --help` for options.
+> [!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).
 
-## Installing and building
+### build from source
 
-See [Installing & building](./doc/installation.md) for prebuilt-binary notes, per-platform build instructions (Linux, macOS, Windows), and how to run the tests and examples.
+Building from source, or [contributing](./doc/contributing.md)? See [Building from source](./doc/building.md).
 
-## Contributing
+## Documentation
+
+[Read our documentation here](./doc/index.md)
 
-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`.
+## Other notes
 
-- https://developer.gnome.org/gi/stable/index.html
-- https://v8docs.nodesource.com/
-- https://github.com/nodejs/nan#api
+`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).
 
-There is a [Discord channel](https://discord.gg/r2VqPUV) but it receives little monitoring, use github issues or
-discussions preferably.
+[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/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/native.js

@@ -4,10 +4,61 @@
 
 const binary = require('@mapbox/node-pre-gyp')
 const path = require('path')
+const fs = require('fs')
 
 const packagePath = path.resolve(path.join(__dirname,'../package.json'))
 const bindingPath = binary.find(packagePath)
 
+// On Windows, the prebuilt binary ships with its whole GTK runtime bundled in
+// the same directory as the .node (DLLs, GObject-Introspection typelibs, and
+// runtime data). Wire the process environment to that bundle BEFORE the addon
+// is loaded, so a plain `npm install node-gtk` works with no MSYS2, no compiler
+// and no manual PATH setup. Done in this file specifically because it must run
+// before `require(bindingPath)` (the addon's DLL imports are resolved at load
+// time) and before bootstrap.js requires the GIRepository typelib.
+if (process.platform === 'win32')
+  setupBundledRuntime(path.dirname(bindingPath))
+
+function setupBundledRuntime(bundleDir) {
+  // A self-contained prebuilt always bundles its typelibs; if that marker is
+  // absent the addon was built from source against a system GTK, so leave the
+  // environment alone.
+  const typelibDir = path.join(bundleDir, 'girepository-1.0')
+  if (!fs.existsSync(typelibDir))
+    return
+
+  const prepend = (name, value) => {
+    const cur = process.env[name]
+    process.env[name] = cur ? value + path.delimiter + cur : value
+  }
+  const exists = p => { try { return fs.existsSync(p) } catch (e) { return false } }
+
+  // 1) DLLs — both the addon's own imports and the namespace shared libraries
+  //    GObject-Introspection loads at runtime via g_module_open().
+  prepend('PATH', bundleDir)
+
+  // 2) GI typelibs.
+  prepend('GI_TYPELIB_PATH', typelibDir)
+
+  // 3) Runtime data: icon themes, GtkSourceView languages/styles, schemas.
+  const share = path.join(bundleDir, 'share')
+  if (exists(share))
+    prepend('XDG_DATA_DIRS', share)
+  const schemas = path.join(share, 'glib-2.0', 'schemas')
+  if (exists(schemas) && !process.env.GSETTINGS_SCHEMA_DIR)
+    process.env.GSETTINGS_SCHEMA_DIR = schemas
+
+  // 4) gdk-pixbuf image loaders (made path-portable at bundle time). The
+  //    loaders dir goes on PATH so g_module_open() of a bare loader name from
+  //    the cache resolves.
+  const loadersDir = path.join(bundleDir, 'lib', 'gdk-pixbuf-2.0', '2.10.0', 'loaders')
+  if (exists(loadersDir))
+    prepend('PATH', loadersDir)
+  const loaderCache = path.join(bundleDir, 'lib', 'gdk-pixbuf-2.0', '2.10.0', 'loaders.cache')
+  if (exists(loaderCache) && !process.env.GDK_PIXBUF_MODULE_FILE)
+    process.env.GDK_PIXBUF_MODULE_FILE = loaderCache
+}
+
 const binding = require(bindingPath)
 
 module.exports = binding

package/lib/register-class.js

@@ -11,17 +11,50 @@ const GObject = module_.require('GObject')
 
 module.exports = registerClass
 
+// Make registerClass() optional: the first `new Subclass()` of an unregistered
+// JS subclass lazily registers it through this hook (see GObjectConstructor in
+// src/gobject.cc). registerClass() stays available for callers that need the
+// GType before constructing (e.g. getGType, GtkBuilder templates).
+internal.SetLazyClassRegister(registerClass)
+
+// A registered class owns its `__gtype__` (native classes via the prototype
+// template, JS classes via registerClass below); an unregistered subclass only
+// inherits one. Used to make registration idempotent and to find ancestors that
+// still need registering.
+function isRegistered(klass) {
+  return Object.prototype.hasOwnProperty.call(klass.prototype, '__gtype__')
+}
+
 /**
- * Create a new GObject type
+ * Create a new GObject type.
+ *
+ * To override a virtual function, define a method named `virtual_` + the
+ * camelCase vfunc name (e.g. `virtual_sizeAllocate` overrides
+ * `size_allocate`, `virtual_getRequestMode` overrides `get_request_mode`).
+ * Only `virtual_*`-prefixed methods are wired into the vtable; plain methods are
+ * never treated as overrides. Chain up to the parent implementation with
+ * `super.virtual_sizeAllocate(...)`. See doc/index.md "Inheritance".
+ *
  * @param {Class} klass - The class to register
  * @param {string} [klass.GTypeName] - The name of the GType (klass.name by default)
+ * @returns {Class} the same class (so it can be assigned or used as a decorator)
  */
 function registerClass(klass) {
+  // Idempotent: a class that already owns a GType is registered. This also makes
+  // the lazy-on-first-construct path a no-op for explicitly-registered classes.
+  if (isRegistered(klass))
+    return klass
+
   const parent = Object.getPrototypeOf(klass.prototype).constructor
 
   if (!(klass.prototype instanceof GObject.Object))
     throw new Error(`Invalid base class (${parent.name})`)
 
+  // Register any unregistered ancestor first, so a subclass can be constructed
+  // (or registered) without its superclass having been registered by hand.
+  if (!isRegistered(parent))
+    registerClass(parent)
+
   const name = createGTypeName(klass)
   const gtype = GObject.typeFromName(name)
   const parentName = getGTypeName(parent)
@@ -41,26 +74,51 @@ function registerClass(klass) {
 
   // Setup virtual functions
   setupVirtualFunctions(klass, klassGtype, parentGtype)
+
+  return klass
 }
 
 // Helpers
 
+/* Methods whose name starts with `virtual_` are treated as virtual-function
+ * overrides — and *only* those. This makes overriding explicit and opt-in: a
+ * plain method named `dispose`, `getProperty`, `sizeAllocate`, … can no longer
+ * silently hijack the matching GObject vfunc (issue #457). The prefix also keeps
+ * the override name distinct from the public invoker method of the same vfunc
+ * (e.g. `widget.sizeAllocate(...)` the method vs. the `virtual_sizeAllocate`
+ * override), so the two no longer collide. */
+const VIRTUAL_PREFIX = /^virtual_/
+
+/* `virtual_getRequestMode` -> `get_request_mode` (drop the prefix, snake_case the
+ * rest). snakeCase('virtual_getRequestMode') === 'virtual_get_request_mode'. */
+function vfuncNativeName(key) {
+  return snakeCase(key).replace(/^virtual_/, '')
+}
+
 function setupVirtualFunctions(klass, klassGtype, parentGtype) {
   const parentInfo = findInfoByGtype(parentGtype)
   if (!parentInfo)
     throw new Error(`Could not find GIR data in inheritance chain`)
 
+  const parentPrototype = Object.getPrototypeOf(klass.prototype)
+
   Object.getOwnPropertyNames(klass.prototype).forEach(key => {
     if (key === 'constructor')
       return
+    if (!VIRTUAL_PREFIX.test(key))
+      return
     if (typeof klass.prototype[key] !== 'function')
       return
 
-    const nativeName = snakeCase(key)
+    const nativeName = vfuncNativeName(key)
     const vfuncInfo = findVFunc(klassGtype, parentInfo, nativeName)
 
     if (!vfuncInfo)
-     return
+      throw new Error(
+        `${klass.name}.${key}: no virtual function '${nativeName}' on ` +
+        `'${GObject.typeName(parentGtype)}' or its interfaces. A 'virtual_*' ` +
+        `method must name an existing vfunc (e.g. 'virtual_sizeAllocate' for ` +
+        `'size_allocate'); rename it if it is a plain method.`)
 
     internal.RegisterVFunc(
       vfuncInfo,
@@ -68,6 +126,31 @@ function setupVirtualFunctions(klass, klassGtype, parentGtype) {
       nativeName,
       klass.prototype[key]
     )
+
+    installParentVFunc(parentPrototype, parentGtype, key, vfuncInfo)
+  })
+}
+
+/* Make `super.<vfunc>(...)` reachable from an override. The override replaces
+ * the parent's implementation in the class vtable, so a JS subclass otherwise
+ * has no way to call the implementation it overrode. We install, on the parent
+ * GI class's prototype, a method that invokes the *parent's* native vfunc impl
+ * (resolved through `parentGtype`'s vtable, not the overriding subclass's).
+ *
+ * Only the native boundary needs bridging: if the parent prototype already owns
+ * `key` — i.e. the parent is itself a registered JS class that overrode this
+ * vfunc — then `super.<vfunc>()` resolves to that JS method on its own. */
+function installParentVFunc(parentPrototype, parentGtype, key, vfuncInfo) {
+  if (Object.prototype.hasOwnProperty.call(parentPrototype, key))
+    return
+
+  Object.defineProperty(parentPrototype, key, {
+    value: function (...args) {
+      return internal.CallVFunc(vfuncInfo, parentGtype, this, args)
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false,
   })
 }