tools: install local preview QML stubs

openSUSE Tumbleweed's plasma6-nm 6.6.4 does not ship the org.kde.plasma.networkmanagement.cellular QML submodule that SignalStrengthInfo.qml imports unconditionally. Without it the MobileShell QML namespace fails to load and preview boots to a black screen.

Keep a minimal fallback module under tools/preview-stubs and install it only for local .prefix preview installs by default, with SHIFT_INSTALL_PREVIEW_QML_STUBS=AUTO/ON/OFF for explicit control. Add a CTest guard so qmldir entries stay backed by real files and the fallback remains tied to the QML import tree.

CMakeLists.txt

@@ -153,6 +153,7 @@ add_subdirectory(cursors)
 add_subdirectory(desktoptheme)
 add_subdirectory(fonts)
 add_subdirectory(icons)
+add_subdirectory(tools/preview-stubs)
 add_subdirectory(wallpapers)
 add_subdirectory(components)
 add_subdirectory(containments)

tests/CMakeLists.txt

@@ -25,6 +25,11 @@ if(BASH_EXECUTABLE)
         COMMAND ${BASH_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/check-shift-theme-identity.sh
     )
 
+    add_test(
+        NAME shift-preview-qml-stubs
+        COMMAND ${BASH_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/check-preview-qml-stubs.sh
+    )
+
     add_test(
         NAME shift-initialstart-metadata
         COMMAND ${BASH_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/check-shift-initialstart-metadata.sh

tests/check-preview-qml-stubs.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2026 Marco Allegretti
+# SPDX-License-Identifier: EUPL-1.2
+
+set -euo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$repo_dir"
+
+fail() {
+    printf '%s\n' "$1" >&2
+    exit 1
+}
+
+[[ -f tools/preview-stubs/CMakeLists.txt ]] || fail "preview QML stubs must have tracked CMake integration"
+grep -Fq 'set(SHIFT_INSTALL_PREVIEW_QML_STUBS "AUTO"' tools/preview-stubs/CMakeLists.txt \
+    || fail "preview QML stubs must default to AUTO, not unconditional installation"
+grep -Fq 'PROPERTY STRINGS AUTO ON OFF' tools/preview-stubs/CMakeLists.txt \
+    || fail "preview QML stubs must provide an explicit OFF mode"
+grep -Fq 'CMAKE_INSTALL_PREFIX MATCHES "/\\.prefix$"' tools/preview-stubs/CMakeLists.txt \
+    || fail "preview QML stubs must be limited to local .prefix installs by default"
+grep -Eq 'DESTINATION \$\{KDE_INSTALL_QMLDIR\}' tools/preview-stubs/CMakeLists.txt \
+    || fail "preview QML stubs must install into the Qt QML import tree"
+
+while IFS= read -r -d '' qmldir; do
+    module_dir="$(dirname "$qmldir")"
+    while IFS= read -r line; do
+        line="${line%%#*}"
+        [[ -n "${line//[[:space:]]/}" ]] || continue
+
+        case "$line" in
+            module\ *|plugin\ *|classname\ *|typeinfo\ *|depends\ *|prefer\ *)
+                continue
+                ;;
+        esac
+
+        set -- $line
+        qml_file="${3:-}"
+        [[ -n "$qml_file" ]] || continue
+        [[ -f "$module_dir/$qml_file" ]] || fail "$qmldir declares missing file: $qml_file"
+    done < "$qmldir"
+done < <(find tools/preview-stubs/qml -name qmldir -print0)
+
+printf 'preview-qml-stubs-ok\n'

tools/preview-stubs/CMakeLists.txt

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2026 Marco Allegretti
+# SPDX-License-Identifier: EUPL-1.2
+
+set(SHIFT_INSTALL_PREVIEW_QML_STUBS "AUTO" CACHE STRING "Install preview fallback QML stubs: AUTO, ON, or OFF")
+set_property(CACHE SHIFT_INSTALL_PREVIEW_QML_STUBS PROPERTY STRINGS AUTO ON OFF)
+
+if(NOT SHIFT_INSTALL_PREVIEW_QML_STUBS MATCHES "^(AUTO|ON|OFF)$")
+    message(FATAL_ERROR "SHIFT_INSTALL_PREVIEW_QML_STUBS must be AUTO, ON, or OFF")
+endif()
+
+set(_shift_install_preview_qml_stubs OFF)
+if(SHIFT_INSTALL_PREVIEW_QML_STUBS STREQUAL "ON")
+    set(_shift_install_preview_qml_stubs ON)
+elseif(SHIFT_INSTALL_PREVIEW_QML_STUBS STREQUAL "AUTO" AND CMAKE_INSTALL_PREFIX MATCHES "/\\.prefix$")
+    set(_shift_install_preview_qml_stubs ON)
+endif()
+
+if(_shift_install_preview_qml_stubs)
+    install(
+        DIRECTORY qml/
+        DESTINATION ${KDE_INSTALL_QMLDIR}
+        FILES_MATCHING
+            PATTERN "*.qml"
+            PATTERN "qmldir"
+    )
+endif()

tools/preview-stubs/README.md

@@ -0,0 +1,28 @@
+<!-- SPDX-FileCopyrightText: 2026 Marco Allegretti -->
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Preview-only QML stubs
+
+These stub modules satisfy QML imports that **upstream Plasma Mobile expects**
+but that are not provided by the QML packages shipped on the host distro used
+for preview/development.
+
+They are installed only for local preview prefixes by default:
+`SHIFT_INSTALL_PREVIEW_QML_STUBS=AUTO` enables installation when
+`CMAKE_INSTALL_PREFIX` ends in `.prefix`. Set it to `ON` to force installation
+for another prefix, or `OFF` to disable it. Production installs using normal
+system prefixes leave these stubs out.
+
+## Current stubs
+
+- `org/kde/plasma/networkmanagement/cellular/` — `CellularModemList`,
+  `CellularModem`. Required by
+  `components/mobileshell/qml/dataproviders/SignalStrengthInfo.qml`.
+  openSUSE Tumbleweed's `plasma6-nm 6.6.4` package does not ship this
+  QML submodule (only the cellular KCM `.so`). Without the stub the
+  entire MobileShell QML namespace fails to load and the homescreen
+  is blank.
+
+When the host distro starts providing a real module at the same import path,
+disable the local fallback by configuring with `SHIFT_INSTALL_PREVIEW_QML_STUBS=OFF`
+before comparing against the system module.

tools/preview-stubs/qml/org/kde/plasma/networkmanagement/cellular/CellularModem.qml

@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: 2026 Marco Allegretti
+// SPDX-License-Identifier: EUPL-1.2
+
+// Minimal stub for the upstream plasma-nm cellular QML module.
+// See CellularModemList.qml for rationale.
+import QtQuick
+QtObject {
+    property bool mobileDataEnabled: false
+    property bool mobileDataSupported: false
+    property bool needsAPNAdded: false
+    property bool simEmpty: true
+}

tools/preview-stubs/qml/org/kde/plasma/networkmanagement/cellular/CellularModemList.qml

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2026 Marco Allegretti
+// SPDX-License-Identifier: EUPL-1.2
+
+// Minimal stub for the upstream plasma-nm cellular QML module.
+// openSUSE Tumbleweed's plasma6-nm 6.6.4 package does not yet ship this
+// module, but components/mobileshell/.../SignalStrengthInfo.qml imports
+// it unconditionally. Without this stub, every MobileShell type fails to
+// load and the homescreen is blank.
+import QtQuick
+QtObject {
+    property bool modemAvailable: false
+    property var primaryModem: null
+}

tools/preview-stubs/qml/org/kde/plasma/networkmanagement/cellular/qmldir

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2026 Marco Allegretti
+# SPDX-License-Identifier: EUPL-1.2
+
+module org.kde.plasma.networkmanagement.cellular
+CellularModemList 1.0 CellularModemList.qml
+CellularModem 1.0 CellularModem.qml