perf(electron): optionally unload renderer on close

Author: backryun

electron/lib/remoteServerPreferences.js

@@ -5,8 +5,8 @@ const path = require("path");
 
 /**
  * remoteServerPreferences.js — pure read/write helpers for the small JSON
- * preferences file that persists the operator-configured remote server URL
- * across app restarts (see resolveRemoteServerUrl.js for how it's consumed).
+ * preferences file that persists desktop-shell choices needed before the
+ * server-owned settings database is available.
  *
  * Deliberately a plain flat JSON file rather than the app's SQLite database:
  * this preference must be readable before deciding whether to spawn (or even
@@ -18,19 +18,20 @@ const path = require("path");
  * @param {string} prefsPath - absolute path to electron-preferences.json
  * @param {(p: string) => boolean} [existsSync]
  * @param {(p: string, enc: string) => string} [readFileSync]
- * @returns {{remoteServerUrl: string|null}}
+ * @returns {{remoteServerUrl: string|null, closeBehavior: "keep-loaded"|"unload"}}
  */
 function readPreferences(prefsPath, existsSync = fs.existsSync, readFileSync = fs.readFileSync) {
-  if (!existsSync(prefsPath)) return { remoteServerUrl: null };
+  if (!existsSync(prefsPath)) return { remoteServerUrl: null, closeBehavior: "keep-loaded" };
   try {
     const parsed = JSON.parse(readFileSync(prefsPath, "utf8"));
     const remoteServerUrl =
       typeof parsed.remoteServerUrl === "string" && parsed.remoteServerUrl.trim()
         ? parsed.remoteServerUrl.trim()
         : null;
-    return { remoteServerUrl };
+    const closeBehavior = parsed.closeBehavior === "unload" ? "unload" : "keep-loaded";
+    return { remoteServerUrl, closeBehavior };
   } catch {
-    return { remoteServerUrl: null };
+    return { remoteServerUrl: null, closeBehavior: "keep-loaded" };
   }
 }
 
@@ -72,4 +73,35 @@ function writeRemoteServerUrl(
   }
 }
 
-module.exports = { readPreferences, writeRemoteServerUrl };
+/** Persist whether closing the dashboard hides it or unloads its renderer. */
+function writeCloseBehavior(
+  prefsPath,
+  closeBehavior,
+  {
+    existsSync = fs.existsSync,
+    readFileSync = fs.readFileSync,
+    writeFileSync = fs.writeFileSync,
+    mkdirSync = fs.mkdirSync,
+  } = {}
+) {
+  try {
+    const dir = path.dirname(prefsPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    const current = readPreferences(prefsPath, existsSync, readFileSync);
+    const next = {
+      ...current,
+      closeBehavior: closeBehavior === "unload" ? "unload" : "keep-loaded",
+    };
+    writeFileSync(prefsPath, JSON.stringify(next, null, 2) + "\n", "utf8");
+  } catch (err) {
+    console.error(
+      `[remoteServerPreferences] Failed to write preferences to ${prefsPath}:`,
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+}
+
+module.exports = { readPreferences, writeRemoteServerUrl, writeCloseBehavior };

electron/lib/windowClosePolicy.js

@@ -0,0 +1,26 @@
+"use strict";
+
+const CLOSE_BEHAVIOR_KEEP_LOADED = "keep-loaded";
+const CLOSE_BEHAVIOR_UNLOAD = "unload";
+
+function normalizeCloseBehavior(value) {
+  if (value === CLOSE_BEHAVIOR_KEEP_LOADED || value === CLOSE_BEHAVIOR_UNLOAD) return value;
+  return null;
+}
+
+function resolveRendererUrl(currentUrl, serverUrl) {
+  try {
+    const current = new URL(currentUrl);
+    const server = new URL(serverUrl);
+    return current.origin === server.origin ? current.href : server.href;
+  } catch {
+    return serverUrl;
+  }
+}
+
+module.exports = {
+  CLOSE_BEHAVIOR_KEEP_LOADED,
+  CLOSE_BEHAVIOR_UNLOAD,
+  normalizeCloseBehavior,
+  resolveRendererUrl,
+};

electron/main.js

@@ -38,8 +38,18 @@ const { killProcessTree } = require("./processTree");
 const { resolveServerEntry } = require("./lib/resolveServerEntry");
 const { resolveDarwinHelperExecutable } = require("./lib/resolveNodeHelper");
 const { resolveRemoteServerUrl, isValidHttpUrl } = require("./lib/resolveRemoteServerUrl");
-const { writeRemoteServerUrl } = require("./lib/remoteServerPreferences");
+const {
+  readPreferences,
+  writeRemoteServerUrl,
+  writeCloseBehavior,
+} = require("./lib/remoteServerPreferences");
 const { buildReadinessUrl, waitForServer } = require("./lib/serverReadiness");
+const {
+  CLOSE_BEHAVIOR_KEEP_LOADED,
+  CLOSE_BEHAVIOR_UNLOAD,
+  normalizeCloseBehavior,
+  resolveRendererUrl,
+} = require("./lib/windowClosePolicy");
 
 // ── Single Instance Lock ───────────────────────────────────
 const gotTheLock = app.requestSingleInstanceLock();
@@ -49,11 +59,12 @@ if (!gotTheLock) {
 }
 
 app.on("second-instance", () => {
-  if (mainWindow) {
-    if (mainWindow.isMinimized()) mainWindow.restore();
-    mainWindow.show();
-    mainWindow.focus();
-  }
+  const isHeadless =
+    process.argv.includes("--headless") ||
+    process.argv.includes("--cli") ||
+    process.env.OMNIROUTE_HEADLESS === "true";
+  if (isHeadless) return;
+  showMainWindow();
 });
 
 // ── Environment Detection ──────────────────────────────────
@@ -71,6 +82,7 @@ let nextServer = null;
 let serverPort = 20128;
 let isServerStopped = false;
 let remoteServerPromptWindow = null;
+let lastRendererUrl = null;
 
 // ── Remote Server Mode ──────────────────────────────────────
 // Lets the desktop shell attach to an already-running OmniRoute server (e.g. a
@@ -81,6 +93,8 @@ const REMOTE_SERVER_PREFS_PATH = path.join(
   resolveDataDir(null, process.env),
   "electron-preferences.json"
 );
+const electronPreferences = readPreferences(REMOTE_SERVER_PREFS_PATH);
+let closeBehavior = electronPreferences.closeBehavior;
 let remoteServerUrl = resolveRemoteServerUrl({
   env: process.env,
   prefsPath: REMOTE_SERVER_PREFS_PATH,
@@ -365,14 +379,18 @@ function setupContentSecurityPolicy() {
 }
 
 // ── Create Window ──────────────────────────────────────────
-function createWindow() {
+function createWindow({ showWhenReady = true } = {}) {
+  if (mainWindow && !mainWindow.isDestroyed()) return mainWindow;
+
+  const rendererStartedAt = Date.now();
+
   // Platform-conditional options (#9)
   const platformWindowOptions =
     process.platform === "darwin"
       ? { titleBarStyle: "hiddenInset", trafficLightPosition: { x: 16, y: 16 } }
       : { titleBarStyle: "default" };
 
-  mainWindow = new BrowserWindow({
+  const window = new BrowserWindow({
     width: 1400,
     height: 900,
     minWidth: 1024,
@@ -390,28 +408,25 @@ function createWindow() {
     backgroundColor: "#0a0a0a",
     ...platformWindowOptions,
   });
+  mainWindow = window;
 
   // Load the Next.js app
-  mainWindow.loadURL(getServerUrl());
+  window.loadURL(resolveRendererUrl(lastRendererUrl, getServerUrl()));
   if (isDev) {
-    mainWindow.webContents.openDevTools({ mode: "detach" });
+    window.webContents.openDevTools({ mode: "detach" });
   }
 
-  // Show window when ready (unless starting minimized/hidden in tray)
-  mainWindow.once("ready-to-show", () => {
-    const startHidden =
-      process.argv.includes("--hidden") ||
-      process.argv.includes("--minimized") ||
-      app.getLoginItemSettings().wasOpenedAsHidden;
-    if (!startHidden) {
-      mainWindow.show();
+  window.once("ready-to-show", () => {
+    console.log(`[Electron] Renderer ready in ${Date.now() - rendererStartedAt}ms`);
+    if (showWhenReady) {
+      window.show();
     } else {
       console.log("[Electron] Launched hidden in background tray");
     }
   });
 
   // Handle external links — validate URL protocol to prevent RCE
-  mainWindow.webContents.setWindowOpenHandler(({ url }) => {
+  window.webContents.setWindowOpenHandler(({ url }) => {
     try {
       const parsedUrl = new URL(url);
       if (["http:", "https:"].includes(parsedUrl.protocol)) {
@@ -425,18 +440,46 @@ function createWindow() {
     return { action: "deny" };
   });
 
-  // Handle window close — minimize to tray
-  mainWindow.on("close", (event) => {
+  // Keep the server alive while either hiding the renderer for a fast reopen or
+  // unloading it to reclaim memory, according to the persisted tray preference.
+  window.on("close", (event) => {
     if (!app.isQuitting) {
       event.preventDefault();
-      mainWindow.hide();
+      lastRendererUrl = resolveRendererUrl(window.webContents.getURL(), getServerUrl());
+      if (closeBehavior === CLOSE_BEHAVIOR_UNLOAD) {
+        console.log("[Electron] Dashboard renderer unloaded; server remains running");
+        window.destroy();
+      } else {
+        console.log("[Electron] Dashboard hidden; renderer kept loaded");
+        window.hide();
+      }
     }
     return false;
   });
 
-  mainWindow.on("closed", () => {
-    mainWindow = null;
+  window.on("closed", () => {
+    if (mainWindow === window) mainWindow = null;
   });
+
+  return window;
+}
+
+function showMainWindow() {
+  if (!mainWindow || mainWindow.isDestroyed()) {
+    createWindow();
+    return;
+  }
+  if (mainWindow.isMinimized()) mainWindow.restore();
+  mainWindow.show();
+  mainWindow.focus();
+}
+
+function setCloseBehavior(nextBehavior) {
+  const normalized = normalizeCloseBehavior(nextBehavior);
+  if (!normalized || normalized === closeBehavior) return;
+  closeBehavior = normalized;
+  writeCloseBehavior(REMOTE_SERVER_PREFS_PATH, closeBehavior);
+  createTray();
 }
 
 // ── System Tray ────────────────────────────────────────────
@@ -465,12 +508,7 @@ function createTray() {
   const contextMenu = Menu.buildFromTemplate([
     {
       label: "Open OmniRoute",
-      click: () => {
-        if (mainWindow) {
-          mainWindow.show();
-          mainWindow.focus();
-        }
-      },
+      click: () => showMainWindow(),
     },
     {
       label: "Open Dashboard",
@@ -504,6 +542,23 @@ function createTray() {
         },
       ],
     },
+    {
+      label: "When Dashboard Closes",
+      submenu: [
+        {
+          label: "Keep Loaded (Faster Reopen)",
+          type: "radio",
+          checked: closeBehavior === CLOSE_BEHAVIOR_KEEP_LOADED,
+          click: () => setCloseBehavior(CLOSE_BEHAVIOR_KEEP_LOADED),
+        },
+        {
+          label: "Unload Renderer (Lower Memory)",
+          type: "radio",
+          checked: closeBehavior === CLOSE_BEHAVIOR_UNLOAD,
+          click: () => setCloseBehavior(CLOSE_BEHAVIOR_UNLOAD),
+        },
+      ],
+    },
     { type: "separator" },
     {
       label: "Check for Updates",
@@ -522,12 +577,7 @@ function createTray() {
   tray.setToolTip("OmniRoute");
   tray.setContextMenu(contextMenu);
 
-  tray.on("double-click", () => {
-    if (mainWindow) {
-      mainWindow.show();
-      mainWindow.focus();
-    }
-  });
+  tray.on("double-click", () => showMainWindow());
 }
 
 // ── Change Port (#3: now restarts server) ──────────────────
@@ -549,6 +599,7 @@ async function changePort(newPort) {
   await waitForServer(getServerReadinessUrl());
 
   // Reload window and update tray
+  lastRendererUrl = getServerUrl();
   if (mainWindow && !mainWindow.isDestroyed()) {
     mainWindow.loadURL(getServerUrl());
   }
@@ -613,6 +664,7 @@ async function setRemoteServerUrl(nextUrl) {
 
   remoteServerUrl = normalized;
   writeRemoteServerUrl(REMOTE_SERVER_PREFS_PATH, remoteServerUrl);
+  lastRendererUrl = getServerUrl();
 
   startNextServer();
   try {
@@ -1106,7 +1158,11 @@ app.whenReady().then(async () => {
   if (isHeadless) {
     console.log("[Electron] Headless mode active — UI window and tray icon skipped");
   } else {
-    createWindow();
+    const startHidden =
+      process.argv.includes("--hidden") ||
+      process.argv.includes("--minimized") ||
+      app.getLoginItemSettings().wasOpenedAsHidden;
+    createWindow({ showWhenReady: !startHidden });
     createTray();
   }
 
@@ -1133,11 +1189,7 @@ app.whenReady().then(async () => {
   // macOS: recreate window when dock icon clicked
   app.on("activate", () => {
     if (isHeadless) return;
-    if (BrowserWindow.getAllWindows().length === 0) {
-      createWindow();
-    } else if (mainWindow) {
-      mainWindow.show();
-    }
+    showMainWindow();
   });
 });
 
@@ -1147,7 +1199,7 @@ app.on("window-all-closed", () => {
     process.argv.includes("--headless") ||
     process.argv.includes("--cli") ||
     process.env.OMNIROUTE_HEADLESS === "true";
-  if (process.platform !== "darwin" && !isHeadless) {
+  if (process.platform !== "darwin" && !isHeadless && closeBehavior !== CLOSE_BEHAVIOR_UNLOAD) {
     app.quit();
   }
 });

electron/package.json

@@ -67,6 +67,7 @@
       "lib/resolveRemoteServerUrl.js",
       "lib/remoteServerPreferences.js",
       "lib/serverReadiness.js",
+      "lib/windowClosePolicy.js",
       "assets/remoteServerPrompt.html",
       "package.json",
       "node_modules/**/*"