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.
92 lines
3.0 KiB
Markdown
92 lines
3.0 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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.
|
|
|
|
```text
|
|
Application / game
|
|
→ Wayland / XWayland
|
|
→ compositor
|
|
→ GPU
|
|
```
|
|
|
|
## Loading modes
|
|
|
|
### Development
|
|
|
|
The host will load a configurable Vite origin, conceptually:
|
|
|
|
```text
|
|
NEBULA_SHELL_DEV_URL=http://127.0.0.1:5174
|
|
```
|
|
|
|
and request:
|
|
|
|
```text
|
|
{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.
|