path: root/site/news/CFTSpatialShell.org

#+TITLE: Call For Testers: Spatial Shell

In August, 2022, I discovered [[https://material-shell.com][Material Shell]]. A
few weeks later, I had pieced together a working prototype of a dynamic tiling
management “a la Material Shell” for [[https://swaywm.org][sway]]. By October,
the project was basically fulfilling my main needs, and I had already started
to use it on my workstation[fn::I 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
[[https://lthms.github.io/spatial-shell/spatial.1.html][man pages]], which
turned out to be the perfect opportunity to clean-up every clunkiness I could
possibly found.

I can’t help but finding the result rather nice, and I hope you will enjoy it
too! [[https://github.com/lthms/spatial-shell][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
in the hands of (motivated) alpha testers.

#+BEGIN_EXPORT html
<nav id="generate-toc"></nav>
<div id="history">site/news/CFTSpatialShell.org</div>
#+END_EXPORT

It would be fair to say that Spatial Shell does not bring any novel ideas to
the table (neither from a user perspective, nor a developer one). Hopefully, it
does implement well established ideas in a nice and reliable way, so sway users
can enjoy Material Shell key ideas without having to install GNOME 3.

Anyway, let me give a tour!

* Spatial Model

At its core, Spatial Shell allows you to navigate a gride of windows, wherein
each workspace is a row. Each workspace can be configured to determine how many
windows (cells) you can see at once. More precisely, Spatial Shell supports two
layouts:

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

The reason why *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 picture[fn::Created using
[[https://excalidraw.com/][Excalidraw]].] summarizes one particular setup with
tree workspaces, each configured differently.

#+CAPTION: Spatial Shell allows users to configure the layout of each workspace individually.
#+NAME:    fig:spatial-shell-example
[[../img/spatial-shell-example.png]]

- Workspace 1 contains three windows, and is configured to use the *Column*
  layout to display at most three windows, so every windows are visible, with
  the focus being on the leftmost one.
- Workspace 2 contains four windows, and is configured to use the *Column*
  layout to display at most two windows. As a consequence, two windows are not
  visible.
- Workspace 3 contains two windows, and is configured to use 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:

- [[https://lthms.github.io/spatial-shell/spatial.1.html][spatial(1)]], the
  daemon implementing the spatial model described in the previous section, and
- [[https://lthms.github.io/spatial-shell/spatialmsg.1.html][spatialmsg(1)]], a
  client used to control the current instance of spatial.

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

#+begin_src
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"
#+end_src

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
~$XDR_RUNTIME_DIR/spatial/config~[fn::If unset, ~XDG_RUNTIME_DIR~ defaults to
~$HOME/.config~.].

For instance, my config file looks like that.

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

See [[https://lthms.github.io/spatial-shell/spatial.5.html][spatial(5)]] for
the list of commands supported by Spatial Shell.

As a sidenote, readers familiar with sway will definetely 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 sends it commands
(see [[https://lthms.github.io/spatial-shell/spatial.5.html][spatial(5)]])
using a dedicated IPC protocol inherited from i3 (see
[[https://lthms.github.io/spatial-shell/sway-ipc.7.html][sway-ipc(5)]]). 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
set of commands
([[https://lthms.github.io/spatial-shell/spatial-ipc.7.html][spatial-ipc.7.html]]).
spatial does exactly the same thing.

* 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 [[https://github.com/lthms/spatial-shell][Spatial Shell
repository]], interested readers will find a configuration for
[[https://github.com/Alexays/Waybar][Waybar]][fn::Readers familiar with
Material Shell design will not be surprised by the general look and feel of
this screenshot.]. 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 workspaces, you are good to go!

#+CAPTION: Mandatory screenshot of Spatial Shell, with the Waybar configuration.
#+NAME:    fig:spatial-shell
[[../img/spatial-shell.png]]

* 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.

#+begin_src
make build-deps
make install
#+end_src

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~.