Originally forked from pop-shell, Mosaic is a keyboard-driven layer for GNOME Shell that was which allows for quick and sensible navigation and management of windows. It is an opinionated GNOME extension that aims for simple and intuitive window management as well as minimal configuration and sane defaults.

With pop-shell as a starting point, this project is intended to implement mosaic-style window management as defined in GNOME's Rethinking Window Management blog post. These changes are not yet implemented, but are being actively developed.

GNU Make and TypeScript are also required to build the project.

Proper functionality of the shell requires modifying GNOME's default keyboard shortcuts. For a local installation, run make local-install.

If you want to uninstall the extension, you may invoke make uninstall, and then open the "Keyboard Shortcuts" panel in GNOME Settings to select the "Reset All.." button in the header bar.

Features that are shared between floating and auto-tiling modes.

These are key to many of the shortcuts utilized by tiling window managers. This document will henceforth refer to these keys as <Direction>, which default to the following keys:

This mode is activated with Super + Return.

Window management mode activates additional keyboard control over the size and location of the currently-focused window. The behavior of this mode changes slightly based on whether you are in auto-tile mode, or in the default floating mode. In the default mode, an overlay is displayed snapped to a grid, which represents a possible future location and size of your focused window. This behavior changes slightly in auto-tiling mode, where resizes are performed immediately and overlays are only shown when swapping windows.

Activating this enables the following behaviors:

When not in window management mode, pressing Super + <Direction> will shift window focus to a window in the given direction. This is calculated based on the distance between the center of the side of the focused window that the window is being shifted from, and the opposite side of windows surrounding it.

Switching focus to the left will calculate from the center of the east side of the focused window to the center of the west side of all other windows. The window with the least distance is the window we pick.

Gaps improve the aesthetics of tiled windows and make it easier to grab the edge of a specific window. We've decided to add support for inner and outer gaps, and made these settings configurable in the extension's popup menu.

Windows with server-side decorations may have their title bars completely hidden, resulting in additional screen real estate for your applications, and a visually cleaner environment. This feature can be toggled in the extension's popup menu. Windows can be moved with the mouse by holding Super when clicking and dragging a window to another location, or using the keyboard shortcuts native to gnome-mosaic. Windows may be closed by pressing Super + Q, and maximized with Super + M.

This is the default mode of Mosaic, which combines traditional floating window management, with optional tiling window management features.

In this mode, displays are split into a grid of columns and rows. When entering tile mode, windows are snapped to this grid as they are placed. The number of rows and columns are configurable in the extension's popup menu in the panel.

An optional feature to improve your tiling experience is the ability to snap windows to the grid when using your mouse to move and resize them. This provides the same precision as entering window management mode to position a window with your keyboard, but with the convenience and familiarity of a mouse. This feature can be enabled through the extension's popup menu.

Disabled by default, this mode manages windows using a tree-based tiling window manager. Similar to i3, each node of the tree represents two branches. A branch may be a window, a fork containing more branches, or a stack that contains many windows. Each branch represents a rectangular area of space on the screen, and can be subdivided by creating more branches inside of a branch. As windows are created, they are assigned to the window or stack that is actively focused, which creates a new fork on a window, or attaches the window to the focused stack. As windows are destroyed, the opposite is performed to compress the tree and rearrange windows to their new dimensions.

There is file $XDG_CONFIG_HOME/gnome-mosaic/config.json where you can add the following structure:

{
    "class": "<WM_CLASS String from xprop>",
    "title": "<Optional Window Title>"
}

For example, doing xprop on GNOME Settings (or GNOME Control Center), the WM_CLASS values are gnome-control-center and Gnome-control-center. Use the second value (Gnome-control-center), which gnome-mosaic will read. The title field is optional.

After applying changes in config.json, you can reload the tiling if it doesn't work the first time.

Due to the risky nature of plain JavaScript, this GNOME Shell extension is written in TypeScript. In addition to supplying static type-checking and self-documenting classes and interfaces, it allows us to write modern JavaScript syntax whilst supporting the generation of code for older targets.

Please install the following as dependencies when developing:

• Node.js LTS+ (v12+)
• Latest npm (comes with NodeJS)
• npm install typescript@latest

While working on the shell, you can recompile, reconfigure, reinstall, and restart GNOME Shell with logging with make debug. Note that this only works reliably in X11 sessions, since Wayland will exit to the login screen on restarting the shell.

Licensed under the GNU General Public License, Version 3.0, (LICENSE or https://www.gnu.org/licenses/gpl-3.0.en.html)

Any contribution intentionally submitted for inclusion in the work by you shall be licensed under the GNU GPLv3.