@amd-gaia/agent-ui 0.25.0 → 0.25.1-rc.10

package/main.cjs

@@ -13,7 +13,17 @@
 //   services/notification-service.js  — Desktop notifications + permission prompts (T5)
 //   preload.cjs                       — contextBridge for IPC channels (T0/T1)
 
-const { app, BrowserWindow, dialog, shell } = require("electron");
+const {
+  app,
+  autoUpdater: electronAutoUpdater,
+  BrowserWindow,
+  Menu,
+  dialog,
+  ipcMain,
+  powerMonitor,
+  session,
+  shell,
+} = require("electron");
 const path = require("path");
 const fs = require("fs");
 const os = require("os");
@@ -37,12 +47,18 @@ const _MAIN_LOG_PATH = path.join(_GAIA_DIR, "electron-main.log");
 // very handler we are trying to install, falling through to Electron's bare
 // JS-error dialog.
 let installSafetyNet, installLogTee, _fatalHandler;
+// Set when a fatal error quits the app: the crash dialog was the question,
+// so the quit guard must not ask again.
+let fatalQuitting = false;
 try {
   ({ installSafetyNet, installLogTee } = require("./main-safety-net.cjs"));
   ({ fatal: _fatalHandler } = installSafetyNet({
     logPath: _MAIN_LOG_PATH,
     dialogModule: dialog,
     appModule: app,
+    beforeQuit: () => {
+      fatalQuitting = true;
+    },
   }));
 } catch (err) {
   try { process.stderr.write(`[main] safety-net load failed: ${err.message}\n`); } catch { }
@@ -54,10 +70,21 @@ try {
 
 // Services (loaded after app.whenReady)
 const TrayManager = require("./services/tray-manager.cjs");
+const { appIconPath, appUserModelId } = require("./services/app-icon.cjs");
+const {
+  attachWindowGuards,
+  confirmQuit,
+  fetchWorkInProgress,
+  installQuitGuard,
+  QUIT,
+  RESTART_FOR_UPDATE,
+} = require("./services/quit-guard.cjs");
 const AgentProcessManager = require("./services/agent-process-manager.cjs");
 const NotificationService = require("./services/notification-service.cjs");
+const KeepAwake = require("./services/keep-awake.cjs");
 const PortManager = require("./services/port-manager.cjs");
 const { isGaiaBackendProcess } = require("./services/backend-orphan.cjs");
+const { showBackendCrashDialog } = require("./services/backend-crash-dialog.cjs");
 const { buildIndexQuery } = require("./services/index-query.cjs");
 const backendInstaller = require("./services/backend-installer.cjs");
 const installerProgressDialog = require("./services/backend-installer-progress-dialog.cjs");
@@ -76,27 +103,14 @@ const {
   describeBlockedUrl,
 } = require("./services/link-policy.cjs");
 const { createStartupDeepLinkQueue } = require("./services/deep-link-queue.cjs");
-
-// ── F7: Ozone hint (issue #782) ─────────────────────────────────────────────
-// Electron-recommended switch for distro-agnostic Linux behaviour: picks
-// Wayland on Wayland sessions, X11 elsewhere. Must be set before
-// app.whenReady() fires.
-app.commandLine.appendSwitch("ozone-platform-hint", "auto");
-
-// ── F7: --no-sandbox on Linux (issue #782) ───────────────────────────────────
-// chrome-sandbox is deleted from the packaged tree by after-pack.cjs so
-// Chromium must use its unprivileged user-namespace sandbox on every launch
-// path. The .desktop Exec= line already carries --no-sandbox via
-// electron-builder.yml linux.executableArgs, but direct `./GAIA.AppImage`
-// invocations bypass the .desktop entry. Appending the switch here makes
-// all Linux launch paths behave identically.
-if (process.platform === "linux") {
-  app.commandLine.appendSwitch("no-sandbox");
-
-  // Workaround: disable Chromium's Wayland color management which crashes on
-  // some Wayland compositors that implement the wp_color_manager protocol
-  // partially. See issue reports about wayland_wp_color_manager.cc SIGTRAP.
-  app.commandLine.appendSwitch("disable-features", "WaylandColorManagement");
+const { installWindowKeys } = require("./services/window-keys.cjs");
+const { installQuitCleanup } = require("./services/quit-cleanup.cjs");
+const { chromiumSwitches } = require("./services/chromium-switches.cjs");
+
+// No ozone switch: Electron 38+ already picks Wayland or X11, and users override with --ozone-platform=x11.
+for (const [name, value] of chromiumSwitches({ platform: process.platform, env: process.env })) {
+  if (value === undefined) app.commandLine.appendSwitch(name);
+  else app.commandLine.appendSwitch(name, value);
 }
 
 // ── F7: Log tee to ~/.gaia/electron-main.log (issue #782) ───────────────────
@@ -205,6 +219,11 @@ const windowConfig = appConfig.window || {
 // ── State ──────────────────────────────────────────────────────────────────
 
 let backendProcess = null;
+// The in-flight startBackend(), so a quit during startup can wait for the
+// spawn and stop it instead of leaving it behind.
+let backendStarting = null;
+// Set as cleanup() begins; startup stops at its next step once it is.
+let shutdownStarted = false;
 let backendPort = DEFAULT_BACKEND_PORT;
 let healthCheckUrl = `http://localhost:${backendPort}/api/health`;
 let backendStderrTail = [];
@@ -225,6 +244,9 @@ let agentProcessManager = null;
 /** @type {NotificationService | null} */
 let notificationService = null;
 
+/** @type {KeepAwake | null} */
+let keepAwake = null;
+
 /** @type {PortManager} */
 const portManager = new PortManager({
   logger: { log: console.log.bind(console), error: console.error.bind(console) },
@@ -386,6 +408,7 @@ async function startBackend() {
     }
     const crashed = !isIntentionalKill && code !== 0 && code !== null;
     backendProcess = null;
+    if (trayManager && !isQuitting) trayManager.setBackendAlive(false);
 
     if (crashed && !isQuitting) {
       // Fire-and-forget — don't block the event loop.
@@ -411,46 +434,23 @@ async function startBackend() {
 }
 
 /**
- * Show a user-facing crash dialog with the last ~20 stderr lines and
- * offer to write a diagnostics bundle. Invoked from child.on("exit")
- * when the kill was NOT initiated by us.
+ * Tell the user the backend stopped and offer Restart / Save diagnostics /
+ * Quit. Invoked from child.on("exit") when the kill was NOT initiated by us.
  */
 async function handleBackendCrash(code, signal) {
-  const tail = backendStderrTail.slice(-20).join("\n") || "(no stderr captured)";
-  const detail =
-    `The GAIA backend exited unexpectedly (code=${code}, signal=${signal}).\n\n` +
-    `Recent log output:\n${tail}`;
-
   try {
-    const choice = await dialog.showMessageBox({
-      type: "error",
-      title: "GAIA backend crashed",
-      message: "GAIA backend crashed",
-      detail,
-      buttons: ["Copy diagnostics", "Quit"],
-      defaultId: 0,
-      cancelId: 1,
-      noLink: true,
+    const choice = await showBackendCrashDialog({
+      dialog,
+      app,
+      code,
+      signal,
+      tailLines: backendStderrTail.slice(-8),
+      writeDiagnostics: () => portManager.writeDiagnosticsBundle(),
+      // The backend is gone, so there is no running work to ask about.
+      beforeQuit: () => { fatalQuitting = true; },
+      parent: mainWindow,
     });
-
-    if (choice.response === 0) {
-      try {
-        const bundlePath = await portManager.writeDiagnosticsBundle();
-        await dialog.showMessageBox({
-          type: "info",
-          title: "Diagnostics saved",
-          message: "Diagnostics bundle written",
-          detail: `Attach this file to your bug report:\n${bundlePath}`,
-          buttons: ["OK"],
-        });
-      } catch (err) {
-        console.error("[main] Could not write diagnostics bundle:", err.message);
-        dialog.showErrorBox(
-          "Could not write diagnostics",
-          `Failed to write diagnostics bundle: ${err.message}`
-        );
-      }
-    }
+    console.log(`[main] Backend crash: user chose ${choice}`);
   } catch (err) {
     console.error("[main] handleBackendCrash failed:", err.message);
   }
@@ -523,14 +523,57 @@ function reportBlockedLink(url) {
     );
 }
 
+// No system title bar: the app's own top row is the window's top edge, and
+// the native window controls are drawn into it (traffic lights on macOS).
+// Keep the height in sync with --titlebar-h in src/styles/index.css. The
+// renderer sends its canvas and text colors once it paints; until then the
+// controls use the dark canvas, like the window background.
+const TITLE_BAR_HEIGHT = 48;
+const TITLE_BAR_INITIAL = { color: "#1A1917", symbolColor: "#EFECE6" };
+const IS_MAC = process.platform === "darwin";
+const HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
+
+function titleBarOptions() {
+  return IS_MAC
+    ? { titleBarStyle: "hidden", trafficLightPosition: { x: 16, y: 16 } }
+    : {
+        titleBarStyle: "hidden",
+        titleBarOverlay: { ...TITLE_BAR_INITIAL, height: TITLE_BAR_HEIGHT },
+      };
+}
+
+// The renderer sends its canvas and text colors so the controls match the theme.
+ipcMain.handle("window:set-titlebar-colors", (_event, colors) => {
+  const { color, symbolColor } = colors || {};
+  if (!HEX_COLOR.test(color) || !HEX_COLOR.test(symbolColor)) {
+    throw new Error(`Title bar colors must be #rrggbb, got ${JSON.stringify(colors)}`);
+  }
+  if (!IS_MAC && mainWindow && !mainWindow.isDestroyed()) {
+    mainWindow.setTitleBarOverlay({ color, symbolColor });
+  }
+  return true;
+});
+
+// Registered once: createWindow runs again on every macOS reopen, and the session is shared.
+function titleDownloadSaveDialogs() {
+  // An export is a blob: download, and Chromium titles its Save dialog with the blob URL.
+  session.defaultSession.on("will-download", (_event, item) => {
+    item.setSaveDialogOptions({
+      title: "Save from GAIA",
+      defaultPath: path.join(app.getPath("downloads"), item.getFilename()),
+    });
+  });
+}
+
 function createWindow() {
   mainWindow = new BrowserWindow({
+    ...titleBarOptions(),
     width: windowConfig.width,
     height: windowConfig.height,
     minWidth: windowConfig.minWidth,
     minHeight: windowConfig.minHeight,
     title: APP_NAME,
-    icon: path.join(__dirname, "assets", process.platform === "win32" ? "icon.ico" : "icon.png"),
+    icon: appIconPath(),
     show: false, // Don't show until ready (prevents flash)
     webPreferences: {
       nodeIntegration: false,
@@ -539,7 +582,12 @@ function createWindow() {
     },
   });
 
-  // Remove default menu bar
+  // No File/Edit/View menu: hiding the bar alone still lets Alt bring it back.
+  // macOS keeps its menu, which carries copy, paste and quit.
+  if (process.platform !== "darwin") {
+    Menu.setApplicationMenu(null);
+    installWindowKeys(mainWindow.webContents, { devTools: !app.isPackaged });
+  }
   mainWindow.setMenuBarVisibility(false);
 
   // Open external links in the default browser. The URL here is already
@@ -567,18 +615,27 @@ function createWindow() {
     reportBlockedLink(url);
   });
 
-  // ── Minimize-to-tray on close (C4 fix) ──────────────────────────────
-  // Intercept window close — hide instead of closing when tray mode is active
-  mainWindow.on("close", (event) => {
-    if (!isQuitting && trayManager && trayManager.minimizeToTray) {
-      event.preventDefault();
-      mainWindow.hide();
-      console.log("[main] Window hidden to tray");
-    }
+  // ── Minimize-to-tray on close (C4 fix), first-close notice, quit guard ──
+  attachWindowGuards(mainWindow, {
+    app,
+    guard: quitGuard,
+    getTray: () => trayManager,
+    isQuitting: () => isQuitting,
+    platform: process.platform,
+    reportNoticeError: (err) => {
+      console.error("[main] First-close notice failed:", err.message);
+      const where = process.platform === "darwin" ? "menu bar" : "tray";
+      dialog.showErrorBox(
+        "GAIA is still running",
+        `GAIA is still running in the ${where}. Quit from the ${where} menu to stop it.\n\n` +
+          `(The usual notice failed: ${err.message})`
+      );
+    },
   });
 
   mainWindow.on("closed", () => {
     mainWindow = null;
+    if (trayManager) trayManager.windowClosed();
   });
 
   // Show window when ready (unless --minimized or startMinimized config)
@@ -631,9 +688,9 @@ async function loadApp() {
              * src/styles/index.css, so the dark theme's role values are
              * mirrored here. Keep them in step with that file. */
             :root {
-              --bg-primary: #17161C;
-              --text-primary: #F0EDE7;
-              --text-secondary: #AAA5B0;
+              --bg-primary: #1A1917;
+              --text-primary: #EFECE6;
+              --text-secondary: #B3ADA5;
             }
             body {
               font-family: -apple-system, BlinkMacSystemFont, sans-serif;
@@ -664,6 +721,25 @@ async function loadApp() {
 
 // ── Services Setup ─────────────────────────────────────────────────────────
 
+/**
+ * Recreate the window after it was closed (macOS keeps the app running).
+ * Services are re-pointed at it, not re-created: their IPC handlers stay.
+ * @returns {Electron.BrowserWindow}
+ */
+function reopenWindow() {
+  createWindow();
+  // Asked for from the tray or the dock: show it even when starting minimized.
+  mainWindow.once("ready-to-show", () => mainWindow && mainWindow.show());
+  if (agentProcessManager) agentProcessManager.mainWindow = mainWindow;
+  if (trayManager) trayManager.mainWindow = mainWindow;
+  if (notificationService) notificationService.mainWindow = mainWindow;
+  loadApp().catch((err) => {
+    console.error("[main] Failed to load the reopened window:", err.message);
+    dialog.showErrorBox("GAIA", `GAIA couldn't reopen its window: ${err.message}`);
+  });
+  return mainWindow;
+}
+
 function initializeServices() {
   console.log("[main] Initializing services...");
 
@@ -676,8 +752,16 @@ function initializeServices() {
   });
 
   // T1: Tray Manager (system tray icon + context menu)
-  trayManager = new TrayManager(mainWindow, { backendPort });
+  trayManager = new TrayManager(mainWindow, {
+    backendPort,
+    reopenWindow: () => reopenWindow(),
+  });
   trayManager.create();
+  try {
+    trayManager.syncLoginItem();
+  } catch (err) {
+    console.error(`[main] Could not read the sign-in start setting: ${err.message}`);
+  }
 
   // T5: Notification Service (routes agent notifications to OS + renderer)
   notificationService = new NotificationService(
@@ -686,6 +770,9 @@ function initializeServices() {
     trayManager
   );
 
+  // #5226: hold off idle sleep while a chat turn runs
+  keepAwake = new KeepAwake();
+
   // #2007: System metrics for the observability dashboard
   systemMetrics.registerIpcHandlers();
 
@@ -732,8 +819,19 @@ function setupJumpList() {
 // ── Backend Bootstrap (Phase A) ───────────────────────────────────────────
 
 /** First install found a Lemonade already running: use it, or install GAIA's own? */
-async function chooseLemonadeInDialog(found) {
-  const { response } = await dialog.showMessageBox({
+async function chooseLemonadeInDialog(found, parent) {
+  // Modal to the progress window and in front: otherwise it can open behind
+  // other windows while the install sits at 70% waiting for it.
+  const owner = parent && !parent.isDestroyed() ? parent : null;
+  if (owner) {
+    if (owner.isMinimized()) owner.restore();
+    owner.show();
+    owner.moveTop();
+    owner.focus();
+    // Windows can refuse focus to a background app; the taskbar flash is the hint.
+    if (!owner.isFocused()) owner.flashFrame(true);
+  }
+  const box = {
     type: "question",
     title: "Lemonade Server found",
     message: `A Lemonade Server (v${found.version}) is already running at ${found.url}. Use it instead of installing GAIA's own?`,
@@ -742,7 +840,11 @@ async function chooseLemonadeInDialog(found) {
     defaultId: 0,
     cancelId: 1,
     noLink: true,
-  });
+  };
+  const { response } = owner
+    ? await dialog.showMessageBox(owner, box)
+    : await dialog.showMessageBox(box);
+  if (owner && !owner.isDestroyed()) owner.flashFrame(false);
   return response === 0 ? "external" : "gaia";
 }
 
@@ -793,7 +895,7 @@ async function bootstrapBackend() {
       await backendInstaller.ensureBackend({
         onProgress: progress.onProgress,
         isPackaged: app.isPackaged,
-        chooseLemonade: chooseLemonadeInDialog,
+        chooseLemonade: (found) => chooseLemonadeInDialog(found, progress.window),
       });
       progress.close();
       console.log("[main] Backend bootstrap complete");
@@ -1054,6 +1156,11 @@ if (!gotTheSingleInstanceLock) {
   process.exit(0);
 }
 
+// Before any window: the taskbar reads the ID when a window first appears.
+if (process.platform === "win32") {
+  app.setAppUserModelId(appUserModelId(app.isPackaged));
+}
+
 app.on("second-instance", (_event, argv, _cwd) => {
   // A second launch happened while we were running. Surface our window
   // (the user almost certainly wanted to see it). mainWindow may be null
@@ -1111,9 +1218,16 @@ app.whenReady().then(async () => {
   }
 
   // Start the Python backend
-  backendProcess = await startBackend();
+  if (shutdownStarted) return;
+  backendStarting = startBackend();
+  backendProcess = await backendStarting;
+  if (shutdownStarted) {
+    console.log("[main] Quit during startup — not opening the window");
+    return;
+  }
 
   // Create the window (hidden until ready-to-show)
+  titleDownloadSaveDialogs();
   createWindow();
   isBootstrapping = false; // progress dialog is gone; window-all-closed may now quit
 
@@ -1125,7 +1239,7 @@ app.whenReady().then(async () => {
   // Any failure here is logged and swallowed — the app continues to run
   // even if auto-update is unavailable.
   try {
-    autoUpdater.init(mainWindow);
+    autoUpdater.init(mainWindow, { confirmRestart: confirmUpdateRestart });
   } catch (err) {
     console.error(
       "[main] Failed to init auto-updater:",
@@ -1169,18 +1283,12 @@ app.whenReady().then(async () => {
     }
   }
 
-  app.on("activate", async () => {
+  // macOS and Linux: the shutdown is the OS's, so don't ask.
+  powerMonitor.on("shutdown", () => quitGuard.allow());
+
+  app.on("activate", () => {
     if (BrowserWindow.getAllWindows().length === 0) {
-      createWindow();
-      // Re-wire existing services to the new window (don't re-create — IPC handlers are already registered)
-      if (agentProcessManager) agentProcessManager.mainWindow = mainWindow;
-      if (trayManager) trayManager.mainWindow = mainWindow;
-      if (notificationService) notificationService.mainWindow = mainWindow;
-      try {
-        await loadApp();
-      } catch (err) {
-        console.error("[main] Failed to load app on activate:", err.message);
-      }
+      reopenWindow();
     } else if (mainWindow) {
       mainWindow.show();
     }
@@ -1215,33 +1323,57 @@ app.on("window-all-closed", () => {
 // Electron's before-quit does NOT await async handlers.
 // We use will-quit + event.preventDefault() to perform async cleanup, then re-quit.
 
-let cleanupDone = false;
-
-app.on("before-quit", () => {
-  isQuitting = true;
-  // Mark any subsequent backend exit as intentional so we don't pop the
-  // crash dialog during normal shutdown.
-  isIntentionalKill = true;
-});
+/** Only while the GAIA service runs: without it, no answer is running. */
+function workCanBeLost() {
+  return Boolean(trayManager && backendProcess);
+}
 
-app.on("will-quit", (event) => {
-  if (cleanupDone) return; // Cleanup already finished, let the app quit
+/** Ask about losing work in front of the window, even when it was hidden in the tray. */
+function askAboutRunningWork(action) {
+  return confirmQuit({
+    action,
+    getWork: () => fetchWorkInProgress(backendPort),
+    showMessageBox: (opts) => {
+      if (!mainWindow || mainWindow.isDestroyed()) return dialog.showMessageBox(opts);
+      if (!mainWindow.isVisible()) mainWindow.show();
+      return dialog.showMessageBox(mainWindow, opts);
+    },
+  });
+}
 
-  event.preventDefault(); // Prevent quit until cleanup is done
-  console.log("[main] will-quit: performing async cleanup...");
+/** The update dialog's "Restart now": the installer starts at once, so ask first. */
+function confirmUpdateRestart() {
+  return workCanBeLost() ? askAboutRunningWork(RESTART_FOR_UPDATE) : Promise.resolve(true);
+}
 
-  cleanup().then(() => {
-    cleanupDone = true;
-    console.log("[main] Cleanup complete, quitting...");
-    app.quit(); // Re-trigger quit — cleanupDone prevents infinite loop
-  }).catch((err) => {
-    console.error("[main] Cleanup error:", err.message);
-    cleanupDone = true;
-    app.quit();
-  });
+// Every quit asks first while an answer or index job would be lost; an
+// update restart (asked in confirmUpdateRestart) and an OS shutdown don't.
+const quitGuard = installQuitGuard({
+  app,
+  updater: electronAutoUpdater,
+  shouldAsk: () => !fatalQuitting && workCanBeLost(),
+  confirm: () => askAboutRunningWork(QUIT),
+  onQuitting: () => {
+    isQuitting = true;
+    // Mark any subsequent backend exit as intentional so we don't pop the
+    // crash dialog during normal shutdown.
+    isIntentionalKill = true;
+  },
+  onError: (err) => {
+    console.error("[main] Quit check failed:", err);
+    dialog.showErrorBox(
+      "GAIA",
+      `GAIA couldn't ask whether to stop the running work: ${err.message}\n\n` +
+        "Quit again within a minute to quit anyway; any answer still being written will be lost."
+    );
+  },
 });
 
+installQuitCleanup({ app, cleanup });
+
 async function cleanup() {
+  shutdownStarted = true;
+
   // Phase F: tear down auto-updater timers and IPC handlers.
   try {
     autoUpdater.destroy();
@@ -1258,24 +1390,48 @@ async function cleanup() {
     notificationService = null;
   }
 
-  // Stop all managed OS agents gracefully
-  if (agentProcessManager) {
-    console.log("Stopping all managed agents...");
-    try {
-      await agentProcessManager.stopAll();
-    } catch (err) {
-      console.error("Error stopping agents:", err.message);
-    }
-    agentProcessManager = null;
+  if (keepAwake) {
+    keepAwake.destroy();
+    keepAwake = null;
   }
 
+  // The agents and the backend stop side by side: each waits out its own
+  // grace period, and in series they could overrun the quit's time limit.
+  await Promise.all([stopAgentsForQuit(), stopBackendForQuit()]);
+
   // Destroy tray icon
   if (trayManager) {
     trayManager.destroy();
     trayManager = null;
   }
+}
+
+async function stopAgentsForQuit() {
+  if (!agentProcessManager) return;
+  console.log("Stopping all managed agents...");
+  try {
+    await agentProcessManager.stopAll();
+  } catch (err) {
+    console.error("Error stopping agents:", err.message);
+  }
+  agentProcessManager = null;
+}
+
+async function stopBackendForQuit() {
+  // A quit during startup: wait for the spawn so it can be stopped below.
+  if (backendStarting) {
+    try {
+      const started = await backendStarting;
+      if (started && !backendProcess && started.exitCode === null && started.signalCode === null) {
+        backendProcess = started;
+      }
+    } catch (err) {
+      console.error("[main] Backend start failed during quit:", err.message);
+    }
+  }
 
-  // Stop the Python backend via the port-manager (SIGTERM → wait 3 s → SIGKILL).
+  // Stop the Python backend and everything it started via the port-manager
+  // (SIGTERM → wait 3 s → SIGKILL).
   // F5: previously we did this inline; extracted so main.cjs stays lean and
   // to prevent orphan leaks across runs (issue #782).
   if (backendProcess) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amd-gaia/agent-ui",
-  "version": "0.25.0",
+  "version": "0.25.1-rc.10",
   "type": "module",
   "productName": "GAIA Agent UI",
   "description": "Chat with the GAIA agent - local and private by default on AMD Ryzen AI, cloud models when you choose them",
@@ -59,12 +59,14 @@
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:visual": "vite build && playwright test -c visual/playwright.config.ts",
     "gen:api-types": "node scripts/gen-api-types.mjs"
   },
   "dependencies": {
     "electron-updater": "^6.8.3"
   },
   "devDependencies": {
+    "@playwright/test": "1.63.0",
     "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",

package/preload.cjs

@@ -14,6 +14,7 @@
  *   install:*        — First-run backend install progress (Phase A)
  *   gaia:update:*    — Auto-update status & manual check (Phase F)
  *   system:*         — System metrics for the observability dashboard (#2007)
+ *   power:*          — Keep the PC awake while a chat turn runs (#5226)
  */
 
 const { contextBridge, ipcRenderer } = require("electron");
@@ -53,6 +54,10 @@ contextBridge.exposeInMainWorld("gaiaAPI", {
   tray: {
     getConfig: () => ipcRenderer.invoke("tray:get-config"),
     setConfig: (cfg) => ipcRenderer.invoke("tray:set-config", cfg),
+    // What GAIA is doing, for the tray icon, tooltip and menu.
+    setActivity: (activity) => ipcRenderer.invoke("tray:set-activity", activity),
+    // Tray menu actions: open-chat, new-chat, open-settings, refresh-status.
+    onCommand: (cb) => onEvent("tray:command", cb),
     onNavigate: (cb) => onEvent("tray:navigate", cb),
   },
 
@@ -63,6 +68,16 @@ contextBridge.exposeInMainWorld("gaiaAPI", {
     respondPermission: (id, action, remember) =>
       ipcRenderer.invoke("notification:respond", id, action, remember),
     onNotification: (cb) => onEvent("notification:new", cb),
+    // Chat alerts (#5226)
+    show: (payload) => ipcRenderer.invoke("notification:show", payload),
+    flash: () => ipcRenderer.invoke("notification:flash"),
+    setAttentionCount: (count) =>
+      ipcRenderer.invoke("notification:attention", count),
+  },
+
+  // ── Keep the PC awake while GAIA works (#5226) ────────────────────────
+  power: {
+    setKeepAwake: (on) => ipcRenderer.invoke("power:keep-awake", on),
   },
 
   // ── System metrics for the observability dashboard (#2007) ────────────
@@ -71,6 +86,15 @@ contextBridge.exposeInMainWorld("gaiaAPI", {
   },
 });
 
+// ── Window frame ─────────────────────────────────────────────────────────
+// The app draws its own top row; this says how the native controls sit in it.
+contextBridge.exposeInMainWorld("gaiaWindow", {
+  /** "mac": traffic lights at the top left; "overlay": controls at the top right. */
+  titleBar: process.platform === "darwin" ? "mac" : "overlay",
+  /** Match the native window controls to the app: { color, symbolColor } as #rrggbb. */
+  setColors: (colors) => ipcRenderer.invoke("window:set-titlebar-colors", colors),
+});
+
 // ── Install progress (Phase A) ──────────────────────────────────────────
 // Exposed as a separate global so the progress window can use it without
 // pulling in the full gaiaAPI surface (and so it keeps working if an