Start small. Explore safely.

Build the preview, open it inside your existing desktop, and verify real windows, graphics and clean shutdown before trying a standalone session.

Build on Arch Linux

sudo pacman -S --needed base-devel cmake ninja \
  qt6-base qt6-declarative qt6-wayland qt6-translations \
  quickshell konsole fish mesa

git clone https://github.com/LuYishan-4/LunaDash.git
cd LunaDash
./scripts/install-session.sh

Use a fresh build directory for a different CMake generator or compiler. Complete source changes before building. OpenGL 3.3 compatibility or OpenGL ES 3.0 is required; remove stale MESA_GL_VERSION_OVERRIDE and MESA_GLSL_VERSION_OVERRIDE values when diagnosing startup.

Your first session

1. Choose English or Traditional Chinese.
2. Review your connection. Existing network profiles are reused, and offline continuation is supported.
3. Choose a color, wallpaper, spacing and panel height.
4. Finish the guide, then use the panel gear for the complete settings center.

Super+Return opens the default terminal; Super+E opens the default file manager. Native X11 apps can be launched in the optional authenticated XWayland container. They share one compatibility window; save work before closing that container.

Run the checks

sudo pacman -S --needed xorg-server-xvfb xorg-xauth xdotool python-pillow xorg-xwayland
LUDASH_GRAPHICS=opengl ./scripts/test-wayland.sh
LUDASH_GRAPHICS=gles ./scripts/test-wayland.sh
xvfb-run -a -s "-screen 0 1440x900x24" \
  python3 tests/wayland/test_customization.py build

The tests use isolated runtime/configuration directories. Success requires rendered client content and clean child-process shutdown—not just correct window geometry. Check the process exit code and logs. The customization test also loads a deliberately invalid QML template, verifies fallback, recolors Files, and executes a command in interactive Fish.

Understand the preview

Arch is the first target. Ubuntu and Fedora builds are configured in GitHub Actions; that configuration does not prove a remote job has run. Software-rendered Xvfb sessions do not verify all GPUs or standalone login sessions. Multiple outputs, screen locking, complete portals, input-method-v2 and a full system tray are still incomplete.

Recent Foot needs Wayland core protocol versions not yet exposed by this Qt compositor. The default terminal therefore uses Konsole with Fish. Native plugins and custom QML are disabled until explicitly trusted.

See the repository's testing guide and complete file map for sanitizer commands, platform dependencies, evidence files, packaging checks and the dated verification record.