AutotileEngine.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
//
// FILE-SIZE EXCEPTION (sanctioned): AutotileEngine is one class — the tiling
// engine's whole public and internal surface — and C++ cannot split a class
// declaration across headers. The IMPLEMENTATION is already partitioned by
// concern under src/autotileengine/; shrinking this header means extracting
// collaborator classes (drag preview, script-state stash, per-screen config),
// which is a deliberate refactor, not a mechanical file split. Same rationale
// as plasmazoneseffect.h / daemon.h / windowtrackingadaptor.h.
 
#pragma once
 
#include <phosphortileengine_export.h>
#include <PhosphorEngine/EngineTypes.h>
#include <PhosphorLayoutApi/EdgeGaps.h>
#include <PhosphorEngine/IWindowRegistry.h>
#include <PhosphorEngine/IWindowTrackingService.h>
#include <PhosphorEngine/PerScreenStates.h>
#include <PhosphorEngine/PlacementEngineBase.h>
#include <PhosphorEngine/ScreenContextTracker.h>
#include <PhosphorTileEngine/IAutotileSettings.h>
#include <PhosphorTiles/TilingState.h>
#include <QHash>
#include <QJsonObject>
#include <QObject>
#include <QRect>
#include <QSet>
#include <QSize>
#include <QString>
#include <QStringList>
#include <QTimer>
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
 
#include <PhosphorTileEngine/AutotileEngineTypes.h>
#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
    {
        // Canonicalize like every sibling predicate (isWindowTiled,
        // screenForTrackedWindow): callers pass raw daemon/effect composite
        // ids, and a mutated-appId window must still resolve to its
        // tracked entry.
        return m_states.hasWindow(canonicalizeForLookup(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 capturedWindowOrder(screenId);
    }
    QStringList capturedWindowOrder(const QString& screenId) const;
    QString managedFocusedWindow(const QString& screenId) const override;
    int stickyPinnedDesktopForScreen(const QString& screenId) const override
    {
        return m_context.stickyPinnedDesktop(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;
 
    void pruneStatesForRemovedScreen(const QString& physicalScreenId) override;
 
    int currentDesktop() const noexcept
    {
        return m_context.currentDesktop();
    }
 
    const QString& currentActivity() const noexcept
    {
        return m_context.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, const QString& screenIdHint)>;
 
    void setRestorePositionPredicate(RestorePositionPredicate predicate)
    {
        m_restorePositionPredicate = std::move(predicate);
    }
 
    using FloatPredicate = std::function<bool(const QString& windowId, const QString& screenId)>;
 
    void setFloatPredicate(FloatPredicate predicate)
    {
        m_floatPredicate = std::move(predicate);
    }
 
    // Cross-engine handoff (see PhosphorEngine/IPlacementEngine.h for contract)
    // Layout capability (see IPlacementEngine's Layout capability section)
    LayoutSupport layoutSupport() const override
    {
        return LayoutSupport::Placement;
    }
 
    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
    {
        return m_states.keyForWindow(canonicalizeForLookup(windowId)).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);
 
    void setScrollingModeResolver(
        std::function<bool(const QString& screenId, int desktop, const QString& activity)> resolver)
    {
        m_scrollingModeResolver = std::move(resolver);
    }
 
    // 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;
    ::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;
    PhosphorTiles::AutotileInsertPosition effectiveInsertPosition(const QString& screenId) const;
    qreal effectiveSplitRatioStep(const QString& screenId) const override;
    int runtimeMaxWindows() const override;
    std::optional<int> savedMaxWindowsForAlgorithm(const QString& algorithmId) const override;
    QString effectiveAlgorithmId(const QString& screenId) const;
    PhosphorTiles::TilingAlgorithm* effectiveAlgorithm(const QString& screenId) const;
 
    void clearScreenScheduling(const QString& screenId);
 
    void clearPendingInitialOrder(const QString& screenId);
 
    void purgeFromPendingOrders(const QString& windowId);
 
    void notifyAlgorithmWindowAdded(PhosphorTiles::TilingState* state, const QString& screenId,
                                    const QString& windowId);
 
    void requestPostRetileFocus(const QString& screenId, const QString& windowId);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // 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 = kDefaultSplitRatioStep) override;
 
    Q_INVOKABLE void decreaseMasterRatio(qreal delta = kDefaultSplitRatioStep) 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 switchFocusBetweenFloatingAndTiling(const QString& screenId) override;
 
    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 spanFocusedInDirection(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 on the concrete engine.
    void rotateWindows(bool clockwise, const QString& screenId);
 
    Q_INVOKABLE void setWindowFloat(const QString& windowId, bool shouldFloat,
                                    const QString& screenId = QString()) 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;
    bool claimCrossScreenReopen(const QString& windowId, const QString& openingScreenId, int minWidth,
                                int minHeight) override;
    QString heldScreenForWindow(const QString& windowId) const override;
 
    void windowMinSizeUpdated(const QString& windowId, int minWidth, int minHeight) override;
    QSize windowMinimumSize(const QString& windowId) const override;
 
    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& rawWindowId, const QString& screenId) override;
 
    void updateDragInsertPreview(int insertIndex);
 
    void updateDragInsertPreview(const DragInsertTarget& target) override;
 
    void commitDragInsertPreview() override;
 
    void cancelDragInsertPreview() override;
 
    int computeDragInsertIndexAtPoint(const QString& screenId, const QPoint& cursorPos) const;
 
    DragInsertTarget computeDragInsertTargetAtPoint(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();
    }
 
    QString dragInsertPreviewPriorScreenId() const override
    {
        return m_dragInsertPreview && m_dragInsertPreview->hadPriorState ? m_dragInsertPreview->priorKey.screenId
                                                                         : 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.
 
    // windowFloatingChanged (emitted from performToggleFloat and
    // setWindowFloat with user-intent semantics: the downstream handler
    // restores pre-tile geometry, shows the navigation OSD, etc.),
    // activateWindowRequested, and navigationFeedback are inherited from
    // PlacementEngineBase. Plain comments, not a doxygen block — this class
    // declares no signal of those names for a doc block to attach to.
 
    // 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;
 
    QRect lastManagedRect(const QString& rawWindowId) const 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, const QString& screenId);
    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;
 
    bool releaseScreenStateForTeardown(const QString& screenId, PhosphorTiles::TilingState* state,
                                       QStringList& releasedWindows, bool drainOverflow = true,
                                       bool clearScreenOrderMaps = 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 and the sticky-pin / per-output subtleties live in the
        // shared ScreenContextTracker (sticky-pin override > per-output desktop >
        // global desktop; activity = current activity).
        return m_context.currentKeyForScreen(screenId);
    }
 
    enum class PropagateScope {
        CurrentContext,
        AllContexts,
    };
 
    void propagateGlobalSplitRatio(PropagateScope scope = PropagateScope::CurrentContext);
 
    void propagateGlobalMasterCount(PropagateScope scope = PropagateScope::CurrentContext);
 
    void backfillWindows();
 
    void retileScreen(const QString& screenId);
 
    void scheduleRetileRetry(const QString& screenId);
 
    void processRetileRetries();
 
    // ═══════════════════════════════════════════════════════════════════════════════
    // Helper Methods
    // ═══════════════════════════════════════════════════════════════════════════════
 
    bool cleanupPendingOrderIfResolved(const QString& screenId);
    void schedulePendingOrderTimeout(const QString& screenId, uint64_t generation);
 
    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);
 
    void toggleWindowFloatAs(const QString& rawWindowId, const QString& screenId, const QString& failureAction);
 
    PhosphorTiles::TilingState* stateForWindow(const QString& windowId, QString* outScreenId = nullptr);
 
    QSet<QString> m_autotileFloatedWindows;
 
    PhosphorZones::LayoutRegistry* m_layoutManager = nullptr;
    std::function<bool(const QString& screenId, int desktop, const QString& activity)> m_scrollingModeResolver;
    PhosphorEngine::IWindowTrackingService* m_windowTracker = nullptr;
    PhosphorScreens::ScreenManager* m_screenManager = nullptr;
    PhosphorEngine::ICrossSurfaceResolver* m_crossSurfaceResolver = nullptr;
    PhosphorEngine::IWindowRegistry* m_windowRegistry = nullptr;
    QMetaObject::Connection m_appIdResolverHook;
    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{};
 
    // MigrationArrival moved to AutotileEngineTypes.h; alias keeps the
    // AutotileEngine::MigrationArrival spelling valid for existing call sites.
    using MigrationArrival = ::PhosphorTileEngine::MigrationArrival;
    std::optional<MigrationArrival> m_migrationArrival;
 
    bool insertShouldFloat(const QString& windowId, const QString& screenId) const;
 
    QSet<QString> m_autotileScreens;
    QString m_algorithmId;
    bool m_algorithmEverSet = false; 
    bool m_refreshingFromSettings = false;
    QString m_activeScreen; // Last-focused screen (updated by onWindowFocused)
 
    // Per-screen tiling states + the windowId→owning-key reverse map. States are
    // owned via Qt parent (this); PerScreenStates holds only the two maps and
    // their lockstep bookkeeping — engine-specific lifecycle stays in this class.
    PhosphorEngine::PerScreenStates<PhosphorTiles::TilingState> m_states;
 
    // 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;
 
    // Script-state bags rescued from TilingStates that a teardown destroys, so a
    // re-created state for the same key can pick its bag back up. See
    // StashedScriptState in AutotileEngineTypes.h for the full rationale (harvest
    // rules, the algorithm tag, split-tree carry). The alias keeps the
    // AutotileEngine::StashedScriptState spelling valid for existing call sites.
    using StashedScriptState = ::PhosphorTileEngine::StashedScriptState;
    std::unordered_map<PhosphorEngine::TilingStateKey, StashedScriptState> m_scriptStateStash;
 
    void stashScriptState(const PhosphorEngine::TilingStateKey& key, PhosphorTiles::TilingState* state);
 
    void restoreStashedScriptState(const PhosphorEngine::TilingStateKey& key, PhosphorTiles::TilingState* state);
 
    void restoreStashedSplitTree(const PhosphorEngine::TilingStateKey& key, PhosphorTiles::TilingState* state,
                                 const PhosphorTiles::TilingAlgorithm* algo);
 
    void dropStashedScriptStatesForAlgorithmChange(const QString& screenId, const QString& newAlgorithmId);
 
    QHash<QString, QSize> m_windowMinSizes; // windowId -> minimum size from KWin
 
    // Canonical windowId → tile rect last emitted for it by applyTiling.
    // Backs lastManagedRect(): deliberately NOT cleared when the window
    // leaves the tiled state (that survival is the point — see the base
    // doc). Cleared on exactly two events: a genuine cross-screen move off
    // an autotile screen (the reposition has already moved the frame off
    // the old tile rect) and stale-window pruning. Everything else KEEPS
    // the entry — windowClosed (the effect notifies autotile before
    // WindowTracking, so the orchestrator's close capture and its tile-rect
    // guard run after this engine's teardown), handoffRelease (the adopting
    // engine's capture runs right after the release), and
    // releaseScreenStateForTeardown (windows still open) — because in each
    // the live frame can still be the tile rect, exactly when the
    // orchestrator's guard needs this memory. Closed windows' entries are
    // reclaimed by pruneStaleWindows, whose sweep is independent of
    // tracking. Used solely for an exact frame comparison, so a stale rect
    // is harmless.
    QHash<QString, QRect> m_lastAppliedTileRect;
 
    // 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 — the global current desktop, per-output
    // desktop overrides (#648), the sticky-desktop pin, the current activity, and
    // the "ever set" arming flags. Used by tilingStateForScreen() to construct
    // the owning key via currentKeyForScreen(). Fed by setCurrentDesktop()/
    // setCurrentActivity()/setCurrentDesktopForScreen() BEFORE updateEngineScreens()
    // runs on a desktop/activity switch.
    PhosphorEngine::ScreenContextTracker m_context;
 
    // Armed by a genuine desktop/activity switch (see the setCurrent* mutators);
    // consumed by setAutotileScreens()/the desktop-switch pass. Engine-specific,
    // so it stays here rather than in the shared ScreenContextTracker.
    bool m_isDesktopContextSwitch = false;
 
    // Pre-seeded window order for snapping → autotile transitions.
    // Keyed by stable EDID-based screen ID (PhosphorScreens::ScreenIdentity::identifierFor).
    // Consumed by the strict seed in setAutotileScreens() (visible windows,
    // eagerly) and by insertWindow() as remaining windows arrive; purged
    // per-window via purgeFromPendingOrders (close, cap rejection), swept
    // by pruneStaleWindows, and reaped by the pending-order timeout — which
    // deliberately RETAINS an order holding live minimized placeholders, so
    // those entries persist until the window opens or closes.
    QHash<QString, QStringList> m_pendingInitialOrders;
    QHash<QString, uint64_t> m_pendingOrderGeneration;
    uint64_t m_pendingOrderSerial = 0;
    // 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).
    // Lifetime is TIED to the pending order's own: cleared wherever the
    // order is removed (full consumption, per-window purge emptying it,
    // stale-window sweep, timeout reap, screen teardown) — an order retained
    // for a minimized placeholder keeps its strict flag with it. Entries seeded by
    // setInitialWindowOrder (mode transition) are the strict ones, and it is the
    // only producer in the tree, so every entry is strict today. Advisory
    // entries reconstructed per-window from the placement store would NOT be 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, keyed by screen: set by onWindowAdded and
    // requestPostRetileFocus, emitted after that screen's 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. Per-screen so an entry stranded by a no-op retile cannot be
    // consumed by another screen's batch and activate the wrong window.
    QHash<QString, QString> m_pendingFocusByScreen;
 
    // Focus-before-track reseed: a windowFocused() notification can arrive before
    // the window it names is tracked in a TilingState — most visibly on daemon
    // restart, where the effect re-notifies the active window during bring-up but
    // the window re-announce (windowsOpenedBatch) lands afterwards. onWindowFocused
    // would otherwise drop that focus, leaving a focus-driven layout (Theater) with
    // no focused window until the user clicks around. Stash the dropped id here and
    // replay it in onWindowAdded once the window is tracked.
    QString m_pendingFocusReseedWindowId;
 
    // DragInsertPreview moved to AutotileEngineTypes.h; alias keeps the
    // AutotileEngine::DragInsertPreview spelling valid for existing call sites.
    using DragInsertPreview = ::PhosphorTileEngine::DragInsertPreview;
    std::optional<DragInsertPreview> m_dragInsertPreview;
 
    void processPendingRetiles();
};
 
} // namespace PhosphorTileEngine