@workbench-kit/electron-shell 0.0.2-prototype.0.2.26 → 0.0.2-prototype.0.2.27

package/README.md

@@ -1,8 +1,8 @@
 # `@workbench-kit/electron-shell`
 
-Electron **main-process** helpers (window controls, asset protocol, secret vault)
-and a typed **preload** scaffold. The package stays Electron-free — hosts inject
-narrow `ipcMain` / `ipcRenderer` / `contextBridge` surfaces.
+Electron **main-process** helpers (application quit lifecycle, window controls,
+asset protocol, secret vault) and a typed **preload** scaffold. The package stays
+Electron-free — hosts inject narrow Electron surfaces.
 
 Published on npm with the **`prototype`** dist tag.
 
@@ -16,12 +16,81 @@ pnpm add @workbench-kit/electron-shell@prototype
 
 ```ts
 import {
+  createApplicationQuitGuard,
   registerWindowControlIpc,
   createEncryptedSecretVault,
   requireOwnedWindowForSender,
 } from '@workbench-kit/electron-shell';
 ```
 
+## Focused entries
+
+Performance-sensitive hosts can import only the reusable Electron boundary they
+need. Product channel names, URL catalogs, storage paths, and policy remain
+host-owned.
+
+```ts
+import { openAllowlistedExternalLink } from '@workbench-kit/electron-shell/external-links';
+import { createApplicationQuitGuard } from '@workbench-kit/electron-shell/application-quit-guard';
+import { requireOwnedWindowForSender } from '@workbench-kit/electron-shell/sender-security';
+import {
+  createWindowControlsBridge,
+  registerWindowControlIpc,
+} from '@workbench-kit/electron-shell/window-controls';
+```
+
+`registerWindowControlIpc` validates the sender through the host-injected window
+resolver. `createWindowControlsBridge().toggleMaximized()` resolves to the final
+maximized state returned by the main handler.
+
+## Application quit guard (`./application-quit-guard`)
+
+Electron's `before-quit` event must be vetoed synchronously, even when checking
+dirty state or asking for a decision is asynchronous. The guard coordinates that
+flow while the host retains ownership of application state, prompts, save/discard
+operations, and event registration.
+
+```ts
+const quitGuard = createApplicationQuitGuard({
+  isDirty: (signal) => documentStore.isDirty({ signal }),
+  requestDecision: (signal) => quitPrompt.requestDecision({ signal }),
+  save: (signal) => documentStore.saveAll({ signal }),
+  discard: (signal) => documentStore.discardAll({ signal }),
+  resumeQuit: () => electronApp.quit(),
+  timeoutMs: 30_000,
+});
+
+electronApp.on('before-quit', (event) => {
+  void quitGuard.handleBeforeQuit(event);
+});
+```
+
+Repeated quit events are coalesced into the active request. After save or discard,
+the guard rechecks dirty state and resumes only when clean. Errors, timeout, and a
+still-dirty recheck fail closed. `cancelPending()` aborts an obsolete request and
+invalidates any late guard completion; call it when the owning lifecycle is
+replaced. A callback that has already started must honor its `AbortSignal` to stop
+its own side effects.
+The injected `resumeQuit` port must re-enter the registered guard synchronously;
+an asynchronous wrapper is treated as a fresh request. OS shutdown paths that do
+not emit `before-quit`, and updater flows that emit it after windows close, remain
+host-owned lifecycle concerns outside this guard.
+
+For external links, keep the product allowlist outside the Kit and pass only an
+opaque link id into the generic helper:
+
+```ts
+const PRODUCT_LINKS = {
+  docs: 'https://example.com/docs',
+} as const;
+
+await openAllowlistedExternalLink({
+  allowlist: PRODUCT_LINKS,
+  linkId: 'docs',
+  openExternal: (url) => electronShell.openExternal(url),
+});
+```
+
 ## Typed preload scaffold (`./preload`)
 
 Secure renderer↔main pattern: allowlisted invoke/subscribe + `contextBridge`
@@ -74,12 +143,13 @@ declare global {
 }
 
 await window.workbenchKit.window.minimize();
+const isMaximized = await window.workbenchKit.window.toggleMaximized();
 ```
 
 ### Enablement checklist
 
 1. `contextIsolation: true`, `nodeIntegration: false` on BrowserWindow
-2. Register main IPC with `registerWindowControlIpc` + `requireOwnedWindowForSender`
+2. Register main IPC with `registerWindowControlIpc` + an owned-window resolver
 3. Build preload with `createWorkbenchKitPreloadApi` + `exposeWorkbenchKitPreload`
 4. Do **not** expose `ipcRenderer`, `require`, or Node builtins to the page
 5. Keep channel names host-owned; only allowlist channels the scaffold will call

package/dist/lifecycle/application-quit-guard.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApplicationQuitGuard = createApplicationQuitGuard;
+class ApplicationQuitGuardAbort extends Error {
+    constructor(kind) {
+        super(`Application quit guard request was ${kind}.`);
+        this.kind = kind;
+        this.name = 'ApplicationQuitGuardAbort';
+    }
+}
+function validateTimeoutMs(timeoutMs) {
+    if (timeoutMs !== undefined &&
+        (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647)) {
+        throw new RangeError('Application quit guard timeoutMs must be a positive safe integer no greater than 2147483647.');
+    }
+}
+function raceWithAbort(operation, signal, readAbortKind) {
+    if (signal.aborted) {
+        return Promise.reject(new ApplicationQuitGuardAbort(readAbortKind()));
+    }
+    const operationPromise = Promise.resolve().then(() => {
+        if (signal.aborted) {
+            throw new ApplicationQuitGuardAbort(readAbortKind());
+        }
+        return operation();
+    });
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            reject(new ApplicationQuitGuardAbort(readAbortKind()));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        operationPromise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+    });
+}
+/**
+ * Coordinate an Electron-style before-quit boundary without importing Electron.
+ * The host owns event registration, dirty state, prompts, persistence, and quit invocation.
+ */
+function createApplicationQuitGuard(options) {
+    const timeoutMs = options.timeoutMs;
+    validateTimeoutMs(timeoutMs);
+    let generation = 0;
+    let inFlight = null;
+    let pendingController = null;
+    let resumePermit = false;
+    const startRequest = () => {
+        const requestGeneration = ++generation;
+        const controller = new AbortController();
+        let abortKind = 'cancelled';
+        let timeout;
+        pendingController = controller;
+        if (timeoutMs !== undefined) {
+            timeout = setTimeout(() => {
+                if (requestGeneration !== generation || controller.signal.aborted) {
+                    return;
+                }
+                abortKind = 'timeout';
+                controller.abort();
+            }, timeoutMs);
+        }
+        const isCurrent = () => requestGeneration === generation;
+        const run = (operation) => raceWithAbort(operation, controller.signal, () => abortKind);
+        const recheckAndResume = async (reason) => {
+            const dirty = await run(() => options.isDirty(controller.signal));
+            if (dirty !== false && dirty !== true) {
+                throw new TypeError('Application quit guard isDirty must return a boolean.');
+            }
+            if (dirty) {
+                return { status: 'blocked', reason: 'still-dirty' };
+            }
+            return resume(reason);
+        };
+        const resume = (reason) => {
+            // The decision is now irreversible. `cancelPending` must not report a cancellable request
+            // while the host is synchronously re-entering before-quit.
+            if (isCurrent()) {
+                pendingController = null;
+            }
+            resumePermit = true;
+            try {
+                options.resumeQuit();
+            }
+            finally {
+                // Electron re-enters before-quit synchronously. Never leave a permit for a later request.
+                resumePermit = false;
+            }
+            return { status: 'proceed', reason };
+        };
+        const execute = async () => {
+            try {
+                const dirty = await run(() => options.isDirty(controller.signal));
+                if (dirty !== false && dirty !== true) {
+                    throw new TypeError('Application quit guard isDirty must return a boolean.');
+                }
+                if (!dirty) {
+                    return resume('clean');
+                }
+                const decision = await run(() => options.requestDecision(controller.signal));
+                if (decision === 'cancel') {
+                    return { status: 'cancelled' };
+                }
+                if (decision === 'save') {
+                    await run(() => options.save(controller.signal));
+                    return await recheckAndResume('saved');
+                }
+                if (decision === 'discard') {
+                    await run(() => options.discard(controller.signal));
+                    return await recheckAndResume('discarded');
+                }
+                throw new TypeError('Application quit guard requestDecision must return save, discard, or cancel.');
+            }
+            catch (error) {
+                if (error instanceof ApplicationQuitGuardAbort) {
+                    return error.kind === 'timeout'
+                        ? { status: 'blocked', reason: 'timeout' }
+                        : { status: 'cancelled' };
+                }
+                return { status: 'blocked', reason: 'error', error };
+            }
+            finally {
+                if (timeout !== undefined) {
+                    clearTimeout(timeout);
+                }
+                if (isCurrent()) {
+                    inFlight = null;
+                    pendingController = null;
+                }
+            }
+        };
+        return execute();
+    };
+    return {
+        handleBeforeQuit(event) {
+            if (resumePermit) {
+                resumePermit = false;
+                return undefined;
+            }
+            event.preventDefault();
+            if (inFlight !== null) {
+                return inFlight;
+            }
+            inFlight = startRequest();
+            return inFlight;
+        },
+        cancelPending() {
+            if (inFlight === null || pendingController === null) {
+                return false;
+            }
+            const controller = pendingController;
+            generation += 1;
+            inFlight = null;
+            pendingController = null;
+            controller.abort();
+            return true;
+        },
+    };
+}

package/dist/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/security/open-allowlisted-external-link.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidExternalLinkUrlError = exports.UnknownExternalLinkIdError = void 0;
+exports.openAllowlistedExternalLink = openAllowlistedExternalLink;
+class UnknownExternalLinkIdError extends Error {
+    constructor(linkId) {
+        super('External link id is not in the allowlist.');
+        this.code = 'unknown_external_link_id';
+        this.name = 'UnknownExternalLinkIdError';
+        this.linkId = linkId;
+    }
+}
+exports.UnknownExternalLinkIdError = UnknownExternalLinkIdError;
+class InvalidExternalLinkUrlError extends Error {
+    constructor(linkId, message = 'Allowlisted external link URL is invalid.') {
+        super(message);
+        this.code = 'invalid_external_link_url';
+        this.name = 'InvalidExternalLinkUrlError';
+        this.linkId = linkId;
+    }
+}
+exports.InvalidExternalLinkUrlError = InvalidExternalLinkUrlError;
+function assertHttpsUrl(linkId, url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new InvalidExternalLinkUrlError(linkId, 'Allowlisted external link URL is not absolute.');
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new InvalidExternalLinkUrlError(linkId, 'Allowlisted external link URL must use http: or https:.');
+    }
+}
+/**
+ * Resolve an opaque link id through a host-injected allowlist, then open via `openExternal`.
+ * Pair IPC entry with `requireOwnedWindowForSender`. No product URL catalogs in kit.
+ */
+async function openAllowlistedExternalLink(input) {
+    const linkId = input.linkId.trim();
+    if (linkId.length === 0) {
+        throw new UnknownExternalLinkIdError(linkId);
+    }
+    const url = input.allowlist[linkId];
+    if (typeof url !== 'string' || url.trim().length === 0) {
+        throw new UnknownExternalLinkIdError(linkId);
+    }
+    const resolvedUrl = url.trim();
+    assertHttpsUrl(linkId, resolvedUrl);
+    await input.openExternal(resolvedUrl);
+}

package/dist/security/require-owned-window-for-sender.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UntrustedIpcSenderError = void 0;
+exports.requireOwnedWindowForSender = requireOwnedWindowForSender;
+class UntrustedIpcSenderError extends Error {
+    constructor(message = 'IPC sender is not bound to an owned window.') {
+        super(message);
+        this.code = 'untrusted_ipc_sender';
+        this.name = 'UntrustedIpcSenderError';
+    }
+}
+exports.UntrustedIpcSenderError = UntrustedIpcSenderError;
+/**
+ * Resolve an IPC sender to a host-owned window handle, or throw.
+ * Hosts own registry membership; kit owns the gate.
+ */
+function requireOwnedWindowForSender(sender, resolveOwnedWindow) {
+    const windowHandle = resolveOwnedWindow(sender);
+    if (windowHandle === null) {
+        throw new UntrustedIpcSenderError();
+    }
+    return windowHandle;
+}

package/dist/window/window-controls.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextMaximizedState = nextMaximizedState;
+exports.registerWindowControlIpc = registerWindowControlIpc;
+exports.createWindowControlsBridge = createWindowControlsBridge;
+const require_owned_window_for_sender_js_1 = require("../security/require-owned-window-for-sender.js");
+/** Pure helper: next maximized state after a toggle. */
+function nextMaximizedState(isMaximized) {
+    return !isMaximized;
+}
+/**
+ * Register frameless window-control IPC handlers on an injected ipcMain.
+ * Hosts inject channel names and resolve owned windows (pair with sender gate).
+ */
+function registerWindowControlIpc(options) {
+    const { ipcMain, channels, resolveWindow, resolveWebContents } = options;
+    const unsubscribers = new Map();
+    const resolveOwned = (sender) => (0, require_owned_window_for_sender_js_1.requireOwnedWindowForSender)(sender, resolveWindow);
+    const ensureMaximizedPush = (sender, windowSurface) => {
+        if (!windowSurface.onMaximizedChange || unsubscribers.has(sender)) {
+            return;
+        }
+        const unsubscribe = windowSurface.onMaximizedChange((maximized) => {
+            const webContents = resolveWebContents?.(sender) ?? null;
+            webContents?.send(channels.maximizedChanged, maximized);
+        });
+        unsubscribers.set(sender, unsubscribe);
+    };
+    ipcMain.handle(channels.minimize, (event) => {
+        const windowSurface = resolveOwned(event.sender);
+        ensureMaximizedPush(event.sender, windowSurface);
+        windowSurface.minimize();
+    });
+    ipcMain.handle(channels.toggleMaximized, (event) => {
+        const windowSurface = resolveOwned(event.sender);
+        ensureMaximizedPush(event.sender, windowSurface);
+        if (windowSurface.isMaximized()) {
+            windowSurface.unmaximize();
+        }
+        else {
+            windowSurface.maximize();
+        }
+        return windowSurface.isMaximized();
+    });
+    ipcMain.handle(channels.close, (event) => {
+        const windowSurface = resolveOwned(event.sender);
+        windowSurface.close();
+    });
+    ipcMain.handle(channels.isMaximized, (event) => {
+        const windowSurface = resolveOwned(event.sender);
+        ensureMaximizedPush(event.sender, windowSurface);
+        return windowSurface.isMaximized();
+    });
+    return () => {
+        for (const unsubscribe of unsubscribers.values()) {
+            unsubscribe();
+        }
+        unsubscribers.clear();
+    };
+}
+/**
+ * Preload/renderer bridge factory for window controls.
+ * Channel names are injected; kit owns the invoke/subscribe shape.
+ */
+function createWindowControlsBridge(options) {
+    const { channels, invoke, subscribe } = options;
+    return {
+        minimize: async () => {
+            await invoke(channels.minimize);
+        },
+        toggleMaximized: async () => {
+            const value = await invoke(channels.toggleMaximized);
+            return Boolean(value);
+        },
+        close: async () => {
+            await invoke(channels.close);
+        },
+        isMaximized: async () => {
+            const value = await invoke(channels.isMaximized);
+            return Boolean(value);
+        },
+        onMaximizedChanged: (listener) => subscribe(channels.maximizedChanged, (maximized) => {
+            listener(Boolean(maximized));
+        }),
+    };
+}

package/package.json

@@ -1,20 +1,65 @@
 {
   "name": "@workbench-kit/electron-shell",
-  "version": "0.0.2-prototype.0.2.26",
+  "version": "0.0.2-prototype.0.2.27",
   "private": false,
   "type": "module",
+  "types": "./src/index.ts",
+  "typesVersions": {
+    "*": {
+      "application-quit-guard": [
+        "src/lifecycle/application-quit-guard.ts"
+      ],
+      "external-links": [
+        "src/security/open-allowlisted-external-link.ts"
+      ],
+      "preload": [
+        "src/preload/index.ts"
+      ],
+      "sender-security": [
+        "src/security/require-owned-window-for-sender.ts"
+      ],
+      "window-controls": [
+        "src/window/window-controls.ts"
+      ]
+    }
+  },
   "exports": {
     ".": "./src/index.ts",
-    "./preload": "./src/preload/index.ts"
+    "./application-quit-guard": {
+      "types": "./src/lifecycle/application-quit-guard.ts",
+      "require": "./dist/lifecycle/application-quit-guard.js",
+      "import": "./src/lifecycle/application-quit-guard.ts",
+      "default": "./src/lifecycle/application-quit-guard.ts"
+    },
+    "./external-links": {
+      "types": "./src/security/open-allowlisted-external-link.ts",
+      "require": "./dist/security/open-allowlisted-external-link.js",
+      "import": "./src/security/open-allowlisted-external-link.ts",
+      "default": "./src/security/open-allowlisted-external-link.ts"
+    },
+    "./preload": "./src/preload/index.ts",
+    "./sender-security": {
+      "types": "./src/security/require-owned-window-for-sender.ts",
+      "require": "./dist/security/require-owned-window-for-sender.js",
+      "import": "./src/security/require-owned-window-for-sender.ts",
+      "default": "./src/security/require-owned-window-for-sender.ts"
+    },
+    "./window-controls": {
+      "types": "./src/window/window-controls.ts",
+      "require": "./dist/window/window-controls.js",
+      "import": "./src/window/window-controls.ts",
+      "default": "./src/window/window-controls.ts"
+    }
   },
   "files": [
+    "dist",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
     "!src/**/*.stories.ts",
     "!src/**/*.stories.tsx"
   ],
-  "description": "Electron main-process helpers for Workbench Kit hosts (window controls, asset protocol, secret vault) plus a typed preload scaffold.",
+  "description": "Electron main-process helpers for Workbench Kit hosts (quit lifecycle, window controls, asset protocol, secret vault) plus a typed preload scaffold.",
   "publishConfig": {
     "access": "public",
     "tag": "prototype",
@@ -26,6 +71,8 @@
     "directory": "packages/electron-shell"
   },
   "scripts": {
+    "prebuild": "node scripts/clean-dist.mjs",
+    "build": "tsc -p tsconfig.cjs.json && node scripts/write-cjs-package.mjs",
     "test": "vitest run src",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }

package/src/index.ts

@@ -1,3 +1,12 @@
+export {
+  createApplicationQuitGuard,
+  type ApplicationQuitDecision,
+  type ApplicationQuitEvent,
+  type ApplicationQuitGuard,
+  type ApplicationQuitGuardResult,
+  type ApplicationQuitProceedReason,
+  type CreateApplicationQuitGuardOptions,
+} from './lifecycle/application-quit-guard.js';
 export {
   createEncryptedSecretVault,
   EncryptionUnavailableError,

package/src/lifecycle/application-quit-guard.ts

@@ -0,0 +1,251 @@
+export interface ApplicationQuitEvent {
+  preventDefault(): void;
+}
+
+export type ApplicationQuitDecision = 'cancel' | 'discard' | 'save';
+
+export type ApplicationQuitProceedReason = 'clean' | 'discarded' | 'saved';
+
+export type ApplicationQuitGuardResult =
+  | {
+      readonly status: 'proceed';
+      readonly reason: ApplicationQuitProceedReason;
+    }
+  | {
+      readonly status: 'cancelled';
+    }
+  | {
+      readonly status: 'blocked';
+      readonly reason: 'still-dirty' | 'timeout';
+    }
+  | {
+      readonly status: 'blocked';
+      readonly reason: 'error';
+      readonly error: unknown;
+    };
+
+export interface CreateApplicationQuitGuardOptions {
+  /** Return whether application-owned state currently needs a quit decision. */
+  readonly isDirty: (signal: AbortSignal) => boolean | Promise<boolean>;
+  /** Ask the integrating host how a dirty quit request should be handled. */
+  readonly requestDecision: (
+    signal: AbortSignal,
+  ) => ApplicationQuitDecision | Promise<ApplicationQuitDecision>;
+  /** Persist dirty state before the guard checks it again. */
+  readonly save: (signal: AbortSignal) => void | Promise<void>;
+  /** Drop dirty state before the guard checks it again. */
+  readonly discard: (signal: AbortSignal) => void | Promise<void>;
+  /** Re-enter the host quit path. The next synchronous before-quit event is allowed once. */
+  readonly resumeQuit: () => void;
+  /** Optional bound for the complete check, decision, action, and recheck flow. */
+  readonly timeoutMs?: number;
+}
+
+export interface ApplicationQuitGuard {
+  /**
+   * Veto and coordinate a before-quit request. Concurrent requests share one result.
+   * Returns undefined only for the one synchronous re-entry allowed by `resumeQuit`.
+   */
+  handleBeforeQuit(event: ApplicationQuitEvent): Promise<ApplicationQuitGuardResult> | undefined;
+  /**
+   * Abort and invalidate the current request. Late guard completion is ignored, but an
+   * already-started callback must honor its AbortSignal to stop its own side effects.
+   * Returns false when no request is pending.
+   */
+  cancelPending(): boolean;
+}
+
+type AbortKind = 'cancelled' | 'timeout';
+
+class ApplicationQuitGuardAbort extends Error {
+  constructor(readonly kind: AbortKind) {
+    super(`Application quit guard request was ${kind}.`);
+    this.name = 'ApplicationQuitGuardAbort';
+  }
+}
+
+function validateTimeoutMs(timeoutMs: number | undefined): void {
+  if (
+    timeoutMs !== undefined &&
+    (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
+  ) {
+    throw new RangeError(
+      'Application quit guard timeoutMs must be a positive safe integer no greater than 2147483647.',
+    );
+  }
+}
+
+function raceWithAbort<Value>(
+  operation: () => Value | Promise<Value>,
+  signal: AbortSignal,
+  readAbortKind: () => AbortKind,
+): Promise<Value> {
+  if (signal.aborted) {
+    return Promise.reject(new ApplicationQuitGuardAbort(readAbortKind()));
+  }
+
+  const operationPromise = Promise.resolve().then(() => {
+    if (signal.aborted) {
+      throw new ApplicationQuitGuardAbort(readAbortKind());
+    }
+    return operation();
+  });
+  return new Promise<Value>((resolve, reject) => {
+    const onAbort = (): void => {
+      reject(new ApplicationQuitGuardAbort(readAbortKind()));
+    };
+
+    signal.addEventListener('abort', onAbort, { once: true });
+    operationPromise.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort);
+        resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener('abort', onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Coordinate an Electron-style before-quit boundary without importing Electron.
+ * The host owns event registration, dirty state, prompts, persistence, and quit invocation.
+ */
+export function createApplicationQuitGuard(
+  options: CreateApplicationQuitGuardOptions,
+): ApplicationQuitGuard {
+  const timeoutMs = options.timeoutMs;
+  validateTimeoutMs(timeoutMs);
+
+  let generation = 0;
+  let inFlight: Promise<ApplicationQuitGuardResult> | null = null;
+  let pendingController: AbortController | null = null;
+  let resumePermit = false;
+
+  const startRequest = (): Promise<ApplicationQuitGuardResult> => {
+    const requestGeneration = ++generation;
+    const controller = new AbortController();
+    let abortKind: AbortKind = 'cancelled';
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+
+    pendingController = controller;
+    if (timeoutMs !== undefined) {
+      timeout = setTimeout(() => {
+        if (requestGeneration !== generation || controller.signal.aborted) {
+          return;
+        }
+        abortKind = 'timeout';
+        controller.abort();
+      }, timeoutMs);
+    }
+
+    const isCurrent = (): boolean => requestGeneration === generation;
+    const run = <Value>(operation: () => Value | Promise<Value>): Promise<Value> =>
+      raceWithAbort(operation, controller.signal, () => abortKind);
+
+    const recheckAndResume = async (
+      reason: Exclude<ApplicationQuitProceedReason, 'clean'>,
+    ): Promise<ApplicationQuitGuardResult> => {
+      const dirty = await run(() => options.isDirty(controller.signal));
+      if (dirty !== false && dirty !== true) {
+        throw new TypeError('Application quit guard isDirty must return a boolean.');
+      }
+      if (dirty) {
+        return { status: 'blocked', reason: 'still-dirty' };
+      }
+      return resume(reason);
+    };
+
+    const resume = (reason: ApplicationQuitProceedReason): ApplicationQuitGuardResult => {
+      // The decision is now irreversible. `cancelPending` must not report a cancellable request
+      // while the host is synchronously re-entering before-quit.
+      if (isCurrent()) {
+        pendingController = null;
+      }
+      resumePermit = true;
+      try {
+        options.resumeQuit();
+      } finally {
+        // Electron re-enters before-quit synchronously. Never leave a permit for a later request.
+        resumePermit = false;
+      }
+      return { status: 'proceed', reason };
+    };
+
+    const execute = async (): Promise<ApplicationQuitGuardResult> => {
+      try {
+        const dirty = await run(() => options.isDirty(controller.signal));
+        if (dirty !== false && dirty !== true) {
+          throw new TypeError('Application quit guard isDirty must return a boolean.');
+        }
+        if (!dirty) {
+          return resume('clean');
+        }
+
+        const decision = await run(() => options.requestDecision(controller.signal));
+        if (decision === 'cancel') {
+          return { status: 'cancelled' };
+        }
+        if (decision === 'save') {
+          await run(() => options.save(controller.signal));
+          return await recheckAndResume('saved');
+        }
+        if (decision === 'discard') {
+          await run(() => options.discard(controller.signal));
+          return await recheckAndResume('discarded');
+        }
+        throw new TypeError(
+          'Application quit guard requestDecision must return save, discard, or cancel.',
+        );
+      } catch (error: unknown) {
+        if (error instanceof ApplicationQuitGuardAbort) {
+          return error.kind === 'timeout'
+            ? { status: 'blocked', reason: 'timeout' }
+            : { status: 'cancelled' };
+        }
+        return { status: 'blocked', reason: 'error', error };
+      } finally {
+        if (timeout !== undefined) {
+          clearTimeout(timeout);
+        }
+        if (isCurrent()) {
+          inFlight = null;
+          pendingController = null;
+        }
+      }
+    };
+
+    return execute();
+  };
+
+  return {
+    handleBeforeQuit(event) {
+      if (resumePermit) {
+        resumePermit = false;
+        return undefined;
+      }
+
+      event.preventDefault();
+      if (inFlight !== null) {
+        return inFlight;
+      }
+
+      inFlight = startRequest();
+      return inFlight;
+    },
+    cancelPending() {
+      if (inFlight === null || pendingController === null) {
+        return false;
+      }
+
+      const controller = pendingController;
+      generation += 1;
+      inFlight = null;
+      pendingController = null;
+      controller.abort();
+      return true;
+    },
+  };
+}

package/src/window/window-controls.ts

@@ -44,7 +44,8 @@ export interface RegisterWindowControlIpcOptions {
 
 export interface WindowControlsBridge {
   minimize(): Promise<void>;
-  toggleMaximized(): Promise<void>;
+  /** Toggle the host window and resolve to its final maximized state. */
+  toggleMaximized(): Promise<boolean>;
   close(): Promise<void>;
   isMaximized(): Promise<boolean>;
   onMaximizedChanged(listener: (maximized: boolean) => void): () => void;
@@ -133,7 +134,8 @@ export function createWindowControlsBridge(
       await invoke(channels.minimize);
     },
     toggleMaximized: async () => {
-      await invoke(channels.toggleMaximized);
+      const value = await invoke(channels.toggleMaximized);
+      return Boolean(value);
     },
     close: async () => {
       await invoke(channels.close);