@gjsify/terminal-native 0.54.0 → 0.55.0

package/lib/types/index.d.ts

@@ -16,6 +16,11 @@ export interface NativeResizeWatcherClass {
 export interface NativeResizeWatcher {
     /** Start watching SIGWINCH.  Idempotent. */
     start(): void;
+    /**
+     * Stop watching SIGWINCH and release the source's reference to this
+     * watcher.  Idempotent.  Without it a started watcher is immortal.
+     */
+    stop(): void;
     connect(signal: 'resized', handler: (obj: NativeResizeWatcher, rows: number, cols: number) => void): number;
     disconnect(id: number): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/terminal-native",
-    "version": "0.54.0",
+    "version": "0.55.0",
     "description": "Optional Vala/GObject bridge providing Posix.isatty(), ioctl(TIOCGWINSZ), termios raw-mode and SIGWINCH for GJS. Enhances @gjsify/tty and @gjsify/process with correct terminal behaviour when installed.",
     "type": "module",
     "main": "lib/esm/index.js",
@@ -62,10 +62,10 @@
     "dependencies": {
         "@girs/glib-2.0": "5.4.0",
         "@girs/gobject-2.0": "5.4.0",
-        "@gjsify/utils": "^0.54.0"
+        "@gjsify/utils": "^0.55.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.54.0",
+        "@gjsify/cli": "^0.55.0",
         "@ts-for-gir/cli": "^4.1.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
@@ -81,12 +81,12 @@
     },
     "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/node/terminal-native#readme",
     "optionalDependencies": {
-        "@gjsify/terminal-native-darwin-arm64": "0.54.0",
-        "@gjsify/terminal-native-darwin-x64": "0.54.0",
-        "@gjsify/terminal-native-linux-arm64": "0.54.0",
-        "@gjsify/terminal-native-linux-ppc64": "0.54.0",
-        "@gjsify/terminal-native-linux-riscv64": "0.54.0",
-        "@gjsify/terminal-native-linux-s390x": "0.54.0",
-        "@gjsify/terminal-native-linux-x64": "0.54.0"
+        "@gjsify/terminal-native-darwin-arm64": "0.55.0",
+        "@gjsify/terminal-native-darwin-x64": "0.55.0",
+        "@gjsify/terminal-native-linux-arm64": "0.55.0",
+        "@gjsify/terminal-native-linux-ppc64": "0.55.0",
+        "@gjsify/terminal-native-linux-riscv64": "0.55.0",
+        "@gjsify/terminal-native-linux-s390x": "0.55.0",
+        "@gjsify/terminal-native-linux-x64": "0.55.0"
     }
 }

package/src/vala/terminal.vala

@@ -104,9 +104,18 @@ namespace GjsifyTerminal {
      * ResizeWatcher — fires #GjsifyTerminal.ResizeWatcher::resized whenever
      * the terminal window is resized (SIGWINCH).
      *
-     * Call start() once; the watcher stays active for the process lifetime.
      * The signal is dispatched on the GLib main context via GLib.Idle so
      * JavaScript signal handlers run on the main thread.
+     *
+     * LIFECYCLE: `start()` takes a GLib source on the DEFAULT main context and
+     * that source holds a strong reference to the watcher (it is the callback's
+     * user_data), so a watcher that was started and never stopped is immortal —
+     * it can never be finalized, keeps its signal handlers alive, and is only
+     * torn down when GLib unrefs it during the host's own shutdown. `stop()`
+     * releases that reference and `dispose()` calls it, so a caller that is
+     * done with a watcher MUST stop or dispose it. Keeping the source id is
+     * what makes that possible; discarding it (as this class used to) leaves
+     * no way to reach the source again.
      */
     public class ResizeWatcher : GLib.Object {
 
@@ -118,17 +127,19 @@ namespace GjsifyTerminal {
         public signal void resized (int rows, int cols);
 
         private bool _active = false;
+        private uint _winch_source = 0;
 
         /**
          * start:
          *
-         * Begin watching SIGWINCH.  Idempotent — safe to call multiple times.
+         * Begin watching SIGWINCH.  Idempotent — safe to call multiple times,
+         * and safe to call again after stop().
          */
         public void start () {
             if (_active) return;
             _active = true;
 
-            GLib.Unix.signal_add (Posix.Signal.WINCH, () => {
+            _winch_source = (uint) GLib.Unix.signal_add (Posix.Signal.WINCH, () => {
                 int r = 0, c = 0, xp = 0, yp = 0;
                 if (Terminal.get_size (1, out r, out c, out xp, out yp)) {
                     int rows_snap = r;
@@ -141,5 +152,39 @@ namespace GjsifyTerminal {
                 return GLib.Source.CONTINUE;
             });
         }
+
+        /**
+         * stop:
+         *
+         * Stop watching SIGWINCH and drop the source's reference to this
+         * watcher, so it can be finalized.  Idempotent — safe on a watcher
+         * that was never started, and safe to call twice.
+         *
+         * A resize already dispatched to GLib.Idle still fires `resized`:
+         * that idle holds its own reference, so a watcher is never emitted on
+         * after it is gone.
+         */
+        public void stop () {
+            if (!_active) return;
+            _active = false;
+
+            if (_winch_source != 0) {
+                GLib.Source.remove (_winch_source);
+                _winch_source = 0;
+            }
+        }
+
+        /**
+         * dispose:
+         *
+         * Release the SIGWINCH source on an explicit `run_dispose()`.  This is
+         * NOT reached when the last JavaScript reference is dropped: the source
+         * holds its own reference, so a started watcher is never disposed by
+         * garbage collection.  Call stop() for that.
+         */
+        public override void dispose () {
+            stop ();
+            base.dispose ();
+        }
     }
 }