roger-roger 0.1.0

package/skills/roger-roger/tray/main.mjs

@@ -0,0 +1,749 @@
+// The tray icon and the panel behind it.
+//
+// This process draws; it does not decide. Everything it shows comes from ~/.roger-roger/tray.json,
+// which the daemon keeps up to date, and everything it offers runs an ordinary `roger-roger` command.
+// So it can crash, be killed, or never be installed at all, and nothing else in the skill notices.
+//
+// The native part is @webviewjs/webview, installed on demand into ~/.roger-roger rather than vendored
+// here, so the skill itself stays a dependency-free Node script.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { execFileSync, spawn } from "node:child_process";
+
+// Decoded properly: a hand-trimmed URL pathname keeps its %20s and mangles UNC paths.
+const MAIN = fileURLToPath(import.meta.url);
+const HERE = path.dirname(MAIN);
+const CLI = path.join(HERE, "..", "scripts", "roger-roger.mjs");
+const HOME = process.env.ROGER_ROGER_HOME || path.join(os.homedir(), ".roger-roger");
+const SNAPSHOT = path.join(HOME, "tray.json");
+const PID_FILE = path.join(HOME, "tray.pid");
+
+// The daemon rewrites the snapshot every 15 seconds. Four missed beats and nobody is writing it.
+const STALE_MS = 60_000;
+
+const PANEL = { width: 360, height: 480, minWidth: 300, minHeight: 240, gap: 10 };
+
+// The size the user dragged the panel's edges to, kept across restarts like where they put it.
+const SIZE_FILE = path.join(HOME, "tray-size.json");
+
+function readSize() {
+  try {
+    const s = JSON.parse(fs.readFileSync(SIZE_FILE, "utf8"));
+    return s?.width >= PANEL.minWidth && s?.height >= PANEL.minHeight ? { width: s.width, height: s.height } : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeSize(size) {
+  try {
+    fs.writeFileSync(SIZE_FILE, JSON.stringify(size) + "\n", "utf8");
+  } catch (e) {
+    log(`could not remember the panel's size: ${e.message}`);
+  }
+}
+
+/** Load the native library from wherever it was installed, not from this repo. */
+async function loadWebview() {
+  const require = createRequire(path.join(HOME, "package.json"));
+  const entry = require.resolve("@webviewjs/webview");
+  return import(pathToFileURL(entry).href);
+}
+
+/** The self-contained panel. Nothing is fetched at runtime. */
+function panelHtml() {
+  return fs.readFileSync(path.join(HERE, "panel.html"), "utf8");
+}
+
+/**
+ * The environment a command from the tray runs in. The tray is often started from inside an agent's
+ * terminal and inherits its session variables, and a snooze pressed by hand must not be filed under
+ * whichever agent happened to launch the tray. So those go, and the command is told who is asking.
+ */
+function childEnv() {
+  const env = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (/_SESSION_ID$/.test(key)) continue;
+    if (/^(?:CLAUDE_CODE|CODEX|OPENCODE)_/.test(key)) continue;
+    if (key === "CLAUDE_PID" || key === "CLAUDECODE" || key === "AI_AGENT" || key === "ROGER_ROGER_AGENT_PID") continue;
+    env[key] = value;
+  }
+  env.ROGER_ROGER_CALLER = "tray";
+  return env;
+}
+
+// Run from HOME so a long-lived child never pins whatever directory the tray was started in.
+const childOptions = () => ({ cwd: HOME, env: childEnv(), windowsHide: true });
+
+/** Run an `roger-roger` command and forget about it: the daemon owns the outcome, not this process. */
+function run(...args) {
+  spawn(process.execPath, [CLI, ...args], { ...childOptions(), detached: true, stdio: "ignore" }).unref();
+}
+
+/**
+ * Run a command and say how it went: null when it worked, otherwise what went wrong. For settings,
+ * where a value `setup` refuses would otherwise vanish without a word and the control would just
+ * flick back on the next redraw.
+ */
+function runChecked(...args) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(process.execPath, [CLI, ...args], { ...childOptions(), stdio: ["ignore", "pipe", "pipe"] });
+    } catch (e) {
+      return resolve(e.message);
+    }
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => (stdout += chunk));
+    child.stderr.on("data", (chunk) => (stderr += chunk));
+    child.on("error", (e) => resolve(e.message));
+    child.on("close", (code) => {
+      let answer = null;
+      try {
+        answer = JSON.parse(stdout);
+      } catch {
+        // Not JSON; the exit code is all there is to go on.
+      }
+      if (code === 0 && answer?.ok !== false) return resolve(null);
+      const lastLine = (text) => text.trim().split(/\r?\n/).pop() || "";
+      resolve(answer?.error || lastLine(stderr) || lastLine(stdout) || `exited with code ${code}`);
+    });
+  });
+}
+
+const LOG = path.join(HOME, "tray.log");
+/** Nothing reads this process's output once it is detached, so anything worth knowing goes here. */
+function log(line) {
+  try {
+    fs.appendFileSync(LOG, `${new Date().toISOString()} ${line}\n`);
+  } catch {
+    // Logging must never be the thing that breaks the tray.
+  }
+}
+
+const read = () => {
+  try {
+    return JSON.parse(fs.readFileSync(SNAPSHOT, "utf8"));
+  } catch {
+    return { agents: [], questions: [], working: [], muted: {} };
+  }
+};
+
+/**
+ * A snapshot nobody is keeping up to date. The file outlives the daemon that wrote it, so without
+ * this a question answered an hour ago would keep the icon lit and the panel full of ghosts.
+ */
+function isStale(state, now = Date.now()) {
+  if (!state.daemon) return true;
+  const at = Date.parse(state.updatedAt);
+  return !Number.isFinite(at) || now - at > STALE_MS;
+}
+
+/**
+ * A 16×16 icon as raw RGBA, so there is no image file to ship or decode. A thick ring normally, a
+ * solid disc when somebody is waiting on an answer — both drawn opaque, because a tasteful hairline
+ * at this size is a smudge you cannot find. White, and a template on macOS so the menu bar recolours
+ * it to suit itself.
+ */
+function icon(alert) {
+  const size = 32; // Drawn at 32 and let the tray scale down: a 16px source on a scaled display
+  const data = Buffer.alloc(size * size * 4); // arrives upscaled and blurry, which reads as faint.
+  const c = (size - 1) / 2;
+  const outer = 14;
+  const inner = 7.2;
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      const d = Math.hypot(x - c, y - c);
+      // Solid to within half a pixel of each edge, then one pixel of softening so it reads as round.
+      const outside = Math.min(1, Math.max(0, outer - d));
+      const hole = alert ? 0 : Math.min(1, Math.max(0, inner - d));
+      const a = Math.max(0, outside - hole);
+      const i = (y * size + x) * 4;
+      data[i] = data[i + 1] = data[i + 2] = 255;
+      data[i + 3] = Math.round(a * 255);
+    }
+  }
+  return data;
+}
+
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+
+function tooltip(state, stale) {
+  if (stale) return "roger-roger — the daemon isn't running";
+  const agents = state.agents ?? [];
+  if (!agents.length) return "roger-roger — nothing running";
+  const waiting = (state.questions ?? []).length;
+  const parts = [plural(agents.length, "agent", "agents")];
+  if (waiting) parts.push(plural(waiting, "question", "questions"));
+  if (state.muted?.snoozeUntil) parts.push("snoozed");
+  return `roger-roger — ${parts.join(", ")}`;
+}
+
+/**
+ * The right-click menu is a menu: a few things you can do. Who is running belongs in the panel,
+ * where there is room to say what they are doing. Kept short and rebuilt only when it changes,
+ * because replacing a menu while it is open is how a menu ends up refusing to close.
+ */
+function menu(state, spot) {
+  const items = [];
+  if (state.muted?.snoozeUntil) {
+    items.push({ id: "snooze:off", label: "Stop snoozing" });
+  } else {
+    items.push({ id: "snooze:15m", label: "Snooze for 15 minutes" });
+    items.push({ id: "snooze:1h", label: "Snooze for an hour" });
+  }
+  // Dragged somewhere, the panel stays there; this is the way back.
+  if (spot) items.push({ id: "forget-spot", label: "Open the panel under the icon again" });
+  items.push({ id: "sep1", label: "-" }, { id: "quit", label: "Quit" });
+  return { items };
+}
+
+const menuKey = (state, spot) => `${state.muted?.snoozeUntil ? "snoozed" : "awake"}:${spot ? "spot" : "free"}`;
+
+function onMenu(id) {
+  if (id === "snooze:off") return run("snooze", "off");
+  if (id?.startsWith("snooze:")) return run("snooze", id.slice("snooze:".length));
+  return null;
+}
+
+/**
+ * Put the panel under the icon, and keep it on the screen the icon is on. That screen is found from
+ * the icon itself: the panel is parked off-screen between uses, so asking the panel which monitor it
+ * is on gets whichever one the operating system thinks is nearest to nowhere.
+ */
+// Where the user dragged the panel to, if they did. It opens there from then on, instead of under
+// the icon, until they choose "under the icon" on the right-click menu.
+const POSITION_FILE = path.join(HOME, "tray-position.json");
+
+function readSpot() {
+  try {
+    const p = JSON.parse(fs.readFileSync(POSITION_FILE, "utf8"));
+    return Number.isFinite(p?.x) && Number.isFinite(p?.y) ? { x: p.x, y: p.y } : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeSpot(pos) {
+  try {
+    if (pos) fs.writeFileSync(POSITION_FILE, JSON.stringify(pos) + "\n", "utf8");
+    else fs.rmSync(POSITION_FILE, { force: true });
+  } catch (e) {
+    log(`could not remember where the panel was put: ${e.message}`);
+  }
+}
+
+/**
+ * Put the panel where it was dragged to, if that is still on a screen. A monitor unplugged since
+ * would otherwise open it somewhere nobody can see, so then it goes back under the icon.
+ */
+function placeAtSpot(window, pos) {
+  if (!pos || typeof window.getMonitorFromPoint !== "function") return false;
+  let monitor = null;
+  try {
+    monitor = window.getMonitorFromPoint(pos.x + 40, pos.y + 20);
+  } catch {
+    return false;
+  }
+  if (!monitor) return false;
+  window.setPosition(pos.x, pos.y);
+  return true;
+}
+
+function placePanel(window, rect) {
+  if (!rect) return;
+  // Whatever size it is now, which is not the size it started at once the user has resized it.
+  let size = { width: PANEL.width, height: PANEL.height };
+  try {
+    size = window.getOuterSize();
+  } catch {
+    // The starting size is a fair guess.
+  }
+  let monitor = null;
+  try {
+    if (typeof window.getMonitorFromPoint === "function") {
+      monitor = window.getMonitorFromPoint(Math.round(rect.x + rect.width / 2), Math.round(rect.y + rect.height / 2));
+    }
+  } catch {
+    // Fall through to the older, vaguer answer.
+  }
+  if (!monitor && typeof window.getCurrentMonitor === "function") monitor = window.getCurrentMonitor();
+  const screen = monitor ? { x: monitor.position.x, y: monitor.position.y, w: monitor.size.width, h: monitor.size.height } : null;
+  const below = screen ? rect.y < screen.y + screen.h / 2 : true;
+  let x = Math.round(rect.x + rect.width / 2 - size.width / 2);
+  let y = below ? Math.round(rect.y + rect.height + PANEL.gap) : Math.round(rect.y - size.height - PANEL.gap);
+  if (screen) {
+    x = Math.min(Math.max(x, screen.x + PANEL.gap), screen.x + screen.w - size.width - PANEL.gap);
+    y = Math.min(Math.max(y, screen.y + PANEL.gap), screen.y + screen.h - size.height - PANEL.gap);
+  }
+  window.setPosition(x, y);
+}
+
+// ---------------------------------------------------------------- one tray at a time
+
+/**
+ * Whether `pid` is a tray running this very file. A live pid is not enough: Windows hands pids out
+ * again quickly, and a pid file left behind by a killed tray would otherwise make every new tray
+ * find some unrelated process behind it and quietly leave. So the process's command line is checked
+ * for this file's path. If the command line cannot be read at all, the pid is believed: two trays
+ * is the worse mistake.
+ */
+function isTray(pid) {
+  if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) return false;
+  try {
+    process.kill(pid, 0); // throws when nothing is there any more
+  } catch (e) {
+    if (e.code !== "EPERM") return false;
+  }
+  let args;
+  try {
+    args =
+      process.platform === "win32"
+        ? execFileSync(
+            "powershell.exe",
+            ["-NoProfile", "-NonInteractive", "-Command", `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CommandLine`],
+            { encoding: "utf8", windowsHide: true, timeout: 15_000 },
+          )
+        : execFileSync("ps", ["-o", "args=", "-p", String(pid)], { encoding: "utf8", timeout: 15_000 });
+  } catch (e) {
+    if (process.platform !== "win32" && e.status === 1) return false; // ps: no such process
+    log(`could not read the command line of pid ${pid}, so trusting the pid file: ${e.message}`);
+    return true;
+  }
+  // Slashes and, on Windows, case can differ between how it was started and how it is spelled here.
+  const norm = (s) => {
+    const flat = s.trim().replace(/[\\/]+/g, "/");
+    return process.platform === "win32" ? flat.toLowerCase() : flat;
+  };
+  return norm(args).includes(norm(MAIN));
+}
+
+/** What the pid file says: `{ pid, startedAt }`, or an older file with just the number in it. */
+function readPidFile() {
+  let raw;
+  try {
+    raw = fs.readFileSync(PID_FILE, "utf8");
+  } catch (e) {
+    return e.code === "ENOENT" ? { missing: true } : { raw: "" };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") return { ...parsed, raw };
+    return { pid: Number(parsed) || null, raw };
+  } catch {
+    return { pid: null, raw };
+  }
+}
+
+/**
+ * Take the pid file before doing anything slow, so two trays started together cannot both look,
+ * both find nobody, and both stay. `wx` makes the creation itself the decision: exactly one of them
+ * gets to make the file. A file that is already there is honoured only if a tray is really behind
+ * it; otherwise it is left over, and replaced.
+ *
+ * Returns what is already running (a pid, or "another tray" when it is too early to say which),
+ * or null once the file is ours.
+ */
+function claimPidFile() {
+  fs.mkdirSync(HOME, { recursive: true });
+  const mine = JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      fs.writeFileSync(PID_FILE, mine, { encoding: "utf8", flag: "wx" });
+      return null;
+    } catch (e) {
+      if (e.code !== "EEXIST") throw e;
+    }
+    const other = readPidFile();
+    if (other.missing) continue;
+    if (!other.pid) {
+      // Empty or half-written: most likely a tray that created the file a moment ago and has not
+      // filled it in yet. Only an old one is junk.
+      let age = Infinity;
+      try {
+        age = Date.now() - fs.statSync(PID_FILE).mtimeMs;
+      } catch {}
+      if (age < 5000) return "another tray";
+    } else if (isTray(other.pid)) {
+      return other.pid;
+    }
+    // Stale. Removed only if it still says what was judged stale, so a claim another tray made in
+    // the meantime is not the thing thrown away.
+    if (readPidFile().raw === other.raw) {
+      try {
+        fs.rmSync(PID_FILE, { force: true });
+      } catch {}
+    }
+  }
+  throw new Error(`could not claim ${PID_FILE}`);
+}
+
+/** Remove the pid file, but only while it is still ours: a newer tray may have claimed it since. */
+function releasePidFile() {
+  try {
+    if (readPidFile().pid === process.pid) fs.rmSync(PID_FILE, { force: true });
+  } catch {}
+}
+
+async function main() {
+  const running = claimPidFile();
+  if (running) {
+    process.stderr.write(`a tray is already running (pid ${running})\n`);
+    process.exit(0);
+  }
+  process.on("exit", releasePidFile);
+  const { Application } = await loadWebview();
+  const app = new Application();
+  await app.whenReady({ interval: 16, ref: true });
+
+  let state = read();
+  let stale = isStale(state);
+  let shown = false;
+  let spot = readSpot(); // where the user dragged the panel to, or null for under the icon
+  // Pinned with the button in its header: the panel stays up when you click elsewhere, and goes
+  // away only when you click the icon (or unpin it).
+  let keepOpen = false;
+  // Nobody is waiting on a question the daemon is not there to deliver.
+  const alerting = () => !stale && (state.questions ?? []).length > 0;
+  const renderScript = () => `window.render(${JSON.stringify({ ...state, stale })})`;
+
+  const tray = app.createTrayIcon({
+    id: "roger-roger",
+    icon: { data: icon(alerting()), width: 32, height: 32 },
+    tooltip: tooltip(state, stale),
+    menu: menu(state),
+    menuOnLeftClick: false,
+    menuOnRightClick: true,
+  });
+  if (process.platform === "darwin") tray.setIconAsTemplate(true);
+  // Belt and braces over the constructor options: left click belongs to the panel.
+  tray.setShowMenuOnLeftClick(false);
+  tray.setShowMenuOnRightClick(true);
+
+  // Built once, here, and never from inside an event handler: creating a window while the event
+  // loop is dispatching a click asks the native side to borrow the application twice, which it
+  // refuses. So the panel exists from the start, hidden, and a click only shows it.
+  let panel = null;
+  function buildPanel() {
+    const window = app.createBrowserWindow({
+      title: "roger-roger",
+      width: PANEL.width,
+      height: PANEL.height,
+      decorations: false,
+      transparent: true,
+      alwaysOnTop: true,
+      // Frameless, but its edges still resize it: the library leaves that to Windows.
+      resizable: true,
+      // The header is a title bar as far as Windows knows, and a double-click on one maximizes.
+      maximizable: false,
+      visible: false,
+      // The library's name for it. Plain `skipTaskbar` is silently ignored, which left the panel on
+      // the taskbar with Node's icon — and closing that button took the whole tray down with it.
+      windowsSkipTaskbar: true,
+      // What actually makes it see-through on Windows. Without it the window keeps an opaque
+      // backing surface and the translucent page is drawn over light grey: milky, not glass.
+      windowsNoRedirectionBitmap: true,
+      windowsUndecoratedShadow: true,
+    });
+    // Its own data directory, so it never argues with another webview on this machine over a lock.
+    const context = app.createWebContext({ dataDirectory: path.join(HOME, "webview") });
+    const webview = window.createWebview({ html: panelHtml(), transparent: true }, context);
+    // What the panel's buttons do. A link to a made-up scheme never reached us — the webview
+    // swallowed it — so the page asks over IPC instead, which is what it is for.
+    webview.onIpcMessage((message) => {
+      let ask;
+      try {
+        ask = JSON.parse(String(message?.body ?? message ?? ""));
+      } catch {
+        return log(`the panel said something I could not read: ${message?.body ?? message}`);
+      }
+      if (ask.do === "snooze") return run("snooze", ask.value || "1h");
+      if (ask.do === "hide") return hidePanel();
+      if (ask.do === "keep-open") {
+        keepOpen = Boolean(ask.value);
+        return;
+      }
+      // Anything `setup` understands, without this file having to know what any of it means.
+      if (ask.do === "set" && ask.flag) return applySetting(String(ask.flag), String(ask.value ?? ""));
+      if (ask.do === "test-voice") return testVoice();
+      if (ask.do === "refresh-voices") return refreshVoices();
+      log(`the panel asked for something I don't do: ${ask.do}`);
+    });
+    // Clicking away puts it away, like anything else hanging off a tray icon. Registered here
+    // because the window has to exist first — asking a null for its events does nothing, quietly.
+    window.on("blur", onBlur);
+    window.on("move", onMoved);
+    window.on("resize", onResized);
+    try {
+      window.setMinSize(PANEL.minWidth, PANEL.minHeight);
+      const saved = readSize();
+      if (saved) window.setSize(saved.width, saved.height);
+    } catch (e) {
+      log(`could not size the panel: ${e.message}`);
+    }
+    // The panel is never really closed, only put away. Alt+F4, or a close from anywhere else,
+    // would otherwise end the window and with it the tray the user never meant to quit.
+    window.on("close", (event) => {
+      event.preventDefault();
+      hidePanel();
+    });
+    return { window, webview };
+  }
+
+  /**
+   * One setting, as `--flag=value` in a single argument: a value that happens to start with `--`
+   * would otherwise be read as the next flag. A refusal is logged and shown in the panel. Success
+   * is left for the daemon to pick up, and the panel redrawn once it has had a moment to.
+   */
+  async function applySetting(flag, value) {
+    const problem = await runChecked("setup", `--${flag}=${value}`);
+    if (problem) {
+      log(`setup --${flag} was refused: ${problem}`);
+      const message = `Could not change ${flag}: ${problem}`;
+      if (panel) panel.webview.evaluateScript(`window.flash && window.flash(${JSON.stringify(message)})`);
+      return;
+    }
+    // A new provider, or a new place for its key: ask it what voices and models it has.
+    if (flag === "speech-provider" || flag === "speech-key-var") refreshVoices();
+    setTimeout(refresh, 500);
+  }
+
+  /**
+   * Ask the provider for its voices and models (the daemon keeps the answer, and the snapshot
+   * carries it). Only when there is a key to ask with; a missing key is already on screen.
+   */
+  let refreshingVoices = false;
+  async function refreshVoices() {
+    if (refreshingVoices) return;
+    refreshingVoices = true;
+    try {
+      // The setting may only just have been saved; let the snapshot say whether the key is there.
+      await new Promise((r) => setTimeout(r, 300));
+      const problem = await runChecked("voices", "--refresh");
+      if (problem && !/not set|empty/.test(problem)) {
+        log(`could not load voices: ${problem}`);
+        panel?.webview.evaluateScript(`window.flash && window.flash(${JSON.stringify(`Could not load voices: ${problem}`)})`);
+      }
+    } finally {
+      refreshingVoices = false;
+      setTimeout(refresh, 500);
+    }
+  }
+
+  /**
+   * Say something with the chosen provider, voice and key, and nothing else: `say --test` never
+   * falls back to the computer's own voice, so hearing it means it all works, and silence comes
+   * with a reason.
+   */
+  async function testVoice() {
+    const flash = (message, kind) => panel?.webview.evaluateScript(`window.flash && window.flash(${JSON.stringify(message)}, ${JSON.stringify(kind)})`);
+    const problem = await runChecked("say", "Roger roger. [short pause] This is how I sound.", "--test");
+    if (problem) {
+      log(`voice test failed: ${problem}`);
+      return flash(`Voice test failed: ${problem}`, "error");
+    }
+    const provider = (state.options?.speechProviders ?? []).find((p) => p.id === state.settings?.speechProvider)?.label ?? "The provider";
+    const used = state.settings?.speechKeyUsed;
+    flash(`${provider} spoke${used ? ` using ${used}` : ""}. It works.`, "ok");
+  }
+
+  let drawnAlert = null;
+  let drawnMenu = null;
+  const draw = () => {
+    const alert = alerting();
+    if (alert !== drawnAlert) {
+      tray.setIcon(icon(alert), 32, 32);
+      drawnAlert = alert;
+    }
+    tray.setTooltip(tooltip(state, stale));
+    const key = menuKey(state, spot);
+    if (key !== drawnMenu) {
+      tray.setMenu(menu(state, spot));
+      drawnMenu = key;
+    }
+    if (shown && panel) panel.webview.evaluateScript(renderScript());
+  };
+
+  // Staleness is worked out on every refresh, not only when the file changes: a daemon that has
+  // died is precisely one that has stopped changing it.
+  const refresh = () => {
+    state = read();
+    stale = isStale(state);
+    draw();
+  };
+
+  // fs.watch is the fast path and is unreliable on some platforms, so a slow poll backs it up.
+  try {
+    fs.watch(SNAPSHOT, { persistent: false }, refresh);
+  } catch {
+    // The file may not exist yet; the poll below will pick it up when it does.
+  }
+  const poll = setInterval(refresh, 2000);
+  poll.unref?.();
+
+  function quit() {
+    // Ending the event loop from inside one of its own callbacks can throw, and an exception here
+    // used to mean the process never got as far as leaving. Leaving is the part that matters.
+    log("quitting");
+    releasePidFile();
+    try {
+      app.exit();
+    } catch (e) {
+      log(`the event loop would not stop: ${e.message}`);
+    }
+    process.exit(0);
+  }
+
+  // Parked off-screen rather than hidden. Hiding a transparent window and showing it again loses
+  // the transparency on Windows — the composition is set up once, when the window appears — so it
+  // never disappears, it just goes somewhere nobody is looking.
+  function hidePanel() {
+    if (!shown || !panel) return;
+    shown = false;
+    panel.window.setPosition(-32000, -32000);
+  }
+
+  // A window that has just been told to show has not been given focus yet, and the blur that
+  // arrives in that moment is not the user clicking away — it is the window being born. Hiding on
+  // it is the flicker. Ignoring it outright, though, can strand the panel open when that really
+  // was the last blur it will get; so it is looked at again once the window has settled, and the
+  // panel put away then if it still does not have focus.
+  const BORN_MS = 500;
+  let shownAt = 0;
+  let blurCheck = null;
+  // When a blur last put the panel away. Clicking the icon of an open panel blurs the panel first,
+  // and without this the click that follows would open it straight back up.
+  let blurHiddenAt = 0;
+  function hideOnBlur() {
+    blurHiddenAt = Date.now();
+    hidePanel();
+  }
+  function onBlur() {
+    if (!shown || !panel || keepOpen) return;
+    const settling = BORN_MS - (Date.now() - shownAt);
+    if (settling <= 0) return hideOnBlur();
+    clearTimeout(blurCheck);
+    blurCheck = setTimeout(() => {
+      blurCheck = null;
+      let focused = false;
+      try {
+        focused = panel.window.isFocused();
+      } catch {}
+      if (shown && !focused) hideOnBlur();
+    }, settling + 50);
+  }
+
+  let lastClick = 0;
+  /**
+   * Where the panel lives once the user has dragged it. Windows moves the window itself (the header
+   * is its title bar), so all there is to do here is notice. Moves the tray makes — placing it when
+   * it opens, parking it when it closes — happen while it is closed or in the moment it opens, so
+   * a move while it is open and settled is the user's. Saved once the dragging stops.
+   */
+  let saveTimer = null;
+  function onMoved() {
+    if (!shown || !panel || Date.now() - shownAt < BORN_MS) return;
+    clearTimeout(saveTimer);
+    saveTimer = setTimeout(() => {
+      if (!shown) return;
+      const at = panel.window.getPosition();
+      spot = { x: at.x, y: at.y };
+      writeSpot(spot);
+      draw(); // the menu grows its way back under the icon
+    }, 400);
+  }
+
+  /** Resized by its edges: remember the size once the user lets go. Only the user resizes it. */
+  let sizeTimer = null;
+  function onResized() {
+    if (!panel) return;
+    clearTimeout(sizeTimer);
+    sizeTimer = setTimeout(() => {
+      try {
+        const { width, height } = panel.window.getOuterSize();
+        if (width >= PANEL.minWidth && height >= PANEL.minHeight) writeSize({ width, height });
+      } catch (e) {
+        log(`could not read the panel's size: ${e.message}`);
+      }
+    }, 400);
+  }
+
+  function forgetSpot() {
+    spot = null;
+    writeSpot(null);
+    draw();
+    if (!shown || !panel) return;
+    try {
+      placePanel(panel.window, tray.rect());
+    } catch (e) {
+      log(`could not place the panel: ${e.message}`);
+    }
+  }
+
+  function showPanel() {
+    if (!panel) return log("there is no panel to show; see the error above");
+    const now = Date.now();
+    if (now - lastClick < 350) return;
+    lastClick = now;
+    if (shown) return hidePanel();
+    // The blur from this same click has already put it away. The click meant "close", and it is.
+    if (now - blurHiddenAt < 300) return;
+    shown = true;
+    shownAt = Date.now();
+    refresh();
+    // A key that is there but whose provider hasn't been asked yet: ask now, while the panel is up.
+    if (state.settings?.speechKeyFound && !state.options?.speechCatalog?.fetchedAt) refreshVoices();
+    try {
+      if (!placeAtSpot(panel.window, spot)) placePanel(panel.window, tray.rect());
+    } catch (e) {
+      // A panel in the wrong place still beats no panel.
+      log(`could not place the panel: ${e.message}`);
+    }
+    panel.webview.evaluateScript(renderScript());
+    panel.window.show();
+    panel.window.focus();
+  }
+
+  // The native side reports a click for the press and again for the release, for every button.
+  // Only the left button's release opens the panel; the right one belongs to the menu. A field that
+  // is missing altogether counts as a yes, so a build that does not report them still works.
+  tray.on("click", (event) => {
+    const button = String(event?.button ?? "left").toLowerCase();
+    const buttonState = String(event?.buttonState ?? "up").toLowerCase();
+    if (button !== "left") return;
+    if (buttonState !== "up" && buttonState !== "released") return;
+    showPanel();
+  });
+
+  app.on("custom-menu-click", (event) => {
+    const id = event?.customMenuEvent?.id;
+    log(`menu: ${id ?? JSON.stringify(event)}`);
+    if (id === "quit") return quit();
+    if (id === "forget-spot") return forgetSpot();
+    onMenu(id);
+  });
+
+  try {
+    panel = buildPanel();
+    // Shown once, out of sight. A transparent window gets its composition when it first appears,
+    // and on Windows hiding it and showing it again does not get it back.
+    panel.window.setPosition(-32000, -32000);
+    panel.window.show();
+    // Again after showing: on Windows the taskbar button is created when the window first appears.
+    panel.window.setSkipTaskbar?.(true);
+  } catch (e) {
+    // The icon, its tooltip and its menu are all still worth having without it.
+    log(`the panel could not be built: ${e.stack ?? e.message}`);
+  }
+}
+
+main().catch((e) => {
+  log(`the tray could not start: ${e.stack ?? e.message}`);
+  process.stderr.write(`the tray could not start: ${e.stack ?? e.message}\n`);
+  process.exit(1);
+});