electron-osx-spaces 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toru Nayuki
+
+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

@@ -0,0 +1,77 @@
+# electron-osx-spaces
+
+Save and restore Electron window positions across macOS Spaces (virtual desktops).
+
+## Why?
+
+Electron does not participate in macOS State Restoration, so windows always open on the current Space. This package captures AppKit's native restoration data and replays it on the next launch, putting windows back on the Space where they were saved.
+
+## Install
+
+```bash
+npm install electron-osx-spaces
+```
+
+Requires Xcode Command Line Tools for the native addon build.
+
+## Usage
+
+```js
+const { app, BrowserWindow } = require('electron');
+const spaces = require('electron-osx-spaces');
+
+let win;
+
+app.whenReady().then(() => {
+  win = new BrowserWindow({ width: 800, height: 600 });
+
+  // Restore from previously saved data
+  const saved = loadState(); // your persistence layer
+  if (saved) {
+    spaces.restoreState(win, saved, { restoreSpace: true });
+  }
+});
+
+app.on('before-quit', () => {
+  // Save the window's Space + frame state
+  const data = spaces.encodeState(win);
+  if (data) {
+    saveState(data); // store as Buffer or base64
+  }
+});
+```
+
+## API
+
+### `spaces.encodeState(win: BrowserWindow): Buffer | null`
+
+Encodes the window's current frame and Space information into an opaque Buffer. Returns `null` on non-macOS platforms or if encoding fails.
+
+### `spaces.restoreState(win: BrowserWindow, data: Buffer, options?: RestoreOptions): boolean`
+
+Restores the window's frame and Space from a previously encoded Buffer. Returns `true` if restoration succeeded.
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `restoreSpace` | `boolean` | `true` | Whether to restore the Space (virtual desktop) |
+
+## How it works
+
+1. `encodeState` calls `NSWindow.encodeRestorableStateWithCoder:` to capture AppKit's native restoration data (frame + Space info) as a binary archive
+2. Your app persists the binary (e.g. as base64 in a JSON file)
+3. On next launch, `restoreState` calls `NSWindow.restoreStateWithCoder:` to replay the data, and macOS moves the window to the original Space
+
+An `NSKeyedArchiverDelegate` is used to skip objects that don't support `NSSecureCoding` (such as Electron's internal NSView subclasses).
+
+On macOS 15+, a workaround for broken `NSWindowRestoresWorkspaceAtLaunch` is applied via a private API override. This makes the package **incompatible with Mac App Store** distribution.
+
+## Platform support
+
+- **macOS**: Full functionality
+- **Other platforms**: No-op (functions return `null` / `false`)
+
+## License
+
+MIT

package/binding.gyp

@@ -0,0 +1,20 @@
+{
+  "targets": [
+    {
+      "target_name": "spaces",
+      "conditions": [
+        ["OS=='mac'", {
+          "sources": ["src/spaces.mm"],
+          "xcode_settings": {
+            "OTHER_CPLUSPLUSFLAGS": ["-std=c++17", "-ObjC++"],
+            "OTHER_LDFLAGS": ["-framework Cocoa"]
+          },
+          "include_dirs": [
+            "<!@(node -p \"require('node-addon-api').include\")"
+          ],
+          "defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"]
+        }]
+      ]
+    }
+  ]
+}

package/index.d.ts

@@ -0,0 +1,24 @@
+import { BrowserWindow } from 'electron';
+
+export interface RestoreOptions {
+  /** Whether to restore the Space (virtual desktop). Defaults to true. */
+  restoreSpace?: boolean;
+}
+
+/**
+ * Encode the current window state including Space (virtual desktop) info.
+ * Returns a Buffer containing the opaque AppKit restoration data,
+ * or null on non-macOS platforms or if encoding fails.
+ */
+export function encodeState(win: BrowserWindow): Buffer | null;
+
+/**
+ * Restore the window's state (frame + Space) from previously encoded data.
+ * Returns true if restoration succeeded, false otherwise.
+ * No-op on non-macOS platforms.
+ */
+export function restoreState(
+  win: BrowserWindow,
+  data: Buffer,
+  options?: RestoreOptions,
+): boolean;

package/index.js

@@ -0,0 +1,49 @@
+if (process.platform !== 'darwin') {
+  module.exports = {
+    encodeState() {
+      return null;
+    },
+    restoreState() {
+      return false;
+    },
+  };
+} else {
+  const native = require('./build/Release/spaces.node');
+
+  module.exports = {
+    /**
+     * Encode the current window state including Space (virtual desktop) info.
+     * Returns a Buffer containing the opaque AppKit restoration data,
+     * or null if encoding fails.
+     *
+     * @param {BrowserWindow} win - Electron BrowserWindow instance
+     * @returns {Buffer|null}
+     */
+    encodeState(win) {
+      try {
+        return native.encodeState(win.getNativeWindowHandle());
+      } catch {
+        return null;
+      }
+    },
+
+    /**
+     * Restore the window's state (frame + Space) from previously encoded data.
+     *
+     * @param {BrowserWindow} win - Electron BrowserWindow instance
+     * @param {Buffer} data - Data previously returned by encodeState()
+     * @param {object} [options]
+     * @param {boolean} [options.restoreSpace=true] - Whether to restore the Space
+     * @returns {boolean} true if restoration succeeded
+     */
+    restoreState(win, data, options) {
+      if (!data) return false;
+      try {
+        native.restoreState(win.getNativeWindowHandle(), data, options);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "electron-osx-spaces",
+  "version": "0.1.0",
+  "description": "Save and restore Electron window Spaces (virtual desktop) positions on macOS",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/spaces.mm",
+    "binding.gyp"
+  ],
+  "scripts": {
+    "install": "node-gyp rebuild",
+    "build": "node-gyp rebuild",
+    "clean": "node-gyp clean",
+    "example": "env -u ELECTRON_RUN_AS_NODE npx electron example/main.js",
+    "test": "env -u ELECTRON_RUN_AS_NODE npx electron test/smoke.js",
+    "lint": "npx @biomejs/biome check .",
+    "lint:fix": "npx @biomejs/biome check --write .",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "electron",
+    "macos",
+    "spaces",
+    "virtual-desktop",
+    "window-state",
+    "restore"
+  ],
+  "author": "Toru Nayuki",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tnayuki/electron-osx-spaces.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tnayuki/electron-osx-spaces/issues"
+  },
+  "homepage": "https://github.com/tnayuki/electron-osx-spaces#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "os": [
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "node-addon-api": "^8.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
+    "@electron/rebuild": "^4.0.3",
+    "electron": "^40.8.5",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "node-gyp": ">=9.0.0"
+  },
+  "lint-staged": {
+    "*.{js,json}": "npx @biomejs/biome check --write --no-errors-on-unmatched"
+  }
+}

package/src/spaces.mm

@@ -0,0 +1,172 @@
+#import <Cocoa/Cocoa.h>
+#import <napi.h>
+
+// NSKeyedArchiverDelegate to skip objects that cannot be securely encoded
+// (NSWindow itself, NSViews such as Electron's BridgedContentView).
+@interface SpacesArchiverDelegate : NSObject <NSKeyedArchiverDelegate>
+@property(nonatomic, assign) NSWindow* window;
+@end
+
+@implementation SpacesArchiverDelegate
+
+- (id)archiver:(NSKeyedArchiver*)archiver willEncodeObject:(id)object {
+    if (object == self.window)
+        return nil;
+    if ([object isKindOfClass:[NSView class]])
+        return nil;
+    return object;
+}
+
+@end
+
+// macOS 15 workaround for Space restoration (FB15644170).
+// Override _windowRestorationOptions to return a default-initialized value,
+// which tells AppKit to restore windows to their original Space.
+//
+// On macOS 14 and earlier, NSWindowRestoresWorkspaceAtLaunch UserDefault
+// controls this behavior instead.
+@interface SpacesKeyedUnarchiver : NSKeyedUnarchiver
+@property(nonatomic) BOOL shouldRestoreSpace;
+@end
+
+@implementation SpacesKeyedUnarchiver
+
+- (id)_windowRestorationOptions {
+    if (self.shouldRestoreSpace) {
+        return [[NSClassFromString(@"NSWindowRestorationOptions") alloc] init];
+    }
+    return nil;
+}
+
+@end
+
+static NSWindow* GetNSWindow(Napi::Value handle) {
+    auto buf = handle.As<Napi::Buffer<uint8_t>>();
+    NSView* view = *reinterpret_cast<NSView* __strong*>(buf.Data());
+    return [view window];
+}
+
+// Encode the window's restorable state (frame + Space info) into a Buffer.
+// Uses NSKeyedArchiverDelegate to skip NSView objects that don't adopt
+// NSSecureCoding.
+Napi::Value EncodeState(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+
+    if (info.Length() < 1 || !info[0].IsBuffer()) {
+        Napi::TypeError::New(env, "Expected native window handle (Buffer)")
+            .ThrowAsJavaScriptException();
+        return env.Undefined();
+    }
+
+    NSWindow* win = GetNSWindow(info[0]);
+    if (!win) {
+        Napi::Error::New(env, "Could not get NSWindow from handle")
+            .ThrowAsJavaScriptException();
+        return env.Undefined();
+    }
+
+    @try {
+        NSKeyedArchiver* encoder =
+            [[NSKeyedArchiver alloc] initRequiringSecureCoding:YES];
+        SpacesArchiverDelegate* delegate =
+            [[SpacesArchiverDelegate alloc] init];
+        delegate.window = win;
+        encoder.delegate = delegate;
+
+        [win encodeRestorableStateWithCoder:encoder];
+        [encoder finishEncoding];
+        NSData* data = encoder.encodedData;
+
+        return Napi::Buffer<uint8_t>::Copy(
+            env,
+            static_cast<const uint8_t*>(data.bytes),
+            data.length);
+    } @catch (NSException* exception) {
+        Napi::Error::New(
+            env,
+            std::string("encodeRestorableState failed: ") +
+                exception.reason.UTF8String)
+            .ThrowAsJavaScriptException();
+        return env.Undefined();
+    }
+}
+
+// Restore the window's state (frame + Space) from a previously encoded Buffer.
+Napi::Value RestoreState(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+
+    if (info.Length() < 2 || !info[0].IsBuffer() || !info[1].IsBuffer()) {
+        Napi::TypeError::New(
+            env, "Expected (nativeHandle: Buffer, stateData: Buffer)")
+            .ThrowAsJavaScriptException();
+        return env.Undefined();
+    }
+
+    bool restoreSpace = true;
+    if (info.Length() >= 3 && info[2].IsObject()) {
+        auto opts = info[2].As<Napi::Object>();
+        if (opts.Has("restoreSpace")) {
+            restoreSpace = opts.Get("restoreSpace").ToBoolean().Value();
+        }
+    }
+
+    NSWindow* win = GetNSWindow(info[0]);
+    if (!win) {
+        Napi::Error::New(env, "Could not get NSWindow from handle")
+            .ThrowAsJavaScriptException();
+        return env.Undefined();
+    }
+
+    auto buf = info[1].As<Napi::Buffer<uint8_t>>();
+    NSData* data = [NSData dataWithBytes:buf.Data() length:buf.Length()];
+
+    @try {
+        NSError* error = nil;
+        SpacesKeyedUnarchiver* decoder =
+            [[SpacesKeyedUnarchiver alloc] initForReadingFromData:data
+                                                           error:&error];
+        if (error) {
+            Napi::Error::New(
+                env,
+                std::string("Failed to create unarchiver: ") +
+                    error.localizedDescription.UTF8String)
+                .ThrowAsJavaScriptException();
+            return env.Undefined();
+        }
+
+        decoder.shouldRestoreSpace = restoreSpace;
+
+        // On macOS < 15, NSWindowRestoresWorkspaceAtLaunch UserDefault
+        // controls Space restoration. On macOS 15+, that UserDefault is
+        // broken (FB15644170, still unfixed as of macOS 26), so
+        // _windowRestorationOptions override is used instead.
+        if (restoreSpace) {
+            if (@available(macOS 15, *)) {
+                // _windowRestorationOptions override handles this
+            } else {
+                [NSUserDefaults.standardUserDefaults registerDefaults:@{
+                    @"NSWindowRestoresWorkspaceAtLaunch" : @YES
+                }];
+            }
+        }
+
+        [win restoreStateWithCoder:decoder];
+    } @catch (NSException* exception) {
+        Napi::Error::New(
+            env,
+            std::string("restoreStateWithCoder failed: ") +
+                exception.reason.UTF8String)
+            .ThrowAsJavaScriptException();
+        return env.Undefined();
+    }
+
+    return env.Undefined();
+}
+
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+    exports.Set("encodeState", Napi::Function::New(env, EncodeState));
+    exports.Set("restoreState", Napi::Function::New(env, RestoreState));
+    return exports;
+}
+
+NODE_API_MODULE(spaces, Init)