Surface Wallpaper Engine project type in the UI

[louzt]

Closes #275

Summary

Normalize Wallpaper Engine metadata from project.json and surface the detected project type directly in the UI so scene, video, and web entries stop looking like generic static previews.

Architecture

This PR is standalone on top of main; it does not require #279 to be merged first.

To keep Wallpaper Engine-specific metadata out of the generic file/image helpers, this PR adds a small waypaper/wallpaperengine.py module for the UI metadata slice:

• preview discovery for Wallpaper Engine projects
• project directory normalization
• project.json loading and type/title normalization
• type-aware UI labels such as Title [scene], Title [video], and Title [web]
• defensive fallback to the project directory name if metadata cannot be read while rendering the grid

waypaper/common.py remains focused on generic file/image operations, and waypaper/app.py imports the Wallpaper Engine label helpers from the dedicated module.

If #279 or #280 lands first, the shared wallpaperengine.py module boundary can be reconciled through a normal rebase. This PR remains reviewable as the narrow UI metadata slice.

Scope Boundary

• No backend routing changes here.
• No launcher hardening here.
• No renderer behavior changes here.
• This PR exists so later behavior decisions can rely on normalized metadata instead of preview filenames.

Validation

• python3 -m py_compile waypaper/app.py waypaper/common.py waypaper/wallpaperengine.py tests/test_wallpaperengine.py
• python3 -m unittest discover -s tests
• git diff --check origin/main...HEAD

Current result: 17 tests pass.

[louzt]

Updated this branch after the module-boundary cleanup from the neighboring PRs, and clarified the GTK grid layout detail added by the visible labels.

What changed:

moved Wallpaper Engine metadata helpers out of common.py

added a small standalone waypaper/wallpaperengine.py module for preview discovery, project.json normalization, and type-aware UI labels

updated app.py so the GTK grid consumes Wallpaper Engine labels from that dedicated module

added unit tests for metadata normalization, label formatting, preview discovery, and bad-metadata fallback

documented the + 34 row-height padding in app.py

The + 34 is there because this PR changes each grid item from image-only to image + visible wrapped label. The extra row height reserves the vertical label footprint: 6px from the Gtk.Box spacing plus roughly one wrapped text row. That prevents later rows from overlapping or truncating labels when GTK reflows the grid during window resizing. This is especially easy to trigger under tiling compositors such as Niri, Hyprland, or Sway, but it is the same GTK layout issue under any live resize.

The metadata fallback is also intentional: if a Workshop project's project.json is missing or malformed, the grid falls back to the project directory name instead of failing while rendering thumbnails. Additionally, layout stability has been fully validated across complex multi-monitor environments, supporting both vertical and horizontal display alignments seamlessly.

This keeps #278 independent from #279 while still following the same module boundary. If #279 or #280 lands first, the shared module can be reconciled by a normal rebase.

Validation after the update:

[anufrievroman]

My main issue is that this creates a label with a name, regardless of the backend. Typically we don't have labels on thumbnails by design, just to keep a minimal look. Are these labels somehow necessary on this backend? I know that the name in the tooltip is meaningless number, but even if so, it should not affect the other backends, but ideally, it would be great if the app.py part would not be touched without real necessity.

[louzt]

Fair point, and you're right — the visible label is gratuitous for the
generic image backends, and the +34 row-height padding I added was
specifically to keep that label from overlapping later rows, so it
shouldn't be there if the label isn't.

The shape I'm going to push on this branch:

• Drop the visible label and the +34 row-height padding in
  app.py. app.py returns to its main shape — zero GTK layout
  changes from this PR.
• Keep the type tag, but move it into the existing tooltip. The
  tooltip already shows the project name, so for Wallpaper Engine
  items it will read e.g. Neon Driver [scene] / Title [web], with
  [type ?] only for unknown type values.
• Keep waypaper/wallpaperengine.py as the internal module:
  common.get_image_name will call the new
  get_wallpaperengine_image_name helper when the path looks like a
  Workshop project (i.e. has a sibling project.json), so the other
  backends' tooltip behavior is unchanged. The function falls through
  to the regular path-based name when project.json is missing or
  malformed.
• Tests stay on the new module (normalization, label formatting,
  preview discovery, bad-metadata fallback) plus three new tests for
  the get_image_name Workshop detection and its two fallback paths.

Net diff for main:

• waypaper/app.py: 0 lines
• waypaper/common.py: -18 net lines (delegate to the new helper)
• waypaper/wallpaperengine.py: new module
• tests/test_wallpaperengine.py: new tests

Re: the backends concern — the type tag only ever applies to paths
sitting next to a project.json, and it's only added to the tooltip
string get_image_name returns. The image backends' tooltip behavior
is untouched, and the +34 padding never lands on main, so the
layout risk you flagged disappears with the visible label.

Re: the #278 / #279 / #280 ordering — the three branches all touch
wallpaperengine.py. The least-painful merge order is probably #278
(this branch, smallest) → #280 → #279 (launcher-hardening, the
bigger module + diagnostics). That way #279 can rebase once at the
end to consolidate wallpaperengine.py without dragging behavioral
changes.

I'll push the reduced branch shortly and ping back with the diff
stat + unittest result. Apologies for the scope creep on the first
pass.

[Im-shamo]

Title [scene], Title [video], and Title [web]

I use the wallpaperengine app on windows. I don't know what they are too.

[louzt]

Regarding your question about necessity: The labels were indeed too intrusive, hence why I moved them to the tooltip.

About the 'why': Moving from Wallpaper Engine on Windows to Linux (specifically tiling managers like Niri/Hyprland), I noticed that the way these assets are handled is fundamentally different. On Windows, the engine self-adjusts based on the asset type (Scene, Video, Web), but in Linux, we are often forced to run them through compatibility layers or specialized backends.

This metadata normalization is not just about UI labels; it is about establishing a stable data contract for Wallpaper Engine items within Waypaper. Without this in "'main'", any logic required to improve backend routing or handle edge cases (like the ones I've been working on to prevent process conflicts) has to re-scan project.json files repeatedly, leading to fragmented and brittle code.

By normalizing this metadata here, we move the 'brittleness' of Workshop projects into one tested, internal module. It turns Waypaper into a more robust tool that understands what it is running, rather than just treating everything as a generic image path. The tooltip is just the first consumer of this data, but it essentially future-proofs the codebase for better backend integration. In this way, and with other follow-ups hardenings on my edge, i been capable of fluent performance, ofc if other layer are above this in a better set up its great, but on the Penguin could be useful for debugging and actual compatibility on some edge cases/distros/way that the OS manage windows different than in Windows itself.

[anufrievroman]

Thank you for the changes, sorry I didn't have time yet to review everything again, I'll try to find time soon