move carouselview to standalone c++ component, fix crash due to memory leak in wallpaper object creation

Modules/Launcher/CarouselView.qml

@@ -1,338 +1,55 @@
-pragma ComponentBehavior: Bound
-
 import Quickshell
 import QtQuick
+import ZShell.Components
 import ZShell.Config
 import qs.Modules.Launcher.Items
 import qs.Components
 import qs.Helpers
 
-Item {
+CarouselView {
 	id: root
 
-	readonly property var arrangement: {
-		const W = width;
-		const F = focalWidth;
-		const M = minEdgeWidth;
-		const sp = itemSpacing;
-
-		if (W <= 0 || F <= 0)
-			return {
-				n: 0,
-				sizes: [F],
-				effectiveExtraWidth: 0
-			};
-
-		let bestN = 0;
-		let bestSizes = [F];
-		let bestExtraWidth = 0;
-
-		for (let n = 1; ; n++) {
-			const ratio = Math.pow(M / F, 1 / n);
-			const sizes = [F];
-
-			for (let i = 1; i <= n; i++) {
-				sizes.push(i === n ? M : F * Math.pow(ratio, i));
-			}
-
-			let decreasedWidth = 0;
-
-			for (let i = 1; i <= n; i++)
-				decreasedWidth += pitch - sizes[i];
-
-			const effectiveWidth = W + decreasedWidth * 2;
-			const requiredWidth = (2 * n + 1) * pitch;
-
-			if (requiredWidth > effectiveWidth)
-				break;
-
-			bestN = n;
-			bestSizes = sizes;
-			bestExtraWidth = decreasedWidth;
-		}
-
-		return {
-			n: bestN,
-			sizes: bestSizes,
-			effectiveExtraWidth: bestExtraWidth
-		};
-	}
-	readonly property int centerBlockIndex: Math.floor(loopMultiplier / 2)
-	readonly property int centerBlockStart: centerBlockIndex * realCount
-	readonly property int currentRealIndex: realIndexOf(view.currentIndex)
-	readonly property real focalWidth: Config.launcher.sizes.wallpaperWidth
-	readonly property real itemSpacing: Tokens.spacing.small
-	readonly property var keylines: {
-		const sp = itemSpacing;
-		const sizes = arrangement.sizes;
-		const n = arrangement.n;
-
-		const right = [
-			{
-				io: 0,
-				lo: 0,
-				sz: sizes[0]
-			}
-		];
-
-		let lo = sizes[0] / 2;
-
-		for (let i = 1; i <= n; i++) {
-			const size = sizes[i];
-
-			lo += sp + size / 2;
-
-			right.push({
-				io: i,
-				lo: lo,
-				sz: size
-			});
-
-			lo += size / 2;
-		}
-
-		right.push({
-			io: n + 1,
-			lo: width / 2 - sp,
-			sz: 0
-		});
-
-		const k = [];
-
-		for (let i = right.length - 1; i >= 1; i--) {
-			k.push({
-				io: -right[i].io,
-				lo: -right[i].lo,
-				sz: right[i].sz
-			});
-		}
-
-		for (const item of right)
-			k.push(item);
-
-		for (let i = 0; i < k.length; i++)
-			k[i].loc = k[i].io * pitch;
-
-		return k;
-	}
-	readonly property int loopMultiplier: 401
-	readonly property real minEdgeWidth: 56
 	required property var panels
-	readonly property real pitch: focalWidth + itemSpacing
-	readonly property int realCount: values.length
 	readonly property var screen: QsWindow.window?.screen
 	required property SearchBar search
-	readonly property real shrinkRatio: 0.63
-	readonly property real tileHeight: focalWidth / 16 * 9
 	readonly property var values: Wallpapers.query(root.search.text.split(" ").slice(1).join(" "))
-	readonly property int virtualCount: realCount > 0 ? realCount * loopMultiplier : 0
 	required property var visibilities
 
-	function contentXForIndex(index) {
-		return index * pitch + pitch / 2 - width / 2;
-	}
-
-	function decrementCurrentIndex() {
-		if (realCount === 0)
-			return;
-
-		goTo(view.currentIndex - 1);
-	}
-
-	function glideTo(dest) {
-		if (Math.abs(dest - view.contentX) < 0.5)
-			return;
-		view.cancelFlick();
-		snapAnim.stop();
-		snapAnim.from = view.contentX;
-		snapAnim.to = dest;
-		snapAnim.start();
-	}
-
-	function goTo(virtualIndex) {
-		glideTo(contentXForIndex(virtualIndex));
-	}
-
-	function incrementCurrentIndex() {
-		if (realCount === 0)
-			return;
-
-		goTo(view.currentIndex + 1);
-	}
-
-	function indexForContentX(x) {
-		return Math.round((x + width / 2 - pitch / 2) / pitch);
-	}
-
-	function realIndexOf(virtualIndex) {
-		if (realCount === 0)
-			return -1;
-		return ((virtualIndex % realCount) + realCount) % realCount;
-	}
-
-	function sample(childLoc) {
-		const k = keylines;
-
-		if (childLoc <= k[0].loc)
-			return {
-				c: k[0].lo,
-				s: 0
-			};
-
-		if (childLoc >= k[k.length - 1].loc)
-			return {
-				c: k[k.length - 1].lo,
-				s: 0
-			};
-
-		for (let i = 0; i < k.length - 1; i++) {
-			const a = k[i];
-			const b = k[i + 1];
-
-			if (childLoc > b.loc)
-				continue;
-
-			const span = b.loc - a.loc;
-			const t = span > 0 ? (childLoc - a.loc) / span : 0;
-
-			return {
-				c: a.lo + (b.lo - a.lo) * t,
-				s: a.sz + (b.sz - a.sz) * t
-			};
-		}
-
-		return {
-			c: 0,
-			s: 0
-		};
-	}
-
-	function selectReal(realIdx) {
-		if (realCount === 0)
-			return;
-
-		const curBlock = Math.floor(view.currentIndex / realCount);
-		const current = view.currentIndex;
-
-		let target = curBlock * realCount + realIdx;
-
-		if (target - current > realCount / 2)
-			target -= realCount;
-		else if (current - target > realCount / 2)
-			target += realCount;
-
-		goTo(target);
-	}
-
-	function snapTarget(x) {
-		return contentXForIndex(indexForContentX(x));
-	}
-
-	function snapToNearest() {
-		glideTo(snapTarget(view.contentX));
-	}
-
+	// Forwarded verbatim as a property of the same name onto every delegate
+	// instance (the delegate declares `required property PersistentProperties visibilities`).
+	delegateProperties: ({
+			visibilities: root.visibilities
+		})
+	focalWidth: Config.launcher.sizes.wallpaperWidth
+	glideDuration: 250
+	glideEasingType: Easing.OutCubic
 	implicitHeight: tileHeight + Tokens.spacing.small / 2 + Tokens.padding.large + Tokens.padding.normal
-	implicitWidth: {
+	itemSpacing: Tokens.spacing.small
+	maxWidth: {
 		if (!screen)
 			return 0;
-
 		const barMargins = Config.bar.border * 2;
 		let margins = 0;
 		if (visibilities.utilities || visibilities.sidebar)
 			margins = panels.utilities.implicitWidth;
-		const maxWidth = screen.width - (barMargins + margins) * 2 - Config.bar.rounding * 4;
-
-		return maxWidth;
+		return screen.width - (barMargins + margins) * 2 - Config.bar.rounding * 4;
+	}
+	minEdgeWidth: 56
+	model: values
+	tileHeight: focalWidth / 16 * 9
+
+	delegate: Component {
+		WallpaperTile {
+		}   // your existing delegate file, unchanged
 	}
-	width: implicitWidth
 
 	Component.onCompleted: {
 		const idx = Wallpapers.list.findIndex(w => w.path === Wallpapers.actualCurrent);
-
 		if (idx >= 0)
-			view.contentX = contentXForIndex(centerBlockStart + idx);
+			jumpToIndex(idx);
 	}
 	Component.onDestruction: Wallpapers.stopPreview()
-
-	ListView {
-		id: view
-
-		anchors.fill: parent
-		boundsBehavior: Flickable.StopAtBounds
-		cacheBuffer: root.width
-		clip: false
-		currentIndex: root.centerBlockStart
-		displayMarginBeginning: root.arrangement.effectiveExtraWidth
-		displayMarginEnd: root.arrangement.effectiveExtraWidth
-		interactive: true
-		model: root.virtualCount
-		orientation: ListView.Horizontal
-		snapMode: ListView.NoSnap
-
-		Anim on contentX {
-			id: snapAnim
-
-			running: false
-			type: Anim.Standard
-		}
-		delegate: Item {
-			id: slot
-
-			readonly property real childLoc: index * root.pitch + root.pitch / 2 - view.contentX - view.width / 2
-			required property int index
-			readonly property bool isCurrent: index === view.currentIndex
-			readonly property var keyline: root.sample(childLoc)
-			readonly property var modelData: realIdx >= 0 ? root.values[realIdx] : null
-			readonly property int realIdx: root.realIndexOf(index)
-			readonly property real tileWidth: keyline.s
-
-			height: view.height
-			visible: modelData !== null
-			width: root.pitch
-
-			WallpaperTile {
-				anchors.verticalCenter: parent.verticalCenter
-				isCurrent: slot.isCurrent
-				modelData: slot.modelData
-				tileHeight: root.tileHeight
-				tileWidth: slot.tileWidth
-				visibilities: root.visibilities
-				x: (slot.keyline.c - slot.childLoc) + (slot.width - width) / 2
-
-				onRequestActivate: {
-					if (slot.isCurrent) {
-						Wallpapers.setWallpaper(slot.modelData.path);
-						root.visibilities.launcher = false;
-					} else {
-						root.goTo(slot.index);
-					}
-				}
-			}
-		}
-
-		onContentXChanged: {
-			if (root.realCount === 0)
-				return;
-			const blockWidth = root.realCount * root.pitch;
-			const centerX = root.contentXForIndex(root.centerBlockStart);
-			const blocksFromCenter = Math.round((contentX - centerX) / blockWidth);
-			if (Math.abs(blocksFromCenter) >= 2) {
-				const shift = blocksFromCenter * blockWidth;
-
-				contentX -= shift;
-
-				if (snapAnim.running)
-					snapAnim.to -= shift;
-			}
-			currentIndex = Math.round((contentX + width / 2 - root.pitch / 2) / root.pitch);
-		}
-		onCurrentIndexChanged: {
-			const realIdx = root.realIndexOf(currentIndex);
-			if (realIdx >= 0)
-				Wallpapers.preview(root.values[realIdx].path);
-		}
-		onFlickEnded: root.snapToNearest()
-		onMovementEnded: root.snapToNearest()
+	onPreviewIndexChanged: (realIndex, modelData) => {
+		Wallpapers.preview(modelData.path);
 	}
 }

Modules/Launcher/Items/WallpaperTile.qml

@@ -14,8 +14,6 @@ Item {
 	required property real tileWidth
 	required property PersistentProperties visibilities
 
-	// Emitted on click: caller decides whether that means "activate" (if
-	// already current) or "bring to center" (if not) - see CarouselView.
 	signal requestActivate
 
 	implicitHeight: tileHeight + Tokens.padding.large * 2
@@ -31,13 +29,6 @@ Item {
 		radius: Tokens.rounding.small
 		y: Tokens.padding.large
 
-		Behavior on implicitWidth {
-			enabled: !root.visibilities.launcher // avoid fighting drag-driven updates
-
-			Anim {
-			}
-		}
-
 		MaterialIcon {
 			anchors.centerIn: parent
 			color: Colors.tPalette.m3outline

Modules/Wallpaper/WallBackground.qml

@@ -5,103 +5,46 @@ import Quickshell.Hyprland
 import QtQuick
 import qs.Components
 import qs.Helpers
-import ZShell.Config
 import ZShell.Internal
 
 Item {
 	id: root
 
-	property bool completed
-	property real cropHeight: displayData?.height ?? 1.0
-	property real cropWidth: displayData?.width ?? 1.0
-	property real cropX: displayData?.x ?? 0.0
-	property real cropY: displayData?.y ?? 0.0
-	property WallpaperImage current
 	readonly property var displayData: Wallpapers.getCrop(screen.name)
 	required property ShellScreen screen
 	property size screenResolution: Qt.size(screen.width * screenScale, screen.height * screenScale)
 	property real screenScale: Hyprland.monitorFor(screen).scale
-	property string source: Wallpapers.current
 
 	anchors.fill: parent
 
-	Component.onCompleted: {
-		Hyprland.refreshMonitors();
+	Component.onCompleted: Hyprland.refreshMonitors()
 
-		if (source)
-			Qt.callLater(() => {
-				current = imgComp.createObject(this, {
-					source
-				});
-				completed = true;
-			});
-	}
-	onSourceChanged: {
-		if (!source)
-			current = null;
-		else
-			current = imgComp.createObject(this, {
-				source: source
-			});
-	}
+	WallpaperImage {
+		id: img
 
-	Component {
-		id: imgComp
+		anchors.fill: parent
+		cropHeight: root.displayData?.height ?? 1.0
+		cropWidth: root.displayData?.width ?? 1.0
+		cropX: root.displayData?.x ?? 0.0
+		cropY: root.displayData?.y ?? 0.0
+		fadeDuration: 150
+		screenResolution: root.screenResolution
+		source: Wallpapers.current
 
-		WallpaperImage {
-			id: img
-
-			anchors.fill: parent
-			cropHeight: root.cropHeight
-			cropWidth: root.cropWidth
-			cropX: root.cropX
-			cropY: root.cropY
-			opacity: 0
-			screenResolution: root.screenResolution
-			source: root.source
-
-			Behavior on cropHeight {
-				Anim {
-					id: heightAnim
-				}
+		Behavior on cropHeight {
+			Anim {
 			}
-			Behavior on cropWidth {
-				Anim {
-					id: widthAnim
-				}
+		}
+		Behavior on cropWidth {
+			Anim {
 			}
-			Behavior on cropX {
-				Anim {
-					id: xAnim
-				}
+		}
+		Behavior on cropX {
+			Anim {
 			}
-			Behavior on cropY {
-				Anim {
-					id: yAnim
-				}
-			}
-			Anim on opacity {
-				id: anim
-
-				from: 0
-				running: false
-				to: 1
-				type: Anim.SlowEffects
-			}
-
-			onStatusChanged: {
-				if (status === Image.Ready) {
-					anim.start();
-				}
-			}
-
-			Timer {
-				id: destroyTimer
-
-				interval: anim.duration * 2
-				running: root.current !== img && root.current?.status === Image.Ready
-
-				onTriggered: Qt.callLater(() => img.destroy())
+		}
+		Behavior on cropY {
+			Anim {
 			}
 		}
 	}

Plugins/ZShell/Components/CMakeLists.txt

@@ -4,6 +4,7 @@ qml_module(ZShell-components
         lazylistview.hpp lazylistview.cpp
 		wavyline.hpp wavyline.cpp
 		buttonrow.hpp buttonrow.cpp
+		carouselview.hpp carouselview.cpp
     LIBRARIES
         Qt::Quick
 )

Plugins/ZShell/Components/carouselview.cpp

@@ -0,0 +1,785 @@
+#include "carouselview.hpp"
+
+#include <QQmlContext>
+#include <QQmlProperty>
+#include <QMouseEvent>
+#include <QWheelEvent>
+#include <QGuiApplication>
+#include <QStyleHints>
+#include <cmath>
+
+namespace ZShell::components {
+
+namespace {
+constexpr qreal kDragThreshold = 4.0;	  // px before a press becomes a drag
+constexpr qreal kFlickFriction = 0.0022;  // px/ms^2 deceleration
+constexpr qreal kMinFlickVelocity = 60.0; // px/sec below which we just snap
+constexpr qreal kMaxFlickVelocity = 6000.0;
+} // namespace
+
+CarouselView::CarouselView(QQuickItem* parent) : QQuickItem(parent) {
+	setAcceptedMouseButtons(Qt::LeftButton);
+	setFlag(QQuickItem::ItemHasContents, false);
+	setClip(false);
+
+	m_glideAnim = new QVariantAnimation(this);
+	m_glideAnim->setEasingCurve(m_glideEasingType);
+	connect(
+		m_glideAnim,
+		&QVariantAnimation::valueChanged,
+		this,
+		[this](const QVariant& v) {
+			m_contentX = v.toReal();
+			wrapContentIfNeeded();
+			updateCurrentIndexFromContentX(true);
+			relayout();
+		});
+	connect(m_glideAnim, &QVariantAnimation::finished, this, [this]() {
+		updateCurrentIndexFromContentX(true);
+	});
+
+	m_flickAnim = new QVariantAnimation(this);
+	m_flickAnim->setEasingCurve(QEasingCurve::Linear);
+	connect(
+		m_flickAnim,
+		&QVariantAnimation::valueChanged,
+		this,
+		[this](const QVariant& v) {
+			m_contentX = v.toReal();
+			wrapContentIfNeeded();
+			updateCurrentIndexFromContentX(true);
+			relayout();
+		});
+	connect(m_flickAnim, &QVariantAnimation::finished, this, [this]() {
+		snapToNearest();
+	});
+}
+
+CarouselView::~CarouselView() {
+	releaseAllItems();
+}
+
+// ---------------------------------------------------------------- properties
+
+void CarouselView::setDelegate(QQmlComponent* c) {
+	if (m_delegate == c) return;
+	m_delegate = c;
+	releaseAllItems();
+	emit delegateChanged();
+	relayout();
+}
+
+void CarouselView::setModel(const QVariantList& m) {
+	m_model = m;
+	emit modelChanged();
+
+	// Re-anchor on the currently selected path if possible, otherwise clamp.
+	int newCount = m_model.size();
+	if (newCount == 0) {
+		m_currentRealIndex = -1;
+		releaseAllItems();
+		rebuildArrangement();
+		return;
+	}
+	if (!m_initializedLayout) {
+		m_centerBlockStart = (kLoopMultiplier / 2) * newCount;
+		m_currentVirtualIndex = m_centerBlockStart;
+		m_contentX = contentXForIndex(m_currentVirtualIndex);
+		m_currentRealIndex = realIndexOf(m_currentVirtualIndex);
+		m_previewRealIndex = m_currentRealIndex;
+		m_initializedLayout = true;
+		rebuildArrangement();
+		relayout();
+		return;
+	}
+
+	// Model contents changed under us (e.g. search text filtered the list).
+	// Re-anchor instantly on the clamped selection -- no glide, since this
+	// isn't a user-initiated navigation.
+	rebuildArrangement();
+	centerInstantlyOnReal(qBound(0, m_currentRealIndex, newCount - 1));
+}
+
+void CarouselView::setFocalWidth(qreal v) {
+	if (qFuzzyCompare(m_focalWidth, v)) return;
+	m_focalWidth = v;
+	emit focalWidthChanged();
+	rebuildArrangement();
+	relayout();
+}
+
+void CarouselView::setMinEdgeWidth(qreal v) {
+	if (qFuzzyCompare(m_minEdgeWidth, v)) return;
+	m_minEdgeWidth = v;
+	emit minEdgeWidthChanged();
+	rebuildArrangement();
+	relayout();
+}
+
+void CarouselView::setItemSpacing(qreal v) {
+	if (qFuzzyCompare(m_itemSpacing, v)) return;
+	m_itemSpacing = v;
+	emit itemSpacingChanged();
+	rebuildArrangement();
+	relayout();
+}
+
+void CarouselView::setTileHeight(qreal v) {
+	if (qFuzzyCompare(m_tileHeight, v)) return;
+	m_tileHeight = v;
+	emit tileHeightChanged();
+	for (const Slot& s : std::as_const(m_slots)) {
+		if (s.active && s.item)
+			QQmlProperty::write(
+				s.item, QStringLiteral("tileHeight"), m_tileHeight);
+	}
+}
+
+void CarouselView::setMaxWidth(qreal v) {
+	if (qFuzzyCompare(m_maxWidth, v)) return;
+	m_maxWidth = v;
+	emit maxWidthChanged();
+	rebuildArrangement();
+	relayout();
+}
+
+void CarouselView::setGlideDuration(int v) {
+	if (m_glideDuration == v) return;
+	m_glideDuration = v;
+	emit glideDurationChanged();
+}
+
+void CarouselView::setGlideEasingType(QEasingCurve::Type t) {
+	if (m_glideEasingType == t) return;
+	m_glideEasingType = t;
+	m_glideAnim->setEasingCurve(t);
+	emit glideEasingTypeChanged();
+}
+
+void CarouselView::setDelegateProperties(const QVariantMap& v) {
+	m_delegateProperties = v;
+	emit delegatePropertiesChanged();
+	for (const Slot& s : std::as_const(m_slots)) {
+		if (s.active && s.item) {
+			for (auto it = m_delegateProperties.constBegin();
+				 it != m_delegateProperties.constEnd();
+				 ++it)
+				QQmlProperty::write(s.item, it.key(), it.value());
+		}
+	}
+}
+
+void CarouselView::setCurrentIndex(int idx) {
+	goToIndex(idx);
+}
+
+// ---------------------------------------------------------------- geometry
+
+void CarouselView::geometryChange(const QRectF& newGeo, const QRectF& oldGeo) {
+	QQuickItem::geometryChange(newGeo, oldGeo);
+	if (!qFuzzyCompare(newGeo.width(), oldGeo.width()) ||
+		!qFuzzyCompare(newGeo.height(), oldGeo.height())) {
+		// Recentre on the same virtual index rather than letting contentX
+		// drift, exactly like the QML version's onWidthChanged handler --
+		// but here it happens in the same pass as the arrangement rebuild,
+		// so x/width for every slot are recomputed together.
+		rebuildArrangement();
+		if (m_initializedLayout)
+			m_contentX = contentXForIndex(m_currentVirtualIndex);
+		relayout();
+	}
+}
+
+// ---------------------------------------------------------------- arrangement math
+// Direct port of the QML `arrangement` computed property + keylineCenter/
+// keylineSize/sampleCenter/sampleSize helpers. Kept numerically identical on
+// purpose so behaviour doesn't change, just *when* it's applied.
+
+void CarouselView::rebuildArrangement() {
+	Arrangement& a = m_arrangement;
+	a = Arrangement{};
+
+	// IMPORTANT: this must be the external constraint (m_maxWidth), never
+	// width() -- width() is a *result* of this computation (see below), and
+	// using it here would make the arrangement depend on its own previous
+	// output. On first layout, before width() has ever been set, that
+	// bootstraps to W==0 -> n==0 -> every side item falls back to a flat
+	// minEdgeWidth with no taper at all, which is what caused items to slide
+	// off looking "pushed out" instead of shrinking.
+	const qreal W = m_maxWidth;
+	const qreal F = m_focalWidth;
+	const qreal M = m_minEdgeWidth;
+	const qreal sp = m_itemSpacing;
+
+	if (W <= 0 || F <= 0) {
+		a.sizes = {F};
+		a.centers = {0};
+		return;
+	}
+
+	int bestN = 0;
+	QVector<qreal> bestSizes = {F};
+	qreal bestWidth = F;
+
+	for (int n = 1;; ++n) {
+		const qreal ratio = std::pow(M / F, 1.0 / n);
+		QVector<qreal> sizes = {F};
+		qreal sideWidth = 0;
+
+		for (int i = 1; i <= n; ++i) {
+			const qreal size = (i == n) ? M : F * std::pow(ratio, i);
+			sizes.push_back(size);
+			sideWidth += size;
+		}
+
+		const qreal requiredWidth = F + 2 * n * sp + 2 * sideWidth;
+		if (requiredWidth > W) break;
+
+		bestN = n;
+		bestSizes = sizes;
+		bestWidth = requiredWidth;
+
+		// Safety valve: arrangement size is bounded by how many halvings fit,
+		// this just guards against pathological inputs (F <= M etc).
+		if (n > 64) break;
+	}
+
+	a.n = bestN;
+	a.sizes = bestSizes;
+	a.width = bestWidth;
+
+	QVector<qreal> centers = {0};
+	qreal center = 0;
+	for (int i = 1; i <= bestN; ++i) {
+		center += bestSizes[i - 1] / 2.0 + sp + bestSizes[i] / 2.0;
+		centers.push_back(center);
+	}
+	a.centers = centers;
+
+	qreal extra = 0;
+	for (int i = 1; i <= bestN; ++i)
+		extra += pitch() - bestSizes[i];
+	a.effectiveExtraWidth = extra;
+
+	setImplicitWidth(m_maxWidth);
+	// This mirrors the original `width: arrangement.width` binding. It's
+	// safe against feedback because the arrangement above only ever reads
+	// m_maxWidth, never width() -- so if a.width doesn't change, setWidth()
+	// here is a no-op and geometryChange() won't recurse.
+	setWidth(a.width);
+}
+
+qreal CarouselView::keylineCenter(int io) const {
+	const int n = m_arrangement.n;
+	const int i = std::abs(io);
+	if (i == 0) return 0;
+	const int sign = io < 0 ? -1 : 1;
+
+	if (i <= n) return sign * m_arrangement.centers[i];
+
+	if (i == n + 1) {
+		const qreal lastCenter = m_arrangement.centers[n];
+		const qreal lastSize = m_arrangement.sizes[n];
+		return sign * (lastCenter + lastSize / 2.0 + m_itemSpacing +
+					   m_minEdgeWidth / 2.0);
+	}
+
+	const qreal outgoingCenter = std::abs(keylineCenter(sign * (n + 1)));
+	return sign * (outgoingCenter + m_minEdgeWidth / 2.0 + m_itemSpacing);
+}
+
+qreal CarouselView::keylineSize(int io) const {
+	const int n = m_arrangement.n;
+	const int i = std::abs(io);
+	if (i == 0) return m_focalWidth;
+	if (i <= n) return m_arrangement.sizes[i];
+	if (i == n + 1) return m_minEdgeWidth;
+	return 0;
+}
+
+qreal CarouselView::sampleCenter(qreal childLoc) const {
+	const int n = m_arrangement.n;
+	if (n <= 0) return 0;
+
+	const int minIo = -(n + 2);
+	const int maxIo = n + 2;
+	const qreal p = pitch();
+
+	const int a = static_cast<int>(std::floor(childLoc / p));
+	if (a < minIo) return keylineCenter(minIo);
+	if (a >= maxIo) return keylineCenter(maxIo);
+
+	const int b = a + 1;
+	const qreal t = (childLoc - a * p) / p;
+	return keylineCenter(a) + (keylineCenter(b) - keylineCenter(a)) * t;
+}
+
+qreal CarouselView::sampleSize(qreal childLoc) const {
+	const int n = m_arrangement.n;
+	if (n <= 0) return 0;
+
+	const int minIo = -(n + 2);
+	const int maxIo = n + 2;
+	const qreal p = pitch();
+
+	const int a = static_cast<int>(std::floor(childLoc / p));
+	if (a < minIo) return keylineSize(minIo);
+	if (a >= maxIo) return keylineSize(maxIo);
+
+	const int b = a + 1;
+	const qreal t = (childLoc - a * p) / p;
+	return keylineSize(a) + (keylineSize(b) - keylineSize(a)) * t;
+}
+
+// ---------------------------------------------------------------- index math
+
+int CarouselView::realIndexOf(int virtualIndex) const {
+	const int count = m_model.size();
+	if (count == 0) return -1;
+	return ((virtualIndex % count) + count) % count;
+}
+
+qreal CarouselView::contentXForIndex(qreal index) const {
+	return index * pitch() + pitch() / 2.0 - width() / 2.0;
+}
+
+int CarouselView::indexForContentX(qreal x) const {
+	return static_cast<int>(
+		std::round((x + width() / 2.0 - pitch() / 2.0) / pitch()));
+}
+
+qreal CarouselView::snapTargetX(qreal x) const {
+	return contentXForIndex(indexForContentX(x));
+}
+
+void CarouselView::wrapContentIfNeeded() {
+	const int count = m_model.size();
+	if (count == 0) return;
+
+	const qreal blockWidth = count * pitch();
+	const qreal centerX = contentXForIndex(m_centerBlockStart);
+	const int blocksFromCenter =
+		static_cast<int>(std::round((m_contentX - centerX) / blockWidth));
+
+	if (std::abs(blocksFromCenter) >= 2) {
+		const qreal shift = blocksFromCenter * blockWidth;
+		m_contentX -= shift;
+
+		if (m_glideAnim->state() == QAbstractAnimation::Running) {
+			const qreal newEnd = m_glideAnim->endValue().toReal() - shift;
+			m_glideAnim->setEndValue(newEnd);
+		}
+		if (m_flickAnim->state() == QAbstractAnimation::Running) {
+			const qreal newEnd = m_flickAnim->endValue().toReal() - shift;
+			m_flickAnim->setEndValue(newEnd);
+		}
+		// Also shift every currently-live slot's virtual index bookkeeping so
+		// it doesn't think it needs to be recycled just because of the wrap.
+		const int indexShift = static_cast<int>(std::round(shift / pitch()));
+		for (Slot& s : m_slots) {
+			if (s.active) s.virtualIndex -= indexShift;
+		}
+	}
+}
+
+void CarouselView::updateCurrentIndexFromContentX(bool emitPreview) {
+	const int count = m_model.size();
+	if (count == 0) return;
+
+	const int newVirtual = static_cast<int>(
+		std::round((m_contentX + width() / 2.0 - pitch() / 2.0) / pitch()));
+	if (newVirtual == m_currentVirtualIndex) return;
+
+	m_currentVirtualIndex = newVirtual;
+	const int newReal = realIndexOf(newVirtual);
+
+	if (newReal != m_currentRealIndex) {
+		m_currentRealIndex = newReal;
+		emit currentIndexChanged();
+	}
+	if (emitPreview && newReal != m_previewRealIndex) {
+		m_previewRealIndex = newReal;
+		if (newReal >= 0)
+			emit previewIndexChanged(newReal, m_model.at(newReal));
+	}
+}
+
+// ---------------------------------------------------------------- pool / delegates
+
+QQuickItem* CarouselView::acquireItem() {
+	if (!m_delegate) return nullptr;
+
+	QQmlContext* ctx = QQmlEngine::contextForObject(this);
+	QVariantMap initial;
+	initial.insert(QStringLiteral("isCurrent"), false);
+	initial.insert(QStringLiteral("modelData"), QVariant());
+	initial.insert(QStringLiteral("tileHeight"), m_tileHeight);
+	initial.insert(QStringLiteral("tileWidth"), m_focalWidth);
+	for (auto it = m_delegateProperties.constBegin();
+		 it != m_delegateProperties.constEnd();
+		 ++it)
+		initial.insert(it.key(), it.value());
+
+	QObject* obj = m_delegate->createWithInitialProperties(initial, ctx);
+	if (!obj) {
+		qWarning(
+			"CarouselView: failed to create delegate instance: %s",
+			qPrintable(m_delegate->errorString()));
+		return nullptr;
+	}
+	QQuickItem* item = qobject_cast<QQuickItem*>(obj);
+	if (!item) {
+		qWarning("CarouselView: delegate root is not an Item");
+		delete obj;
+		return nullptr;
+	}
+
+	item->setParentItem(this);
+	QQmlEngine::setObjectOwnership(item, QQmlEngine::CppOwnership);
+
+	const QMetaMethod activateSignal = item->metaObject()->method(
+		item->metaObject()->indexOfSignal("requestActivate()"));
+	if (activateSignal.isValid()) {
+		static const QMetaMethod slot = metaObject()->method(
+			metaObject()->indexOfSlot("handleDelegateActivate()"));
+		connect(item, activateSignal, this, slot);
+	}
+
+	return item;
+}
+
+void CarouselView::applyPropertiesToItem(QQuickItem* item, int realIndex) const {
+	if (!item) return;
+	const bool isCurrent = (realIndex == m_currentRealIndex);
+	QQmlProperty::write(item, QStringLiteral("isCurrent"), isCurrent);
+	QQmlProperty::write(
+		item,
+		QStringLiteral("modelData"),
+		realIndex >= 0 && realIndex < m_model.size() ? m_model.at(realIndex)
+													 : QVariant());
+	QQmlProperty::write(item, QStringLiteral("tileHeight"), m_tileHeight);
+}
+
+void CarouselView::updateSlotContent(Slot& slot, int virtualIndex) {
+	if (!slot.item) slot.item = acquireItem();
+	if (!slot.item) return;
+
+	slot.virtualIndex = virtualIndex;
+	slot.realIndex = realIndexOf(virtualIndex);
+	slot.active = slot.realIndex >= 0;
+	slot.item->setVisible(slot.active);
+	if (slot.active) applyPropertiesToItem(slot.item, slot.realIndex);
+}
+
+void CarouselView::positionSlot(const Slot& slot) const {
+	if (!slot.item || !slot.active) return;
+
+	const qreal childLoc = slot.virtualIndex * pitch() + pitch() / 2.0 -
+						   m_contentX - width() / 2.0;
+	const qreal center = sampleCenter(childLoc);
+	const qreal size = sampleSize(childLoc);
+
+	// slot's "column" spans one pitch, centred at width()/2 + center; item is
+	// centred within that column, matching the QML delegate's x expression.
+	const qreal slotX = childLoc + width() / 2.0 - pitch() / 2.0;
+	const qreal itemX = (center - childLoc) + (pitch() - size) / 2.0 + slotX;
+
+	QQmlProperty::write(slot.item, QStringLiteral("tileWidth"), size);
+	slot.item->setX(itemX);
+	slot.item->setY(0);
+	slot.item->setVisible(size > 0.5);
+}
+
+void CarouselView::releaseAllItems() {
+	for (Slot& s : m_slots) {
+		if (s.item) s.item->deleteLater();
+	}
+	m_slots.clear();
+}
+
+// ---------------------------------------------------------------- layout pass
+
+void CarouselView::relayout() {
+	const int count = m_model.size();
+	if (count == 0 || width() <= 0 || m_focalWidth <= 0) {
+		for (Slot& s : m_slots)
+			if (s.item) s.item->setVisible(false);
+		return;
+	}
+
+	const int n = m_arrangement.n;
+	// Window of virtual indices that can ever be visible, plus a small buffer
+	// so items don't pop in/out right at the edge during a fast flick.
+	const int half = n + 3;
+	const int lo = m_currentVirtualIndex - half;
+	const int hi = m_currentVirtualIndex + half;
+	const int needed = hi - lo + 1;
+
+	// Grow the pool if needed (shrinking is unnecessary: idle items are just
+	// marked inactive/invisible, which is cheap and avoids churn).
+	while (m_slots.size() < needed)
+		m_slots.append(Slot{});
+
+	// Figure out which virtual indices are already backed by a slot.
+	QHash<int, int> virtualToSlot; // virtualIndex -> slot list position
+	virtualToSlot.reserve(m_slots.size());
+	for (int i = 0; i < m_slots.size(); ++i) {
+		if (m_slots[i].active) virtualToSlot.insert(m_slots[i].virtualIndex, i);
+	}
+
+	QVector<bool> slotUsedThisPass(m_slots.size(), false);
+
+	for (int v = lo; v <= hi; ++v) {
+		auto it = virtualToSlot.find(v);
+		if (it != virtualToSlot.end()) {
+			slotUsedThisPass[it.value()] = true;
+			// Content (isCurrent / modelData) may still need refreshing if
+			// currentRealIndex changed since last pass.
+			applyPropertiesToItem(
+				m_slots[it.value()].item, m_slots[it.value()].realIndex);
+			continue;
+		}
+
+		// find a free slot: one not used this pass and not already at a
+		// virtual index inside [lo, hi] (those are all still needed).
+		int freeSlot = -1;
+		for (int i = 0; i < m_slots.size(); ++i) {
+			if (slotUsedThisPass[i]) continue;
+			if (m_slots[i].active && m_slots[i].virtualIndex >= lo &&
+				m_slots[i].virtualIndex <= hi)
+				continue;
+			freeSlot = i;
+			break;
+		}
+		if (freeSlot < 0) {
+			// Shouldn't happen given the pool growth above, but guard anyway.
+			m_slots.append(Slot{});
+			slotUsedThisPass.append(false);
+			freeSlot = m_slots.size() - 1;
+		}
+
+		updateSlotContent(m_slots[freeSlot], v);
+		slotUsedThisPass[freeSlot] = true;
+	}
+
+	for (int i = 0; i < m_slots.size(); ++i) {
+		if (!slotUsedThisPass[i] && m_slots[i].item) {
+			m_slots[i].active = false;
+			m_slots[i].item->setVisible(false);
+		}
+	}
+
+	for (const Slot& s : std::as_const(m_slots))
+		positionSlot(s);
+}
+
+// ---------------------------------------------------------------- animation
+
+void CarouselView::cancelAnimations() {
+	if (m_glideAnim->state() == QAbstractAnimation::Running)
+		m_glideAnim->stop();
+	if (m_flickAnim->state() == QAbstractAnimation::Running)
+		m_flickAnim->stop();
+}
+
+void CarouselView::glideTo(qreal dest) {
+	if (std::abs(dest - m_contentX) < 0.5) return;
+
+	cancelAnimations();
+	m_glideAnim->setDuration(m_glideDuration);
+	m_glideAnim->setStartValue(m_contentX);
+	m_glideAnim->setEndValue(dest);
+	m_glideAnim->start();
+}
+
+void CarouselView::snapToNearest() {
+	glideTo(snapTargetX(m_contentX));
+}
+
+// ---------------------------------------------------------------- public API
+
+void CarouselView::goToIndex(int realIndex) {
+	const int count = m_model.size();
+	if (count == 0) return;
+	realIndex = qBound(0, realIndex, count - 1);
+
+	const int curBlock =
+		static_cast<int>(std::floor(qreal(m_currentVirtualIndex) / count));
+	const int current = m_currentVirtualIndex;
+	int target = curBlock * count + realIndex;
+
+	if (target - current > count / 2)
+		target -= count;
+	else if (current - target > count / 2)
+		target += count;
+
+	glideTo(contentXForIndex(target));
+}
+
+void CarouselView::incrementCurrentIndex() {
+	if (m_model.isEmpty()) return;
+	glideTo(contentXForIndex(m_currentVirtualIndex + 1));
+}
+
+void CarouselView::decrementCurrentIndex() {
+	if (m_model.isEmpty()) return;
+	glideTo(contentXForIndex(m_currentVirtualIndex - 1));
+}
+
+void CarouselView::jumpToIndex(int realIndex) {
+	centerInstantlyOnReal(realIndex);
+}
+
+void CarouselView::centerInstantlyOnReal(int realIndex) {
+	const int count = m_model.size();
+	if (count == 0) return;
+	realIndex = qBound(0, realIndex, count - 1);
+
+	cancelAnimations();
+
+	const int curBlock =
+		static_cast<int>(std::floor(qreal(m_currentVirtualIndex) / count));
+	const int current = m_currentVirtualIndex;
+	int target = curBlock * count + realIndex;
+
+	if (target - current > count / 2)
+		target -= count;
+	else if (current - target > count / 2)
+		target += count;
+
+	m_currentVirtualIndex = target;
+	m_contentX = contentXForIndex(target);
+
+	const bool changed = (realIndex != m_currentRealIndex);
+	m_currentRealIndex = realIndex;
+	m_previewRealIndex = realIndex;
+	if (changed) emit currentIndexChanged();
+	emit previewIndexChanged(realIndex, m_model.at(realIndex));
+
+	relayout();
+}
+
+// ---------------------------------------------------------------- input
+
+void CarouselView::mousePressEvent(QMouseEvent* event) {
+	// Deliberately do NOT cancel animations here. A press that turns out to
+	// be a plain tap (never crosses the drag threshold) should leave any
+	// in-flight glide/flick completely untouched. We only touch the
+	// animation once we know it's actually a drag (see mouseMoveEvent).
+	m_dragging = true;
+	m_dragActive = false;
+	m_pressPos = event->position();
+	// Capture wherever contentX currently is, even mid-animation -- if this
+	// does turn into a drag, it should pick up smoothly from the visual
+	// position, not teleport to some rest position first.
+	m_pressContentX = m_contentX;
+	m_dragTimer.start();
+	m_lastMoveX = event->position().x();
+	m_lastMoveT = 0;
+	m_velocity = 0;
+	event->accept();
+}
+
+void CarouselView::mouseMoveEvent(QMouseEvent* event) {
+	if (!m_dragging) return;
+
+	const qreal dx = event->position().x() - m_pressPos.x();
+	if (!m_dragActive && std::abs(dx) > kDragThreshold) {
+		m_dragActive = true;
+		m_pressContentX =
+			m_contentX; // re-anchor to the live (possibly mid-animation) value
+		cancelAnimations();
+		grabMouse();
+	}
+	if (!m_dragActive) return;
+
+	m_contentX = m_pressContentX - dx;
+	wrapContentIfNeeded();
+	updateCurrentIndexFromContentX(true);
+	relayout();
+
+	const qint64 t = m_dragTimer.elapsed();
+	const qint64 dt = t - m_lastMoveT;
+	if (dt > 0) {
+		const qreal instVel =
+			(m_lastMoveX - event->position().x()) / (dt / 1000.0);
+		// Light smoothing so a single jittery sample doesn't dominate the flick.
+		m_velocity = m_velocity * 0.7 + instVel * 0.3;
+	}
+	m_lastMoveX = event->position().x();
+	m_lastMoveT = t;
+
+	event->accept();
+}
+
+void CarouselView::mouseReleaseEvent(QMouseEvent* event) {
+	if (!m_dragging) return;
+	m_dragging = false;
+	ungrabMouse();
+
+	if (!m_dragActive) {
+		// A plain click/tap with no drag: let it fall through to the
+		// delegate's own StateLayer/MouseArea via requestActivate().
+		event->accept();
+		return;
+	}
+	m_dragActive = false;
+
+	qreal v = qBound(-kMaxFlickVelocity, m_velocity, kMaxFlickVelocity);
+	if (std::abs(v) < kMinFlickVelocity) {
+		snapToNearest();
+		event->accept();
+		return;
+	}
+
+	// Simple constant-deceleration flick: distance = v^2 / (2*friction).
+	const qreal duration = std::abs(v) / (kFlickFriction * 1000.0); // ms
+	const qreal distance =
+		(v * (duration / 1000.0)) / 2.0; // average-velocity approximation
+	const qreal rawDest = m_contentX + distance;
+	const qreal dest = snapTargetX(rawDest);
+
+	cancelAnimations();
+	m_flickAnim->setDuration(
+		static_cast<int>(qBound<qreal>(120, duration, 900)));
+	m_flickAnim->setEasingCurve(QEasingCurve::OutCubic);
+	m_flickAnim->setStartValue(m_contentX);
+	m_flickAnim->setEndValue(dest);
+	m_flickAnim->start();
+
+	event->accept();
+}
+
+void CarouselView::mouseUngrabEvent() {
+	m_dragging = false;
+	m_dragActive = false;
+}
+
+void CarouselView::wheelEvent(QWheelEvent* event) {
+	const int steps = event->angleDelta().y() / 120;
+	if (steps > 0)
+		decrementCurrentIndex();
+	else if (steps < 0)
+		incrementCurrentIndex();
+	event->accept();
+}
+
+// ---------------------------------------------------------------- delegate signal
+
+void CarouselView::handleDelegateActivate() {
+	QQuickItem* item = qobject_cast<QQuickItem*>(sender());
+	if (!item) return;
+
+	for (const Slot& s : std::as_const(m_slots)) {
+		if (s.item == item && s.active) {
+			if (s.realIndex == m_currentRealIndex) {
+				emit activated(s.realIndex, m_model.at(s.realIndex));
+			} else {
+				goToIndex(s.realIndex);
+			}
+			return;
+		}
+	}
+}
+
+} // namespace ZShell::components

Plugins/ZShell/Components/carouselview.hpp

@@ -0,0 +1,220 @@
+#pragma once
+
+#include <QQuickItem>
+#include <QQmlComponent>
+#include <QQmlEngine>
+#include <QVariantList>
+#include <QVariantAnimation>
+#include <QEasingCurve>
+#include <QElapsedTimer>
+#include <QPointF>
+#include <QVector>
+#include <QList>
+
+namespace ZShell::components {
+
+class CarouselView : public QQuickItem {
+	Q_OBJECT
+	QML_ELEMENT
+
+	Q_PROPERTY(
+		QQmlComponent* delegate READ delegate WRITE setDelegate NOTIFY
+			delegateChanged)
+	Q_PROPERTY(QVariantList model READ model WRITE setModel NOTIFY modelChanged)
+
+	Q_PROPERTY(
+		qreal focalWidth READ focalWidth WRITE setFocalWidth NOTIFY
+			focalWidthChanged)
+	Q_PROPERTY(
+		qreal minEdgeWidth READ minEdgeWidth WRITE setMinEdgeWidth NOTIFY
+			minEdgeWidthChanged)
+	Q_PROPERTY(
+		qreal itemSpacing READ itemSpacing WRITE setItemSpacing NOTIFY
+			itemSpacingChanged)
+	Q_PROPERTY(
+		qreal tileHeight READ tileHeight WRITE setTileHeight NOTIFY
+			tileHeightChanged)
+	Q_PROPERTY(
+		qreal maxWidth READ maxWidth WRITE setMaxWidth NOTIFY maxWidthChanged)
+
+	Q_PROPERTY(
+		int currentIndex READ currentIndex WRITE setCurrentIndex NOTIFY
+			currentIndexChanged)
+	Q_PROPERTY(
+		int glideDuration READ glideDuration WRITE setGlideDuration NOTIFY
+			glideDurationChanged)
+	Q_PROPERTY(
+		QEasingCurve::Type glideEasingType READ glideEasingType WRITE
+			setGlideEasingType NOTIFY glideEasingTypeChanged)
+
+	// Extra properties (e.g. { visibilities: root.visibilities }) forwarded
+	// verbatim onto every delegate instance as a property of the same name.
+	Q_PROPERTY(
+		QVariantMap delegateProperties READ delegateProperties WRITE
+			setDelegateProperties NOTIFY delegatePropertiesChanged)
+
+	public:
+	explicit CarouselView(QQuickItem* parent = nullptr);
+	~CarouselView() override;
+
+	QQmlComponent* delegate() const { return m_delegate; }
+	void setDelegate(QQmlComponent* c);
+
+	QVariantList model() const { return m_model; }
+	void setModel(const QVariantList& m);
+
+	qreal focalWidth() const { return m_focalWidth; }
+	void setFocalWidth(qreal v);
+
+	qreal minEdgeWidth() const { return m_minEdgeWidth; }
+	void setMinEdgeWidth(qreal v);
+
+	qreal itemSpacing() const { return m_itemSpacing; }
+	void setItemSpacing(qreal v);
+
+	qreal tileHeight() const { return m_tileHeight; }
+	void setTileHeight(qreal v);
+
+	qreal maxWidth() const { return m_maxWidth; }
+	void setMaxWidth(qreal v);
+
+	int currentIndex() const { return m_currentRealIndex; }
+	void setCurrentIndex(int idx); // jumps (animated glide) to a real index
+
+	int glideDuration() const { return m_glideDuration; }
+	void setGlideDuration(int v);
+
+	QEasingCurve::Type glideEasingType() const { return m_glideEasingType; }
+	void setGlideEasingType(QEasingCurve::Type t);
+
+	QVariantMap delegateProperties() const { return m_delegateProperties; }
+	void setDelegateProperties(const QVariantMap& v);
+
+	// Animated (glides).
+	Q_INVOKABLE void goToIndex(int realIndex);
+	Q_INVOKABLE void incrementCurrentIndex();
+	Q_INVOKABLE void decrementCurrentIndex();
+
+	// Instant, no animation -- use for initial placement (e.g. restoring the
+	// saved wallpaper on Component.onCompleted) where a glide would be wrong.
+	Q_INVOKABLE void jumpToIndex(int realIndex);
+
+	signals:
+	void delegateChanged();
+	void modelChanged();
+	void focalWidthChanged();
+	void minEdgeWidthChanged();
+	void itemSpacingChanged();
+	void tileHeightChanged();
+	void maxWidthChanged();
+	void currentIndexChanged();
+	void glideDurationChanged();
+	void glideEasingTypeChanged();
+	void delegatePropertiesChanged();
+
+	// Emitted when the currently-centred delegate is clicked while already
+	// centred (i.e. "activate/select this one").
+	void activated(int realIndex, QVariant modelData);
+	// Emitted continuously as the centred item changes, for preview-on-scroll
+	// behaviour (used to drive Wallpapers.preview() from QML).
+	void previewIndexChanged(int realIndex, QVariant modelData);
+
+	protected:
+	void geometryChange(const QRectF& newGeo, const QRectF& oldGeo) override;
+	void mousePressEvent(QMouseEvent* event) override;
+	void mouseMoveEvent(QMouseEvent* event) override;
+	void mouseReleaseEvent(QMouseEvent* event) override;
+	void mouseUngrabEvent() override;
+	void wheelEvent(QWheelEvent* event) override;
+
+	private slots:
+	void handleDelegateActivate();
+
+	private:
+	struct Arrangement {
+		int n = 0;
+		qreal width = 0;
+		QVector<qreal> sizes; // sizes[0] = focal, sizes[i] = i-th side item
+		QVector<qreal>
+			centers; // centers[0] = 0, centers[i] = i-th side centre offset
+		qreal effectiveExtraWidth = 0;
+	};
+
+	struct Slot {
+		QQuickItem* item = nullptr;
+		int virtualIndex =
+			0; // which "virtual" (unbounded) index this slot currently renders
+		int realIndex = -1; // resolved model index, -1 if none / hidden
+		bool active = false;
+	};
+
+	void rebuildArrangement();
+	void relayout(); // recomputes window + positions every slot (one pass)
+	void updateSlotContent(Slot& slot, int virtualIndex);
+	void positionSlot(const Slot& slot) const;
+	void applyPropertiesToItem(QQuickItem* item, int realIndex) const;
+
+	qreal pitch() const { return m_focalWidth + m_itemSpacing; }
+	qreal contentXForIndex(qreal index) const;
+	int indexForContentX(qreal x) const;
+	qreal snapTargetX(qreal x) const;
+	void snapToNearest();
+	void glideTo(qreal dest);
+	void cancelAnimations();
+
+	qreal keylineCenter(int io) const;
+	qreal keylineSize(int io) const;
+	qreal sampleCenter(qreal childLoc) const;
+	qreal sampleSize(qreal childLoc) const;
+
+	int realIndexOf(int virtualIndex) const;
+	void updateCurrentIndexFromContentX(bool emitPreview);
+	void wrapContentIfNeeded();
+	void centerInstantlyOnReal(int realIndex); // no animation, no glide
+
+	QQuickItem* acquireItem();
+	void releaseAllItems();
+
+	QQmlComponent* m_delegate = nullptr;
+	QVariantList m_model;
+	QVariantMap m_delegateProperties;
+
+	qreal m_focalWidth = 0;
+	qreal m_minEdgeWidth = 56;
+	qreal m_itemSpacing = 8;
+	qreal m_tileHeight = 0;
+	qreal m_maxWidth = 0;
+
+	Arrangement m_arrangement;
+
+	qreal m_contentX = 0;
+	int m_currentVirtualIndex = 0;
+	int m_currentRealIndex = -1;
+	int m_previewRealIndex = -1;
+
+	static constexpr int kLoopMultiplier = 401;
+	int m_centerBlockStart = 0;
+
+	QList<Slot>
+		m_slots; // pooled delegate slots, unordered; window recomputed each relayout
+
+	int m_glideDuration = 250;
+	QEasingCurve::Type m_glideEasingType = QEasingCurve::OutCubic;
+	QVariantAnimation* m_glideAnim = nullptr;
+
+	// Drag / flick state
+	bool m_dragging = false;
+	bool m_dragActive = false; // exceeded the drag threshold
+	QPointF m_pressPos;
+	qreal m_pressContentX = 0;
+	QElapsedTimer m_dragTimer;
+	qreal m_lastMoveX = 0;
+	qint64 m_lastMoveT = 0;
+	qreal m_velocity = 0; // px/sec
+	QVariantAnimation* m_flickAnim = nullptr;
+
+	bool m_initializedLayout = false;
+	bool m_relayoutQueued = false;
+};
+
+}; // namespace ZShell::components

Plugins/ZShell/Internal/wallpaperimage.cpp

@@ -4,14 +4,31 @@
 #include <QCryptographicHash>
 #include <QDir>
 #include <QFileInfo>
+#include <QImageReader>
 #include <QtConcurrent>
-#include <QSGImageNode>
 #include <QQuickWindow>
 
 namespace ZShell::internal {
 
+QThreadPool* WallpaperImage::loadPool() {
+	static QThreadPool* pool = [] {
+		auto* p = new QThreadPool();
+		p->setMaxThreadCount(4);
+		return p;
+	}();
+	return pool;
+}
+
 WallpaperImage::WallpaperImage(QQuickItem* parent) : QQuickItem(parent) {
 	setFlag(ItemHasContents, true);
+
+	m_loadDebounceTimer.setSingleShot(true);
+	connect(
+		&m_loadDebounceTimer,
+		&QTimer::timeout,
+		this,
+		&WallpaperImage::beginLoad);
+
 	connect(
 		&m_imageWatcher,
 		&QFutureWatcher<QImage>::finished,
@@ -20,12 +37,15 @@ WallpaperImage::WallpaperImage(QQuickItem* parent) : QQuickItem(parent) {
 }
 
 WallpaperImage::~WallpaperImage() {
+	m_requestGeneration->fetch_add(1, std::memory_order_relaxed);
+	m_imageWatcher.disconnect();
+
 	if (m_texture) delete m_texture;
+	if (m_previousTexture) delete m_previousTexture;
 }
 
 void WallpaperImage::setStatus(const Status s) {
 	if (m_status == s) return;
-
 	m_status = s;
 	emit statusChanged();
 }
@@ -36,14 +56,14 @@ void WallpaperImage::setSource(const QUrl& source) {
 	emit sourceChanged();
 
 	setStatus(Loading);
-	loadImage();
+	m_loadDebounceTimer.start(80);
 }
 
 void WallpaperImage::setScreenResolution(const QSize& screenResolution) {
 	if (m_screenResolution == screenResolution) return;
 	m_screenResolution = screenResolution;
 	emit screenResolutionChanged();
-	loadImage();
+	beginLoad();
 }
 
 void WallpaperImage::setZoom(qreal zoom) {
@@ -53,6 +73,13 @@ void WallpaperImage::setZoom(qreal zoom) {
 	update();
 }
 
+void WallpaperImage::setFadeDuration(int ms) {
+	if (ms < 0) ms = 0;
+	if (m_fadeDuration == ms) return;
+	m_fadeDuration = ms;
+	emit fadeDurationChanged();
+}
+
 void WallpaperImage::setCropX(qreal x) {
 	if (qFuzzyCompare(m_cropX, x)) return;
 	m_cropX = x;
@@ -100,143 +127,227 @@ QString WallpaperImage::getCacheFilePath() const {
 	return cachePath + "/" + hash + ".png";
 }
 
-void WallpaperImage::loadImage() {
+void WallpaperImage::beginLoad() {
 	if (m_source.isEmpty()) {
 		setStatus(Null);
 		return;
 	}
 
+	const quint64 requestId =
+		m_requestGeneration->fetch_add(1, std::memory_order_relaxed) + 1;
+
 	QString cacheFile = getCacheFilePath();
 	QString sourceFile = m_source.isLocalFile() ? m_source.toLocalFile()
 												: m_source.toString();
-
-	if (sourceFile.startsWith("qrc:/")) {
-		sourceFile = sourceFile.mid(3);
-	}
+	if (sourceFile.startsWith("qrc:/")) sourceFile = sourceFile.mid(3);
 
 	QSize targetRes = m_screenResolution;
+	auto generation = m_requestGeneration;
+
+	QFuture<QImage> future = QtConcurrent::run(
+		loadPool(),
+		[sourceFile, cacheFile, targetRes, requestId, generation]() -> QImage {
+			auto stale = [&] {
+				return generation->load(std::memory_order_relaxed) != requestId;
+			};
+
+			if (stale()) return QImage();
 
-	QFuture<QImage> future =
-		QtConcurrent::run([sourceFile, cacheFile, targetRes]() -> QImage {
 			if (!targetRes.isEmpty() && !cacheFile.isEmpty() &&
 				QFileInfo::exists(cacheFile)) {
 				QImage cached(cacheFile);
 				if (!cached.isNull()) return cached;
 			}
 
-			QImage original(sourceFile);
+			if (stale()) return QImage();
+
+			QImage original;
+			QImageReader reader(sourceFile);
+			if (!targetRes.isEmpty() &&
+				reader.supportsOption(QImageIOHandler::Size)) {
+				QSize actual = reader.size();
+				if (actual.isValid() &&
+					(actual.width() > targetRes.width() ||
+					 actual.height() > targetRes.height())) {
+					QSize scaledSize =
+						actual.scaled(targetRes, Qt::KeepAspectRatioByExpanding);
+					reader.setScaledSize(scaledSize);
+				}
+				original = reader.read();
+			} else {
+				original = QImage(sourceFile);
+			}
 			if (original.isNull()) return QImage();
 
-			if (targetRes.isEmpty()) {
-				return original;
-			}
+			if (stale()) return QImage();
 
-			if (original.width() > targetRes.width() ||
-				original.height() > targetRes.height()) {
-				QImage scaled = original.scaled(
-					targetRes,
-					Qt::KeepAspectRatioByExpanding,
-					Qt::SmoothTransformation);
-				if (!cacheFile.isEmpty()) scaled.save(cacheFile, "PNG");
-				return scaled;
-			}
+			if (targetRes.isEmpty()) return original;
 
-			if (!cacheFile.isEmpty()) original.save(cacheFile, "PNG");
-			return original;
+			QImage scaled = (original.width() > targetRes.width() ||
+							 original.height() > targetRes.height())
+								? original.scaled(
+									  targetRes,
+									  Qt::KeepAspectRatioByExpanding,
+									  Qt::SmoothTransformation)
+								: original;
+
+			if (stale()) return scaled;
+
+			if (!cacheFile.isEmpty()) scaled.save(cacheFile, "PNG");
+			return scaled;
 		});
 
 	m_imageWatcher.setFuture(future);
 }
 
 void WallpaperImage::handleImageLoaded() {
-	m_image = m_imageWatcher.result();
+	QImage result = m_imageWatcher.result();
+	if (result.isNull()) {
+		setStatus(Error);
+		return;
+	}
 
-	setStatus(m_image.isNull() ? Error : Ready);
-
-	m_textureDirty = true;
+	m_pendingImage = result;
+	m_hasPending = true;
+	setStatus(Ready);
 	update();
 }
 
-QSGNode* WallpaperImage::updatePaintNode(
-	QSGNode* oldNode, UpdatePaintNodeData*) {
-	auto* node = static_cast<QSGImageNode*>(oldNode);
+QRectF WallpaperImage::computeSourceRect(QSGTexture* texture) const {
+	QSize texSize = texture->textureSize();
 
-	if (m_image.isNull()) {
-		delete node;
-		return nullptr;
+	qreal cW = m_cropWidth / m_zoom;
+	qreal cH = m_cropHeight / m_zoom;
+
+	QRectF reqRect(
+		m_cropX * texSize.width(),
+		m_cropY * texSize.height(),
+		cW * texSize.width(),
+		cH * texSize.height());
+
+	QRectF bounds = boundingRect();
+	if (bounds.isEmpty() || reqRect.isEmpty()) return reqRect;
+
+	qreal targetRatio = bounds.width() / bounds.height();
+	qreal reqRatio = reqRect.width() / reqRect.height();
+
+	QRectF sourceRect = reqRect;
+
+	if (reqRatio > targetRatio) {
+		qreal newWidth = reqRect.height() * targetRatio;
+		qreal xOffset = (reqRect.width() - newWidth) / 2.0;
+		sourceRect.setX(reqRect.x() + xOffset);
+		sourceRect.setWidth(newWidth);
+	} else if (reqRatio < targetRatio) {
+		qreal newHeight = reqRect.width() / targetRatio;
+		qreal yOffset = (reqRect.height() - newHeight) / 2.0;
+		sourceRect.setY(reqRect.y() + yOffset);
+		sourceRect.setHeight(newHeight);
 	}
 
-	if (!node) {
-		node = window()->createImageNode();
-	}
+	return sourceRect;
+}
 
-	if (m_textureDirty) {
-		if (m_texture) delete m_texture;
-		m_texture = window()->createTextureFromImage(
-			m_image, QQuickWindow::TextureHasAlphaChannel);
-		m_textureDirty = false;
-	}
+void WallpaperImage::configureImageNode(
+	QSGImageNode* node, QSGTexture* texture) {
+	node->setTexture(texture);
+	node->setRect(boundingRect());
+	node->setFiltering(QSGTexture::Linear);
 
-	if (m_texture) {
-		node->setTexture(m_texture);
-		node->setRect(boundingRect());
-		node->setFiltering(QSGTexture::Linear);
-
-		qreal cW = m_cropWidth / m_zoom;
-		qreal cH = m_cropHeight / m_zoom;
-
-		QRectF reqRect(
-			m_cropX * m_texture->textureSize().width(),
-			m_cropY * m_texture->textureSize().height(),
-			cW * m_texture->textureSize().width(),
-			cH * m_texture->textureSize().height());
-
-		QRectF bounds = boundingRect();
-		if (bounds.isEmpty() || reqRect.isEmpty()) return node;
-
-		qreal targetRatio = bounds.width() / bounds.height();
-		qreal reqRatio = reqRect.width() / reqRect.height();
-
-		QRectF sourceRect = reqRect;
-
-		if (reqRatio > targetRatio) {
-			qreal newWidth = reqRect.height() * targetRatio;
-			qreal xOffset = (reqRect.width() - newWidth) / 2.0;
-			sourceRect.setX(reqRect.x() + xOffset);
-			sourceRect.setWidth(newWidth);
-		} else if (reqRatio < targetRatio) {
-			qreal newHeight = reqRect.width() / targetRatio;
-			qreal yOffset = (reqRect.height() - newHeight) / 2.0;
-			sourceRect.setY(reqRect.y() + yOffset);
-			sourceRect.setHeight(newHeight);
-		}
+	QRectF sourceRect = computeSourceRect(texture);
+	node->setSourceRect(sourceRect);
 
+	if (texture == m_texture) {
+		QSize texSize = texture->textureSize();
 		QRectF normalizedActual(
-			sourceRect.x() / m_texture->textureSize().width(),
-			sourceRect.y() / m_texture->textureSize().height(),
-			sourceRect.width() / m_texture->textureSize().width(),
-			sourceRect.height() / m_texture->textureSize().height());
+			sourceRect.x() / texSize.width(),
+			sourceRect.y() / texSize.height(),
+			sourceRect.width() / texSize.width(),
+			sourceRect.height() / texSize.height());
 
 		bool changed = false;
-
 		auto updateIfChanged = [&](qreal& dst, qreal value) {
 			if (!qFuzzyCompare(dst, value)) {
 				dst = value;
 				changed = true;
 			}
 		};
-
 		updateIfChanged(m_actualCropX, normalizedActual.x());
 		updateIfChanged(m_actualCropY, normalizedActual.y());
 		updateIfChanged(m_actualCropWidth, normalizedActual.width());
 		updateIfChanged(m_actualCropHeight, normalizedActual.height());
-
 		if (changed) emit actualCropChanged();
+	}
+}
 
-		node->setSourceRect(sourceRect);
+QSGNode* WallpaperImage::updatePaintNode(
+	QSGNode* oldNode, UpdatePaintNodeData*) {
+	Q_UNUSED(oldNode);
+
+	if (m_hasPending) {
+		if (m_previousTexture) {
+			delete m_previousTexture;
+			m_previousTexture = nullptr;
+		}
+		m_previousTexture = m_texture;
+		m_texture = window()->createTextureFromImage(
+			m_pendingImage, QQuickWindow::TextureHasAlphaChannel);
+		m_pendingImage = QImage();
+		m_hasPending = false;
+
+		if (m_previousTexture && m_fadeDuration > 0) {
+			m_fading = true;
+			m_fadeTimer.restart();
+		} else {
+			if (m_previousTexture) {
+				delete m_previousTexture;
+				m_previousTexture = nullptr;
+			}
+			m_fading = false;
+		}
 	}
 
-	return node;
+	if (!m_texture) {
+		return m_rootNode;
+	}
+
+	if (!m_rootNode) {
+		m_rootNode = new QSGNode();
+
+		m_newOpacityNode = new QSGOpacityNode();
+		m_newImageNode = window()->createImageNode();
+		m_newOpacityNode->appendChildNode(m_newImageNode);
+		m_rootNode->appendChildNode(m_newOpacityNode);
+
+		m_oldOpacityNode = new QSGOpacityNode();
+		m_oldImageNode = window()->createImageNode();
+		m_oldOpacityNode->appendChildNode(m_oldImageNode);
+		m_rootNode->appendChildNode(m_oldOpacityNode);
+	}
+
+	configureImageNode(m_newImageNode, m_texture);
+	m_newOpacityNode->setOpacity(1.0);
+
+	if (m_fading && m_previousTexture) {
+		qreal progress =
+			qBound(0.0, qreal(m_fadeTimer.elapsed()) / m_fadeDuration, 1.0);
+
+		configureImageNode(m_oldImageNode, m_previousTexture);
+		m_oldOpacityNode->setOpacity(1.0 - progress);
+
+		if (progress >= 1.0) {
+			m_fading = false;
+			delete m_previousTexture;
+			m_previousTexture = nullptr;
+			m_oldOpacityNode->setOpacity(0.0);
+		} else {
+			update();
+		}
+	} else {
+		m_oldOpacityNode->setOpacity(0.0);
+	}
+
+	return m_rootNode;
 }
 
 } // namespace ZShell::internal

Plugins/ZShell/Internal/wallpaperimage.hpp

@@ -4,9 +4,15 @@
 #include <QImage>
 #include <QUrl>
 #include <QSGTexture>
+#include <QSGOpacityNode>
+#include <QSGImageNode>
 #include <QFutureWatcher>
+#include <QElapsedTimer>
+#include <QThreadPool>
+#include <QTimer>
 #include <QtQml/qqml.h>
 #include <qtmetamacros.h>
+#include <atomic>
 
 namespace ZShell::internal {
 
@@ -19,6 +25,9 @@ class WallpaperImage : public QQuickItem {
 			NOTIFY screenResolutionChanged)
 	Q_PROPERTY(qreal zoom READ zoom WRITE setZoom NOTIFY zoomChanged)
 	Q_PROPERTY(Status status READ status NOTIFY statusChanged)
+	Q_PROPERTY(
+		int fadeDuration READ fadeDuration WRITE setFadeDuration NOTIFY
+			fadeDurationChanged)
 
 	Q_PROPERTY(qreal actualCropX READ actualCropX NOTIFY actualCropChanged)
 	Q_PROPERTY(qreal actualCropY READ actualCropY NOTIFY actualCropChanged)
@@ -54,12 +63,12 @@ class WallpaperImage : public QQuickItem {
 	qreal zoom() const { return m_zoom; }
 	void setZoom(qreal zoom);
 
+	int fadeDuration() const { return m_fadeDuration; }
+	void setFadeDuration(int ms);
+
 	qreal actualCropX() const { return m_actualCropX; }
-
 	qreal actualCropY() const { return m_actualCropY; }
-
 	qreal actualCropWidth() const { return m_actualCropWidth; }
-
 	qreal actualCropHeight() const { return m_actualCropHeight; }
 
 	qreal cropX() const { return m_cropX; }
@@ -82,6 +91,7 @@ class WallpaperImage : public QQuickItem {
 	void sourceChanged();
 	void screenResolutionChanged();
 	void zoomChanged();
+	void fadeDurationChanged();
 	void actualCropChanged();
 	void cropXChanged();
 	void cropYChanged();
@@ -90,15 +100,18 @@ class WallpaperImage : public QQuickItem {
 	void statusChanged();
 
 	private:
-	void loadImage();
+	void beginLoad();
 	void handleImageLoaded();
 	QString getCacheFilePath() const;
 	void setStatus(const Status s);
+	QRectF computeSourceRect(QSGTexture* texture) const;
+	void configureImageNode(QSGImageNode* node, QSGTexture* texture);
 
 	Status m_status = Null;
 	QUrl m_source;
 	QSize m_screenResolution;
 	qreal m_zoom = 1.0;
+	int m_fadeDuration = 400;
 
 	qreal m_actualCropX = 0.0;
 	qreal m_actualCropY = 0.0;
@@ -110,10 +123,25 @@ class WallpaperImage : public QQuickItem {
 	qreal m_cropWidth = 1.0;
 	qreal m_cropHeight = 1.0;
 
-	QImage m_image;
-	QSGTexture* m_texture = nullptr;
-	bool m_textureDirty = false;
+	QTimer m_loadDebounceTimer;
 	QFutureWatcher<QImage> m_imageWatcher;
+	std::shared_ptr<std::atomic<quint64>> m_requestGeneration =
+		std::make_shared<std::atomic<quint64>>(0);
+	static QThreadPool* loadPool();
+	QImage m_pendingImage;
+	bool m_hasPending = false;
+
+	QSGTexture* m_texture = nullptr;
+	QSGTexture* m_previousTexture = nullptr;
+
+	bool m_fading = false;
+	QElapsedTimer m_fadeTimer;
+
+	QSGNode* m_rootNode = nullptr;
+	QSGOpacityNode* m_newOpacityNode = nullptr;
+	QSGOpacityNode* m_oldOpacityNode = nullptr;
+	QSGImageNode* m_newImageNode = nullptr;
+	QSGImageNode* m_oldImageNode = nullptr;
 };
 
 } // namespace ZShell::internal