Move to CEF Browser Engine

.github/workflows/archlinux.yml

@@ -38,7 +38,8 @@ jobs:
             tar \
             python \
             nodejs \
-            webkitgtk-6.0 \
+            glib2 \
+            sqlite \
             curl \
             crypto++ \
             libssh \
@@ -53,7 +54,26 @@ jobs:
             zstd \
             xz \
             docker \
-            docker-buildx
+            docker-buildx \
+            alsa-lib \
+            at-spi2-core \
+            cairo \
+            dbus \
+            expat \
+            libcups \
+            libx11 \
+            libxcb \
+            libxcomposite \
+            libxdamage \
+            libxext \
+            libxfixes \
+            libxkbcommon \
+            libxrandr \
+            mesa \
+            nspr \
+            nss \
+            pango \
+            systemd-libs
 
       - uses: actions/checkout@v6
         with:
@@ -116,6 +136,11 @@ jobs:
         run: |
           cd "${{ env.BUILD_DIR }}" && tar -czf "nui-sftp-linux-frontend_${{ env.VERSION }}.tar.gz" frontend
 
+      # The CEF archive this build used, nui-sftp-deploy's prepare_release puts it into the PKGBUILD and the flatpak.
+      - name: Name CEF distribution
+        run: |
+          cp "${{ env.BUILD_DIR }}/text/cef_distribution.json" "${{ env.BUILD_DIR }}/nui-sftp-cef-distribution_${{ env.VERSION }}.json"
+
       - name: Build standalone licenses tarball
         run: |
           # The cmake build already produced licenses.json (and embedded it
@@ -133,6 +158,7 @@ jobs:
         run: |
           gh release upload "v${{ env.VERSION_CLEAN }}" "${{ env.BUILD_DIR }}/nui-sftp-linux-frontend_${{ env.VERSION }}.tar.gz"
           gh release upload "v${{ env.VERSION_CLEAN }}" "${{ env.BUILD_DIR }}/nui-sftp-licenses_${{ env.VERSION }}.tar.gz"
+          gh release upload "v${{ env.VERSION_CLEAN }}" "${{ env.BUILD_DIR }}/nui-sftp-cef-distribution_${{ env.VERSION }}.json"
 
       - name: Upload artifacts to MEGA S4
         if: startsWith(github.ref, 'refs/tags/v')
@@ -153,3 +179,4 @@ jobs:
 
           upload_if_absent "nui-sftp-linux-frontend_${{ env.VERSION }}.tar.gz" "s3://nui-sftp-releases/linux-frontend/"
           upload_if_absent "nui-sftp-licenses_${{ env.VERSION }}.tar.gz" "s3://nui-sftp-releases/licenses/"
+          upload_if_absent "nui-sftp-cef-distribution_${{ env.VERSION }}.json" "s3://nui-sftp-releases/cef-distribution/"

CMakeLists.txt

@@ -21,14 +21,25 @@ option(BUILD_STATIC_LIBS "Build static libraries" ON)
 option(NUI_SFTP_ENABLE_TESTING "Enable testing for nui-sftp" OFF)
 option(OFFLINE_BUILD "Inform CMake that we are building for offline environments (flatpak, yocto), this will set some additional flags and dependencies" OFF)
 option(OMIT_FRONTEND_BUILD "Dont build the frontend, used primarily for flatpak, because using emscripten there is hell" OFF)
+option(NUI_SFTP_FLATPAK "Install for Flatpak (CEF): the executable next to CEF in lib/nui-sftp, bin/nui-sftp starts it through zypak" OFF)
 option(FETCH_RAPIDFUZZ "Fetch rapidfuzz" ON)
 option(FETCH_SPDLOG "Fetch spdlog" ON)
 option(FETCH_EFSW "Fetch efsw" ON)
 option(NUI_SFT_ENABLE_LANGUAGE_TOOLING "Enable building language tooling, which includes a command line tool for checking language files" OFF)
 option(TAR_ARCHIVE_HAS_XZ "Enable xz (liblzma) compression in the tar-archive library" ON)
 
-# Webkit from custom build
+# Chromium (CEF) on Linux and macOS, WebView2 on Windows. native selects WebKitGTK or WKWebView instead.
 if (NOT EMSCRIPTEN)
+    if (WIN32)
+        set(NUI_SFTP_DEFAULT_BROWSER_ENGINE native)
+    else()
+        set(NUI_SFTP_DEFAULT_BROWSER_ENGINE cef)
+    endif()
+    set(NUI_BROWSER_ENGINE "${NUI_SFTP_DEFAULT_BROWSER_ENGINE}" CACHE STRING "Browser engine: cef or native")
+endif()
+
+# Webkit from custom build
+if (NOT EMSCRIPTEN AND NOT NUI_BROWSER_ENGINE STREQUAL "cef")
     if (WEBKIT_PATH)
         message(STATUS "Using custom WebKit build from ${WEBKIT_PATH}")
         set(ENV{PKG_CONFIG_PATH} "${WEBKIT_PATH}/lib/pkgconfig")
@@ -49,7 +60,7 @@ endif()
 
 # Nui and webview both look up WebKitGTK, with different preferences they linked GTK 3 and GTK 4 at once.
 # One API for both: webkitgtk-6.0 (GTK 4) where it is installed, otherwise webkit2gtk-4.1 (GTK 3).
-if (NOT EMSCRIPTEN AND UNIX AND NOT APPLE)
+if (NOT EMSCRIPTEN AND UNIX AND NOT APPLE AND NOT NUI_BROWSER_ENGINE STREQUAL "cef")
     find_package(PkgConfig REQUIRED)
     if (WEBKIT_PATH)
         pkg_search_module(webkit REQUIRED IMPORTED_TARGET ${WEBKIT_PACKAGE_NAME})
@@ -81,6 +92,15 @@ include (${CMAKE_CURRENT_LIST_DIR}/_cmake/common_options.cmake)
 # Nui Dependency
 add_subdirectory("${CMAKE_SOURCE_DIR}/dependencies/Nui" EXCLUDE_FROM_ALL)
 
+# The CEF distribution of this build. The release publishes it for the packages that fetch CEF themselves.
+if (NOT EMSCRIPTEN AND NUI_BROWSER_ENGINE STREQUAL "cef")
+    configure_file(
+        "${CMAKE_CURRENT_LIST_DIR}/_cmake/configured_files/cef_distribution.json.in"
+        "${CMAKE_BINARY_DIR}/text/cef_distribution.json"
+        @ONLY
+    )
+endif()
+
 # Add executable (sources are added later, depending on frontend/backend)
 add_executable(${PROJECT_NAME})
 target_link_libraries(${PROJECT_NAME} PUBLIC core-target)
@@ -106,7 +126,8 @@ if (WIN32)
     )
     add_dependencies(${PROJECT_NAME} nui-sftp-icon)
 elseif (APPLE AND NOT EMSCRIPTEN)
-    # scripts/deploy.sh assembles nui-sftp.app from these, the build tree keeps the plain bin/ layout.
+    # With CEF the build tree has nui-sftp.app (nui_configure_application), with WKWebView the plain bin/ layout, from
+    # which scripts/deploy_macos.sh assembles the bundle.
     # Uint8Array.fromBase64 in static/source/index.js needs the WebKit of macOS 15.2.
     if (NOT CMAKE_OSX_DEPLOYMENT_TARGET OR CMAKE_OSX_DEPLOYMENT_TARGET VERSION_LESS "15.2")
         message(FATAL_ERROR "nui-sftp needs CMAKE_OSX_DEPLOYMENT_TARGET 15.2 or later, use _cmake/macos/toolchain.cmake.")
@@ -119,6 +140,25 @@ elseif (APPLE AND NOT EMSCRIPTEN)
         @ONLY
     )
     add_dependencies(${PROJECT_NAME} nui-sftp-icon)
+    # The licenses of CEF and of the Chromium components in it go into the bundle, the Linux packages install them.
+    set(NUI_SFTP_CEF_LICENSES "")
+    if (NUI_BROWSER_ENGINE STREQUAL "cef")
+        get_filename_component(NUI_SFTP_CEF_ROOT "${NUI_CEF_LIBRARY_DIR}" DIRECTORY)
+        configure_file("${NUI_SFTP_CEF_ROOT}/LICENSE.txt" "${CMAKE_BINARY_DIR}/generated/cef/CEF-LICENSE.txt" COPYONLY)
+        configure_file("${NUI_SFTP_CEF_ROOT}/CREDITS.html" "${CMAKE_BINARY_DIR}/generated/cef/CEF-CREDITS.html" COPYONLY)
+        set(NUI_SFTP_CEF_LICENSES
+            "${CMAKE_BINARY_DIR}/generated/cef/CEF-LICENSE.txt"
+            "${CMAKE_BINARY_DIR}/generated/cef/CEF-CREDITS.html"
+        )
+    endif()
+    nui_configure_application(
+        TARGET ${PROJECT_NAME}
+        NAME nui-sftp
+        IDENTIFIER org.nuicpp.nui_sftp
+        INFO_PLIST "${CMAKE_BINARY_DIR}/generated/Info.plist"
+        ICON "${NUI_SFTP_ICNS}"
+        RESOURCES static/assets themes ${NUI_SFTP_CEF_LICENSES}
+    )
 endif()
 
 # Third-party license drift check: fails the build if a CMake-declared dep
@@ -186,14 +226,37 @@ else()
         )
     endif()
 
-    # Copy module bin to frontend.
+    # Copy module bin to frontend, next to bin/ or into the resources of the app bundle.
+    if (APPLE AND NUI_BROWSER_ENGINE STREQUAL "cef")
+        set(NUI_SFTP_FRONTEND_DIRECTORY "$<TARGET_BUNDLE_CONTENT_DIR:${PROJECT_NAME}>/Resources/frontend")
+    else()
+        set(NUI_SFTP_FRONTEND_DIRECTORY "$<TARGET_FILE_DIR:${PROJECT_NAME}>/../frontend")
+    endif()
     if (NOT OMIT_FRONTEND_BUILD)
         add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
-            COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_BINARY_DIR}/module_${PROJECT_NAME}/bin" "$<TARGET_FILE_DIR:${PROJECT_NAME}>/../frontend"
+            COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_BINARY_DIR}/module_${PROJECT_NAME}/bin" "${NUI_SFTP_FRONTEND_DIRECTORY}"
             VERBATIM
         )
     endif()
 
+    # On macOS with CEF nui-sftp.app carries everything. Elsewhere bin/nui-sftp with frontend, assets and themes next to
+    # bin/ and the CEF runtime in lib/nui-sftp. Windows packages and WKWebView bundles are assembled by
+    # scripts/deploy.sh.
+    if (APPLE AND NUI_BROWSER_ENGINE STREQUAL "cef")
+        nui_install(TARGETS ${PROJECT_NAME})
+    elseif (NOT WIN32)
+        set(NUI_SFTP_INSTALL_FLATPAK "")
+        if (NUI_SFTP_FLATPAK)
+            set(NUI_SFTP_INSTALL_FLATPAK FLATPAK_ZYPAK)
+        endif()
+        nui_install(TARGETS ${PROJECT_NAME} DESTINATION bin ENGINE_DESTINATION lib/${PROJECT_NAME} ${NUI_SFTP_INSTALL_FLATPAK})
+        install(DIRECTORY "${CMAKE_SOURCE_DIR}/static/assets/" DESTINATION assets)
+        install(DIRECTORY "${CMAKE_SOURCE_DIR}/themes/" DESTINATION themes)
+        if (NOT OMIT_FRONTEND_BUILD)
+            install(DIRECTORY "${CMAKE_BINARY_DIR}/module_${PROJECT_NAME}/bin/" DESTINATION frontend)
+        endif()
+    endif()
+
     if (NUI_SFTP_ENABLE_TESTING)
         include(./_cmake/dependencies/gtest.cmake)
         enable_testing()

CONTRIBUTING.md

@@ -9,11 +9,13 @@ how changes are validated in CI.
 nui-sftp is a cross-platform (Linux and Windows) SSH/SFTP workbench. The
 frontend is written in C++ and compiled to WebAssembly via Emscripten using
 [Nui](https://github.com/NuiCpp/Nui); the backend is a native C++ application
-that hosts a WebKit/WebView2 webview and talks to libssh. Frontend and backend
-communicate through Nui's RPC bridge.
+that hosts the page in Chromium (Nui's CEF engine) on Linux and macOS and in
+WebView2 on Windows, and talks to libssh. Frontend and backend communicate
+through Nui's RPC bridge.
 
 Submodules pin most C++ dependencies. System packages (libssh, boost, fmt,
-crypto++, webkitgtk on Linux) are pulled from the distro or MSYS2.
+crypto++) are pulled from the distro or MSYS2. CEF is downloaded by the
+configure step, see [Browser engine](#browser-engine).
 
 ## Reporting bugs and asking questions
 
@@ -47,10 +49,15 @@ minimum packages CI installs are:
 
 ```
 cmake ninja clang lld git python nodejs
-webkitgtk-6.0 curl crypto++ libssh fmt boost boost-libs
+curl crypto++ libssh fmt boost boost-libs glib2
 nlohmann-json zlib bzip2 zstd xz
 ```
 
+`webkitgtk-6.0` is only needed for `-DNUI_BROWSER_ENGINE=native`. The CEF
+library needs `nss`, `alsa-lib`, `at-spi2-core`, `libcups`, `mesa` and a few X11
+libraries, which desktop systems have; the full list for a bare container is
+in [.github/workflows/archlinux.yml](.github/workflows/archlinux.yml).
+
 Node.js 24 is required for the frontend build (Nui invokes `parcel` and
 `npm`).
 
@@ -120,7 +127,26 @@ cmake --build   build/clang_release --target nui-sftp
 ./scripts/deploy.sh
 ```
 
-The release configure omits tests and the XML tool by default.
+The release configure omits tests and the XML tool by default. On Linux and
+macOS `deploy.sh` runs `cmake --install`: `bin/nui-sftp` with `frontend/`,
+`assets/` and `themes/` next to `bin/` and the CEF runtime in `lib/nui-sftp/`
+(libcef is stripped while installing), on macOS `nui-sftp.app`.
+
+### Browser engine
+
+`NUI_BROWSER_ENGINE` is `cef` on Linux and macOS and `native` (WebView2) on
+Windows. `-DNUI_BROWSER_ENGINE=native` builds the Linux and macOS versions with
+WebKitGTK or WKWebView instead. The engine is described in
+[dependencies/Nui/docs/cef_engine.md](dependencies/Nui/docs/cef_engine.md).
+
+- CEF: the configure step downloads the pinned minimal distribution once into
+  `~/.cache/nui/cef` (SHA256 checked) and shares it between build trees.
+  Offline builds pass `-DNUI_FETCH_CEF=OFF` with `-DNUI_CEF_ARCHIVE=<file>` or
+  `-DNUI_CEF_SYSTEM=ON` (Arch: the `cef` package).
+- All Chromium child processes run `nui-cef-helper`, built next to libcef in
+  `build/<dir>/nui-cef/`. The main process never runs in a child, so option
+  parsing and the ForkPool stay as they are.
+- On macOS the build tree has `bin/nui-sftp.app`, run the executable inside it.
 
 ### Standalone marketing webpage
 
@@ -173,9 +199,11 @@ are sensible; override them only when needed.
 | `NUI_BUILD_XML_TOOL` | (via Nui) | Build the `xml-to-nui` SVG/XML converter |
 | `OMIT_FRONTEND_BUILD` | `OFF` | Skip the Emscripten frontend |
 | `OFFLINE_BUILD` | `OFF` | Adjust dependency fetching for sandboxed builds (Flatpak, Yocto) |
+| `NUI_SFTP_FLATPAK` | `OFF` | Install for Flatpak: the executable next to CEF in `lib/nui-sftp`, `bin/nui-sftp` starts it through zypak |
 | `BUILD_WEBPAGE` | `OFF` | Build the marketing webpage module |
 | `FETCH_YAML_CPP` / `FETCH_RAPIDFUZZ` / `FETCH_SPDLOG` / `FETCH_EFSW` | `ON` | Fetch vs. use system version |
-| `WEBKIT_PATH` | "" | Use a custom WebKit build instead of system pkg-config |
+| `NUI_BROWSER_ENGINE` | `cef` (`native` on Windows) | Chromium through CEF, or the platform webview |
+| `WEBKIT_PATH` | "" | Use a custom WebKit build instead of system pkg-config (native engine) |
 | `TAR_ARCHIVE_HAS_XZ` | `ON` | Enable liblzma compression in the tar-archive library |
 
 ## Debugging
@@ -186,20 +214,26 @@ The backend is a normal native binary; debug it directly with gdb or lldb:
 gdb --args build/clang_debug/bin/nui-sftp
 ```
 
-Two caveats worth knowing about:
+Worth knowing:
+
+- DevTools: debug builds (and release builds started with `--enable-dev-tools`)
+  serve the Chrome DevTools Protocol on the port in
+  `NUI_CEF_REMOTE_DEBUGGING_PORT`, open `http://127.0.0.1:<port>` or
+  `chrome://inspect`. Extra Chromium switches go into `NUI_CEF_ARGUMENTS`, for
+  example `--ozone-platform=headless` for runs without a display.
 
-- Tell the debugger to ignore `SIGUSR1` and `SIGXCPU`, otherwise the WebKit
-  and JS runtimes will repeatedly trip it. For gdb:
+- With the native engine, tell the debugger to ignore `SIGUSR1` and `SIGXCPU`,
+  otherwise the WebKit and JS runtimes will repeatedly trip it. For gdb:
 
   ```
   handle SIGUSR1 nostop noprint
   handle SIGXCPU nostop noprint pass
   ```
 
-- The WebKitGTK DMABUF renderer is disabled at startup unless every GPU uses
-  amdgpu, i915 or xe (see `Nui::configureWebKitGtkRendering`), the log states
-  why. Export `WEBKIT_DISABLE_DMABUF_RENDERER=0` to force it on or `=1` to
-  force it off.
+- With the native engine, the WebKitGTK DMABUF renderer is disabled at startup
+  unless every GPU uses amdgpu, i915 or xe (see
+  `Nui::configureWebKitGtkRendering`), the log states why. Export
+  `WEBKIT_DISABLE_DMABUF_RENDERER=0` to force it on or `=1` to force it off.
 
 Test binaries live under `build/clang_debug/test/` and can be launched the
 same way.

README.md

@@ -147,7 +147,7 @@ You can download and upload files and folders directly as tar archives, no manua
 - Box drag select for icon view.
 - Auto refresh after operation complete.
 - Resize left vs right.
-- Upload drag and drop (within view and into the app (Linux caveat: only a single file, bug in webkitgtk)).
+- Upload drag and drop (within view and into the app).
 - Download drag and drop (within view).
 - Searching files.
 - Sorting files.
@@ -161,4 +161,3 @@ You can download and upload files and folders directly as tar archives, no manua
 # Known Problems
 
 - Cannot use mouse side keys for history navigation (yet) because of a bug in WebKit that shows them as "button 0".
-- On WebKit Systems (Linux), the drag and drop from the desktop only supports single files and folders, not a list of items, because WebKit removed the functionality entirely because of an unfixed security issue.

_cmake/common_options.cmake

@@ -25,8 +25,8 @@ else()
 endif()
 target_compile_features(core-target INTERFACE cxx_std_23)
 
-# Set for the macOS backend and for the frontend built for its WKWebView, where __APPLE__ is not defined.
-if (APPLE OR (EMSCRIPTEN AND BROWSER_ENGINE STREQUAL "wkwebview"))
+# Set for the macOS backend and for the frontend built for it, where __APPLE__ is not defined.
+if (APPLE OR (EMSCRIPTEN AND NUI_SFTP_PLATFORM STREQUAL "macos"))
     target_compile_definitions(core-target INTERFACE NUI_SFTP_MACOS=1)
 endif()
 target_compile_definitions(core-target INTERFACE JSON_DIAGNOSTICS=1)

_cmake/configured_files/cef_distribution.json.in

@@ -0,0 +1,7 @@
+{
+    "version": "@NUI_CEF_SELECTED_VERSION@",
+    "platform": "@NUI_CEF_SELECTED_PLATFORM@",
+    "archive": "@NUI_CEF_SELECTED_ARCHIVE@",
+    "url": "@NUI_CEF_SELECTED_URL@",
+    "sha256": "@NUI_CEF_SELECTED_SHA256@"
+}

_cmake/offline_build.cmake

@@ -23,6 +23,7 @@ if(NOT EMSCRIPTEN)
     set(FETCH_EFSW OFF CACHE BOOL "Do not fetch efsw, assume it is in dependencies/efsw" FORCE)
 
     set(OMIT_FRONTEND_BUILD ON CACHE BOOL "Do not build the frontend, in offline environments emscripten is hard to use" FORCE)
+    set(NUI_FETCH_CEF OFF CACHE BOOL "Do not download CEF, pass NUI_CEF_ARCHIVE, NUI_CEF_ROOT or NUI_CEF_SYSTEM instead" FORCE)
 
     find_package(nlohmann_json REQUIRED)
     find_package(fmt REQUIRED)
@@ -33,7 +34,9 @@ if(NOT EMSCRIPTEN)
     add_library(boost_mp11 INTERFACE IMPORTED GLOBAL)
 
     add_subdirectory("${CMAKE_SOURCE_DIR}/dependencies/portable-file-dialogs" EXCLUDE_FROM_ALL)
-    add_subdirectory("${CMAKE_SOURCE_DIR}/dependencies/webview" EXCLUDE_FROM_ALL)
+    if (NOT NUI_BROWSER_ENGINE STREQUAL "cef")
+        add_subdirectory("${CMAKE_SOURCE_DIR}/dependencies/webview" EXCLUDE_FROM_ALL)
+    endif()
     add_subdirectory("${CMAKE_SOURCE_DIR}/dependencies/yaml-cpp" EXCLUDE_FROM_ALL)
     add_subdirectory("${CMAKE_SOURCE_DIR}/dependencies/rapidfuzz" EXCLUDE_FROM_ALL)
     add_subdirectory("${CMAKE_SOURCE_DIR}/dependencies/spdlog" EXCLUDE_FROM_ALL)

backend/include/backend/browser_engine.hpp

@@ -0,0 +1,10 @@
+#pragma once
+
+#include <string>
+
+/**
+ * @brief Name and version of the browser engine that renders the page, read at runtime.
+ *
+ * For example "Chromium 154.0.8037.98 (CEF 154.0.34)", "WebKitGTK 2.50.1" or "WebView2 141.0.3537.71".
+ */
+std::string browserEngineDescription();

backend/include/backend/cef/cef_hooks.hpp

@@ -0,0 +1,27 @@
+#pragma once
+
+#include <nui/backend/rpc_hub.hpp>
+#include <nui/window.hpp>
+
+#include <roar/detail/pimpl_special_functions.hpp>
+
+#include <memory>
+
+/**
+ * @brief CEF behaviour of the main window the page cannot provide on its own.
+ * @details Chromium hands dropped files to JavaScript without their paths. The drag handler reads them when a drag
+ *          enters the window and hands them to the frontend when it claims the drop (NativeFileDrop::claim), like the
+ *          WKWebView hooks on macOS. The hooks also strip the navigation entries from the context menu and keep the
+ *          window on the app: a reload loses the RPC initialization, a file dropped outside a drop zone or a followed
+ *          link would replace the app.
+ */
+class CefHooks
+{
+  public:
+    CefHooks(Nui::Window& window, Nui::RpcHub& hub);
+    ROAR_PIMPL_SPECIAL_FUNCTIONS(CefHooks);
+
+  private:
+    struct Implementation;
+    std::unique_ptr<Implementation> impl_;
+};