@adecore/shell 0.39.0 → 0.40.1

package/dist/app-scheme.js

@@ -1,11 +1,7 @@
 import { realpath, readFile, stat } from 'node:fs/promises';
 import { extname, isAbsolute, join, relative, resolve } from 'node:path';
 import { appWindowNavigation, isAppSender, originOf } from './web-guards.js';
-/*
- * Standard and secure give the page a real origin and a secure context (WebCrypto), fetch and CORS let it
- * load from the scheme and talk to a backend, streaming serves big files, the code cache keeps compiled
- * scripts between starts, and a service worker needs its own privilege.
- */
+/* Standard and secure give the page a real origin and a secure context (WebCrypto); a service worker needs its own privilege. */
 export const APP_SCHEME_PRIVILEGES = {
     standard: true,
     secure: true,

package/dist/bridge/menu.js

@@ -1,8 +1,4 @@
-/*
- * The application menu, built by the page from what has the focus and drawn by the shell as a native
- * menu. The shell only knows these shapes; a click on a command comes back as its id, and the page
- * runs it.
- */
+/* The application menu, built by the page and drawn by the shell; a click on a command comes back as its id. */
 /* The native roles the shell accepts. Each still carries a label from the page, so the whole menu is
    in the language of the interface and not half in the system's. */
 export const MENU_ROLES = [

package/dist/menu.js

@@ -39,9 +39,8 @@ export const menuTemplateOf = (spec, options) => {
 };
 const withSeparator = (items) => (items.length > 0 ? [...items, { type: 'separator' }] : []);
 /*
- * The menu that stands until the page sends its own, again after a reload or a crash, and while no
- * window is open, so Quit is always there. The stock View menu without reload and the zoom roles: their accelerators are taken
- * before the page sees them, and a reload would drop the page's state without asking.
+ * The menu until the page sends its own, and while no window is open, so Quit is always there. The View
+ * menu leaves out reload and zoom: their keys are taken before the page sees them, and a reload drops its state.
  */
 export const staticMenuTemplate = (options) => {
     const platform = options.platform ?? process.platform;
@@ -78,10 +77,8 @@ export const staticMenuTemplate = (options) => {
     return [appMenu, ...fileMenu, { role: 'editMenu' }, viewMenu, { role: 'windowMenu' }];
 };
 /*
- * Runs a menu command in the page (`menu:run`), which runs it the way its own palette does. One fired by
- * a key the page already had is dropped: its own listeners answered it or let it pass on purpose. Only a
- * minimized window is shown: showing activates the app, and a pick from behind the person's work must
- * leave it there.
+ * Runs a menu command in the page (`menu:run`). One fired by a key the page already had is dropped: its
+ * listeners answered it or let it pass. Only a minimized window is shown, since showing activates the app.
  */
 export const createMenuCommands = (options) => (id, byKey) => {
     if (byKey && !(options.keyBypassesPage?.() ?? false) && options.pageKeys.take()) {

package/dist/page-keys.js

@@ -2,10 +2,8 @@
 export const PAGE_KEY_MS = 1000;
 /*
  * Whether a menu item that Electron says its accelerator fired answers a key the page already had.
- * Electron says so for every pick that is not a mouse click, so an item picked through accessibility
- * or with the keyboard inside the menu reads as fired by its key as well, and a key sent to the app
- * while none of its windows is key reaches the menu without the page ever seeing it. Only a key with
- * Cmd or Ctrl counts, since the menu binds no other.
+ * Electron says so for every pick that is not a mouse click, such as through accessibility, so only
+ * a key the page saw counts. Only Cmd or Ctrl keys, since the menu binds no other.
  */
 export const createPageKeys = (now = Date.now) => {
     // One entry per key, so a held key that repeats before the menu answers the first still answers each.

package/dist/theme.js

@@ -1,16 +1,11 @@
 /*
- * The theme the pages report, applied to what only the shell can paint: the ground of every window, so
- * a reload or a resize never flashes the other theme, the native controls off macOS, and the
- * `prefers-color-scheme` Chromium answers, which follows the app instead of the system it runs on.
- * A new window opens in the theme the others are in.
+ * The theme the pages report, applied to what only the shell paints: every window's ground, so a reload
+ * never flashes the other theme, the native controls off macOS, and Chromium's `prefers-color-scheme`.
  */
 export const createTheme = (options) => {
     const platform = options.platform ?? process.platform;
     let current = null;
-    /*
-     * The colors a page reports win over the ones per theme, so the controls stay on its ground after it
-     * changed and a window opened later starts on it too. Only the two colors are taken from what crossed IPC.
-     */
+    // The colors a page reports win over the ones per theme. Only the two colors are taken from what crossed IPC.
     const overlayOf = (theme) => {
         if (!options.overlay) {
             return undefined;

package/dist/updater.js

@@ -37,8 +37,7 @@ export const createUpdater = (options) => {
         }
     };
     const check = async () => {
-        // Nothing to learn while a check or a download runs, and a build already waiting to be installed
-        // does not get better for being asked about again.
+        // Nothing to learn while a check or a download runs, or while a build waits to be installed.
         if (!updater || state.status === 'checking' || state.status === 'downloading' || state.status === 'ready') {
             return;
         }
@@ -59,8 +58,7 @@ export const createUpdater = (options) => {
             }
             try {
                 const loaded = options.load();
-                // The page owns the preference and sends it before the first check, so nothing downloads
-                // behind the back of someone who turned it off.
+                // The page sends its preference before the first check, so nothing downloads for someone who turned it off.
                 loaded.autoDownload = false;
                 loaded.on('checking-for-update', () => setState({ status: 'checking', error: null, errorCode: null }));
                 loaded.on('update-available', (info) => setState({ status: 'available', version: info.version, error: null, errorCode: null }));

package/dist/window-state.js

@@ -6,10 +6,8 @@ const overlap = (a, b) => ({
     height: Math.max(0, Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y))
 });
 /*
- * The bounds to open a window with. Saved bounds stand as long as a display still shows enough of them
- * to grab, shrunk to that display's work area; a display that was unplugged or rearranged since leaves
- * them off screen, and then the window opens at its default size, which Electron centers. Null bounds
- * mean nothing was saved.
+ * Saved bounds stand while a display still shows enough of them to grab, shrunk to its work area;
+ * otherwise, or for null, the window opens at its default size, which Electron centers.
  */
 export const fitBounds = (saved, displays, defaults) => {
     if (saved) {
@@ -97,10 +95,7 @@ const parse = (text) => {
     }
     return windows;
 };
-/*
- * Keeps where each window stood, by a key the app chooses, so it opens there again: the size, the
- * place, maximized and full screen. Written a moment after a window stops moving and when it closes.
- */
+/* Keeps where each window stood by a key the app chooses, written a moment after it stops moving and when it closes. */
 export const createWindowState = (options) => {
     const delayMs = options.delayMs ?? 500;
     const later = options.setTimeout ?? ((run, ms) => setTimeout(run, ms));
@@ -127,9 +122,8 @@ export const createWindowState = (options) => {
         /* The bounds to construct the window with. `fallback` stands in for a key that has none saved, such as a spot beside another window. */
         bounds: (key, fallback = null) => fitBounds(windows.get(key) ?? fallback, options.displays(), options.defaults),
         /*
-         * Follows a window from now on and, once it is ready to show, maximizes it or puts it in full
-         * screen as it was left. Call it right after constructing the window, before it is shown. A key
-         * given as a function is asked at every change, for a window that comes to show something else.
+         * Call right after constructing the window, before it is shown; it is maximized or put in full screen
+         * as it was left. A key given as a function is asked at every change, for a window that shows another.
          */
         track: (key, window) => {
             const keyNow = typeof key === 'function' ? key : () => key;

package/dist/windows.js

@@ -53,7 +53,12 @@ export const createWindows = (options) => {
     let confirming = false;
     let installing = false;
     const later = options.setTimeout ?? ((run, ms) => setTimeout(run, ms));
-    const alive = () => [...entries.values()].filter((entry) => !entry.window.isDestroyed());
+    const isAlive = (entry) => entry !== undefined && !entry.window.isDestroyed();
+    const alive = () => [...entries.values()].filter(isAlive);
+    const frontToBack = () => order
+        .toReversed()
+        .map((id) => entries.get(id))
+        .filter(isAlive);
     const writeSession = () => {
         if (quitting) {
             return;
@@ -61,21 +66,13 @@ export const createWindows = (options) => {
         const shown = order.map((id) => entries.get(id));
         const keys = shown.map((entry) => entry?.key ?? null);
         const states = shown.map((entry) => entry?.state ?? null);
-        const file = states.some((state) => state !== null) ? { version: SESSION_VERSION, windows: keys, states } : { version: SESSION_VERSION, windows: keys };
+        const file = { version: SESSION_VERSION, windows: keys, ...(states.some((state) => state !== null) ? { states } : {}) };
         options.session.write(`${JSON.stringify(file, null, 2)}\n`);
     };
     const toFront = (id) => {
         order = [...order.filter((other) => other !== id), id];
     };
-    const focused = () => {
-        for (let i = order.length - 1; i >= 0; i--) {
-            const entry = entries.get(order[i]);
-            if (entry && !entry.window.isDestroyed()) {
-                return entry.window;
-            }
-        }
-        return null;
-    };
+    const focused = () => frontToBack()[0]?.window ?? null;
     const holderOf = (key) => alive().find((entry) => entry.key === key || entry.held.includes(key)) ?? null;
     /* Takes a key out of the window that has it, shown or kept. */
     const release = (entry, key) => {
@@ -275,19 +272,13 @@ export const createWindows = (options) => {
         /* The window that shows or keeps a key, if any. */
         holderOf: (key) => holderOf(key)?.window ?? null,
         /* The app window under a point on the screen, the one last in front first, leaving out `except`. */
-        windowAt: (point, except) => {
-            for (let i = order.length - 1; i >= 0; i--) {
-                const entry = entries.get(order[i]);
-                if (!entry || entry.window.isDestroyed() || entry.window === except || entry.window.isMinimized() || !entry.window.isVisible()) {
-                    continue;
-                }
-                const bounds = entry.window.getBounds();
-                if (point.x >= bounds.x && point.x < bounds.x + bounds.width && point.y >= bounds.y && point.y < bounds.y + bounds.height) {
-                    return entry.window;
-                }
+        windowAt: (point, except) => frontToBack().find(({ window }) => {
+            if (window === except || window.isMinimized() || !window.isVisible()) {
+                return false;
             }
-            return null;
-        },
+            const bounds = window.getBounds();
+            return point.x >= bounds.x && point.x < bounds.x + bounds.width && point.y >= bounds.y && point.y < bounds.y + bounds.height;
+        })?.window ?? null,
         /*
          * What a window's page keeps of itself across a quit, opaque to the shell, such as the tabs it
          * had. The session hands it back to `create` for that window; null keeps nothing.
@@ -339,12 +330,9 @@ export const createWindows = (options) => {
             }
         },
         /*
-         * What every app with this set of windows does with its app's events: a second instance raises
-         * the window in front, a click on the dock icon with no window open opens the last session's
-         * again, a quit that goes ahead keeps its windows in the session, pending bounds are written at
-         * quit, and off macOS the app quits with its last window while that window stays in the session.
-         * With `confirmQuit`, a quit waits for its answer. Call it before `app.whenReady()`, and
-         * `restore()` once ready.
+         * Follows the app's events: a second instance raises the window in front, the dock icon with no
+         * window reopens the last session, a quit keeps its windows in the session, and off macOS the app
+         * quits with its last window. Call it before `app.whenReady()`, and `restore()` once ready.
          */
         attach: (app, attachOptions = {}) => {
             const { confirmQuit } = attachOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/shell",
-  "version": "0.39.0",
+  "version": "0.40.1",
   "description": "The main process of an Electron app: its menu, its updater and the guards around its page.",
   "license": "FSL-1.1-MIT",
   "author": "Bas Milius",
@@ -50,10 +50,10 @@
     }
   },
   "devDependencies": {
-    "@types/bun": "^1.4.2",
-    "@types/node": "^24.13.6",
-    "electron": "^44.9.0",
-    "electron-updater": "^6.8.9",
+    "@types/bun": "^1.4.4",
+    "@types/node": "^24.19.2",
+    "electron": "^45.0.0",
+    "electron-updater": "^6.8.11",
     "typescript": "^7.0.2"
   }
 }

package/src/app-scheme.ts

@@ -3,11 +3,7 @@ import { extname, isAbsolute, join, relative, resolve } from 'node:path';
 import type { CustomScheme } from 'electron';
 import { appWindowNavigation, isAppSender, originOf, type NavigationVerdict, type SenderFrame } from './web-guards.ts';
 
-/*
- * Standard and secure give the page a real origin and a secure context (WebCrypto), fetch and CORS let it
- * load from the scheme and talk to a backend, streaming serves big files, the code cache keeps compiled
- * scripts between starts, and a service worker needs its own privilege.
- */
+/* Standard and secure give the page a real origin and a secure context (WebCrypto); a service worker needs its own privilege. */
 export const APP_SCHEME_PRIVILEGES: NonNullable<CustomScheme['privileges']> = {
     standard: true,
     secure: true,
@@ -102,27 +98,35 @@ const readWhole = async (file: string): Promise<Response> => new Response(new Ui
 /* The segments of a path as the URL carries them, decoded, or null when one could climb out or means nothing on its own. */
 export const segmentsOf = (pathname: string): string[] | null => {
     const path = pathname.replace(/^\/+/, '');
+
     if (path === '') {
         return [];
     }
+
     const segments: string[] = [];
+
     for (const raw of path.split('/')) {
         let segment: string;
+
         try {
             segment = decodeURIComponent(raw);
         } catch {
             return null;
         }
+
         if (segment === '' || segment === '.' || segment === '..' || /[/\\\0]/.test(segment)) {
             return null;
         }
+
         segments.push(segment);
     }
+
     return segments;
 };
 
 const isInside = (root: string, path: string): boolean => {
     const between = relative(root, path);
+
     return between !== '' && !between.startsWith('..') && !isAbsolute(between);
 };
 
@@ -144,36 +148,46 @@ export function createAppScheme(options: AppSchemeOptions): AppScheme {
 
     const serveFile = async (root: string, file: string, request: Request, headers: Record<string, string> = {}): Promise<Response> => {
         let found: string;
+
         try {
             const [realRoot, realFile] = await Promise.all([realpath(resolve(root)), realpath(resolve(file))]);
+
             if (!isInside(realRoot, realFile) || !(await stat(realFile)).isFile()) {
                 return notFound();
             }
+
             found = realFile;
         } catch {
             return notFound();
         }
+
         const response = await read(found, request);
         const merged = new Headers(response.headers);
         const type = CONTENT_TYPES[extname(found).toLowerCase()];
+
         if (type !== undefined) {
             merged.set('content-type', type);
         }
+
         for (const [name, value] of Object.entries(headers)) {
             merged.set(name, value);
         }
+
         return new Response(response.body, { status: response.status, statusText: response.statusText, headers: merged });
     };
 
     const serveFolder = (folder: SchemeFolder, request: Request, address: URL): Promise<Response> | Response => {
         const segments = segmentsOf(address.pathname);
+
         if (segments === null) {
             return notFound();
         }
+
         // A missing chunk with an extension stays a 404, so a stale one fails as a load error rather than as the page.
         const page = segments.length === 0 || (folder.routes === true && extname(segments.at(-1)!) === '');
         const file = page ? join(folder.root, 'index.html') : join(folder.root, ...segments);
         const headers = typeof folder.headers === 'function' ? folder.headers(file) : folder.headers;
+
         return serveFile(folder.root, file, request, headers);
     };
 
@@ -184,15 +198,19 @@ export function createAppScheme(options: AppSchemeOptions): AppScheme {
         privileged: { scheme, privileges: options.privileges ?? APP_SCHEME_PRIVILEGES },
         handle: async (request) => {
             let address: URL;
+
             try {
                 address = new URL(request.url);
             } catch {
                 return notFound();
             }
+
             const host = address.protocol === `${scheme}:` ? hosts.get(address.host.toLowerCase()) : undefined;
+
             if (host === undefined) {
                 return notFound();
             }
+
             return typeof host === 'function' ? host(request, address) : serveFolder(host, request, address);
         },
         serveFile,

package/src/bridge/menu.ts

@@ -1,8 +1,4 @@
-/*
- * The application menu, built by the page from what has the focus and drawn by the shell as a native
- * menu. The shell only knows these shapes; a click on a command comes back as its id, and the page
- * runs it.
- */
+/* The application menu, built by the page and drawn by the shell; a click on a command comes back as its id. */
 
 /* The native roles the shell accepts. Each still carries a label from the page, so the whole menu is
    in the language of the interface and not half in the system's. */

package/src/bridge/versions.ts

@@ -12,14 +12,18 @@ export const isVersion = (version: string): boolean => SEMVER.test(version);
 export const compareVersions = (a: string, b: string): number => {
     const left = SEMVER.exec(a);
     const right = SEMVER.exec(b);
+
     if (!left || !right) {
         return (left ? 1 : 0) - (right ? 1 : 0);
     }
+
     for (let i = 1; i <= 3; i++) {
         const difference = Number(left[i]) - Number(right[i]);
+
         if (difference !== 0) {
             return difference;
         }
     }
+
     return 0;
 };

package/src/menu.ts

@@ -18,7 +18,9 @@ export const menuTemplateOf = <Action extends string>(spec: MenuSpec<Action>, op
     if (!Array.isArray(spec?.menus)) {
         return null;
     }
+
     const platform = options.platform ?? process.platform;
+
     const itemOf = (node: MenuNode<Action>): MenuItemConstructorOptions | null => {
         switch (node.kind) {
             case 'separator':
@@ -42,8 +44,10 @@ export const menuTemplateOf = <Action extends string>(spec: MenuSpec<Action>, op
                 };
         }
     };
+
     const itemsOf = (nodes: readonly MenuNode<Action>[]): MenuItemConstructorOptions[] =>
         nodes.map(itemOf).filter((item): item is MenuItemConstructorOptions => item !== null);
+
     return spec.menus.map((menu) => ({
         label: menu.label,
         ...(menu.role !== undefined && MENU_BAR_ROLES.includes(menu.role) ? { role: menu.role } : {}),
@@ -66,15 +70,15 @@ export interface StaticMenuOptions {
 const withSeparator = (items: MenuItemConstructorOptions[]): MenuItemConstructorOptions[] => (items.length > 0 ? [...items, { type: 'separator' }] : []);
 
 /*
- * The menu that stands until the page sends its own, again after a reload or a crash, and while no
- * window is open, so Quit is always there. The stock View menu without reload and the zoom roles: their accelerators are taken
- * before the page sees them, and a reload would drop the page's state without asking.
+ * The menu until the page sends its own, and while no window is open, so Quit is always there. The View
+ * menu leaves out reload and zoom: their keys are taken before the page sees them, and a reload drops its state.
  */
 export const staticMenuTemplate = (options: StaticMenuOptions): MenuItemConstructorOptions[] => {
     const platform = options.platform ?? process.platform;
     const appItems = options.appItems ?? [];
     const quitItems = options.quitItems ?? [];
     const fileItems = options.fileItems ?? [];
+
     const appMenu: MenuItemConstructorOptions =
         platform === 'darwin'
             ? {
@@ -94,7 +98,9 @@ export const staticMenuTemplate = (options: StaticMenuOptions): MenuItemConstruc
             : fileItems.length > 0 || quitItems.length > 0
               ? { label: 'File', submenu: [...withSeparator(fileItems), ...withSeparator(quitItems), { role: 'quit' }] }
               : { role: 'fileMenu' };
+
     const fileMenu: MenuItemConstructorOptions[] = platform === 'darwin' && fileItems.length > 0 ? [{ label: 'File', submenu: fileItems }] : [];
+
     const viewMenu: MenuItemConstructorOptions = {
         label: 'View',
         submenu: [
@@ -103,6 +109,7 @@ export const staticMenuTemplate = (options: StaticMenuOptions): MenuItemConstruc
             { role: 'togglefullscreen' }
         ]
     };
+
     return [appMenu, ...fileMenu, { role: 'editMenu' }, viewMenu, { role: 'windowMenu' }];
 };
 
@@ -122,10 +129,8 @@ export interface MenuCommandOptions {
 }
 
 /*
- * Runs a menu command in the page (`menu:run`), which runs it the way its own palette does. One fired by
- * a key the page already had is dropped: its own listeners answered it or let it pass on purpose. Only a
- * minimized window is shown: showing activates the app, and a pick from behind the person's work must
- * leave it there.
+ * Runs a menu command in the page (`menu:run`). One fired by a key the page already had is dropped: its
+ * listeners answered it or let it pass. Only a minimized window is shown, since showing activates the app.
  */
 export const createMenuCommands =
     (options: MenuCommandOptions) =>
@@ -133,9 +138,12 @@ export const createMenuCommands =
         if (byKey && !(options.keyBypassesPage?.() ?? false) && options.pageKeys.take()) {
             return;
         }
+
         const window = options.window();
+
         if (window?.isMinimized()) {
             window.show();
         }
+
         window?.webContents.send('menu:run', id);
     };

package/src/page-keys.ts

@@ -10,14 +10,13 @@ export const PAGE_KEY_MS = 1000;
 
 /*
  * Whether a menu item that Electron says its accelerator fired answers a key the page already had.
- * Electron says so for every pick that is not a mouse click, so an item picked through accessibility
- * or with the keyboard inside the menu reads as fired by its key as well, and a key sent to the app
- * while none of its windows is key reaches the menu without the page ever seeing it. Only a key with
- * Cmd or Ctrl counts, since the menu binds no other.
+ * Electron says so for every pick that is not a mouse click, such as through accessibility, so only
+ * a key the page saw counts. Only Cmd or Ctrl keys, since the menu binds no other.
  */
 export const createPageKeys = (now: () => number = Date.now) => {
     // One entry per key, so a held key that repeats before the menu answers the first still answers each.
     let seen: number[] = [];
+
     return {
         saw: (key: PageKey): void => {
             if (key.type === 'keyDown' && (key.meta || key.control)) {
@@ -27,6 +26,7 @@ export const createPageKeys = (now: () => number = Date.now) => {
         take: (): boolean => {
             const since = now() - PAGE_KEY_MS;
             seen = seen.filter((at) => at >= since);
+
             return seen.shift() !== undefined;
         }
     };

package/src/theme.ts

@@ -20,24 +20,21 @@ export interface ThemeOptions {
 }
 
 /*
- * The theme the pages report, applied to what only the shell can paint: the ground of every window, so
- * a reload or a resize never flashes the other theme, the native controls off macOS, and the
- * `prefers-color-scheme` Chromium answers, which follows the app instead of the system it runs on.
- * A new window opens in the theme the others are in.
+ * The theme the pages report, applied to what only the shell paints: every window's ground, so a reload
+ * never flashes the other theme, the native controls off macOS, and Chromium's `prefers-color-scheme`.
  */
 export const createTheme = (options: ThemeOptions) => {
     const platform = options.platform ?? process.platform;
     let current: ThemeState | null = null;
 
-    /*
-     * The colors a page reports win over the ones per theme, so the controls stay on its ground after it
-     * changed and a window opened later starts on it too. Only the two colors are taken from what crossed IPC.
-     */
+    // The colors a page reports win over the ones per theme. Only the two colors are taken from what crossed IPC.
     const overlayOf = (theme: Pick<ThemeState, 'resolved' | 'overlay'>) => {
         if (!options.overlay) {
             return undefined;
         }
+
         const { color, symbolColor } = theme.overlay ?? options.overlay.colors[theme.resolved];
+
         return { height: options.overlay.height, color, symbolColor };
     };
 
@@ -46,13 +43,16 @@ export const createTheme = (options: ThemeOptions) => {
             current = theme;
             options.nativeTheme.themeSource = theme.followsSystem ? 'system' : theme.resolved;
             const overlay = platform === 'darwin' ? undefined : overlayOf(theme);
+
             for (const window of options.windows()) {
                 if (window.isDestroyed()) {
                     continue;
                 }
+
                 if (overlay) {
                     window.setTitleBarOverlay(overlay);
                 }
+
                 window.setBackgroundColor(theme.background);
             }
         },
@@ -62,10 +62,12 @@ export const createTheme = (options: ThemeOptions) => {
         /* The constructor options of a new window: its own chrome and the ground the others have. Dark until a page says otherwise. */
         windowOptions: (): BrowserWindowConstructorOptions => {
             const overlay = overlayOf(current ?? { resolved: 'dark' });
+
             const chrome: BrowserWindowConstructorOptions =
                 platform === 'darwin'
                     ? { titleBarStyle: 'hiddenInset', trafficLightPosition: options.trafficLights ?? { x: 17, y: 17 } }
                     : { titleBarStyle: 'hidden', ...(overlay ? { titleBarOverlay: overlay } : {}) };
+
             return { ...chrome, backgroundColor: current?.background ?? options.background };
         }
     };

package/src/updater.ts

@@ -11,9 +11,11 @@ export const UPDATE_INTERVAL_MS = 60 * 60 * 1000;
  */
 export const describeUpdateError = (message: string): { code: UpdateErrorCode; detail: string | null } => {
     const first = message.split('\n')[0]?.trim();
+
     if (!first) {
         return { code: 'failed', detail: null };
     }
+
     return {
         code: first.startsWith('404') ? 'no-feed' : 'failed',
         detail: first.length > 200 ? `${first.slice(0, 200)}…` : first
@@ -65,12 +67,13 @@ export const createUpdater = (options: UpdaterOptions) => {
     };
 
     const check = async (): Promise<void> => {
-        // Nothing to learn while a check or a download runs, and a build already waiting to be installed
-        // does not get better for being asked about again.
+        // Nothing to learn while a check or a download runs, or while a build waits to be installed.
         if (!updater || state.status === 'checking' || state.status === 'downloading' || state.status === 'ready') {
             return;
         }
+
         options.beforeCheck?.();
+
         try {
             await updater.checkForUpdates();
         } catch (e) {
@@ -86,21 +89,23 @@ export const createUpdater = (options: UpdaterOptions) => {
             if (!options.packaged) {
                 return;
             }
+
             try {
                 const loaded = options.load();
-                // The page owns the preference and sends it before the first check, so nothing downloads
-                // behind the back of someone who turned it off.
+                // The page sends its preference before the first check, so nothing downloads for someone who turned it off.
                 loaded.autoDownload = false;
                 loaded.on('checking-for-update', () => setState({ status: 'checking', error: null, errorCode: null }));
                 loaded.on('update-available', (info) => setState({ status: 'available', version: info.version, error: null, errorCode: null }));
                 loaded.on('update-not-available', () => setState({ status: 'current', version: undefined, error: null, errorCode: null }));
                 loaded.on('download-progress', (progress) => setState({ status: 'downloading', percent: progress.percent }));
                 loaded.on('update-downloaded', (info) => setState({ status: 'ready', version: info.version, percent: 100 }));
+
                 loaded.on('error', (e) => {
                     installFailed();
                     const { code, detail } = describeUpdateError(e.message);
                     setState({ status: 'error', error: detail, errorCode: code });
                 });
+
                 updater = loaded;
                 setState({ status: 'idle' });
             } catch (e) {
@@ -114,6 +119,7 @@ export const createUpdater = (options: UpdaterOptions) => {
             if (!updater) {
                 return;
             }
+
             updater.autoDownload = autoDownload === true;
             timer ??= every(() => void check(), UPDATE_INTERVAL_MS);
         },
@@ -124,6 +130,7 @@ export const createUpdater = (options: UpdaterOptions) => {
             if (!updater) {
                 return;
             }
+
             try {
                 await updater.downloadUpdate();
             } catch (e) {
@@ -136,14 +143,18 @@ export const createUpdater = (options: UpdaterOptions) => {
             if (!updater || state.status !== 'ready') {
                 return false;
             }
+
             installing = true;
             options.onQuit?.(true);
+
             try {
                 updater.quitAndInstall();
+
                 return true;
             } catch (e) {
                 log('Update install failed', e);
                 installFailed();
+
                 return false;
             }
         }

package/src/web-guards.ts

@@ -11,9 +11,11 @@ export const originOf = (url: string, schemes: readonly string[] = []): string |
     try {
         const parsed = new URL(url);
         const scheme = parsed.protocol.slice(0, -1);
+
         if (schemes.includes(scheme)) {
             return parsed.host ? `${scheme}://${parsed.host.toLowerCase()}` : null;
         }
+
         return parsed.origin === 'null' ? null : parsed.origin;
     } catch {
         return null;
@@ -38,6 +40,7 @@ export const appWindowNavigation = (url: string, appOrigin: string, schemes: rea
     if (isAppUrl(url, appOrigin, schemes)) {
         return 'allow';
     }
+
     return isWebLink(url) ? 'external' : 'refuse';
 };
 

package/src/window-state.ts

@@ -30,21 +30,22 @@ const overlap = (a: Rectangle, b: Rectangle): WindowSize => ({
 });
 
 /*
- * The bounds to open a window with. Saved bounds stand as long as a display still shows enough of them
- * to grab, shrunk to that display's work area; a display that was unplugged or rearranged since leaves
- * them off screen, and then the window opens at its default size, which Electron centers. Null bounds
- * mean nothing was saved.
+ * Saved bounds stand while a display still shows enough of them to grab, shrunk to its work area;
+ * otherwise, or for null, the window opens at its default size, which Electron centers.
  */
 export const fitBounds = (saved: Rectangle | null, displays: readonly WindowDisplay[], defaults: WindowSize): Partial<Rectangle> & WindowSize => {
     if (saved) {
         const display = displays.find(({ workArea }) => {
             const shared = overlap(saved, workArea);
+
             return shared.width >= Math.min(VISIBLE_EDGE.width, saved.width) && shared.height >= Math.min(VISIBLE_EDGE.height, saved.height);
         });
+
         if (display) {
             const area = display.workArea;
             const width = Math.min(saved.width, area.width);
             const height = Math.min(saved.height, area.height);
+
             return {
                 x: Math.min(Math.max(saved.x, area.x), area.x + area.width - width),
                 y: Math.min(Math.max(saved.y, area.y), area.y + area.height - height),
@@ -53,6 +54,7 @@ export const fitBounds = (saved: Rectangle | null, displays: readonly WindowDisp
             };
         }
     }
+
     return { width: defaults.width, height: defaults.height };
 };
 
@@ -79,11 +81,13 @@ export function renameRetrying(from: string, to: string, rename: (from: string,
     for (let attempt = 0; ; attempt++) {
         try {
             rename(from, to);
+
             return;
         } catch (e) {
             if (!isTransient(e) || attempt >= RENAME_RETRIES) {
                 throw e;
             }
+
             // A synchronous wait: the write runs in a timer of the main process and has no promise to wait on.
             Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, RENAME_RETRY_MS);
         }
@@ -122,21 +126,28 @@ const isSaved = (value: unknown): value is SavedWindow => {
     if (typeof value !== 'object' || value === null) {
         return false;
     }
+
     const saved = value as Record<string, unknown>;
+
     const whole = (key: string): boolean => Number.isInteger(saved[key]);
+
     return whole('x') && whole('y') && whole('width') && whole('height') && (saved.width as number) > 0 && (saved.height as number) > 0;
 };
 
 const parse = (text: string | null): Map<string, SavedWindow> => {
     const windows = new Map<string, SavedWindow>();
+
     if (text === null) {
         return windows;
     }
+
     try {
         const file = JSON.parse(text) as { version?: unknown; windows?: Record<string, unknown> };
+
         if (file.version !== FILE_VERSION || typeof file.windows !== 'object' || file.windows === null) {
             return windows;
         }
+
         for (const [key, value] of Object.entries(file.windows)) {
             if (isSaved(value)) {
                 windows.set(key, { ...value, maximized: value.maximized === true, fullScreen: value.fullScreen === true });
@@ -145,13 +156,11 @@ const parse = (text: string | null): Map<string, SavedWindow> => {
     } catch {
         // A file that does not parse is a first start: every window opens at its default.
     }
+
     return windows;
 };
 
-/*
- * Keeps where each window stood, by a key the app chooses, so it opens there again: the size, the
- * place, maximized and full screen. Written a moment after a window stops moving and when it closes.
- */
+/* Keeps where each window stood by a key the app chooses, written a moment after it stops moving and when it closes. */
 export const createWindowState = (options: WindowStateOptions) => {
     const delayMs = options.delayMs ?? 500;
     const later = options.setTimeout ?? ((run, ms) => setTimeout(run, ms));
@@ -164,6 +173,7 @@ export const createWindowState = (options: WindowStateOptions) => {
             cancel(timer);
             timer = null;
         }
+
         options.storage.write(`${JSON.stringify({ version: FILE_VERSION, windows: Object.fromEntries(windows) }, null, 2)}\n`);
     };
 
@@ -171,6 +181,7 @@ export const createWindowState = (options: WindowStateOptions) => {
         if (timer !== null) {
             cancel(timer);
         }
+
         timer = later(() => {
             timer = null;
             flush();
@@ -183,13 +194,13 @@ export const createWindowState = (options: WindowStateOptions) => {
             fitBounds(windows.get(key) ?? fallback, options.displays(), options.defaults),
 
         /*
-         * Follows a window from now on and, once it is ready to show, maximizes it or puts it in full
-         * screen as it was left. Call it right after constructing the window, before it is shown. A key
-         * given as a function is asked at every change, for a window that comes to show something else.
+         * Call right after constructing the window, before it is shown; it is maximized or put in full screen
+         * as it was left. A key given as a function is asked at every change, for a window that shows another.
          */
         track: (key: string | (() => string), window: StateWindow): void => {
             const keyNow = typeof key === 'function' ? key : () => key;
             const last = windows.get(keyNow());
+
             window.once('ready-to-show', () => {
                 if (last?.fullScreen) {
                     window.setFullScreen(true);
@@ -197,25 +208,31 @@ export const createWindowState = (options: WindowStateOptions) => {
                     window.maximize();
                 }
             });
+
             const remember = (): boolean => {
                 if (window.isDestroyed()) {
                     return false;
                 }
+
                 const bounds = window.getNormalBounds();
                 windows.set(keyNow(), { ...bounds, maximized: window.isMaximized(), fullScreen: window.isFullScreen() });
+
                 return true;
             };
+
             const changed = (): void => {
                 if (remember()) {
                     schedule();
                 }
             };
+
             window.on('resize', changed);
             window.on('move', changed);
             window.on('maximize', changed);
             window.on('unmaximize', changed);
             window.on('enter-full-screen', changed);
             window.on('leave-full-screen', changed);
+
             window.on('close', () => {
                 remember();
                 flush();

package/src/windows.ts

@@ -71,19 +71,26 @@ const parseSession = (text: string | null): SessionWindow[] => {
     if (text === null) {
         return [];
     }
+
     try {
         const file = JSON.parse(text) as { version?: unknown; windows?: unknown; states?: unknown };
+
         if (file.version !== SESSION_VERSION || !Array.isArray(file.windows)) {
             return [];
         }
+
         const states: unknown[] = Array.isArray(file.states) ? file.states : [];
+
         const windows = file.windows.flatMap((key: unknown, index): SessionWindow[] => {
             if (key !== null && (typeof key !== 'string' || key === '')) {
                 return [];
             }
+
             const state = states[index];
+
             return [{ key, state: typeof state === 'string' ? state : null }];
         });
+
         // A key belongs to one window, so a file that lists one twice keeps the last.
         return windows.filter(({ key }, index) => key === null || windows.findLastIndex((other) => other.key === key) === index);
     } catch {
@@ -114,16 +121,25 @@ export const createWindows = (options: WindowsOptions) => {
     let installing = false;
     const later = options.setTimeout ?? ((run, ms) => setTimeout(run, ms));
 
-    const alive = (): Entry[] => [...entries.values()].filter((entry) => !entry.window.isDestroyed());
+    const isAlive = (entry: Entry | undefined): entry is Entry => entry !== undefined && !entry.window.isDestroyed();
+
+    const alive = (): Entry[] => [...entries.values()].filter(isAlive);
+
+    const frontToBack = (): Entry[] =>
+        order
+            .toReversed()
+            .map((id) => entries.get(id))
+            .filter(isAlive);
 
     const writeSession = (): void => {
         if (quitting) {
             return;
         }
+
         const shown = order.map((id) => entries.get(id));
         const keys = shown.map((entry) => entry?.key ?? null);
         const states = shown.map((entry) => entry?.state ?? null);
-        const file = states.some((state) => state !== null) ? { version: SESSION_VERSION, windows: keys, states } : { version: SESSION_VERSION, windows: keys };
+        const file = { version: SESSION_VERSION, windows: keys, ...(states.some((state) => state !== null) ? { states } : {}) };
         options.session.write(`${JSON.stringify(file, null, 2)}\n`);
     };
 
@@ -131,15 +147,7 @@ export const createWindows = (options: WindowsOptions) => {
         order = [...order.filter((other) => other !== id), id];
     };
 
-    const focused = (): BrowserWindow | null => {
-        for (let i = order.length - 1; i >= 0; i--) {
-            const entry = entries.get(order[i]!);
-            if (entry && !entry.window.isDestroyed()) {
-                return entry.window;
-            }
-        }
-        return null;
-    };
+    const focused = (): BrowserWindow | null => frontToBack()[0]?.window ?? null;
 
     const holderOf = (key: string): Entry | null => alive().find((entry) => entry.key === key || entry.held.includes(key)) ?? null;
 
@@ -148,6 +156,7 @@ export const createWindows = (options: WindowsOptions) => {
         if (entry.key === key) {
             entry.key = null;
         }
+
         entry.held = entry.held.filter((other) => other !== key);
     };
 
@@ -157,20 +166,26 @@ export const createWindows = (options: WindowsOptions) => {
         if (window.isMinimized()) {
             window.restore();
         }
+
         window.show();
         window.focus();
     };
 
     const boundsFor = (key: string | null): Partial<Rectangle> & WindowSize => {
         const stateKey = key ?? UNKEYED_STATE;
+
         if (options.state.has(stateKey)) {
             return options.state.bounds(stateKey);
         }
+
         const front = focused();
+
         if (!front) {
             return options.state.bounds(options.formerKey !== undefined && options.state.has(options.formerKey) ? options.formerKey : stateKey);
         }
+
         const beside = front.getNormalBounds();
+
         return options.state.bounds(stateKey, { ...beside, x: beside.x + CASCADE, y: beside.y + CASCADE });
     };
 
@@ -182,11 +197,13 @@ export const createWindows = (options: WindowsOptions) => {
         entries.set(id, entry);
         toFront(id);
         options.state.track(() => entry.key ?? UNKEYED_STATE, window);
+
         // The order only decides which window comes back in front, so it is written with the next change rather than at every focus.
         window.on('focus', () => {
             toFront(id);
             options.onFront?.(window);
         });
+
         window.on('close', (event) => {
             if (quitsWithLastWindow && alive().length === 1) {
                 markQuit();
@@ -199,21 +216,27 @@ export const createWindows = (options: WindowsOptions) => {
                 }
             }
         });
+
         window.on('closed', () => {
             entries.delete(id);
             order = order.filter((other) => other !== id);
+
             for (const [guest, owner] of guestOwners) {
                 if (owner === id) {
                     guestOwners.delete(guest);
                 }
             }
+
             writeSession();
         });
+
         window.webContents.on('did-attach-webview', (_event, guest) => {
             guestOwners.set(guest.id, id);
             guest.once('destroyed', () => guestOwners.delete(guest.id));
         });
+
         writeSession();
+
         return window;
     };
 
@@ -225,10 +248,13 @@ export const createWindows = (options: WindowsOptions) => {
     const restore = (): void => {
         const windows = parseSession(options.session.read());
         started = true;
+
         if (windows.length === 0) {
             create(null, 'first');
+
             return;
         }
+
         for (const { key, state } of windows) {
             create(key, 'session', state);
         }
@@ -247,6 +273,7 @@ export const createWindows = (options: WindowsOptions) => {
         if (quitting && started && alive().length === 0) {
             restore();
         }
+
         resume();
     };
 
@@ -254,10 +281,13 @@ export const createWindows = (options: WindowsOptions) => {
         /* Raises the window that has the key, or opens one for it, at `at` when given. Null always opens a new window. */
         open: (key: string | null, at?: WindowPoint): BrowserWindow => {
             const holder = key === null ? null : holderOf(key);
+
             if (holder) {
                 raise(holder.window);
+
                 return holder.window;
             }
+
             return create(key, 'opened', null, at);
         },
 
@@ -270,16 +300,22 @@ export const createWindows = (options: WindowsOptions) => {
          */
         claim: (window: BrowserWindow, key: string | null): boolean => {
             const entry = entries.get(window.id);
+
             if (!entry) {
                 return false;
             }
+
             const holder = key === null ? null : holderOf(key);
+
             if (holder && holder !== entry) {
                 raise(holder.window);
+
                 return false;
             }
+
             entry.key = key;
             writeSession();
+
             return true;
         },
 
@@ -295,11 +331,14 @@ export const createWindows = (options: WindowsOptions) => {
          */
         move: (window: BrowserWindow, at?: WindowPoint): BrowserWindow | null => {
             const entry = entries.get(window.id);
+
             if (!entry || entry.key === null) {
                 return null;
             }
+
             const key = entry.key;
             release(entry, key);
+
             return create(key, 'opened', null, at);
         },
 
@@ -309,13 +348,17 @@ export const createWindows = (options: WindowsOptions) => {
          */
         hold: (window: BrowserWindow, keys: readonly string[]): string[] => {
             const entry = entries.get(window.id);
+
             if (!entry) {
                 return [];
             }
+
             entry.held = [...new Set(keys)].filter((key) => {
                 const holder = holderOf(key);
+
                 return holder === null || holder === entry;
             });
+
             return entry.held;
         },
 
@@ -325,11 +368,14 @@ export const createWindows = (options: WindowsOptions) => {
          */
         detach: (window: BrowserWindow, key: string, at?: WindowPoint): BrowserWindow | null => {
             const entry = entries.get(window.id);
+
             if (!entry || (entry.key !== key && !entry.held.includes(key))) {
                 return null;
             }
+
             release(entry, key);
             writeSession();
+
             return create(key, 'opened', null, at);
         },
 
@@ -339,17 +385,23 @@ export const createWindows = (options: WindowsOptions) => {
          */
         transfer: (key: string, window: BrowserWindow): boolean => {
             const target = entries.get(window.id);
+
             if (!target) {
                 return false;
             }
+
             const holder = holderOf(key);
+
             if (holder !== null && holder !== target) {
                 release(holder, key);
             }
+
             if (!target.held.includes(key)) {
                 target.held = [...target.held, key];
             }
+
             writeSession();
+
             return true;
         },
 
@@ -357,19 +409,16 @@ export const createWindows = (options: WindowsOptions) => {
         holderOf: (key: string): BrowserWindow | null => holderOf(key)?.window ?? null,
 
         /* The app window under a point on the screen, the one last in front first, leaving out `except`. */
-        windowAt: (point: WindowPoint, except?: BrowserWindow): BrowserWindow | null => {
-            for (let i = order.length - 1; i >= 0; i--) {
-                const entry = entries.get(order[i]!);
-                if (!entry || entry.window.isDestroyed() || entry.window === except || entry.window.isMinimized() || !entry.window.isVisible()) {
-                    continue;
-                }
-                const bounds = entry.window.getBounds();
-                if (point.x >= bounds.x && point.x < bounds.x + bounds.width && point.y >= bounds.y && point.y < bounds.y + bounds.height) {
-                    return entry.window;
+        windowAt: (point: WindowPoint, except?: BrowserWindow): BrowserWindow | null =>
+            frontToBack().find(({ window }) => {
+                if (window === except || window.isMinimized() || !window.isVisible()) {
+                    return false;
                 }
-            }
-            return null;
-        },
+
+                const bounds = window.getBounds();
+
+                return point.x >= bounds.x && point.x < bounds.x + bounds.width && point.y >= bounds.y && point.y < bounds.y + bounds.height;
+            })?.window ?? null,
 
         /*
          * What a window's page keeps of itself across a quit, opaque to the shell, such as the tabs it
@@ -377,9 +426,11 @@ export const createWindows = (options: WindowsOptions) => {
          */
         setState: (window: BrowserWindow, state: string | null): void => {
             const entry = entries.get(window.id);
+
             if (!entry || entry.state === state) {
                 return;
             }
+
             entry.state = state;
             writeSession();
         },
@@ -387,9 +438,11 @@ export const createWindows = (options: WindowsOptions) => {
         /* The window a page or a `<webview>` inside it belongs to, such as whose menu a guest opens. Not a check of who may speak for the app: that is `fromPage`. */
         fromContents: (contents: WebContents): BrowserWindow | null => {
             const guestOwner = guestOwners.get(contents.id);
+
             if (guestOwner !== undefined) {
                 return entries.get(guestOwner)?.window ?? null;
             }
+
             return pageWindow(contents);
         },
 
@@ -429,54 +482,65 @@ export const createWindows = (options: WindowsOptions) => {
         },
 
         /*
-         * What every app with this set of windows does with its app's events: a second instance raises
-         * the window in front, a click on the dock icon with no window open opens the last session's
-         * again, a quit that goes ahead keeps its windows in the session, pending bounds are written at
-         * quit, and off macOS the app quits with its last window while that window stays in the session.
-         * With `confirmQuit`, a quit waits for its answer. Call it before `app.whenReady()`, and
-         * `restore()` once ready.
+         * Follows the app's events: a second instance raises the window in front, the dock icon with no
+         * window reopens the last session, a quit keeps its windows in the session, and off macOS the app
+         * quits with its last window. Call it before `app.whenReady()`, and `restore()` once ready.
          */
         attach: (app: Pick<App, 'on' | 'quit'>, attachOptions: AttachOptions = {}): void => {
             const { confirmQuit } = attachOptions;
             const platform = options.platform ?? process.platform;
             quitsWithLastWindow = platform !== 'darwin';
+
             app.on('second-instance', () => {
                 const window = focused();
+
                 if (window) {
                     raise(window);
                 } else if (started) {
                     restore();
                 }
             });
+
             app.on('activate', () => {
                 if (started && alive().length === 0) {
                     restore();
                 }
             });
+
             app.on('before-quit', (event) => {
                 if (confirmQuit === undefined || quitConfirmed) {
                     quitEvent = event;
+
                     return;
                 }
+
                 event.preventDefault();
+
                 if (confirming) {
                     return;
                 }
+
                 confirming = true;
+
                 void new Promise<boolean>((resolve) => resolve(confirmQuit({ update: installing })))
                     .catch(() => true)
                     .then((go) => {
                         confirming = false;
+
                         if (!go) {
                             stay();
+
                             return;
                         }
+
                         quitConfirmed = true;
                         // A quit asked from inside this event would be undone by the one still running, so it waits for a task of its own.
                         later(() => app.quit(), 0);
                     });
             });
+
             app.on('will-quit', () => options.state.flush());
+
             app.on('window-all-closed', () => {
                 if (quitsWithLastWindow) {
                     app.quit();