Introducing a new way to review your PRs.

Read the announcement

opencut-app / opencut

The open-source CapCut alternative

View on GitHub

12 documents · Updated Nov 16, 2026

docs / desktop-shell


covers:

  • apps/desktop/src/main.rs
  • apps/desktop/src/shell.rs
  • apps/desktop/src/theme.rs
  • apps/desktop/Cargo.toml
  • apps/desktop/moon.yml
  • apps/desktop/README.md

Desktop Shell

Overview

The desktop application is the Rust GPUI entrypoint for OpenCut. apps/…/Cargo.toml defines the opencut-desktop package and binary, with src/main.rs as the executable entrypoint and gpui as its only direct dependency.

apps/…/main.rs performs a Linux-only WSLg guard before starting GPUI: when /proc/sys/kernel/osrelease indicates WSL and both DISPLAY and WAYLAND_DISPLAY are set, it removes WAYLAND_DISPLAY so GPUI uses XWayland instead of WSLg Wayland. The code comment ties this to GPUI 0.2.2 requiring xdg_wm_base v2+, while current WSLg advertises v1. After that guard, Application::new().run opens the main window centered at 960x600 but requested as maximized, with the native titlebar title set to OpenCut. Window construction creates a Shell entity and attaches an observe_window_appearance callback that refreshes the window whenever the system appearance changes, allowing the theme colors to update.

apps/…/shell.rs owns the top-level desktop layout. Shell::new creates one GPUI entity each for Browser, Preview, Inspector, and Timeline, instead of allocating them during render, so panel state survives re-renders. Render for Shell reads window.theme().colors, paints the root background and foreground, then lays out a vertical flex container: the upper two-thirds is a bordered horizontal row containing browser, preview, and inspector panels; the lower section contains the timeline panel.

apps/…/theme.rs provides the semantic color system consumed by the shell and panels. Theme::for_appearance maps GPUI WindowAppearance::Light/VibrantLight to a cached light theme and Dark/VibrantDark to a cached dark theme through OnceLock, so theme values are constructed once per process. The ActiveTheme trait is implemented for gpui::Window, letting render code call window.theme() and receive the theme matching the current system appearance. Theme tokens are authored as OKLCH values and converted to GPUI Hsla through oklch_with_alpha, which converts OKLCH to linear sRGB, gamma-corrects to sRGB, clamps the channels and alpha, and stores the result as Hsla. Unit tests in apps/…/theme.rs cover neutral endpoint conversion, translucent dark tokens, and appearance-to-theme selection.

Desktop developer workflow is registered in apps/…/moon.yml: desktop:dev runs cargo run and is disabled in CI, desktop:check runs cargo check, and desktop:build runs cargo build --release with /target/release/opencut-desktop as its output. Both check and build declare src/**/*, the package Cargo.toml, the root Cargo.toml, and the root Cargo.lock as inputs. apps/…/README.md documents the same Moon tasks and the platform prerequisites for GPUI: Metal/Xcode tools on macOS, Win32/DirectWrite on Windows, and Vulkan plus Wayland/X11/fontconfig/toolchain packages on Linux, with WSL2/WSLg expected to use XWayland automatically.

Coupling

  • If apps/…/main.rs is renamed or the binary entrypoint moves, update apps/…/Cargo.toml [[bin]].path; Cargo will otherwise build a package whose configured binary path no longer exists.
  • If files outside apps/desktop/src/**/*, apps/…/Cargo.toml, the root Cargo.toml, or the root Cargo.lock become required to compile or package the desktop app, add them to apps/…/moon.yml inputs so Moon invalidates desktop:check and desktop:build correctly.
  • If GPUI's WSLg Wayland behavior changes, check both apps/…/main.rs and apps/…/README.md; the runtime workaround and the documented WSL2 expectation must continue to describe the same display-server behavior.
  • If new shell or panel styles need semantic colors, add tokens in apps/…/theme.rs rather than hard-coding colors in render code; apps/…/shell.rs already depends on window.theme().colors so appearance changes refresh consistently.

Risks

  • In apps/…/main.rs, the WSLg workaround uses unsafe std::env::remove_var and the comment requires it to remain the first statement in main, before GPUI or any other code can spawn threads. If code that may start threads is inserted above it, mutating the process environment can become unsound and WSLg users may hit the GPUI Wayland panic the workaround is meant to avoid.
  • In apps/…/theme.rs, oklch_with_alpha is a hand-written color conversion rather than a library call. If the conversion constants or gamma threshold are changed incorrectly, every semantic token returned through window.theme() can shift, affecting the entire shell and panel color scheme.