arcana

Hidden knowledge, revealed on demand.

A summon-on-screen overlay for cheat sheets — keyboard shortcuts, game moves, whatever you keep forgetting. Sheets are plain Markdown files; arcana floats them above your current window as a Wayland layer-shell overlay.

Sibling to grimoire (which casts the apps): the grimoire holds the spells, arcana shows you how to cast them.

Status

Working:

• Layer-shell overlay (centered, above normal windows) on wlroots / KWin.
• Sidebar of sheets + WebKitGTK content pane (HTML/CSS, tables, icon glyphs).
• Single resident instance with --toggle — see Hotkey.
• Esc to dismiss (hides; the daemon stays resident).

Not yet:

• Phone sync — keep sheets under ~/Nextcloud/arcana/ and read them on your phone via the Nextcloud app or any Markdown viewer. A static HTML export (reusing render::sheet_to_html) is the planned one-click path.

Hotkey

arcana runs as a single resident instance; the first launch builds the (hidden) overlay and stays alive, and every later invocation is forwarded to it over D-Bus:

Command	Effect
arcana	summon the overlay (browse mode: sidebar + all sheets)
arcana --toggle	summon/dismiss browse mode
arcana <sheet>	focused mode — just that one sheet, no sidebar (toggles)
arcana --hide	build hidden and wait (for autostart)
arcana --quit	stop the resident instance

<sheet> is a path (relative to where you run it) or a bare name resolved against the sheet dir — so arcana vim opens vim.md. Re-running the same sheet hides it, so it toggles like the main overlay. This is what you bind to per-sheet hotkeys (e.g. Meta+V → arcana vim, Meta+B → arcana blender).

Bind arcana --toggle (or a specific arcana <sheet>) to a global shortcut. On KDE Plasma:

System Settings → Keyboard → Shortcuts → Add New → Command or Script → enter the full path (e.g. ~/.local/bin/arcana --toggle) → assign a key (e.g. Meta+/).

Because KWin owns the keypress, this works even over a fullscreen game. The bind is self-bootstrapping: the first press launches the daemon and shows the overlay; every press after toggles instantly. For an instant first press, also autostart the hidden daemon — copy contrib/arcana.desktop to ~/.config/autostart/ (it runs arcana --hide at login).

Put the binary on your PATH first, e.g.:

cargo build --release
ln -sf "$PWD/target/release/arcana" ~/.local/bin/arcana

Sheet location

First existing directory wins:

1. $ARCANA_DIR
2. $MOI_HOME/arcana
3. ./cheatsheets (repo-local; makes cargo run work out of the box)
4. ~/.config/arcana/cheatsheets

A sheet is any *.md file. Its sidebar title is the first # Heading, else the filename.

Build

Needs GTK4, gtk4-layer-shell, and WebKitGTK 6.0 dev libraries (Fedora / Nobara):

sudo dnf install gtk4-devel gtk4-layer-shell-devel webkitgtk6.0-devel

Then:

cargo run

Why GTK4 (and not iced)

The overlay behaviors — frameless, always-on-top, positioned above other windows — are compositor concerns handled on Wayland via the wlr-layer-shell protocol. iced's winit backend doesn't expose layer-shell; GTK4 + gtk4-layer-shell is the proven stack. Doubles as practice for a future Lutris (PyGObject → gtk4-rs) port.