Window Platform Configuration

WindowManager splits per-window configuration into three orthogonal layers:

• windowOptions — Electron BrowserWindow constructor parameters (including platformOverrides for static per-OS differences).
• behavior — cross-platform declarative WM behavior that Electron's constructor cannot express (blur-auto-hide, setAlwaysOnTop level, setVisibleOnAllWorkspaces options, Dock visibility). See README → Configuration Layers.
• quirks — OS-specific hacks / workarounds applied via method-slot monkey-patches around hide() / show() / close().

Naming rule: any field effective on only one platform carries a mac / win / linux prefix, irrespective of layer (e.g. behavior.macShowInDock, quirks.macRestoreFocusOnHide).

OS Quirks

Some OS-specific behaviors are tedious to hand-roll at every call site (e.g. the macOS focus dance around hide()). WindowManager ships these as declarative opt-in flags under WindowTypeMetadata.quirks. When set, the manager transparently monkey-patches the corresponding BrowserWindow instance methods so business code continues calling window.hide() / window.show() as usual.

Available Quirks

All quirks are macOS-only: on other platforms the methods are left untouched, and window.hide === originalHide (identity preserved).

Example

[WindowType.SelectionToolbar]: {
  type: WindowType.SelectionToolbar,
  lifecycle: 'singleton',
  showMode: 'manual',
  windowOptions: { /* ... */ },
  behavior: {
    hideOnBlur: true,
    alwaysOnTop: { level: 'screen-saver' },  // level lives here, not in quirks
    visibleOnAllWorkspaces: { enabled: true, visibleOnFullScreen: true },
    macShowInDock: false
  },
  quirks: {
    macRestoreFocusOnHide: true,
    macClearHoverOnHide: true,
    macReapplyAlwaysOnTop: true              // boolean switch; reads level from behavior above
  }
}

With that in place, this.toolbarWindow.hide() from the domain service will:

1. Snapshot every visible focusable window and call setFocusable(false) on them.
2. Invoke the native hide().
3. Send the synthetic mouseMove(-1, -1) to clear hover.
4. Schedule setFocusable(true) restoration for the snapshot after 50ms.

The domain service carries none of this code.

Implementation Notes

• w.hide.bind(w) captures the native method with this correctly bound, so Electron's C++ bindings continue to see the real BrowserWindow.
• EventEmitter behavior (.on('hide', ...), .once('close', ...)) is untouched — the quirks patch only the method slots, not the emitter wiring.
• Quirks run after onWindowCreated and after applyWindowBehavior fires. This ordering means the behavior layer's initial setter calls (e.g. first setAlwaysOnTop(true, level)) do not trigger the monkey-patched show/showInactive.
• Quirks are applied per-window at creation time; there is no runtime toggle.

Declarative Behavior Layer

behavior captures configuration that's non-hacky, cross-platform, and needed beyond the Electron constructor. WindowManager applies these on window creation via applyWindowBehavior (in src/main/core/window/behavior.ts).

Runtime Setters

Runtime setters for the behavior layer live on wm.behavior (a BehaviorController instance defined in src/main/core/window/behavior.ts). Grouping them under this sub-namespace mirrors the three-layer windowOptions / behavior / quirks split at the API surface.

setVisibleOnAllWorkspaces intentionally has no WM-level setter — consumers call it directly on the BrowserWindow when needed. See README → When to Provide a Runtime Setter.

Platform Overrides

Static BrowserWindowConstructorOptions that differ per OS go in windowOptions.platformOverrides. Only the branch matching the current runtime is deep-merged into the final config; unmatched branches are discarded, and the platformOverrides field itself is stripped before reaching new BrowserWindow(...).

windowOptions: {
  width: 350, height: 43,
  frame: false, transparent: true,
  platformOverrides: {
    mac: { type: 'panel', hiddenInMissionControl: true, acceptFirstMouse: true },
    win: { type: 'toolbar', focusable: false },
    linux: { type: 'toolbar' } // focusable is set at runtime by the domain service
  },
  webPreferences: { /* ... */ }
}

Precedence (later wins) when merging inside mergeWindowOptions:

1. baseOptions (registry windowOptions)
2. baseOptions.platformOverrides[currentPlatform]
3. Caller-provided overrides (via wm.open(type, { options }))
4. Caller-provided overrides.platformOverrides[currentPlatform]

webPreferences is deep-merged in the same order.

When to Use Which Layer

The layers are composable: Selection's toolbar uses all three (windowOptions.platformOverrides for static per-OS differences, behavior.hideOnBlur / behavior.alwaysOnTop / behavior.visibleOnAllWorkspaces / behavior.macShowInDock for declarative behavior, and quirks.* for the macOS hide/show hacks).

Electron Edge Cases

• setAlwaysOnTop(false, level) — Electron ignores level when enabled is false. The WM wm.behavior.setAlwaysOnTop(id, false) preserves the registry-declared level arg only for signature symmetry; the effect is identical.
• VisibleOnAllWorkspacesOptions — both visibleOnFullScreen and skipTransformProcessType are documented as @platform darwin in Electron. They are silently ignored on Windows / Linux.
• Linux Wayland "phantom popup" bug — setVisibleOnAllWorkspaces can put windows into a broken "floating popup" state on KDE Wayland. See MainWindowService.ts:573 for context. WM does not intervene; consumers using behavior.visibleOnAllWorkspaces on Linux should guard via runtime display-protocol checks if they see the regression.
• Parameters<> type derivation — AlwaysOnTopLevel is derived from Parameters<BrowserWindow['setAlwaysOnTop']>[1]. If Electron adds method overloads to setAlwaysOnTop, this derivation resolves against the last overload only and may silently narrow. Re-verify after Electron upgrades.