A look at the architecture beneath SHIFT's convergence mode: one configuration flag, a dozen listeners, and what it actually takes to make a phone shell turn into a desktop without restarting.

The first post about SHIFT described what convergence means at the intent level: a single shell that reconfigures itself when you connect a monitor, without rebooting, without switching sessions. This one goes one level down, into how it's actually built.

One flag

The whole thing pivots on a single value: convergenceModeEnabled, a boolean stored in plasmamobilerc. Every component in the shell reads it from ShellSettings.Settings, a shared QML singleton. When it changes — because you docked the device, or because you toggled the quick setting — the change propagates automatically to every listener. No restart, no re-launch.

What that looks like in practice: the navigation gesture bar has visible: !ShellSettings.Settings.convergenceModeEnabled. In phone mode it's there; in desktop mode it simply isn't. The dock underneath does the opposite — it expands from a phone-style icon row into a full desktop dock with running-app indicators. The status bar gains a system tray. The KWin compositor starts applying window decorations instead of stripping them. All of this happens in response to the same property changing in the same config file.

The bar that transforms

The most interesting piece of code in SHIFT isn't the thing that's most visible. It's FavouritesBar.qml — the horizontal strip at the bottom of the homescreen that shows pinned apps.

In phone mode, this is a row of four or five icons sitting above the gesture bar. In desktop mode, it becomes the dock: the same component, same icons, same position in the containment hierarchy, but its geometry and behavior change completely based on convergenceModeEnabled.

The icon cells change size — dockCellWidth: convergenceMode ? root.height : folio.HomeScreenState.pageCellWidth — so that in convergence mode the icons are sized for a dock bar rather than a phone grid. Running apps appear alongside the pinned favourites. Navigation control buttons materialise on either side. A virtual desktop pager appears when there are multiple desktops. Every transition is animated with a NumberAnimation so the bar doesn't jump — it slides and resizes as the context switches.

This is the most direct expression of SHIFT's design premise: the shell doesn't maintain two separate docks, one for phones and one for desktops. It maintains one dock that knows what it is. The phone dock and the desktop dock are the same QML item in two different states.

The window manager's job

The shell itself is just QML drawn on top of a compositor. The behaviour of windows — whether they're maximized, whether they have decorations, where they sit on screen — is managed by KWin. SHIFT ships a KWin script, convergentwindows, that watches every window and decides what to do with it.

The rules are simple in outline. In phone mode: maximize everything, strip decorations. In desktop mode: restore decorations, let windows be windowed. In gaming mode: maximize everything, strip decorations again — but for a different reason.

The script also watches the convergenceModeEnabled flag. When it changes, the script iterates every open window and re-applies the current rules in-place. You can have five apps open on the phone, plug in a monitor, and all five windows simultaneously acquire titlebars and restore to their last desktop-mode size and position.

There's a subtlety buried in there that reveals real engineering. When a window un-maximizes in convergence mode, the dock at the bottom reserves its own space through the Wayland layer-shell protocol. But the layer-shell exclusive zone — the reservation that tells the compositor to keep windows out of that area — needs one Wayland round-trip to commit before KWin updates its MaximizeArea. If you restore a window immediately, it can extend behind the dock. The solution is a 200-millisecond deferred timer: after an un-maximize, wait for the round-trip, then clamp the window's bottom edge to the available area. It's a small thing, but it's the kind of small thing that the alternative — three completely separate shell codebases — would need to solve three times.

Dynamic tiling

The tiling engine is separate from the convergence machinery, though it reads the same settings. It's implemented as a second KWin script that runs a BSP algorithm — binary space partitioning, the same approach used by tiling window managers like bspwm and xmonad — on each monitor independently.

Each screen maintains an ordered list of tile slots. When a new window opens, it splits an existing slot to make room. Dragging a window over another tile swaps them. Drag to a screen edge and the window snaps to a predefined split. The gaps — 8 pixels outer, 8 pixels inner — are applied symmetrically so tiles butting against each other look like they have 8 pixels of space, not 16.

The same 200-millisecond deferred flush pattern appears here too, for the same reason: the exclusive zone round-trip. Rather than duplicate the insight, both scripts independently arrived at the same solution — which is probably the strongest evidence that the constraint is real.

Window thumbnails via PipeWire

Hover over a running-app icon in the convergence dock, and a live preview of the window appears. This is PipeWireThumbnail.qml, ten lines of QML that wraps PipeWire.PipeWireSourceItem and a TaskManager.ScreencastingRequest.

PipeWire is primarily an audio routing layer, but it doubles as the standard Wayland screen-sharing mechanism. The screencasting request takes a window UUID, negotiates with the compositor for a PipeWire stream, and the PipeWireSourceItem renders whatever the compositor is sending. On X11 this would have required XComposite and a grabbed pixmap. On Wayland with PipeWire it's a standard protocol exchange. The shell doesn't need special compositor privileges or a screencasting daemon; it just asks through the regular channel.

What it means to build on a fork

SHIFT is a fork of plasma-mobile, which is itself part of the KDE Plasma project. Most of the code in the repository — the homescreen layouts, the quick settings tiles, the status bar widgets, the action drawer — comes from upstream. SHIFT adds its layer on top: the convergence dock behavior, the KWin scripts, the dynamic tiling, the settings integration.

The consequence is that when KDE ships a Plasma 6.x update, SHIFT picks up those changes by rebasing. New upstream components, bug fixes, and translated strings arrive automatically. The convergence work doesn't fork the homescreen from scratch — it extends it. The FavouritesBar that transforms into a desktop dock started its life as an upstream component; SHIFT's changes are additions, not rewrites.

This shapes what the project can be. It's not aiming to be a complete alternative to KDE. It's aiming to be the convergence behavior that KDE Plasma Mobile currently lacks, sitting on top of the infrastructure KDE already maintains.

The repository is at code.marcoallegretti.me/marcoallegretti/shift-shell.