path: root/README.md

# conky-theme-udt

A fullscreen Conky dashboard for Hyprland, drawn with Cairo from Lua, living on
a special workspace that `SUPER+S` toggles.

Colours come from [unified-desktop-theme](../unified-desktop-theme): this repo
holds `conky.conf.in`, and UDT's `bin/udt-palette` renders it into `conky.conf`
using the current scheme's `[conky]` roles. Switching scheme recolours the
dashboard.

## Install

Rendering and linking are automatic:

    cd ../unified-desktop-theme && ./install.sh

That renders `conky.conf` from `conky.conf.in` and symlinks it, along with
`dashboard.lua`, `lib/`, `widgets/` and `bin/`, into `~/.config/conky/`.
Re-running it after a scheme change re-renders the colours.

The Hyprland side is **not** installed by that script and is still yours to do.
Until you do it, the dashboard opens as an ordinary floating window on whatever
workspace is current, with no keybind, because the window rules that place it
are not loaded. Two things are needed, both described in
[`hypr/README.md`](hypr/README.md): symlinking `hypr/dashboard.lua` into
`~/.config/hypr/sections/` and requiring it from `hyprland.lua`, and changing
the bare `hl.exec_cmd("conky")` in `sections/autostart.lua` so it loads this
config. Both are deliberately left as your choice rather than done for you.

## Weather

The weather card needs an [OpenWeatherMap](https://openweathermap.org/api) API
key. Copy the example and fill it in:

    cp weather.env.example ~/.config/udt/weather.env
    chmod 600 ~/.config/udt/weather.env

That path is outside the repo because it holds a key, and anything committed is
potentially public. `weather.env` is gitignored here as a second line of
defence.

**A new key returns `401 Invalid API key` for anywhere from a few minutes to a
few hours after you create it.** That is the API activating it, not a mistake in
the file. Until it works, and whenever the cache is missing, the card draws its
own chrome with `no weather data` and the thing to fix, rather than vanishing.

Fetching is scheduled by conky itself: `conky.text` carries a single
`${execi 900 ~/.config/conky/bin/weather-fetch.sh}`, so the cache refreshes
every 15 minutes while the dashboard runs and never while it does not. The
widget only ever reads `~/.cache/udt/weather.json`; it makes no network call and
cannot block the draw.

To check the fetch by hand:

    ./bin/weather-fetch.sh; echo "exit: $?"

It prints nothing and exits 0 on success. On failure it says why on stderr and
leaves any existing cache alone, so a transient error never replaces good data
with an error body.

Location and units live in `weather.env` too (`CITY`, `COUNTRY`, `UNITS`), not
in the source, so no real location appears in committed files.

## Changing the layout

Edit the `layout` table at the top of `dashboard.lua`. `col`/`row` are grid
cells and `w`/`h` span them; cell size is derived from the screen, so the same
table works on differently shaped monitors.

    local layout = {
      { widget = 'clock', col = 1, row = 1, w = 1, h = 1 },
      { widget = 'weather', col = 1, row = 2, w = 1, h = 1 },
    }

Reordering widgets is an edit to that table and nothing else: a widget is handed
a rectangle and draws inside it, so it cannot care where it is. Adding one is a
file in `widgets/` exporting `draw(cr, rect, colors)` plus a row in the table.

`COLS` and `ROWS` above the table set the grid. Cards snap to it; there is no
absolute pixel placement, deliberately, because cells keep aligning when the
grid or the screen changes.

## Writing a widget

A widget module exports one function, `draw(cr, rect, colors)`. `lib/card.lua`
carries the primitives it should use rather than reaching for Cairo directly:

- `card(cr, rect, colors)` draws the rounded card and returns the padded inner
  rect to lay out against.
- `font(cr, family, size, bold)` and `rgba(cr, colour)` set the state.
- `text(cr, x, y, s)` draws at a baseline, `text_right(cr, x, y, s)` aligns to a
  right edge, `label(cr, x, y, s, colors)` draws a small-caps section label.
- `measure(cr, s)` returns the **ink** size, what the glyphs actually cover. Use
  it to centre or right-align.
- `advance(cr, s)` returns the **x_advance**, how far the cursor moves after
  drawing. Use it to step along a run of text.

`measure` and `advance` are not interchangeable, and conflating them was a real
bug here: ink width ignores leading and trailing spaces, so `' / '` measures 6px
of ink against a 14px advance, and stepping a cursor by the ink width renders
the date as `16 /SEP /2026`.

### Widgets are fluid

A widget is handed a rectangle and must fill it, whatever shape the grid makes
it. That is what lets you retune `COLS`/`ROWS` or move a card without touching
widget code. Three rules, all learned by getting them wrong:

**Derive every size and offset from the rect.** No fixed pixel drops between
elements. A fixed `+34` under a numeral that scales leaves a dead band in a tall
cell and overlaps in a short one.

**Scale type off the WIDTH, not the height.** Height is what changes when you
add a row to the grid, and a card that shrinks its text every time its cell gets
shorter reads as broken beside its neighbours. Width is also usually what
constrains the text, since rows run edge to edge. Clamp it: `math.max(lo,
math.min(hi, inner.w * k))`.

**Decide where the slack goes, and let one element absorb it.** The clock pins
its date block to the bottom and gives the numerals everything above. The
weather card stacks from the top and lets the arc take the remainder. Either is
fine; what fails is leaving the slack wherever it lands.

An element that cannot shrink below some size should drop out rather than
overlap. The weather arc does this: below 70px it is not drawn at all, because a
curve crossing the stat rows is worse than no curve. Check a widget at several
spans before believing it is fluid, which the offscreen renderer above makes
cheap.

## Development

After editing `dashboard.lua` or a widget:

    ./restart.sh

Conky never rereads its config and the Lua is symlinked into `~/.config/conky/`,
so a restart is the whole update path. The script syntax-checks first and
refuses to restart on a Lua error, since the alternative is a blank screen with
no message. Only a change to `conky.conf.in` or the palette needs UDT's
`install.sh` to re-render first.

To see Lua output, which is the only debugging channel, run it in the
foreground instead:

    pkill -x conky; conky -c ~/.config/conky/conky.conf

Run the parser and layout checks:

    lua test/test_data.lua && lua test/test_layout.lua && lua test/test_weather.lua

Screenshot it. `grim` captures screen coordinates, not a window, so the
dashboard's workspace has to be the active one first, and the toggle needs the
Lua dispatch form because this Hyprland config is Lua (the plain
`togglespecialworkspace dash` form fails with `')' expected near 'dash'`).

**Poll for the switch, do not sleep through it.** A fixed `sleep` races the
compositor and captures whatever was on screen before; that is how a review
screenshot here once came back showing a terminal. Capture the whole output
instead of the window geometry, too: a window parked on a hidden special
workspace reports a negative Y (`0,-540`), and feeding that to `grim -g` grabs
the wrong region entirely.

    hyprctl dispatch 'hl.dsp.workspace.toggle_special("dash")'
    for i in $(seq 40); do
      [ "$(hyprctl monitors -j | jq -r '.[0].specialWorkspace.name')" = "special:dash" ] && break
      sleep 0.15
    done
    sleep 2.5    # conky redraws every 2s; make sure a frame has landed
    grim -o DP-1 /tmp/dash.png
    hyprctl dispatch 'hl.dsp.workspace.toggle_special("dash")'

Then **look at the PNG**. `grim` exits 0 whether the card drew correctly, drew
nothing, or drew an error, so the exit status says nothing about the thing you
are checking.

Faster, for iterating on a widget's layout: conky's Cairo bindings load in
plain Lua, so a widget can be rendered to a PNG without conky at all. Point
`package.cpath` at `/usr/lib64/conky/lib?.so`, `require 'cairo'`, build an
image surface, and call the widget's `draw` with a hand-made rect and palette.
That turns install-restart-toggle-screenshot into one command. Be aware it
crops away the neighbouring cards, so check the real dashboard before believing
anything about relative type size.

Before the Hyprland section is installed there is no `special:dash` to toggle,
so the window is simply wherever it opened and a bare `grim` captures it.

## Gotchas worth knowing

**Cairo on Wayland needs `conky_surface()`.** Under `out_to_wayland`,
`conky_window.drawable` and `.visual` are both `nil`, so the
`cairo_xlib_surface_create` idiom used by essentially every Conky-Lua tutorial
cannot work here.

**A Lua error is a blank screen and nothing else.** No stderr, no log. The draw
runs inside `pcall` and paints the caught error on the surface, which is the
only reason a mistake is visible at all.

**`own_window_type` must be `normal`.** A `desktop`-type window is a
layer-surface at level 0 and Hyprland cannot assign it to a workspace.

**Lua cannot read the palette through `conky_parse`.** `conky_parse('${color3}')`
comes back as an **empty string**: conky's colour variables emit renderer escape
codes into the text stream rather than evaluating to hex, and
`${default_shade_color}` is not a variable at all. `conky.config` is not exposed
to Lua either. What Lua does get is `conky_config`, the config file's path, so
`dashboard.lua` opens that file and parses the hex out of it.

**Cairo has no Black font weight.** `CAIRO_FONT_WEIGHT_BOLD` is the maximum, so
the heavy clock numerals ask for the family `Noto Sans Black` at normal weight.

**Sensors are globbed by hwmon `name`, never by index.** Indices drift across
kernel and hardware reorders, and a stale one silently reports a different chip.

**`${execi}` fires even though `conky.text` renders nothing.** Cairo output
covers the text stream, so the `execi` that refreshes the weather cache is
invisible, but it still runs on schedule. This was checked with a probe config
rather than assumed, because the whole refresh mechanism rests on it.

**The weather cache is written to a temp file and renamed.** The widget reads it
on the 2-second draw cadence, entirely unrelated to the 15-minute fetch, so a
fetch killed mid-write would otherwise hand the parser half a response. Rename
is only atomic within a filesystem, so the temp file sits in the same directory.

**A bad OWM key returns 401 and an unknown city returns 404**, so `curl -f`
catches both. The fetch script also checks `.cod` is 200 before replacing the
cache, which covers the remaining case of a 200 whose body is not usable
weather. The polybar script this was ported from needed that check as its only
defence, because it ran curl without `-f`.

**Nothing in `lib/weather.lua` raises.** Every function returns nil, or a
sentinel, on input it cannot use, and that is verified against every function
for nil, string, table, boolean, NaN and negative arguments. It matters because
the parser's input is a file written by a network fetch, and a raise here is a
blank dashboard rather than a message.

**Card type scales off the cell WIDTH, not its height.** Height changes with the
grid, and scaling off it made the weather text shrink to a whisper beside the
clock's numerals when its cell got shorter.

## License

GPLv2 only. See `LICENSE`.

## Development Approach

This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.

All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.

The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.