Repository: electron
Issue: [Feature Request]: Enable Application Window Restoration
Labels: enhancement :sparkles:

### Preflight Checklist

- [X] I have read the [Contributing Guidelines](https://github.com/electron/electron/blob/main/CONTRIBUTING.md) for this project.
- [X] I agree to follow the [Code of Conduct](https://github.com/electron/electron/blob/main/CODE_OF_CONDUCT.md) that this project adheres to.
- [X] I have searched the [issue tracker](https://www.github.com/electron/electron/issues) for a feature request that matches the one I want to file, without success.

### Problem Description

Electron based applications fail to restore their windows to their user-assigned [Virtual Desktop](https://support.microsoft.com/en-us/windows/multiple-desktops-in-windows-36f52e38-5b4a-557b-2ff9-e1a60c976434) [Windows 10/11] or [Space](https://support.apple.com/guide/mac-help/work-in-multiple-spaces-mh14112/mac) [macOS].

Unfortunately, this **isn't** something that Electron users can address in their application implementations. This is due to the fact that OS APIs do not [universally] exist to enable such **direct** management:

- Microsoft provides the [`VirtualDesktopManager`](https://learn.microsoft.com/en-us/windows/win32/shell/virtualdesktopmanager) which supports a very limited set of APIs (so limited, in fact, that there does not appear to be a way to enumerate the user's current set of available Desktops).
- Apple [explains their own process](https://developer.apple.com/library/archive/documentation/General/Conceptual/MOSXAppProgrammingGuide/CoreAppDesign/CoreAppDesign.html#//apple_ref/doc/uid/TP40010543-CH3-SW26) in their Mac App Programming Guide which amounts to "conform to some protocols and `NSWindow` state will be saved on application shutdown/restored on application startup".

(I haven't looked into Linux window manager APIs...)

Regardless, Microsoft and Apple provide enough APIs for applications to save and restore their "Virtual Desktop"/"Space" assignment on application restart. While Microsoft's APIs appear to be usable at any point in the application's life cycle, Apple's APIs are very much tied to the implementation of the `NSWindow`.

Electron's upstream Chromium does properly support session restoration with Virtual Desktop / Space assignments for its windows. The bugs that tracked these features are as follows:

- Windows: https://bugs.chromium.org/p/chromium/issues/detail?id=873414
- macOS: https://bugs.chromium.org/p/chromium/issues/detail?id=74812

The implementations of these features can be seen in the following change lists:

- Windows: https://chromium-review.googlesource.com/c/chromium/src/+/1570246
- macOS: https://chromium-review.googlesource.com/c/chromium/src/+/1808708

These are clearly implemented in drastically different ways. The macOS implementation is most directly (and clearly) tied to Chromium's concept of "session restoration".

Current versions of Electron do not provide any ability to tap into Chromium's window restoration capabilities (or provide their own mechanism). Applications currently have to rely on APIs provided by the [`BrowserWindow`](https://www.electronjs.org/docs/latest/api/browser-window) class and that class does not (and _cannot_) provide the APIs necessary to support this feature.

### Proposed Solution

I would like Electron to provide an option wherein an Electron application developer can specify that they would like the windows of an application to be restored on next start. This option should handle window Virtual Desktop/Space reassignment. I expect that APIs may be necessary to enable applications to "rehydrate" the restored windows with serialized application state.

Unfortunately, my personal experience with Electron application session restoration is insufficient to propose anything more than the high level ask above. Perhaps @bpasero might chime in - he seems like someone who may be sufficiently steeped in the complexities of [window/state restoration](https://github.com/microsoft/vscode/blame/11fcbd051ad22bde4f7b22ebee8e0158d77cb7c9/src/vs/platform/windows/electron-main/windowsStateHandler.ts#L426) to be able to suggest a solution or improved list of requirements for a solution.

### Alternatives Considered

The alternatives considered are as follows:

1. **Use [`BrowserWindow`](https://www.electronjs.org/docs/latest/api/browser-window) APIs.** The APIs do not provide any way to control Virtual Desktop/Space assignment.
2. **Wait for a separate set of "[Workspace APIs](https://github.com/electron/electron/issues/5362)".** These APIs are not yet implemented. Moreover, the proposed set of APIs aren't currently feasible given the available set of APIs provided by the host OSes themselves (importantly, _none_ of them are available on macOS).

These approaches are both at the level of "we can pass this off to Electron application developers". Unfortunately, due to the nature of how Virtual Desktop/Space systems work this needs to be something that is handled internally.

### Additional Information

I should also explain that there are several scenarios that _end users_ expect this feature:

1. "I restarted my computer and my previously open applications automatically restore to the setup I had before rebooting."
2. "I restarted my application to install an update."
3. "I exited my application, went to lunch, came back, and re-opened my application."

Notably, Apple only explains that they support restoration when the computer restarts and applications are reopened. The other two scenarios aren't _officially_ handled. That said, the Chromium developers were able to identify an approach that enables Chromium itself to restart (e.g. during an update) and restore windows to their previously assigned Spaces. This feature _mostly_ works when quitting/starting Chrome normally (case 3 above), though this may require [setting a custom preference](https://apple.stackexchange.com/a/269664).

It appears that the Windows APIs also operate on a "best effort" basis wherein if the ID of the Virtual Desktop targeted for restoration doesn't exist anymore, the window is moved instead to the active Virtual Desktop.

---

**Related issues:**

- **Electron**
  - https://github.com/electron/electron/issues/10124 - This was closed as being considered out of scope for the roadmap at the time. At the time the upstream Chromium project had also not yet implemented the feature.
  - https://github.com/electron/electron/issues/15211 - This was closed with the suggestion that app developers should handle it. That is unfortunately not possible.
  - https://github.com/electron/electron/issues/5362 - This issue targets providing an API within Electron itself to manage Virtual Desktop/Space assignments. Of the four bullet points in this issue, only three are potentially doable in Windows and none are doable on macOS.
- **VS Code**
  - https://github.com/microsoft/vscode/issues/979 - This was closed because the upstream issue ([#10124](https://github.com/electron/electron/issues/10124)) was closed.
  - https://github.com/microsoft/vscode/issues/88257 - Automatically closed due to lacking enough votes.
  - https://github.com/microsoft/vscode/issues/116358 - Automatically closed due to lacking enough votes.
  - https://github.com/microsoft/vscode/issues/123517
  - https://github.com/microsoft/vscode/issues/138936 - Automatically closed due to lacking enough votes.
  - https://github.com/microsoft/vscode/issues/146915
  - https://github.com/microsoft/vscode/issues/152869