feat: initial commit for pixel-snapping components and helpers

Plugins/ZShell/zutils.hpp

@@ -53,6 +53,44 @@ class ZUtils : public QObject {
 	Q_INVOKABLE static QList<QQuickItem*> findChildrenMatching(
 		QQuickItem* root, const QString& pattern);
 
+	// Device pixel ratio of the window the item lives in (falls back to the primary screen, then 1.0)
+	Q_INVOKABLE static qreal dprFor(QQuickItem* item);
+
+	// Snap a logical value to the device pixel grid of the item's window.
+	// Centering is detected from the item: anchors.centerIn,
+	// anchors.horizontalCenter / verticalCenter, and Layout alignment. A size
+	// along a centered axis is snapped so the centered edges land on whole
+	// device pixels — using Qt's own rounding rule for that anchor style
+	// (exact halves when `alignWhenCentered` is true, the rounded half of the
+	// anchor target when it is false).
+	Q_INVOKABLE static qreal snap(qreal value, QQuickItem* item);
+	Q_INVOKABLE static qreal snapCeil(qreal value, QQuickItem* item); // text-derived sizes
+	Q_INVOKABLE static qreal snapFloor(qreal value, QQuickItem* item);
+	// Logs where an item sits in device pixels and whether it is aligned.
+	// Returns true if aligned. `tag` is an optional label for the log line.
+	// Items centered on a target are judged by the centering rule above
+	// (whole device size, plus the offset the anchor produces), which is
+	// detected from the item's anchors and Layout alignment.
+	Q_INVOKABLE static bool logPlacement(
+		QQuickItem* item,
+		const QString& tag = QString());
+
+	// Walks a stroked curve path (flat x,y pairs in the item's logical coords,
+	// every point along the curve, not just its defined points) and checks
+	// whether both stroke edges land on device pixel boundaries at `lineWidth`.
+	// Returns true if every sample is aligned.
+	Q_INVOKABLE static bool logCurvePlacement(
+		QQuickItem* item,
+		const QList<qreal>& samples,
+		qreal lineWidth,
+		const QString& tag = QString());
+
+	// Distributes `total` (logical px) across items with the given preferred widths.
+	// Every result is a whole number of device pixels and the results sum exactly to
+	// the snapped total. If the preferred widths don't fit, they shrink proportionally.
+	Q_INVOKABLE static QList<qreal> distribute(
+		qreal total, const QList<qreal>& preferred, QQuickItem* item);
+
 	[[nodiscard]] QString version() const;
 	[[nodiscard]] QString qtVersion() const;
 };