@gjsify/terminal-native 0.53.0 → 0.54.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;
@@ -22,7 +23,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 +42,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.54.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.54.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.53.0",
+        "@gjsify/cli": "^0.54.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.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"
     }
 }