@gjsify/terminal-native 0.53.0 → 0.55.0

package/lib/esm/index.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{loadOptionalNativeModule as e}from"@gjsify/utils/core";const t=e(`GjsifyTerminal`,[`Terminal`,`ResizeWatcher`]),n=t.module,r=n;function hasNativeTerminal(){return n!==null}function getNativeTerminalLoadError(){return t.error}export{getNativeTerminalLoadError,hasNativeTerminal,r as nativeTerminal};
+import"./_virtual/_rolldown/runtime.js";import{claimRawMode as e,isRawModeClaimed as t,noteRawMode as n,releaseRawMode as r,restoreClaimedRawModes as i}from"./raw-mode.js";import{loadOptionalNativeModule as a}from"@gjsify/utils/core";const o=a(`GjsifyTerminal`,[`Terminal`,`ResizeWatcher`]),s=o.module,c=s;function hasNativeTerminal(){return s!==null}function getNativeTerminalLoadError(){return o.error}function callableModule(){if(!s)return null;try{return s.Terminal.is_tty(2),s}catch{return null}}function nativeIsTty(e){try{return callableModule()?.Terminal.is_tty(e)??null}catch{return null}}function nativeTerminalSize(e){try{let[t,n,r]=callableModule()?.Terminal.get_size(e)??[!1,0,0];return!t||r<=0?null:{rows:n,columns:r}}catch{return null}}function nativeSetRawMode(e,t){try{return callableModule()?.Terminal.set_raw_mode(e,t)??null}catch{return null}}export{e as claimRawMode,getNativeTerminalLoadError,hasNativeTerminal,t as isRawModeClaimed,nativeIsTty,nativeSetRawMode,c as nativeTerminal,nativeTerminalSize,n as noteRawMode,r as releaseRawMode,i as restoreClaimedRawModes};

package/lib/esm/raw-mode.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";const e=Symbol.for(`@gjsify/terminal-native:raw-mode-claims`),t=globalThis,n=t[e]??=new Map;function claimRawMode(e,t){n.set(e,t)}function releaseRawMode(e){n.delete(e)}function isRawModeClaimed(e){return n.has(e)}function noteRawMode(e,t,n){let r=n(t);return t?r&&claimRawMode(e,()=>{n(!1)}):releaseRawMode(e),r}function restoreClaimedRawModes(){let e=[...n.entries()];n.clear();let t=0,r;for(let[,n]of e)try{n(),t+=1}catch(e){r??=e}if(r!==void 0)throw r;return t}export{claimRawMode,isRawModeClaimed,noteRawMode,releaseRawMode,restoreClaimedRawModes};

package/lib/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from './raw-mode.js';
 export interface NativeTerminal {
     /** Check whether fd is an interactive terminal (Posix.isatty). */
     is_tty(fd: number): boolean;
@@ -15,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;
 }
@@ -22,7 +28,16 @@ export interface GjsifyTerminalModule {
     Terminal: NativeTerminal;
     ResizeWatcher: NativeResizeWatcherClass;
 }
-/** The native GjsifyTerminal module, or null if not installed. */
+/**
+ * The native GjsifyTerminal module, or null if not installed.
+ *
+ * READING this namespace proves less than it looks: girepository opens the
+ * shared library at the first member CALL, not at the load, so a namespace
+ * that resolved can still raise on every call (see {@link callableModule}).
+ * Prefer the `native*` accessors below — they carry that one step and return
+ * `null` instead of throwing, which is what an optional prebuild owes a caller
+ * that already has a fallback.
+ */
 export declare const nativeTerminal: GjsifyTerminalModule | null;
 /** Returns true when the GjsifyTerminal native library is available. */
 export declare function hasNativeTerminal(): boolean;
@@ -32,3 +47,27 @@ export declare function hasNativeTerminal(): boolean;
  * dependency when it is installed but its library will not open.
  */
 export declare function getNativeTerminalLoadError(): Error | null;
+/**
+ * `Terminal.is_tty(fd)`, or `null` when the native module is absent or its
+ * calls throw. `null` is distinct from `false`: a caller that owns a fallback
+ * (`process.stdout.isTTY` → GLib's `log_writer_supports_color`) must take it
+ * on `null` and answer `false` itself on a real answer.
+ */
+export declare function nativeIsTty(fd: number): boolean | null;
+/**
+ * `Terminal.get_size(fd)` as `[rows, columns]`, or `null` when the native
+ * module is absent, its calls throw, or the ioctl reports no size. The last
+ * collapse is deliberate: every consumer asks the same question — "how wide is
+ * this fd, if I can really tell?" — and answered `ok && cols > 0` itself.
+ * Returns columns second, matching the bridge's own tuple order.
+ */
+export declare function nativeTerminalSize(fd: number): {
+    rows: number;
+    columns: number;
+} | null;
+/**
+ * `Terminal.set_raw_mode(fd, enable)`, or `null` when the native module is
+ * absent or its calls throw. The caller keeps its own `isRaw` bookkeeping, so
+ * the return value is only ever read as "did the native call happen".
+ */
+export declare function nativeSetRawMode(fd: number, enable: boolean): boolean | null;

package/lib/types/raw-mode.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Record that this process put `fd` into raw mode, and how to undo it.
+ *
+ * Called by whoever performs the transition, on EVERY path — a path that forgets
+ * to claim is a terminal nobody will restore, which is the bug this exists for.
+ */
+export declare function claimRawMode(fd: number, restore: () => void): void;
+/**
+ * Record that the owner turned `fd` back itself, in the normal close() path.
+ *
+ * A paid debt: nothing is owed at exit, so the exit hook must not run a restore
+ * that could fight whoever claimed the descriptor afterwards.
+ */
+export declare function releaseRawMode(fd: number): void;
+/** Whether this process still owes `fd` a restore. */
+export declare function isRawModeClaimed(fd: number): boolean;
+/**
+ * Make the raw-mode transition on `fd` and record what it now owes — or that it
+ * owes nothing. The rule in one place, because getting it wrong is the whole
+ * failure: one call used to take two branches and only one of them remembered,
+ * so the terminal was restored where the native module was absent and stranded
+ * everywhere else.
+ *
+ * `setRawMode` performs the change and reports whether it HAPPENED; that verdict
+ * is the return value, so a caller with a further fallback (the `stty` spawn in
+ * `@gjsify/process`) can take it without asking the terminal twice. It is the
+ * same function for both directions, so the undo cannot drift from the change: a
+ * claim taken on a transition that did not happen would restore a terminal this
+ * process never broke, and turning raw mode off through here PAYS the debt rather
+ * than recording it, so no stale undo can outlive the owner that made it — and it
+ * pays it whatever the verdict, because an owner that asked to let go has let go
+ * whether or not the terminal heard it, and a claim the exit hook would then run
+ * is a restore of a state this process may never have reached.
+ */
+export declare function noteRawMode(fd: number, mode: boolean, setRawMode: (enable: boolean) => boolean): boolean;
+/**
+ * Pay every outstanding debt, and report how many were paid.
+ *
+ * The map is emptied BEFORE anything runs, so a restore that claims again — or
+ * throws — cannot be undone by this same pass. One descriptor failing does not
+ * strand the others: every restore is attempted, and the first failure is
+ * rethrown afterwards so the caller can see it. A silently empty restore is the
+ * exact failure this module exists to remove, so the error is never swallowed.
+ */
+export declare function restoreClaimedRawModes(): number;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/terminal-native",
-    "version": "0.53.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.53.0"
+        "@gjsify/utils": "^0.55.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.53.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.53.0",
-        "@gjsify/terminal-native-darwin-x64": "0.53.0",
-        "@gjsify/terminal-native-linux-arm64": "0.53.0",
-        "@gjsify/terminal-native-linux-ppc64": "0.53.0",
-        "@gjsify/terminal-native-linux-riscv64": "0.53.0",
-        "@gjsify/terminal-native-linux-s390x": "0.53.0",
-        "@gjsify/terminal-native-linux-x64": "0.53.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 ();
+        }
     }
 }