feat(appearance): wallpapers by folder, system ones, quality borders

The wallpaper tab showed every image under ~/Pictures/wallpapers in one
grid. It now groups them by top-level folder, each behind a header that
opens and closes it, and adds the distribution's /usr/share/wallpapers:
its loose images as "system", its Plasma packages as "Plasma". A package
carries one picture at several resolutions under contents/images/, some
with a dark version under contents/images_dark/, so it shows once, the
dark version where there is one and the largest of those, labelled with
the package name rather than "5120x2880.png". Groups are keyed apart from
their names, so a local folder called "system" does not share open state
with the system group. Open state lives in the Wallpapers singleton,
because the panel is destroyed on close.

The list is one flat ListView of rows, a header or a row of thumbnails,
so only rows in view (plus cacheBuffer) are instantiated and decode. A
first version made each folder one delegate, which loaded every image of
a folder as soon as it opened; the system group alone is 727. The rows
live in a ListModel and a toggle inserts or removes only that folder's
rows: assigning a fresh JS array instead resets the view, which loses the
scroll position and re-decodes everything visible. cacheBuffer is clamped
at 0 because the column's width reads negative before layout and the
ListView warns on each negative value.

The scan's find calls go through a small shell function rather than eval.

Each thumbnail's 2px border tells how it will look on the targeted
screen. `file -N -0` reads every image's size from its header after each
scan, ~0.6s for 1161; the NUL keeps names containing ": " intact, and the
size is the last WxH in the description because a JPEG's "density 72x72"
comes first. wallp runs swaybg -m fill, which scales to cover, so the
measure is the enlargement factor: <=1 green, <=1.33 yellow, else red, in
the udt palette colours. A note under the mock screens, in that colour,
gives the size, the factor and why it will look soft or pixelated, for
the hovered image or else the staged one. The staged image keeps its
accent border. Screen sizes are fixed, as the mock's already were.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 29 insertions, 7 deletions

diff --git a/appearance/README.md b/appearance/README.md
index 467dcd3..2c127a2 100644
--- a/appearance/README.md
+++ b/appearance/README.md
@@ -4,13 +4,13 @@ Wallpapers and colour scheme in one drawer. `SUPER+Return` opens it on the
 Wallpaper tab; Tab switches tabs, Escape closes.
 
     ┌─[ Wallpaper ]─[ Theme ]─[ Sunset ]─[ Idle ]─[ Icons ]──┐
-    │  Set on [Horizontal] [Vertical]   261 wallpapers       │
-    │  ┌────┐ ┌────┐ ┌────┐ ┌────┐        ┌──┐ ┌─────┐       │
-    │  │    │ │    │ │    │ │    │        │  │ │     │       │
-    │  └────┘ └────┘ └────┘ └────┘        └┬─┘ └──┬──┘       │
-    │  ┌────┐ ┌────┐ ┌────┐ ┌────┐        ═╧═  ══╧══         │
-    │  │    │ │    │ │    │ │    │      [Apply] [Reset]      │
-    │  └────┘ └────┘ └────┘ └────┘                           │
+    │  Set on [Horizontal] [Vertical]   1161 wallpapers      │
+    │  ▸ wallpapers                 16    ┌──┐ ┌─────┐       │
+    │  ▾ SFW                        30    │  │ │     │       │
+    │  ┌────┐ ┌────┐ ┌────┐ ┌────┐        └┬─┘ └──┬──┘       │
+    │  │    │ │    │ │    │ │    │        ═╧═  ══╧══         │
+    │  └────┘ └────┘ └────┘ └────┘     enlarged 1.6×: …      │
+    │  ▸ system                    727  [Apply] [Reset]      │
     └────────────────────────────────────────────────────────┘
 
 ## Running it
@@ -75,6 +75,28 @@ would look like: the staged pick where there is one, what is currently set
 where there is not, and the hovered thumbnail on the targeted screen while the
 pointer is over it.
 
+The thumbnails are grouped by folder, each a header that opens and closes
+it, closed to begin with and remembered while the shell runs. The local
+groups are the top-level folders of `~/Pictures/wallpapers`, with the images
+loose in it as a group of its own; after them come the distribution's,
+`/usr/share/wallpapers`, as `system` for its loose images and `Plasma` for
+its packages. A Plasma package holds one picture at several resolutions,
+some in a dark version too, so it shows once: dark where there is one, then
+the largest, named after the package rather than its `5120x2880.png`.
+
+The list is flat, one row of thumbnails per item, so only the rows in view
+exist and decode, and a folder of hundreds loads as it scrolls. Opening or
+closing a folder inserts or removes just its rows, which keeps the scroll
+position and the thumbnails around it. A first version made each folder one
+item, which loaded every thumbnail of a folder the moment it opened.
+
+Each thumbnail's border says how it will look on the targeted screen, from
+its real size, which `file` reads from the header after each scan (half a
+second for a thousand). `swaybg -m fill` scales to cover, so the measure is
+how far it enlarges: not at all is green, up to 1.33x yellow, past that red.
+Under the mock screens a note in the same colour says why, for the hovered
+image or else the staged one. The staged image keeps the accent border.
+
 `wallp` does the actual work, including running `udt-accent`, so the accent
 follows the new wallpaper exactly as it does from a terminal. This panel
 replaces its qarma file dialog, not the script.