WindowTrackingService.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <phosphorplacement_export.h>
 
#include <PhosphorEngine/EngineTypes.h>
#include <PhosphorEngine/IWindowTrackingService.h>
#include <PhosphorEngine/PlacementEngineBase.h>
#include <PhosphorEngine/WindowRegistry.h>
#include <PhosphorPlacement/IGeometryResolver.h>
#include <PhosphorPlacement/PlacementConfig.h>
#include <PhosphorProtocol/WindowTypes.h>
#include <PhosphorProtocol/ZoneTypes.h>
#include <PhosphorScreens/ScreenIdentity.h>
 
#include <QHash>
#include <QObject>
#include <QPointer>
#include <QRect>
#include <QSet>
#include <QString>
#include <QStringList>
 
#include <functional>
#include <optional>
#include <utility>
 
namespace PhosphorZones {
class IZoneDetector;
class Layout;
class LayoutRegistry;
class Zone;
}
 
namespace PhosphorSnapEngine {
class SnapState;
}
 
namespace PhosphorEngine {
class WindowRegistry;
}
 
namespace PhosphorWorkspaces {
class VirtualDesktopManager;
}
 
namespace Phosphor::Screens {
class ScreenManager;
}
 
namespace PhosphorPlacement {
 
class PHOSPHORPLACEMENT_EXPORT WindowTrackingService : public QObject, public PhosphorEngine::IWindowTrackingService
{
    Q_OBJECT
 
public:
    explicit WindowTrackingService(PhosphorZones::LayoutRegistry* layoutManager,
                                   PhosphorZones::IZoneDetector* zoneDetector,
                                   Phosphor::Screens::ScreenManager* screenManager,
                                   PhosphorWorkspaces::VirtualDesktopManager* vdm,
                                   IGeometryResolver* geometryResolver = nullptr, PlacementConfig config = {},
                                   QObject* parent = nullptr);
 
    void setConfig(const PlacementConfig& config)
    {
        m_config = config;
    }
    const PlacementConfig& config() const
    {
        return m_config;
    }
 
    QObject* asQObject() override
    {
        return this;
    }
    ~WindowTrackingService() override;
 
    void setWindowRegistry(PhosphorEngine::WindowRegistry* registry)
    {
        m_windowRegistry = registry;
    }
 
    void setSnapState(PhosphorSnapEngine::SnapState* state)
    {
        m_snapState = state;
    }
 
    using ShouldTrackPredicate = std::function<bool(const QString& screenId, int virtualDesktop)>;
 
    void setShouldTrackPredicate(ShouldTrackPredicate predicate)
    {
        m_shouldTrackPredicate = std::move(predicate);
    }
 
    void setSnapEngine(PhosphorEngine::PlacementEngineBase* engine)
    {
        m_snapEngine = engine;
    }
 
    PhosphorEngine::PlacementEngineBase* snapEngine() const
    {
        return m_snapEngine.data();
    }
 
    PhosphorEngine::WindowRegistry* windowRegistry() const
    {
        return m_windowRegistry;
    }
 
    Phosphor::Screens::ScreenManager* screenManager() const override
    {
        return m_screenManager;
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // PhosphorZones::Zone Assignment Management
    // ═══════════════════════════════════════════════════════════════════════════
 
    void assignWindowToZone(const QString& windowId, const QString& zoneId, const QString& screenId,
                            int virtualDesktop) override;
 
    void assignWindowToZones(const QString& windowId, const QStringList& zoneIds, const QString& screenId,
                             int virtualDesktop) override;
 
    void unassignWindow(const QString& windowId) override;
 
    QString zoneForWindow(const QString& windowId) const override;
 
    QStringList zonesForWindow(const QString& windowId) const override;
 
    QStringList windowsInZone(const QString& zoneId) const override;
 
    QStringList snappedWindows() const;
 
    int pruneStaleAssignments(const QSet<QString>& aliveWindowIds);
 
    bool isWindowSnapped(const QString& windowId) const override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Geometry Validation Utility
    // ═══════════════════════════════════════════════════════════════════════════
 
    std::optional<QRect> validateGeometryForScreen(const QRect& geo, const QString& savedScreen,
                                                   const QString& currentScreenName) const;
 
    std::optional<QRect> validatedUnmanagedGeometry(const QString& windowId, const QString& screenId,
                                                    bool exactOnly = false) const override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Floating Window State
    // ═══════════════════════════════════════════════════════════════════════════
 
    bool isWindowFloating(const QString& windowId) const override;
 
    void setWindowFloating(const QString& windowId, bool floating) override;
 
    QStringList floatingWindows() const;
 
    void unsnapForFloat(const QString& windowId) override;
 
    QString preFloatZone(const QString& windowId) const;
 
    QStringList preFloatZones(const QString& windowId) const override;
 
    QString preFloatScreen(const QString& windowId) const override;
 
    void clearPreFloatZone(const QString& windowId);
 
    void clearPreFloatZoneForWindow(const QString& windowId);
 
    bool clearFloatingForSnap(const QString& windowId) override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Sticky Window Handling
    // ═══════════════════════════════════════════════════════════════════════════
 
    void setWindowSticky(const QString& windowId, bool sticky);
 
    bool isWindowSticky(const QString& windowId) const override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Auto-Snap Logic
    // ═══════════════════════════════════════════════════════════════════════════
 
    void recordSnapIntent(const QString& windowId, bool wasUserInitiated) override;
 
    QString lastUsedZoneId() const;
 
    QString lastUsedZoneClass() const;
 
    void retagLastUsedZoneClass(const QString& newClass);
 
    void updateLastUsedZone(const QString& zoneId, const QString& screenId, const QString& windowClass,
                            int virtualDesktop) override;
 
    void markAsAutoSnapped(const QString& windowId);
 
    bool isAutoSnapped(const QString& windowId) const;
 
    bool clearAutoSnapped(const QString& windowId) override;
 
    bool consumePendingAssignment(const QString& windowId) override;
 
    int pruneExcludedPendingRestores(const QStringList& exclusionPatterns);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Navigation Helpers
    // ═══════════════════════════════════════════════════════════════════════════
 
    QString findEmptyZone(const QString& screenId = QString()) const override;
 
    PhosphorProtocol::EmptyZoneList getEmptyZones(const QString& screenId) const;
 
    QRect zoneGeometry(const QString& zoneId, const QString& screenId = QString()) const override;
 
    QRect multiZoneGeometry(const QStringList& zoneIds, const QString& screenId = QString()) const;
 
    void populateResnapBufferForAllScreens(const QSet<QString>& excludeScreens = {},
                                           const QSet<QString>& includeScreens = {}, int desktopFilter = 0);
 
    void clearResnapBuffer()
    {
        m_resnapBuffer.clear();
    }
 
    QStringList buildZoneOrderedWindowList(const QString& screenId) const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Virtual Screen Migration
    // ═══════════════════════════════════════════════════════════════════════════
 
    void migrateScreenAssignmentsToVirtual(const QString& physicalScreenId, const QStringList& virtualScreenIds,
                                           Phosphor::Screens::ScreenManager* mgr);
 
    void migrateScreenAssignmentsFromVirtual(const QString& physicalScreenId);
 
    QSet<QString> physicalScreensWithStaleVirtualAssignments(const QSet<QString>& subdividedPhysicalIds) const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Resolution Change Handling
    // ═══════════════════════════════════════════════════════════════════════════
 
    QHash<QString, QRect> updatedWindowGeometries() const;
 
    struct PendingRestoreTarget
    {
        QRect geometry;
        QString screenId;
    };
 
    QHash<QString, PendingRestoreTarget> pendingRestoreGeometries() const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Window Lifecycle
    // ═══════════════════════════════════════════════════════════════════════════
 
    void windowClosed(const QString& windowId, PhosphorEngine::WindowKind kind = PhosphorEngine::WindowKind::Unknown);
 
    void onLayoutChanged();
 
    // ═══════════════════════════════════════════════════════════════════════════
    // State Access (for adaptor persistence via KConfig)
    // ═══════════════════════════════════════════════════════════════════════════
 
    const QHash<QString, QStringList>& zoneAssignments() const override;
 
    const QHash<QString, QString>& screenAssignments() const override;
 
    const QHash<QString, int>& desktopAssignments() const;
 
    using PendingRestore = PhosphorEngine::PendingRestore;
    using ResnapEntry = PhosphorEngine::ResnapEntry;
 
    const QHash<QString, QList<PendingRestore>>& pendingRestoreQueues() const override
    {
        return m_pendingRestoreQueues;
    }
 
    QVector<ResnapEntry> takeResnapBuffer() override
    {
        return std::exchange(m_resnapBuffer, {});
    }
 
    const QSet<QString>& userSnappedClasses() const;
 
    void setActiveAssignments(const QHash<QString, QStringList>& zones, const QHash<QString, QString>& screens,
                              const QHash<QString, int>& desktops);
 
    void setPendingRestoreQueues(const QHash<QString, QList<PendingRestore>>& queues)
    {
        m_pendingRestoreQueues = queues;
    }
 
    void setUserSnappedClasses(const QSet<QString>& classes);
 
    void setLastUsedZone(const QString& zoneId, const QString& screenId, const QString& zoneClass, int desktop);
 
    void setFloatingWindows(const QSet<QString>& windows)
    {
        m_floatingWindows = windows;
    }
 
    const QHash<QString, QStringList>& preFloatZoneAssignments() const;
    const QHash<QString, QString>& preFloatScreenAssignments() const;
 
    void setPreFloatZoneAssignments(const QHash<QString, QStringList>& assignments);
    void setPreFloatScreenAssignments(const QHash<QString, QString>& assignments);
 
    // ═══════════════════════════════════════════════════════════════════════
    // Dirty field tracking (Phase 3 of refactor/dbus-performance)
    //
    // Replaces "any mutation forces a full re-serialization" with a bitfield
    // mask of which persisted state has changed since the last successful
    // save. WindowTrackingAdaptor::saveState() reads this mask to decide
    // which JSON maps to re-write, and the persistence worker's write-
    // completed signal clears the committed bits — surviving bits either
    // represent new mutations that landed during the in-flight write, or
    // the write itself failed (same treatment in both cases: retry on the
    // next tick).
    //
    // The mask is initialized to All so the first save after a daemon
    // startup always writes every field. loadState() should clear the mask
    // immediately after populating in-memory state so the first real save
    // doesn't redundantly write back what we just loaded.
    // ═══════════════════════════════════════════════════════════════════════
    enum DirtyField : uint32_t {
        DirtyNone = 0,
        DirtyActiveLayoutId = 1u << 0,
        DirtyZoneAssignments = 1u << 1, // zones + screens + desktops (always written together)
        DirtyPendingRestores = 1u << 2,
        DirtyPreTileGeometries = 1u << 3,
        DirtyLastUsedZone = 1u << 4,
        DirtyPreFloatZones = 1u << 5,
        DirtyPreFloatScreens = 1u << 6,
        DirtyUserSnapped = 1u << 7,
        DirtyAutotileOrders = 1u << 8,
        DirtyAutotilePending = 1u << 9,
        DirtyAll = 0x3FFu,
    };
    using DirtyMask = uint32_t;
 
    void markDirty(DirtyMask fields);
 
    DirtyMask takeDirty();
 
    DirtyMask peekDirty() const
    {
        return m_dirtyMask;
    }
 
    void clearDirty();
 
Q_SIGNALS:
    // WARNING: AutotileEngine connects to this signal via string-based SIGNAL/SLOT
    // (it holds IWindowTrackingService*, not WindowTrackingService*, so PMF connect
    // is unavailable). Renaming this signal will silently break autotile zone tracking.
    void windowZoneChanged(const QString& windowId, const QString& zoneId);
 
    void stateChanged();
 
private:
    // Minimum visible area for geometry validation
    static constexpr int MinVisibleWidth = 100;
    static constexpr int MinVisibleHeight = 100;
 
    // Helpers
    //
    // scheduleSaveState() wraps markDirty(DirtyAll). Retained as the
    // default entry point for mutators that haven't been updated to
    // declare which specific fields they touch — marking everything dirty
    // is behaviorally equivalent to the pre-refactor code. Hot-path
    // mutators (assign/unassign zone, storePreTileGeometry, etc.) should
    // call markDirty() directly with a narrow mask so the next save
    // only re-serializes the fields that actually changed.
    void scheduleSaveState(DirtyMask fields = DirtyAll);
    bool isGeometryOnScreen(const QRect& geometry) const;
    QRect adjustGeometryToScreen(const QRect& geometry) const;
    PhosphorZones::Zone* findZoneById(const QString& zoneId) const;
 
    template<typename Func>
    auto preFloatLookup(const QString& windowId, Func&& getter) const -> decltype(getter(windowId));
 
    void validateLastUsedZone(const QString& targetScreen);
 
    static QString findNearestVirtualScreen(const QStringList& vsIds, int oldIndex);
 
    struct ZoneLookupResult
    {
        PhosphorZones::Zone* zone = nullptr;
        PhosphorZones::Layout* layout = nullptr;
    };
    ZoneLookupResult findZoneInAllLayouts(const QUuid& zoneUuid) const;
 
public:
    QString resolveEffectiveScreenId(const QString& screenId) const override;
 
    QRect resolveZoneGeometry(const QStringList& zoneIds, const QString& screenId) const override;
 
    QString findEmptyZoneInLayout(PhosphorZones::Layout* layout, const QString& screenId,
                                  int desktopFilter = 0) const override;
 
    // Zone sort / position-map helpers now live in PhosphorZones::LayoutUtils.
    // Call PhosphorZones::LayoutUtils::sortZonesByNumber / buildZonePositionMap directly.
 
    QSet<QUuid> buildOccupiedZoneSet(const QString& screenFilter = QString(), int desktopFilter = 0) const override;
 
    QString currentAppIdFor(const QString& anyWindowId) const override;
 
    QString canonicalizeForLookup(const QString& rawWindowId) const;
 
private:
    // Dependencies
    PhosphorZones::LayoutRegistry* m_layoutManager;
    PhosphorZones::IZoneDetector* m_zoneDetector;
    PhosphorSnapEngine::SnapState* m_snapState = nullptr;
    IGeometryResolver* m_geometryResolver;
    PlacementConfig m_config;
    PhosphorWorkspaces::VirtualDesktopManager* m_virtualDesktopManager;
    // Shared registry for current-class queries and canonical key translation.
    // Not owned. Null in unit tests.
    PhosphorEngine::WindowRegistry* m_windowRegistry = nullptr;
    Phosphor::Screens::ScreenManager* m_screenManager = nullptr;
    QPointer<PhosphorEngine::PlacementEngineBase> m_snapEngine;
 
    // Floating windows: full windowId at runtime, appId for session-restored entries
    // Converted from windowId to appId on window close for persistence
    QSet<QString> m_floatingWindows;
 
    // Session persistence: consumption queue (appId -> list of pending restores, consumed FIFO)
    QHash<QString, QList<PendingRestore>> m_pendingRestoreQueues;
 
    // Optional daemon-injected gate consulted before recording a PendingRestore
    // on windowClosed. When unset (e.g. unit tests), every context is treated
    // as active and the historical write-everything behavior is preserved.
    ShouldTrackPredicate m_shouldTrackPredicate{};
 
    // Pre-float zone and screen state is owned by SnapState (authoritative store).
    // WTS preFloat getter methods add appId-fallback queries for session-restored
    // entries keyed by appId. SnapState itself uses windowId-only keys.
 
    // Sticky window states
    QHash<QString, bool> m_windowStickyStates;
 
    QVector<ResnapEntry> m_resnapBuffer;
 
    // Delta-persistence dirty mask. Initial value DirtyAll forces the first
    // save after daemon startup to serialize every field. Cleared by
    // loadState() once in-memory state mirrors the disk file.
    DirtyMask m_dirtyMask = DirtyAll;
 
    // Note: No save timer - persistence handled by WindowTrackingAdaptor via KConfig
    // Service emits stateChanged() signal when state needs saving
};
 
} // namespace PhosphorPlacement