@adecore/shell 0.0.0-stage → 0.14.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bas Milius
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# @adecore/shell
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@adecore/shell)](https://www.npmjs.com/package/@adecore/shell)
+[![Docs](https://img.shields.io/badge/docs-adecore.dev-blue)](https://adecore.dev/shell/)
+
+The main process of an Electron app whose page draws its own interface. The page builds the application menu and shows where updating stands. The shell turns that menu into a native one and runs electron-updater. It also opens each window where it was left, puts the page's theme on the window and keeps the page's bridge in the app's own frame.
+
+**[Documentation](https://adecore.dev/shell/)**
+
+## Install
+
+```sh
+bun add @adecore/shell
+```
+
+Electron 44 or later and electron-updater are optional peer dependencies; the app brings its own. The package imports only their types, so a test runs in Bun without Electron.
+
+## Nothing listens on its own
+
+The package registers no IPC handler and listens to no app-wide Electron event. Every IPC message from the page crosses a security boundary, so the app wires each channel itself, behind its own check of the sender (`isAppSender`), and calls into the package from there.
+
+## Entry points
+
+| Import | What it holds |
+|---|---|
+| `@adecore/shell` | For the main process: `createWindows`, `createWindowState`, `createUpdater`, `createTheme`, `menuTemplateOf`, `staticMenuTemplate`, `createMenuCommands`, `createPageKeys` 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. |
+
+## Documentation
+
+| Page | What it covers |
+|---|---|
+| [Application menu](https://adecore.dev/shell/menu) | The menu the page builds, the one that stands until it does, and how a command gets back to the page |
+| [Updater](https://adecore.dev/shell/updater) | electron-updater as a state the page watches |
+| [Windows](https://adecore.dev/shell/windows) | A set of windows, one per key, restored at the next start |
+| [Window state](https://adecore.dev/shell/window-state) | Each window opens where it was left |
+| [Theme](https://adecore.dev/shell/theme) | The page's theme on the window, its controls and Chromium |
+| [Web guards](https://adecore.dev/shell/web-guards) | Where the app's page may go, and who may speak for it |
+| [Bridge](https://adecore.dev/shell/bridge) | The shapes that cross IPC |
+
+## License
+
+MIT

package/dist/bridge/index.d.ts

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

package/dist/bridge/index.js

@@ -0,0 +1,6 @@
+/*
+ * 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 { compareVersions, isVersion } from './versions.js';

package/dist/bridge/menu.d.ts

@@ -0,0 +1,35 @@
+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 type MenuNode<Action extends string = string> = {
+    kind: 'command';
+    id: string;
+    label: string;
+    accelerator?: string;
+    keys?: string;
+    enabled?: boolean;
+    checked?: boolean;
+    radio?: boolean;
+} | {
+    kind: 'role';
+    role: MenuRole;
+    label: string;
+} | {
+    kind: 'shell';
+    action: Action;
+    label: string;
+} | {
+    kind: 'separator';
+} | {
+    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>[];
+    }[];
+}

package/dist/bridge/menu.js

@@ -0,0 +1,25 @@
+/*
+ * 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 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 = [
+    'undo',
+    'redo',
+    'cut',
+    'copy',
+    'paste',
+    'selectAll',
+    'services',
+    'hide',
+    'hideOthers',
+    'unhide',
+    'minimize',
+    'zoom',
+    'front',
+    'close',
+    'quit',
+    'togglefullscreen'
+];

package/dist/bridge/theme.d.ts

@@ -0,0 +1,5 @@
+export interface ThemeState {
+    resolved: 'light' | 'dark';
+    followsSystem: boolean;
+    background: string;
+}

package/dist/bridge/theme.js

@@ -0,0 +1 @@
+export {};

package/dist/bridge/update.d.ts

@@ -0,0 +1,7 @@
+export interface UpdateState {
+    status: 'unsupported' | 'idle' | 'checking' | 'current' | 'available' | 'downloading' | 'ready' | 'error';
+    currentVersion: string;
+    version?: string;
+    percent?: number;
+    error?: string | null;
+}

package/dist/bridge/update.js

@@ -0,0 +1 @@
+export {};

package/dist/bridge/versions.d.ts

@@ -0,0 +1,2 @@
+export declare const isVersion: (version: string) => boolean;
+export declare const compareVersions: (a: string, b: string) => number;

package/dist/bridge/versions.js

@@ -0,0 +1,22 @@
+/*
+ * The order the shell sorts the release list in has to be the order the page reads it in, or the
+ * notes of a version land under the wrong heading. One comparison, so the two cannot disagree.
+ */
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+/* A plain `1.2.3`. A git tag carries a `v` in front of it, which is the tag's and not the version's. */
+export const isVersion = (version) => SEMVER.test(version);
+/* Negative when `a` is older than `b`. A version that is not semver sorts below every one that is. */
+export const compareVersions = (a, b) => {
+    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/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { createMenuCommands, devToolsAccelerator, menuTemplateOf, staticMenuTemplate } from './menu.ts';
+export type { MenuCommandOptions, MenuTemplateOptions, MenuWindow, StaticMenuOptions } from './menu.ts';
+export { createPageKeys, PAGE_KEY_MS } from './page-keys.ts';
+export type { PageKey, PageKeys } from './page-keys.ts';
+export { createUpdater, describeUpdateError, UPDATE_INTERVAL_MS } from './updater.ts';
+export type { Updater, UpdaterOptions } from './updater.ts';
+export { appWindowNavigation, isAppSender, isAppUrl, isExternalLink, isWebLink, originOf } from './web-guards.ts';
+export type { NavigationVerdict, SenderFrame } from './web-guards.ts';
+export { createWindowState, fileStorage, fitBounds, VISIBLE_EDGE } from './window-state.ts';
+export type { SavedWindow, StateWindow, WindowDisplay, WindowSize, WindowState, WindowStateOptions, WindowStateStorage } from './window-state.ts';
+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';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { createMenuCommands, devToolsAccelerator, menuTemplateOf, staticMenuTemplate } from './menu.js';
+export { createPageKeys, PAGE_KEY_MS } from './page-keys.js';
+export { createUpdater, describeUpdateError, UPDATE_INTERVAL_MS } from './updater.js';
+export { appWindowNavigation, isAppSender, isAppUrl, isExternalLink, isWebLink, originOf } from './web-guards.js';
+export { createWindowState, fileStorage, fitBounds, VISIBLE_EDGE } from './window-state.js';
+export { createTheme } from './theme.js';
+export { CASCADE, createWindows, UNKEYED_STATE } from './windows.js';

package/dist/menu.d.ts

@@ -0,0 +1,31 @@
+import type { MenuItemConstructorOptions } from 'electron';
+import { type MenuSpec } from './bridge/menu.ts';
+import type { PageKeys } from './page-keys.ts';
+export declare const devToolsAccelerator: (platform?: NodeJS.Platform) => string;
+export interface MenuTemplateOptions<Action extends string> {
+    run: (id: string, byKey: boolean) => void;
+    shellItem: (action: Action, label: string) => MenuItemConstructorOptions | null;
+    platform?: NodeJS.Platform;
+}
+export declare const menuTemplateOf: <Action extends string>(spec: MenuSpec<Action>, options: MenuTemplateOptions<Action>) => MenuItemConstructorOptions[] | null;
+export interface StaticMenuOptions {
+    appName: string;
+    toggleDevTools: () => void;
+    appItems?: MenuItemConstructorOptions[];
+    quitItems?: MenuItemConstructorOptions[];
+    platform?: NodeJS.Platform;
+}
+export declare const staticMenuTemplate: (options: StaticMenuOptions) => MenuItemConstructorOptions[];
+export interface MenuWindow {
+    isMinimized(): boolean;
+    show(): void;
+    readonly webContents: {
+        send(channel: string, ...args: unknown[]): void;
+    };
+}
+export interface MenuCommandOptions {
+    pageKeys: PageKeys;
+    window: () => MenuWindow | null;
+    keyBypassesPage?: () => boolean;
+}
+export declare const createMenuCommands: (options: MenuCommandOptions) => (id: string, byKey: boolean) => void;

package/dist/menu.js

@@ -0,0 +1,88 @@
+import { 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. */
+export const menuTemplateOf = (spec, options) => {
+    if (!Array.isArray(spec?.menus)) {
+        return null;
+    }
+    const platform = options.platform ?? process.platform;
+    const itemOf = (node) => {
+        switch (node.kind) {
+            case 'separator':
+                return { type: 'separator' };
+            case 'submenu':
+                return { label: node.label, enabled: node.enabled ?? true, submenu: itemsOf(node.items) };
+            case 'role':
+                return MENU_ROLES.includes(node.role) ? { role: node.role, label: node.label } : null;
+            case 'shell':
+                return options.shellItem(node.action, node.label);
+            case 'command':
+                return {
+                    label: node.label,
+                    type: node.checked === undefined ? 'normal' : node.radio === true ? 'radio' : 'checkbox',
+                    checked: node.checked ?? false,
+                    enabled: node.enabled ?? true,
+                    ...(node.accelerator ? { accelerator: node.accelerator } : {}),
+                    // Off macOS a registered accelerator would take a key such as Ctrl+W before the page saw it.
+                    registerAccelerator: platform === 'darwin',
+                    click: (_item, _window, event) => options.run(node.id, event.triggeredByAccelerator === true)
+                };
+        }
+    };
+    const itemsOf = (nodes) => nodes.map(itemOf).filter((item) => item !== null);
+    return spec.menus.map((menu) => ({ label: menu.label, submenu: itemsOf(menu.items) }));
+};
+/*
+ * 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
+ * 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 appMenu = platform === 'darwin'
+        ? {
+            label: options.appName,
+            submenu: [
+                ...(appItems.length > 0 ? [...appItems, { type: 'separator' }] : []),
+                { role: 'services' },
+                { type: 'separator' },
+                { role: 'hide' },
+                { role: 'hideOthers' },
+                { role: 'unhide' },
+                { type: 'separator' },
+                ...quitItems,
+                { role: 'quit' }
+            ]
+        }
+        : quitItems.length > 0
+            ? { label: 'File', submenu: [...quitItems, { type: 'separator' }, { role: 'quit' }] }
+            : { role: 'fileMenu' };
+    const viewMenu = {
+        label: 'View',
+        submenu: [
+            { label: 'Toggle Developer Tools', accelerator: devToolsAccelerator(platform), click: () => options.toggleDevTools() },
+            { type: 'separator' },
+            { role: 'togglefullscreen' }
+        ]
+    };
+    return [appMenu, { 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.
+ */
+export const createMenuCommands = (options) => (id, byKey) => {
+    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/dist/page-keys.d.ts

@@ -0,0 +1,11 @@
+export interface PageKey {
+    type: string;
+    meta: boolean;
+    control: boolean;
+}
+export declare const PAGE_KEY_MS = 1000;
+export declare const createPageKeys: (now?: () => number) => {
+    saw: (key: PageKey) => void;
+    take: () => boolean;
+};
+export type PageKeys = ReturnType<typeof createPageKeys>;

package/dist/page-keys.js

@@ -0,0 +1,25 @@
+/* How long after the page had a key the menu may still be answering it: the page's round trip, with room for a busy one. */
+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.
+ */
+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.
+    let seen = [];
+    return {
+        saw: (key) => {
+            if (key.type === 'keyDown' && (key.meta || key.control)) {
+                seen.push(now());
+            }
+        },
+        take: () => {
+            const since = now() - PAGE_KEY_MS;
+            seen = seen.filter((at) => at >= since);
+            return seen.shift() !== undefined;
+        }
+    };
+};

package/dist/theme.d.ts

@@ -0,0 +1,26 @@
+import type { BrowserWindow, BrowserWindowConstructorOptions, NativeTheme } from 'electron';
+import type { ThemeState } from './bridge/theme.ts';
+export interface TitleBarOverlay {
+    height: number;
+    colors: Record<ThemeState['resolved'], {
+        color: string;
+        symbolColor: string;
+    }>;
+}
+export interface ThemeOptions {
+    nativeTheme: Pick<NativeTheme, 'themeSource'>;
+    windows: () => readonly BrowserWindow[];
+    background: string;
+    overlay?: TitleBarOverlay;
+    trafficLights?: {
+        x: number;
+        y: number;
+    };
+    platform?: NodeJS.Platform;
+}
+export declare const createTheme: (options: ThemeOptions) => {
+    apply: (theme: ThemeState) => void;
+    current: () => ThemeState | null;
+    windowOptions: () => BrowserWindowConstructorOptions;
+};
+export type Theme = ReturnType<typeof createTheme>;

package/dist/theme.js

@@ -0,0 +1,37 @@
+/*
+ * 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.
+ */
+export const createTheme = (options) => {
+    const platform = options.platform ?? process.platform;
+    let current = null;
+    const overlayOf = (resolved) => options.overlay ? { height: options.overlay.height, ...options.overlay.colors[resolved] } : undefined;
+    return {
+        apply: (theme) => {
+            current = theme;
+            options.nativeTheme.themeSource = theme.followsSystem ? 'system' : theme.resolved;
+            for (const window of options.windows()) {
+                if (window.isDestroyed()) {
+                    continue;
+                }
+                const overlay = overlayOf(theme.resolved);
+                if (platform !== 'darwin' && overlay) {
+                    window.setTitleBarOverlay(overlay);
+                }
+                window.setBackgroundColor(theme.background);
+            }
+        },
+        current: () => current,
+        /* The constructor options of a new window: its own chrome and the ground the others have. Dark until a page says otherwise. */
+        windowOptions: () => {
+            const resolved = current?.resolved ?? 'dark';
+            const overlay = overlayOf(resolved);
+            const chrome = platform === 'darwin'
+                ? { titleBarStyle: 'hiddenInset', trafficLightPosition: options.trafficLights ?? { x: 17, y: 17 } }
+                : { titleBarStyle: 'hidden', ...(overlay ? { titleBarOverlay: overlay } : {}) };
+            return { ...chrome, backgroundColor: current?.background ?? options.background };
+        }
+    };
+};

package/dist/updater.d.ts

@@ -0,0 +1,23 @@
+import type { AppUpdater } from 'electron-updater';
+import type { UpdateState } from './bridge/update.ts';
+export declare const UPDATE_INTERVAL_MS: number;
+export declare const describeUpdateError: (message: string) => string;
+export interface UpdaterOptions {
+    currentVersion: string;
+    packaged: boolean;
+    load: () => AppUpdater;
+    publish: (state: UpdateState) => void;
+    beforeCheck?: () => void;
+    onQuit?: (quitting: boolean) => void;
+    log?: (message: string, error: unknown) => void;
+    setInterval?: (run: () => void, ms: number) => unknown;
+}
+export declare const createUpdater: (options: UpdaterOptions) => {
+    state: () => UpdateState;
+    start: () => void;
+    configure: (autoDownload: unknown) => void;
+    check: () => Promise<void>;
+    download: () => Promise<void>;
+    install: () => boolean;
+};
+export type Updater = ReturnType<typeof createUpdater>;

package/dist/updater.js

@@ -0,0 +1,120 @@
+/* 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.
+ */
+export const describeUpdateError = (message) => {
+    const first = message.split('\n')[0]?.trim();
+    if (!first) {
+        return 'No reason given.';
+    }
+    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;
+};
+/*
+ * The updater as a state machine the page watches, not a dialog that interrupts. In a checkout the
+ * state stays `unsupported`, so nothing in the page offers to update.
+ */
+export const createUpdater = (options) => {
+    const log = options.log ?? ((message, error) => console.error(message, error));
+    const every = options.setInterval ?? ((run, ms) => setInterval(run, ms));
+    let state = { status: 'unsupported', currentVersion: options.currentVersion };
+    let updater = null;
+    let timer = null;
+    let installing = false;
+    const setState = (patch) => {
+        state = { ...state, ...patch };
+        options.publish(state);
+    };
+    const installFailed = () => {
+        if (installing) {
+            installing = false;
+            options.onQuit?.(false);
+        }
+    };
+    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.
+        if (!updater || state.status === 'checking' || state.status === 'downloading' || state.status === 'ready') {
+            return;
+        }
+        options.beforeCheck?.();
+        try {
+            await updater.checkForUpdates();
+        }
+        catch (e) {
+            // checkForUpdates rejects as well as emitting `error`; the state is already set there.
+            log('Update check failed', e);
+        }
+    };
+    return {
+        state: () => state,
+        start: () => {
+            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.
+                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('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) });
+                });
+                updater = loaded;
+                setState({ status: 'idle' });
+            }
+            catch (e) {
+                // electron-updater missing from the bundle is the only way here; the app stays as it is.
+                log('The updater did not start', e);
+            }
+        },
+        /* The hourly check starts with the first preference the page sends, never before: until then the shell does not know whether it may download what a check turns up. */
+        configure: (autoDownload) => {
+            if (!updater) {
+                return;
+            }
+            updater.autoDownload = autoDownload === true;
+            timer ??= every(() => void check(), UPDATE_INTERVAL_MS);
+        },
+        check,
+        download: async () => {
+            if (!updater) {
+                return;
+            }
+            try {
+                await updater.downloadUpdate();
+            }
+            catch (e) {
+                log('Update download failed', e);
+            }
+        },
+        /* Quits into the downloaded build. False when there is none, or the install failed at once. */
+        install: () => {
+            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/dist/web-guards.d.ts

@@ -0,0 +1,11 @@
+export declare const originOf: (url: string, schemes?: readonly string[]) => string | null;
+export declare const isAppUrl: (url: string, appOrigin: string, schemes?: readonly string[]) => boolean;
+export declare const isWebLink: (url: string) => boolean;
+export declare const isExternalLink: (url: string) => boolean;
+export type NavigationVerdict = 'allow' | 'external' | 'refuse';
+export declare const appWindowNavigation: (url: string, appOrigin: string, schemes?: readonly string[]) => NavigationVerdict;
+export interface SenderFrame {
+    readonly url: string;
+    readonly parent: unknown;
+}
+export declare const isAppSender: (isAppWindow: boolean, frame: SenderFrame | null, appOrigin: string, schemes?: readonly string[]) => boolean;

package/dist/web-guards.js

@@ -0,0 +1,41 @@
+/*
+ * What the shell lets the app's page do, as pure decisions, so the main process only wires them to
+ * Electron's events. The app's page carries the whole bridge, so each rule here is a security boundary.
+ *
+ * `schemes` lists the standard schemes an app registers for itself (`app://`): Node's URL gives every
+ * scheme it does not know the origin `null`, where Chromium gives a registered standard scheme a real one.
+ */
+/* The origin of a URL, or null for one that does not parse or has no origin of its own (`about:`, `data:`). */
+export const originOf = (url, schemes = []) => {
+    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;
+    }
+};
+export const isAppUrl = (url, appOrigin, schemes = []) => originOf(url, schemes) === appOrigin;
+export const isWebLink = (url) => /^https?:\/\//i.test(url);
+/* What the system browser or mail app may be handed; a `file:` link could open an application. */
+export const isExternalLink = (url) => isWebLink(url) || /^mailto:/i.test(url);
+/*
+ * Where the app window's own page may go. A dropped link or file navigates the top frame, and the page
+ * it lands on would inherit the bridge, so only the app stays in the window and a web link leaves for
+ * the system browser.
+ */
+export const appWindowNavigation = (url, appOrigin, schemes = []) => {
+    if (isAppUrl(url, appOrigin, schemes)) {
+        return 'allow';
+    }
+    return isWebLink(url) ? 'external' : 'refuse';
+};
+/*
+ * Whether an IPC message came from the app itself: the top frame of an app window, still on the app's
+ * origin. The web contents alone says nothing, since it stays the same object whatever it navigates to.
+ */
+export const isAppSender = (isAppWindow, frame, appOrigin, schemes = []) => isAppWindow && frame !== null && frame.parent === null && isAppUrl(frame.url, appOrigin, schemes);