Lagrange v1.18: TUI and Misfin

Development of version 1.18 has been a slow burn. Over the past year, I've been putting finishing touches on the Curses-based TUI variant and adding support for new Gemini-adjacent protocols. A number of bugs were fixed as well, and I've made several minor improvements in the user interface.

Curses-based TUI

In version 1.18, the TUI has been polished up a bit and there are now official prebuilt "clagrange" binaries.

To get started with the TUI:

• Download and run one of the clagrange binaries.
• At the top of the screen, you can see the most important keyboard shortcuts. For example, the Return key will focus the URL field, and the menubar can be activated with ? (or by TABing the focus around).
• Most features can be found in the menubar, including the associated keyboard shortcuts.
• The default config and runtime files are under "~/.config/lagrange", so some of them may be directly shared with the GUI version (for example on Linux). If not, you can still export your user data out from the GUI, launch clagrange with the path of the user data ZIP file as an argument, and hit Return to start the import. Alternatively, you can direct clagrange to use an existing runtime directory with the `-U` option.

Additional tips:

• The / (slash) key opens a context menu based on the current focus, so for example you can open the bookmark context menu while in the sidebar, and the page context menu while browsing normally.
• Context menus react to the A-Z keys for quickly moving the cursor based on the first letter of the item label.
• Most key bindings can be changed just like in the GUI version in Preferences > Keys.
• As usual with Curses, the TERM environment variable controls the terminal display mode. You'll generally want to use `TERM=xterm-256color` for the best appearance, however smaller color palettes should also work (for example: `TERM=xterm`, `TERM=vt100`).
• If your terminal supports Emoji and other wide Unicode characters, you should go to Preferences > Appearance and disable the setting "Force ASCII character set".

Over the past two years the TUI has received some attention as new features have been added to the GUI. However, the major shortcomings like proper keyboard navigation and on-screen display of the basic browsing actions have remained unaddressed. Also some UI layouts, like the one in the Preferences panel, were not working too well in the minimum 80x25 resolution. I've taken care of all of these in v1.18. As a bonus, UI keyboard navigation with arrow keys is fully available in the GUI as well.

When it comes to terminal window size, you can run the app in windows smaller than 80x25, too, but some dialogs may not be fully visible horizontally. Large windows are naturally not a problem because everything scales up without issue.

The final missing step was packaging the prebuilt TUI binaries. The CMake project was improved for building both the GUI and TUI variants at the same time, or just building either one. These are separate because the TUI works by emulating SDL2 APIs on a text canvas, so it is a compile-time choice. On Linux, I went with an AppImage because that makes it easier to distribute the "resources.lgr" file. For macOS, clagrange is a statically linked executable that installs to "/usr/local/bin/clagrange" via a .pkg. The installer and the executable have both been signed and notarized as expected.

There is no prebuilt binary for Windows, though! If you really really want clagrange on Windows, I recommend looking into WSL and running it inside a Linux VM. In theory, clagrange should work under the MSYS2 environment, or Cygwin for that matter, however I did not consider this a high-priority item. The build environment is easier to set up in Linux than in MSYS2/Cygwin. I'm planning on switching the Windows binary to be MinGW-compiled in the future so it would run as a native Windows executable; I want to minimize time investment into the non-native MSYS2. There's PDCurses that will likely be of use here, but it will require some effort to get it working with my SEALCurses that powers the text-based UI.

All in all, the TUI is in a usable shape now, although it would still benefit from further adoption of typical terminal UI patterns to make it feel more at home in the terminal. I've probably also missed a few UI strings that reference GUI-specific features, and things like drag-and-drop may be expected here and there. The TUI will keep evolving over time, much like the mobile ports.

New features and improvements

• When a server responds with the 31 Permanent Redirection status, all bookmarks (including feed subscriptions) are updated automatically to reflect the new URL.
• There is now support for Opus audio playback using the opusfile library, however this is not currently enabled in the prebuilt binaries. (Contributed by Martin Chang.)

Documents:

• Page layout expands up to window width when necessary, for example to accommodate long plaintext lines. You may want to disable the "Wrap long plaintext lines" setting to better take advantage of this, for example when viewing Gopher pages.
• Right-clicking the site banner shows a link-like context menu (bookmark link, open on the side, new window, new tab, etc.).

User interface:

• The Return key focuses the URL field for conveniently entering lookup words, search terms, or a URL.
• The Upload dialog allows entering a file path manually, in case drag-and-drop with the mouse is inconvenient or not supported.
• Saving the current page to downloads pops up a confirmation. Previously there was no indication of the saving taking place, which may have been confusing.
• A few updated UI symbols: Go to Root, remote bookmarks, and navbar bookmark button. These icons have been a bit small/unclear.
• Updated Noto Emoji font.

The above is a summary of the full release notes. You can find the complete list in-app by visiting "about:version":

Smol protocols

Misfin

Misfin is a messaging protocol that has been in the works since May 2023. Like Gemini, it relies on TLS and simple text-based requests, with 'text/gemini' as the content format.

Lagrange v1.18 adds support for importing Misfin identity certificates and sending messages. While there are already both client and server implementations, I feel that it is beneficial to have a convenient way to send messages to addresses found in Geminispace. You will still need a Misfin mailbox where you can receive messages — servers are expected to verify the identity of unknown senders by checking if the sender's certificate matches the one provided by their server.

A Misfin identity certificate is a TLS client certificate where the UID field specifies the mailbox name, subject alternative name(s) specify the domain name(s), and the Common Name is the human-readable name. You will need to import one or more of these before sending any messages.

When sending a message, the Upload dialog opens in Misfin mode with "To" and "From" fields. As usual, the text editor in the dialog has basic Gemtext syntax highlighting, but otherwise the editor has nothing Misfin-specific. A toggle is provided if you want to send a copy of the message to yourself. Lagrange does not keep copies of sent messages, because it does not maintain a local Misfin mailbox.

When you click on a link with a "misfin://" URI, the dialog opens automatically with the recipient address prefilled.

If you have any questions getting started with Misfin, perhaps the best place to visit is s/Misfin on BBS.

Titan

Along with fixes to a few Titan bugs, v1.18 adds support for the proposed Titan edit links. Their purpose is to streamline the user experience of editing resources. Summarizing, when requesting a Titan URL with ";edit" included, the client will receive the latest version of the resource in a format suitable for editing. After the user is finished editing the content, it can be submitted back to the server via the same URL, sans the ";edit".

Guppy

Support for the Guppy Protocol was contributed by the protocol's author, Dima Krasner. Thanks for being patient with me as I sat on the PR for the better part of a year!

Guppy is a UDP-based non-encrypted transmission protocol that aims to be very light-weight. The Raspberry Pi Pico W server hosting the Guppy capsule certainly responds much faster over Guppy than Gemini.

Guppy is a simple protocol for quick transfer of small documents, inspired by Gemini, Spartan, Gopher and TFTP. In a nutshell, it's Gemini without TLS and some status codes, over UDP.

Gopher

• Fixed issue where Gemtext formatting in the gophermap (i.e., info lines that start with certain characters) has unwanted effects on the page as displayed by Lagrange.
• `i` lines can have a blank port number (since it's not an address/link these fields have no meaning).
• Telnet lines `8` and `T` are recognized and become clickable links.

Road ahead

There has not been much time to do in-depth testing of the .0 release, so I am more or less crossing my fingers and hoping there aren't any horrible bugs left. There will again undoubtedly be a series of quick patches as any remaining or newly discovered issues are fixed.

If something seems off or blows up, please file a bug report:

Next, I'll shift focus toward the mobile ports to get them on par with the desktop v1.18. Maybe I'll even add a dark mode icon for iOS 18!

📅 2024-09-20

CC-BY-SA 4.0