@adecore/shell 0.23.0 → 0.24.0

package/README.md

@@ -24,7 +24,7 @@ The package registers no IPC handler and listens to no app-wide Electron event.
 | Import | What it holds |
 |---|---|
 | `@adecore/shell` | For the main process: `createWindows`, `createWindowState`, `createUpdater`, `createTheme`, `menuTemplateOf`, `staticMenuTemplate`, `createMenuCommands`, `createPageKeys`, `createAppScheme` and the web guards |
-| `@adecore/shell/bridge` | The shapes that cross IPC: `MenuSpec`, `MenuNode`, `MENU_ROLES`, `UpdateState`, `ThemeState` and `compareVersions`. It imports nothing from Electron, so a preload and the page read it too. |
+| `@adecore/shell/bridge` | The shapes that cross IPC: `MenuSpec`, `MenuNode`, `MENU_ROLES`, `MENU_BAR_ROLES`, `UpdateState`, `ThemeState` and `compareVersions`. It imports nothing from Electron, so a preload and the page read it too. |
 
 ## Documentation
 

package/dist/bridge/index.d.ts

@@ -1,4 +1,4 @@
-export { MENU_ROLES, type MenuNode, type MenuRole, type MenuSpec } from './menu.ts';
+export { MENU_BAR_ROLES, MENU_ROLES, type MenuBarRole, type MenuNode, type MenuRole, type MenuSpec } from './menu.ts';
 export type { ThemeState } from './theme.ts';
-export type { UpdateState } from './update.ts';
+export type { UpdateErrorCode, UpdateState } from './update.ts';
 export { compareVersions, isVersion } from './versions.ts';

package/dist/bridge/index.js

@@ -2,5 +2,5 @@
  * The shapes that cross IPC between the shell and the page it hosts. Nothing here imports Electron, so
  * a preload and a page read them as well as the main process.
  */
-export { MENU_ROLES } from './menu.js';
+export { MENU_BAR_ROLES, MENU_ROLES } from './menu.js';
 export { compareVersions, isVersion } from './versions.js';

package/dist/bridge/menu.d.ts

@@ -1,5 +1,7 @@
 export declare const MENU_ROLES: readonly ['undo', 'redo', 'cut', 'copy', 'paste', 'selectAll', 'services', 'hide', 'hideOthers', 'unhide', 'minimize', 'zoom', 'front', 'close', 'quit', 'togglefullscreen'];
 export type MenuRole = (typeof MENU_ROLES)[number];
+export declare const MENU_BAR_ROLES: readonly ['window', 'help'];
+export type MenuBarRole = (typeof MENU_BAR_ROLES)[number];
 export type MenuNode<Action extends string = string> = {
     kind: 'command';
     id: string;
@@ -30,6 +32,7 @@ export interface MenuSpec<Action extends string = string> {
     menus: {
         id: string;
         label: string;
+        role?: MenuBarRole;
         items: MenuNode<Action>[];
     }[];
 }

package/dist/bridge/menu.js

@@ -23,3 +23,6 @@ export const MENU_ROLES = [
     'quit',
     'togglefullscreen'
 ];
+/* The roles a whole menu in the bar can take. On macOS `window` is where the system lists the open
+   windows and `help` gets the system's search field. */
+export const MENU_BAR_ROLES = ['window', 'help'];

package/dist/bridge/update.d.ts

@@ -1,7 +1,9 @@
+export type UpdateErrorCode = 'no-feed' | 'failed';
 export interface UpdateState {
     status: 'unsupported' | 'idle' | 'checking' | 'current' | 'available' | 'downloading' | 'ready' | 'error';
     currentVersion: string;
     version?: string;
     percent?: number;
     error?: string | null;
+    errorCode?: UpdateErrorCode | null;
 }

package/dist/index.d.ts

@@ -13,4 +13,4 @@ export type { SavedWindow, StateWindow, WindowDisplay, WindowSize, WindowState,
 export { createTheme } from './theme.ts';
 export type { Theme, ThemeOptions, TitleBarOverlay } from './theme.ts';
 export { CASCADE, createWindows, UNKEYED_STATE } from './windows.ts';
-export type { WindowOrigin, Windows, WindowsOptions } from './windows.ts';
+export type { AttachOptions, QuitRequest, WindowOrigin, WindowPoint, Windows, WindowsOptions } from './windows.ts';

package/dist/menu.d.ts

@@ -13,6 +13,7 @@ export interface StaticMenuOptions {
     toggleDevTools: () => void;
     appItems?: MenuItemConstructorOptions[];
     quitItems?: MenuItemConstructorOptions[];
+    fileItems?: MenuItemConstructorOptions[];
     platform?: NodeJS.Platform;
 }
 export declare const staticMenuTemplate: (options: StaticMenuOptions) => MenuItemConstructorOptions[];

package/dist/menu.js

@@ -1,4 +1,4 @@
-import { MENU_ROLES } from './bridge/menu.js';
+import { MENU_BAR_ROLES, MENU_ROLES } from './bridge/menu.js';
 /* Named instead of the role: that one follows the focused web contents, which is a guest page as soon as one has the keyboard. */
 export const devToolsAccelerator = (platform = process.platform) => (platform === 'darwin' ? 'Alt+Command+I' : 'Ctrl+Shift+I');
 /* The native menu of a spec the page sent, or null for a spec that is no menu at all. */
@@ -31,22 +31,28 @@ export const menuTemplateOf = (spec, options) => {
         }
     };
     const itemsOf = (nodes) => nodes.map(itemOf).filter((item) => item !== null);
-    return spec.menus.map((menu) => ({ label: menu.label, submenu: itemsOf(menu.items) }));
+    return spec.menus.map((menu) => ({
+        label: menu.label,
+        ...(menu.role !== undefined && MENU_BAR_ROLES.includes(menu.role) ? { role: menu.role } : {}),
+        submenu: itemsOf(menu.items)
+    }));
 };
+const withSeparator = (items) => (items.length > 0 ? [...items, { type: 'separator' }] : []);
 /*
- * The menu that stands until the page sends its own, and again after a reload or a crash, so Quit is
- * always there. The stock View menu without reload and the zoom roles: their accelerators are taken
+ * 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.
  */
 export const staticMenuTemplate = (options) => {
     const platform = options.platform ?? process.platform;
     const appItems = options.appItems ?? [];
     const quitItems = options.quitItems ?? [];
+    const fileItems = options.fileItems ?? [];
     const appMenu = platform === 'darwin'
         ? {
             label: options.appName,
             submenu: [
-                ...(appItems.length > 0 ? [...appItems, { type: 'separator' }] : []),
+                ...withSeparator(appItems),
                 { role: 'services' },
                 { type: 'separator' },
                 { role: 'hide' },
@@ -57,9 +63,10 @@ export const staticMenuTemplate = (options) => {
                 { role: 'quit' }
             ]
         }
-        : quitItems.length > 0
-            ? { label: 'File', submenu: [...quitItems, { type: 'separator' }, { role: 'quit' }] }
+        : fileItems.length > 0 || quitItems.length > 0
+            ? { label: 'File', submenu: [...withSeparator(fileItems), ...withSeparator(quitItems), { role: 'quit' }] }
             : { role: 'fileMenu' };
+    const fileMenu = platform === 'darwin' && fileItems.length > 0 ? [{ label: 'File', submenu: fileItems }] : [];
     const viewMenu = {
         label: 'View',
         submenu: [
@@ -68,7 +75,7 @@ export const staticMenuTemplate = (options) => {
             { role: 'togglefullscreen' }
         ]
     };
-    return [appMenu, { role: 'editMenu' }, viewMenu, { role: 'windowMenu' }];
+    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

package/dist/updater.d.ts

@@ -1,7 +1,10 @@
 import type { AppUpdater } from 'electron-updater';
-import type { UpdateState } from './bridge/update.ts';
+import type { UpdateErrorCode, UpdateState } from './bridge/update.ts';
 export declare const UPDATE_INTERVAL_MS: number;
-export declare const describeUpdateError: (message: string) => string;
+export declare const describeUpdateError: (message: string) => {
+    code: UpdateErrorCode;
+    detail: string | null;
+};
 export interface UpdaterOptions {
     currentVersion: string;
     packaged: boolean;

package/dist/updater.js

@@ -2,18 +2,18 @@
 export const UPDATE_INTERVAL_MS = 60 * 60 * 1000;
 /*
  * electron-updater puts the whole HTTP exchange in the message of a failed check: every response
- * header, the session cookie among them. Only the first line travels, and a 404 on the feed gets the
- * sentence that says what went wrong.
+ * header, the session cookie among them. Only the first line travels. The words are the page's, in
+ * the person's language, so the shell sends a code beside that line and no sentence of its own.
  */
 export const describeUpdateError = (message) => {
     const first = message.split('\n')[0]?.trim();
     if (!first) {
-        return 'No reason given.';
+        return { code: 'failed', detail: null };
     }
-    if (first.startsWith('404')) {
-        return 'No release feed found. There is no published release yet, or the repository is private.';
-    }
-    return first.length > 200 ? `${first.slice(0, 200)}…` : first;
+    return {
+        code: first.startsWith('404') ? 'no-feed' : 'failed',
+        detail: first.length > 200 ? `${first.slice(0, 200)}…` : first
+    };
 };
 /*
  * The updater as a state machine the page watches, not a dialog that interrupts. In a checkout the
@@ -62,14 +62,15 @@ export const createUpdater = (options) => {
                 // The page owns the preference and sends it before the first check, so nothing downloads
                 // behind the back of someone who turned it off.
                 loaded.autoDownload = false;
-                loaded.on('checking-for-update', () => setState({ status: 'checking', error: null }));
-                loaded.on('update-available', (info) => setState({ status: 'available', version: info.version, error: null }));
-                loaded.on('update-not-available', () => setState({ status: 'current', version: undefined, error: null }));
+                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();
-                    setState({ status: 'error', error: describeUpdateError(e.message) });
+                    const { code, detail } = describeUpdateError(e.message);
+                    setState({ status: 'error', error: detail, errorCode: code });
                 });
                 updater = loaded;
                 setState({ status: 'idle' });

package/dist/windows.d.ts

@@ -6,24 +6,42 @@ export type WindowOrigin = 'session' | 'first' | 'opened';
 export interface WindowsOptions {
     state: WindowState;
     session: WindowStateStorage;
-    create: (key: string | null, bounds: Partial<Rectangle> & WindowSize, origin: WindowOrigin) => BrowserWindow;
+    create: (key: string | null, bounds: Partial<Rectangle> & WindowSize, origin: WindowOrigin, state: string | null) => BrowserWindow;
     onFront?: (window: BrowserWindow) => void;
     formerKey?: string;
     platform?: NodeJS.Platform;
+    setTimeout?: (run: () => void, ms: number) => unknown;
+}
+export interface QuitRequest {
+    update: boolean;
+}
+export interface AttachOptions {
+    confirmQuit?: (request: QuitRequest) => boolean | Promise<boolean>;
+}
+export interface WindowPoint {
+    x: number;
+    y: number;
 }
 export declare const createWindows: (options: WindowsOptions) => {
-    open: (key: string | null) => BrowserWindow;
+    open: (key: string | null, at?: WindowPoint) => BrowserWindow;
     restore: () => void;
     claim: (window: BrowserWindow, key: string | null) => boolean;
     fromPage: (contents: WebContents) => BrowserWindow | null;
-    move: (window: BrowserWindow) => BrowserWindow | null;
+    move: (window: BrowserWindow, at?: WindowPoint) => BrowserWindow | null;
+    hold: (window: BrowserWindow, keys: readonly string[]) => string[];
+    detach: (window: BrowserWindow, key: string, at?: WindowPoint) => BrowserWindow | null;
+    transfer: (key: string, window: BrowserWindow) => boolean;
+    holderOf: (key: string) => BrowserWindow | null;
+    windowAt: (point: WindowPoint, except?: BrowserWindow) => BrowserWindow | null;
+    setState: (window: BrowserWindow, state: string | null) => void;
     fromContents: (contents: WebContents) => BrowserWindow | null;
     focused: () => BrowserWindow | null;
     keyOf: (window: BrowserWindow) => string | null;
     all: () => BrowserWindow[];
     send: (channel: string, ...args: unknown[]) => void;
     quit: () => void;
-    attach: (app: Pick<App, 'on' | 'quit'>) => void;
+    quitForUpdate: (going: boolean) => void;
+    attach: (app: Pick<App, 'on' | 'quit'>, attachOptions?: AttachOptions) => void;
     resume: () => void;
 };
 export type Windows = ReturnType<typeof createWindows>;

package/dist/windows.js

@@ -3,6 +3,10 @@ export const UNKEYED_STATE = 'start';
 /* How far a new window sits from the one in front, when its key has no bounds of its own. */
 export const CASCADE = 24;
 const SESSION_VERSION = 1;
+/*
+ * The states sit in a list of their own beside the keys, at the same places, so a shell from before
+ * them still reads the keys and opens the windows without what their pages kept.
+ */
 const parseSession = (text) => {
     if (text === null) {
         return [];
@@ -12,9 +16,16 @@ const parseSession = (text) => {
         if (file.version !== SESSION_VERSION || !Array.isArray(file.windows)) {
             return [];
         }
-        const keys = file.windows.filter((key) => key === null || (typeof key === 'string' && key !== ''));
+        const states = Array.isArray(file.states) ? file.states : [];
+        const windows = file.windows.flatMap((key, index) => {
+            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 keys.filter((key, index) => key === null || keys.lastIndexOf(key) === index);
+        return windows.filter(({ key }, index) => key === null || windows.findLastIndex((other) => other.key === key) === index);
     }
     catch {
         return [];
@@ -36,13 +47,22 @@ export const createWindows = (options) => {
     let started = false;
     // Off macOS the app quits with its last window, after that window already left the session.
     let quitsWithLastWindow = false;
+    // The app's last `before-quit`. Its windows stay in the session as they close, unless a listener after ours kept the app open.
+    let quitEvent = null;
+    let quitConfirmed = false;
+    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 writeSession = () => {
         if (quitting) {
             return;
         }
-        const keys = order.map((id) => entries.get(id)?.key ?? null);
-        options.session.write(`${JSON.stringify({ version: SESSION_VERSION, windows: keys }, null, 2)}\n`);
+        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 };
+        options.session.write(`${JSON.stringify(file, null, 2)}\n`);
     };
     const toFront = (id) => {
         order = [...order.filter((other) => other !== id), id];
@@ -56,7 +76,14 @@ export const createWindows = (options) => {
         }
         return null;
     };
-    const holderOf = (key) => alive().find((entry) => entry.key === key) ?? 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) => {
+        if (entry.key === key) {
+            entry.key = null;
+        }
+        entry.held = entry.held.filter((other) => other !== key);
+    };
     const pageWindow = (contents) => alive().find((entry) => entry.window.webContents === contents)?.window ?? null;
     const raise = (window) => {
         if (window.isMinimized()) {
@@ -77,9 +104,10 @@ export const createWindows = (options) => {
         const beside = front.getNormalBounds();
         return options.state.bounds(stateKey, { ...beside, x: beside.x + CASCADE, y: beside.y + CASCADE });
     };
-    const create = (key, origin) => {
-        const window = options.create(key, boundsFor(key), origin);
-        const entry = { window, key };
+    const create = (key, origin, state = null, at) => {
+        const bounds = boundsFor(key);
+        const window = options.create(key, at === undefined ? bounds : { ...bounds, x: Math.round(at.x), y: Math.round(at.y) }, origin, state);
+        const entry = { window, key, state, held: [] };
         const id = window.id;
         entries.set(id, entry);
         toFront(id);
@@ -89,10 +117,19 @@ export const createWindows = (options) => {
             toFront(id);
             options.onFront?.(window);
         });
-        window.on('close', () => {
+        window.on('close', (event) => {
             if (quitsWithLastWindow && alive().length === 1) {
                 markQuit();
             }
+            else if (quitEvent !== null && !quitEvent.defaultPrevented) {
+                if (event.defaultPrevented) {
+                    // A window that stays open stops Electron's quit, so a window that closes later is a person's doing.
+                    quitEvent = null;
+                }
+                else {
+                    markQuit();
+                }
+            }
         });
         window.on('closed', () => {
             entries.delete(id);
@@ -116,31 +153,45 @@ export const createWindows = (options) => {
         quitting = true;
     };
     const restore = () => {
-        const keys = parseSession(options.session.read());
+        const windows = parseSession(options.session.read());
         started = true;
-        if (keys.length === 0) {
+        if (windows.length === 0) {
             create(null, 'first');
             return;
         }
-        for (const key of keys) {
-            create(key, 'session');
+        for (const { key, state } of windows) {
+            create(key, 'session', state);
+        }
+    };
+    const resume = () => {
+        quitting = false;
+        quitEvent = null;
+        quitConfirmed = false;
+        installing = false;
+        writeSession();
+    };
+    /* The quit does not happen. Windows it already closed, the last one off macOS or all of them for an install, come back as they were. */
+    const stay = () => {
+        if (quitting && started && alive().length === 0) {
+            restore();
         }
+        resume();
     };
     return {
-        /* Raises the window that has the key, or opens one for it. Null always opens a new window. */
-        open: (key) => {
+        /* Raises the window that has the key, or opens one for it, at `at` when given. Null always opens a new window. */
+        open: (key, at) => {
             const holder = key === null ? null : holderOf(key);
             if (holder) {
                 raise(holder.window);
                 return holder.window;
             }
-            return create(key, 'opened');
+            return create(key, 'opened', null, at);
         },
         /* Opens the windows that were open when the app last quit, or one without a key. */
         restore,
         /*
          * Makes a window the one that shows a key, as when its page opens a project. False when another
-         * window already has it; that window comes to the front instead. Null lets the key go.
+         * window already shows or keeps it; that window comes to the front instead. Null lets the key go.
          */
         claim: (window, key) => {
             const entry = entries.get(window.id);
@@ -165,14 +216,89 @@ export const createWindows = (options) => {
          * Moves what a window shows into a new window, which comes to the front, and leaves the old one
          * without a key. The key is never without a window in between. Null for a window that shows nothing.
          */
-        move: (window) => {
+        move: (window, at) => {
             const entry = entries.get(window.id);
             if (!entry || entry.key === null) {
                 return null;
             }
             const key = entry.key;
-            entry.key = null;
-            return create(key, 'opened');
+            release(entry, key);
+            return create(key, 'opened', null, at);
+        },
+        /*
+         * The keys a window keeps besides the one it shows, such as its tabs. A key another window shows
+         * or keeps stays that window's, so the answer is the keys this window has now.
+         */
+        hold: (window, keys) => {
+            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;
+        },
+        /*
+         * Takes a key a window shows or keeps into a new window of its own, at `at` when given, as when
+         * a tab is dragged out. Null when the window does not have the key.
+         */
+        detach: (window, key, at) => {
+            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);
+        },
+        /*
+         * Hands a key to another window to keep, out of whichever window had it, as when a tab is dropped
+         * on another window. That window's page then shows it with `claim`.
+         */
+        transfer: (key, window) => {
+            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;
+        },
+        /* 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;
+                }
+            }
+            return 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.
+         */
+        setState: (window, state) => {
+            const entry = entries.get(window.id);
+            if (!entry || entry.state === state) {
+                return;
+            }
+            entry.state = state;
+            writeSession();
         },
         /* 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) => {
@@ -194,15 +320,34 @@ export const createWindows = (options) => {
                 }
             }
         },
-        /* From the moment the app quits, windows that close stay in the session, so the next start opens them again. */
+        /*
+         * From the moment the app quits, windows that close stay in the session, so the next start opens
+         * them again. `attach` calls it for a quit that goes ahead; an app only needs it without `attach`.
+         */
         quit: markQuit,
+        /*
+         * The updater's `onQuit`: true right before an install quits the app, after which the windows
+         * it closes stay in the session; false when the install failed and the app stays.
+         */
+        quitForUpdate: (going) => {
+            if (going) {
+                installing = true;
+                markQuit();
+            }
+            else {
+                stay();
+            }
+        },
         /*
          * 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, pending bounds are written at quit, and off macOS the app quits with its last window
-         * while that window stays in the session. Call it before `app.whenReady()`, and `restore()` once ready.
+         * 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.
          */
-        attach: (app) => {
+        attach: (app, attachOptions = {}) => {
+            const { confirmQuit } = attachOptions;
             const platform = options.platform ?? process.platform;
             quitsWithLastWindow = platform !== 'darwin';
             app.on('second-instance', () => {
@@ -219,6 +364,29 @@ export const createWindows = (options) => {
                     restore();
                 }
             });
+            app.on('before-quit', (event) => {
+                if (confirmQuit === undefined || quitConfirmed) {
+                    quitEvent = event;
+                    return;
+                }
+                event.preventDefault();
+                if (confirming) {
+                    return;
+                }
+                confirming = true;
+                void new Promise((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) {
@@ -226,10 +394,7 @@ export const createWindows = (options) => {
                 }
             });
         },
-        /* The quit did not go ahead after all, such as an update that failed to install: a window that closes leaves the session again. */
-        resume: () => {
-            quitting = false;
-            writeSession();
-        }
+        /* The quit did not go ahead after all: a window that closes leaves the session again. `attach` calls it when `confirmQuit` says no. */
+        resume
     };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/shell",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "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",
@@ -52,7 +52,7 @@
   "devDependencies": {
     "@types/bun": "^1.4.2",
     "@types/node": "^24.13.6",
-    "electron": "^44.4.4",
+    "electron": "^44.7.0",
     "electron-updater": "^6.8.9",
     "typescript": "^7.0.2"
   }

package/src/bridge/index.ts

@@ -3,7 +3,7 @@
  * a preload and a page read them as well as the main process.
  */
 
-export { MENU_ROLES, type MenuNode, type MenuRole, type MenuSpec } from './menu.ts';
+export { MENU_BAR_ROLES, MENU_ROLES, type MenuBarRole, type MenuNode, type MenuRole, type MenuSpec } from './menu.ts';
 export type { ThemeState } from './theme.ts';
-export type { UpdateState } from './update.ts';
+export type { UpdateErrorCode, UpdateState } from './update.ts';
 export { compareVersions, isVersion } from './versions.ts';

package/src/bridge/menu.ts

@@ -27,6 +27,12 @@ export const MENU_ROLES = [
 
 export type MenuRole = (typeof MENU_ROLES)[number];
 
+/* The roles a whole menu in the bar can take. On macOS `window` is where the system lists the open
+   windows and `help` gets the system's search field. */
+export const MENU_BAR_ROLES = ['window', 'help'] as const;
+
+export type MenuBarRole = (typeof MENU_BAR_ROLES)[number];
+
 /* `Action` names what only the shell can carry out; an app lists its own. */
 export type MenuNode<Action extends string = string> =
     | {
@@ -48,5 +54,5 @@ export type MenuNode<Action extends string = string> =
     | { kind: 'submenu'; id: string; label: string; items: MenuNode<Action>[]; enabled?: boolean };
 
 export interface MenuSpec<Action extends string = string> {
-    menus: { id: string; label: string; items: MenuNode<Action>[] }[];
+    menus: { id: string; label: string; role?: MenuBarRole; items: MenuNode<Action>[] }[];
 }

package/src/bridge/update.ts

@@ -1,3 +1,6 @@
+/* Why updating failed, for the page to put in its own words: `no-feed` is a 404 on the release feed, which has no published release yet or is private. */
+export type UpdateErrorCode = 'no-feed' | 'failed';
+
 /* Where updating stands, as the shell keeps it and the page draws it. */
 export interface UpdateState {
     /* `unsupported` is a checkout, which has no feed; `current` means a check found nothing newer. */
@@ -6,5 +9,7 @@ export interface UpdateState {
     /* The version on the other side, once a check has seen one. */
     version?: string;
     percent?: number;
+    /* The first line of what went wrong, as electron-updater said it, in English and untranslated; null when it said nothing. */
     error?: string | null;
+    errorCode?: UpdateErrorCode | null;
 }

package/src/index.ts

@@ -13,4 +13,4 @@ export type { SavedWindow, StateWindow, WindowDisplay, WindowSize, WindowState,
 export { createTheme } from './theme.ts';
 export type { Theme, ThemeOptions, TitleBarOverlay } from './theme.ts';
 export { CASCADE, createWindows, UNKEYED_STATE } from './windows.ts';
-export type { WindowOrigin, Windows, WindowsOptions } from './windows.ts';
+export type { AttachOptions, QuitRequest, WindowOrigin, WindowPoint, Windows, WindowsOptions } from './windows.ts';

package/src/menu.ts

@@ -1,5 +1,5 @@
 import type { MenuItemConstructorOptions } from 'electron';
-import { MENU_ROLES, type MenuNode, type MenuSpec } from './bridge/menu.ts';
+import { MENU_BAR_ROLES, MENU_ROLES, type MenuNode, type MenuSpec } from './bridge/menu.ts';
 import type { PageKeys } from './page-keys.ts';
 
 /* Named instead of the role: that one follows the focused web contents, which is a guest page as soon as one has the keyboard. */
@@ -44,7 +44,11 @@ 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, submenu: itemsOf(menu.items) }));
+    return spec.menus.map((menu) => ({
+        label: menu.label,
+        ...(menu.role !== undefined && MENU_BAR_ROLES.includes(menu.role) ? { role: menu.role } : {}),
+        submenu: itemsOf(menu.items)
+    }));
 };
 
 export interface StaticMenuOptions {
@@ -54,24 +58,29 @@ export interface StaticMenuOptions {
     appItems?: MenuItemConstructorOptions[];
     /* Right above Quit, on every platform. */
     quitItems?: MenuItemConstructorOptions[];
+    /* A File menu of their own, such as New Window, which a macOS app with no window open can only reach here. Above the quit items elsewhere. */
+    fileItems?: MenuItemConstructorOptions[];
     platform?: NodeJS.Platform;
 }
 
+const withSeparator = (items: MenuItemConstructorOptions[]): MenuItemConstructorOptions[] => (items.length > 0 ? [...items, { type: 'separator' }] : []);
+
 /*
- * The menu that stands until the page sends its own, and again after a reload or a crash, so Quit is
- * always there. The stock View menu without reload and the zoom roles: their accelerators are taken
+ * 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.
  */
 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'
             ? {
                   label: options.appName,
                   submenu: [
-                      ...(appItems.length > 0 ? [...appItems, { type: 'separator' } as const] : []),
+                      ...withSeparator(appItems),
                       { role: 'services' },
                       { type: 'separator' },
                       { role: 'hide' },
@@ -82,9 +91,10 @@ export const staticMenuTemplate = (options: StaticMenuOptions): MenuItemConstruc
                       { role: 'quit' }
                   ]
               }
-            : quitItems.length > 0
-              ? { label: 'File', submenu: [...quitItems, { type: 'separator' }, { role: 'quit' }] }
+            : 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: [
@@ -93,7 +103,7 @@ export const staticMenuTemplate = (options: StaticMenuOptions): MenuItemConstruc
             { role: 'togglefullscreen' }
         ]
     };
-    return [appMenu, { role: 'editMenu' }, viewMenu, { role: 'windowMenu' }];
+    return [appMenu, ...fileMenu, { role: 'editMenu' }, viewMenu, { role: 'windowMenu' }];
 };
 
 /* The part of a window a menu command reaches. */

package/src/updater.ts

@@ -1,23 +1,23 @@
 import type { AppUpdater } from 'electron-updater';
-import type { UpdateState } from './bridge/update.ts';
+import type { UpdateErrorCode, UpdateState } from './bridge/update.ts';
 
 /* Often enough that a release lands the same day, rarely enough to be invisible. */
 export const UPDATE_INTERVAL_MS = 60 * 60 * 1000;
 
 /*
  * electron-updater puts the whole HTTP exchange in the message of a failed check: every response
- * header, the session cookie among them. Only the first line travels, and a 404 on the feed gets the
- * sentence that says what went wrong.
+ * header, the session cookie among them. Only the first line travels. The words are the page's, in
+ * the person's language, so the shell sends a code beside that line and no sentence of its own.
  */
-export const describeUpdateError = (message: string): string => {
+export const describeUpdateError = (message: string): { code: UpdateErrorCode; detail: string | null } => {
     const first = message.split('\n')[0]?.trim();
     if (!first) {
-        return 'No reason given.';
+        return { code: 'failed', detail: null };
     }
-    if (first.startsWith('404')) {
-        return 'No release feed found. There is no published release yet, or the repository is private.';
-    }
-    return first.length > 200 ? `${first.slice(0, 200)}…` : first;
+    return {
+        code: first.startsWith('404') ? 'no-feed' : 'failed',
+        detail: first.length > 200 ? `${first.slice(0, 200)}…` : first
+    };
 };
 
 export interface UpdaterOptions {
@@ -33,7 +33,7 @@ export interface UpdaterOptions {
     /*
      * True right before installing quits the app, false when that install failed and the app stays.
      * electron-updater closes the windows before the app's own `before-quit`, so this is where a set of
-     * windows learns the quit is coming (`windows.quit()` and `windows.resume()`).
+     * windows learns the quit is coming: pass `windows.quitForUpdate`.
      */
     onQuit?: (quitting: boolean) => void;
     log?: (message: string, error: unknown) => void;
@@ -91,14 +91,15 @@ export const createUpdater = (options: UpdaterOptions) => {
                 // The page owns the preference and sends it before the first check, so nothing downloads
                 // behind the back of someone who turned it off.
                 loaded.autoDownload = false;
-                loaded.on('checking-for-update', () => setState({ status: 'checking', error: null }));
-                loaded.on('update-available', (info) => setState({ status: 'available', version: info.version, error: null }));
-                loaded.on('update-not-available', () => setState({ status: 'current', version: undefined, error: null }));
+                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();
-                    setState({ status: 'error', error: describeUpdateError(e.message) });
+                    const { code, detail } = describeUpdateError(e.message);
+                    setState({ status: 'error', error: detail, errorCode: code });
                 });
                 updater = loaded;
                 setState({ status: 'idle' });

package/src/windows.ts

@@ -14,34 +14,78 @@ export interface WindowsOptions {
     state: WindowState;
     /* Which windows were open when the app last quit, so a cold start opens them again. */
     session: WindowStateStorage;
-    /* Builds the app's window for a key and loads it. The bounds go into the constructor. */
-    create: (key: string | null, bounds: Partial<Rectangle> & WindowSize, origin: WindowOrigin) => BrowserWindow;
+    /*
+     * Builds the app's window for a key and loads it. The bounds go into the constructor. `state` is
+     * what the window's page last handed `setState` before a quit, on a window the session opens again.
+     */
+    create: (key: string | null, bounds: Partial<Rectangle> & WindowSize, origin: WindowOrigin, state: string | null) => BrowserWindow;
     /* A window came to the front, after `focused()` already answers it, such as to draw its own menu. */
     onFront?: (window: BrowserWindow) => void;
     /* The key an app kept its one window under before it had several, where a first window without bounds of its own opens. */
     formerKey?: string;
     platform?: NodeJS.Platform;
+    /* The timer that asks for the quit again once `confirmQuit` said yes, replaced in a test. */
+    setTimeout?: (run: () => void, ms: number) => unknown;
+}
+
+/* What a quit `confirmQuit` decides on is about. `update` is a quit an install started, after it closed the windows. */
+export interface QuitRequest {
+    update: boolean;
+}
+
+export interface AttachOptions {
+    /*
+     * Asked once per quit, before any window closes; the quit waits while the answer is pending, so this
+     * is also where the app finishes what has to end first. False keeps the app open. A throw lets the
+     * quit go ahead, so a broken check never traps the app.
+     */
+    confirmQuit?: (request: QuitRequest) => boolean | Promise<boolean>;
 }
 
 interface Entry {
     window: BrowserWindow;
     key: string | null;
+    state: string | null;
+    /* The keys the window keeps besides the one it shows, such as its tabs, which no other window may show. */
+    held: string[];
+}
+
+/* Where a new window's top left corner goes on the screen, such as under the pointer that dragged something out. */
+export interface WindowPoint {
+    x: number;
+    y: number;
+}
+
+interface SessionWindow {
+    key: string | null;
+    state: string | null;
 }
 
 const SESSION_VERSION = 1;
 
-const parseSession = (text: string | null): (string | null)[] => {
+/*
+ * The states sit in a list of their own beside the keys, at the same places, so a shell from before
+ * them still reads the keys and opens the windows without what their pages kept.
+ */
+const parseSession = (text: string | null): SessionWindow[] => {
     if (text === null) {
         return [];
     }
     try {
-        const file = JSON.parse(text) as { version?: unknown; windows?: unknown };
+        const file = JSON.parse(text) as { version?: unknown; windows?: unknown; states?: unknown };
         if (file.version !== SESSION_VERSION || !Array.isArray(file.windows)) {
             return [];
         }
-        const keys = file.windows.filter((key): key is string | null => key === null || (typeof key === 'string' && key !== ''));
+        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 keys.filter((key, index) => key === null || keys.lastIndexOf(key) === index);
+        return windows.filter(({ key }, index) => key === null || windows.findLastIndex((other) => other.key === key) === index);
     } catch {
         return [];
     }
@@ -63,6 +107,12 @@ export const createWindows = (options: WindowsOptions) => {
     let started = false;
     // Off macOS the app quits with its last window, after that window already left the session.
     let quitsWithLastWindow = false;
+    // The app's last `before-quit`. Its windows stay in the session as they close, unless a listener after ours kept the app open.
+    let quitEvent: { readonly defaultPrevented: boolean } | null = null;
+    let quitConfirmed = false;
+    let confirming = false;
+    let installing = false;
+    const later = options.setTimeout ?? ((run, ms) => setTimeout(run, ms));
 
     const alive = (): Entry[] => [...entries.values()].filter((entry) => !entry.window.isDestroyed());
 
@@ -70,8 +120,11 @@ export const createWindows = (options: WindowsOptions) => {
         if (quitting) {
             return;
         }
-        const keys = order.map((id) => entries.get(id)?.key ?? null);
-        options.session.write(`${JSON.stringify({ version: SESSION_VERSION, windows: keys }, null, 2)}\n`);
+        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 };
+        options.session.write(`${JSON.stringify(file, null, 2)}\n`);
     };
 
     const toFront = (id: number): void => {
@@ -88,7 +141,15 @@ export const createWindows = (options: WindowsOptions) => {
         return null;
     };
 
-    const holderOf = (key: string): Entry | null => alive().find((entry) => entry.key === key) ?? null;
+    const holderOf = (key: string): Entry | null => 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: Entry, key: string): void => {
+        if (entry.key === key) {
+            entry.key = null;
+        }
+        entry.held = entry.held.filter((other) => other !== key);
+    };
 
     const pageWindow = (contents: WebContents): BrowserWindow | null => alive().find((entry) => entry.window.webContents === contents)?.window ?? null;
 
@@ -113,9 +174,10 @@ export const createWindows = (options: WindowsOptions) => {
         return options.state.bounds(stateKey, { ...beside, x: beside.x + CASCADE, y: beside.y + CASCADE });
     };
 
-    const create = (key: string | null, origin: WindowOrigin): BrowserWindow => {
-        const window = options.create(key, boundsFor(key), origin);
-        const entry: Entry = { window, key };
+    const create = (key: string | null, origin: WindowOrigin, state: string | null = null, at?: WindowPoint): BrowserWindow => {
+        const bounds = boundsFor(key);
+        const window = options.create(key, at === undefined ? bounds : { ...bounds, x: Math.round(at.x), y: Math.round(at.y) }, origin, state);
+        const entry: Entry = { window, key, state, held: [] };
         const id = window.id;
         entries.set(id, entry);
         toFront(id);
@@ -125,9 +187,16 @@ export const createWindows = (options: WindowsOptions) => {
             toFront(id);
             options.onFront?.(window);
         });
-        window.on('close', () => {
+        window.on('close', (event) => {
             if (quitsWithLastWindow && alive().length === 1) {
                 markQuit();
+            } else if (quitEvent !== null && !quitEvent.defaultPrevented) {
+                if (event.defaultPrevented) {
+                    // A window that stays open stops Electron's quit, so a window that closes later is a person's doing.
+                    quitEvent = null;
+                } else {
+                    markQuit();
+                }
             }
         });
         window.on('closed', () => {
@@ -154,26 +223,42 @@ export const createWindows = (options: WindowsOptions) => {
     };
 
     const restore = (): void => {
-        const keys = parseSession(options.session.read());
+        const windows = parseSession(options.session.read());
         started = true;
-        if (keys.length === 0) {
+        if (windows.length === 0) {
             create(null, 'first');
             return;
         }
-        for (const key of keys) {
-            create(key, 'session');
+        for (const { key, state } of windows) {
+            create(key, 'session', state);
         }
     };
 
+    const resume = (): void => {
+        quitting = false;
+        quitEvent = null;
+        quitConfirmed = false;
+        installing = false;
+        writeSession();
+    };
+
+    /* The quit does not happen. Windows it already closed, the last one off macOS or all of them for an install, come back as they were. */
+    const stay = (): void => {
+        if (quitting && started && alive().length === 0) {
+            restore();
+        }
+        resume();
+    };
+
     return {
-        /* Raises the window that has the key, or opens one for it. Null always opens a new window. */
-        open: (key: string | null): BrowserWindow => {
+        /* 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');
+            return create(key, 'opened', null, at);
         },
 
         /* Opens the windows that were open when the app last quit, or one without a key. */
@@ -181,7 +266,7 @@ export const createWindows = (options: WindowsOptions) => {
 
         /*
          * Makes a window the one that shows a key, as when its page opens a project. False when another
-         * window already has it; that window comes to the front instead. Null lets the key go.
+         * window already shows or keeps it; that window comes to the front instead. Null lets the key go.
          */
         claim: (window: BrowserWindow, key: string | null): boolean => {
             const entry = entries.get(window.id);
@@ -208,14 +293,95 @@ export const createWindows = (options: WindowsOptions) => {
          * Moves what a window shows into a new window, which comes to the front, and leaves the old one
          * without a key. The key is never without a window in between. Null for a window that shows nothing.
          */
-        move: (window: BrowserWindow): BrowserWindow | null => {
+        move: (window: BrowserWindow, at?: WindowPoint): BrowserWindow | null => {
             const entry = entries.get(window.id);
             if (!entry || entry.key === null) {
                 return null;
             }
             const key = entry.key;
-            entry.key = null;
-            return create(key, 'opened');
+            release(entry, key);
+            return create(key, 'opened', null, at);
+        },
+
+        /*
+         * The keys a window keeps besides the one it shows, such as its tabs. A key another window shows
+         * or keeps stays that window's, so the answer is the keys this window has now.
+         */
+        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;
+        },
+
+        /*
+         * Takes a key a window shows or keeps into a new window of its own, at `at` when given, as when
+         * a tab is dragged out. Null when the window does not have the key.
+         */
+        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);
+        },
+
+        /*
+         * Hands a key to another window to keep, out of whichever window had it, as when a tab is dropped
+         * on another window. That window's page then shows it with `claim`.
+         */
+        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;
+        },
+
+        /* The window that shows or keeps a key, if any. */
+        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;
+                }
+            }
+            return 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.
+         */
+        setState: (window: BrowserWindow, state: string | null): void => {
+            const entry = entries.get(window.id);
+            if (!entry || entry.state === state) {
+                return;
+            }
+            entry.state = state;
+            writeSession();
         },
 
         /* 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`. */
@@ -243,16 +409,35 @@ export const createWindows = (options: WindowsOptions) => {
             }
         },
 
-        /* From the moment the app quits, windows that close stay in the session, so the next start opens them again. */
+        /*
+         * From the moment the app quits, windows that close stay in the session, so the next start opens
+         * them again. `attach` calls it for a quit that goes ahead; an app only needs it without `attach`.
+         */
         quit: markQuit,
 
+        /*
+         * The updater's `onQuit`: true right before an install quits the app, after which the windows
+         * it closes stay in the session; false when the install failed and the app stays.
+         */
+        quitForUpdate: (going: boolean): void => {
+            if (going) {
+                installing = true;
+                markQuit();
+            } else {
+                stay();
+            }
+        },
+
         /*
          * 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, pending bounds are written at quit, and off macOS the app quits with its last window
-         * while that window stays in the session. Call it before `app.whenReady()`, and `restore()` once ready.
+         * 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.
          */
-        attach: (app: Pick<App, 'on' | 'quit'>): void => {
+        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', () => {
@@ -268,6 +453,29 @@ export const createWindows = (options: WindowsOptions) => {
                     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) {
@@ -276,11 +484,8 @@ export const createWindows = (options: WindowsOptions) => {
             });
         },
 
-        /* The quit did not go ahead after all, such as an update that failed to install: a window that closes leaves the session again. */
-        resume: (): void => {
-            quitting = false;
-            writeSession();
-        }
+        /* The quit did not go ahead after all: a window that closes leaves the session again. `attach` calls it when `confirmQuit` says no. */
+        resume
     };
 };