# 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 |
| `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.1** is a C++20 Qt Quick/QML Wayland shell using LayerShellQt. It can discover installed applications and launch them (including Foot) from the GUI. See `shells/desktop/`.

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

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
 ↓
Nebula Shell  Qt Quick/QML
```

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

## 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
./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.