# NebulaOS

A Linux desktop environment built around a custom compositor, shell, and service stack.

## Structure

| Path | Purpose |
|------|---------|
| `core/nebula-core` | Core runtime and platform APIs (growing) |
| `core/applications` | Installed `.desktop` discovery and launching |
| `core/windows` | Window and workspace management (`WindowService`) |
| `compositor/` | Compositor configuration (Sway is temporary) |
| `shells/` | Desktop and future Bigscreen shells |
| `packages/` | Shared UI (`Nebula.UI`), icons, API, and design tokens |
| `services/` | System services (audio, network, bluetooth, power, accounts) |
| `session/` | Session manager and desktop entry |
| `packaging/` | Distribution packaging (Ubuntu) |
| `branding/` | Boot assets, wallpapers, and sounds |
| `scripts/` | Development helpers (including the VMware shell wrapper) |

## Shells

**Nebula Desktop 0.2** is a C++20 Qt Quick/QML Wayland shell using LayerShellQt. It is floating-first: ordinary applications open as independently movable windows. See `shells/desktop/`.

**Nebula Bigscreen** is planned as a separate Qt Quick/QML shell with a controller-first interaction model, sharing `Nebula.UI`, `Nebula.Applications`, and `Nebula.Windows`.

Standalone Nebula applications may still use React/Tauri where that is a better fit. The operating-system shell does not.

An archived React desktop prototype lives in `shells/desktop/prototype-react/` as a design reference only.

## Current stack

```text
Ubuntu
 ↓
Wayland
 ↓
Sway                 temporary compositor / window manager
 ↓
Nebula Shell         Qt Quick/QML via LayerShellQt
```

Window management is abstracted:

```text
Nebula QML
    ↓
WindowService
    ↓
Sway IPC backend     now
Nebula compositor    later
    ↓
Sway
 /    \
Wayland app   XWayland app
```

Applications and games render on their own Wayland/XWayland paths. They are not composited inside QML.

Sway currently provides temporary window decorations (title bar and border) so windows can be identified, dragged, and resized. Custom Nebula window chrome is later work.

## Getting started (development VM)

```bash
cd shells/desktop/shell
rm -rf build
cmake -S . -B build
cmake --build build -j$(nproc)
```

Then, from the repository root:

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

or:

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

The VMware wrapper sets `QT_QUICK_BACKEND=software`. Production `nebula-shell` does not. Details: `shells/desktop/README.md` and `compositor/README.md`.

The Qt shell must be compiled on Linux (the Ubuntu NebulaOS VM). It will not build on Windows.