node-gtk 2.2.0 → 4.0.0

package/src/modules/cairo/font-extents.cc

@@ -28,8 +28,12 @@ void FontExtents::Initialize(Nan::ADDON_REGISTER_FUNCTION_ARGS_TYPE target) {
   tpl->InstanceTemplate()->SetInternalFieldCount(1);
   tpl->SetClassName(Nan::New("CairoFontExtents").ToLocalChecked());
 
-  // Prototype
-  Local<ObjectTemplate> proto = tpl->PrototypeTemplate();
+  // Accessors and indexed handlers must be installed on the instance
+  // template, not the prototype: in V8 14 property callbacks expose only
+  // HolderV2() (the holder). An accessor on the prototype would hand the
+  // callback the prototype object, which has no internal field, and
+  // Nan::ObjectWrap::Unwrap would abort. The instance carries the field.
+  Local<ObjectTemplate> proto = tpl->InstanceTemplate();
   SetProtoAccessor(proto, UTF8("ascent"),   GetAscent,   SetAscent,   tpl);
   SetProtoAccessor(proto, UTF8("descent"),  GetDescent,  SetDescent,  tpl);
   SetProtoAccessor(proto, UTF8("height"),   GetHeight,   SetHeight,   tpl);

package/src/modules/cairo/generator.js

@@ -133,7 +133,7 @@ function getSource(fn) {
     })() : '' }
     NAN_METHOD(${getJSName(fn.name)}) {
         auto self = info.This();
-        auto ${selfArgument.name} = (${getTypeName(selfArgument.type)}) self->GetAlignedPointerFromInternalField (0);
+        auto ${selfArgument.name} = (${getTypeName(selfArgument.type)}) Nan::GetInternalFieldPointer(self, 0);
 ${inArguments.length > 0 ? `
         // in-arguments
         ${inArguments.map(getInArgumentSource).join('\n        ')}

package/src/modules/cairo/glyph.cc

@@ -28,8 +28,12 @@ void Glyph::Initialize(Nan::ADDON_REGISTER_FUNCTION_ARGS_TYPE target) {
   tpl->InstanceTemplate()->SetInternalFieldCount(1);
   tpl->SetClassName(Nan::New("CairoGlyph").ToLocalChecked());
 
-  // Prototype
-  Local<ObjectTemplate> proto = tpl->PrototypeTemplate();
+  // Accessors and indexed handlers must be installed on the instance
+  // template, not the prototype: in V8 14 property callbacks expose only
+  // HolderV2() (the holder). An accessor on the prototype would hand the
+  // callback the prototype object, which has no internal field, and
+  // Nan::ObjectWrap::Unwrap would abort. The instance carries the field.
+  Local<ObjectTemplate> proto = tpl->InstanceTemplate();
   SetProtoAccessor(proto, UTF8("length"), GetLength, NULL,  tpl);
   Nan::SetIndexedPropertyHandler(proto, IndexGetter);
 

package/src/modules/cairo/path.cc

@@ -28,8 +28,12 @@ void Path::Initialize(Nan::ADDON_REGISTER_FUNCTION_ARGS_TYPE target) {
   tpl->InstanceTemplate()->SetInternalFieldCount(1);
   tpl->SetClassName(Nan::New("CairoPath").ToLocalChecked());
 
-  // Prototype
-  Local<ObjectTemplate> proto = tpl->PrototypeTemplate();
+  // Accessors and indexed handlers must be installed on the instance
+  // template, not the prototype: in V8 14 property callbacks expose only
+  // HolderV2() (the holder). An accessor on the prototype would hand the
+  // callback the prototype object, which has no internal field, and
+  // Nan::ObjectWrap::Unwrap would abort. The instance carries the field.
+  Local<ObjectTemplate> proto = tpl->InstanceTemplate();
   SetProtoAccessor(proto, UTF8("status"), GetStatus, NULL,  tpl);
 
   auto ctor = Nan::GetFunction (tpl).ToLocalChecked();

package/src/modules/cairo/rectangle-int.cc

@@ -28,8 +28,12 @@ void RectangleInt::Initialize(Nan::ADDON_REGISTER_FUNCTION_ARGS_TYPE target) {
   tpl->InstanceTemplate()->SetInternalFieldCount(1);
   tpl->SetClassName(Nan::New("CairoRectangleInt").ToLocalChecked());
 
-  // Prototype
-  Local<ObjectTemplate> proto = tpl->PrototypeTemplate();
+  // Accessors and indexed handlers must be installed on the instance
+  // template, not the prototype: in V8 14 property callbacks expose only
+  // HolderV2() (the holder). An accessor on the prototype would hand the
+  // callback the prototype object, which has no internal field, and
+  // Nan::ObjectWrap::Unwrap would abort. The instance carries the field.
+  Local<ObjectTemplate> proto = tpl->InstanceTemplate();
   SetProtoAccessor(proto, UTF8("x"),      GetX,      SetX,      tpl);
   SetProtoAccessor(proto, UTF8("y"),      GetY,      SetY,      tpl);
   SetProtoAccessor(proto, UTF8("width"),  GetWidth,  SetWidth,  tpl);

package/src/modules/cairo/rectangle.cc

@@ -28,8 +28,12 @@ void Rectangle::Initialize(Nan::ADDON_REGISTER_FUNCTION_ARGS_TYPE target) {
   tpl->InstanceTemplate()->SetInternalFieldCount(1);
   tpl->SetClassName(Nan::New("CairoRectangle").ToLocalChecked());
 
-  // Prototype
-  Local<ObjectTemplate> proto = tpl->PrototypeTemplate();
+  // Accessors and indexed handlers must be installed on the instance
+  // template, not the prototype: in V8 14 property callbacks expose only
+  // HolderV2() (the holder). An accessor on the prototype would hand the
+  // callback the prototype object, which has no internal field, and
+  // Nan::ObjectWrap::Unwrap would abort. The instance carries the field.
+  Local<ObjectTemplate> proto = tpl->InstanceTemplate();
   SetProtoAccessor(proto, UTF8("x"),      GetX,      SetX,      tpl);
   SetProtoAccessor(proto, UTF8("y"),      GetY,      SetY,      tpl);
   SetProtoAccessor(proto, UTF8("width"),  GetWidth,  SetWidth,  tpl);

package/src/modules/cairo/text-cluster.cc

@@ -28,8 +28,12 @@ void TextCluster::Initialize(Nan::ADDON_REGISTER_FUNCTION_ARGS_TYPE target) {
   tpl->InstanceTemplate()->SetInternalFieldCount(1);
   tpl->SetClassName(Nan::New("CairoTextCluster").ToLocalChecked());
 
-  // Prototype
-  Local<ObjectTemplate> proto = tpl->PrototypeTemplate();
+  // Accessors and indexed handlers must be installed on the instance
+  // template, not the prototype: in V8 14 property callbacks expose only
+  // HolderV2() (the holder). An accessor on the prototype would hand the
+  // callback the prototype object, which has no internal field, and
+  // Nan::ObjectWrap::Unwrap would abort. The instance carries the field.
+  Local<ObjectTemplate> proto = tpl->InstanceTemplate();
   SetProtoAccessor(proto, UTF8("length"), GetLength, NULL,  tpl);
   SetProtoAccessor(proto, UTF8("flags"),  GetFlags,  NULL,  tpl);
   Nan::SetIndexedPropertyHandler(proto, IndexGetter);

package/src/modules/cairo/text-extents.cc

@@ -28,8 +28,12 @@ void TextExtents::Initialize(Nan::ADDON_REGISTER_FUNCTION_ARGS_TYPE target) {
   tpl->InstanceTemplate()->SetInternalFieldCount(1);
   tpl->SetClassName(Nan::New("CairoTextExtents").ToLocalChecked());
 
-  // Prototype
-  Local<ObjectTemplate> proto = tpl->PrototypeTemplate();
+  // Accessors and indexed handlers must be installed on the instance
+  // template, not the prototype: in V8 14 property callbacks expose only
+  // HolderV2() (the holder). An accessor on the prototype would hand the
+  // callback the prototype object, which has no internal field, and
+  // Nan::ObjectWrap::Unwrap would abort. The instance carries the field.
+  Local<ObjectTemplate> proto = tpl->InstanceTemplate();
   SetProtoAccessor(proto, UTF8("xBearing"), GetXBearing, SetXBearing,  tpl);
   SetProtoAccessor(proto, UTF8("yBearing"), GetYBearing, SetYBearing, tpl);
   SetProtoAccessor(proto, UTF8("width"),    GetWidth,  SetWidth,  tpl);

package/src/modules/system.cc

@@ -24,7 +24,7 @@ namespace System {
 static gsize GetObjectSize (Local<Object> object) {
     // Boxed
     if (object->InternalFieldCount() == 2) {
-        auto box = static_cast<Boxed*>(object->GetAlignedPointerFromInternalField(1));
+        auto box = static_cast<Boxed*>(Nan::GetInternalFieldPointer(object, 1));
         return GetComplexTypeSize(box->info);
     }
     // GObject
@@ -38,7 +38,7 @@ static gsize GetObjectSize (Local<Object> object) {
 
 NAN_METHOD(AddressOf) {
     Local<Object> object = info[0].As<Object>();
-    void *pointer = object->GetAlignedPointerFromInternalField (0);
+    void *pointer = Nan::GetInternalFieldPointer(object, 0);
     RETURN(Nan::New<Number>((uint64_t)pointer));
 }
 
@@ -64,7 +64,7 @@ NAN_METHOD(ConvertGValue) {
         RETURN(Nan::Undefined());
         return;
     }
-    void *ptr = obj->GetAlignedPointerFromInternalField (0);
+    void *ptr = Nan::GetInternalFieldPointer(obj, 0);
     ResourceOwnership ownership = kCopy;
     RETURN(GValueToV8(reinterpret_cast<GValue *>(ptr), ownership));
 }
@@ -79,7 +79,7 @@ NAN_METHOD(GetMemoryContent) {
     }
     else {
         auto object = info[0].As<Object>();
-        address = (uint8_t *) object->GetAlignedPointerFromInternalField (0);
+        address = (uint8_t *) Nan::GetInternalFieldPointer(object, 0);
         size    = GetObjectSize(object);
     }
 

package/src/util.h

@@ -48,14 +48,14 @@ inline void SetProtoAccessor(
         Nan::SetterCallback setter,
         v8::Local<v8::FunctionTemplate> ctor
         ) {
+    // Trailing settings/attribute args are omitted so Nan supplies the right
+    // AccessControl default per V8 version (v8::DEFAULT was removed in V8 14).
     Nan::SetAccessor(
             tpl,
             name,
             getter,
             setter,
-            v8::Local<v8::Value>(),
-            v8::DEFAULT,
-            v8::None);
+            v8::Local<v8::Value>());
 }
 
 namespace Util

package/src/value.cc

@@ -6,6 +6,7 @@
 
 #include "error.h"
 #include "boxed.h"
+#include "fundamental.h"
 #include "function.h"
 #include "gi.h"
 #include "gobject.h"
@@ -51,7 +52,7 @@ static guint64 V8ToUint64 (Local<Value> value) {
 }
 
 
-Local<Value> GIArgumentToV8(GITypeInfo *type_info, GIArgument *arg, long length, ResourceOwnership ownership) {
+Local<Value> GIArgumentToV8(GITypeInfo *type_info, GIArgument *arg, long length, ResourceOwnership ownership, bool nullable) {
     GITypeTag type_tag = g_type_info_get_tag (type_info);
 
     switch (type_tag) {
@@ -120,6 +121,11 @@ Local<Value> GIArgumentToV8(GITypeInfo *type_info, GIArgument *arg, long length,
     case GI_TYPE_TAG_UTF8: {
         if (arg->v_string)
             return New<String>(arg->v_string).ToLocalChecked();
+        else if (nullable)
+            // A nullable string (e.g. g_data_input_stream_read_line_utf8_finish
+            // at EOF) returns NULL: surface it as `null` so it is
+            // distinguishable from a legitimately empty string. (#467)
+            return Nan::Null();
         else
             return Nan::EmptyString();
     }
@@ -136,7 +142,9 @@ Local<Value> GIArgumentToV8(GITypeInfo *type_info, GIArgument *arg, long length,
              * of a GObject, instead this represent the object type (eg class).  A GObject
              * has methods, fields, properties, signals, interfaces, constants and virtual functions. */
             case GI_INFO_TYPE_OBJECT:
-                if (G_IS_PARAM_SPEC(arg->v_pointer))
+                if (IsFundamentalObjectInfo(interface_info))
+                    value = WrapperFromFundamental(interface_info, arg->v_pointer, ownership);
+                else if (G_IS_PARAM_SPEC(arg->v_pointer))
                     value = ParamSpec::FromGParamSpec((GParamSpec *)arg->v_pointer);
                 else
                     value = WrapperFromGObject((GObject *)arg->v_pointer);
@@ -144,7 +152,12 @@ Local<Value> GIArgumentToV8(GITypeInfo *type_info, GIArgument *arg, long length,
             case GI_INFO_TYPE_BOXED:
             case GI_INFO_TYPE_STRUCT:
             case GI_INFO_TYPE_UNION:
-                value = WrapperFromBoxed (interface_info, arg->v_pointer, ownership);
+                // GVariant is a struct-classed fundamental: refcount it via the
+                // fundamental wrapper rather than g_boxed_copy (#465).
+                if (IsVariantInfo (interface_info))
+                    value = WrapperFromVariant (arg->v_pointer, ownership);
+                else
+                    value = WrapperFromBoxed (interface_info, arg->v_pointer, ownership);
                 break;
             case GI_INFO_TYPE_ENUM:
                 value = New<Number>(arg->v_int);
@@ -166,7 +179,7 @@ Local<Value> GIArgumentToV8(GITypeInfo *type_info, GIArgument *arg, long length,
         }
 
     case GI_TYPE_TAG_ARRAY:
-        return ArrayToV8(type_info, arg->v_pointer, length);
+        return ArrayToV8(type_info, arg->v_pointer, length, nullable);
 
     case GI_TYPE_TAG_GLIST:
         return GListToV8(type_info, (GList *)arg->v_pointer);
@@ -323,7 +336,13 @@ static bool IsZeroMemory (const void *ptr, gsize size) {
     return true;
 }
 
-Local<Value> ArrayToV8 (GITypeInfo *type_info, void* data, long length) {
+Local<Value> ArrayToV8 (GITypeInfo *type_info, void* data, long length, bool nullable) {
+
+    // A nullable array return (e.g. g_data_input_stream_read_line_finish at
+    // EOF) yields a NULL pointer: surface it as `null` so it is
+    // distinguishable from a legitimately empty array. (#467)
+    if (data == nullptr && nullable)
+        return Nan::Null();
 
     auto array = New<Array>();
 
@@ -833,6 +852,15 @@ bool V8ToGIArgumentInterface(GIBaseInfo *gi_info, GIArgument *arg, Local<Value>
             arg->v_pointer = ParamSpec::FromWrapper(value);
             break;
         }
+
+        if (IsFundamentalObjectInfo(gi_info)) {
+            // A fundamental (non-GObject) instance such as GskRenderNode: take
+            // the raw wrapped pointer. GObjectFromWrapper would G_OBJECT()-cast
+            // it — silently on Linux (cast checks compiled out) but a fatal
+            // `invalid cast ... to GObject` under G_DEBUG on Windows (#468).
+            arg->v_pointer = PointerFromWrapper(value);
+            break;
+        }
         // fallthrough
     }
     case GI_INFO_TYPE_INTERFACE:
@@ -1726,7 +1754,7 @@ bool CanConvertV8ToGValue(GValue *gvalue, Local<Value> value) {
     } else if (G_VALUE_HOLDS_POINTER (gvalue)) {
         return false;
     } else if (G_VALUE_HOLDS_VARIANT (gvalue)) {
-        return false;
+        return value->IsNullOrUndefined() || ValueIsInstanceOfGType(value, G_TYPE_VARIANT);
     }
 
     ERROR("Unhandled GValue type: %s (please report this)",
@@ -1819,7 +1847,13 @@ bool V8ToGValue(GValue *gvalue, Local<Value> value, ResourceOwnership ownership)
     } else if (G_VALUE_HOLDS_POINTER (gvalue)) {
         ERROR("Unsupported type: pointer");
     } else if (G_VALUE_HOLDS_VARIANT (gvalue)) {
-        ERROR("Unsupported type: variant");
+        // GVariant is nullable. g_value_set_variant refs a non-NULL variant
+        // (and sinks a floating one), so the GValue holds its own reference
+        // independent of the JS wrapper (#465).
+        g_value_set_variant (gvalue,
+                value->IsNullOrUndefined()
+                    ? NULL
+                    : (GVariant *) PointerFromWrapper (value));
     } else {
         ERROR("Unhandled GValue type: %s (please report this)",
                 g_type_name(G_VALUE_TYPE(gvalue)));
@@ -1896,7 +1930,9 @@ Local<Value> GValueToV8(const GValue *gvalue, ResourceOwnership ownership) {
     } else if (G_VALUE_HOLDS_POINTER (gvalue)) {
         ERROR("Unsuported type: pointer");
     } else if (G_VALUE_HOLDS_VARIANT (gvalue)) {
-        ERROR("Unsuported type: variant");
+        // GVariant is a struct-classed fundamental; the fundamental wrapper
+        // takes its own reference according to `ownership` (#465).
+        return WrapperFromVariant (g_value_get_variant (gvalue), ownership);
     } else {
         // Don't abort the whole process on a GValue type we can't convert
         // (e.g. GStreamer's GstValueArray / GstValueList, #389). Warn and

package/src/value.h

@@ -20,9 +20,9 @@ enum ResourceOwnership {
 Local<Value> GListToV8  (GITypeInfo *info, GList  *glist);
 Local<Value> GSListToV8 (GITypeInfo *info, GSList *glist);
 Local<Value> GHashToV8 (GITypeInfo *info, GHashTable *hash);
-Local<Value> ArrayToV8  (GITypeInfo *info, gpointer data, long length = -1);
+Local<Value> ArrayToV8  (GITypeInfo *info, gpointer data, long length = -1, bool nullable = false);
 Local<Value> GErrorToV8 (GITypeInfo *type_info, GError *err, ResourceOwnership ownership = kNone);
-Local<Value> GIArgumentToV8 (GITypeInfo *type_info, GIArgument *argument, long length = -1, ResourceOwnership ownership = kNone);
+Local<Value> GIArgumentToV8 (GITypeInfo *type_info, GIArgument *argument, long length = -1, ResourceOwnership ownership = kNone, bool nullable = false);
 long         GIArgumentToLength(GITypeInfo *type_info, GIArgument *arg, bool is_pointer);
 
 bool         V8ToGIArgumentInterface (GIBaseInfo *gi_info, GIArgument *argument, Local<Value> value);

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 }