Feature proposal: Live window thumbnails with text filter and hint-based selection

[sim590]

Context

This proposal addresses #26 (Live thumbnails — 16 upvotes, help wanted) and #424 (Live window preview) by introducing live window thumbnails with a new selection workflow.

Hyprland already supports ext-image-capture-source-v1 with per-toplevel capture and ext-image-copy-capture-v1 with damage notifications — all the building blocks are there for live window previews.

Proposed feature

A grid of live window thumbnails with a two-phase selection workflow:

Phase 1: Text filter (default)

When activated, the view displays all windows as live thumbnails in a grid. The user types text to filter windows by title, class, or workspace name. As windows are filtered out:

• They disappear from the grid
• The grid reorganizes dynamically
• Remaining thumbnails grow larger, making visual identification progressively easier

This addresses a fundamental problem with exposé-style views: with many windows, thumbnails are too small to be useful. Filtering reduces the count and increases thumbnail size proportionally.

Phase 2: Hint selection (via TAB)

Pressing TAB overlays alphanumeric hint labels (j, k, l, f, d, s, ...) on each remaining window. The user presses the corresponding key to select the window instantly. TAB toggles between the two phases, allowing users to go back and refine their filter if needed.

How it compares to existing modes

	Switch	Overview	This proposal
Activation	Hold modifier + Tab to cycle	Toggle (quick press)	Toggle (quick press)
Display	Linear window list with icons	Downscaled workspace layout + launcher	Grid of live window thumbnails
Selection	Sequential (Tab, Tab...)	Mouse click or arrow keys	Text filter → alphanumeric hints
Live thumbnails	No	No	Yes (ext-image-capture-source)
Integrated launcher	No	Yes	See "Structural options" below

Configuration

# Suggested configuration keys (names TBD)
charorder = "jkluiopyhnmfdsatgvcewqzx1234567890"
auto_select_threshold = 0  # 0 = disabled; when ≤ N windows remain, 
                           # auto-switch to hint phase
filter_fields = ["title", "class", "workspace"]
case_sensitive = false

Technical approach

Live thumbnails via ext-image-capture-source-v1

This would be the first screen capture integration in hyprshell. The protocol enables:

• Per-window capture (not just per-output) via ext-foreign-toplevel-image-capture-source-v1
• DMA-BUF transfer (GPU-to-GPU, no CPU copy overhead)
• Continuous updates with damage notifications (only re-render changed windows)

Captured buffers would be displayed as GdkTexture (via gdk::Texture::for_dmabuf() or gdk::MemoryTexture) in GTK4 widgets.

What gets reused (unchanged)

• exec-lib/collect.rs — Hyprland IPC data collection
• core-lib — ClientData, HyprlandData types
• windows-lib/data.rs — MRU sorting
• windows-lib/icon.rs — icon resolution
• exec-lib — switch_client(), switch_workspace()
• GTK4 + gtk4-layer-shell + Relm4 framework
• CSS theming system

Structural options

I see two ways this could be integrated, and I'd like your input on which you'd prefer:

Option A: New separate mode (mosaic)

A third mode alongside Switch and Overview, following the existing pattern:

crates/windows-lib/src/
├── switch/     # existing, unchanged
├── overview/   # existing, unchanged
├── mosaic/     # NEW
│   ├── root.rs
│   ├── capture.rs
│   ├── grid.rs
│   ├── filter.rs
│   └── hints.rs
└── shared/

Configuration would add a [windows.mosaic] section. No launcher integration — the text input is exclusively for filtering open windows.

Pros:

• Clean separation, no risk of breaking existing modes
• Input field has a single, unambiguous purpose (window filtering)
• Easier to develop incrementally

Cons:

• Potentially seen as redundant with Overview

Option B: Extend Overview

Add live thumbnails and the filter/hint workflow as options within the existing Overview mode.

Pros:

• No new mode to maintain
• Users get thumbnails in an interface they already know

Cons:

• Input field conflict: Overview's input currently drives the launcher (search apps, calculate, web search). The mosaic workflow uses the input field to filter open windows. These serve fundamentally different purposes. Possible solutions (prefix character, mode toggle key) each add friction to one of the two workflows.
• The display logic differs substantially: Overview organizes by workspace (windows nested inside workspace containers), while the mosaic flattens all windows into a single grid regardless of workspace.
• Risk of increased complexity in an already working component.

My preference

I lean toward Option A (new separate mode). The input field conflict in Option B feels like a fundamental UX compromise that would add friction to one of the two workflows regardless of the solution chosen (prefix, toggle key, etc.). A separate mode keeps both experiences clean: Overview remains a workspace viewer with launcher, and the mosaic mode becomes a dedicated window finder.

That said, I'm open to Option B if you feel it fits better with the project's direction.

Questions

1. Which structural approach do you prefer (new mode vs. extending Overview)?
2. If extending Overview: how should the input field conflict be handled?
3. Any preferences on where the capture protocol integration should live? (separate crate? inside exec-lib?)
4. I have some experience with Rust (hypr-layout, contributions to Reedline/Nushell), but I'm relatively new to the hyprshell codebase — I'd welcome guidance on project-specific conventions and architecture decisions.

I'm happy to start with a proof-of-concept PR on whichever approach you prefer. Looking forward to your thoughts!

[H3rmt]

Thanks for the detailed feedback.
I think that live thumbnails could definitely be implemented across the existing "switch" and "overview" modes. The idea of an "overview-only" mode is also interesting as removing the launcher definitely allows for more filtering by typing.

They aren't going to be top priorities for the moment, though. I’m currently focused on:

1. Cleaning up the codebase post-realm rewrite (getting CI passing again).
2. Rewriting the plugin system (it is kind of weirdly structured, beacuse I moved from custom sorting logic to using a fzf matcher).
3. Implementing clipboard history, which has been on the roadmap for at least half a Year.

[sim590]

Thanks for the detailed feedback and for being open to this!

They aren't going to be top priorities for the moment, though

That's totally understandable! I'd be happy to take ownership of this feature and drive the implementation independently, so it won't pull you away from your current priorities (CI cleanup, plugin rewrite, clipboard history).

I'll go with Option A (separate mosaic mode) since you confirmed that an overview-only mode without the launcher makes sense for text-based filtering. I'll start working on a proof of concept.

If architectural questions come up along the way, would you prefer I ask them here, or would a separate discussion thread be more appropriate?

[H3rmt]

I think this should be split into 2 separate features, the new overview mode and the live preview stuff.

I think the the live preview for windows is the most requested feature and won't touch most of the current code (I think).

We could hide it behind the HYPRSHELL_EXPERIMWNTAL flag, or we could add the config option directly to both the modes.
For a first implementation I would prefer the env flag. Interested users could then try this feature out and when confirmed working for multiple users we can add config options, add nix home manager options and add it to Settings app

[sim590]

That makes a lot of sense! Splitting it into two features is a good approach. The live preview layer is the hardest technical piece and benefits the whole project.

I'll start with the live preview behind HYPRSHELL_EXPERIMENTAL:

1. Implement the ext-image-capture-source-v1 / ext-image-copy-capture-v1 integration
2. Add live thumbnails to the existing Switch and Overview modes
3. Gate it behind the env flag

Once that's stable and validated by users, we can build the mosaic mode on top of it as a second step.

A couple of quick questions before I start:

• For the capture integration code, would you prefer it in a new crate (e.g. capture-lib) or inside exec-lib?
• Should I target the current hyprshell-release branch, or is there a development branch I should work against given the ongoing CI cleanup?

[H3rmt]

You should target the hyprshell branch (it is the dev branch)

The hyprshell-release branch always is set to the latest release.

I think this could be implemented inside the exec-lib crate.

I am still working on the launcher plugin rewrite as many CI lint isses are unused functions and properties. I will then fix the remaining issues (most are just unused imports).

[sim590]

Just a little update: I made a little prototype for testing out SHM capture. It's on my fork on capture-proto branch.

capture.mp4

I'm now working on making the change for DMA-BUF approach which is more efficient. After that, I'll move the code to the appropriate directory and plug it in the two existing modes.

[sim590]

Here is another update: I have DMA-BUF live captures working with automatic detection of newly opened and closed windows (on the same branch). Here is a demo:

capture.mp4

Now, I'm working on plugging this into exec-lib / windows-lib.

[sim590]

OK!

capture.mp4

Code is on branch live-window-capture. I'll start a PR soon.

[sim590]

Now that the capture work is merged ( 🎉 ), here's the plan for the mosaic mode itself:

Layout engine — abstracted behind a LayoutEngine trait so it's swappable. MVP uses an adaptive grid that scales to fit the screen. For the final version I'm planning to implement the MaxRects bin-packing algorithm with bisection to find the optimal scale factor — this handles windows of widely different aspect ratios much better than a uniform grid.

Interaction — two-phase toggle via TAB:

• Default: type to live-filter windows by title/app_id (ordered by pertinence + MRU)
• TAB: switch to alphanumeric hint selection (a, s, d, f... mapped in MRU order)
• TAB toggle back to filter mode
• Auto-select threshold: configurable, off by default. Single remaining window is always explicit.

Canvas — plain GtkFixed with custom-positioned thumbnails, no GTK chrome around them. Spring animations for fluid repositioning when the filter changes (polish step).

I'll send a draft PR once the grid layout + filter/search + hint selection loop is working, so you can get a feel for the interaction early. The live capture code should slot right into the mosaic client widgets.

[H3rmt]

I would recomend to just layout the windows the same way switch in nonworkspace mode does it, all the same size inside a box that has configurable max children (via config)

[sim590]

Thanks for the suggestion! The uniform grid makes a lot of sense for the switch mode, but for the mosaic mode I've been aiming for a slightly different look: uneven tile sizes that adapt to each window's aspect ratio, with configurable spacing between windows and around the frame, plus smooth animations when the layout changes. That's the visual style I had in mind from the start.

I'm still using a grid for the early prototype to move fast, but the LayoutEngine trait is there so we can experiment with different packing strategies later without touching the rest of the code.

Does this direction work for you? If the mosaic concept doesn't quite fit where you see hyprshell going, no worries. I can build it as a standalone tool in my own project on top of the capture code. Either way, the capture work now benefits hyprshell regardless.

[H3rmt]

You can always open up a PR in draft mode so I can see what you are doing. you could also post screenshots, etc. into the PR.

This way I can quickly comment on the code

[H3rmt]

https://github.com/H3rmt/hyprshell/releases/tag/v4.11.0-alpha