Module config 

Configuration and XDG persistence.

This module owns two concerns:

• Config — the user-facing TOML file at $XDG_CONFIG_HOME/tree-space/config.toml (~/.config/tree-space/config.toml). Every field has a sane default via #[serde(default)], so a minimal file (or none at all) is valid. Those defaults are not written here: they are parsed from the shipped default-config.toml (see [builtin]), which is the single source of truth for every default value.
• SessionState — small runtime state (last opened root) kept in $XDG_STATE_HOME/tree-space/state.toml. Kept separate from the config so that re-exporting the config as a “default” for users stays clean.

The XDG resolution helpers are pure functions over environment-style inputs so they can be tested without mutating process-global environment variables.

Structs

Bookmark

One entry in the bookmarks list: either a directory shortcut (has a path), a folder grouping nested entries (non-empty items), or both.

BookmarksConfig

The [bookmarks] options table. Bookmarks are a pane view (a “new panel” showing directory shortcuts to jump from).

BuiltinEntry

A builtin menu item written out in table form, so a label override and/or a shortcut can be attached to it: { action = "Cut", shortcut = "Ctrl+x" }.

CommandAction

A custom command run with the row’s path. The {path} marker is replaced with the row’s full path; {dir} with the directory itself for a directory row or its parent for a file. With no marker, the path is appended as the final argument.

Config

Top-level configuration.

ContextMenu

Configurable per-row context menus.

ContextRule

A context-menu rule: rows claimed by any matches entry get exactly items. Rules are evaluated top-down; the first match wins.

LoadResult

The outcome of loading a config: always a usable config plus an optional problem description for the status bar.

PaneMenu

The configurable hamburger (“pane”) menu that opens from the toolbar.

PanelConfig

Dock/panel configuration. Field-level serde defaults keep a partially written [panel] table valid without consulting Self::default() (which parses the shipped file — see [builtin]).

SessionState

Small runtime state persisted between launches.

Stylesheet

The outcome of loading the user stylesheet.

Submenu

A nested submenu: a labelled row that opens a child menu of its own items. The items may be anything a top-level menu item can be, including further submenus.

ThemeConfig

The [theme] section: how the panel gets its colors and fonts.

TreeConfig

Sorting and visibility rules for the tree.

Enums

BuiltinAction

A built-in context-menu action: everything the panel can do to a row that is not a custom command. A Separator is only a menu divider; it has no action.

ContextAction

One entry in a context-menu rule:

ContextMatch

Which rows a context-menu rule applies to. Checked in order of rule precedence: Dir first, then extension, then no-extension, then Regex / Fallback for anything else.

LoadProblem

Why a config could not be loaded cleanly. Absence of a problem (/ defaults used because the file doesn’t exist) is not reported.

PanelLayer

The wlr-layer-shell layer the panel lives in. Bottom keeps it behind normal windows (the Ormachy/Hyprland “stays out of the way” mode).

PanelSide

Which edge of the screen the panel docks to.

ShortcutTarget

The action bound by a shortcut: a builtin, or a custom command that is run against the current row.

StartupRoot

Where the panel opens when launched without an explicit path argument.

StyleSource

Which stylesheet load_stylesheet actually returned.

SystemTheme

Which desktop theme ThemeMode::System follows. Only Omarchy is supported today; more providers may be added later.

ThemeMode

How the panel is styled.

WorkspaceMove

Where a “move the panel” action should send the panel.

Constants

APP_DIR

The directory name used below all XDG base dirs.

BOOKMARKS_FILE

Default name of the bookmarks list file inside APP_DIR. The config’s [bookmarks] file may point elsewhere.

CONFIG_FILE

Name of the config file inside APP_DIR.

DEFAULT_STYLESHEET

The shipped default stylesheet, written out beside the config on first launch and used as a fallback when the user’s own is missing or unreadable.

PANEL_MAX_WIDTH

Largest allowed panel width, in pixels.

PANEL_MIN_WIDTH

Smallest allowed panel width, in pixels.

STATE_FILE

Name of the state file inside APP_DIR.

STYLE_FILE

Name of the user stylesheet inside APP_DIR.

Functions

action_command

Build a command line for a custom context-menu action on path.

bookmark_file_path

Absolute path of the bookmarks list for the current environment, given the configured [bookmarks] file (relative to the config directory, or absolute).

config_file

Absolute path of the config file for the current environment.

default_bookmarks

The bookmark list a fresh install starts with: one entry for the home directory. Empty only when $HOME is unknown.

default_structure

The theme-independent part of the default stylesheet: every rule, with the @define-color palette stripped off. A system theme prepends its own palette (and font rules) and reuses this structure, so it never needs the user’s main.css.

ensure_bookmarks_at

ensure_bookmarks_file against an explicit path (tests).

ensure_bookmarks_file

Create the bookmarks file for config (containing list) on first launch, so the user has something to edit. Never clobbers an existing file; a read-only directory is treated as “nothing to write” (as with the config).

expand_bookmark_path

Expand a leading ~ in a bookmark path (a no-op for ordinary paths). Stored paths are absolute in practice, but a hand-written ~/notes still works.

expand_tilde

Expand a leading ~ in path to $HOME. An empty string stays empty.

load_bookmarks

Read the bookmarks list named by config for the current environment. A missing file yields default_bookmarks with no problem; an unreadable or unparsable one yields the default list plus the problem, so a broken file never takes the section down.

load_bookmarks_from_path

Read a bookmarks list from an explicit path (tests).

load_stylesheet

Load the stylesheet selected by [theme].

save_bookmarks_to_path

Write bookmarks to path atomically, creating parent directories. Mirrors SessionState::save_to_path: temp file plus rename, so a crash mid-write never truncates the existing list.

state_file

Absolute path of the state file for the current environment.

style_file

Absolute path of the user stylesheet for the current environment.