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/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 <QObject>
#include <QRect>
#include <QSet>
#include <QSize>
#include <QString>
#include <QStringList>
#include <QTimer>
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
 
#include <PhosphorTileEngine/OverflowManager.h>
 
namespace PhosphorZones {
class Layout;
class LayoutRegistry;
}
 
namespace PhosphorTileEngine {
 
class AutotileConfig;
 
class NavigationController;
class PerScreenConfigResolver;
} // namespace PhosphorTileEngine
 
// ScreenManager lives in libs/phosphor-screens; forward-declared here.
namespace PhosphorScreens {
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,
                            PhosphorScreens::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& rawWindowId) const override;
 
    bool isWindowFloatingInAutotile(const QString& windowId) const;
 
    QStringList allFloatingWindows() const;
 
    // 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 setCurrentDesktopForScreen(const QString& screenId, int desktop) override;
 
    void clearCurrentDesktopForScreen(const QString& screenId) override;
 
    void setCrossSurfaceResolver(PhosphorEngine::ICrossSurfaceResolver* resolver) override
    {
        m_crossSurfaceResolver = resolver;
    }
 
    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);
    }
 
    using RestorePositionPredicate = std::function<bool(const QString& windowId)>;
 
    void setRestorePositionPredicate(RestorePositionPredicate predicate)
    {
        m_restorePositionPredicate = std::move(predicate);
    }
 
    using FloatPredicate = std::function<bool(const QString& windowId)>;
 
    void setFloatPredicate(FloatPredicate predicate)
    {
        m_floatPredicate = std::move(predicate);
    }
 
    // 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;
    }
 
    void onWindowResized(const QString& rawWindowId, const QRect& oldFrame, const QRect& newFrame,
                         const QString& screenId) override;
    // ═══════════════════════════════════════════════════════════════════════════
    // 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);
 
    // Inject the per-context (window-rule) gap-override provider — forwarded to
    // PerScreenConfigResolver. The daemon supplies the screen's current-context
    // gap overrides so tiled windows honour context gap rules like snapping does.
    void setContextGapProvider(std::function<QVariantMap(const QString& screenId)> provider);
 
    // Mark the active (screen, desktop, activity) state's split ratio / master
    // count as user-tuned so propagateGlobalSplitRatio/MasterCount leaves it
    // alone — the adjustment stays local to that desktop instead of bleeding into
    // the global config. Called by NavigationController after a shortcut/resize
    // adjustment in the no-per-screen-override case.
    void noteSplitRatioUserTuned(const QString& screenId);
    void noteMasterCountUserTuned(const QString& screenId);
 
    // 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;
 
    QString entryWindowForCrossing(const QString& screenId, const QString& direction) const;
    int windowOrderIndexForWindow(const QString& screenId, const QString& windowId) const;
    void reapplyLayout(const PhosphorEngine::NavigationContext& ctx) override;
    void reapplyManagedWindowAppearance() override;
    std::optional<PhosphorEngine::WindowPlacement> capturePlacement(const QString& windowId) const 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;
 
    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& rawWindowId);
    void clearAutotileFloated(const QString& rawWindowId);
    bool isAutotileFloated(const QString& rawWindowId) 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);
 
private:
    void connectSignals();
    bool insertWindow(const QString& windowId, const QString& screenId);
    // Passive float-state sync after insertWindow() places a window: notify the
    // daemon it opened floating (matched Float rule / restored saved float), or
    // clear a stale WTS float when it was placed tiled. Shared by onWindowAdded
    // and backfillWindows so the two cannot diverge.
    void emitInsertFloatStateSync(const QString& windowId, const QString& screenId);
    void insertWindowByConfigOrder(PhosphorTiles::TilingState* state, const QString& windowId);
    void removeWindow(const QString& windowId);
 
    QString removeTrackedWindowNoRetile(const QString& windowId);
 
    void dropClosedWindowFromDragPreview(const QString& windowId);
    bool storeWindowMinSize(const QString& windowId, int minWidth, int minHeight);
    bool recalculateLayout(const QString& screenId);
    void applyTiling(const QString& screenId);
 
    bool applyTreeResizeReflow(PhosphorTiles::TilingState* state, const QString& windowId, const QRect& oldFrame,
                               const QRect& newFrame, 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;
 
    void releaseScreenStateForTeardown(const QString& screenId, PhosphorTiles::TilingState* state,
                                       QStringList& releasedWindows, bool drainOverflow = true);
 
    void migrateWindowBetweenKeys(const QString& windowId, const PhosphorEngine::TilingStateKey& oldKey,
                                  const QString& newScreenId);
 
    void revalidateWindowContext(const QString& windowId, const QString& screenId);
 
    PhosphorEngine::TilingStateKey currentKeyForScreen(const QString& screenId) const
    {
        // Precedence (highest first):
        //   1. sticky-pin override (m_screenDesktopOverride) — a CORRECTNESS
        //      constraint: sticky on-all-desktops windows must keep their state on
        //      the desktop where they live, so the pin must win;
        //   2. per-output virtual desktop (m_screenCurrentDesktop, Plasma 6.7) —
        //      the normal per-screen input;
        //   3. the global current desktop (m_currentDesktop) — fallback.
        int desktop = m_currentDesktop;
        if (auto perOut = m_screenCurrentDesktop.constFind(screenId); perOut != m_screenCurrentDesktop.constEnd()) {
            desktop = perOut.value();
        }
        if (auto pin = m_screenDesktopOverride.constFind(screenId); pin != m_screenDesktopOverride.constEnd()) {
            desktop = pin.value();
        }
        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);
 
    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 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;
    PhosphorScreens::ScreenManager* m_screenManager = nullptr;
    PhosphorEngine::ICrossSurfaceResolver* m_crossSurfaceResolver = 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;
 
    // Floated-position-restore gate. Empty until the daemon wires it; while empty
    // the engine always re-applies a floated window's recorded position (historical
    // behaviour). See RestorePositionPredicate doc above.
    RestorePositionPredicate m_restorePositionPredicate{};
 
    // Rule-driven open-floating gate. Empty until the daemon wires it; while empty
    // no window is rule-floated. See FloatPredicate doc above.
    FloatPredicate m_floatPredicate{};
 
    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)
 
    // Screen+desktop states whose split ratio / master count the user has
    // explicitly tuned (keyboard shortcut or interactive resize). propagateGlobal*
    // skips these so a per-desktop tweak survives a settings refresh and is never
    // written into the global config — keeping the adjustment local to that
    // (screen, desktop, activity). Cleared on an algorithm switch and when the
    // user changes the corresponding global value in settings. This is
    // within-session state only: it is not persisted, so the per-desktop tweak
    // does not survive a daemon restart (neither does the value it guards —
    // autotile persistence is per-window, not per-desktop ratio/count).
    QSet<PhosphorEngine::TilingStateKey> m_userTunedSplitRatio;
    QSet<PhosphorEngine::TilingStateKey> m_userTunedMasterCount;
 
    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;
    bool m_desktopContextEverSet = false;
    bool m_activityContextEverSet = 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;
 
    // Per-screen current virtual desktop under Plasma 6.7 "switch desktops
    // independently for each screen" (#648). Fed by setCurrentDesktopForScreen
    // from the daemon's per-output desktop reports. Distinct from
    // m_screenDesktopOverride (the sticky-pin map): the sticky pin is a
    // correctness constraint and wins in currentKeyForScreen; this is the normal
    // per-screen input. Empty when per-output desktops aren't in use, so every
    // screen falls back to m_currentDesktop.
    QHash<QString, int> m_screenCurrentDesktop;
 
    // Pre-seeded window order for snapping → autotile transitions.
    // Keyed by stable EDID-based screen ID (PhosphorScreens::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 seeded by
    // setInitialWindowOrder (mode transition) are the strict ones; advisory
    // entries reconstructed per-window from the placement store are NOT in this
    // set — for those the saved position is 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;
 
    // 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