AutotileEngine.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <phosphortileengine_export.h>
#include <PhosphorEngine/PerScreenKeys.h>
#include <PhosphorEngine/EngineTypes.h>
#include <PhosphorLayoutApi/EdgeGaps.h>
#include <PhosphorEngine/IWindowRegistry.h>
#include <PhosphorEngine/IWindowTrackingService.h>
#include <PhosphorEngine/PlacementEngineBase.h>
#include <PhosphorTileEngine/IAutotileSettings.h>
#include <QHash>
#include <QJsonArray>
#include <QObject>
#include <QRect>
#include <QSet>
#include <QSize>
#include <QString>
#include <QStringList>
#include <QTimer>
#include <functional>
#include <memory>
#include <optional>
 
#include <PhosphorTileEngine/OverflowManager.h>
 
namespace PhosphorZones {
class Layout;
class LayoutRegistry;
}
 
namespace PhosphorTileEngine {
 
struct PendingAutotileRestore
{
    PendingAutotileRestore() = default;
    PendingAutotileRestore(int pos, PhosphorEngine::TilingStateKey ctx, bool floating)
        : position(pos)
        , context(std::move(ctx))
        , wasFloating(floating)
    {
    }
 
    int position = -1; 
    PhosphorEngine::TilingStateKey context; 
    bool wasFloating = false; 
};
 
constexpr int MaxPendingRestoresPerApp = 16;
 
class AutotileConfig;
 
class NavigationController;
class PerScreenConfigResolver;
// Phosphor::Screens::ScreenManager moved to libs/phosphor-screens (Phosphor::Screens::ScreenManager).
} // namespace PhosphorTileEngine
namespace Phosphor::Screens {
class ScreenManager;
}
 
namespace PhosphorTiles {
class ITileAlgorithmRegistry;
class TilingAlgorithm;
class TilingState;
}
 
namespace PhosphorTileEngine {
 
class PHOSPHORTILEENGINE_EXPORT AutotileEngine : public PhosphorEngine::PlacementEngineBase
{
    Q_OBJECT
    Q_PROPERTY(bool enabled READ isEnabled NOTIFY enabledChanged)
    Q_PROPERTY(QString algorithm READ algorithm WRITE setAlgorithm NOTIFY algorithmChanged)
 
    friend class NavigationController;
    friend class PerScreenConfigResolver;
 
public:
    explicit AutotileEngine(PhosphorZones::LayoutRegistry* layoutManager,
                            PhosphorEngine::IWindowTrackingService* windowTracker,
                            Phosphor::Screens::ScreenManager* screenManager,
                            PhosphorTiles::ITileAlgorithmRegistry* algorithmRegistry, QObject* parent = nullptr);
    ~AutotileEngine() override;
 
    PhosphorTiles::ITileAlgorithmRegistry* algorithmRegistry() const
    {
        return m_algorithmRegistry;
    }
 
    void setWindowRegistry(QObject* registry) override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Per-screen autotile state (derived from layout assignments)
    // ═══════════════════════════════════════════════════════════════════════════
 
    bool isEnabled() const noexcept override;
 
    QSet<int> desktopsWithActiveState() const override;
 
    bool isAutotileScreen(const QString& screenId) const;
 
    bool isWindowTracked(const QString& windowId) const override
    {
        return m_windowToStateKey.contains(windowId);
    }
 
    bool isWindowTiled(const QString& windowId) const override;
 
    // IPlacementEngine
    bool isActiveOnScreen(const QString& screenId) const override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // IPlacementEngine — generic screen/window management overrides
    //
    // Each override delegates to the concrete autotile method below it.
    // AutotileAdaptor continues to call the concrete methods directly.
    // ═══════════════════════════════════════════════════════════════════════════
 
    QSet<QString> activeScreens() const override
    {
        return autotileScreens();
    }
    void setActiveScreens(const QSet<QString>& screens) override
    {
        setAutotileScreens(screens);
    }
    QStringList managedWindowOrder(const QString& screenId) const override
    {
        return tiledWindowOrder(screenId);
    }
    bool isModeSpecificFloated(const QString& windowId) const override
    {
        return isAutotileFloated(windowId);
    }
    void clearModeSpecificFloatMarker(const QString& windowId) override
    {
        clearAutotileFloated(windowId);
    }
    bool isWindowManaged(const QString& windowId) const override
    {
        return isWindowTiled(windowId);
    }
    QString algorithmId() const override
    {
        return algorithm();
    }
    void markModeSpecificFloated(const QString& windowId) override
    {
        markAutotileFloated(windowId);
    }
 
    const QSet<QString>& autotileScreens() const
    {
        return m_autotileScreens;
    }
 
    QString activeScreen() const override
    {
        return m_activeScreen;
    }
 
    void setAutotileScreens(const QSet<QString>& screens);
 
    void setCurrentDesktop(int desktop) override;
 
    void setCurrentActivity(const QString& activity) override;
 
    void updateStickyScreenPins(const std::function<bool(const QString&)>& isWindowSticky) override;
 
    void pruneStatesForDesktop(int removedDesktop) override;
 
    void pruneStatesForActivities(const QStringList& validActivities) override;
 
    int currentDesktop() const noexcept
    {
        return m_currentDesktop;
    }
 
    const QString& currentActivity() const noexcept
    {
        return m_currentActivity;
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Algorithm selection
    // ═══════════════════════════════════════════════════════════════════════════
 
    QString algorithm() const noexcept;
 
    void setAlgorithm(const QString& algorithmId) override;
 
    PhosphorTiles::TilingAlgorithm* currentAlgorithm() const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Tiling state access
    // ═══════════════════════════════════════════════════════════════════════════
 
    PhosphorTiles::TilingState* tilingStateForScreen(const QString& screenId);
 
    PhosphorEngine::IPlacementState* stateForScreen(const QString& screenId) override;
    const PhosphorEngine::IPlacementState* stateForScreen(const QString& screenId) const override;
 
    AutotileConfig* config() const noexcept;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Session Persistence
    // ═══════════════════════════════════════════════════════════════════════════
 
    void saveState() override;
 
    void loadState() override;
 
    void setPersistenceDelegate(std::function<void()> saveFn, std::function<void()> loadFn)
    {
        m_persistSaveFn = std::move(saveFn);
        m_persistLoadFn = std::move(loadFn);
    }
 
    void setIsWindowFloatingFn(std::function<bool(const QString&)> fn) override
    {
        m_isWindowFloatingFn = std::move(fn);
    }
 
    // Cross-engine handoff (see PhosphorEngine/IPlacementEngine.h for contract)
    QString engineId() const override
    {
        return QStringLiteral("autotile");
    }
    void handoffReceive(const HandoffContext& ctx) override;
    void handoffRelease(const QString& windowId) override;
    QString screenForTrackedWindow(const QString& windowId) const override
    {
        const auto it = m_windowToStateKey.constFind(canonicalizeForLookup(windowId));
        return it == m_windowToStateKey.constEnd() ? QString() : it.value().screenId;
    }
 
    QJsonArray serializeWindowOrders() const override;
 
    void deserializeWindowOrders(const QJsonArray& orders) override;
 
    QJsonObject serializePendingRestores() const override;
 
    void deserializePendingRestores(const QJsonObject& obj) override;
 
    int pruneExcludedPendingRestores(const QStringList& exclusionPatterns);
 
    using ShouldPersistRestorePredicate =
        std::function<bool(const QString& screenId, int desktop, const QString& activity)>;
 
    void setShouldPersistRestorePredicate(ShouldPersistRestorePredicate predicate)
    {
        m_shouldPersistRestorePredicate = std::move(predicate);
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Settings synchronization
    // ═══════════════════════════════════════════════════════════════════════════
 
    PhosphorEngine::IAutotileSettings* autotileSettings() const;
    void writeBackTuning();
    void refreshConfigFromSettings() override;
 
    // Per-screen config — forwarded to PerScreenConfigResolver (IPlacementEngine overrides)
    void applyPerScreenConfig(const QString& screenId, const QVariantMap& overrides) override;
    void clearPerScreenConfig(const QString& screenId) override;
    QVariantMap perScreenOverrides(const QString& screenId) const override;
    bool hasPerScreenOverride(const QString& screenId, const QString& key) const;
    void updatePerScreenOverride(const QString& screenId, const QString& key, const QVariant& value);
 
    // Effective per-screen values — forwarded to PerScreenConfigResolver
    int effectiveInnerGap(const QString& screenId) const;
    int effectiveOuterGap(const QString& screenId) const;
    ::PhosphorLayout::EdgeGaps effectiveOuterGaps(const QString& screenId) const;
    bool effectiveSmartGaps(const QString& screenId) const;
    bool effectiveRespectMinimumSize(const QString& screenId) const;
    int effectiveMaxWindows(const QString& screenId) const;
    qreal effectiveSplitRatioStep(const QString& screenId) const override;
    int runtimeMaxWindows() const override;
    QString effectiveAlgorithmId(const QString& screenId) const;
    PhosphorTiles::TilingAlgorithm* effectiveAlgorithm(const QString& screenId) const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Manual tiling operations
    // ═══════════════════════════════════════════════════════════════════════════
 
    void setInnerGap(int gap);
    void setOuterGap(int gap);
    void setSmartGaps(bool enabled);
    void setFocusNewWindows(bool enabled);
    Q_INVOKABLE void retile(const QString& screenId = QString()) override;
 
    Q_INVOKABLE void swapWindows(const QString& windowId1, const QString& windowId2);
 
    Q_INVOKABLE void promoteToMaster(const QString& windowId);
 
    Q_INVOKABLE void demoteFromMaster(const QString& windowId);
 
    Q_INVOKABLE void swapFocusedWithMaster() override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Focus/window cycling
    // ═══════════════════════════════════════════════════════════════════════════
 
    Q_INVOKABLE void focusNext();
 
    Q_INVOKABLE void focusPrevious();
 
    Q_INVOKABLE void focusMaster() override;
 
    void setFocusedWindow(const QString& windowId);
 
    void setActiveScreenHint(const QString& screenId) override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Split ratio adjustment
    // ═══════════════════════════════════════════════════════════════════════════
 
    Q_INVOKABLE void increaseMasterRatio(qreal delta = 0.05) override;
 
    Q_INVOKABLE void decreaseMasterRatio(qreal delta = 0.05) override;
 
    void setGlobalSplitRatio(qreal ratio);
 
    void setGlobalMasterCount(int count);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Master count adjustment
    // ═══════════════════════════════════════════════════════════════════════════
 
    Q_INVOKABLE void increaseMasterCount() override;
 
    Q_INVOKABLE void decreaseMasterCount() override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Window rotation and floating (context-aware shortcuts support)
    // ═══════════════════════════════════════════════════════════════════════════
 
    Q_INVOKABLE void rotateWindowOrder(bool clockwise = true);
 
    Q_INVOKABLE void toggleFocusedWindowFloat();
 
    Q_INVOKABLE void toggleWindowFloat(const QString& windowId, const QString& screenId) override;
 
    Q_INVOKABLE void swapFocusedInDirection(const QString& direction, const QString& action = QStringLiteral("move"));
 
    Q_INVOKABLE void focusInDirection(const QString& direction, const QString& action = QStringLiteral("focus"));
 
    Q_INVOKABLE void moveFocusedToPosition(int position);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // IPlacementEngine — navigation overrides
    //
    // Each override absorbs what AutotileNavigationAdapter did: translate
    // the user-intent-shaped IPlacementEngine call into the existing
    // concrete AutotileEngine method with the right parameters.
    // ═══════════════════════════════════════════════════════════════════════════
 
    void focusInDirection(const QString& direction, const PhosphorEngine::NavigationContext& ctx) override;
    void moveFocusedInDirection(const QString& direction, const PhosphorEngine::NavigationContext& ctx) override;
    void swapFocusedInDirection(const QString& direction, const PhosphorEngine::NavigationContext& ctx) override;
    void moveFocusedToPosition(int position, const PhosphorEngine::NavigationContext& ctx) override;
    void rotateWindows(bool clockwise, const PhosphorEngine::NavigationContext& ctx) override;
    void reapplyLayout(const PhosphorEngine::NavigationContext& ctx) override;
    void snapAllWindows(const PhosphorEngine::NavigationContext& ctx) override;
    void toggleFocusedFloat(const PhosphorEngine::NavigationContext& ctx) override;
    void cycleFocus(bool forward, const PhosphorEngine::NavigationContext& ctx) override;
    void pushToEmptyZone(const PhosphorEngine::NavigationContext& ctx) override;
    void restoreFocusedWindow(const PhosphorEngine::NavigationContext& ctx) override;
 
    // Autotile-specific navigation. Callable directly on the concrete
    // AutotileEngine pointer from internal callers.
    void swapInDirection(const QString& direction, const QString& action);
    void rotateWindows(bool clockwise, const QString& screenId);
    void moveToPosition(const QString& windowId, int position, const QString& screenId);
 
    Q_INVOKABLE void setWindowFloat(const QString& windowId, bool shouldFloat) override;
 
    Q_INVOKABLE void floatWindow(const QString& windowId);
 
    Q_INVOKABLE void unfloatWindow(const QString& windowId);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // PhosphorZones::Zone-ordered window transitions (snapping ↔ autotile)
    // ═══════════════════════════════════════════════════════════════════════════
 
    void setInitialWindowOrder(const QString& screenId, const QStringList& windowIds) override;
 
    void clearSavedFloatingForWindows(const QStringList& windowIds) override;
 
    void clearAllSavedFloating() override;
 
    QStringList tiledWindowOrder(const QString& screenId) const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Window event handlers (public API for external notification)
    // ═══════════════════════════════════════════════════════════════════════════
 
    using IPlacementEngine::windowOpened;
    void windowOpened(const QString& windowId, const QString& screenId, int minWidth, int minHeight) override;
 
    void windowMinSizeUpdated(const QString& windowId, int minWidth, int minHeight);
 
    void windowClosed(const QString& windowId) override;
 
    void windowFocused(const QString& windowId, const QString& screenId) override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Retile helpers (public — used by extracted classes)
    // ═══════════════════════════════════════════════════════════════════════════
 
    void scheduleRetileForScreen(const QString& screenId) override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Drag-insert preview (trigger-held window drag reorders autotile stack)
    // ═══════════════════════════════════════════════════════════════════════════
 
    bool beginDragInsertPreview(const QString& windowId, const QString& screenId) override;
 
    void updateDragInsertPreview(int insertIndex) override;
 
    void commitDragInsertPreview() override;
 
    void cancelDragInsertPreview() override;
 
    int computeDragInsertIndexAtPoint(const QString& screenId, const QPoint& cursorPos) const override;
 
    bool hasDragInsertPreview() const override
    {
        return m_dragInsertPreview.has_value();
    }
 
    QString dragInsertPreviewWindowId() const
    {
        return m_dragInsertPreview ? m_dragInsertPreview->windowId : QString();
    }
 
    QString dragInsertPreviewScreenId() const override
    {
        return m_dragInsertPreview ? m_dragInsertPreview->targetScreenId : QString();
    }
 
    void retileAfterOperation(const QString& screenId, bool operationSucceeded);
 
Q_SIGNALS:
    void enabledChanged(bool enabled);
 
    void autotileScreensChanged(const QStringList& screenIds, bool isDesktopSwitch);
 
    // algorithmChanged(const QString&) — inherited from PlacementEngineBase.
    // placementChanged(const QString&) — inherited from PlacementEngineBase.
    //   Replaces the former tilingChanged signal; all internal emitters now
    //   emit placementChanged, and callers connect to the base-class signal.
    // windowsReleased(const QStringList&, const QSet<QString>&) — inherited
    //   from PlacementEngineBase. Replaces windowsReleasedFromTiling.
 
    // windowFloatingStateSynced and windowsBatchFloated are inherited from
    // PlacementEngineBase. Autotile-specific documentation: windowFloatingStateSynced
    // is emitted when the engine's TilingState::isFloating diverges from WTS's view
    // (e.g. a newly-inserted window carries stale snap-mode float state). The
    // downstream handler updates WTS bookkeeping without geometry restore.
    // windowsBatchFloated is emitted when overflow windows are batch-floated
    // during applyTiling; the daemon handler updates WTS state directly.
 
    void windowsTiled(const QString& tileRequestsJson);
 
public:
    // ═══════════════════════════════════════════════════════════════════════════
    // Autotile-float origin tracking (ephemeral, not persisted)
    // ═══════════════════════════════════════════════════════════════════════════
 
    void markAutotileFloated(const QString& windowId);
    void clearAutotileFloated(const QString& windowId);
    bool isAutotileFloated(const QString& windowId) const;
 
    int pruneStaleWindows(const QSet<QString>& aliveWindowIds) override;
 
private Q_SLOTS:
    void onWindowZoneChanged(const QString& windowId, const QString& zoneId);
    void onWindowAdded(const QString& windowId);
    void onWindowRemoved(const QString& windowId);
    void onWindowFocused(const QString& windowId);
    void onScreenGeometryChanged(const QString& screenId);
    void onLayoutChanged(PhosphorZones::Layout* layout);
 
protected:
    void onWindowClaimed(const QString& windowId) override;
    void onWindowReleased(const QString& windowId) override;
    void onWindowFloated(const QString& windowId) override;
    void onWindowUnfloated(const QString& windowId) override;
 
private:
    void connectSignals();
    bool insertWindow(const QString& windowId, const QString& screenId);
    void removeWindow(const QString& windowId);
    void removeSavedFloatingEntry(const QString& windowId);
    void pruneStaleRestores(const QString& appId);
    bool storeWindowMinSize(const QString& windowId, int minWidth, int minHeight);
    bool recalculateLayout(const QString& screenId);
    void applyTiling(const QString& screenId);
    bool shouldTileWindow(const QString& windowId) const;
    QString screenForWindow(const QString& windowId) const;
    QRect screenGeometry(const QString& screenId) const;
 
    bool isKnownScreen(const QString& screenId) const;
 
    PhosphorEngine::TilingStateKey currentKeyForScreen(const QString& screenId) const
    {
        auto it = m_screenDesktopOverride.constFind(screenId);
        int desktop = (it != m_screenDesktopOverride.constEnd()) ? it.value() : m_currentDesktop;
        return PhosphorEngine::TilingStateKey{screenId, desktop, m_currentActivity};
    }
 
    PhosphorTiles::TilingState* stateForKey(const PhosphorEngine::TilingStateKey& key);
 
    void resetMaxWindowsForAlgorithmSwitch(PhosphorTiles::TilingAlgorithm* oldAlgo,
                                           PhosphorTiles::TilingAlgorithm* newAlgo);
 
    void propagateGlobalSplitRatio();
 
    void propagateGlobalMasterCount();
 
    void backfillWindows();
 
    void retileScreen(const QString& screenId);
 
    void scheduleRetileRetry(const QString& screenId);
 
    void processRetileRetries();
 
    // ═══════════════════════════════════════════════════════════════════════════════
    // Helper Methods
    // ═══════════════════════════════════════════════════════════════════════════════
 
    bool cleanupPendingOrderIfResolved(const QString& screenId);
 
    void schedulePromoteSavedWindowOrders();
 
    void promoteSavedWindowOrders();
 
    bool warnIfEmptyWindowId(const QString& windowId, const char* operation) const;
 
    QString canonicalizeWindowId(const QString& rawWindowId);
 
    void cleanupCanonical(const QString& anyWindowId);
 
    QString canonicalizeForLookup(const QString& rawWindowId) const;
 
    QString currentAppIdFor(const QString& anyWindowId) const;
 
    void syncShortcutAdjustmentToSettings();
 
    void performToggleFloat(PhosphorTiles::TilingState* state, const QString& windowId, const QString& screenId);
 
    PhosphorTiles::TilingState* stateForWindow(const QString& windowId, QString* outScreenId = nullptr);
 
    QSet<QString> m_autotileFloatedWindows;
 
    PhosphorZones::LayoutRegistry* m_layoutManager = nullptr;
    PhosphorEngine::IWindowTrackingService* m_windowTracker = nullptr;
    Phosphor::Screens::ScreenManager* m_screenManager = nullptr;
    PhosphorEngine::IWindowRegistry* m_windowRegistry = nullptr;
    PhosphorTiles::ITileAlgorithmRegistry* m_algorithmRegistry = nullptr; 
    std::unique_ptr<AutotileConfig> m_config;
    std::unique_ptr<PerScreenConfigResolver> m_configResolver;
    std::unique_ptr<NavigationController> m_navigation;
    QTimer m_writeBackGuardTimer;
    QTimer m_settingsRetileTimer;
 
    // Persistence delegates (KConfig stays in WTA layer)
    std::function<void()> m_persistSaveFn;
    std::function<void()> m_persistLoadFn;
    std::function<bool(const QString&)> m_isWindowFloatingFn;
 
    QSet<QString> m_autotileScreens;
    QString m_algorithmId;
    bool m_algorithmEverSet = false; 
    QString m_activeScreen; // Last-focused screen (updated by onWindowFocused)
    QHash<PhosphorEngine::TilingStateKey, PhosphorTiles::TilingState*> m_screenStates; // Owned via Qt parent (this)
 
    QHash<QString, PhosphorEngine::TilingStateKey> m_windowToStateKey; // windowId -> owning state key
    QHash<QString, QSize> m_windowMinSizes; // windowId -> minimum size from KWin
 
    // Instance id → first-seen canonical windowId.
    //
    // Fallback for when no shared WindowRegistry is attached (unit tests).
    // With a registry, canonicalization delegates to it instead. Production
    // daemons always take the registry path, so this map stays empty.
    //
    // The canonical form is the FIRST windowId string we saw for a given
    // instance id. Subsequent arrivals with a mutated appId (Electron/CEF
    // apps that swap WM_CLASS mid-session) resolve back to that canonical
    // form so every map/PhosphorTiles::TilingState key in the engine stays consistent.
    QHash<QString, QString> m_canonicalByInstance;
 
    // Current desktop/activity context — used by tilingStateForScreen() to construct
    // TilingStateKey. Updated by setCurrentDesktop()/setCurrentActivity() BEFORE
    // updateAutotileScreens() runs on desktop/activity switch.
    int m_currentDesktop = 1;
    QString m_currentActivity;
    bool m_isDesktopContextSwitch = false;
 
    // Per-screen desktop override for sticky screens. When the KWin script
    // "virtualdesktopsonlyonprimary" pins all secondary-screen windows to all
    // desktops, the TilingStateKey desktop dimension becomes meaningless for
    // those screens. This map pins such screens to their original desktop so
    // currentKeyForScreen() returns the key of the existing PhosphorTiles::TilingState rather
    // than a new (empty) key after a desktop switch.
    QHash<QString, int> m_screenDesktopOverride;
 
    // Floating window IDs preserved across mode switches, per desktop/activity.
    // When autotile is deactivated, floated windows are saved here so that
    // re-enabling autotile restores them as floating regardless of screen.
    QHash<PhosphorEngine::TilingStateKey, QSet<QString>> m_savedFloatingWindows;
 
    // Pre-seeded window order for snapping → autotile transitions.
    // Keyed by stable EDID-based screen ID (Phosphor::Screens::ScreenIdentity::identifierFor).
    // Consumed by insertWindow() as windows arrive; also cleaned up by
    // removeWindow() if a pre-seeded window closes before arriving.
    QHash<QString, QStringList> m_pendingInitialOrders;
    QHash<QString, uint64_t> m_pendingOrderGeneration;
    // Screens whose pendingInitialOrders entry is "strict" — saved order
    // wins even when arrival order differs. Set by setInitialWindowOrder
    // (mode transition: the daemon intentionally pre-computed an order from
    // the previous mode's zones, and that order MUST be preserved).
    // Cleared after the order is fully consumed. Entries from the
    // deserialize / promoteSavedWindowOrders paths are NOT in this set —
    // for those, the saved position is "advisory": honored only when it
    // appends at the current tail, otherwise insertPosition takes over.
    // This is the behaviour users expect from their "After existing" /
    // "After focused" / "As main window" preference for new windows.
    QSet<QString> m_strictInitialOrderScreens;
 
    // Saved window orders from session persistence, keyed by full context.
    // On desktop/activity switch, orders for the new context are promoted into
    // m_pendingInitialOrders so windows arriving on the new desktop get their
    // saved ordering. Consumed once per context (removed after promotion).
    QHash<PhosphorEngine::TilingStateKey, QStringList> m_savedWindowOrders;
 
    // Pending restore queue for windows removed from autotile (close/reopen).
    // Keyed by appId (stable across KWin restarts). Multiple entries per appId
    // support multi-instance apps; consumed FIFO by insertWindow().
    // Analogous to snapping's PendingRestoreQueues.
    QHash<QString, QList<PendingAutotileRestore>> m_pendingAutotileRestores;
 
    // Disabled-context gate injected by the daemon adaptor. See
    // ShouldPersistRestorePredicate. Empty until the daemon wires it; while
    // empty every (screen, desktop, activity) tuple is treated as active —
    // the behaviour unit tests rely on.
    ShouldPersistRestorePredicate m_shouldPersistRestorePredicate{};
 
    // Zero-delay timer to coalesce promoteSavedWindowOrders() calls during
    // simultaneous desktop+activity switches. Without coalescing, the first
    // call (after setCurrentDesktop) would promote using the stale activity,
    // potentially consuming the wrong specific-activity entry.
    QTimer m_promoteOrdersTimer;
 
    // Per-screen overflow tracking with O(1) reverse-index lookups.
    OverflowManager m_overflow;
 
    bool m_retiling = false;
 
    // Queued-connection retile coalescing: windowOpened D-Bus calls arriving in
    // the same event loop pass are coalesced into a single retile per screen.
    // Uses QMetaObject::invokeMethod(Qt::QueuedConnection) which fires after
    // all currently-pending events are processed — no fixed delay needed.
    QSet<QString> m_pendingRetileScreens;
    bool m_retilePending = false;
 
    // Bounded retry for transient screen geometry failures.
    // When QScreen is temporarily unavailable (e.g. during Wayland desktop switch),
    // recalculateLayout cannot compute zone geometry. Rather than silently dropping
    // the retile (leaving stale zones), we retry after a short interval.
    // Per-screen retry counts prevent infinite loops; cleared on success or screen removal.
    static constexpr int MaxRetileRetries = 3;
    static constexpr int RetileRetryIntervalMs = 150;
    QTimer m_retileRetryTimer;
    QSet<QString> m_retileRetryScreens;
    QHash<QString, int> m_retileRetryCount;
 
    // Deferred focus: set by onWindowAdded, emitted after applyTiling so the
    // focus request arrives at KWin AFTER windowsTiled (whose onComplete raises
    // windows in tiling order). Without this, the raise loop buries the new window.
    QString m_pendingFocusWindowId;
 
    // Drag-insert preview state. When set, applyTiling() filters the dragged
    // window out of the windowsTiled batch so the KWin interactive move isn't
    // fought, while the remaining windows animate into their new positions.
    // Supports three entry modes (captured at begin() time for cancel restoration):
    //   - Same-screen reorder: window was already tiled/floating on targetScreenId
    //   - Cross-screen adoption: window was tracked on a different autotile screen
    //   - Fresh adoption: window was not tracked by the engine at all
    struct DragInsertPreview
    {
        QString windowId;
        QString targetScreenId;
        int lastInsertIndex = -1;
 
        // Prior-state restoration info (used on cancel)
        bool hadPriorState = false; // True if m_windowToStateKey contained windowId at begin
        PhosphorEngine::TilingStateKey
            priorKey; // Key of the prior PhosphorTiles::TilingState (meaningful iff hadPriorState)
        int priorRawIndex = -1; // Raw index in priorState->windowOrder() at begin
        bool priorFloating = false; // Prior floating flag in priorState
        bool priorSameScreen = false; // priorKey == currentKeyForScreen(targetScreenId)
 
        // Eviction info (used when the target stack is already at maxWindows
        // and the dragged window is a new member). The last tiled neighbour
        // is floated to make room; on cancel the eviction is undone, on
        // commit the evicted window is sent through the batch-float path so
        // its pre-tile geometry is restored.
        QString evictedWindowId;
    };
    std::optional<DragInsertPreview> m_dragInsertPreview;
 
    void processPendingRetiles();
};
 
} // namespace PhosphorTileEngine