aegis-desktop 0.3.0 → 0.4.0

package/lib/local/tools.js

@@ -39,6 +39,7 @@
  */
 
 const { spawn } = require('node:child_process');
+const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 const { agentRoles } = require('./agents.js');
@@ -53,6 +54,11 @@ const GREP_SIZE_CAP = 10 * 1024 * 1024; // grep silently skips files above this
 const EXEC_TIMEOUT_DEFAULT = 120_000;
 const EXEC_TIMEOUT_CAP = 600_000; // 10 minutes, matches the CLI's cap
 const EXEC_MAX_BUFFER = 1_048_576; // 1 MB of combined stdout+stderr
+// The LCS diff below is O(lines_before * lines_after); past this many cells
+// (or this many lines on either side) the diff is skipped in favor of a
+// one-line summary rather than freezing the approval flow on a huge file.
+const DIFF_MAX_CELLS = 4_000_000;
+const DIFF_MAX_LINES = 20_000;
 
 /** Truncate oversized tool output (the model never needs the whole log). */
 function cap(s) {
@@ -332,28 +338,260 @@ function writeFile({ file_path, content } = {}) {
   }
 }
 
-function editFile({ file_path, old_string, new_string, replace_all } = {}) {
+function editFile(args = {}) {
+  try {
+    const preview = previewEditFile(args);
+    if (!preview.ok) return fail(preview.error);
+    fs.writeFileSync(args.file_path, preview.after, 'utf8');
+    return ok(`Edited ${args.file_path} (${preview.count} occurrence${preview.count > 1 ? 's' : ''} replaced)`);
+  } catch (e) {
+    return fail(e && e.message ? e.message : String(e));
+  }
+}
+
+// ── Approval-gate helpers ───────────────────────────────────────────────────
+//
+// The renderer approval gate (desktop/lib/local/engine.js gatedExecuteTool)
+// needs to show the user a diff BEFORE a mutating call runs, then re-verify
+// the file hasn't moved out from under it before actually writing. Everything
+// below is pure preparation: it never writes to disk on its own except
+// applyWriteChecked/applyEditChecked, which are the only functions engine.js
+// calls once the user has approved.
+
+/** exec/writeFile/editFile change machine state; listDir/glob/grep/readFile
+ *  never do — this is the set the approval gate checks against. */
+const MUTATING_TOOLS = new Set(['exec', 'writeFile', 'editFile']);
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(text == null ? '' : text, 'utf8').digest('hex');
+}
+
+/** Read a file for a preview/hash snapshot. Distinguishes "doesn't exist yet"
+ *  (ok, exists:false) from a real read failure (permissions, is a directory —
+ *  ok:false), so callers can tell a brand-new file from a broken path. */
+function readForPreview(file_path) {
+  try {
+    if (!fs.existsSync(file_path)) return { ok: true, exists: false, content: null };
+    if (fs.statSync(file_path).isDirectory()) {
+      return { ok: false, error: `${file_path} is a directory` };
+    }
+    return { ok: true, exists: true, content: fs.readFileSync(file_path, 'utf8') };
+  } catch (e) {
+    return { ok: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+/** Classic LCS line diff: returns the {type:'equal'|'delete'|'insert', a, b}
+ *  op list turning array `a` into array `b`, indices into each array. */
+function diffLines(a, b) {
+  const n = a.length;
+  const m = b.length;
+  const dp = new Array(n + 1);
+  for (let i = 0; i <= n; i++) dp[i] = new Int32Array(m + 1);
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    }
+  }
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ type: 'equal', a: i, b: j });
+      i++;
+      j++;
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      ops.push({ type: 'delete', a: i });
+      i++;
+    } else {
+      ops.push({ type: 'insert', b: j });
+      j++;
+    }
+  }
+  while (i < n) ops.push({ type: 'delete', a: i++ });
+  while (j < m) ops.push({ type: 'insert', b: j++ });
+  return ops;
+}
+
+/** Group an op list into unified-diff hunks (git diff -Ucontext style) and
+ *  render them as text with a/b line numbers in the @@ headers. */
+function formatUnifiedDiff(ops, a, b, { label, context }) {
+  const n = ops.length;
+  const keep = new Array(n).fill(false);
+  for (let i = 0; i < n; i++) {
+    if (ops[i].type === 'equal') continue;
+    keep[i] = true;
+    for (let k = 1; k <= context; k++) {
+      if (i - k >= 0) keep[i - k] = true;
+      if (i + k < n) keep[i + k] = true;
+    }
+  }
+  const hunkRanges = [];
+  let start = -1;
+  for (let i = 0; i <= n; i++) {
+    if (i < n && keep[i]) {
+      if (start === -1) start = i;
+    } else if (start !== -1) {
+      hunkRanges.push([start, i - 1]);
+      start = -1;
+    }
+  }
+  if (!hunkRanges.length) return `--- ${label}\n+++ ${label}\n(no changes)`;
+
+  const out = [`--- ${label}`, `+++ ${label}`];
+  for (const [s, e] of hunkRanges) {
+    let aLine = 1;
+    let bLine = 1;
+    for (let i = 0; i < s; i++) {
+      if (ops[i].type !== 'insert') aLine++;
+      if (ops[i].type !== 'delete') bLine++;
+    }
+    let aCount = 0;
+    let bCount = 0;
+    const body = [];
+    for (let i = s; i <= e; i++) {
+      const op = ops[i];
+      if (op.type === 'equal') {
+        body.push(` ${a[op.a]}`);
+        aCount++;
+        bCount++;
+      } else if (op.type === 'delete') {
+        body.push(`-${a[op.a]}`);
+        aCount++;
+      } else {
+        body.push(`+${b[op.b]}`);
+        bCount++;
+      }
+    }
+    out.push(`@@ -${aLine},${aCount} +${bLine},${bCount} @@`);
+    out.push(...body);
+  }
+  return out.join('\n');
+}
+
+/** Unified diff between two whole-file strings (`before` may be null — a new
+ *  file). Falls back to a one-line summary for files too large to diff cheaply. */
+function unifiedDiff(before, after, { label = 'file', context = 3 } = {}) {
+  const a = before == null ? [] : String(before).split('\n');
+  const b = after == null ? [] : String(after).split('\n');
+  if (a.length > DIFF_MAX_LINES || b.length > DIFF_MAX_LINES || a.length * b.length > DIFF_MAX_CELLS) {
+    const added = Math.max(0, b.length - a.length);
+    const removed = Math.max(0, a.length - b.length);
+    return `--- ${label}\n+++ ${label}\n@@ file too large to preview — approx +${added}/-${removed} lines @@`;
+  }
+  return formatUnifiedDiff(diffLines(a, b), a, b, { label, context });
+}
+
+/** Build the {before, after, diff, hash} preview for a writeFile call without
+ *  touching disk. `hash` is the sha256 of the CURRENT on-disk content (null
+ *  for a not-yet-existing file) — the snapshot applyWriteChecked re-verifies
+ *  against before actually writing. */
+function previewWriteFile({ file_path, content } = {}) {
+  if (!file_path) return { ok: false, error: 'file_path is required' };
+  const read = readForPreview(file_path);
+  if (!read.ok) return { ok: false, error: read.error };
+  const before = read.exists ? read.content : null;
+  const after = String(content == null ? '' : content);
+  return {
+    ok: true,
+    before,
+    after,
+    diff: unifiedDiff(before, after, { label: file_path }),
+    hash: before == null ? null : sha256(before),
+  };
+}
+
+/** Same shape as previewWriteFile, for editFile — shares its validation with
+ *  the executor above so there is exactly one place that knows how to apply
+ *  an edit. */
+function previewEditFile({ file_path, old_string, new_string, replace_all } = {}) {
+  if (!file_path) return { ok: false, error: 'file_path is required' };
+  if (old_string === undefined || old_string === '') {
+    return { ok: false, error: 'old_string is required and must be non-empty' };
+  }
+  const read = readForPreview(file_path);
+  if (!read.ok) return { ok: false, error: read.error };
+  if (!read.exists) return { ok: false, error: `${file_path} does not exist` };
+  const before = read.content;
+  const count = before.split(old_string).length - 1;
+  if (count === 0) return { ok: false, error: `old_string not found in ${file_path}` };
+  if (count > 1 && !replace_all) {
+    return { ok: false, error: `old_string is not unique (${count} matches) — use replace_all or more context` };
+  }
+  const after = replace_all
+    ? before.split(old_string).join(new_string == null ? '' : new_string)
+    : before.replace(old_string, new_string == null ? '' : new_string);
+  return {
+    ok: true,
+    before,
+    after,
+    diff: unifiedDiff(before, after, { label: file_path }),
+    hash: sha256(before),
+    count,
+  };
+}
+
+/** Dispatch a preview by tool name. Only writeFile/editFile have one — exec
+ *  has nothing to diff, and the approval gate skips this call for it. */
+function previewMutation(name, args) {
+  if (name === 'writeFile') return previewWriteFile(args);
+  if (name === 'editFile') return previewEditFile(args);
+  return { ok: false, error: `no diff preview for ${name}` };
+}
+
+/** Apply a writeFile the user has approved, but only if the file on disk
+ *  still matches the hash captured at preview time — otherwise something
+ *  else changed it while the approval card was open, and applying blind
+ *  would silently clobber that change. */
+function applyWriteChecked({ file_path, content } = {}, expectedHash) {
   try {
     if (!file_path) return fail('file_path is required');
-    if (old_string === undefined || old_string === '') {
-      return fail('old_string is required and must be non-empty');
+    const read = readForPreview(file_path);
+    if (!read.ok) return fail(read.error);
+    const currentHash = read.exists ? sha256(read.content) : null;
+    if (currentHash !== expectedHash) {
+      return fail(
+        `${file_path} changed on disk since the diff was shown — refusing to apply a stale write. Re-run writeFile to get an updated diff.`
+      );
     }
-    const src = fs.readFileSync(file_path, 'utf8');
-    const count = src.split(old_string).length - 1;
-    if (count === 0) return fail(`old_string not found in ${file_path}`);
-    if (count > 1 && !replace_all) {
-      return fail(`old_string is not unique (${count} matches) — use replace_all or more context`);
+    fs.mkdirSync(path.dirname(file_path), { recursive: true });
+    fs.writeFileSync(file_path, String(content == null ? '' : content), 'utf8');
+    return ok(`Wrote ${String(content == null ? '' : content).length} bytes to ${file_path}`);
+  } catch (e) {
+    return fail(e && e.message ? e.message : String(e));
+  }
+}
+
+/** Same guard as applyWriteChecked, for an already-computed editFile result
+ *  (`after` — the preview's replacement, not recomputed here since a hash
+ *  match means the source it was computed from is still exactly on disk). */
+function applyEditChecked({ file_path, after } = {}, expectedHash) {
+  try {
+    if (!file_path) return fail('file_path is required');
+    const read = readForPreview(file_path);
+    if (!read.ok) return fail(read.error);
+    const currentHash = read.exists ? sha256(read.content) : null;
+    if (currentHash !== expectedHash) {
+      return fail(
+        `${file_path} changed on disk since the diff was shown — refusing to apply a stale edit. Re-run editFile to get an updated diff.`
+      );
     }
-    const next = replace_all
-      ? src.split(old_string).join(new_string == null ? '' : new_string)
-      : src.replace(old_string, new_string == null ? '' : new_string);
-    fs.writeFileSync(file_path, next, 'utf8');
-    return ok(`Edited ${file_path} (${count} occurrence${count > 1 ? 's' : ''} replaced)`);
+    fs.writeFileSync(file_path, after, 'utf8');
+    return ok(`Edited ${file_path}`);
   } catch (e) {
     return fail(e && e.message ? e.message : String(e));
   }
 }
 
+/** Apply an approved writeFile/editFile call using the hash captured in its
+ *  `preview` (see previewMutation) — the single entry point engine.js calls
+ *  once the user has said yes. */
+function applyChecked(name, args, preview) {
+  if (name === 'writeFile') return applyWriteChecked(args, preview.hash);
+  return applyEditChecked({ file_path: args.file_path, after: preview.after }, preview.hash);
+}
+
 const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', '.aegiscode']);
 
 function listDir({ path: dir } = {}) {
@@ -626,6 +864,10 @@ module.exports = {
   executeTool,
   isTool,
   toolResultText,
+  // approval gate (desktop/lib/local/engine.js gatedExecuteTool)
+  MUTATING_TOOLS,
+  previewMutation,
+  applyChecked,
   // limits (unit tests assert against them instead of hard-coding numbers)
   OUTPUT_CAP,
   READ_LINE_CAP,
@@ -635,4 +877,6 @@ module.exports = {
   EXEC_TIMEOUT_DEFAULT,
   EXEC_TIMEOUT_CAP,
   EXEC_MAX_BUFFER,
+  DIFF_MAX_CELLS,
+  DIFF_MAX_LINES,
 };

package/lib/quick-launcher.js

@@ -0,0 +1,81 @@
+'use strict';
+
+/**
+ * quick-launcher.js — pure geometry + gating logic for the global quick-
+ * launcher popup (native desktop plumbing). Mirrors desktop/lib/window-state.js:
+ * no Electron import, so both functions unit-test without the Electron binary.
+ * main.js wires the result into a BrowserWindow + globalShortcut; this module
+ * only decides where the window should sit and whether the shortcut should be
+ * registered at all.
+ */
+
+/**
+ * A global shortcut is a machine-wide hook — every packaged build ships it,
+ * but a `npm start` dev run must NOT silently start grabbing a hotkey that
+ * might collide with whatever else the developer has running, unless they've
+ * explicitly opted in via the settings flag.
+ */
+function shouldEnableGlobalShortcut({ isPackaged, enabled } = {}) {
+  return Boolean(isPackaged) || Boolean(enabled);
+}
+
+/**
+ * Where the launcher window should land: centred on the cursor's current
+ * position, clamped so the whole window stays within that cursor's display
+ * work area (never straddling into an unplugged second monitor, never
+ * hanging off a screen edge). Falls back to centring on the first available
+ * display — or the given fallback rectangle — when there is no usable cursor
+ * point or display list (e.g. a headless test).
+ *
+ * `cursor` / `displays` take the plain shapes electron.screen already
+ * returns (`{x,y}` / `{workArea:{x,y,width,height}}`), so this stays pure and
+ * Electron-free for testing, exactly like window-state.js's clampToDisplay.
+ */
+function computeQuickLauncherBounds({ cursor, displays, size, fallback } = {}) {
+  const width = Math.max(1, (size && size.width) || 560);
+  const height = Math.max(1, (size && size.height) || 320);
+  const list = Array.isArray(displays) ? displays : [];
+  const point =
+    cursor && Number.isFinite(cursor.x) && Number.isFinite(cursor.y) ? cursor : null;
+
+  const containing = point
+    ? list.find((d) => {
+        const wa = d && d.workArea;
+        return (
+          wa &&
+          point.x >= wa.x &&
+          point.x < wa.x + wa.width &&
+          point.y >= wa.y &&
+          point.y < wa.y + wa.height
+        );
+      })
+    : null;
+
+  const target = containing || list[0] || null;
+  if (!target || !target.workArea) {
+    return {
+      x: (fallback && fallback.x) || 0,
+      y: (fallback && fallback.y) || 0,
+      width,
+      height,
+    };
+  }
+
+  const wa = target.workArea;
+  let x;
+  let y;
+  if (point) {
+    x = Math.round(point.x - width / 2);
+    y = Math.round(point.y - height / 2);
+  } else {
+    x = Math.round(wa.x + (wa.width - width) / 2);
+    y = Math.round(wa.y + (wa.height - height) / 2);
+  }
+
+  x = Math.min(Math.max(x, wa.x), Math.max(wa.x, wa.x + wa.width - width));
+  y = Math.min(Math.max(y, wa.y), Math.max(wa.y, wa.y + wa.height - height));
+
+  return { x, y, width, height };
+}
+
+module.exports = { shouldEnableGlobalShortcut, computeQuickLauncherBounds };

package/lib/settings.js

@@ -35,10 +35,31 @@ const AEGIS_KEY_NAMESPACE = '__aegis';
  *  migrateLegacyAegisKey() relocates it (and list() hides it meanwhile). */
 const LEGACY_AEGIS_NAMESPACE = 'aegis';
 
+/** Reserved namespace for the global quick-launcher shortcut config
+ *  ({ enabled, shortcut }) — app-level settings, not a provider, so it must
+ *  stay out of the provider CRUD surface for the same reason the AEGIS key
+ *  does (see AEGIS_KEY_NAMESPACE above). */
+const QUICK_LAUNCHER_NAMESPACE = '__quickLauncher';
+
+/** Default global shortcut: rare enough on both major platforms to avoid
+ *  fighting existing app/OS bindings, memorable enough to type once. */
+const DEFAULT_QUICK_LAUNCHER_SHORTCUT = 'CmdOrCtrl+Shift+Space';
+
+/** Reserved namespace for the tool-call approval ("confirm mode") preference:
+ *  `{ enabled }` — app-level, not a provider, so it stays out of the provider
+ *  CRUD surface for the same reason the AEGIS key does. Default is ON
+ *  (settings.getConfirmMode() === true when unset), which is the historical
+ *  behaviour: exec/writeFile/editFile always asked for approval.
+ *  NOTE: like the AEGIS key and the quick launcher, this lives in its own
+ *  top-level namespace — never inside a provider's `cfg[provider]` object. */
+const CONFIRM_MODE_NAMESPACE = '__confirmMode';
+
 /** Namespaces the provider-config surface must never see or mutate. */
 const RESERVED_NAMESPACES = Object.freeze([
   AEGIS_KEY_NAMESPACE,
   LEGACY_AEGIS_NAMESPACE,
+  QUICK_LAUNCHER_NAMESPACE,
+  CONFIRM_MODE_NAMESPACE,
 ]);
 
 /** True for the AEGIS-key namespace(s) — provider CRUD must refuse these. */
@@ -199,6 +220,54 @@ function createSettingsStore({ dir, safeStorage } = {}) {
     }
   }
 
+  // --- Quick launcher: reserved namespace, plain (unencrypted) config ------
+  // No secret lives here — just a bool and a shortcut string — so unlike the
+  // AEGIS key above there is nothing to encrypt/decrypt.
+
+  function quickLauncherConfig() {
+    const cfg = load()[QUICK_LAUNCHER_NAMESPACE] || {};
+    const shortcut =
+      typeof cfg.shortcut === 'string' && cfg.shortcut.trim()
+        ? cfg.shortcut.trim()
+        : DEFAULT_QUICK_LAUNCHER_SHORTCUT;
+    return { enabled: Boolean(cfg.enabled), shortcut };
+  }
+
+  function setQuickLauncherConfig({ enabled, shortcut } = {}) {
+    const data = load();
+    data[QUICK_LAUNCHER_NAMESPACE] = {
+      enabled: Boolean(enabled),
+      shortcut:
+        typeof shortcut === 'string' && shortcut.trim()
+          ? shortcut.trim()
+          : DEFAULT_QUICK_LAUNCHER_SHORTCUT,
+    };
+    save(data);
+    return quickLauncherConfig();
+  }
+
+  // --- Confirm mode: reserved namespace, plain (unencrypted) preference ----
+  // "Confirm before running tools" — the ON/OFF switch for the renderer's
+  // tool-call approval gate (desktop/lib/local/engine.js gatedExecuteTool).
+  // ON (default, and the behaviour shipped so far) means every mutating tool
+  // call — exec / writeFile / editFile — is previewed and approved by the user
+  // first. OFF means the engine runs them straight through, like a tool the
+  // session already allowed. Nothing secret is stored here, so no encryption.
+
+  function getConfirmMode() {
+    const cfg = load()[CONFIRM_MODE_NAMESPACE] || {};
+    // Unset === true: an existing install that never touched the toggle keeps
+    // the gate exactly as it was.
+    return cfg.enabled === undefined ? true : Boolean(cfg.enabled);
+  }
+
+  function setConfirmMode(enabled) {
+    const data = load();
+    data[CONFIRM_MODE_NAMESPACE] = { enabled: Boolean(enabled) };
+    save(data);
+    return getConfirmMode();
+  }
+
   return {
     file,
     get,
@@ -211,6 +280,10 @@ function createSettingsStore({ dir, safeStorage } = {}) {
     aegisRawKey,
     setAegisKey,
     migrateLegacyAegisKey,
+    quickLauncherConfig,
+    setQuickLauncherConfig,
+    getConfirmMode,
+    setConfirmMode,
   };
 }
 
@@ -218,6 +291,9 @@ module.exports = {
   SETTINGS_FILE,
   AEGIS_KEY_NAMESPACE,
   LEGACY_AEGIS_NAMESPACE,
+  QUICK_LAUNCHER_NAMESPACE,
+  CONFIRM_MODE_NAMESPACE,
+  DEFAULT_QUICK_LAUNCHER_SHORTCUT,
   RESERVED_NAMESPACES,
   isReservedNamespace,
   maskKey,

package/lib/sync/sessions.js

@@ -183,6 +183,31 @@ function mergeRemoteSessions(dir, remoteSessions) {
   return merged;
 }
 
+/**
+ * Markdown export (session export, plan: Save as.../Export session). Each
+ * message becomes a `## Role` heading followed by its content verbatim —
+ * content is never re-escaped or re-wrapped, so any code fences a message
+ * already contains (assistant replies routinely have them) survive untouched
+ * instead of being nested inside an outer fence.
+ */
+function toMarkdown(session) {
+  const title = (session && (session.title || session.id)) || 'session';
+  const messages = (session && Array.isArray(session.messages)) ? session.messages : [];
+  const lines = [`# ${title}`, ''];
+  for (const message of messages) {
+    const role = (message && message.role) || 'unknown';
+    const heading = role.charAt(0).toUpperCase() + role.slice(1);
+    const content = (message && (message.content || message.text)) || '';
+    lines.push(`## ${heading}`, '', content, '');
+  }
+  return lines.join('\n');
+}
+
+/** JSON export: the session record as stored, pretty-printed. */
+function toJson(session) {
+  return JSON.stringify(session, null, 2);
+}
+
 module.exports = {
   sessionsFile,
   load,
@@ -196,4 +221,6 @@ module.exports = {
   markPending,
   listPending,
   mergeRemoteSessions,
+  toMarkdown,
+  toJson,
 };

package/lib/window-state.js

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * window-state.js — persisted BrowserWindow bounds (native desktop plumbing).
+ * Pure Node + injectable dir, mirrors desktop/lib/sync/memory-queue.js: reads
+ * and writes <dir>/window-state.json, no Electron import, so it unit-tests
+ * without the Electron binary.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function stateFile(dir) {
+  return path.join(dir, 'window-state.json');
+}
+
+function load(dir) {
+  try {
+    const data = JSON.parse(fs.readFileSync(stateFile(dir), 'utf8'));
+    return data && typeof data === 'object' ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+function save(dir, state) {
+  const file = stateFile(dir);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * Clamp a saved rectangle so it always intersects at least one connected
+ * display's work area. A saved position from a monitor that has since been
+ * unplugged, or from a resolution that shrank, would otherwise place the
+ * window off every visible screen — it "opens" but is unreachable. `displays`
+ * takes plain `{ workArea: {x,y,width,height} }` objects (electron.screen's
+ * shape) so this stays pure and Electron-free for testing.
+ */
+function clampToDisplay(bounds, displays, fallback) {
+  if (!bounds || typeof bounds !== 'object') return { ...fallback };
+  const { x, y, width, height } = bounds;
+  if (![x, y, width, height].every((n) => Number.isFinite(n))) return { ...fallback };
+
+  const w = Math.max(1, width);
+  const h = Math.max(1, height);
+  const list = Array.isArray(displays) ? displays : [];
+
+  const visible = list.some((d) => {
+    const wa = d && d.workArea;
+    if (!wa) return false;
+    return x < wa.x + wa.width && x + w > wa.x && y < wa.y + wa.height && y + h > wa.y;
+  });
+
+  if (visible) return { x, y, width: w, height: h };
+  // Position is off every screen: keep the saved size but drop x/y so the
+  // caller's default centering (no x/y passed to BrowserWindow) takes over.
+  return { ...fallback, width: w, height: h };
+}
+
+module.exports = { stateFile, load, save, clampToDisplay };