feresaria/docs/desktop-widgets.md

Desktop widgets

Clock and sticky-note widgets sit above the wallpaper and behind windows. Drag the clock or a note's title to move it. Release to save, or press Escape to cancel. Widgets stop at each other's edges on the same display.

Enable it in Settings → Desktop widgets or in your Ferese config:

desktop-widgets {
    clock enabled=#true anchor="top_left" margin-x=64 margin-y=80 {
        style "pixel"                   // or "minimal"
        outputs                         // every output; or outputs "DP-2"
        width 440
        height 320
        font-family ""                  // style default; or "Comfortaa"
        bold #false
        time-size 128.0
        date-size 18.0
        time-format "%-I:%M %p"          // use "%H:%M" for 24-hour time
        date-format "%a, %b %-d"
        time-zone ""                    // system zone; or "Africa/Lagos"
        show-date #true
        lowercase #true
        color ""                        // theme primary text
        date-color ""                   // theme muted text
        opacity 0.9
        alignment "center"              // left, center, right
        gap 4.0
        padding 12.0
        background ""                   // transparent; or "#10101080"
        radius 16.0
    }
}

Positions: top_left, top_center, top_right, center_left, center, center_right, bottom_left, bottom_center, bottom_right. Margins affect anchored axes only: a centered horizontal position ignores margin-x; a centered vertical position ignores margin-y. All geometry and text sizes use logical pixels and follow the output's scale. Increase the widget width/height for longer formats or larger text.

Choose Pixel for stacked hours and minutes with alternating theme colors, or Minimal for a plain time/date layout. Pixel zero-pads hours and hides am/pm. Formats containing seconds or extra text use a single line. Both styles shrink time text to fit. Select a different font in Settings, or set font-family.

Changes apply live. Colors and fonts follow the theme unless overridden. Formatting uses strftime-compatible formats. Use %H:%M for 24-hour time or %-I:%M %p for 12-hour time.

Clock limits

Clock and note corners follow the shared shell radius. Their radius fields are accepted for compatibility but do not override it.

All clock keys are optional. The example enables the clock (disabled by default); the other values illustrate defaults or their empty-string equivalents. outputs is an array of strings; enabled, bold, show-date, lowercase are booleans; width, height, and margins are integers. Other sizes/opacity are numbers.

Fields	Accepted range
width, height	64–1600, 32–800
margin-x, margin-y	0–8192
time-size, date-size	8–240, 8–96
opacity	0–1
gap, padding, radius	0–64, 0–64, 0–128
font-family, time-format, date-format	At most 128 bytes each
outputs	At most 32 exact output names, each 1–128 bytes

Formats must be valid; time-zone must be empty or a recognized IANA name. Colors are empty (inherit), #RRGGBB or #RRGGBBAA; all numeric values must be finite.

Sticky notes

Settings → Desktop widgets → Add note creates a card. Drag its title to move it; click Edit for its multiline editor, then Done to finish. Text autosaves after 500 ms without typing. Escape cancels a drag or finishes editing. Position saves on release; dragging changes the anchor to top_left and saves pixel margins. Title, size and style are also editable in Settings. Notes persist in the config. Choose a note’s font in Settings or set font-family "Comfortaa" in its note node. Without an override, notes use the interface font.

These are plain-text notes, not Markdown or HTML.

desktop-widgets {
    note id="today" title="Today" text="Review the pull request\nTake a break\n" anchor="top_right" margin-x=48 margin-y=80
}

Repeat the note node for additional notes; IDs must be unique. Cards stay behind windows and take keyboard focus only when clicked. Set interactive #false for a fully click-through card. Long text wraps; increase height if needed.

Key	Type	Default / accepted values
id	string	"note"; unique, 1–64 ASCII letters/digits/-/_
enabled	boolean	true
interactive	boolean	true; drag/edit controls; false is click-through
title	string	"Note"; empty hides it; maximum 256 bytes
text	string	""; multiline plain text, maximum 16 KiB
outputs	string array	[] means all; at most 32 exact names, each 1–128 bytes
anchor	string	"top_right"; same nine positions as clock
margin-x, margin-y	integer	48, 80; 0–8192; anchored edges only
width, height	integer	320, 240; 120–1200, 80–1200
font-family	string	omitted/empty follows desktop font; maximum 128 bytes
text-size, title-size	number	16, 18; 8–96
color	string	omitted/empty/"theme" follows primary text; or hex color
background	string	omitted/"theme" follows surface base; empty is transparent; or hex color
opacity	number	0.9; 0–1, multiplies text/background alpha
padding, gap	number	20, 8; 0–64
radius	number	16; 0–128
alignment	string	"left"; left, center, right

At most 32 notes; the entire live config is limited to 60 KiB.