Files

T

andrew dd9b43bd27 Bootstrap NebulaOS repo and desktop shell UI

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.

2026-08-26 15:31:54 +12:00

3.0 KiB

Raw Permalink Blame History

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.

3.0 KiB Raw Permalink Blame History