Spatial Shell: Call For Testers

In August 2022, I have discovered Material Shell . A few weeks later, I had pieced together a working prototype of a dynamic tiling management “a la Material Shell” for sway . By October, the project was basically fulfilling my needs, and I had already started to use it on my workstationI tried so you do not have to: having my graphical session going crazy during a work meeting because of a software I had written. . The project sat there for a while until I rediscovered this thing called holidays.

For a short week, I tried to address at many of the remaining issues and missing features that I was aware of. Then, I started to write man pages , which turned out to be the perfect opportunity to clean up every clunkiness I could possibly find.

I can’t help but find the result rather nice and satisfying, and I hope you will enjoy it too! Spatial Shell  works on my machine, which means it will definitely break on yours. But this is where the fun lies, right? At this point, I definitely think the project is ready to fall into the hands of (motivated) alpha testers.

Anyway, let me give you a tour!

Spatial Model

At its core, Spatial Shell allows you to navigate a grid of windows. Workspace are rows which can be individually configured to determine how many windows (cells) you can see at once. More precisely, workspaces in Spatial Shell can use two layouts:

• Maximize: One window is displayed at a time
• Column: Several windows are displayed side by side, to your convenience

The reason Maximize is not a particular case of Column, but instead a layout on its own, is to easily allow you to switch to and back from maximizing the focused window. The following pictureCreated using Excalidraw . summarizes one particular setup with tree workspaces, each configured differently.

• Workspace 1 contains three windows, and uses the Column layout to display at most three windows, so each window is visible, with the focus being on the leftmost one.
• Workspace 2 contains four windows, and uses the Column layout to display at most two windows. As a consequence, two windows are not visible.
• Workspace 3 contains two windows, and uses the Maximize layout so only the focused window is visible.

To help users know which window is currently holding the focus, Spatial Shell slightly reduces the opacity of unfocused windows (as poorly hinted by the gray backgrounds in the figure). Finally, Spatial Shell can also set a background for empty workspaces (using swaybg under the hood).

And this is basically it. There is not much more to say about Spatial Shell features.

Configuration

From an implementation and user experience perspective, Spatial Shell is taking inspiration from i3 and sway.

More precisely, Spatial Shell comprises two executables:

• spatial(1) , the daemon implementing the spatial model described in the previous section, and
• spatialmsg(1) , a client used to control the current instance of spatial.

Assuming $spatial and $spatialmsg contains the paths to spatial and spatialmsg binaries respectively, then the simplest sway configuration to start using Spatial Shell is the following

exec $spatial

# moving the focus
bindsym $mod+h exec $spatialmsg "focus left"
bindsym $mod+l exec $spatialmsg "focus right"
bindsym $mod+k exec $spatialmsg "focus up"
bindsym $mod+j exec $spatialmsg "focus down"

# moving the focused window
bindsym $mod+Shift+h exec $spatialmsg "move left"
bindsym $mod+Shift+l exec $spatialmsg "move right"
bindsym $mod+Shift+k exec $spatialmsg "move up"
bindsym $mod+Shift+j exec $spatialmsg "move down"

# toggle between Maximize and Column layout
bindsym $mod+space exec $spatialmsg "toggle layout"

# modify the number of windows to display in the Column layout
bindsym $mod+i exec $spatialmsg "column count decrement"
bindsym $mod+o exec $spatialmsg "column count increment"

# start waybar, spatial will take care of the rest
exec waybar

By default, Spatial Shell sets the initial configuration of a workspace to the Column layout with two columns at most, and sets the opacity of the unfocused windows to 75%. This can be customized, either globally or per workspace, by creating a configuration file in $XDG_CONFIG_HOME/spatial/configIf unset, $XDG_CONFIG_HOME defaults to $HOME/.config. .

For instance, my config file looks like that.

[workspace=3] default layout maximize
background "~/.config/spatial/wallpaper.jpg"
unfocus opacity 85

See spatial(5)  for the list of commands supported by Spatial Shell.

As a side note, readers familiar with sway will definitely pick the resemblance with sway and swaymsg, and it actually goes pretty deep. In a nutshell, swaymsg connects to a UNIX socket created by sway at startup time, to send it commands (see spatial(5) ) using a dedicated IPC protocol inherited from i3 (see sway-ipc(7) ). Not only spatial also relies on sway IPC protocol to interact with sway and implement its spatial model, it creates a UNIX of its own, and supports its own protocol (spatial-ipc(7) ).

Waybar Integration

It is a common practice to use a so-called “bar” with sway, to display some useful information about the current state of the system. In the contrib/ directory of Spatial Shell repository , interested readers will find a configuration for Waybar Readers familiar with Material Shell design will not be surprised by the general look and feel of the screenshot below. . This configuration is somewhat clunky at the moment, due to the limitations of the custom widget of Waybar which does not allow to have one widget defines several “buttons.” I am interested in investing a bit of time to see if I could write a native widget, similarly to sway’s one.

That being said, the user experience with this integration is already pretty neat. As long as you don’t need more than 6 workspaces and 8 windows per workspacesThese constants are totally arbitrary and can be increased by modifying the Waybar config, but the issue will remain that a limit will exist. , you are good to go!

Building from Source

As of April 2023, the only way to get Spatial Shell is to build it from source.

You will need the following runtime dependencies:

• sway (i3 might be supported at some point)
• gmp (for bad reasons, fortunalety this will be removed at some point)
• swaybg
• waybar (if you want the full experience)

You will need the following build dependencies:

• opam
• scdoc (for the man pages)

Then, building and installing Spatial Shell is as simple as using the two following commands.

make build-deps
make install

The latter command will install Spatial Shell’s binaries in /usr/local/bin, and the man pages in /usr/local/man. You can remove them with make uninstall.

To install Waybar theme, copy contrib/waybar/spatialbar.py to /usr/local/bin/spatialbar for instance, and the Waybar style and config file to $HOME/.config/waybar.