staysfixed 0.1.0

package/src/drive/cdp.js

@@ -0,0 +1,382 @@
+/**
+ * A tiny Chrome DevTools Protocol client.
+ *
+ * Chrome, Edge and Electron all speak the same protocol over one WebSocket, so
+ * this is the only "driver" the tool needs — no puppeteer, no playwright.
+ * Node 22 gives us `fetch` and `WebSocket` as globals, so there is nothing to install.
+ */
+
+import { StaysFixedError } from '../core/errors.js';
+import { warn } from '../core/log.js';
+
+/** Trim a trailing slash so `${endpoint}/json/version` never doubles up. */
+function tidyEndpoint(/** @type {string} */ endpoint) {
+  return String(endpoint).replace(/\/+$/, '');
+}
+
+/**
+ * Combine an optional caller signal with our own deadline, so a hung port
+ * cannot wedge a run forever.
+ * @param {number} timeoutMs
+ * @param {AbortSignal} [signal]
+ * @returns {AbortSignal}
+ */
+function deadline(timeoutMs, signal) {
+  const own = AbortSignal.timeout(timeoutMs);
+  return signal ? AbortSignal.any([own, signal]) : own;
+}
+
+/**
+ * @param {number} ms
+ * @returns {string}
+ */
+function seconds(ms) {
+  const s = Math.max(1, Math.round(ms / 1000));
+  return `${s} second${s === 1 ? '' : 's'}`;
+}
+
+/**
+ * Ask the app which WebSocket to talk to.
+ * @param {string} endpoint  e.g. "http://127.0.0.1:9333"
+ * @param {{timeoutMs?: number, signal?: AbortSignal}} [opts]
+ * @returns {Promise<{webSocketDebuggerUrl: string, Browser: string} & Record<string, any>>}
+ */
+export async function fetchVersion(endpoint, opts = {}) {
+  const base = tidyEndpoint(endpoint);
+  /** @type {Response} */
+  let res;
+  try {
+    res = await fetch(`${base}/json/version`, {
+      signal: deadline(opts.timeoutMs ?? 5000, opts.signal),
+      headers: { Accept: 'application/json' },
+    });
+  } catch (e) {
+    throw new StaysFixedError(`Nothing is answering at ${base}.`, {
+      hint: 'The app is either not running yet or is listening somewhere else.',
+      cause: e,
+    });
+  }
+  if (!res.ok) {
+    throw new StaysFixedError(
+      `The app answered on ${base} but would not say what it is (it replied ${res.status}).`,
+      { hint: 'Something else may be listening on that port. Pick another one with app.debugPort.' },
+    );
+  }
+  const body = /** @type {any} */ (await res.json());
+  if (!body || typeof body.webSocketDebuggerUrl !== 'string') {
+    throw new StaysFixedError(
+      `The app on ${base} did not offer a debug connection.`,
+      { hint: 'Start it with --remote-debugging-port so Stays Fixed can drive it.' },
+    );
+  }
+  return body;
+}
+
+/**
+ * Poll until the app opens its debug port. Apps take a moment to boot; this is
+ * the difference between "flaky" and "reliable" on a cold machine.
+ * @param {string} endpoint
+ * @param {{timeoutMs?: number, intervalMs?: number, signal?: AbortSignal}} [opts]
+ * @returns {Promise<{webSocketDebuggerUrl: string, Browser: string} & Record<string, any>>}
+ */
+export async function waitForEndpoint(endpoint, opts = {}) {
+  const base = tidyEndpoint(endpoint);
+  const timeoutMs = opts.timeoutMs ?? 60_000;
+  const intervalMs = opts.intervalMs ?? 200;
+  const until = Date.now() + timeoutMs;
+  /** @type {unknown} */
+  let last = null;
+
+  for (;;) {
+    if (opts.signal?.aborted) {
+      throw new StaysFixedError('Stopped while waiting for the app to open its debug port.');
+    }
+    try {
+      return await fetchVersion(base, { timeoutMs: Math.min(3000, timeoutMs), signal: opts.signal });
+    } catch (e) {
+      last = e;
+    }
+    if (Date.now() >= until) break;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+
+  throw new StaysFixedError(
+    `The app never opened its debug port at ${base}. Stays Fixed waited ${seconds(timeoutMs)}.`,
+    {
+      hint: 'Check that the app really starts (run the start command yourself), that it is not already running on that port, and that app.startTimeoutMs is long enough.',
+      cause: last,
+    },
+  );
+}
+
+/**
+ * List the tabs / windows the app is showing.
+ * @param {string} endpoint
+ * @returns {Promise<Array<{id: string, type: string, title: string, url: string, webSocketDebuggerUrl?: string, attached?: boolean}>>}
+ */
+export async function listTargets(endpoint) {
+  const base = tidyEndpoint(endpoint);
+  /** @type {Response} */
+  let res;
+  try {
+    res = await fetch(`${base}/json/list`, {
+      signal: deadline(5000),
+      headers: { Accept: 'application/json' },
+    });
+  } catch (e) {
+    throw new StaysFixedError(`Nothing is answering at ${base}, so Stays Fixed cannot see the app's windows.`, {
+      cause: e,
+    });
+  }
+  if (!res.ok) {
+    throw new StaysFixedError(
+      `Could not ask ${base} what windows it has open (it replied ${res.status}).`,
+    );
+  }
+  const body = /** @type {any} */ (await res.json());
+  if (!Array.isArray(body)) {
+    throw new StaysFixedError(`The app on ${base} sent back a window list Stays Fixed could not read.`);
+  }
+  return body;
+}
+
+/**
+ * Turn a CDP error object into something a human can act on.
+ * @param {string} method
+ * @param {any} err
+ */
+function protocolError(method, err) {
+  const detail = err && typeof err === 'object' ? String(err.message ?? 'no reason given') : String(err);
+  const extra = err && typeof err === 'object' && err.data ? ` (${String(err.data)})` : '';
+  return new StaysFixedError(`The app refused the request "${method}": ${detail}${extra}`);
+}
+
+/**
+ * Open a connection to the app and keep it alive.
+ * @param {string} webSocketDebuggerUrl
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {Promise<import('../types.js').CdpSession>}
+ */
+export async function connect(webSocketDebuggerUrl, opts = {}) {
+  const callTimeoutMs = opts.timeoutMs ?? 30_000;
+
+  /** @type {WebSocket} */
+  let ws;
+  try {
+    ws = new WebSocket(webSocketDebuggerUrl);
+  } catch (e) {
+    throw new StaysFixedError(`Stays Fixed could not open a debug connection to the app.`, { cause: e });
+  }
+
+  /** @type {Map<number, {resolve: (v: any) => void, reject: (e: unknown) => void, timer: ReturnType<typeof setTimeout>, method: string}>} */
+  const pending = new Map();
+  /** @type {Map<string, Set<(params: any, sessionId?: string) => void>>} */
+  const listeners = new Map();
+
+  let nextId = 0;
+  let shut = false;
+  let warnedAboutJunk = false;
+
+  // A socket with no error listener throws at the top level and kills the run.
+  ws.addEventListener('error', () => {});
+
+  /**
+   * @param {string} event
+   * @param {any} params
+   * @param {string|undefined} sessionId
+   */
+  function dispatch(event, params, sessionId) {
+    const exact = listeners.get(event);
+    if (exact) {
+      for (const handler of [...exact]) {
+        try {
+          handler(params, sessionId);
+        } catch {
+          // A misbehaving listener must never take the connection down with it.
+        }
+      }
+    }
+    const all = listeners.get('*');
+    if (all) {
+      for (const handler of [...all]) {
+        try {
+          handler({ method: event, params, sessionId }, sessionId);
+        } catch {
+          /* same */
+        }
+      }
+    }
+  }
+
+  ws.addEventListener('message', (/** @type {MessageEvent<any>} */ event) => {
+    // Screenshots come back as one very large text frame; parsing is the only cost.
+    const raw = typeof event.data === 'string' ? event.data : String(event.data ?? '');
+    /** @type {any} */
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      if (!warnedAboutJunk) {
+        warnedAboutJunk = true;
+        warn('The app sent something Stays Fixed could not read. Ignoring it and carrying on.');
+      }
+      return;
+    }
+    if (!msg || typeof msg !== 'object') return;
+
+    if (msg.id !== undefined && msg.id !== null) {
+      const entry = pending.get(msg.id);
+      if (!entry) return;
+      pending.delete(msg.id);
+      clearTimeout(entry.timer);
+      if (msg.error) entry.reject(protocolError(entry.method, msg.error));
+      else entry.resolve(msg.result ?? {});
+      return;
+    }
+
+    if (typeof msg.method === 'string') {
+      dispatch(msg.method, msg.params ?? {}, typeof msg.sessionId === 'string' ? msg.sessionId : undefined);
+    }
+  });
+
+  ws.addEventListener('close', () => {
+    shut = true;
+    const dead = new StaysFixedError(
+      "The app's debug connection closed while Stays Fixed was still talking to it.",
+      { hint: 'The app probably quit or crashed. Check that it stays open on its own.' },
+    );
+    for (const [id, entry] of pending) {
+      pending.delete(id);
+      clearTimeout(entry.timer);
+      entry.reject(dead);
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      done();
+      try {
+        ws.close();
+      } catch {
+        /* already gone */
+      }
+      reject(
+        new StaysFixedError('The app accepted a debug connection but never finished opening it.', {
+          hint: 'Try starting the app again, or give it longer with app.startTimeoutMs.',
+        }),
+      );
+    }, callTimeoutMs);
+
+    const onOpen = () => {
+      done();
+      resolve(undefined);
+    };
+    const onFail = () => {
+      done();
+      reject(
+        new StaysFixedError('Stays Fixed could not open a debug connection to the app.', {
+          hint: 'The app may have closed the port again. Check nothing else is using it.',
+        }),
+      );
+    };
+    function done() {
+      clearTimeout(timer);
+      ws.removeEventListener('open', onOpen);
+      ws.removeEventListener('error', onFail);
+      ws.removeEventListener('close', onFail);
+    }
+    ws.addEventListener('open', onOpen);
+    ws.addEventListener('error', onFail);
+    ws.addEventListener('close', onFail);
+  });
+
+  /**
+   * @param {string} method
+   * @param {Record<string, unknown>} [params]
+   * @param {string} [sessionId]
+   * @returns {Promise<any>}
+   */
+  function send(method, params, sessionId) {
+    if (shut || ws.readyState !== 1) {
+      return Promise.reject(
+        new StaysFixedError(
+          `Stays Fixed tried to ask the app for "${method}", but the debug connection is closed.`,
+        ),
+      );
+    }
+    const id = ++nextId;
+    /** @type {Record<string, unknown>} */
+    const message = { id, method, params: params ?? {} };
+    // Flat sessions: one socket, many pages, told apart only by this field.
+    if (sessionId) message.sessionId = sessionId;
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(
+          new StaysFixedError(`The app did not answer "${method}" within ${seconds(callTimeoutMs)}.`, {
+            hint: 'The page may be stuck on a dialog or a request that never finishes.',
+          }),
+        );
+      }, callTimeoutMs);
+      pending.set(id, { resolve, reject, timer, method });
+      try {
+        ws.send(JSON.stringify(message));
+      } catch (e) {
+        pending.delete(id);
+        clearTimeout(timer);
+        reject(new StaysFixedError(`Stays Fixed could not send "${method}" to the app.`, { cause: e }));
+      }
+    });
+  }
+
+  /**
+   * @param {string} event
+   * @param {(params: any, sessionId?: string) => void} handler
+   * @returns {() => void}
+   */
+  function on(event, handler) {
+    let set = listeners.get(event);
+    if (!set) {
+      set = new Set();
+      listeners.set(event, set);
+    }
+    set.add(handler);
+    return () => {
+      const current = listeners.get(event);
+      if (!current) return;
+      current.delete(handler);
+      if (current.size === 0) listeners.delete(event);
+    };
+  }
+
+  /** @returns {Promise<void>} */
+  function close() {
+    if (shut || ws.readyState === 3) {
+      shut = true;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      const finish = () => {
+        clearTimeout(timer);
+        ws.removeEventListener('close', finish);
+        shut = true;
+        resolve();
+      };
+      // Never hang a run on a socket that refuses to say goodbye.
+      const timer = setTimeout(finish, 2000);
+      ws.addEventListener('close', finish);
+      try {
+        ws.close();
+      } catch {
+        finish();
+      }
+    });
+  }
+
+  function isOpen() {
+    return !shut && ws.readyState === 1;
+  }
+
+  return { send, on, close, isOpen };
+}

package/src/drive/electron.js

@@ -0,0 +1,326 @@
+/**
+ * A real desktop app, opened and driven the same way a browser is.
+ *
+ * Electron is Chrome underneath, so the same debugging connection works — but
+ * two things are different and both bite. An Electron app ignores most of
+ * Chrome's command line, and an Electron app can have several windows, only one
+ * of which is the one a person means.
+ */
+
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { StaysFixedError, isExpected } from '../core/errors.js';
+import { detail } from '../core/log.js';
+import { DEFAULT_VIEWPORT } from '../core/config.js';
+
+const execFileAsync = promisify(execFile);
+import { waitForEndpoint, listTargets, connect } from './cdp.js';
+import { resolveElectronBinary, freePort } from './find.js';
+import { createPage } from './page.js';
+import { childEnv, delay, keepOutput, stopProcess } from './browser.js';
+
+/**
+ * The flags Electron actually honours at launch. The rest of Chrome's
+ * determinism switches are set from inside the page by the freeze layer.
+ * @param {Required<import('../types.js').ViewportConfig>} viewport
+ * @returns {string[]}
+ */
+function electronRenderingArgs(viewport) {
+  return [
+    // Same pixel grid every run.
+    `--force-device-scale-factor=${viewport.deviceScaleFactor}`,
+    '--force-color-profile=srgb',
+    '--disable-lcd-text',
+    '--font-render-hinting=none',
+    // No animation is half-finished at the moment of the shutter.
+    '--force-prefers-reduced-motion',
+    // A window that is behind another window gets slowed down, which turns
+    // "wait for the list" into a random timeout.
+    '--disable-background-timer-throttling',
+    '--disable-renderer-backgrounding',
+    '--disable-backgrounding-occluded-windows',
+  ];
+}
+
+/**
+ * @param {any[]} windows
+ * @returns {string|undefined}
+ */
+function describeWindows(windows) {
+  if (windows.length === 0) return undefined;
+  const lines = windows.map((w) => `  ${String(w.title ?? '(no title)')}  —  ${String(w.url ?? '')}`);
+  return `Windows the app has open right now:\n${lines.join('\n')}`;
+}
+
+/**
+ * Pick the window to drive.
+ * @param {string} endpoint
+ * @param {string|undefined} match
+ * @param {number} deadline epoch ms to give up at
+ * @returns {Promise<any>}
+ */
+async function findWindow(endpoint, match, deadline) {
+  /** @type {any[]} */
+  let pages = [];
+  for (;;) {
+    const targets = /** @type {any[]} */ (await listTargets(endpoint));
+    pages = targets.filter((t) => t && t.type === 'page');
+    if (match) {
+      const hit = pages.find(
+        (t) => String(t.title ?? '').includes(match) || String(t.url ?? '').includes(match),
+      );
+      if (hit) return hit;
+    } else {
+      const real = pages.find((t) => {
+        const url = String(t.url ?? '');
+        return !url.startsWith('devtools://') && url !== 'about:blank' && url !== '';
+      });
+      if (real) return real;
+    }
+    if (Date.now() > deadline) break;
+    // An Electron window is blank for the first moment of its life. Asking
+    // again a beat later is the difference between driving the app and
+    // photographing an empty rectangle.
+    await delay(250);
+  }
+
+  if (!match) {
+    // It stayed blank the whole time. Drive it anyway — an app whose window is
+    // genuinely empty is exactly the kind of thing a picture check should catch.
+    const blank = pages.find((t) => !String(t.url ?? '').startsWith('devtools://'));
+    if (blank) return blank;
+    throw new StaysFixedError('The app started but never opened a window to look at.', {
+      hint: 'If it shows a splash window first, give it longer with `app.startTimeoutMs`.',
+    });
+  }
+  throw new StaysFixedError(`The app has no window matching "${match}".`, {
+    hint: describeWindows(pages) ?? 'Check `app.windowMatch` against the real window title.',
+  });
+}
+
+/**
+ * Start a desktop app and attach to its main window.
+ * @param {import('../types.js').AppConfig} app
+ * @param {import('./browser.js').LaunchOptions} [opts]
+ * @returns {Promise<import('../types.js').LaunchedApp>}
+ */
+export async function launchElectron(app, opts = {}) {
+  if (opts.signal?.aborted) {
+    throw new StaysFixedError('Stopped before the app could start.');
+  }
+  if (!app.binary) {
+    throw new StaysFixedError('This app has no `app.binary`, so there is nothing to open.', {
+      hint: 'On macOS point it inside the bundle: /Applications/Your App.app/Contents/MacOS/Your App',
+    });
+  }
+
+  const binary = await resolveElectronBinary(app.binary);
+  const port = await freePort(app.debugPort);
+  const viewport = { ...DEFAULT_VIEWPORT, ...(opts.viewport ?? {}) };
+  const startTimeoutMs = app.startTimeoutMs ?? 60_000;
+  const extraArgs = app.args ?? [];
+
+  // Never point a real app at a real person's data. If the caller or the config
+  // already chose a profile we respect it; otherwise we make a scratch one and
+  // delete it afterwards.
+  const configured = extraArgs.some((a) => String(a).startsWith('--user-data-dir'));
+  const ownProfile = !opts.userDataDir && !configured;
+  const profileDir = opts.userDataDir ?? (ownProfile ? await fsp.mkdtemp(path.join(os.tmpdir(), 'staysfixed-app-')) : null);
+
+  /** @type {string[]} */
+  const args = [`--remote-debugging-port=${port}`, '--remote-allow-origins=*'];
+  if (profileDir) args.push(`--user-data-dir=${profileDir}`);
+  args.push(...electronRenderingArgs(viewport), ...extraArgs);
+
+  detail(`app: ${binary}`);
+  detail(`debugging port: ${port}`);
+
+  // Remember who had the screen, so we can give it straight back.
+  //
+  // Opening a desktop app takes the foreground, and a check that runs every few minutes
+  // takes it every few minutes — it steals the window out from under whatever the person
+  // was actually doing. The app still has to really open (it is being photographed, not
+  // simulated), but it does not have to be in front: the flags below keep it painting
+  // while it is behind another window, so the pictures are the same either way.
+  //
+  // Set `app.foreground: true` to watch it work instead.
+  const wantsFront = /** @type {any} */ (app).foreground === true;
+  const previousApp = wantsFront ? null : await frontmostApp();
+
+  const child = spawn(binary, args, {
+    cwd: app.cwd,
+    env: childEnv(app, opts),
+    stdio: ['ignore', 'pipe', 'pipe'],
+    signal: opts.signal,
+  });
+  const output = keepOutput(child);
+
+  const diedEarly = /** @type {Promise<never>} */ (
+    new Promise((_resolve, reject) => {
+      child.once('error', (cause) => {
+        reject(
+          new StaysFixedError(`Could not run the app at ${binary}.`, {
+            hint: 'Check `app.binary` points at the executable, not the folder.',
+            cause,
+          }),
+        );
+      });
+      child.once('exit', (code, signal) => {
+        reject(
+          new StaysFixedError(
+            `The app quit before it was ready (${signal ? `signal ${signal}` : `exit code ${code}`}).`,
+            { hint: output() ? `The last thing it said:\n${output()}` : undefined },
+          ),
+        );
+      });
+    })
+  );
+  // A normal quit later on must not crash the CLI with an unhandled rejection.
+  diedEarly.catch(() => {});
+
+  const endpoint = `http://127.0.0.1:${port}`;
+  /** @type {import('../types.js').CdpSession|null} */
+  let session = null;
+
+  try {
+    /** @type {any} */
+    let version;
+    try {
+      version = await Promise.race([
+        waitForEndpoint(endpoint, { timeoutMs: startTimeoutMs, intervalMs: 200 }),
+        diedEarly,
+      ]);
+    } catch (cause) {
+      if (isExpected(cause)) throw cause;
+      throw new StaysFixedError('The app started but never opened its debugging connection.', {
+        hint: output()
+          ? `The last thing it said:\n${output()}`
+          : 'Some apps only allow this in a development build. Check it starts with --remote-debugging-port by hand.',
+        cause,
+      });
+    }
+
+    const wsUrl = version?.webSocketDebuggerUrl;
+    if (!wsUrl) {
+      throw new StaysFixedError('The app answered but did not offer a debugging connection.');
+    }
+
+    const cdp = /** @type {import('../types.js').CdpSession} */ (await connect(wsUrl, { timeoutMs: 15_000 }));
+    session = cdp;
+
+    const chosen = await findWindow(endpoint, app.windowMatch, Date.now() + startTimeoutMs);
+    const targetId = String(chosen.id ?? chosen.targetId);
+    detail(`window: ${String(chosen.title ?? '(no title)')} — ${String(chosen.url ?? '')}`);
+
+    const attached = await cdp.send('Target.attachToTarget', { targetId, flatten: true });
+    const sessionId = String(attached.sessionId);
+    const page = await createPage(
+      cdp,
+      /** @type {any} */ ({ sessionId, targetId, baseUrl: app.url ?? null, timeoutMs: startTimeoutMs }),
+    );
+
+    /** @type {Promise<void>|null} */
+    let closing = null;
+    const close = () => {
+      // Safe to call twice: the second caller waits on the first close.
+      closing ??= (async () => {
+        try {
+          await cdp.send('Target.detachFromTarget', { sessionId });
+        } catch {
+          // The window may already be gone, which is where we were heading.
+        }
+        try {
+          await cdp.close();
+        } catch {
+          // Hanging up cannot meaningfully fail.
+        }
+        // A desktop app can take a moment to save its state on the way out, so
+        // it gets longer than a browser does before we insist.
+        await stopProcess(child, 5000);
+        if (ownProfile && profileDir) {
+          await fsp.rm(profileDir, { recursive: true, force: true }).catch(() => {});
+        }
+      })();
+      return closing;
+    };
+
+    // The window is up and answering; hand the screen back to whoever had it.
+    if (previousApp) await giveFocusBack(previousApp);
+
+    return { cdp, page, close, endpoint, pid: child.pid ?? null, kind: 'electron' };
+  } catch (e) {
+    // Half-launched means a leaked app window sitting on somebody's screen.
+    if (session) await session.close().catch(() => {});
+    await stopProcess(child, 2000);
+    if (ownProfile && profileDir) await fsp.rm(profileDir, { recursive: true, force: true }).catch(() => {});
+    throw e;
+  }
+}
+
+/**
+ * Every window the app currently has open. `staysfixed doctor` prints this so a
+ * person can see which one a check will drive, and what to put in `windowMatch`.
+ * @param {string} endpoint
+ * @returns {Promise<{id: string, title: string, url: string, type: string}[]>}
+ */
+export async function listElectronWindows(endpoint) {
+  const targets = /** @type {any[]} */ (await listTargets(endpoint));
+  const windows = targets.map((t) => ({
+    id: String(t?.id ?? t?.targetId ?? ''),
+    title: String(t?.title ?? ''),
+    url: String(t?.url ?? ''),
+    type: String(t?.type ?? ''),
+  }));
+  // Real windows first. An app also reports service workers and popups, and the
+  // first row a person reads should be the one a check would actually drive.
+  return windows.sort((a, b) => Number(b.type === 'page') - Number(a.type === 'page'));
+}
+
+/**
+ * The name of the application currently in front, on macOS. Null anywhere else.
+ *
+ * @returns {Promise<string|null>}
+ */
+async function frontmostApp() {
+  if (process.platform !== 'darwin') return null;
+  try {
+    const { stdout } = await execFileAsync(
+      'osascript',
+      ['-e', 'tell application "System Events" to get name of first application process whose frontmost is true'],
+      { timeout: 4000 },
+    );
+    const name = stdout.trim();
+    return name.length > 0 ? name : null;
+  } catch {
+    // No Apple Events permission, or no window server at all (CI). Not worth a word.
+    return null;
+  }
+}
+
+/**
+ * Put the screen back where it was before we opened anything.
+ *
+ * The app carries on running and carries on being photographed — the rendering flags it
+ * was launched with keep it painting while it sits behind another window. Bring it to the
+ * front yourself any time you want to watch it work.
+ *
+ * @param {string} name
+ * @returns {Promise<void>}
+ */
+async function giveFocusBack(name) {
+  if (process.platform !== 'darwin') return;
+  try {
+    await execFileAsync(
+      'osascript',
+      ['-e', `tell application "System Events" to set frontmost of first application process whose name is ${JSON.stringify(name)} to true`],
+      { timeout: 4000 },
+    );
+    detail(`left the screen with ${name}; the app is running behind it`);
+  } catch {
+    // Worst case the app keeps the foreground. Never a reason to fail a run.
+  }
+}