feat(desktop-qt): add a customizable QML shell and example layouts

.github/workflows/desktop-qt.yml

@@ -0,0 +1,117 @@
+name: desktop-qt
+
+on:
+  push:
+    paths:
+      - "apps/desktop-qt/**"
+      - "apps/server/**"
+      - "apps/web/**"
+      - "packages/**"
+      - "patches/**"
+      - "assets/prod/black-universal-1024.png"
+      - "scripts/lib/cli-external-packages.ts"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "vite.config.ts"
+      - ".github/workflows/desktop-qt.yml"
+  pull_request:
+    paths:
+      - "apps/desktop-qt/**"
+      - "apps/server/**"
+      - "apps/web/**"
+      - "packages/**"
+      - "patches/**"
+      - "assets/prod/black-universal-1024.png"
+      - "scripts/lib/cli-external-packages.ts"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "vite.config.ts"
+      - ".github/workflows/desktop-qt.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-24.04
+            qt_host: linux
+            qt_arch: linux_gcc_64
+          - os: macos-15
+            qt_host: mac
+            qt_arch: clang_64
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Setup Vite+
+        uses: voidzero-dev/setup-vp@v1
+        with:
+          node-version-file: package.json
+          cache: true
+          run-install: |
+            args:
+              - --filter=t3...
+
+      # Official Qt binaries on every platform so WebEngine is always present
+      # (distro packages often ship without it).
+      - uses: jurplel/install-qt-action@v4
+        with:
+          version: "6.9.*"
+          host: ${{ matrix.qt_host }}
+          arch: ${{ matrix.qt_arch }}
+          modules: qtwebengine qtwebchannel qtpositioning
+          cache: true
+
+      - name: Install build tools (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ninja-build libgl1-mesa-dev libxkbcommon-dev libfuse2 \
+            libxcb-cursor0 libnss3 libxcomposite1 libxdamage1 libxrandr2 libasound2t64
+
+      - name: Install build tools (macOS)
+        if: runner.os == 'macOS'
+        run: brew install ninja
+
+      - name: Configure
+        run: >
+          cmake -S apps/desktop-qt -B apps/desktop-qt/build/release -G Ninja
+          -DCMAKE_BUILD_TYPE=Release
+          -DCMAKE_PREFIX_PATH="${{ env.QT_ROOT_DIR }}"
+
+      - name: Build
+        run: cmake --build apps/desktop-qt/build/release
+
+      - name: Build server runtime
+        run: vp run --filter t3 build
+
+      - name: Test QML
+        run: node apps/desktop-qt/scripts/test-qml.mjs
+
+      - name: Package (Linux AppImage)
+        if: runner.os == 'Linux'
+        run: apps/desktop-qt/scripts/package-linux.sh apps/desktop-qt/build/release
+
+      - name: Package (macOS app bundle)
+        if: runner.os == 'macOS'
+        run: |
+          node apps/desktop-qt/scripts/stage-runtime.mjs apps/desktop-qt/build/release/t3code-qt.app/Contents/Resources/t3code
+          "${QT_ROOT_DIR}/bin/macdeployqt" apps/desktop-qt/build/release/t3code-qt.app -qmldir=apps/desktop-qt/qml
+          ditto -c -k --keepParent apps/desktop-qt/build/release/t3code-qt.app apps/desktop-qt/build/release/t3code-qt-macos.zip
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: t3code-qt-${{ matrix.os }}
+          path: |
+            apps/desktop-qt/build/release/*.AppImage
+            apps/desktop-qt/build/release/*.zip
+          if-no-files-found: error

apps/desktop-qt/CMakeLists.txt

@@ -0,0 +1,120 @@
+cmake_minimum_required(VERSION 3.21)
+
+project(t3code-qt VERSION 0.0.1 LANGUAGES CXX)
+
+if(APPLE)
+  enable_language(OBJCXX)
+endif()
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_AUTOMOC ON)
+
+find_package(Qt6 6.9 REQUIRED COMPONENTS Core Gui GuiPrivate Quick WebEngineQuick WebChannel)
+qt_standard_project_setup(REQUIRES 6.9)
+qt_policy(SET QTP0001 NEW)
+
+# Where the QML bricks live on disk. Non-release builds load them from here so
+# edits hot-reload without a rebuild; release builds only use the compiled-in
+# copies. T3_QML_SOURCE_DIR="" disables disk loading for any build type.
+if(NOT DEFINED T3_QML_SOURCE_DIR)
+  set(T3_QML_SOURCE_DIR "$<IF:$<CONFIG:Release>,,${CMAKE_CURRENT_SOURCE_DIR}/qml>")
+endif()
+
+# The Node desktop host entry. In-repo builds point at the TypeScript source.
+# Release builds resolve an installed path relative to the executable.
+if(NOT DEFINED T3_HOST_ENTRY)
+  if(APPLE)
+    set(_t3_installed_host "../Resources/t3code/host/main.ts")
+  else()
+    set(_t3_installed_host "../share/t3code/host/main.ts")
+  endif()
+  set(T3_HOST_ENTRY "$<IF:$<CONFIG:Release>,${_t3_installed_host},${CMAKE_CURRENT_SOURCE_DIR}/host/main.ts>")
+endif()
+
+# Release packages carry the same Node executable that installed their native
+# dependencies. Development builds keep using the command from PATH.
+if(NOT DEFINED T3_NODE_ENTRY)
+  if(APPLE)
+    set(_t3_installed_node "../Resources/t3code/bin/node")
+  elseif(WIN32)
+    set(_t3_installed_node "../share/t3code/bin/node.exe")
+  else()
+    set(_t3_installed_node "../share/t3code/bin/node")
+  endif()
+  set(T3_NODE_ENTRY "$<IF:$<CONFIG:Release>,${_t3_installed_node},node>")
+endif()
+
+# qwebchannel.js is the browser half of Qt WebChannel. Qt installs it as data
+# (share/qt6/webchannel); bundling it makes the injected script independent of
+# whether the runtime Qt exposes it as a qrc resource.
+get_filename_component(_qt_prefix "${QT6_INSTALL_PREFIX}" ABSOLUTE)
+find_file(T3_QWEBCHANNEL_JS qwebchannel.js
+  HINTS
+    "${_qt_prefix}/${QT6_INSTALL_DATA}/webchannel"
+    "${_qt_prefix}/share/qt6/webchannel"
+    "${_qt_prefix}/share/qt/webchannel"
+    "${_qt_prefix}/../qtwebchannel/share/qt6/webchannel"
+)
+
+qt_add_executable(t3code-qt
+  src/main.cpp
+  src/BackendProcess.cpp
+  src/BackendProcess.h
+  src/ShellBridge.cpp
+  src/ShellBridge.h
+  src/ShellRuntime.cpp
+  src/ShellRuntime.h
+  src/ThemeStore.cpp
+  src/ThemeStore.h
+  src/WebProfile.cpp
+  src/WebProfile.h
+  src/PlatformWindow.h
+)
+
+if(T3_QWEBCHANNEL_JS)
+  set_source_files_properties("${T3_QWEBCHANNEL_JS}" PROPERTIES QT_RESOURCE_ALIAS "qwebchannel.js")
+  qt_add_resources(t3code-qt "t3_webchannel" PREFIX "/t3" FILES "${T3_QWEBCHANNEL_JS}")
+  target_compile_definitions(t3code-qt PRIVATE T3_WEBCHANNEL_SCRIPT_URL="qrc:/t3/qwebchannel.js")
+else()
+  message(STATUS "qwebchannel.js not found next to Qt; relying on qrc:///qtwebchannel/qwebchannel.js at runtime")
+  target_compile_definitions(t3code-qt PRIVATE T3_WEBCHANNEL_SCRIPT_URL="qrc:///qtwebchannel/qwebchannel.js")
+endif()
+
+target_compile_definitions(t3code-qt PRIVATE
+  T3_QML_SOURCE_DIR="${T3_QML_SOURCE_DIR}"
+  T3_HOST_ENTRY="${T3_HOST_ENTRY}"
+  T3_NODE_ENTRY="${T3_NODE_ENTRY}"
+  T3_APP_VERSION="${PROJECT_VERSION}"
+)
+
+if(APPLE)
+  target_sources(t3code-qt PRIVATE src/PlatformWindow.mm)
+  target_link_libraries(t3code-qt PRIVATE "-framework AppKit")
+else()
+  target_sources(t3code-qt PRIVATE src/PlatformWindow.cpp)
+endif()
+
+add_subdirectory(qml/T3/Bricks)
+
+target_link_libraries(t3code-qt PRIVATE
+  Qt6::Core
+  Qt6::Gui
+  Qt6::GuiPrivate
+  Qt6::Quick
+  Qt6::WebEngineQuick
+  Qt6::WebChannel
+  t3bricksplugin
+)
+
+set_target_properties(t3code-qt PROPERTIES
+  MACOSX_BUNDLE TRUE
+  MACOSX_BUNDLE_GUI_IDENTIFIER "codes.t3.desktop-qt"
+  MACOSX_BUNDLE_BUNDLE_NAME "T3 Code"
+  WIN32_EXECUTABLE TRUE
+)
+
+install(TARGETS t3code-qt
+  BUNDLE DESTINATION .
+  RUNTIME DESTINATION bin
+)

apps/desktop-qt/README.md

@@ -0,0 +1,25 @@
+# @t3tools/desktop-qt
+
+Qt/QML shell for T3 Code. Hosts the web app in a `WebEngineView` and lets the
+window chrome be rearranged and themed from `~/.t3/shell/`.
+
+Architecture, setup, and the QML/theme contracts: `docs/internals/desktop-qt.md`.
+
+```sh
+vp run dev                      # terminal 1: server + web
+vp run dev:qt                   # terminal 2: build the shell, pair, launch
+```
+
+Focused native checks use temporary data and run offscreen:
+
+```sh
+vp run --filter @t3tools/desktop-qt test:qml
+cmake -S apps/desktop-qt/tests/native -B apps/desktop-qt/build/tests/native
+cmake --build apps/desktop-qt/build/tests/native
+ctest --test-dir apps/desktop-qt/build/tests/native --output-on-failure
+```
+
+`ShellRuntime` covers reload and theme ownership. `ShellExamples` loads all
+four examples at 640, 1000, and 1400 pixels, checking header text and dashboard
+card bounds, long branch names, clipped icons, and scrolling to the last card. It uses a local
+view-model fixture and a blank web page; no running server or pairing is needed.

apps/desktop-qt/examples/README.md

@@ -0,0 +1,40 @@
+# Shell examples
+
+Each folder is a complete rice: a `shell.qml` layout composed from the
+`T3.Bricks` module and a `theme.json` in the web app's theme format (plus the
+shell-only `window`, `radius` and `fonts` keys). Copy one into your config dir
+and the app reloads on save:
+
+```sh
+cp examples/glass/*.* ~/.t3/shell/
+```
+
+| Example     | Idea                                                                                                                                                                                                                                                                                                                                                    |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `minimal`   | The default layout with the title bar moved to the bottom, on the web app's own dark palette (`theme.json` here is the page's default theme, so it is the one to copy when a rice should start from stock colours).                                                                                                                                     |
+| `dashboard` | Rosé light theme, an icon rail that also carries settings, and a Dashboard button that pulls a widget drawer over the page: today, the month, the open workspace, thread meters, and the agent, with a cat at play (a Lottie animation; needs the Qt Lottie module, `qt6-lottie` on Arch, and shows the agent's initial without it).                    |
+| `glass`     | The shape of a Mac app: one rounded window with a hairline edge, traffic lights, a translucent sidebar for the compositor to blur behind, and a unified toolbar over an opaque content column.                                                                                                                                                          |
+| `terminal`  | Status line with the wordmark, a prompt mark, counts and the model; mono type, sharp corners. Made for a tiling desktop such as Omarchy, with flags at the top of `shell.qml` for a clock, window buttons and a chip of the palette's sixteen colours. Its `theme.json` is Tokyo Night as `vp run theme:qt` writes it from a terminal in those colours. |
+
+Pick up your own terminal's colours (it asks the terminal for its palette and
+writes `theme.json` into the shell directory, `~/.t3/shell` by default):
+
+```sh
+vp run theme:qt
+vp run theme:qt ~/.t3/shell
+```
+
+What you can reach from `shell.qml`: `ShellWindow` as the root (window
+colour, opacity and frame from the theme, `sidebarCollapsed` and
+`settingsActive` from the page, the error overlay and the page's window
+commands built in), the bricks (`TitleBar`, `Sidebar`, `SettingsNav`,
+`Workspace`, `GitActions`, `WebSurface`, `Composer`, `RightPanel`, `TerminalDrawer`,
+`Notifications`), the themed controls (`ShellCard`, `ShellButton`,
+`ShellComboBox`, `ShellTextField`, `ShellMenu`, `ShellMenuItem`, `ShellIcon`,
+`WindowControls`), and the `T3.Shell` singletons: `Shell.state.<key>` for
+everything the page publishes, `Shell.dispatch(action, payload)` to act,
+`Theme.color(role, fallback)` / `Theme.radius` / `Theme.fontUi` /
+`Theme.fontMono`, and `Runtime.reload()`.
+
+A broken `shell.qml` never locks you out: the built-in shell takes over with
+the error shown in an overlay.

apps/desktop-qt/examples/dashboard/CatPlaying.qml

@@ -0,0 +1,20 @@
+import QtQuick
+import Qt.labs.lottieqt
+
+// The cat at play (cat-playing.json), fitted into whatever box it is given.
+// Qt Lottie paints at the frame size the file declares, so the painter is
+// scaled instead of the item. Needs the Qt Lottie module (qt6-lottie); the
+// dashboard falls back to the agent's initial when the import fails.
+LottieAnimation {
+    id: cat
+
+    // The file's frame (its "w" and "h"); the host resizes the item.
+    readonly property size frame: Qt.size(1070, 456)
+
+    implicitHeight: width * frame.height / frame.width
+    source: "cat-playing.json"
+    autoPlay: true
+    loops: LottieAnimation.Infinite
+    quality: LottieAnimation.HighQuality
+    contentsScale: Math.min(width / frame.width, height / frame.height)
+}