Merge pull request #6 from KonstantinMerkel/bugfix/phantom_retile

Bugfix/phantom retile

Author: KonstantinMerkel

.gitignore

@@ -2,5 +2,8 @@ node_modules/
 .DS_Store
 *.log
 extension.zip
+CLAUDE.md
+CODEX.md
+CURSOR.md
 GEMINI.md
 coverage/

AGENTS.md

@@ -0,0 +1,44 @@
+# Workflow Tiling AI Development Guidelines
+
+## Role & Mission
+You are an AI developer assisting with the Workflow Tiling GNOME Shell extension.
+
+## General Mandates
+
+### 1. Testing Mandate
+**ALWAYS** run unit tests before proposing a change.
+**ALWAYS** write unit tests for new features. A task is not considered "ready for testing" until unit tests are written and pass.
+```bash
+npm test
+```
+
+### 2. Commentary & Documentation Rules
+Documentation focuses on the current state and behavior of the system.
+Avoid numbered lists for documentation or commentary.
+Exclude explanations of why alternative approaches were rejected.
+Do not use temporal language such as "new", "now", or "replaced".
+Refrain from "diary comments" that describe the history or process of changes.
+
+**CRITICAL DOCS MANDATE**: Always keep documentation files (`architecture.md`, `layouts.md`, `README.md`, etc.) up-to-date when altering code functionality. If you change a class name, execution flow, or API, immediately update the relevant docs.
+
+### 3. Logging Suggestion
+It is highly suggested to use debuggable logging (`Logger` in `lib/logger.js`). When debugging complex flows, include verbose logs for state sequences to aid troubleshooting.
+
+### 4. Settings UI Design
+Follow a **"minimal clutter, expand only after needed"** design philosophy for `prefs.js`. 
+Examples from the current codebase:
+- "Inner Gaps" and "Outer Gaps" spinrows only appear when "Enable Gaps" is toggled on.
+- Custom shortcuts rows only appear when "Mode" is set to "Custom".
+- The Advanced JSON Editor page only mounts when explicitly toggled.
+Always use `Adw` (libadwaita) components. Bind visibility state dynamically to reduce visual noise for the average user.
+
+### 5. Gnome API Guidelines
+Always use the newest solutions and APIs for GNOME Shell.
+
+### 6. Event-Driven Architecture
+Avoid arbitrary timeouts. Rely on GNOME Shell signals (`size-changed`, `window-created`, etc.) or frame-synced deferrals (`GLib.idle_add`, `Meta.LaterType.BEFORE_REDRAW`) instead of `GLib.timeout_add`.
+
+## Cross References
+- **Architecture**: See `architecture.md` for discrete responsibilities and execution flow. **Note**: We rely on *insertion-order based slots* (historical tracking) rather than purely arbitrary visual spatial arrangements. `StateTracker` matches windows to slots via their internal IDs (`get_id()`).
+- **Layout JSONs**: See `layouts.md` for guidelines on how the Escalator layouts and transitions are formatted in JSON.
+- **Vision**: See `vision.md` for core philosophy and scaling design.

Makefile

@@ -0,0 +1,29 @@
+UUID = workflow-tiling@konstantin.dev
+EXT_DIR = ~/.local/share/gnome-shell/extensions/$(UUID)
+FILES = extension.js metadata.json lib/ schemas/ prefs.js
+
+.PHONY: all sync install test pack enable disable clean
+
+all: sync
+
+sync:
+	mkdir -p $(EXT_DIR)
+	cp -r $(FILES) $(EXT_DIR)/
+
+install: sync enable
+
+test:
+	npm test
+
+pack:
+	glib-compile-schemas schemas/ 2>/dev/null || true
+	zip -r extension.zip $(FILES)
+
+enable:
+	gnome-extensions enable $(UUID)
+
+disable:
+	gnome-extensions disable $(UUID)
+
+clean:
+	rm -f extension.zip

README.md

@@ -8,10 +8,13 @@ A deterministic customizable auto-tiler extension for GNOME Shell (GNOME 50+).
 - **Workspace Isolation**: Tiling states are unique to each GNOME workspace.
 - **Stability Focused**: Uses WindowWrapper object modeling and compositor-native synchronization (Meta.LaterType) to prevent race conditions and Shell crashes.
 
+## Recommended Extensions
+Workflow Tiling does not natively draw an active window border. For visual indication of the focused window, it is highly recommended to use an extension like **P7 Border** 
+
 ## Custom Layouts
 Layout transitions are configured via JSON string, supporting custom window counts and sizes.
 
-Optional `id` integer properties (1-indexed) in the JSON structure define how windows transition between states:
+Optional `id` (1-indexed) integer properties in the JSON structure define how windows transition between states. It is required for all elements:
 
 ```json
 {
@@ -36,12 +39,11 @@ Optional `id` integer properties (1-indexed) in the JSON structure define how wi
 Unit tests are written using **Vitest**.
 ```bash
 npm install
-npm test
+make test
 ```
 
 ### Installation
-To link the extension to your local GNOME Shell directory:
+To deploy the extension to your local GNOME Shell directory:
 ```bash
-ln -s $(pwd) ~/.local/share/gnome-shell/extensions/workflow-tiling@konstantin.dev
-gnome-extensions enable workflow-tiling@konstantin.dev
+make install
 ```

architecture.md

@@ -27,8 +27,9 @@ Encapsulates `Meta.Window`.
 Applies calculated geometry.
 Binds single-shot `size-changed` signals to detect external resizing.
 
-## WorkspaceGrid (`lib/workspace.js`)
-Tracks windows per workspace and monitor.
+## WorkspaceManager & WorkspaceLayout (`lib/workspace.js`)
+`WorkspaceManager` tracks multiple layouts across GNOME workspaces.
+`WorkspaceLayout` tracks windows per workspace and monitor.
 Calculates window slots based on insertion order.
 Provides window displacement and swapping logic.
 
@@ -37,14 +38,27 @@ Maintains stable ordered list of windows.
 Handles track and untrack operations.
 Swaps window positions.
 
+## DragManager (`lib/drag.js`)
+Tracks window drag-and-drop operations.
+Renders visual swap indicators.
+Triggers geometric swapping based on pointer intersections.
+
+## SettingsManager (`lib/settings.js`)
+Loads configuration preferences.
+Parses layout JSON into valid escalator transitions.
+
+## Logger (`lib/logger.js`)
+Provides debug and trace logging.
+Configurable output verbosity.
+
 ## Escalator (`lib/layout.js`)
 Generates tile geometries.
 Provides geometric estates based on current window count.
 
 ## Execution Flow
 Signal triggers event.
 Controller receives event.
-Controller updates WorkspaceGrid state.
+Controller updates WorkspaceLayout state.
 Controller schedules deferred retile.
 Retile queries Escalator for layouts.
 Retile invokes WindowWrapper to apply geometries.

layouts.md

@@ -0,0 +1,29 @@
+# Layout Customization (JSON)
+
+Workflow Tiling uses an "Escalator" system (`lib/layout.js`) to generate window estates dynamically. 
+Custom layout transitions are defined via a JSON object.
+
+## Structure
+The JSON keys represent the total number of windows on a monitor. The values are arrays of window geometry definitions for that count.
+
+```json
+{
+  "1": [
+    {"x": 0, "y": 0, "w": 100, "h": 100, "id": 1}
+  ],
+  "2": [
+    {"x": 0, "y": 0, "w": 50, "h": 100, "id": 1},
+    {"x": 50, "y": 0, "w": 50, "h": 100, "id": 2}
+  ]
+}
+```
+
+## Properties
+- `x`: X percentage offset (0 to 100)
+- `y`: Y percentage offset (0 to 100)
+- `w`: Width percentage (0 to 100)
+- `h`: Height percentage (0 to 100)
+- `id` (Required): The logical 1-indexed ID this window occupies. The IDs map to the insertion order of windows. E.g., `id: 1` is the oldest window, `id: 2` is the second oldest. It MUST be unique and cover 1 to the window count.
+
+## Fallback
+If the window count exceeds the highest key defined in the JSON, extra windows will fall back to floating mode (unmanaged by the auto-tiler).

lib/controller.js

@@ -71,21 +71,34 @@ export class TilingController {
      * Registers a window and initiates the One-Shot Signal sequence.
      */
     tilingRequest(window) {
-        if (window.unmanaged) return;
+        if (window.unmanaged) {
+            Logger.debug(`tilingRequest: Rejected unmanaged window`);
+            return;
+        }
+
+        Logger.debug(`tilingRequest: Initiating for window ID ${window.get_id ? window.get_id() : 'unknown'} ("${window.get_title ? window.get_title() : 'unknown'}")`);
 
         let wrapper = this._ensureWrapper(window);
-        if (!wrapper) return;
+        if (!wrapper) {
+            Logger.debug(`tilingRequest: Aborted. Wrapper creation rejected window.`);
+            return;
+        }
 
         wrapper.bindSignals();
         wrapper.bindSizeChanged();
 
         try {
             const context = this._resolveTilingContext(window, wrapper);
-            if (!context) return;
+            if (!context) {
+                Logger.debug(`tilingRequest: Aborted. No context resolved.`);
+                return;
+            }
 
             const { workspace, monitorIndex, monitorId, isRestoring, preferredSlot } = context;
+            Logger.debug(`tilingRequest: Context resolved -> Workspace: ${workspace.index ? workspace.index() : 'unknown'}, MonitorIndex: ${monitorIndex}, MonitorID: ${monitorId}, Restoring: ${isRestoring}`);
 
             if (this.monitorManager.checkEvacuation(window, wrapper, monitorId, workspace)) {
+                Logger.debug(`tilingRequest: Window evacuated. Updating cache and returning.`);
                 this._updateWrapperCache(wrapper, workspace, monitorIndex, monitorId);
                 return;
             }
@@ -94,6 +107,8 @@ export class TilingController {
             const finalPreferredSlot = isRestoring ? preferredSlot : (oldSlot !== undefined ? oldSlot : undefined);
             this._updateWrapperCache(wrapper, workspace, monitorIndex, monitorId);
             this._applyTrackingState(window, monitorId, workspace, isRestoring, finalPreferredSlot);
+            
+            Logger.debug(`tilingRequest: State applied. Scheduling retile.`);
             this._scheduleRetile(workspace, monitorId, monitorIndex);
         } catch (e) {
             Logger.warn(`Tiling attempt failed for "${wrapper ? wrapper.title : 'unknown'}"`, e);
@@ -198,7 +213,14 @@ export class TilingController {
 
     _scheduleRetile(workspace, monitorId, monitorIndex) {
         if (this._batchMode) return;
-        if (this.dragManager && this.dragManager._activeDrag) return;
+        if (this.dragManager && this.dragManager._activeDrag) {
+            this.dragManager._deferredRetiles = this.dragManager._deferredRetiles || [];
+            const exists = this.dragManager._deferredRetiles.some(r => r.workspace === workspace && r.monitorId === monitorId);
+            if (!exists) {
+                this.dragManager._deferredRetiles.push({workspace, monitorId, monitorIndex});
+            }
+            return;
+        }
 
         const key = `${workspace}-${monitorId}`;
 
@@ -251,7 +273,7 @@ export class TilingController {
      * This is useful during initialization or when the monitor layout drastically changes.
      */
     hydrate(workspace = null) {
-        Logger.info('Performing single-pass hydration sweep');
+        Logger.info(`Performing single-pass hydration sweep for workspace ${workspace && workspace.index ? workspace.index() : 'ALL'}`);
 
         let windows = [];
         if (workspace) {
@@ -260,22 +282,36 @@ export class TilingController {
             windows = global.display.list_all_windows();
         }
 
-        // Filter and sort active windows geometrically to preserve stable slots
-        const activeWindows = windows.filter(w => w && !w.unmanaged);
-        activeWindows.sort((a, b) => {
-            const rectA = a.get_frame_rect ? a.get_frame_rect() : { x: 0, y: 0 };
-            const rectB = b.get_frame_rect ? b.get_frame_rect() : { x: 0, y: 0 };
-            if (Math.abs(rectA.x - rectB.x) > 5) {
-                return rectA.x - rectB.x;
+        Logger.debug(`Hydrate: Found ${windows.length} total windows from shell.`);
+
+        // Filter and sort active windows by ID to preserve historical insertion order slots
+        const activeWindows = windows.filter(w => {
+            if (!w) {
+                Logger.debug(`Hydrate: Skipping null window object`);
+                return false;
+            }
+            if (w.unmanaged) {
+                Logger.debug(`Hydrate: Skipping unmanaged window ID ${w.get_id ? w.get_id() : 'unknown'}`);
+                return false;
             }
-            return rectA.y - rectB.y;
+            return true;
         });
+        
+        Logger.debug(`Hydrate: Filtered down to ${activeWindows.length} managed active windows.`);
 
+        activeWindows.sort((a, b) => {
+            const idA = a.get_id ? a.get_id() : 0;
+            const idB = b.get_id ? b.get_id() : 0;
+            return idA - idB;
+        });
         const restoringExtra = [...this._restoringWindows.keys()].filter(w => !windows.includes(w));
+        Logger.debug(`Hydrate: Adding ${restoringExtra.length} restoring windows not present in list.`);
         const allWindows = [...activeWindows, ...restoringExtra];
+        Logger.debug(`Hydrate: Final list sorted by ID. Sequence: ${allWindows.map(w => w.get_id ? w.get_id() : 'unknown').join(', ')}`);
 
         allWindows.forEach(window => {
             if (window) {
+                Logger.debug(`Hydrate: Issuing tiling request for window ID ${window.get_id ? window.get_id() : 'unknown'}`);
                 this.tilingRequest(window);
             }
         });

lib/drag.js

@@ -30,7 +30,8 @@ export class DragManager {
             this._handlePositionChanged(wrapper, layout, tracker, originalSlot, indicator);
         });
 
-        this._activeDrag = { window, originalSlot, indicator, signalId, lastHoveredSlot: -1 };
+        const origRect = window.get_frame_rect ? window.get_frame_rect() : { x: 0, y: 0, width: 0, height: 0 };
+        this._activeDrag = { window, originalSlot, indicator, signalId, lastHoveredSlot: -1, origRect };
     }
 
     /**
@@ -136,8 +137,14 @@ export class DragManager {
             this._activeDrag.indicator.destroy();
         }
 
+        const origRect = this._activeDrag.origRect;
         this._activeDrag = null;
 
+        if (this._deferredRetiles && this._deferredRetiles.length > 0) {
+            this._deferredRetiles.forEach(r => this.controller._scheduleRetile(r.workspace, r.monitorId, r.monitorIndex));
+            this._deferredRetiles = [];
+        }
+
         const wrapper = this.controller._windowWrappers.get(window);
         if (!wrapper || !wrapper.workspace || !wrapper.monitorId) return;
 
@@ -150,7 +157,13 @@ export class DragManager {
         const layout = this.controller.workspaceManager.getLayout(workspace);
 
         const [x, y] = global.get_pointer();
-        layout.swapWindowByPointer(wrapper.monitorId, window, x, y, monitorRect, gaps);
-        this.controller._scheduleRetile(wrapper.workspace, wrapper.monitorId, wrapper.monitorIndex);
+        const swapped = layout.swapWindowByPointer(wrapper.monitorId, window, x, y, monitorRect, gaps);
+        
+        const currRect = window.get_frame_rect ? window.get_frame_rect() : { x: 0, y: 0, width: 0, height: 0 };
+        const rectChanged = currRect.x !== origRect.x || currRect.y !== origRect.y || currRect.width !== origRect.width || currRect.height !== origRect.height;
+
+        if (swapped || rectChanged) {
+            this.controller._scheduleRetile(wrapper.workspace, wrapper.monitorId, wrapper.monitorIndex);
+        }
     }
 }

lib/signals.js

@@ -188,9 +188,13 @@ export class SignalListener {
     }
 
     _addWindow(window) {
-        if (window && this._shouldTile(window)) {
-            this.controller.tilingRequest(window);
-        }
+        if (!window) return;
+        GLib.idle_add(GLib.PRIORITY_DEFAULT, () => {
+            if (this._shouldTile(window)) {
+                this.controller.tilingRequest(window);
+            }
+            return GLib.SOURCE_REMOVE;
+        });
     }
 
     rebindKeybindings() {

vision.md

@@ -9,8 +9,7 @@ Layout transitions are predictable, minimal, and fully customizable. The system
 ### Deterministic Layout Flow
 
 - **Single Window**: Full screen layout covering all available space.
-- **Two Windows**: Vertical split dividing space equally.
-- **Three Windows**: Customizable split using equal proportions or master/stack splits.
+- **Multiple Windows**: Fully customizable geometric distributions via JSON configuration.
 - **Fallback**: Additional windows exceeding configured count run in floating mode.
 
 ## Implementation Standards
@@ -26,7 +25,5 @@ Layout transitions are predictable, minimal, and fully customizable. The system
 -   **Workspace Isolation**: Tiling is scoped per GNOME workspace.
 
 ## Future Roadmap
-1.  Custom layout creation via configuration.
-2.  Keyboard and mouse shortcuts for manual re-ordering.
-3.  Active window border, for now just use an extension like focus on active window/ P7 Border.
-4.  Implement type safety (JSDoc + `@girs` types and `jsconfig.json`).
+1.  Implement type safety
+2.  Make some GNOME native shortcuts as remove active window editable in extension.