@pi-unipi/unipi 2.0.3 → 2.0.4

package/packages/notify/platforms/focus.ts

@@ -0,0 +1,33 @@
+/**
+ * @pi-unipi/notify — Focus detection abstraction
+ *
+ * Unified interface for checking whether the terminal window is the
+ * foreground (active) window. Platform-specific implementations are
+ * dispatched based on process.platform.
+ *
+ * Currently implemented:
+ *   - Windows (win32): calls focus-win.ts
+ *
+ * Unimplemented platforms always return false (no suppression).
+ */
+
+import { isWindowFocusedOnWindows } from "./focus-win.js";
+
+/**
+ * Check whether the current terminal/console window is the foreground
+ * (active) window. Used by sendNativeNotification to optionally
+ * suppress notifications when the user is already looking at the screen.
+ *
+ * @returns true if the terminal is the foreground window, false otherwise.
+ *          On unimplemented platforms, always returns false.
+ */
+export async function isWindowFocused(): Promise<boolean> {
+  switch (process.platform) {
+    case "win32":
+      return await isWindowFocusedOnWindows();
+    // TODO: macOS — use osascript to check frontmost application
+    // TODO: Linux — use xdotool (X11) or per-compositor tool (Wayland)
+    default:
+      return false;
+  }
+}

package/packages/notify/platforms/native.ts

@@ -8,22 +8,54 @@
  */
 
 import notifier from "node-notifier";
+import { isWindowFocused } from "./focus.js";
 
 /** Options for native notification */
 export interface NativeNotificationOptions {
   /** Windows appID to show instead of "SnoreToast" */
   windowsAppId?: string;
+  /**
+   * When true, suppresses the notification if the terminal window is
+   * the foreground (active) window. Only effective on platforms where
+   * `isWindowFocused` is implemented (currently Windows).
+   */
+  suppressWhenFocused?: boolean;
+}
+
+/**
+ * Thrown by sendNativeNotification when the notification was suppressed
+ * because suppressWhenFocused is set and the terminal window is focused.
+ *
+ * Callers should catch this and treat it as intentional suppression,
+ * NOT as a send failure.
+ */
+export class SuppressedError extends Error {
+  constructor() {
+    super("Notification suppressed: terminal window is focused");
+    this.name = "SuppressedError";
+  }
 }
 
 /**
  * Send a native OS notification.
- * Resolves when notification is shown, rejects on error.
+ *
+ * When `suppressWhenFocused` is true and `isWindowFocused()` returns true
+ * (i.e. the terminal is the foreground window), the notification is
+ * suppressed and the promise rejects with SuppressedError.
+ *
+ * Resolves when notification is shown, rejects with SuppressedError on
+ * suppression or with a standard Error on failure.
  */
 export async function sendNativeNotification(
   title: string,
   message: string,
   options?: NativeNotificationOptions
 ): Promise<void> {
+  // Suppress if the terminal window is currently focused
+  if (options?.suppressWhenFocused && await isWindowFocused()) {
+    throw new SuppressedError();
+  }
+
   return new Promise((resolve, reject) => {
     notifier.notify(
       {

package/packages/notify/settings.ts

@@ -30,6 +30,7 @@ export const DEFAULT_CONFIG: NotifyConfig = {
   },
   native: {
     enabled: true,
+    suppressWhenFocused: false,
   },
   gotify: {
     enabled: false,

package/packages/notify/tui/settings-overlay.ts

@@ -85,7 +85,7 @@ export class NotifySettingsOverlay implements Component {
   }
 
   private get maxItems(): number {
-    if (this.section === "platforms") return 4; // native, gotify, telegram, ntfy
+    if (this.section === "platforms") return 5; // native, gotify, telegram, ntfy + suppress option
     if (this.section === "recap") return 1; // toggle
     return Object.keys(this.config.events).length;
   }
@@ -98,12 +98,17 @@ export class NotifySettingsOverlay implements Component {
         "telegram",
         "ntfy",
       ];
-      const key = platforms[this.selectedIndex];
-      if (key === "ntfy") {
-        // ntfy toggle updates the resolved ntfy config
-        this.ntfyConfig.enabled = !this.ntfyConfig.enabled;
-      } else if (key) {
-        this.config[key].enabled = !this.config[key].enabled;
+      if (this.selectedIndex < platforms.length) {
+        const key = platforms[this.selectedIndex];
+        if (key === "ntfy") {
+          // ntfy toggle updates the resolved ntfy config
+          this.ntfyConfig.enabled = !this.ntfyConfig.enabled;
+        } else if (key) {
+          this.config[key].enabled = !this.config[key].enabled;
+        }
+      } else {
+        // suppressWhenFocused toggle (index 4)
+        this.config.native.suppressWhenFocused = !this.config.native.suppressWhenFocused;
       }
     } else if (this.section === "recap") {
       this.config.recap.enabled = !this.config.recap.enabled;
@@ -273,6 +278,27 @@ export class NotifySettingsOverlay implements Component {
         )
       );
     }
+
+    // suppressWhenFocused toggle (index 4)
+    {
+      const i = platforms.length;
+      const isSelected = i === this.selectedIndex;
+      const isEnabled = this.config.native.suppressWhenFocused === true;
+      const toggleOn = this.fg("success", "●");
+      const toggleOff = this.fg("dim", "○");
+      const toggle = isEnabled ? toggleOn : toggleOff;
+      const label = isSelected
+        ? this.bold("Suppress when focused")
+        : this.fg("dim", "Suppress when focused");
+      const detail = this.fg("dim", isEnabled ? "Windows only — terminal in foreground → skip" : "Windows only");
+
+      lines.push(
+        this.frameLine(
+          `${isSelected ? this.fg("accent", "▸") : " "} ${toggle} ${label}  ${detail}`,
+          innerWidth
+        )
+      );
+    }
   }
 
   private renderEvents(lines: string[], innerWidth: number): void {

package/packages/notify/types.ts

@@ -19,6 +19,12 @@ export interface NativeConfig {
   enabled: boolean;
   /** Windows appID to show instead of "SnoreToast" */
   windowsAppId?: string;
+  /**
+   * When true, suppresses the notification if the terminal window is the
+   * foreground (active) window. Only effective on supported platforms
+   * (currently Windows). Default: false.
+   */
+  suppressWhenFocused?: boolean;
 }
 
 /** Gotify notification platform config */
@@ -101,6 +107,8 @@ export interface NotifyResult {
   platform: NotifyPlatform;
   /** Whether the send succeeded */
   success: boolean;
+  /** True when the notification was intentionally suppressed (e.g. window focused) */
+  suppressed?: boolean;
   /** Error message if failed */
   error?: string;
 }