docs: document multiple windows

Merged
AV
1mo ago
+51-0

Summary

  • Add a Multiple Windows page to the docs site, under Core Features after Workspaces. The feature shipped in #5337 and is in the 2026-08-23 changelog, but the docs had no coverage.
  • The page covers how to open a window, what each window keeps for itself and what all windows share, one workspace open in two windows, and what comes back on relaunch.

Why / Context

The page is written from the desktop code, not the changelog copy: main/windows/main.ts, main/lib/menu.ts, the window registry and window state, CollectionsProvider, and useV2WorkspacePaneLayout, plus the follow-ups #6894 (in-app and Linux entry points) and #7057 (pane selection stays local to a window).

Where the code and the announcement differ, the page follows the code:

  • Restore is partial. Each window comes back with its position, size, zoom and organization, but not with its own page: every window reads the same saved router history (router-history in localStorage) at boot, so all restored windows open on the page visited last in any window. A window closed before quitting does not come back.
  • Tabs and panes are not per window. The #5337 commit message says they are. In v2 the layout belongs to the workspace and syncs between windows; only the active tab and focused pane are per window (#7057).

Testing

  • bun run typecheck in apps/docs: passes
  • bun run build in apps/docs: passes, and /multiple-windows is in the build output
  • Vale runs only on apps/marketing; the docs app has no prose lint
  • Not viewed in a running docs preview

Notes

  • No macOS shortcut on the page, on purpose. File → New Window shows ⌘⇧N on macOS, but Quick Create Workspace (#6727) binds the same key in the renderer and calls preventDefault, so the menu accelerator never fires and the key creates a workspace. Checked with a real keystroke in a minimal Electron 41.10.3 app; not reproduced in the Superset app itself. The page lists only the entry points that work today. A separate change will move New Window to another key and add the shortcut to this page and to Keyboard Shortcuts.
  • Notification clicks move every window. onNotificationClick focuses the last-used window, then the FOCUS_V2_NOTIFICATION_SOURCE event reaches every renderer and each one navigates to the workspace. The page states this as it is today; scoping the event to one window is a desktop follow-up.
  • Linux launcher action. The page says an AppImage shows New Window in the launcher only when it is integrated with the desktop, per the comment in electron-builder.ts. Not tested on a Linux machine.
  • No screenshot. One image of two windows side by side, each titled with a different organization, would help near the top of the page.

Summary by cubic

Adds a Multiple Windows docs page covering how to open new windows, what each window keeps for itself versus what all windows share, and restore-on-relaunch behavior. The page tracks the desktop code rather than the changelog copy: restore is partial (windows return with position and size but all open on the page visited last in any window), and tabs and panes are shared across windows; only the active tab and focused pane are per-window.

Notes

  • The macOS shortcut (⌘⇧N) is intentionally omitted because Quick Create Workspace intercepts the key, so it never fires.
  • The Linux launcher entry point is described as only available for integrated AppImage installs and the deb.
  • Clicking a notification focuses the last-used window and navigates every open window.
  • On Linux, closing the last window quits Superset, and that window is saved and restored.
  • No screenshot; one showing two windows side by side would help near the top.

Summary by CodeRabbit

  • Documentation
    • Added guidance for opening, switching between, and closing multiple windows, including how window state is shared or kept independent.
    • Explained how windows behave when displaying the same workspace, how notifications work across windows, and how window state is restored after relaunch.
    • Clarified that restored windows share the last-visited page and that closing the final window quits the app on Linux but leaves it running on macOS.