node-gtk 2.1.0 → 3.0.0

package/src/gobject.cc

@@ -1,6 +1,8 @@
 
 #include <string.h>
 
+#include <vector>
+
 #include "boxed.h"
 #include "callback.h"
 #include "closure.h"
@@ -33,6 +35,11 @@ namespace GNodeJS {
 // Our base template for all GObjects
 static Nan::Persistent<FunctionTemplate> baseTemplate;
 
+// JS callback (registerClass) invoked to lazily register an unregistered JS
+// subclass the first time it is constructed. Installed via SetLazyClassRegister,
+// this makes registerClass() optional. Empty until JS installs it.
+static Nan::Persistent<Function> lazyClassRegister;
+
 
 static MaybeLocal<FunctionTemplate> GetClassTemplate(GType gtype);
 static MaybeLocal<Function>         GetClass(GType gtype);
@@ -219,11 +226,34 @@ static void GObjectConstructor(const FunctionCallbackInfo<Value> &info) {
 
     /* User code calling `new Gtk.Widget({ ... })` */
 
+    Local<Object> proto = Nan::To<Object>(self->GetPrototype()).ToLocalChecked();
+
+    /* A JS subclass (`class Foo extends Gtk.Widget {}`) that was never passed to
+     * registerClass() owns no GType: `__gtype__` is only *inherited* from its
+     * nearest registered ancestor, so constructing it as-is would silently
+     * instantiate that ancestor — losing the subtype and any vfunc overrides.
+     * Detect the missing *own* property and register the subclass on demand,
+     * which is what makes registerClass() optional. The JS callback installs an
+     * own `__gtype__` on `proto`, so the lookup below resolves to the
+     * freshly-registered subtype. */
+    if (!lazyClassRegister.IsEmpty()
+            && !Nan::HasOwnProperty(proto, UTF8("__gtype__")).FromMaybe(true)) {
+        Local<Function> registerFn = Nan::New<Function>(lazyClassRegister);
+        Local<Value> klass = Nan::Get(proto, UTF8("constructor")).ToLocalChecked();
+        Local<Value> argv[] = { klass };
+        Nan::TryCatch tryCatch;
+        Nan::Call(registerFn, Nan::GetCurrentContext()->Global(), 1, argv);
+        if (tryCatch.HasCaught()) {
+            tryCatch.ReThrow();
+            return;
+        }
+    }
+
     // FIXME: getting the gtype from the External is faster but doesn't
     // work for dynamically-registered types. Check if we can find something
     // better.
     //gtype = (GType) External::Cast(*info.Data())->Value();
-    gtype = GET_OBJECT_GTYPE (Nan::To<Object>(self->GetPrototype()).ToLocalChecked());
+    gtype = GET_OBJECT_GTYPE (proto);
 
     gobject = CreateGObjectFromObject (gtype, info[0]);
 
@@ -458,6 +488,61 @@ static void DestroyVFuncs(GType gtype) {
     g_type_set_qdata (gtype, GNodeJS::vfuncs_quark(), NULL);
 }
 
+/*
+ * Signal handlers are stored in a JS array held on the wrapper object itself
+ * (via a private symbol), so they are reachable only through the wrapper and
+ * the wrapper <-> handler reference loop can be garbage-collected (#375; see
+ * doc/signal-handler-gc.md). A Closure keeps only its index into that array.
+ */
+static Local<v8::Private> SignalHandlersKey(v8::Isolate *isolate) {
+    return v8::Private::ForApi(isolate, Nan::New("__gnodejs_signal_handlers__").ToLocalChecked());
+}
+
+// Append a handler to the wrapper's handler array, returning its index.
+static guint AddSignalHandler(Local<Object> wrapper, Local<Function> handler) {
+    v8::Isolate *isolate = wrapper->GetIsolate();
+    Local<v8::Context> context = isolate->GetCurrentContext();
+    Local<v8::Private> key = SignalHandlersKey(isolate);
+
+    Local<Value> existing = wrapper->GetPrivate(context, key).ToLocalChecked();
+    Local<Array> handlers;
+    if (existing->IsArray()) {
+        handlers = existing.As<Array>();
+    } else {
+        handlers = Nan::New<Array>();
+        wrapper->SetPrivate(context, key, handlers).Check();
+    }
+
+    guint index = handlers->Length();
+    Nan::Set(handlers, index, handler);
+    return index;
+}
+
+// Look up a handler by the instance it is connected to and its index. Returns
+// an empty handle if the wrapper has been collected or the slot is empty.
+Local<Value> GetSignalHandler(GObject *gobject, guint index) {
+    void *data = g_object_get_qdata (gobject, GNodeJS::object_quark());
+    if (data == NULL)
+        return Local<Value>();
+
+    auto *wrapper = (GObjectWrapper *) data;
+    if (wrapper->collected)
+        return Local<Value>();
+
+    Local<Object> object = Nan::New(wrapper->persistent);
+    if (object.IsEmpty())
+        return Local<Value>();
+
+    v8::Isolate *isolate = object->GetIsolate();
+    Local<v8::Context> context = isolate->GetCurrentContext();
+    Local<Value> handlers =
+        object->GetPrivate(context, SignalHandlersKey(isolate)).ToLocalChecked();
+    if (!handlers->IsArray())
+        return Local<Value>();
+
+    return Nan::Get(handlers.As<Array>(), index).ToLocalChecked();
+}
+
 NAN_METHOD(SignalConnect) {
     bool after = false;
 
@@ -490,9 +575,14 @@ NAN_METHOD(SignalConnect) {
     guint signalId;
     GQuark detail;
     GClosure *gclosure;
+    guint handlerIndex;
     gulong handler_id;
 
-    const char *signalName = *Nan::Utf8String (TO_STRING (info[0]));
+    // Hold the Utf8String for the whole function: `*Nan::Utf8String(...)` alone
+    // dangles after the statement, and AddSignalHandler() below allocates in V8,
+    // which would clobber the freed buffer before g_signal_connect_closure.
+    Nan::Utf8String signalNameValue (TO_STRING (info[0]));
+    const char *signalName = *signalNameValue;
     if (!g_signal_parse_name(signalName, gtype, &signalId, &detail, FALSE)) {
         Nan::ThrowTypeError("Signal name is invalid");
         return;
@@ -506,7 +596,8 @@ NAN_METHOD(SignalConnect) {
         }
     }
 
-    gclosure = Closure::New (callback, signal_info, signalId);
+    handlerIndex = AddSignalHandler (TO_OBJECT (info.This ()), callback);
+    gclosure = Closure::New (handlerIndex, signal_info, signalId);
     handler_id = g_signal_connect_closure (gobject, signalName, gclosure, after);
 
     info.GetReturnValue().Set((double)handler_id);
@@ -964,6 +1055,10 @@ out:
 }
 
 
+NAN_METHOD(SetLazyClassRegister) {
+    lazyClassRegister.Reset(info[0].As<Function>());
+}
+
 NAN_METHOD(RegisterClass) {
     auto jsKlassName  = Nan::To<String>(info[0]).ToLocalChecked();
     auto jsKlass      = info[1].As<Object>();
@@ -1034,6 +1129,78 @@ NAN_METHOD(RegisterVFunc) {
     return;
 }
 
+/*
+ * Invoke a parent class's implementation of a vfunc — the native half of
+ * `super.<vfunc>(...)`. JS args: (vfuncInfo, implementorGType, instance, argsArray).
+ *
+ * `g_vfunc_info_invoke` resolves the vfunc through `implementorGType`'s class
+ * vtable, so passing the *parent* GType runs the parent's implementation rather
+ * than the overriding subclass's (which is what `super` means). The instance is
+ * passed as in-arg 0, the JS args follow.
+ *
+ * Scope: in-only arguments + (void or simple) return value. Out/inout arguments
+ * are rejected rather than silently mishandled.
+ */
+NAN_METHOD(CallVFunc) {
+    auto jsVFuncInfo  = info[0].As<Object>();
+    auto jsImplGType  = info[1].As<BigInt>();
+    auto jsInstance   = info[2];
+    auto jsArgs       = info[3].As<Array>();
+
+    BaseInfo vfuncInfo(jsVFuncInfo);
+    GType implementor = jsImplGType->Uint64Value();
+
+    int n_callable = g_callable_info_get_n_args(*vfuncInfo);
+
+    GObject *instance = GObjectFromWrapper(jsInstance);
+    if (instance == NULL) {
+        // The wrapper has no associated GObject yet — e.g. chaining up to a
+        // construction-time vfunc (`constructed`), which fires inside g_object_new
+        // before node-gtk associates the JS wrapper with the GObject. There is no
+        // valid instance to invoke the parent on; fail loudly instead of crashing.
+        Throw::Error("Cannot chain up to parent vfunc '%s': instance has no GObject yet "
+                "(chaining up during construction is unsupported)",
+                g_base_info_get_name(*vfuncInfo));
+        return;
+    }
+
+    std::vector<GIArgument> in_args(n_callable + 1);
+    in_args[0].v_pointer = instance;
+
+    for (int i = 0; i < n_callable; i++) {
+        GIArgInfo arg_info;
+        GITypeInfo arg_type;
+        g_callable_info_load_arg(*vfuncInfo, i, &arg_info);
+        g_arg_info_load_type(&arg_info, &arg_type);
+
+        if (g_arg_info_get_direction(&arg_info) != GI_DIRECTION_IN) {
+            Throw::Error("Cannot chain up to parent vfunc '%s': out/inout argument %d is unsupported",
+                    g_base_info_get_name(*vfuncInfo), i);
+            return;
+        }
+
+        Local<Value> value = Nan::Get(jsArgs, i).ToLocalChecked();
+        bool may_be_null = g_arg_info_may_be_null(&arg_info);
+        V8ToGIArgument(&arg_type, &in_args[i + 1], value, may_be_null);
+    }
+
+    GIArgument return_value = {};
+    GError *error = NULL;
+    gboolean ok = g_vfunc_info_invoke(*vfuncInfo, implementor,
+            in_args.data(), n_callable + 1, NULL, 0, &return_value, &error);
+
+    if (!ok) {
+        Throw::GError("Failed to chain up to parent vfunc", error);
+        return;
+    }
+
+    GITypeInfo return_type;
+    g_callable_info_load_return_type(*vfuncInfo, &return_type);
+    if (g_type_info_get_tag(&return_type) != GI_TYPE_TAG_VOID) {
+        info.GetReturnValue().Set(GIArgumentToV8(&return_type, &return_value));
+    }
+}
+
 };
 
 };

package/src/gobject.h

@@ -18,14 +18,17 @@ namespace GNodeJS {
 MaybeLocal<Function>    MakeClass            (GIBaseInfo *info);
 Local<Value>            WrapperFromGObject   (GObject *object);
 GObject *               GObjectFromWrapper   (Local<Value> value);
+Local<Value>            GetSignalHandler     (GObject *gobject, guint index);
 Local<FunctionTemplate> GetBaseClassTemplate ();
 MaybeLocal<Value>       GetGObjectProperty   (GObject * gobject, const char *prop_name);
 MaybeLocal<v8::Boolean> SetGObjectProperty   (GObject * gobject, const char *prop_name, Local<Value> value);
 
 namespace ObjectClass {
 
+NAN_METHOD(SetLazyClassRegister);
 NAN_METHOD(RegisterClass);
 NAN_METHOD(RegisterVFunc);
+NAN_METHOD(CallVFunc);
 
 };
 

package/tools/README.md

@@ -45,7 +45,7 @@ script so it regenerates after install.
 - `bin/node-gtk.js` — CLI entry (`package.json` `"bin"`); dispatches `generate-types`.
 - `tools/generate-types.js` — the generator. `run(argv)` / `generate(roots, outdir)`.
 - `examples/ts-demo/` — `app.ts` (valid, typechecks clean) and `app-errors.ts`
-  (4 deliberate mistakes, all caught). Generate types into `.node-gtk-types/` first
+  (5 deliberate mistakes, all caught). Generate types into `.node-gtk-types/` first
   (see that dir's `.gitignore`).
 
 ## Verify the demo
@@ -54,7 +54,7 @@ script so it regenerates after install.
 node bin/node-gtk.js generate-types Gtk-4.0 --outdir examples/ts-demo/.node-gtk-types
 node_modules/.bin/tsc -p examples/ts-demo/tsconfig.json          # passes clean
 sed 's/app.ts/app-errors.ts/' examples/ts-demo/tsconfig.json > examples/ts-demo/tsconfig.errors.json
-node_modules/.bin/tsc -p examples/ts-demo/tsconfig.errors.json   # 4 errors caught
+node_modules/.bin/tsc -p examples/ts-demo/tsconfig.errors.json   # 5 errors caught
 ```
 
 ## Fidelity
@@ -68,6 +68,11 @@ type-check with **0 errors even without `skipLibCheck`**. Modelled faithfully:
 - 64-bit ints return `bigint` (full precision, #323/#149); params accept
   `number | bigint`.
 - Enum methods and interface constants emitted (declaration-merged).
+- Virtual functions emitted as the `virtual_*` override surface that
+  `registerClass` wires into the vtable (`virtual_sizeAllocate` overrides
+  `size_allocate`), including invoker-less lifecycle vfuncs (`virtual_dispose`,
+  `virtual_constructed`, …) so subclass overrides are type-checked and
+  `super.virtual_<name>()` chain-up resolves (issue #457).
 - GObject override conflicts reconciled as overloads, so subclass methods stay
   assignable to inherited ones; multiple-interface signal/method conflicts
   resolved with a unified, assignable-to-all declaration.
@@ -89,3 +94,48 @@ type-check with **0 errors even without `skipLibCheck`**. Modelled faithfully:
   (e.g. a gutter renderer's `activate(iter, …)` vs `GtkWidget.activate()`)
   requires the override to satisfy both signatures — an inherent consequence of
   the GObject API reusing a name, not specific to these types.
+- **`virtual_*` overrides with non-primitive OUT params** are typed with those
+  params in the return tuple (the public-method convention). At runtime a vfunc
+  implementation receives non-primitive OUT params as objects to mutate rather
+  than returning them; the common all-primitive case (e.g. `virtual_measure`)
+  matches exactly.
+- **Interface vfuncs are not emitted** (only object/class vfuncs). Emitting
+  `virtual_*` members on interfaces collides across multiple-interface diamonds
+  (e.g. GTK3's Atk accessibility stack → TS2320). Overriding an interface vfunc
+  still works at runtime; it just isn't type-checked.
+
+---
+
+# `node-gtk create` — create a new app
+
+`node-gtk create <directory>` creates a complete, ready-to-run GTK/Adwaita
+application that uses node-gtk, so a new project is one command away.
+
+```sh
+npx node-gtk create my-app
+cd my-app
+npm run dev
+```
+
+It generates a TypeScript + ESM project: an idiomatic Adwaita application plus its
+tooling — typed `gi:` imports (with `tsconfig` wired to the generated types) and
+npm scripts to run (`dev`/`start`), build (`build`), and regenerate types
+(`generate-types`, also run on `postinstall`).
+
+### Options
+
+```
+node-gtk create <directory> [options]
+
+  --name <name>      Human-facing app name (default: derived from <directory>)
+  --app-id <id>      Reverse-DNS application id (default: com.example.<Name>)
+  --no-install       Don't run `npm install` after creating the project
+  --force            Create into <directory> even if it exists and is non-empty
+  -h, --help         Show this help
+```
+
+The directory basename drives the defaults: `my-cool-app` →
+name *"My Cool App"*, package `my-cool-app`, id `com.example.MyCoolApp`.
+
+The command lives in `tools/create-app.js`; the generated files come from the
+template tree in `tools/templates/app/`.

package/tools/create-app.js

@@ -0,0 +1,246 @@
+/*
+ * create-app.js — create a new GTK/Adwaita application that uses node-gtk.
+ *
+ * Driven by the CLI: `node-gtk create <directory> [options]`.
+ * Copies the template tree in tools/templates/app/, substitutes a few tokens
+ * (app name, app id, package name, node-gtk version), and — unless --no-install
+ * is passed — runs `npm install` in the new directory (which in turn generates
+ * the TypeScript types via the project's postinstall script).
+ */
+
+const fs = require('fs')
+const path = require('path')
+const child_process = require('child_process')
+
+const TEMPLATE_DIR = path.join(__dirname, 'templates', 'app')
+
+// template file -> destination path (relative to the new project root).
+// Templates carry a `.tmpl` suffix so npm never rewrites `.gitignore` to
+// `.npmignore` and never treats a nested `package.json` as a real manifest.
+const FILES = [
+  ['package.json.tmpl', 'package.json'],
+  ['tsconfig.json.tmpl', 'tsconfig.json'],
+  ['gitignore.tmpl', '.gitignore'],
+  ['README.md.tmpl', 'README.md'],
+  ['style.css.tmpl', 'style.css'],
+  ['src/main.ts.tmpl', path.join('src', 'main.ts')],
+  ['src/welcome.ts.tmpl', path.join('src', 'welcome.ts')],
+]
+
+// ---------------------------------------------------------------------------
+// name derivation
+// ---------------------------------------------------------------------------
+
+// A human-facing title: "my-cool-app" / "my_cool_app" -> "My Cool App".
+function toAppName(base) {
+  return base
+    .replace(/[-_.\s]+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, (c) => c.toUpperCase()) || 'My App'
+}
+
+// A valid npm package name: lowercase, url-safe.
+function toPkgName(base) {
+  const name = base
+    .toLowerCase()
+    .replace(/[^a-z0-9-_.]+/g, '-')
+    .replace(/^[-_.]+|[-_.]+$/g, '')
+  return name || 'gtk-app'
+}
+
+// A reverse-DNS application id: "My Cool App" -> "com.example.MyCoolApp".
+function toAppId(appName) {
+  const suffix = appName
+    .replace(/[^A-Za-z0-9 ]+/g, '')
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join('') || 'App'
+  return `com.example.${suffix}`
+}
+
+// GApplication ids must look like reverse-DNS: 2+ dot-separated segments, each
+// starting with a letter, containing only [A-Za-z0-9_-] (and no trailing dot).
+function isValidAppId(id) {
+  return /^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z][A-Za-z0-9_-]*)+$/.test(id)
+}
+
+// The `node-gtk` dependency to write into the generated package.json.
+//
+// The created app uses the `gi:` import scheme and `node-gtk/register`, which
+// exist only in this node-gtk. When run from a normal install we depend on the
+// matching published version (`^x.y.z`). But when run from a *source checkout*
+// (a contributor testing `node bin/node-gtk.js create`), `^x.y.z` would resolve
+// to the published release — which may predate these features — so we instead
+// point the app at the local checkout via `file:`, so it uses the exact node-gtk
+// it was created with.
+function nodeGtkDependency() {
+  const repoRoot = path.resolve(__dirname, '..')
+  const version = require('../package.json').version
+  const isInstalled = repoRoot.split(path.sep).includes('node_modules')
+  return isInstalled ? `^${version}` : `file:${repoRoot}`
+}
+
+// ---------------------------------------------------------------------------
+// project creation (pure: writes files, never installs, never exits the process)
+// ---------------------------------------------------------------------------
+
+function createProject(opts) {
+  const { dir, appName, appId, pkgName, force = false } = opts
+
+  if (fs.existsSync(dir) && fs.readdirSync(dir).length > 0 && !force)
+    throw new Error(`target directory is not empty: ${dir}\nUse --force to write into it anyway.`)
+
+  const nodeGtkVersion = opts.nodeGtkVersion || nodeGtkDependency()
+  const tokens = {
+    __APP_NAME__: appName,
+    __APP_ID__: appId,
+    __PKG_NAME__: pkgName,
+    __NODE_GTK_VERSION__: nodeGtkVersion,
+  }
+  const substitute = (s) =>
+    s.replace(/__APP_NAME__|__APP_ID__|__PKG_NAME__|__NODE_GTK_VERSION__/g, (m) => tokens[m])
+
+  const written = []
+  for (const [src, dest] of FILES) {
+    const content = substitute(fs.readFileSync(path.join(TEMPLATE_DIR, src), 'utf8'))
+    const destPath = path.join(dir, dest)
+    fs.mkdirSync(path.dirname(destPath), { recursive: true })
+    fs.writeFileSync(destPath, content)
+    written.push(dest)
+  }
+  return written
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry
+// ---------------------------------------------------------------------------
+
+const HELP = `node-gtk create — create a GTK/Adwaita app that uses node-gtk
+
+Usage:
+  node-gtk create <directory> [options]
+
+Options:
+  --name <name>      Human-facing app name (default: derived from <directory>)
+  --app-id <id>      Reverse-DNS application id (default: com.example.<Name>)
+  --no-install       Don't run \`npm install\` after creating the project
+  --force            Create into <directory> even if it exists and is non-empty
+  -h, --help         Show this help
+
+Example:
+  node-gtk create my-app --name "My App" --app-id org.example.MyApp
+`
+
+function parseArgs(argv) {
+  const opts = { install: true, force: false }
+  const positional = []
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    switch (arg) {
+      case '-h': case '--help': opts.help = true; break
+      case '--no-install': opts.install = false; break
+      case '--force': opts.force = true; break
+      case '--name': opts.name = argv[++i]; break
+      case '--app-id': opts.appId = argv[++i]; break
+      default:
+        if (arg.startsWith('--name=')) opts.name = arg.slice('--name='.length)
+        else if (arg.startsWith('--app-id=')) opts.appId = arg.slice('--app-id='.length)
+        else if (arg.startsWith('-')) { opts.unknown = arg }
+        else positional.push(arg)
+    }
+  }
+  opts.dir = positional[0]
+  return opts
+}
+
+// Minimal ANSI styling (chalk is only a devDependency, so we can't use it at
+// runtime). No-ops when stdout isn't a TTY or NO_COLOR is set.
+const useColor = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
+const ansi = (open, close) => (s) => useColor ? `\x1b[${open}m${s}\x1b[${close}m` : s
+const bold = ansi(1, 22)
+const dim = ansi(2, 22)
+const cyan = ansi(36, 39)
+const green = ansi(32, 39)
+const yellow = ansi(33, 39)
+
+function run(argv) {
+  const opts = parseArgs(argv)
+
+  if (opts.help) { process.stdout.write(HELP); return }
+  if (opts.unknown) { process.stderr.write(`node-gtk create: unknown option '${opts.unknown}'\n\n${HELP}`); process.exit(1) }
+  if (!opts.dir) { process.stderr.write(`node-gtk create: missing <directory>\n\n${HELP}`); process.exit(1) }
+
+  const dir = path.resolve(opts.dir)
+  const base = path.basename(dir)
+  const appName = opts.name || toAppName(base)
+  const pkgName = toPkgName(base)
+  const appId = opts.appId || toAppId(appName)
+
+  if (!isValidAppId(appId)) {
+    process.stderr.write(`node-gtk create: invalid --app-id '${appId}'.\n` +
+      `It must be reverse-DNS, e.g. com.example.MyApp (2+ segments, each starting with a letter).\n`)
+    process.exit(1)
+  }
+
+  let written
+  try {
+    written = createProject({ dir, appName, appId, pkgName, force: opts.force })
+  } catch (err) {
+    process.stderr.write(`node-gtk create: ${err.message}\n`)
+    process.exit(1)
+  }
+
+  // Shortest copy-pasteable path to the new project: the relative path unless it
+  // escapes the cwd (e.g. `../../tmp/app`), in which case the absolute path reads
+  // better.
+  const relPath = path.relative(process.cwd(), dir)
+  const rel = (!relPath || relPath.startsWith('..')) ? dir : relPath
+
+  process.stdout.write(`\n${green('✓')} ${bold(`Created ${appName}`)} ${dim(`(${written.length} files) in ${dir}`)}\n`)
+
+  if (opts.install) {
+    process.stdout.write(`${dim('…')} ${bold('Installing dependencies')}${dim(' (npm install)')}\n`)
+    // Capture output and surface it only on failure — keep the happy path quiet.
+    const res = child_process.spawnSync('npm', ['install'], { cwd: dir, encoding: 'utf8' })
+    if (res.status !== 0) {
+      const output = `${res.stdout || ''}${res.stderr || ''}`
+      // The one expected, recoverable failure: node-gtk itself installed fine, but
+      // the postinstall type generation couldn't find the GTK/GI typelibs because
+      // the native libraries aren't installed yet. generate-types reports this as
+      // "Typelib file for namespace … not found" — treat it as a warning (the
+      // project is created and runnable) and hand back the command to finish up.
+      if (/Typelib file for namespace/i.test(output)) {
+        const finish = `cd ${rel} && npm run generate-types && npm run dev`
+        process.stdout.write(
+          `\n${yellow(bold('⚠ Project created, but TypeScript types could not be generated.'))}\n` +
+          `  The native ${bold('GTK 4 / libadwaita')} libraries don't seem to be installed.\n` +
+          `  ${dim('They power type generation and the app itself.')}\n\n` +
+          `  ${bold('1.')} Install them for your platform:\n` +
+          `     ${cyan('https://github.com/romgrk/node-gtk#installing')}\n\n` +
+          `  ${bold('2.')} Then finish setup:\n` +
+          `     ${cyan(finish)}\n\n`)
+        return
+      }
+      // Any other failure is unexpected: surface the raw output, the manual
+      // recovery steps, and a link to report it.
+      if (res.stdout) process.stderr.write(res.stdout)
+      if (res.stderr) process.stderr.write(res.stderr)
+      process.stderr.write(
+        `\nnpm install did not complete cleanly. Your project is created — ` +
+        `finish setup manually:\n\n  cd ${rel}\n  npm install\n  npm run dev\n\n` +
+        `If this keeps failing, please report it (include the output above):\n` +
+        `  https://github.com/romgrk/node-gtk/issues\n`)
+      process.exit(res.status || 1)
+    }
+  }
+
+  process.stdout.write(`${green('✓')} ${bold('Done!')}\n`)
+
+  const steps = [`cd ${rel}`].concat(opts.install ? [] : ['npm install']).concat(['npm run dev'])
+  process.stdout.write(`\n${bold('Next steps:')}\n\n`)
+  for (const s of steps) process.stdout.write(`  ${cyan(s)}\n`)
+  process.stdout.write('\n')
+}
+
+module.exports = { run, createProject, nodeGtkDependency, toAppName, toPkgName, toAppId, isValidAppId }