dotfiles/docs/tiling-wm-experience.md

# Tiling WM Experience Spec

This document describes the tiling window manager experience I am targeting.

## Priority Levels

- Required: daily-driver behavior.
- Important: expected for parity, but a rough first version is acceptable.
- Nice: useful polish or compatibility.

## Modifier Terminology

- `Super` names the physical modifier key often labeled Windows, Command, GUI,
  or OS depending on the keyboard.
- `Hyper` means a higher-order logical modifier layer used for monitor,
  workspace, utility, and cross-context operations.
- Prefer implementing `Hyper` as its own virtual modifier or equivalent logical
  mask when the environment supports that.
- If a dedicated virtual `Hyper` mask is not practical, `Ctrl+Alt+Super` is the
  fallback chord.
- The fallback `Hyper` chord intentionally does not include `Shift`; portable
  `Hyper` bindings only use the plain `Hyper` layer and the `Hyper+Shift`
  layer.
- Do not require `Hyper+Ctrl`, `Hyper+Alt`, or `Hyper+Super` bindings. Those
  modifiers may already be part of the fallback `Hyper` chord.
- Binding descriptions should use `Super` and `Hyper` rather than
  hardware-vendor names.

## Workspaces and Monitors

Required behavior:

- Workspaces are a shared global set, not independent per-monitor namespaces.
- Focusing workspace `N` shows workspace `N` on the currently focused monitor.
- Moving a window to workspace `N` does not require caring which monitor
  currently owns that workspace.
- Sending the focused window to workspace `N` without following it is a
  first-class operation.
- Moving the focused window to workspace `N` and following it is a first-class
  operation.
- Sending the focused window to the next empty workspace without following it is
  a first-class operation.
- Moving the focused window to the next empty workspace and following it is a
  first-class operation.
- Normal workspaces are bounded to `1..9`.
- Workspace history is tracked per monitor.
- Last-workspace toggle uses the current monitor's workspace history.
- Workspace cycling works on the current monitor within the bounded workspace
  set.

Important behavior:

- Swapping the current workspace contents with another workspace is available.
- Moving a window to an empty workspace on another monitor is available.
- Moving the focused window to another monitor without following keeps keyboard
  focus on the original monitor.
- Moving the focused window to another monitor and following it moves keyboard
  focus to the destination monitor.
- Hidden/special workspaces exist for scratchpad state.
- Hidden/special workspaces exist for minimized state.
- Hidden/special workspaces are excluded from ordinary workspace cycling.
- Hidden/special workspaces are excluded from taffybar's normal workspace list.

## Directional Navigation

Required behavior:

- Directional window focus is available.
- Directional window swapping or movement is available.
- Directional move-to-monitor is available while preserving useful focus.
- Directional monitor focus is available.
- Directional window movement between monitors is available.
- Moving the focused window to an empty workspace on the monitor in a direction
  remains required behavior, but it should not require an extra `Hyper`
  modifier beyond `Shift`.

Important behavior:

- Directional focus in tabbed/fullscreen mode should cycle predictably through
  windows even though their screen geometry overlaps.
- Keyboard resize remains available, but it should not displace the directional
  move-to-monitor binding.

## Layouts

Required behavior:

- Tiling is dynamic.
- Primary layout is equal-width vertical columns.
- All ordinary splits are vertical.
- Adding windows dynamically redistributes all tiled windows evenly.
- Removing windows dynamically redistributes all tiled windows evenly.
- Ordinary use should not require manually managing a split tree.
- Tabbed/fullscreen-style monocle layout is available.
- Directional window navigation bindings continue to switch windows in
  tabbed/fullscreen mode.
- The important layouts are columns and tabbed/fullscreen.

Important behavior:

- One-window workspaces should have no visible gaps or use smart gaps.
- Gaps are small in normal multi-window layouts.
- Dialogs float.
- Dialogs are centered.
- Layout state is per workspace when the compositor supports it.
- There is a command to jump directly to the columns layout and one to jump
  directly to the tabbed/fullscreen layout.

Nice behavior:

- Gaps can be toggled.
- Fullscreen can be toggled.
- Smart borders can be toggled.
- Layout-related modifiers remain available for experiments.
- Inactive windows are slightly dimmed when supported.

## Overview and Discovery

Required behavior:

- There is an expose-style way to inspect open windows or workspaces before
  jumping.
- There is a rofi-style window picker.
- Window picker entries show icons.
- Window picker entries show titles.
- Window picker entries show workspace labels.
- Go-to-window focuses the selected window wherever it currently lives.
- Bring-window moves a selected non-visible window to the current workspace and
  focuses it.
- Replace-window swaps the focused window with a selected window where feasible.

Important behavior:

- Overview supports both "go" and "bring" workflows when possible.
- Window switchers hide scratchpad windows unless the user is explicitly using a
  scratchpad picker.
- Window switchers hide minimized windows unless the user is explicitly using a
  minimized picker.
- Window switchers hide internal windows.
- Go/bring actions unminimize selected windows when needed.

## Scratchpads

Required behavior:

- A named scratchpad exists for element.
- A named scratchpad exists for gmail.
- A named scratchpad exists for htop.
- A named scratchpad exists for messages.
- A named scratchpad exists for slack.
- A named scratchpad exists for spotify.
- A named scratchpad exists for transmission.
- A named scratchpad exists for volume.
- Scratchpads appear near-fullscreen and centered by default.
- Toggling a scratchpad deactivates fullscreen/tabbed state first.
- Scratchpads are hidden from normal workspace and window listings.

Important behavior:

- A dropdown terminal scratchpad exists.
- Scratchpad matching handles delayed class/title assignment.
- Scratchpad behavior is robust when the app is already running.
- Scratchpad behavior is robust when the app is minimized.
- Scratchpad behavior is robust when the app is on another workspace.

## Minimization

Required behavior:

- Focused window can be minimized.
- Last minimized window can be restored to the current workspace and focused.
- Minimized windows are excluded from normal layout.
- Minimized windows are excluded from ordinary go/bring lists.

Important behavior:

- A minimized picker mode exists.
- Restore-all-minimized exists.
- Other classes in the current workspace can be minimized.
- Windows of the focused class can be restored.
- All minimized windows can be restored.

## Class-Aware Workflows

Important behavior:

- Gather all windows of the focused class onto the current workspace.
- Raise-or-spawn exists for the browser.
- Window menus show class.
- Window menus show title.
- Window menus show workspace.
- Window menus show icon.

## Taffybar Contract

Required behavior:

- Taffybar can list normal workspaces.
- Taffybar can identify the active workspace per monitor.
- Taffybar can list windows per workspace.
- Taffybar can expose class hints for each listed window.
- Taffybar can expose title for each listed window.
- Taffybar can expose active state for each listed window.
- Taffybar can expose minimized state when available.
- Taffybar can expose urgency when available.
- Taffybar can expose approximate window position when available.
- Scratchpad workspaces are marked as special or filtered out.
- Minimized workspaces are marked as special or filtered out.
- Internal workspaces are marked as special or filtered out.

Important behavior:

- Workspace labels are stable.
- Workspace icons are stable.
- Window positioning information is available enough for workspace icon strips
  and future expose-like views.
- Layout information is available enough for workspace icon strips and future
  expose-like views.
- Layout name is exposed if practical.
- Layout state is exposed if practical.

## Session and Utility Behavior

Important behavior:

- Terminal is `ghostty --gtk-single-instance=false`.
- Launcher is `rofi -show drun -show-icons`.
- Run menu is `rofi -show run`.
- Browser raise/spawn behavior exists.
- Border width is effectively zero.
- Taffybar can be toggled per monitor.
- Session startup integrates with the normal graphical-session target.
- Session startup integrates with any required session-specific user target.

Nice behavior:

- Wallpaper behavior remains consistent.
- Idle behavior remains consistent.
- Lock behavior remains consistent.
- Clipboard history behavior remains consistent.
- Screenshot behavior remains consistent.
- Monitor DDC/input switching remains consistent.
- Rofi utility bindings remain consistent.
- Media keys remain consistent.

## Binding Appendix

Required behavior:

- `Hyper` bindings should remain available from a single physical key where
  practical, even if that key emits the fallback chord internally.
- Extra modifiers on `Hyper` are limited to `Shift` for portable bindings.

Important behavior:

- `Hyper` utility bindings must not displace required directional monitor
  bindings on `Hyper+w/a/s/d`.

### Core Bindings

Required behavior:

- `Super+p` opens the application launcher.
- `Super+Shift+p` opens the run menu.
- `Super+Shift+Return` opens a terminal.
- `Super+Tab` opens the overview.
- `Super+Shift+Tab` opens the overview in bring-window mode when supported.
- `Super+g` opens the go-to-window picker.
- `Super+b` opens the bring-window picker.
- `Super+Shift+b` opens the replace-window picker.
- `Super+\` toggles to the previous workspace on the current monitor.
- `Super+Shift+e` moves the focused window to the next empty workspace and
  follows it. This is the target replacement for the older `Super+Shift+h`
  binding.
- `Hyper+e` focuses the next empty workspace.
- `Hyper+5` swaps the current workspace with a selected workspace.
- `Hyper+g` gathers windows of the focused class onto the current workspace.

### Directional Navigation Bindings

Required behavior:

- `Super+w/a/s/d` focuses windows directionally.
- `Super+Shift+w/a/s/d` swaps or moves the focused window directionally.
- `Super+Ctrl+w/a/s/d` moves the focused window to the monitor in that
  direction while preserving useful focus.
- `Hyper+w/a/s/d` focuses monitors directionally.
- `Hyper+Shift+w/a/s/d` swaps or moves windows between monitors directionally.
- Moving the focused window to an empty workspace on the monitor in a direction
  remains required behavior, but it should not require a `Hyper+Ctrl` binding.
- `Super+z` focuses the next monitor.
- `Super+Shift+z` moves the focused window to the next monitor.

### Numbered Workspace Bindings

Required behavior:

- `Super+1..9` focuses workspace `1..9` on the current monitor.
- `Super+Shift+1..9` sends the focused window to workspace `1..9` without
  following it.
- `Super+Ctrl+1..9` sends the focused window to workspace `1..9` and follows
  it.

### Scratchpad Bindings

Required behavior:

- `Super+Alt+e` toggles the element scratchpad.
- `Super+Alt+g` toggles the gmail scratchpad.
- `Super+Alt+h` toggles the htop scratchpad.
- `Super+Alt+m` toggles the messages scratchpad.
- `Super+Alt+k` toggles the slack scratchpad.
- `Super+Alt+s` toggles the spotify scratchpad.
- `Super+Alt+t` toggles the transmission scratchpad.
- `Super+Alt+v` toggles the volume scratchpad.

Important behavior:

- `Super+Alt+grave` toggles the dropdown terminal scratchpad.
- `Super+Alt+c` raises or starts the browser.
- `Super+Alt+Return` enters the minimized-window picker or restores minimized
  windows, depending on environment support.
- `Super+Alt` is reserved for app-specific raise/spawn, scratchpad, and
  scratchpad-adjacent bindings.

### Utility Bindings

Required behavior:

- `Hyper+v` opens clipboard history with a rofi-backed clipboard command
  such as `greenclip print` or `cliphist`.
- `Hyper+p` opens the password picker with `rofi-pass`.
- `Hyper+h` opens the screenshot tool with `rofi_shutter` or the
  `grim`/`slurp`/`swappy` pipeline.
- `Hyper+c` opens a shell command prompt with `shell_command.sh`.
- `Hyper+x` opens the command picker with `rofi_command.sh`.
- `Hyper+k` opens the process killer with `rofi_kill_process.sh`.
- `Hyper+Shift+k` opens the kill-all/process-tree killer with
  `rofi_kill_all.sh`.
- `Hyper+r` opens the systemd/service menu with `rofi-systemd`.
- `Hyper+slash` toggles taffybar with `toggle_taffybar`.
- `Hyper+backslash` toggles the monitor input with `mpg341cx_input toggle`.
- `Hyper+i` opens the audio input selector with `rofi_select_input.hs`.
- `Hyper+o` opens the audio output selector with `rofi_paswitch`.
- `Hyper+y` opens the agentic skill picker with `rofi_agentic_skill`.
- `Hyper+Shift+l` locks the session with the compositor/session-appropriate
  locker.

Important behavior:

- Wallpaper selection is available under `Hyper` via `rofi_wallpaper.sh`, but
  its exact key must avoid the required `Hyper+w/a/s/d` directional monitor
  bindings.
- Expose-style overview remains available as a utility binding using the
  compositor-appropriate implementation, such as `skippy-xd` on X11 or a native
  compositor/plugin overview on Wayland.
- Session-destructive operations use shifted or otherwise harder-to-hit
  variants.