WindowTrackingService.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
// FILE-SIZE EXCEPTION (sanctioned): WindowTrackingService is the engine-
// agnostic facade every placement engine and the daemon share, and this is an
// INSTALLED public header — splitting the class is an API break for the
// third-party consumers the LGPL boundary exists to serve. The implementation
// is already split by concern across src/*.cpp (snap, resnap, navigation,
// virtualscreenmigration, lifecycle), and the member ordering here encodes
// which of those owns what. Same rationale as
// PhosphorTileEngine/AutotileEngine.h.
 
#pragma once
 
#include <phosphorplacement_export.h>
 
#include <PhosphorEngine/EngineTypes.h>
#include <PhosphorEngine/IWindowTrackingService.h>
#include <PhosphorEngine/PlacementEngineBase.h>
#include <PhosphorEngine/WindowRegistry.h>
#include <PhosphorEngine/WindowPlacementStore.h>
#include <PhosphorPlacement/IGeometryResolver.h>
#include <PhosphorPlacement/PlacementConfig.h>
#include <PhosphorPlacement/SnapStateResolver.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 Layout;
class LayoutRegistry;
class Zone;
}
 
namespace PhosphorSnapEngine {
class SnapState;
}
 
namespace PhosphorWorkspaces {
class VirtualDesktopManager;
}
 
namespace PhosphorScreens {
class ScreenManager;
}
 
namespace PhosphorPlacement {
 
class PHOSPHORPLACEMENT_EXPORT WindowTrackingService : public QObject, public PhosphorEngine::IWindowTrackingService
{
    Q_OBJECT
 
public:
    explicit WindowTrackingService(PhosphorZones::LayoutRegistry* layoutManager,
                                   PhosphorScreens::ScreenManager* screenManager,
                                   PhosphorWorkspaces::VirtualDesktopManager* vdm,
                                   IGeometryResolver* geometryResolver = nullptr, PlacementConfig config = {},
                                   QObject* parent = nullptr);
 
    const PlacementConfig& config() const
    {
        return m_config;
    }
 
    QObject* asQObject() override;
    ~WindowTrackingService() override;
 
    void setWindowRegistry(PhosphorEngine::WindowRegistry* registry);
 
    using SnapStateResolver = PhosphorPlacement::SnapStateResolver;
 
    void setSnapStateResolver(SnapStateResolver resolver);
 
    void setSnapState(PhosphorSnapEngine::SnapState* state);
 
    PhosphorEngine::WindowPlacementStore& placementStore() override;
    const PhosphorEngine::WindowPlacementStore& placementStore() const;
 
    using ShouldTrackPredicate = std::function<bool(const QString& screenId, int virtualDesktop)>;
 
    void setShouldTrackPredicate(ShouldTrackPredicate predicate);
 
    void setSnapEngine(PhosphorEngine::PlacementEngineBase* engine);
 
    PhosphorEngine::PlacementEngineBase* snapEngine() const;
 
    using AutotileModePredicate = std::function<bool(const QString& windowId)>;
    void setAutotileModePredicate(AutotileModePredicate predicate);
 
    bool isWindowInAutotileMode(const QString& windowId) const;
 
    using EngineTiledPredicate = std::function<bool(const QString& windowId)>;
    void setEngineTiledPredicate(EngineTiledPredicate predicate);
 
    bool isWindowEngineTiled(const QString& windowId) const;
 
    using ModeEngineIdResolver = std::function<QString(const QString& windowId, const QString& screenId)>;
    void setModeEngineIdResolver(ModeEngineIdResolver resolver);
 
    QString owningModeEngineId(const QString& windowId, const QString& screenId) const;
 
    static void downgradeMismatchedManagedSlots(PhosphorEngine::WindowPlacement& placement,
                                                const QString& recordedScreenId, const QString& closeScreenId);
 
    PhosphorEngine::WindowRegistry* windowRegistry() const;
 
    PhosphorScreens::ScreenManager* screenManager() const override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // 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;
 
    QString screenForWindow(const QString& windowId) const override;
 
    QString screenForWindow(const QString& windowId, const QString& defaultScreen) 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;
 
    void recordFreeGeometry(const QString& windowId, const QString& screenId, const QRect& geometry,
                            bool overwrite) override;
 
    void recordFloatingClose(const QString& windowId, const QString& screenId, const QRect& geometry);
 
    void clearFreeGeometry(const QString& windowId) override;
    void clearFreeGeometry(const QString& windowId, const QString& screenId) override;
 
    void releaseEngineSlot(const QString& windowId, const QString& engineId) override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Floating Window State
    // ═══════════════════════════════════════════════════════════════════════════
 
    using EngineFloatResolver = std::function<bool(const QString& windowId)>;
    using EngineFloatWriter = std::function<void(const QString& windowId, bool floating)>;
    using EngineFloatLister = std::function<QStringList()>;
 
    void setEngineFloatResolver(EngineFloatResolver resolver);
    void setEngineFloatWriter(EngineFloatWriter writer);
    void setEngineFloatLister(EngineFloatLister lister);
 
    bool isWindowFloating(const QString& windowId) const override;
 
    bool isSuspensionFloat(const QString& windowId) const override;
    void markSuspensionFloat(const QString& windowId);
    void clearSuspensionFloat(const QString& windowId) 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) override;
 
    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;
 
    QString lastUsedScreenName() const;
 
    int lastUsedDesktop() 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;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // 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();
 
    QStringList buildZoneOrderedWindowList(const QString& screenId) const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Virtual Screen Migration
    // ═══════════════════════════════════════════════════════════════════════════
 
    void migrateScreenAssignmentsToVirtual(const QString& physicalScreenId, const QStringList& virtualScreenIds,
                                           PhosphorScreens::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
    // ═══════════════════════════════════════════════════════════════════════════
 
    QStringList recordedSnapZones(const QString& windowId) const override;
 
    using PendingRestore = PhosphorEngine::PendingRestore;
    using ResnapEntry = PhosphorEngine::ResnapEntry;
 
    const QHash<QString, QList<PendingRestore>>& pendingRestoreQueues() const override;
 
    QVector<ResnapEntry> takeResnapBuffer() override;
 
    const QSet<QString>& userSnappedClasses() const;
 
    void setPendingRestoreQueues(const QHash<QString, QList<PendingRestore>>& 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);
 
    // ═══════════════════════════════════════════════════════════════════════
    // 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.
    // ═══════════════════════════════════════════════════════════════════════
    // NOTE: several bits below (DirtyZoneAssignments, DirtyPendingRestores,
    // DirtyPreTileGeometries, DirtyPreFloatZones, DirtyPreFloatScreens,
    // DirtyAutotileOrders, DirtyAutotilePending) no longer have a dedicated save
    // block — their legacy keys were collapsed into DirtyWindowPlacements. The
    // runtime mutators that still OR them in are retained because the act of
    // marking ANY bit schedules a save, and saveState()'s refreshOpenWindowPlacements()
    // re-derives the affected per-window state into the placement record. They are
    // therefore "schedule a save" triggers, not independent persisted fields; only
    // DirtyActiveLayoutId / DirtyLastUsedZone / DirtyUserSnapped / DirtyWindowPlacements
    // map to their own on-disk key.
    enum DirtyField : uint32_t {
        DirtyNone = 0,
        DirtyActiveLayoutId = 1u << 0,
        DirtyZoneAssignments = 1u << 1, // legacy save-trigger → DirtyWindowPlacements
        DirtyPendingRestores = 1u << 2, // legacy save-trigger → DirtyWindowPlacements
        DirtyPreTileGeometries = 1u << 3, // legacy save-trigger → DirtyWindowPlacements
        DirtyLastUsedZone = 1u << 4,
        DirtyPreFloatZones = 1u << 5, // legacy save-trigger → DirtyWindowPlacements
        DirtyPreFloatScreens = 1u << 6, // legacy save-trigger → DirtyWindowPlacements
        DirtyUserSnapped = 1u << 7,
        DirtyAutotileOrders = 1u << 8, // legacy save-trigger → DirtyWindowPlacements
        DirtyAutotilePending = 1u << 9, // legacy save-trigger → DirtyWindowPlacements
        // bit 10 reserved (was DirtyFloatRestores, removed with the FloatRestoreQueues key)
        DirtyWindowPlacements = 1u << 11, 
        DirtyScrollStrips = 1u << 12, 
        DirtyAll = 0x1FFFu, // covers bits 0-12 incl. the reserved bit 10
    };
    using DirtyMask = uint32_t;
 
    void markDirty(DirtyMask fields);
 
    DirtyMask takeDirty();
 
    DirtyMask peekDirty() const;
 
    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(std::declval<PhosphorSnapEngine::SnapState*>(), 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:
    // ── Snap-state resolution helpers (wrap the injected resolver) ───────────
    // Each returns nullptr / empty when the resolver is unwired, preserving the
    // historical "no SnapState" no-op guards at the call sites.
    PhosphorSnapEngine::SnapState* snapForWindow(const QString& windowId) const;
    PhosphorSnapEngine::SnapState* snapForWindowOnScreen(const QString& windowId, const QString& screenId);
    PhosphorSnapEngine::SnapState* snapForScreen(const QString& screenId) const;
    PhosphorSnapEngine::SnapState* snapRepresentativeLastUsed() const;
    bool clearGlobalLastUsedIfRemoved(const QStringList& removedZones,
                                      const PhosphorSnapEngine::SnapState* owningStore);
 
    bool pruneMigratedWindows(const QStringList& windowsToRemove);
    PhosphorSnapEngine::SnapState* snapGlobals() const;
    QList<PhosphorSnapEngine::SnapState*> snapAllStates() const;
    bool hasSnapState() const;
    void forEachZoneAssignedWindow(const std::function<void(const QString& windowId, const QStringList& zoneIds,
                                                            const QString& screenId, int desktop)>& fn) const;
 
    void flushPendingUserSnappedClasses();
 
    // Dependencies
    PhosphorZones::LayoutRegistry* m_layoutManager;
    SnapStateResolver m_snapResolver;
    std::optional<QSet<QString>> m_pendingUserSnappedClasses;
    PhosphorEngine::WindowPlacementStore m_placementStore;
    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. QPointer (not raw): both are Daemon
    // children whose destruction order relative to this service is not
    // contractual — a raw borrow dangled during Daemon child teardown, while
    // the QPointer auto-nulls and every use site already null-guards.
    QPointer<PhosphorEngine::WindowRegistry> m_windowRegistry;
    QPointer<PhosphorScreens::ScreenManager> m_screenManager;
    QPointer<PhosphorEngine::PlacementEngineBase> m_snapEngine;
    AutotileModePredicate m_autotileModePredicate{};
    EngineTiledPredicate m_engineTiledPredicate{};
    ModeEngineIdResolver m_modeEngineIdResolver{};
 
    // Floating windows: full windowId at runtime, appId for session-restored entries
    // Converted from windowId to appId on window close for persistence.
    //
    // LEGACY FALLBACK ONLY: used when no per-engine resolver/writer is wired
    // (unit tests / early init). In production the daemon injects
    // m_engineFloatResolver / m_engineFloatWriter and this set is never read or
    // written by isWindowFloating / setWindowFloating.
    QSet<QString> m_floatingWindows;
 
    // Suspension-float classification — see isSuspensionFloat(). Canonical-
    // keyed. Session-transient (never persisted): a restart's restored floats
    // are re-classified when their windows re-report minimize state.
    QSet<QString> m_suspensionFloats;
 
    // Daemon-injected per-engine float reader/writer/lister. See setEngineFloatResolver.
    EngineFloatResolver m_engineFloatResolver{};
    EngineFloatWriter m_engineFloatWriter{};
    EngineFloatLister m_engineFloatLister{};
 
    // 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