SnapEngine.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
//
// FILE-SIZE EXCEPTION (sanctioned): SnapEngine is one class — the snap
// engine's whole public and internal surface — and C++ cannot split a class
// declaration across headers. The implementation is partitioned by concern
// under src/; shrinking this header means extracting collaborator classes,
// a deliberate refactor rather than a mechanical file split. Same rationale
// as AutotileEngine.h / daemon.h / windowtrackingadaptor.h.
 
#pragma once
 
#include <phosphorsnapengine_export.h>
#include <PhosphorEngine/EngineTypes.h>
#include <PhosphorZones/AssignmentEntry.h>
#include <PhosphorEngine/IVirtualDesktopManager.h>
#include <PhosphorSnapEngine/ISnapSettings.h>
#include <PhosphorEngine/IWindowTrackingService.h>
#include <PhosphorEngine/PerScreenStates.h>
#include <PhosphorEngine/PlacementEngineBase.h>
#include <PhosphorEngine/ScreenContextTracker.h>
#include <PhosphorSnapEngine/SnapState.h>
#include <PhosphorSnapEngine/PlacementDirective.h>
#include <PhosphorProtocol/NavigationTypes.h>
#include <PhosphorProtocol/WindowTypes.h>
#include <PhosphorRules/RuleEvaluator.h>
#include <QObject>
#include <QPointer>
#include <QRect>
#include <QSet>
#include <QString>
#include <QStringList>
#include <functional>
#include <optional>
#include <memory>
 
namespace PhosphorZones {
class IZoneDetector;
class LayoutRegistry;
}
 
namespace PhosphorEngine {
class IWindowRegistry;
}
 
// PhosphorRules::RuleEvaluator is included as a member type of
// std::optional below (needs a complete type at declaration); RuleSet
// is referenced only by pointer / reference, so a forward declaration would
// suffice — but including RuleEvaluator.h pulls in RuleSet.h
// transitively anyway, so leave the explicit forward decls out and let
// RuleEvaluator.h provide both.
 
namespace PhosphorSnapEngine {
 
class INavigationStateProvider;
class IZoneAdjacencyResolver;
class SnapNavigationTargetResolver;
 
class PHOSPHORSNAPENGINE_EXPORT SnapEngine : public PhosphorEngine::PlacementEngineBase
{
    Q_OBJECT
 
public:
    explicit SnapEngine(PhosphorZones::LayoutRegistry* layoutManager,
                        PhosphorEngine::IWindowTrackingService* windowTracker,
                        PhosphorZones::IZoneDetector* zoneDetector, PhosphorEngine::IVirtualDesktopManager* vdm,
                        QObject* parent = nullptr);
    ~SnapEngine() override;
 
    int currentVirtualDesktop() const;
    int currentVirtualDesktopForScreen(const QString& screenId) const;
    QString currentActivity() const;
 
    std::pair<QString, QRect> resolveCrossDesktopZone(const QString& currentZoneId, const QString& screenId,
                                                      int targetDesktop) const;
 
    QString entryZoneForCrossing(const QString& direction, const QString& neighbourScreen) const;
 
    QString windowInZoneOnScreen(const QString& zoneId, const QString& screenId) const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // IPlacementEngine — lifecycle
    // ═══════════════════════════════════════════════════════════════════════════
 
    bool isActiveOnScreen(const QString& screenId) const override;
    bool isEnabled() const noexcept override;
    using IPlacementEngine::windowOpened;
    void windowOpened(const QString& windowId, const QString& screenId, int minWidth, int minHeight) override;
 
    using ShouldRestorePredicate = std::function<bool(const QString& screenId)>;
 
    void setShouldRestorePredicate(ShouldRestorePredicate predicate)
    {
        m_shouldRestorePredicate = std::move(predicate);
    }
 
    using RestorePositionPredicate = std::function<bool(const QString& windowId)>;
 
    void setRestorePositionPredicate(RestorePositionPredicate predicate)
    {
        m_restorePositionPredicate = std::move(predicate);
    }
 
    using ManagedRestorePredicate = std::function<bool(const QString& windowId)>;
 
    void setManagedRestorePredicate(ManagedRestorePredicate predicate)
    {
        m_managedRestorePredicate = std::move(predicate);
    }
 
    using LiveModeResolver = std::function<PhosphorZones::AssignmentEntry::Mode(const QString& screenId)>;
    void setLiveModeResolver(LiveModeResolver resolver)
    {
        m_liveModeResolver = std::move(resolver);
    }
 
    using TilingEngineLiveResolver =
        std::function<bool(PhosphorZones::AssignmentEntry::Mode mode, const QString& screenId)>;
    void setTilingEngineLiveResolver(TilingEngineLiveResolver resolver)
    {
        m_tilingEngineLiveResolver = std::move(resolver);
    }
 
    using FloatPredicate = std::function<bool(const QString& windowId, const QString& screenId)>;
 
    void setFloatPredicate(FloatPredicate predicate)
    {
        m_floatPredicate = std::move(predicate);
    }
 
    using UnfloatFallbackPredicate = std::function<bool(const QString& windowId, const QString& screenId)>;
 
    void setUnfloatFallbackPredicate(UnfloatFallbackPredicate predicate)
    {
        m_unfloatFallbackPredicate = std::move(predicate);
    }
 
    using PlacementZonesResolver = std::function<PlacementDirective(const QString& windowId, const QString& screenId)>;
 
    void setPlacementZonesResolver(PlacementZonesResolver resolver)
    {
        m_placementZonesResolver = std::move(resolver);
    }
 
    void windowClosed(const QString& windowId) override;
    void windowFocused(const QString& windowId, const QString& screenId) override;
    void toggleWindowFloat(const QString& windowId, const QString& screenId) override;
    void setWindowFloat(const QString& windowId, bool shouldFloat, const QString& screenId = QString()) override;
    void saveState() override;
    void loadState() override;
 
    // Layout capability (see IPlacementEngine's Layout capability section)
    LayoutSupport layoutSupport() const override
    {
        return LayoutSupport::Placement;
    }
 
    // Cross-engine handoff
    QString engineId() const override
    {
        return QStringLiteral("snap");
    }
    void handoffReceive(const HandoffContext& ctx) override;
    void handoffRelease(const QString& windowId) override;
    QString screenForTrackedWindow(const QString& windowId) const override;
    bool isWindowTracked(const QString& windowId) const override;
 
    void resnapToNewLayout();
 
    void resnapCurrentAssignments(const QString& screenFilter = QString());
 
    void resnapFromAutotileOrder(const QStringList& autotileWindowOrder, const QString& screenId);
 
    QVector<PhosphorEngine::ZoneAssignmentEntry>
    calculateResnapEntriesFromAutotileOrder(const QStringList& autotileWindowOrder, const QString& screenId,
                                            const QStringList& preClaimedZoneIds = {});
 
    PhosphorProtocol::SnapAllResultList calculateSnapAllWindows(const QStringList& windowIds, const QString& screenId);
 
    void emitBatchedResnap(const QVector<PhosphorEngine::ZoneAssignmentEntry>& entries);
 
    void snapAllWindows(const QString& screenId);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Window restore (auto-snap on window open)
    // ═══════════════════════════════════════════════════════════════════════════
 
    PhosphorEngine::SnapResult
    resolveWindowRestore(const QString& windowId, const QString& screenId, bool sticky,
                         PhosphorEngine::WindowKind kind = PhosphorEngine::WindowKind::Unknown);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Autotile engine reference (for isActiveOnScreen routing)
    // ═══════════════════════════════════════════════════════════════════════════
 
    void setAutotileEngine(PhosphorEngine::IPlacementEngine* engine);
 
    void setWindowRegistry(QObject* registry) override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Per-screen state resolution
    //
    // The engine owns one SnapState per (screen, desktop, activity)
    // PlacementStateKey (via PerScreenStates) plus a single global-scalar holder
    // (m_globals, keyed under the empty-screen sentinel). Each per-key store now
    // tracks its OWN last-used zone; m_globals keeps the user-snapped classes (a
    // per-app preference, not a placement) and the single representative last-used
    // restored from disk. A window is placed
    // under the key derived from its screen on first snap/float and stays there
    // for its lifetime (the reverse map is authoritative); its screen is recorded
    // as a per-window value, updated in place, exactly as the former single store.
    // ═══════════════════════════════════════════════════════════════════════════
 
    SnapState* stateForWindow(const QString& windowId);
    const SnapState* stateForWindow(const QString& windowId) const;
 
    SnapState* globalState() const
    {
        return m_globals;
    }
 
    SnapState* snapState() const
    {
        return m_globals;
    }
 
    QList<SnapState*> allSnapStates() const;
 
    SnapState* stateForWindowOnScreen(const QString& windowId, const QString& screenId);
 
    void forgetWindow(const QString& windowId);
 
    bool migrateWindowToScreen(const QString& windowId, const QString& newScreenId);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Current-context feed (ScreenContextTracker)
    //
    // The daemon pushes the current virtual desktop / per-output desktop (#648) /
    // activity here so currentKeyForScreen resolves a window's owning
    // (screen, desktop, activity) key, mirroring the pushes it already makes into
    // AutotileEngine. Snap keys are per-monitor first (the load-bearing #724 fix);
    // the desktop/activity dimensions match autotile's per-context semantics.
    // ═══════════════════════════════════════════════════════════════════════════
 
    void setCurrentDesktop(int desktop) override;
    void setCurrentDesktopForScreen(const QString& screenId, int desktop) override;
    void setCurrentActivity(const QString& activity) override;
 
    // Reclaim per-(screen,desktop,activity) stores whose context no longer exists.
    // Without these the per-monitor stores accumulate across desktop/activity/output
    // removal (the global holder has an empty screenId, so it is never a prune
    // target). The daemon drives them from its desktop-count / activities-changed /
    // screenRemoved signals, mirroring AutotileEngine.
    QSet<int> desktopsWithActiveState() const override;
    void pruneStatesForDesktop(int removedDesktop) override;
    void pruneStatesForActivities(const QStringList& validActivities) override;
    void pruneStatesForRemovedScreen(const QString& physicalScreenId) override;
 
    // Float facade over the per-screen stores (the daemon's engine float
    // resolver/writer/lister route here instead of a single SnapState).
    bool isFloating(const QString& windowId) const;
    void setFloating(const QString& windowId, bool floating);
    QStringList floatingWindows() const;
 
    void applyNoMatchFloatDefault(const QString& windowId, const QString& screenId);
 
    QString zoneForWindow(const QString& windowId) const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Zone adjacency resolver (for daemon-driven navigation)
    // ═══════════════════════════════════════════════════════════════════════════
 
    void setZoneAdjacencyResolver(IZoneAdjacencyResolver* resolver);
 
    void setCrossSurfaceResolver(PhosphorEngine::ICrossSurfaceResolver* resolver) override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Navigation state provider
    // ═══════════════════════════════════════════════════════════════════════════
 
    void setNavigationStateProvider(INavigationStateProvider* provider);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Navigation (moved out of WindowTrackingAdaptor)
    //
    // Every method takes a PhosphorEngine::NavigationContext populated by the daemon's
    // shortcut handler. The engine uses ctx.windowId directly rather than
    // re-reading it from the WTA shadow, which is a step toward retiring
    // the SnapEngine -> WTA back-reference entirely. When ctx.windowId is
    // empty, the engine may consult m_navState->lastActiveWindowId() as a
    // best-effort fallback -- but in the normal path the daemon always
    // provides a resolved target.
    // ═══════════════════════════════════════════════════════════════════════════
 
    // ═══════════════════════════════════════════════════════════════════════════
    // IPlacementEngine — navigation overrides
    // ═══════════════════════════════════════════════════════════════════════════
 
    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 zoneNumber, const PhosphorEngine::NavigationContext& ctx) override;
 
    void rotateWindows(bool clockwise, const PhosphorEngine::NavigationContext& ctx) override;
 
    void reapplyLayout(const PhosphorEngine::NavigationContext& ctx) override;
 
    void reapplyManagedWindowAppearance() override;
 
    std::optional<PhosphorEngine::WindowPlacement> capturePlacement(const QString& windowId) const override;
 
    std::optional<PhosphorEngine::WindowPlacement> capturePlacementAtDesktop(const QString& windowId,
                                                                             int gateDesktop) const;
 
    void snapAllWindows(const PhosphorEngine::NavigationContext& ctx) override;
 
    void pushToEmptyZone(const PhosphorEngine::NavigationContext& ctx) override;
 
    void restoreFocusedWindow(const PhosphorEngine::NavigationContext& ctx) override;
 
    void toggleFocusedFloat(const PhosphorEngine::NavigationContext& ctx) override;
 
    void switchFocusBetweenFloatingAndTiling(const QString& screenId) override;
 
    void cycleFocus(bool forward, const PhosphorEngine::NavigationContext& ctx) override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Snap commit orchestration
    //
    // Full snap lifecycle: clear floating, assign to zone, update tracking,
    // emit state-changed signals. Owns the orchestration that was previously
    // on WindowTrackingService.
    // ═══════════════════════════════════════════════════════════════════════════
 
    void commitSnap(const QString& windowId, const QString& zoneId, const QString& screenId,
                    PhosphorEngine::SnapIntent intent = PhosphorEngine::SnapIntent::UserInitiated,
                    int virtualDesktop = 0);
 
    void commitMultiZoneSnap(const QString& windowId, const QStringList& zoneIds, const QString& screenId,
                             PhosphorEngine::SnapIntent intent = PhosphorEngine::SnapIntent::UserInitiated,
                             int virtualDesktop = 0);
 
    void uncommitSnap(const QString& windowId);
 
    PhosphorEngine::UnfloatResult resolveUnfloatGeometry(const QString& windowId, const QString& fallbackScreen) const;
    PhosphorEngine::UnfloatResult resolveUnfloatGeometry(const QString& windowId, const QString& fallbackScreen,
                                                         bool confineToFallbackScreen) const;
 
    PhosphorEngine::UnfloatResult resolveFallbackUnfloatGeometry(const QString& windowId,
                                                                 const QString& fallbackScreen) const;
 
    PhosphorProtocol::WindowGeometryList
    applyBatchAssignments(const QVector<PhosphorEngine::ZoneAssignmentEntry>& entries,
                          PhosphorEngine::SnapIntent intent = PhosphorEngine::SnapIntent::UserInitiated,
                          std::function<QString()> fallbackScreenResolver = {});
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Auto-snap calculations (moved from WTS)
    // ═══════════════════════════════════════════════════════════════════════════
 
    PhosphorEngine::SnapResult calculateSnapToPlacementRule(const QString& windowId, const QString& windowScreenName,
                                                            bool isSticky) const;
    PhosphorEngine::SnapResult calculateSnapToLastZone(const QString& windowId, const QString& windowScreenId,
                                                       bool isSticky) const;
    PhosphorEngine::SnapResult calculateSnapToEmptyZone(const QString& windowId, const QString& windowScreenId,
                                                        bool isSticky) const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Resnap / rotation calculations (moved from WTS)
    // ═══════════════════════════════════════════════════════════════════════════
 
    QVector<PhosphorEngine::ZoneAssignmentEntry> calculateResnapFromPreviousLayout();
    QVector<PhosphorEngine::ZoneAssignmentEntry>
    calculateResnapFromCurrentAssignments(const QString& screenFilter = QString()) const;
    QVector<PhosphorEngine::ZoneAssignmentEntry>
    calculateResnapFromAutotileOrder(const QStringList& autotileWindowOrder, const QString& screenId,
                                     const QStringList& preClaimedZoneIds = {}) const;
    QVector<PhosphorEngine::ZoneAssignmentEntry> calculateSnapAllWindowEntries(const QStringList& windowIds,
                                                                               const QString& screenId) const;
    QVector<PhosphorEngine::ZoneAssignmentEntry> calculateRotation(bool clockwise,
                                                                   const QString& screenFilter = QString()) const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Effect-reported windows (runtime flag — not persisted)
    // ═══════════════════════════════════════════════════════════════════════════
 
    void markWindowReported(const QString& windowId);
    const QSet<QString>& effectReportedWindows() const
    {
        return m_effectReportedWindows;
    }
 
    int pruneStaleWindows(const QSet<QString>& aliveWindowIds) override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // IPlacementEngine — state access
    //
    // Resolves the per-(screen,desktop,activity) SnapState for a screen via the
    // shared ScreenContextTracker + PerScreenStates. The non-const overload lazily
    // creates the store; an empty screenId resolves to the global-scalar holder.
    // ═══════════════════════════════════════════════════════════════════════════
 
    PhosphorEngine::IPlacementState* stateForScreen(const QString& screenId) override;
    const PhosphorEngine::IPlacementState* stateForScreen(const QString& screenId) const override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Internal navigation helpers (concrete SnapEngine methods that the
    // IPlacementEngine overrides delegate to)
    // ═══════════════════════════════════════════════════════════════════════════
 
    void pushFocusedToEmptyZone(const PhosphorEngine::NavigationContext& ctx);
 
    void rotateWindowsInLayout(bool clockwise, const QString& screenId);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Persistence delegate
    // ═══════════════════════════════════════════════════════════════════════════
 
    void setPersistenceDelegate(std::function<void()> saveFn, std::function<void()> loadFn)
    {
        m_saveFn = std::move(saveFn);
        m_loadFn = std::move(loadFn);
    }
 
    QString lastActiveScreenId() const
    {
        return m_lastActiveScreenId;
    }
 
    void setExcludeRuleSet(const PhosphorRules::RuleSet* ruleSet);
 
    using ExclusionQueryProvider =
        std::function<std::optional<PhosphorRules::WindowQuery>(const QString& windowId, const QString& screenHint)>;
 
    void setExclusionQueryProvider(ExclusionQueryProvider provider)
    {
        m_exclusionQueryProvider = std::move(provider);
    }
 
    bool isAppIdExcluded(const QString& appId) const;
 
    bool isWindowExcluded(const QString& windowId, const QString& screenHint = QString()) const;
 
Q_SIGNALS:
    // ═══════════════════════════════════════════════════════════════════════════
    // Signals (relayed via SnapAdaptor -> WTA -> D-Bus -> effect)
    // ═══════════════════════════════════════════════════════════════════════════
 
    void windowSnapStateChanged(const QString& windowId, const PhosphorProtocol::WindowStateEntry& entry);
 
    void windowFloatingClearedForSnap(const QString& windowId, const QString& screenId);
 
    void applyGeometryRequested(const QString& windowId, int x, int y, int width, int height, const QString& zoneId,
                                const QString& screenId, bool sizeOnly);
 
    void resnapToNewLayoutRequested(const QString& resnapData);
 
    void snapAllWindowsRequested(const QString& screenId);
 
    void applyGeometriesBatch(const PhosphorProtocol::WindowGeometryList& geometries, const QString& action);
 
private:
    PhosphorEngine::ISnapSettings* snapSettings() const;
 
    QString canonicalWindowId(const QString& rawWindowId) const;
 
    PhosphorEngine::PlacementStateKey currentKeyForScreen(const QString& screenId) const
    {
        return m_context.currentKeyForScreen(screenId);
    }
 
    SnapState* ensureStateForKey(const PhosphorEngine::PlacementStateKey& key);
 
    void forEachSnapAssignment(const std::function<void(const QString& windowId, const QStringList& zoneIds,
                                                        const QString& screenId, int desktop)>& fn) const;
 
    void syncGlobalLastUsedForRemovedZones(const QStringList& removedZones);
 
    const SnapState* lastUsedStateForScreen(const QString& screenId) const;
 
    void commitSnapImpl(const QString& windowId, const QStringList& zoneIds, const QString& screenId,
                        PhosphorEngine::SnapIntent intent, int virtualDesktop = 0);
 
    QString resolveUnfloatScreen(const QString& primaryScreen, const QString& fallbackScreen) const;
 
    PhosphorZones::LayoutRegistry* m_layoutManager = nullptr;
    PhosphorEngine::IWindowTrackingService* m_windowTracker = nullptr;
    // Per-(screen,desktop,activity) snap stores + the current-context tracker that
    // resolves a screen to its owning key. The daemon feeds the tracker the current
    // desktop / per-output desktop (#648) / activity, so each screen resolves to a
    // real {screenId, desktop, activity} key and gets its own SnapState (created
    // lazily on first placement). m_globals holds the global user-snapped classes
    // (and the representative last-used restored from disk, plus any screenless
    // float) under the empty-screen key so whole-store iterations pick it up
    // transparently; live last-used now lives in each per-screen store.
    PhosphorEngine::PerScreenStates<SnapState> m_states;
    PhosphorEngine::ScreenContextTracker m_context;
    SnapState* m_globals = nullptr;
    PhosphorEngine::IWindowRegistry* m_windowRegistry = nullptr;
    PhosphorZones::IZoneDetector* m_zoneDetector = nullptr;
    PhosphorEngine::IVirtualDesktopManager* m_virtualDesktopManager = nullptr;
    QPointer<QObject> m_autotileEngineObj;
    PhosphorEngine::IPlacementEngine* m_autotileEngineTyped = nullptr;
    IZoneAdjacencyResolver* m_zoneAdjacencyResolver = nullptr;
    // QObject identity of m_zoneAdjacencyResolver, kept so a replacement can
    // disconnect the previous resolver's destroyed guard (a stale guard firing
    // later would null the LIVE replacement). Mirrors m_autotileEngineObj.
    QPointer<QObject> m_zoneAdjacencyResolverObj;
    PhosphorEngine::ICrossSurfaceResolver* m_crossSurfaceResolver = nullptr;
    // Typed navigation-state provider — replaces the opaque QObject* m_wta
    // back-reference. Provides read-only access to compositor-layer shadows
    // (last-active window, last-active screen, last-cursor screen, frame
    // geometry). Not owned; must outlive SnapEngine.
    INavigationStateProvider* m_navState = nullptr;
    // QObject identity of m_navState — same stale-destroyed-guard rationale
    // as m_zoneAdjacencyResolverObj.
    QPointer<QObject> m_navStateObj;
    // Snap-mode navigation target resolver. Owned by SnapEngine — moved
    // here in Phase 5E from WindowTrackingAdaptor. Constructed lazily on
    // first navigation call (so the construction order isn't constrained
    // by the fact that SnapEngine has to exist before a resolver that
    // takes WTS + PhosphorZones::LayoutRegistry can be built).
    std::unique_ptr<SnapNavigationTargetResolver> m_targetResolver;
    QSet<QString> m_effectReportedWindows;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Float helpers (snapengine/float.cpp)
    //
    // The historical clearFloatingStateForSnap / assignToZones pair was
    // removed — all snap commits now route through commitSnapImpl.
    // ═══════════════════════════════════════════════════════════════════════════
 
    enum class UnfloatCause {
        UserToggle,
        Suspension,
    };
    bool unfloatToZone(const QString& windowId, const QString& screenId, UnfloatCause cause);
    bool applyGeometryForFloat(const QString& windowId, const QString& screenId);
    void applyFloatGeometryUnlessMinimized(const QString& windowId, const QString& screenId);
 
    SnapNavigationTargetResolver* ensureTargetResolver(const QString& action = QString());
 
    bool tryCrossDesktopMove(const QString& windowId, const QString& direction, const QString& screenId);
 
    bool tryCrossModeOutput(const QString& windowId, const QString& direction, const QString& screenId, bool swap);
 
    bool tryCrossDesktopFocus(const QString& focusedWindowId, const QString& direction, const QString& screenId);
 
    bool isWindowExcludedForAction(const QString& windowId, const QString& action, const QString& screenId);
 
    // `isAppIdExcluded` and `isWindowExcluded` are declared in the public
    // section above (so the unit tests can drive the wiring directly); full
    // docstrings live with those declarations.
 
    bool evaluateExcludeRules(const PhosphorRules::WindowQuery& query) const;
 
    const PhosphorRules::RuleSet* m_excludeRuleSet = nullptr;
    mutable std::optional<PhosphorRules::RuleEvaluator> m_excludeEvaluator;
 
    ExclusionQueryProvider m_exclusionQueryProvider{};
 
    // Persistence delegates (KConfig stays in adaptor layer)
    std::function<void()> m_saveFn;
    std::function<void()> m_loadFn;
 
    // Last-focused screen (updated by windowFocused)
    QString m_lastActiveScreenId;
 
    // Auto-snap entry gate. Empty until the daemon wires it; while empty
    // the engine treats every screen as active — preserving the
    // historical default that unit tests rely on. (The predicate's
    // signature is `bool(const QString& screenId)` — the desktop and
    // activity dimensions are resolved by the daemon-side closure at
    // call time, not passed in here; see ShouldRestorePredicate doc
    // above and discussion #461 item 7.)
    ShouldRestorePredicate m_shouldRestorePredicate{};
 
    // Unsnapped-position-restore gate. Empty until the daemon wires it; while
    // empty the engine marks floated windows floating but restores their position
    // only on the reopening screen — the historical behaviour unit tests rely on.
    // See RestorePositionPredicate doc above.
    RestorePositionPredicate m_restorePositionPredicate{};
 
    // Managed (snapped-to-zone) restore gate. Empty until the daemon wires it;
    // while empty the engine restores snapped records unconditionally — the
    // historical behaviour unit tests rely on. See ManagedRestorePredicate.
    ManagedRestorePredicate m_managedRestorePredicate{};
 
    // Live placement-mode resolver. Empty until the daemon wires it; while empty
    // the engine falls back to the layout registry's cascade. See LiveModeResolver
    // doc above.
    LiveModeResolver m_liveModeResolver{};
    TilingEngineLiveResolver m_tilingEngineLiveResolver{};
 
    // 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{};
 
    // Rule-driven unfloat-fallback gate. Empty until the daemon wires it;
    // while empty the ISnapSettings bool decides alone. See
    // UnfloatFallbackPredicate doc above.
    UnfloatFallbackPredicate m_unfloatFallbackPredicate{};
 
    // Rule-driven open-placement resolver (SnapToZone). Empty until the daemon
    // wires it; while empty no window is rule-snapped. See PlacementZonesResolver
    // doc above.
    PlacementZonesResolver m_placementZonesResolver{};
};
 
} // namespace PhosphorSnapEngine