Skip to content

feature: add scratchpad feature for dropdown window support - #334

Open
Granitosaurus wants to merge 9 commits into
malbiruk:mainfrom
Granitosaurus:scratchpad
Open

Granitosaurus wants to merge 9 commits into
malbiruk:mainfrom
Granitosaurus:scratchpad

Conversation

@Granitosaurus

@Granitosaurus Granitosaurus commented Nov 7, 2026 •

Copy link
Copy Markdown

Initial WIP

Working on a scratchpad feature for enabling pinned toggled windows like a dropdown-like terminal similar to Yakuake

2026-11-07_14-47-51.mp4

In the video above I have a dropdown kitty terminal that I hide/unhide with meta + w key. The window preserves its location, dimensions and contents between hide/unhide.

Goals:

  • single global scratchpad per program
  • hotkey toggled e.g. meta + w should hide/unhide the scratchpad
  • support any program window (terminal, email client, music player etc.)
  • hiddes scratchpad should still receive data and function (e.g. terminal shouldn't drop render)
  • always pinned and on top
  • preserve size and location in hide/unhide
  • user tests for regression and UX inconsistencies
  • full code review

Add toggle-scratchpad: stow a window and bring it back, no animation

toggle-scratchpad <app_id> <command> is a new bindable action. One keypress:

  • spawns <command> when no window with that app_id exists,
  • stows the window when it is showing: it vanishes instantly, but stays mapped and its client keeps running,
  • shows it again when stowed: back at exactly the position, size and pin site it left from, raised and focused.

That makes a Yakuake/Quake-style dropdown terminal possible without any external script:

[keybindings]
"mod+w" = "toggle-scratchpad dropdown-term kitty --class dropdown-term"

[[window_rules]]
app_id = "dropdown-term"
pinned_to_screen = true
position = [0, 185]      # output-relative, Y-up from output centre
size = [1200, 450]
2026-11-08_14-19-19.mp4

Why it matters: driftwm has no minimize or hide, so scripts can only fake this by moving the window off screen (pin, unpin, msg move, re-pin). That path runs the pin/unpin animation machinery, so the window visibly resizes and creeps into place, and the dance is slow. A compositor-side stow avoids all of that.

Behaviour details:

  • Move or resize the window while it is up: the next show restores that geometry, not the rule's.
2026-11-08_14-22-34.mp4
  • Stowing the focused window hands keyboard focus to the most recently used window that is not itself stowed (it is not checked against the viewport).
2026-11-08_14-23-46.mp4
  • A stowed window does not catch clicks at its old spot, and is skipped by Alt+Tab, zoom-to-fit and focus-nearest, because all of those already honour the shared "hidden" predicate (details below).
  • Works with any app; app_id is matched exactly. All windows with that app_id (e.g. a mail client's compose windows) and their transient dialogs are stowed and shown together. Intended for pinned_to_screen windows (see limitations).
  • A fullscreen / maximize the app requests while stowed is applied when it is shown again.
  • The scratchpad is not bound to display and will restore on active display trying to replicate % based location if display has different resolution
2026-11-08_16-58-21.mp4
  • A press while a freshly spawned app is still starting does not spawn it a second time (3 s debounce), and a window that has not had its first placement yet is left alone, so its window rules still apply.
  • If a config reload leaves a stowed window with no scratchpad binding, it is shown again rather than stranded.
  • Scratchpad apps are not session-restored: no stand-in comes back after a restart (the binding respawns the app on demand). Any binding kind counts (key, tap, mouse, gesture, touch). A restore_windows = true window rule on the app overrides that.

Related: #333 fixes an existing bug (scroll over a pinned window is dropped when a suspended stand-in is beneath it) that this feature makes easy to hit. Independent of this PR; this one does not depend on it.

Known limitations (deliberately out of scope)

  • Pinned windows lose their original position across a hotplug round trip. This is existing pinned-window rehoming, not scratchpad-specific: when an output disappears, reassign_orphaned_pinned clamps each pin into the surviving output and overwrites the stored site, so it is not restored when the original output returns. A stowed scratchpad inherits that (it follows its pin to the survivor and shows normally, just at the clamped spot). Fixes would be either remembering the pre-clamp site per output or percentage-based placement in window rules. Happy to follow up separately if wanted.
  • Not exercised: how taskbars / foreign-toplevel clients, msg screenshot window and idle inhibitors treat a stowed window.
  • Focus handoff: on hide, focus goes to the most recent non-stowed window, which may be off screen if the canvas was panned.
  • Non-pinned windows: showing a stowed window re-raises and focuses it but does not pan the camera to it, so it may be off screen. Unverified on real hardware; the feature is aimed at pinned windows.
  • IPC wording: the focus, move, pin and suspend verbs refuse stowed windows via the existing deferred-adopt guards, so their error text ("mid-relaunch") is misleading for a stowed window.
  • Naming debt: the hidden predicate is still called hidden_by_deferred_adopt although it now means "stowed or deferred". A rename touches ~28 call sites, so I left it for a separate commit if you want it.
  • Frame callbacks: a stowed client still gets driftwm's off-screen heartbeat (FRAME_CALLBACK_THROTTLE), so a terminal keeps rendering, at heartbeat rate instead of full speed.

Implementation and architecture

(For reviewers, future maintainers and automated tooling.)

Design in one paragraph

A stowed window is not unmapped. It stays on the stage with its client, size, z-slot and pin site untouched. Stowing adds its root surface to a new list, DriftWm::scratchpad_hidden, and the existing "mapped but invisible" predicate used for first-commit deferred adopts is extended to also report true for those surfaces. Every site that already skips such windows (render, canvas hit-testing, focus, fit/zoom, placement, persistence, IPC guards) therefore skips stowed windows. Reusing the predicate also reuses its semantics: placement suppression and the fullscreen/maximize queue, which the toggle accounts for (it never stows a window before its first placement, and it applies the queued request on show). The four pinned hit-test walks did not consult the predicate and are fixed below. Showing removes the surface from the list, cancels any in-flight window animation, then raises and focuses, so it reappears in one frame at its saved place.

Reasoning for reuse over a new stage-level flag: the deferred-adopt predicate already has ~28 audited call sites covering exactly "drawn nowhere, out of every canvas relation, but alive". A parallel flag would need the same sites threaded, and any missed site would leak.

State

Item Where Notes
scratchpad_hidden: Vec<WlSurface> src/state/mod.rs, init in src/state/init.rs Root surfaces of stowed windows; same lifetime pattern as deferred_adoptions.
Predicate src/state/suspended.rs: root_hidden_by_deferred_adopt / hidden_by_deferred_adopt Also true for scratchpad_hidden members. The fast-path guard now checks both lists are empty.
Cleanup cleanup_surface_state in src/state/window_lifecycle.rs Drops the surface so a dead client cannot leave a stale entry.

Action and config

Piece Where
Action::ToggleScratchpad { app_id, command } src/config/types.rs
Parsing: toggle-scratchpad <app_id> <command...> (both required) src/config/parse.rs, plus ACTION_NAMES and the exhaustive action_name test helper
Dispatch src/input/actions.rs calls DriftWm::toggle_scratchpad
Docs config.reference.toml entry and example; docs/config.md regenerated with UPDATE_CONFIG_DOCS=1 cargo test docs_config_md_is_up_to_date

The action is not in runs_during_fullscreen, so like other window actions it exits fullscreen first.

Session restore (src/config/mod.rs, src/state/session_store.rs)

A restored stand-in for a scratchpad app is useless (the binding respawns the app) and the toggle would then spawn a second window next to it, since it only matches live windows. So Config::is_scratchpad_app(app_id) is true when any binding (key, tap, mouse, gesture or touch gesture) holds toggle-scratchpad for that app_id, and restore_windows resolves to false for such apps, on both sides:

  • save: resolve_restore_windows skips their live windows when building the envelope;
  • load: resolve_restore_windows_for_record leaves their saved records unmaterialized (carried forward inert, like any other excluded record).

Precedence: an explicit restore_windows window rule > scratchpad default (off) > [session] restore_windows. An app toggled only via driftwm msg action toggle-scratchpad ... has no binding and gets no implicit exclusion.

The toggle (src/state/scratchpad.rs, new)

toggle_scratchpad(app_id, command):

  1. Collect the group: every non-widget client window whose app_id_or_class() equals app_id exactly (stricter than the IPC selector's case-insensitive substring match), plus, transitively, windows whose xdg_toplevel parent is in the group.
  2. Empty group -> spawn_command(command, child_env) (same no-cursor-reveal path as spawn), unless the same app_id was spawned in the last 3 s (scratchpad_spawns).
  3. Any group member still in pending_center (no first placement yet) -> do nothing.
  4. All members stowed -> show: remove them from the list, cancel_window_animation, apply_queued_geometry_request (a fullscreen/maximize asked for while stowed), then raise_and_focus each. No re-map and no pin/unpin, so no animation entry is ever created and the pin site is untouched.
  5. Otherwise -> hide: push the members, cancel_window_animation, drop from the focus history, and if one held focus, give focus to the most recent history entry that is not stowed (or clear focus if none).

release_unreachable_scratchpads, run after a config reload, shows again any stowed window (and its children) whose app_id no binding toggles any more.

Hit-testing fix for pinned windows (src/input/mod.rs)

The canvas walks already skipped hidden windows, but the four pinned (screen-space) walks did not: pinned_topmost_under, pinned_window_under, pinned_decoration_under and pinned_resize_margin_under. Without a fix a stowed pinned window stayed an invisible click-catcher and resize-cursor trigger at its old site. Each now skips windows for which hidden_by_deferred_adopt is true. The regression test fails without this change.

Frame callbacks (src/render/lifecycle.rs)

post_render computes on_screen per window to choose between render-rate frame callbacks and the throttled off-screen heartbeat. A stowed window is forced to on_screen = false, so its client keeps receiving the heartbeat (a terminal keeps processing output) without being treated as drawn. Rendering itself skips it through the shared predicate.

Hotplug

Stowed windows stay pinned, so reassign_orphaned_pinned and sync_pinned_locs apply to them unchanged: unplugging the output they were pinned to rehomes the pin onto the survivor (clamped), and the last-output placeholder swap rehomes it onto the new output. Both paths are covered by tests (see below). The position-memory limitation above comes from the same code.

Tests (src/tests/scratchpad.rs, new, 15 tests; 3 more in src/tests/session_restore.rs)

  • hide keeps the window on the stage with its pin site, and focus moves from it to the other window
  • hiding the focused window focuses the most recent window
  • show restores the same site and position, focused, raised, with no animation entry
  • hidden scratchpad follows its pin when its output is unplugged, and shows correctly afterwards
  • hidden scratchpad survives losing and regaining the last output
  • hidden scratchpad is not hit by any of the pinned hit-test walks (content, owner, chrome, margin, decoration)
  • a window awaiting its first placement is left alone
  • a fullscreen requested while stowed applies on show
  • same-app_id windows and a transient dialog hide and show together
  • a repeat press during startup does not respawn
  • a reload releases a stowed window no binding reaches, and keeps bound ones
  • every binding kind (key, mouse, gesture, touch) marks a scratchpad app
  • scratchpad_hidden is part of debug_counters, so the fixture's teardown check covers it

In session_restore.rs:

  • a scratchpad app's live window is not saved, an ordinary app's is
  • a saved record for a scratchpad app does not materialize as a stand-in, others do
  • an explicit restore_windows = true rule overrides the scratchpad default

cargo fmt --check, cargo clippy --all-targets -- -D warnings and cargo test -- --include-ignored --skip soak all pass locally.

Verification

Run as the author's daily-driver compositor on NixOS (udev backend, 3440x1440 monitor plus a 2880x1800 laptop panel at scale 2.0), with a pinned kitty and a pinned Thunderbird as scratchpads.

Checked by hand on that setup:

  • spawn / hide / show, with no visible animation;
  • the window returns at the position and size it was left at, after moving and resizing it;
  • focus returns to the previously used window on hide;
  • no stand-in after a reboot for either scratchpad app;
  • a Thunderbird compose window opened from the scratchpad hides and shows together with the main window (same app_id);
  • unplugging the external monitor and plugging it back: the scratchpad survives and keeps working. It lands at the clamped site rather than its original one, which is the existing pin-rehome limitation above.

Covered by the automated tests, not checked by eye: click-through of a stowed window (all four pinned hit-test walks), the last-output-removed placeholder path, the first-placement guard, the spawn debounce, a fullscreen requested while stowed, config-reload release, and the mouse/gesture/touch binding kinds for the session-restore exclusion.

Neither tested nor checked by eye: exclusion from the overview (zoom-to-fit), Alt+Tab and focus-nearest. That relies on those paths honouring the shared hidden predicate, which I read in the code but did not exercise.

Suggested follow-ups (not in this PR)

  1. Rename hidden_by_deferred_adopt / root_hidden_by_deferred_adopt to something neutral such as hidden / root_hidden.
  2. Remember a pinned window's pre-rehome site per output and restore it when that output reconnects (benefits all pinned windows).
  3. Optional percentage-based position / size in window rules.
  4. Neutral IPC error text for stowed windows.

Granitosaurus and others added 3 commits November 7, 2026 12:58
toggle-scratchpad <app_id> <command> hides or shows the window with that
app_id, spawning <command> when none exists. A hidden window stays mapped
with its client, size and pin site, so showing it again is one frame at
the same place with no animation.

Hiding reuses the deferred-adopt hidden state: the window joins
scratchpad_hidden, which root_hidden_by_deferred_adopt now also consults,
so rendering, hit-testing, focus and IPC already skip it. Hidden windows
get the off-screen frame-callback heartbeat so clients keep running.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The pinned walks (content, chrome, resize margin, decoration) never
consulted the hidden state, so a stowed pinned scratchpad kept catching
pointer events at its old site. Skip it in all four, and cover the
unplug paths (survivor rehome, last-output placeholder) with tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A scratchpad is respawned by its own binding, so a stand-in restored for
it after a restart is only in the way, and toggling then spawns a second
window beside it. Resolve restore_windows to false for any app a
toggle-scratchpad keybinding names, on both the save and the load side.
An explicit restore_windows rule still wins.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@Granitosaurus Granitosaurus changed the title WIP: add scratchpad feature for dropdown window support WIP feature: add scratchpad feature for dropdown window support Nov 7, 2026
@Granitosaurus Granitosaurus reopened this Nov 7, 2026
…eload release, spawn debounce

Toggle now acts on every window with the app_id plus transient children,
ignores a window that has not had its first placement, applies a
fullscreen/maximize requested while stowed, debounces repeat spawns, and
releases stowed windows whose binding vanished on config reload. Any
binding kind marks a scratchpad app for session restore. scratchpad_hidden
joins debug_counters. Fix the config reference example that split the
default keybinding table.

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

Copy link
Copy Markdown
Author

I ran extensive review for edge case hunt and it did come up with several tiny edge case issues that I fixed. I'm working on formalizing this PR body next with my introduction for this feature.

Granitosaurus and others added 2 commits November 8, 2026 14:45
…show

The action guard ends fullscreen before the toggle runs; remember which
window that was and queue its fullscreen so show re-enters it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@Granitosaurus
Granitosaurus marked this pull request as ready for review November 8, 2026 11:30
@Granitosaurus Granitosaurus changed the title WIP feature: add scratchpad feature for dropdown window support feature: add scratchpad feature for dropdown window support Nov 8, 2026
@Granitosaurus

Copy link
Copy Markdown
Author

ok ready for review. been running this for some time now and haven't noticed any regressions.

Granitosaurus and others added 2 commits November 9, 2026 01:27
A pinned scratchpad kept the pin of the output it was created on, so
stowing on one display and showing from another brought it back on the
first. Showing now rebinds the pin to the active output, keeping the
screen position.

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

Granitosaurus commented Nov 17, 2026 •

Copy link
Copy Markdown
Author

after using this for a week I'm very happy with this feature.
The only issue that still needs polish is location transfer between two displays of different aspect ratios. For example: scratchpad located on screen1 540, 100 (middle of 1080 screen with 100px padding of top, like yakuake dropdown), when it's recovered on screen2 it doesn't exactly match the expected location. So need to iron this out a bit but it's a very niche inconsistency and overall it's good to merge!

Scaling the frame centre pushed a large window off a smaller output and
the clamp flattened it against the edge. Keep the share of free space
(output minus frame) on each axis instead.

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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant