Nebula-OS/compositor

Compositor

Sway is the temporary Wayland compositor while Nebula Desktop is developed. Configuration lives in sway/nebula-sway.conf.

Sway currently provides:

• Wayland compositor
• floating-first application window management
• temporary title bars and borders on normal application windows
• XWayland
• input and the pointer cursor
• output handling

Nebula provides the visible shell (Qt Quick/QML via LayerShellQt) and logical window management through WindowService (core/windows). The Sway config must not enable a Sway bar.

A custom Nebula compositor is a later milestone. Do not treat this Sway setup as the final architecture. QML must not call swaymsg; the Sway IPC backend is the only Sway-specific code, and it is isolated so it can be replaced.

Ubuntu/Linux
 ↓
Wayland
 ↓
Sway                 now
Nebula compositor    later
 ↓
Nebula Shell
Qt Quick/QML

Floating-first session

Ordinary application windows open as floating windows, sized to about 70% of the current workspace (the usable output area below the 40px Nebula top bar) and centred. Sway workspace geometry already excludes the top-bar exclusive zone, so placement stays on-screen at any resolution.

Rules match only normal application views:

• Wayland: shell="xdg_shell" (app_id)
• XWayland: shell="xwayland" (class)

Layer-shell surfaces (Nebula desktop, top bar, launcher, overlays) are a different shell and are not matched. They stay on BACKGROUND / TOP / OVERLAY.

Sway draws a restrained title bar and border on those application windows so they can be identified, dragged, and resized with the mouse. This is temporary. Custom Nebula decorations, CSD, and wrapping Wayland clients inside QML are out of scope.

Development session

From the NebulaOS repository root:

sway -c compositor/sway/nebula-sway.conf

Recommended on the Ubuntu VMware VM (repo-root cd, cursor environment, software cursors):

sh compositor/sway/dev/run-sway-vm.sh

Sway then autostarts Nebula Desktop through scripts/run-nebula-vm.sh.

Skip shell autostart:

NEBULA_SHELL_AUTOSTART=0 sh compositor/sway/dev/run-sway-vm.sh

Output / resolution

The development config uses scale 1 and does not pin a resolution. Sway uses the output's preferred mode, which follows the current display size (including VMware Autofit Guest). Window sizes use workspace-relative percentages, not hard-coded pixel dimensions.

swaymsg -t get_outputs
swaymsg output <name> scale 1

Cursor

seat * xcursor_theme Adwaita 24
XCURSOR_THEME=Adwaita
XCURSOR_SIZE=24

Requires adwaita-icon-theme. A Nebula-branded cursor theme is a later task.

WLR_NO_HARDWARE_CURSORS=1 is VMware-specific and is set by run-sway-vm.sh, not by production session files.

Emergency / development shortcuts

Normal launching, focusing, and closing is done from the Nebula GUI. These remain compositor fallbacks:

Shortcut	Action
Super+Enter	open Foot
Super+Left Mouse	move the floating window under the pointer
Super+Right Mouse	resize the floating window under the pointer
Super+Left	snap to left half of the usable area
Super+Right	snap to right half of the usable area
Super+Up	maximise to the usable area (below the top bar)
Super+Down	restore to the default ~70% centred size
Super+Shift+Q	close the focused window
Super+Shift+E	exit Sway
Super+Shift+C	reload Sway config

Title-bar drag and border resize should be the normal mouse path. Super+mouse is an emergency convenience.

Rendering

scripts/run-nebula-vm.sh sets QT_QUICK_BACKEND=software for the VMware guest GPU. Production nebula-shell must not set that variable.