andrew
dd9b43bd27
Initialize the NebulaOS monorepo layout with top-level documentation, ignore rules, placeholder service/package directories, compositor docs plus a baseline Sway config, and session startup/desktop entry files. Add the first desktop shell prototype under `shells/desktop/ui` using React + Vite, including themed surface components (desktop, top bar, launcher, preview), mock Nebula APIs and shell bridge state wiring, reusable UI controls/icons, and supporting styles/config needed for local development.
Nebula Desktop native host
This directory will contain the Linux native shell host for Nebula Desktop.
The host is a C++ process that creates several GTK4 windows, each backed by WebKitGTK 6.0 and placed with gtk4-layer-shell. It does not composite application windows. Those remain ordinary Wayland / XWayland clients of the compositor.
Planned stack:
- C++
- GTK4
- gtk4-layer-shell
- WebKitGTK 6.0
- Wayland
Surfaces
The React UI in shells/desktop/ui can render each shell layer independently via a query parameter. The native host will create one WebKitGTK view per surface and append that parameter to the load URL.
| Surface | Query | Layer Shell layer | Placement |
|---|---|---|---|
| Desktop | ?surface=desktop |
BACKGROUND |
Anchored to all monitor edges |
| Top Bar | ?surface=topbar |
TOP |
Anchored top/left/right, fixed shell-defined height, exclusive zone enabled |
| Launcher | ?surface=launcher |
OVERLAY |
Hidden/unmapped when closed |
The host must not hardcode a Vite port. It loads a base URL and appends the surface parameter.
Stacking
OVERLAY
Nebula Launcher
notifications
OSDs
TOP
Nebula Top Bar ← exclusive zone; apps do not go under it
NORMAL APPLICATION WINDOWS
Firefox, Steam, Blender, games, terminals, …
BACKGROUND
Nebula Desktop
wallpaper
React draws shell chrome only. Applications and games render through the compositor, not through WebKit.
Application / game
→ Wayland / XWayland
→ compositor
→ GPU
Loading modes
Development
The host will load a configurable Vite origin, conceptually:
NEBULA_SHELL_DEV_URL=http://127.0.0.1:5174
and request:
{NEBULA_SHELL_DEV_URL}/?surface=desktop
{NEBULA_SHELL_DEV_URL}/?surface=topbar
{NEBULA_SHELL_DEV_URL}/?surface=launcher
The port is environment configuration, not architecture. A combined browser preview (/?surface=preview, also the default) is for Windows UI work only; the native host should load the three surfaces separately.
Production
The host will load the compiled assets from npm run build in shells/desktop/ui/dist, still using the same ?surface= parameters. It will not depend on a Vite server.
Shell bridge
Each WebKit view talks to the host through a JavaScript bridge (shellBridge in the React UI). The development build uses an in-page mock. The native host will inject the real implementation so the top bar can toggle the launcher, and so launching an app can unmap the overlay and update the top-bar context.
nebula.* remains the API boundary for system services (apps, audio, network, power). Those stay mocked until Linux services land.
Current development compositor
Sway is the temporary compositor. See compositor/sway/nebula-sway.conf.
Build notes
This host is Linux-only. Do not expect it to compile on Windows. Implementation is the next Linux-side task.