# GridSpaces

A GNOME Shell extension that turns a chosen workspace into a flexible tiling
grid. Normal workspaces are left completely untouched.

> **Status: experimental / alpha.** GNOME Shell 48, Wayland & X11.
> Developed and tested inside a throwaway VM — a buggy shell extension can
> crash your session on Wayland. Try it the same way (see *Safety* below).

## What it does

- Mark any workspace as a **grid workspace** from the panel button (⊞).
- A grid workspace is a stack of **rows**; each row has its own column count.
  Every cell holds at most one window, which is resized to fill the cell.
- Any window entering a grid workspace auto-fills the first free cell.
  When the grid is full, the window bounces back to where it came from.
- **Drag a window onto another cell to swap** the two windows.
- **Alt+drag the divider lines** to resize adjacent rows / columns. Sizes are
  percentages of the work area and always sum to 100; a preview line follows
  the pointer and the change is applied on release.
- Removing a row / shrinking the grid pops the overflow windows to the
  nearest normal workspace.
- Coexists with Ubuntu's **Tiling Assistant**: its drop popup is suppressed
  only while a grid workspace is active, and restored otherwise.

## Install

```sh
git clone https://git.hangman-lab.top/hzhang/GridSpaces.git \
  ~/.local/share/gnome-shell/extensions/gridspaces@hzhang.local
```

Then log out and back in (Wayland cannot hot-load a new extension), and:

```sh
gnome-extensions enable gridspaces@hzhang.local
```

## Usage

1. Switch to the workspace you want to tile.
2. Click the ⊞ panel button → toggle **Grid workspace** on.
3. Use **Add row** and the per-row column steppers to shape the layout.
4. **Alt+drag** the divider lines to adjust row heights / column widths.
5. Open or drag windows in; drag a window onto another cell to swap.

## Safety

This is an in-development GNOME Shell extension. On a Wayland session an
unhandled error in a shell extension can crash the whole session. **Do not
add it to your autostart while iterating.** Test in a VM with a clean
snapshot, or at minimum enable it manually (never via the autostart list) so
a crash recovers to a clean desktop instead of a login loop.

## License

MIT