feat: route macOS Dock-reopen to the app activate event via an NSApplicationDelegate

Author: ipfizz

src/main/api/app.ts

@@ -59,6 +59,7 @@ export class App extends EventEmitter {
     this.#singleInstance = undefined;
     this.#pathOverrides.clear();
     for (const event of [
+      'activate',
       'window-all-closed',
       'browser-window-created',
       'browser-window-focus',

src/main/bootstrap.ts

@@ -1,3 +1,4 @@
+import { makeCancelableEvent } from '../common/cancelable-event';
 import { app } from './api/app';
 import { nativeApp } from './native-app';
 
@@ -20,6 +21,10 @@ export const ensureNativeStarted = (): void => {
   started = true;
   const native = nativeApp();
   native.onReady(() => app.markReady());
+  // macOS Dock-reopen → Electron's `activate` (Linux backends omit onActivate).
+  native.onActivate?.((hasVisibleWindows) => {
+    app.emit('activate', makeCancelableEvent(), hasVisibleWindows);
+  });
   native.start();
 };
 

src/main/platform/macos/cocoa-app-delegate.ts

@@ -0,0 +1,64 @@
+import { cocoa } from './cocoa-runtime';
+import { defineObjcClass } from './cocoa-runtime-class';
+import type { Handle } from './objc';
+
+/**
+ * Bridges `NSApplicationDelegate` callbacks to JS (D026).
+ *
+ * AppKit reports app-level activation to the application's delegate. We define
+ * the delegate class once at runtime, instantiate one, and route its callbacks
+ * to the registered JS handlers — the same mechanism proven for the window and
+ * navigation delegates.
+ *
+ * `applicationShouldHandleReopen:hasVisibleWindows:` is AppKit's Dock-reopen
+ * hook and the source of Electron's `activate` event. The delegate object is
+ * created with `alloc`/`init` (retain count +1) and never released, so it
+ * outlives `NSApp` (which holds its delegate weakly).
+ */
+
+/** JS handlers an `NSApplicationDelegate` instance routes callbacks to. */
+export type AppDelegateHandlers = {
+  /** The app was re-activated; `hasVisibleWindows` is AppKit's flag. */
+  readonly activate: (hasVisibleWindows: boolean) => void;
+};
+
+let delegateClass: Handle | undefined;
+let current: AppDelegateHandlers | undefined;
+
+const ensureDelegateClass = (): Handle => {
+  if (delegateClass !== undefined) {
+    return delegateClass;
+  }
+  delegateClass = defineObjcClass('SambarAppDelegate', 'NSObject', [
+    {
+      // BOOL applicationShouldHandleReopen:(id)sender hasVisibleWindows:(BOOL)flag
+      selector: 'applicationShouldHandleReopen:hasVisibleWindows:',
+      typeEncoding: 'c@:@c',
+      args: ['object', 'object'],
+      returns: 'bool',
+      impl: (_self, _cmd, _sender, hasVisibleWindows) => {
+        current?.activate(hasVisibleWindows === 1n);
+        // Return YES so AppKit performs its default reopen behavior.
+        return 1;
+      },
+    },
+  ]);
+  return delegateClass;
+};
+
+/** The Objective-C delegate instance to pass to `[NSApp setDelegate:]`. */
+export type AppDelegate = {
+  readonly handle: Handle;
+};
+
+/**
+ * Create an `NSApplicationDelegate` instance routing callbacks to `handlers`.
+ * There is one application delegate per process; the most recent handlers win.
+ */
+export const createAppDelegate = (handlers: AppDelegateHandlers): AppDelegate => {
+  const rt = cocoa();
+  const cls = ensureDelegateClass();
+  current = handlers;
+  const handle = rt.msgSend(rt.msgSend(cls, rt.selectors.get('alloc')), rt.selectors.get('init'));
+  return { handle };
+};

src/main/platform/macos/cocoa-backend.ts

@@ -31,6 +31,7 @@ import {
   msgSendSize,
   msgSendU8,
 } from './cocoa-msgsend-variants';
+import { createAppDelegate } from './cocoa-app-delegate';
 import { createMacOSDrain } from './cocoa-run-loop';
 import { cocoa } from './cocoa-runtime';
 import { createNavigationDelegate } from './cocoa-navigation-delegate';
@@ -462,8 +463,10 @@ class MacOSWindow implements NativeWindow {
 class MacOSApplication implements NativeApplication {
   #started = false;
   #app: Handle = 0n;
+  #appDelegate: Handle = 0n;
   #pump: CooperativePump | undefined;
   #readyCallbacks: Array<() => void> = [];
+  #onActivate: ((hasVisibleWindows: boolean) => void) | undefined;
 
   start(): void {
     if (this.#started) {
@@ -472,6 +475,13 @@ class MacOSApplication implements NativeApplication {
     const rt = cocoa();
     loadWebKit();
     this.#app = rt.msgSend(rt.classes.get('NSApplication'), rt.selectors.get('sharedApplication'));
+    // Install the application delegate (Dock-reopen → activate). NSApp holds its
+    // delegate weakly, so the +1 from alloc/init (never released) keeps it alive.
+    const delegate = createAppDelegate({
+      activate: (hasVisibleWindows) => this.#onActivate?.(hasVisibleWindows),
+    });
+    this.#appDelegate = delegate.handle;
+    msgSendPtr(this.#app, rt.selectors.get('setDelegate:'), this.#appDelegate);
     msgSendI64(this.#app, rt.selectors.get('setActivationPolicy:'), NS_ACTIVATION_POLICY_REGULAR);
     rt.msgSend(this.#app, rt.selectors.get('finishLaunching'));
     msgSendU8(this.#app, rt.selectors.get('activateIgnoringOtherApps:'), 1);
@@ -496,6 +506,10 @@ class MacOSApplication implements NativeApplication {
     }
   }
 
+  onActivate(callback: (hasVisibleWindows: boolean) => void): void {
+    this.#onActivate = callback;
+  }
+
   createWindow(options: NativeWindowOptions): NativeWindow {
     const rt = cocoa();
     const frame: readonly [number, number, number, number] = [0, 0, options.width, options.height];

src/main/platform/native.ts

@@ -141,4 +141,11 @@ export interface NativeApplication {
   createWindow(options: NativeWindowOptions): NativeWindow;
   /** Stop the run loop and release the application. */
   quit(): void;
+  /**
+   * Register a callback fired when the app is re-activated (Electron's `activate`
+   * — e.g. a macOS Dock-icon click), receiving whether any windows are visible.
+   * Optional: platforms without an activation concept (Linux) omit it. Must be
+   * registered before {@link start}.
+   */
+  onActivate?(callback: (hasVisibleWindows: boolean) => void): void;
 }

tests/integration/macos/cocoa-app-delegate.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'bun:test';
+import { currentPlatform } from '../../../src/common/platform';
+import { createAppDelegate } from '../../../src/main/platform/macos/cocoa-app-delegate';
+import { msgSendPtr } from '../../../src/main/platform/macos/cocoa-msgsend-variants';
+import { cocoa } from '../../../src/main/platform/macos/cocoa-runtime';
+
+/**
+ * Drives the runtime `SambarAppDelegate` against the real Objective-C runtime.
+ * The Dock-reopen callback routing uses the same `defineObjcClass` JSCallback
+ * mechanism as the (CI-proven) window/navigation delegates; here we prove the
+ * class builds, instantiates, and installs as `NSApp`'s delegate.
+ */
+
+if (currentPlatform() === 'macos') {
+  describe('SambarAppDelegate on the real macOS runtime', () => {
+    test('createAppDelegate returns a live instance', () => {
+      const delegate = createAppDelegate({ activate: () => undefined });
+      expect(delegate.handle).not.toBe(0n);
+    });
+
+    test('installs on NSApp and reads back via -delegate', () => {
+      const rt = cocoa();
+      const nsApp = rt.msgSend(
+        rt.classes.get('NSApplication'),
+        rt.selectors.get('sharedApplication'),
+      );
+      const delegate = createAppDelegate({ activate: () => undefined });
+      msgSendPtr(nsApp, rt.selectors.get('setDelegate:'), delegate.handle);
+      expect(rt.msgSend(nsApp, rt.selectors.get('delegate'))).toBe(delegate.handle);
+    });
+  });
+}

tests/unit/main/bootstrap.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { app } from '../../../src/main/api/app';
+import { ensureNativeStarted, resetBootstrapForTesting } from '../../../src/main/bootstrap';
+import { setNativeAppForTesting } from '../../../src/main/native-app';
+import type { NativeApplication } from '../../../src/main/platform/native';
+import { installSafeAppExit } from '../../helpers/safe-app-exit';
+
+/** A fake native app exposing a trigger for its registered activate callback. */
+const makeNative = (): { native: NativeApplication; activate: (v: boolean) => void } => {
+  let cb: ((v: boolean) => void) | undefined;
+  const native: NativeApplication = {
+    start: () => undefined,
+    onReady: (ready) => ready(),
+    createWindow: () => {
+      throw new Error('createWindow not used in bootstrap tests');
+    },
+    quit: () => undefined,
+    onActivate: (c) => {
+      cb = c;
+    },
+  };
+  return { native, activate: (v) => cb?.(v) };
+};
+
+describe('bootstrap native wiring', () => {
+  afterEach(() => {
+    setNativeAppForTesting(undefined);
+    app.resetForTesting();
+    resetBootstrapForTesting();
+  });
+
+  test('forwards native activate to the app activate event with hasVisibleWindows', () => {
+    installSafeAppExit();
+    const { native, activate } = makeNative();
+    resetBootstrapForTesting();
+    setNativeAppForTesting(native);
+    ensureNativeStarted();
+    let seen: boolean | undefined;
+    app.on('activate', (_event: unknown, hasVisibleWindows: boolean) => {
+      seen = hasVisibleWindows;
+    });
+    activate(true);
+    expect(seen).toBe(true);
+  });
+
+  test('marks the app ready once the native app signals ready', () => {
+    installSafeAppExit();
+    const { native } = makeNative();
+    resetBootstrapForTesting();
+    setNativeAppForTesting(native);
+    ensureNativeStarted();
+    expect(app.isReady).toBe(true);
+  });
+});