K3 DEPLOYMENT — QML MODULES AND PLATFORM INTEGRATION IN PACKAGED BUILDS

Context

K3 3.0 beta1 is distributed as a portable Linux AppImage. Five testers (openSUSE Leap/Plasma, Manjaro/XFCE, Linux Mint/Cinnamon, CachyOS/Plasma, openSUSE MicroOS/Kalpa) and one Tumbleweed box all reported the same defect: no file or folder dialog appeared when opening or creating a File-mode (SQLite) collection. The same build from source on the development machine worked. Nothing was wrong with the application code.

The AppImage bundles a hand-written list of QML modules. It ships no native file-dialog helper, so QtQuick.Dialogs falls back to its non-native QML implementation — and that implementation imports Qt.labs.folderlistmodel, which the list did not include. The dialog therefore never became visible and the only trace was a log line:

QML FileDialog: Failed to load non-native FileDialog implementation:
module "Qt.labs.folderlistmodel" is not installed

A silent feature loss, visible only to whoever reads the packaged build's stderr. That is the failure mode this page exists to prevent, not just the one missing module.

Adding the module was verified on the openSUSE Leap Plasma virtual machine: the dialog now appears (DPL-F1). With it appearing, a second, smaller report followed — the dialog that appears is Qt's own Fusion-styled Qt Quick dialog with a foreign icon set, not the Plasma dialog the locally built K3 shows. The cause is the same gap: the bundle carries no KDE desktop integration. The approved response is to use the host's own dialog through the XDG desktop portal (DPL-F3), not to bundle a KDE style and icon theme — see Known limitations.

This page covers what a packaged K3 build must contain. It does not cover what any dialog or page does once it works: the collection dialogs themselves are SpecCollectionOpen.md.

Reading the requirement IDs. Each requirement has a permanent ID. IDs are never renumbered or reused; a retired requirement is marked [Removed], not deleted. Status is one of [Implemented] / [Planned] / [Backlog] / [Removed].

---

Scope at a glance

In scope: the QML modules a packaged K3 Linux build must contain, including the modules that bundled modules load at runtime; the platform theme that decides whether file and folder selection uses the host's dialog; the fallback when the host offers none; and the rule that keeps the hand-written module list in step with the sources — and, added 2026-09-23 at the maintainer's direction, the Kirigami colour theme of packaged builds on Linux (AppImage), Windows (portable) and macOS (portable), so that they follow the host's light/dark preference (DPL-F5, DPL-C6) — and, added 2026-10-12 at the maintainer's direction, the build environment and image-library integrity of the macOS package (DPL-F6, DPL-C7, DPL-C8, DPL-C9).

Out of scope (non-goals): the Controls style of packaged builds, which stays Fusion, and the icon theme — recorded below as known limitations, and deliberately not planned work (DPL-C4). Bundling Breeze icon files, building qqc2-desktop-style and building frameworkintegration were each considered and not authorised. The Windows and macOS portable bundles, except for DPL-F5 / DPL-C6 and the macOS rows DPL-F6 / DPL-C7 / DPL-C8 / DPL-C9. Flatpak and any other downstream manifest. K2 packaging (see SpecK2Deployment). The behaviour of any dialog or page once it loads. No qt_quick source change is authorised by this page.

---

Operational requirements — why / for whom

Goals in real use, independent of how they are built.

ID	Requirement	Status
DPL-O1	A tester running a released package gets the same working features as someone running a build from source: every dialog and page that works in a development build also works in the package. A QML module absent from the package MUST NOT silently disable a feature.	[Planned]
DPL-O2	A user selecting a file or folder in a packaged build gets the file dialog of the desktop they are actually running, and can still select a file or folder on a desktop that provides none.	[Planned]

Both operational rows are marked [Planned], not [Implemented], and deliberately so: a goal is only as strong as its verification.

• DPL-O1 — its first instance, the file and folder dialogs, is closed and verified (DPL-F1), but no other page has been walked through in a packaged build yet.
• DPL-O2 — its first half is verified: the host's own dialog appears on openSUSE Leap / Plasma, Linux Mint / Cinnamon and Manjaro / XFCE (DPL-F3). Its second half is not: none of those three hosts lacked a portal backend, so the fallback is built and asserted but has not been seen in use (DPL-F4).

The Implementation shield reads mostly complete on that basis. Every functional row about what the package contains is implemented (DPL-F1, DPL-F3, DPL-F4) and every constructional row is satisfied. What remains is the breadth of verification behind the two operational rows, and DPL-F2, which is a release gate rather than something that can be built.

Functional requirements — what the system does

Observable behaviour that can be triggered and watched.

ID	Requirement	Status
DPL-F1	The Linux AppImage contains every QML module the qt_quick sources import and every module those modules load at runtime. This explicitly includes Qt.labs.folderlistmodel, which no Katalog source imports: the non-native QtQuick.Dialogs implementation requires it, and that implementation is what runs whenever the host offers no native dialog helper. Verified on openSUSE Leap / Plasma: the File-mode dialog appears.	[Implemented]
DPL-F2	A packaged build that logs module "X" is not installed, or Failed to load non-native ... implementation, is a release blocker. Such a line means a feature is silently unavailable to every user of that package.	[Planned]
DPL-F3	In a packaged Linux build, file and folder selection uses the host desktop's own dialog — Plasma's dialog on Plasma, the host's dialog elsewhere — obtained through Qt's xdgdesktopportal platform theme. Verified on openSUSE Leap / Plasma, Linux Mint / Cinnamon and Manjaro / XFCE.	[Implemented]
DPL-F4	When the host provides no portal backend, file and folder selection degrades to Qt's non-native QtQuick.Dialogs implementation and still works. Degradation is a supported path, not an error state. Built and asserted: the launcher selects the portal theme only when the plugin is present and otherwise leaves the theme unset, and the build fails if the fallback's QML module is missing. None of the three hosts tested for DPL-F3 lacked a portal backend, so the degraded path is implemented but not yet observed on a host that needs it.	[Implemented]
DPL-F5	A packaged build — Linux AppImage, Windows portable, macOS portable — follows the host's light/dark preference as Qt reports it through Qt.styleHints.colorScheme (from the XDG desktop portal on Linux, and from the operating system on Windows and macOS). The whole window is consistently light or dark: Kirigami surfaces and the Controls (buttons, text fields, combo boxes, menus). A dark window with light controls does not satisfy this row. The colours are Breeze Light or Breeze Dark, not the host's own colour scheme: a dark GNOME desktop gets Breeze Dark, not Adwaita Dark. When Qt reports no preference (Unknown / NoPreference), the build is light. When the preference changes while Katalog runs and Qt reports that change, the window follows it without a restart. On a host whose preference never reaches Qt, the build stays light, and that is not a defect of this row. (Note 2026-09-24: a host whose preference does reach Qt, but is misread at startup, is a different case from "never reaches Qt". It is recorded under Known limitations (Linux Mint / Cinnamon) as an upstream defect, not as a failure of this row: the build starts light there, and follows correctly from the first change of preference while it runs. Correcting the startup read inside Katalog is THM-F13 (SpecTheme.md), [Backlog], 3.1 candidate.)	[Planned]
DPL-F6	The macOS K3 package loads its bundled images: icons and the combo-box indicator arrows are drawn, and launching it never prints libpng warning: Application built with. That line means every PNG fails to load and is a release blocker, like DPL-F2. Minimum macOS for the K3 package is macOS 15 (Sequoia), Apple Silicon only.	[Planned]
DPL-F7	The Linux AppImage makes HTTPS connections whatever the host's unversioned libssl.so points to. It bundles OpenSSL 3 (libssl.so.3, libcrypto.so.3, plus unversioned libssl.so / libcrypto.so links to them), and the build fails if they cannot be found. Measured 2026-10-15: on a host where libssl.so points to LibreSSL (libressl-devel), Qt refused it (Incompatible version of OpenSSL), fell back to the cert-only backend, and every HTTPS request failed — the version check (SpecVersionCheck.md) stayed silent.	[Implemented]

Constructional requirements — how it is built / limits / MUST-NOTs

Boundaries and implementation constraints, not user-visible behaviour.

ID	Requirement	Status
DPL-C1	The AppImage QML module list is a hand-maintained allow-list, not a scan of the sources. Adding, changing or removing a QML import in any qt_quick source therefore MUST update that list in the same change. A source import that the list does not cover is the defect recorded in Context, and it fails silently.	[Implemented]
DPL-C2	The xdgdesktopportal platform-theme plugin MUST be present in the bundle, otherwise DPL-F3 cannot take effect however the theme is selected.	[Implemented]
DPL-C3	DPL-F1 remains mandatory after DPL-F3 is in place: it is a hard dependency of DPL-F3, not an alternative to it, because DPL-F4 is the path taken on every host without a portal backend. The bundled Qt.labs.folderlistmodel MUST NOT be dropped as "no longer needed now that dialogs are native".	[Implemented]
DPL-C4	The Controls style and icon theme of packaged builds are not part of this change. DPL-F3 addresses the reported appearance by using the host's own dialog instead. Bundling Breeze icon files, building qqc2-desktop-style and building frameworkintegration were each put to the maintainer for this round and not authorised, so no work on them is authorised here. They are not ruled out: introducing any of them is a separate decision, to be taken on its own merits, and requires the maintainer's approval and an amendment to this page first. See Known limitations. (Amended 2026-09-23: the Kirigami colour theme of packaged builds is not the Controls style. It is authorised separately by DPL-F5 / DPL-C6, and that authorisation does not lift anything else in this row.)	[Implemented]
DPL-C5	This work adds, changes and removes no user-visible string, and changes no file under core/. It is deployment configuration only. Likewise for DPL-F6 / DPL-C7–C9: workflow configuration only, no qt_quick source change.	[Implemented]
DPL-C6	DPL-F5 is delivered by packaging, through one file: packaging/Theme.qml in the repository (directly under packaging/, no subdirectory, per the maintainer), copied at package time to org/kde/kirigami/styles/Fusion/Theme.qml inside the bundled Kirigami module. It selects Breeze Light or Breeze Dark colour values from Qt.styleHints.colorScheme for Kirigami.Theme, and the same file covers the Controls part of DPL-F5: it writes the Breeze colours into the palette of each window holding a themed item (Window.window.palette), which Fusion controls inherit — once per window, and again only when the light/dark preference changes, never on every sync (a per-sync write propagates to every item and made startup take minutes in a 2026-09-23 test build). No second mechanism is authorised. Delivery path per platform: Linux — the AppImage workflow (.github/workflows/Katalog_3_Build_linux_qt6_buildKF6_appimage.yml) and packaging/linux/Katalog_create_appimage_local.sh; macOS — .github/workflows/Katalog_3_Build_macOS.yml; Windows — no workflow: the portable package is built manually on a Windows machine by the maintainer, who copies the file into place by hand. Where a package has a bundle allow-list, the file MUST be on it (DPL-C1), and its absence from any package is a failure of DPL-F5. The Breeze hex values live only in that bundled file; they are not a precedent for literal colours in qt_quick QML (SpecTheme.md Context). The Controls style stays Fusion (THM-C14); DPL-C4 and DPL-C5 still hold — no Breeze icon files, no qqc2-desktop-style, no frameworkintegration, no user-visible string, nothing under core/ — and no qt_quick source is changed.	[Planned]
DPL-C7	The K3 macOS package is built on the GitHub runner macos-15 (.github/workflows/Katalog_3_Build_macOS.yml). The runner defines the minimum macOS of DPL-F6. It MUST be a macOS release for which Homebrew publishes bottles of the Qt modules used. Homebrew bottles only the three latest macOS releases, so moving the runner when that window moves is a deliberate change, made together with an amendment of this row and DPL-F6. No Intel or universal build is authorised.	[Planned]
DPL-C8	The macOS workflow MUST fail if Homebrew built qtbase, or any other Qt module, from source instead of pouring a bottle. A runner-built Qt is the 3.0.beta3 defect cause (built against libpng 1.4.12 headers, run with bundled 1.6.59).	[Planned]
DPL-C9	The macOS workflow's launch test MUST fail the build if the bundled app's output contains libpng warning: Application built with. Printing it and passing is the gap that let 3.0.beta3 ship.	[Planned]

---

Known limitations of packaged builds

Recorded so that a future reader does not mistake them for defects introduced here, or for work that was agreed.

Item	Detail
Fusion style, not the desktop style	The bundle contains no qqc2-desktop-style, so Qt Quick Controls resolve to Fusion, visible in a tester's log as QtQuick/Controls/Fusion/Dialog.qml. Building that framework into the bundle was not authorised. Light/dark following is provided separately by DPL-F5.
Generic icon theme	breeze-icons is built when the bundle's KF6 stack is built, but only its shared libraries are copied — the icon files under share/icons/breeze never reach the AppDir, so icons fall back to whatever the host offers. Copying them was not authorised.
No KDE platform theme	frameworkintegration, which provides the kde platform theme plugin, is not built for the bundle. Building it was not authorised. DPL-F3 reaches the host's dialog through the portal instead.
Breeze colours, not the host's scheme	Under DPL-F5 a packaged build is Breeze Light or Breeze Dark. It does not take the host's own colours (Adwaita, Mint-Y, Windows accent colours). A host whose light/dark preference does not reach Qt stays light.
Starts light on Linux Mint / Cinnamon when the desktop is dark	A packaged build started while the Cinnamon desktop is dark opens light; it follows correctly as soon as the preference changes while it runs. Cause, measured 2026-09-24 on a Linux Mint / Cinnamon tester VM with an AppImage built on Qt 6.11.2: the host's xdg-desktop-portal returns the org.freedesktop.appearance namespace twice in Settings.ReadAll (two portal backends merged) — once with color-scheme 1 (dark), once with 0 (no preference). Qt's portal theme stores the ReadAll reply in a map at startup, so the last entry wins and Qt reports Unknown; ReadOne returns 1. Live switching works through SettingChanged. Qt's portal theme implements no requestColorScheme, so QStyleHints::setColorScheme cannot correct it. This is an upstream defect (portal / Qt), not Katalog's. Fedora Workstation / GNOME starts dark correctly. Accepted for 3.0 by the maintainer on 2026-09-24 rather than adding a dependency; the workaround is THM-F13 (SpecTheme.md), [Backlog], 3.1 candidate. Separately, Qt 6.10.0 had its own startup-read defect in the portal theme, fixed in 6.10.1; the AppImage workflow is on Qt 6.11.2. No Qt version is pinned by this page.
Stale drawing in the global drawer under the desktop's software Qt Quick renderer	Applies to any K3 build, packaged or from source, on a host that sets it. Measured 2026-09-30 on the maintainer's tower (openSUSE, KDE Plasma on Wayland, NVIDIA GeForce GTX 960, driver 580.178.04). The desktop-wide setting [QtQuickRendererSettings] SceneGraphBackend=software in kdeglobals makes every Qt Quick application, K3 included, use Qt's software renderer (qt.scenegraph.general: Loading backend software with QSG_INFO=1), and it takes precedence over the QT_QUICK_BACKEND environment variable. In that mode, after page and theme changes involving the Search Results page, moving focus to another window leaves stale drawing in the global drawer: copies of the drawer entries' frames below the last entry and between entries. A test build forcing the OpenGL RHI backend (a temporary diagnostic, since removed) did not show the problem; it was not reproduced on the maintainer's openSUSE Leap VM. Decision of 2026-09-30: K3 does not override the desktop's renderer choice; no code change. Workaround: set the Qt Quick rendering backend back to automatic by removing the key, e.g. kwriteconfig6 --file kdeglobals --group QtQuickRendererSettings --key SceneGraphBackend --delete, then restart Katalog. Not investigated further: what on the Results page triggers the software renderer's partial-update fault.
macOS 14 (Sonoma) and Intel Macs not supported	From the 3.0.beta3 rebuild (2026-10-12) the K3 macOS package is built on macOS 15 (DPL-C7) and does not start on macOS 14 or earlier; Apple Silicon only, as before. Cause: Homebrew no longer publishes arm64_sonoma bottles for qtbase 6.11.2_1 (CI run 38172585493 vs beta2 run 35544535205).

These three are the reason a packaged build looks unlike a local build. They are listed as limitations, not as requirements: none of them is authorised work today, and per DPL-C4 taking any of them on is a separate decision rather than something this page already sanctions.

---

Manual test charter

Each line is a case that must hold for a packaged build. Run them against the AppImage, not against a build from source — the whole subject of this page is the difference between the two.

• DPL-F1 / DPL-O1 — Launch the AppImage with QT_FORCE_STDERR_LOGGING=1, with no settings file present. At first run the File-mode file dialog appears and a database can be created; the Memory-mode folder dialog appears too. Verified on openSUSE Leap / Plasma after the module was added.
• DPL-F2 — Capture the full stderr of that same run, and of a session that visits every page. No module "..." is not installed line and no Failed to load non-native ... implementation line appears. Either one is a release blocker, not a cosmetic warning.
• DPL-F3 — On a Plasma host with a portal backend running, open the collection file dialog from the AppImage. The dialog is the host's own file dialog, not Qt's Fusion-styled Qt Quick dialog. Repeat on a non-Plasma host (XFCE or Cinnamon): the dialog is that desktop's own. Verified after implementation on openSUSE Leap / Plasma, Linux Mint / Cinnamon and Manjaro / XFCE. CachyOS / Plasma and openSUSE MicroOS / Kalpa, which reported the original defect, have not been retested.
• DPL-F4 — On a host with no portal backend available, open the same dialog. It still appears, as Qt's non-native implementation, and a file can be selected. This is the case that DPL-F1 keeps alive. Open: this case is the one gap in the DPL-F3 verification — all three hosts tested had a backend. Proving it needs a host without one, or a run with the portal plugin removed from the AppDir.
• DPL-C1 — Diff the QML import lines of every qt_quick source against the module list in the AppImage workflow. Every imported module is covered. Then confirm the last change that touched a QML import also touched the list.
• DPL-C2 — List the platform-theme plugins inside the built AppDir: the xdgdesktopportal plugin is present. Verified after implementation: the plugin is copied into the AppDir and the build logs the plugins it contains.
• DPL-C3 — Confirm Qt.labs.folderlistmodel is still in the bundled module list after the portal work. Its removal is a failure even if every test host happens to have a portal backend. Verified after implementation: the module is still bundled and the build now fails outright if it is absent.
• DPL-C4 — Review the diff: no Breeze icon files are copied into the AppDir, and neither qqc2-desktop-style nor frameworkintegration has been added to the bundle's framework build list.
• DPL-C5 — Review the diff for tr( and qsTr(: no addition, no change, no removal. Confirm no file under core/ is modified.
• DPL-F5 (Linux, non-Plasma) — On GNOME or XFCE with the desktop set to dark, launch the AppImage. Every page, including its buttons, fields and menus, is dark in Breeze Dark colours, not Adwaita. Switch the desktop to light while it runs: the window follows if the portal reports the change. Repeat with no portal backend: the window is light.
• DPL-F5 (Plasma) — Repeat on Plasma, light and dark: the packaged build follows as well.
• DPL-F5 (Windows, macOS) — With the OS in dark mode, launch the portable build. The whole window, controls included, is dark. Switch to light mode while it runs: the window follows.
• DPL-C6 — List the built AppDir and the macOS bundle, and the manually assembled Windows package: org/kde/kirigami/styles/Fusion/Theme.qml is present in each, and is on each allow-list where one exists. Grep qt_quick/ for new hex colours: there are none.
• DPL-F6 — On macOS 15 / Apple Silicon, mount the DMG and launch: toolbar and drawer icons and combo-box arrows are drawn. Launched from Terminal, no libpng warning line is printed.
• DPL-C7 — The workflow's runs-on is macos-15; lipo -archs in the step summary reads arm64.
• DPL-C8 — The brew install log shows Pouring for every Qt module and no Building from source; a forced source build makes the workflow fail.
• DPL-C9 — The launch-test step fails the job when its output contains the libpng mismatch line (check once by feeding a captured beta3 log through the same check).
• DPL-F7 — On a host whose libssl.so points to LibreSSL, start the AppImage with QT_LOGGING_RULES="qt.network.ssl*=true;qt.tlsbackend*=true": no Incompatible version of OpenSSL and no TLS initialization failed; a version-check build lower than the latest release shows its dialog.