andrew
befed8ff96
Introduce a new production desktop shell at `shells/desktop/shell` built with C++20, Qt Quick/QML, and LayerShellQt, including top bar, launcher, desktop surfaces, shell state, and mock app data. Add the shared `packages/nebula-ui` QML module (theme, controls, focus, icons) and wire it into the shell build. Retire the old GTK/WebKit native host by removing `shells/desktop/native`, move the React shell UI to `shells/desktop/prototype-react` as an archived design reference, and update root/compositor/session documentation to reflect the new Linux-only production architecture and temporary Sway role.
179 lines
3.7 KiB
Markdown
179 lines
3.7 KiB
Markdown
# Nebula Desktop
|
|
|
|
Production shell for the mouse-and-keyboard NebulaOS desktop.
|
|
|
|
## Architecture
|
|
|
|
Nebula Desktop is a **Qt Quick / QML** Wayland shell. It draws system chrome only. It does not host application or game windows.
|
|
|
|
```text
|
|
Ubuntu
|
|
↓
|
|
Wayland
|
|
↓
|
|
Sway
|
|
temporary compositor
|
|
↓
|
|
Nebula Shell
|
|
C++20 + Qt 6 + Qt Quick/QML + LayerShellQt
|
|
```
|
|
|
|
Eventual target:
|
|
|
|
```text
|
|
Ubuntu/Linux
|
|
↓
|
|
Wayland
|
|
↓
|
|
Nebula compositor
|
|
↓
|
|
Nebula Shell
|
|
Qt Quick/QML
|
|
```
|
|
|
|
Normal applications remain ordinary Wayland / XWayland clients of the compositor:
|
|
|
|
```text
|
|
Normal Application
|
|
↓
|
|
Wayland / XWayland
|
|
↓
|
|
Compositor
|
|
↓
|
|
GPU
|
|
```
|
|
|
|
Nebula chrome:
|
|
|
|
```text
|
|
QML
|
|
↓
|
|
Qt Quick
|
|
↓
|
|
Wayland Layer Shell
|
|
↓
|
|
Compositor
|
|
```
|
|
|
|
Games, browsers, terminals, and other apps never pass through Qt Quick.
|
|
|
|
## Production stack
|
|
|
|
| Piece | Technology |
|
|
|-------|------------|
|
|
| Language | C++20 |
|
|
| UI | Qt 6, Qt Quick, QML |
|
|
| Layer surfaces | LayerShellQt |
|
|
| Build | CMake |
|
|
| Shared design system | `packages/nebula-ui` (`import Nebula.UI`) |
|
|
|
|
The executable is `nebula-shell`.
|
|
|
|
QML module URI: `Nebula.Shell`.
|
|
|
|
## Surfaces
|
|
|
|
Independent Wayland layer-shell windows:
|
|
|
|
| Surface | Layer | Role |
|
|
|---------|-------|------|
|
|
| Desktop | `BACKGROUND` | Wallpaper / desktop, no exclusive zone, no keyboard focus |
|
|
| Top Bar | `TOP` | 40px bar, exclusive zone, no keyboard focus by default |
|
|
| Launcher | `OVERLAY` | Hidden until the Nebula button opens it |
|
|
|
|
Stacking:
|
|
|
|
```text
|
|
OVERLAY
|
|
Nebula Launcher
|
|
|
|
TOP
|
|
Nebula Top Bar
|
|
|
|
NORMAL WAYLAND WINDOWS
|
|
Firefox, Steam, Blender, games, terminals, …
|
|
|
|
BACKGROUND
|
|
Nebula Desktop
|
|
```
|
|
|
|
## Layout
|
|
|
|
```text
|
|
shells/desktop/
|
|
├── README.md this file
|
|
├── shell/ production Qt/QML shell
|
|
│ ├── CMakeLists.txt
|
|
│ ├── src/main.cpp
|
|
│ └── qml/
|
|
└── prototype-react/ archived design reference only
|
|
```
|
|
|
|
Shared visual language lives in `packages/nebula-ui`, not in Desktop-specific chrome.
|
|
|
|
## Linux build
|
|
|
|
This project will not compile on Windows. LayerShellQt is a Wayland API and is not stubbed.
|
|
|
|
On the Ubuntu NebulaOS VM:
|
|
|
|
```bash
|
|
sudo apt install \
|
|
qt6-base-dev \
|
|
qt6-declarative-dev \
|
|
qt6-wayland \
|
|
liblayershellqtinterface-dev \
|
|
qml6-module-org-kde-layershell \
|
|
qml6-module-qtquick \
|
|
qml6-module-qtquick-window \
|
|
cmake \
|
|
build-essential
|
|
```
|
|
|
|
Qt 6.4 or newer is required. `loadFromModule` is used on Qt 6.5+.
|
|
|
|
```bash
|
|
cd shells/desktop/shell
|
|
|
|
cmake -S . -B build
|
|
cmake --build build -j$(nproc)
|
|
./build/nebula-shell
|
|
```
|
|
|
|
Run inside a Wayland compositor such as Sway (`compositor/sway/nebula-sway.conf`). Sway must not show its own bar.
|
|
|
|
There is no npm server, Vite server, `NEBULA_SHELL_DEV_URL`, WebKitGTK, GTK4, or React involved in running the production shell.
|
|
|
|
### QML lint
|
|
|
|
If the installed Qt provides `qmllint`:
|
|
|
|
```bash
|
|
qmllint \
|
|
shells/desktop/shell/qml/*.qml \
|
|
shells/desktop/shell/qml/surfaces/*.qml \
|
|
shells/desktop/shell/qml/components/*.qml \
|
|
shells/desktop/shell/qml/mock/*.qml \
|
|
packages/nebula-ui/qml/Nebula/UI/*.qml
|
|
```
|
|
|
|
Do not use ESLint or Oxlint on the production Qt shell.
|
|
|
|
## Design reference
|
|
|
|
`prototype-react/` is an archived React/Vite UI. It is **not** the production shell. Keep it until the Qt shell reaches visual and behavioural parity, then remove it in a later cleanup.
|
|
|
|
## Out of scope
|
|
|
|
Not implemented in this milestone:
|
|
|
|
- PipeWire, NetworkManager, BlueZ, UPower
|
|
- D-Bus services
|
|
- real `.desktop` discovery or app launching
|
|
- Sway IPC, workspaces, notifications
|
|
- authentication, greetd, Gamescope
|
|
- a custom Nebula compositor
|
|
- Nebula Bigscreen
|
|
|
|
Those come later. Bigscreen is expected to reuse `Nebula.UI` and shared C++ services with a different interaction model.
|