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!
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.
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.
$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 defaults to
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) ).
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
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)
- waybar (if you want the full experience)
You will need the following build dependencies:
- 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
To install Waybar theme, copy
/usr/local/bin/spatialbar for instance, and the Waybar style and
config file to