Thomas Letan's Blog - spatial-shell

Spatial Shell 6th Release Might Be the Charm

December 30, 2023

Spatial Shell 6th Release Might Be the Charm

After a first call for testers that could have been more effective if only the building instructions listed in the README were correct , I am quite happy to announce the 6th release for Spatial Shell that, I believe, is pretty usable for someone who isn’t me.

What’s Spatial Shell Already?

In a nutshell, Spatial Shell implements a spatial model inspired by Material Shell for i3 and sway. Windows are organized in a grid whose rows are your workspace, and you can navigate this grid (by focusing neighbors windows), move the focused window around, decide how many window you want to see at most in every workspace, etc.

When I first discovered Material Shell in August 2022, I was pretty excited, but the fact that it is a GNOME extension prevented me from switching completely (besides, it was pretty unstable on my laptop for reasons. So when I discovered that Sway (my personal favorite window manager) could be controlled by a third-party program through a Unix socket , I started experimenting. It didn’t take long before I had a working prototype that fit most of my need , but it took a significant amount of time to turn this prototype into something really usable by anyone who isn’t me.

Here is a clunky showcase of what Spatial Shell can doYes, Scott Pilgrim Takes Off is an awesome show that you definitely need to watch. .

For the interested viewers, I am using a forked version of sway called SwayFX to get these rounded corners and the dim effects on unfocused windows. The status bar is Waybar with a config you can try yourself if you are interested ! There is also a minimal i3blocks config available if you cannot use WaybarI fully intend to provide an example config as visually pleasing as the one for Waybar, but compatible with i3. .

To be clear, the UI part of Spatial Shell remains lacking to this day. My Waybar configuration works, but is pretty verbose and statically limited. For instance, it will only display the 8th first windows of a workspace. This is because Waybar does not allow one widget to generate multiple blocks. The same goes for the i3blocks configuration example. Also, they assume the availability of a font with iconsOn that matter, I love the Nerd Fonts project. .

Try It Yourself!

As of today, you can install Spatial Shell using the following methods:

By fetching the official binary builds for Linux x86_64 from the GitHub releases page
By installing the AUR package for Archlinux
By building directly from source

The README should be a good starting point. If it is lacking key pieces of information, do not hesitate to open an issue. At this point, I am willing to deal with documentation issue as bugs.

Besides its README, Spatial Shell is documented via manpages. For a list of available manpages, you can refer to man -k spatial. Spatial Shell definitely works with sway, and should work with i3 since the former is basically a drop-in replacement for the latter.

Conclusion

The journey from the initial idea up to this moment has definitely been an interesting one. At this point, Spatial Shell provides every feature I need. That being said, it does not mean there is nothing more to tell! I certainly hope this project will catch the eyes of some of you, and soon be used on computers I do not own by folks who are not me.

Contributions are obviously welcome! Typically, if you happen to piece together a neat status bar configuration, I am very interested.

What happened since December 2022?

May 18, 2023

What happened since December 2022?

emacs meta neovim releases spatial-shell

Initially, I started this “What happened” series as an exercise to publish more regularly on this website. Suffice to say, I haven’t done a particularly impressive job in that regard, which only means I have a lot of room for improvement.

Anyway, if the first few months of 2023 has been mostly $WORK focus, the same cannot be said for April and May. For one, I have started running again. But this is only the tip of the iceberg.

Spatial Shell got its first releases

Spatial Shell is probably my hobby project I am most excited about. The “call for testers” article I have published recently managed to catch the attention of a few folksYou want to hear a lesson I learned the hard way just after publishing it? Before calling for testers, it is better to be sure your project can actually be compiled easily by the potential volunteers . . The perspective to publish such a write-up was a very strong source of motivation for me to clean up a project I was using daily for several months now, and I am very satisfied with the result.

Mass adoption is still a distant horizon, but still, the project is now mainstream enough that it has already been mentioned in a random topic on the OCaml discourse by someone who isn’t me . 🎉

This led me to formally release a first version of Spatial Shell in the end of April, and a second today. For the first time, I have also published an Archlinux package , to make the life of potential early adopters even easier. Do not hesitate to upvote it so that it can find its way to the extra repository some day.

Goodbye Emacs! Remember me, Neovim?

In 2015, I started using Coq for my PhD thesis and at the time, there was no real support for (Neo)vimThe situation later improved. Nowadays, you can implement your theories using Coqtail , and Coq LSP will probably become a viable and interesting setup in a near future. . Everyone was using Proof General and Emacs, so I was left with little choice but to follow through. With only my courage and the good advice of a fellow “vimer” who had also made a similar journey , I started using Emacs.

Fast forward 8 years later, and my Emacs configuration has become a project of its own. Overall, I was pretty happy with my setup, but in the same time, I always remained a bit nostalgic of my Neovim days. This is probably why I decided to give this old friend a try when my company bought me a new laptop. I also used this as an opportunity to try out this LSP-thing everyone was talking about.

It has been a month now, and I do not plan to come back to my previous habits. There are still some few edges here and there, I still need to get my head around lua, but LSP is nice, and plugins like telescope are simply too beautiful.

That being said, there was one aspect of moving from Emacs to Neovim I had not anticipated: Org mode. Which constitutes a perfect transition to the next session.

Website redesign, again

Did you notice this website has been revamping recently? The changes are actually deeper than “just” a redesign, to a point where I had to port all my write-ups to a different markup languageAre you starting to understand why “Org mode” was the perfect transition to move on to this section? .

Why, you ask? Well, it’s actually pretty simple: as time goes, I’ve grown lazier.

Let me give you some context. Until very recently, my website was built around the idea to have literate programming as a first-class citizen of my author tools. For instance, you can have a look at what used to be the literate program which was responsible for generating the website. Similarly, most of my write-ups about Coq were actually Coq documents. Literate programming is actually a very nice paradigm for authoring technical contents, because it gives you the tools to keep said contents accurate and up-to-date. In a nutshell, you cannot have a typo in one of your code snippets which would prevent it from compiling, because you actually compile the snippet and catch the typo when you try to generate your website. Or at least, it is what I used to do.

I decided to stop because, for all its benefits, this approach has one major drawback: it is hard to maintain. I had invested quite some time and efforts to keep my website sources under control, but it really was an everyday fight. There are some strange things which start happening when you fully commit to this, as I think I did. For instance, software dependencies tie your article together. Suddenly, you cannot talk about this new fancy feature of the latest Coq release without upgrading all your write-ups implemented as Coq documentsWell, in theory you can. Just have each Coq document specifies the Coq version it requires, and support this level of customization in your build toolchain. But then, your blog takes forever to build from a cold repository. .

That being said, most of the work had already been done. This website was a collection of literate programs, and I was pretty proud of the state of things. I could deal with the annoyancesLike using Coqdoc syntax to write my articles, for instance. I could write about how the Coqdoc syntax irks me for ages. . But then, as I explained in the previous section, I decided to move away from Emacs. The first time I tried to start a new write-up, it hit me.

I used to write most of my contents using Org mode. Org mode, also known as the Emacs markup language.

I know of at least one “Org plugin” for Neovim , but instead of giving it a try, I decided to use this opportunity to tackle my “maintenance problem” once and for all. I gave up on literate programming for this website. As a result, this website is now generated from Markdown files only (using markdown-it with many plugins). As a consequence, the generated HTML is way more “predictable.” This was enough to motivate me at giving a try at Soupault’s indexes , which are way more powerful than I anticipated. Now, this website has

Tags. Each write-up can be labeled with as many tags as I want, there is a page which lists all the tags used in the website, and each tag has its own page (for instance, the coq tag.
A RSS feed. It was actually one of the main features I really wanted to get with this revamp.
Automatically generated list of articles in the home page, for each series (see the Ltac series for instance). Before, I was publishing “curated indexes,” or put in other words: I was writing these indexes myself, by hand. And again, I’ve grown lazier.

It took me a week to go through this rework. Translating manually every write-up was tedious, to say the least, as was implementing the Lua plugins for Soupault since I have neither proficiency nor tooling to help me write Lua code. But I am very glad for the final result.

Also, I have invested in an Antidote license, so hopefully, this website will have fewer typos and English butchering as of now. A clean text, delivered with a nice and simple design, from a sane and maintainable Git repository .

Spatial Shell: Call For Testers

April 27, 2023

Spatial Shell: Call For Testers

spatial-shell

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.

Spatial Shell allows users to configure the layout of each workspace individually.

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.

Mandatory screenshot of Spatial Shell, with the Waybar configuration.

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.

What happened in October and November 2022?

November 19, 2022

What happened in October and November 2022?

spatial-shell nanowrimo coqffi

It is November 19 today, and I’m one month and 4 days late for the October Retrospective! Truth is, $WORK has been intense lately, to a point where I have not made much progress on my side projects. Anyway.

I have implemented the last feature I was really missing in my daily use of Spatial Sway: moving windows to adjacent workspaces. As a result, I think I can say that Spatial Sway has really reached the “Minimum Viable Product” stage, with a convenient UX, and a nice enough UI. It is still lacking when it comes to configurability, though. It is the next item of my TODO list, but I have no idea when I will implement the support for a configuration file.

Another highlight of the past two months was the NaNoWriMo . I took the last week of October and the first week of November off to plan and start writing a fiction project for it. Writing again was really nice, and I even gave writing fiction in English a shot. That made me uncover a bug in the English support of ogam , my markup language for fiction writers, which led me to publish a fix on Crates.io. However, as soon as I came back to $WORK, my writing spree ended. That’s okay, though. It gave me plenty of ideas for future sessions. Thanks, NaNoWriMo! Sorry to quit so soon, and see you next year, maybe.

Finally, a nice surprise of the past month is that someone has started working on adding proper support for coqffi to dune , the build system for OCaml and Coq! I’m thrilled by this. Thanks, @Alizter !

This wraps up this retrospective. I hope I will have more interesting, concrete news to share next month.

What happened in September 2022?

September 18, 2022

What happened in September 2022?

spatial-shell meta

It is September 18 today, and it has already been a month since I decided to start these retrospectives. This means it is time to take a step back and reflect of what happened these past few thirty days or soThere is the shocking news that I have started to use syntax highlighting again. But let’s not linger too much into it just yet. .

Spatial Sway

A few days after publishing my August Retrospective, I have learned the existence of Material Shell , an extension for GNOME 3 that provides a very interesting user experience.

I tried it for a few hours, but the thing kept crashing (it’s probably on me, I did not even remember I had Gnome installed on my machine, and I would not be surprised the culprit was my dusty setup rather than Material Shell itself). The experience remained very promising, though. Their “spatial model” especially felt like a very good fit for me. Basically, the main idea is that you have a grid of windows, with your workspaces acting as the rows. You can navigate horizontally (from one workspace to another), or horizontally, and you choose how many windows you want to see at once on your screen.

And so for a few hours, I was a bit frustrated by the situation… until I learned about how one can actually manage and extend Sway (the Wayland compositor I use for several years now) thanks to its IPC protocol. I spend like three days experimenting, first in Rust, then in OCamlThis was actually an interesting thought process. I am using OCaml at $WORK for about more than a year now. I have curated a setup that works pretty well, and I am familiar with the development tools. On the contrary, I had not written a line of Rust for at least a year, my Emacs configuration for this language was broken, and I had lost all my fluency in this language. Still, I was not expecting to pick OCaml when I started this project. , and by the end of the week, I had a first working prototype I called Spatial Sway . It works pretty well; well enough that I am using it daily for several weeks now. It feels clunky at times, but it works well, and I have been able to write a Waybar configuration heavily inspired on Material Shell UI.

Overall, I am pretty satisfied with this turnout. Writing a hobbyist software project is always nice, but the ones you can integrate in your daily workflow are the best one. The last time I did that was keyrd , my little keystrokes counting daemon19,970,965 since I started using it at the time of writing this article .

Anyway, lots remains to be said about Spatial Sway, but I might save it for a bit later. I still have some key features to implement (notably, moving a window to another workspace), then I will probably try to advertise it a bit. I am under the impression this project could be of interest for others, and I would love to see it used by folks willing to give a Material Shell-like experience a try, without having to deal with Gnome Shell. By the way, considering Sway is a drop-in replacement for i3, and that it implements the exact same IPC protocol, there is no reason why Spatial Sway is actually Sway specific, and I will rename it Spatial Shell at some point.

Mandatory screenshot of Spatial Sway.

This Website

On a side note, I have started to refine the layout of this website a bit. Similarly, I have written a new, curated home page where I want to highlight the most recent things I have published on the Internet.

I have been experimenting with Alectryon as a way to replace coqdoc, to improve the readability of my Coq-related articles. Unfortunately, it looks like this tool is missing a key feature I need . I might try to get my hand dirty and implement it myself if I find the time and the motivation in the following weeks.

Finally, reading about how Xe Iaso’s talk about how she generates her blog was very inspiring to me. I can only suggest that you have a look.

Though not to the same extent, I also think I have spent way too much effort in my website. Most of my Coq-related articles are actual Coq program, expect the articles about coqffi which are Org mode literate programs. Hell, this website itself used to be a literate program of the sort, until I stopped using my homegrown literate programming toolchain cleopatra last month. At some point, I have even spent a bit of time to ensure most of the pages of this website were granted a 100/100 on websites like PageSpeed InsightGood news, I’ve just checked, and it still is! . I had almost forgotten.

A lot remains to be done, but watching this talk made me reflect on the job done. And opened my eyes to a new perspective, too. We will see what translates into reality.