diff --git a/README.md b/README.md new file mode 100644 index 0000000..dcd3456 --- /dev/null +++ b/README.md @@ -0,0 +1,311 @@ +# Skygqts + +A small collection of desktop tools built with [Quickshell](https://quickshell.org/), +for Wayland compositors that speak [niri](https://github.com/YaLTeR/niri) or +[Hyprland](https://hyprland.org/). + +It ships two apps: + +- **app-carousel** — a full-screen launcher carousel. Apps sit in a row; the + one in the middle is selected. Configure it with a JSON file. +- **workspace-manager** — a workspace overview. A carousel of workspace cards + (with a live list of their windows), a bar for renaming the current + workspace, and a 3D "window loop" for picking a window. + +Everything here is QML. Talking to the compositor goes through its command +line tools (`niri msg`, `hyprctl`), so the code is the same on both. + +--- + +## Install + +### With Nix (recommended) + +The repository is a flake that exposes a package and an overlay. Replace +`` below with wherever you host it (a Git URL, or `.` when you +are inside a checkout). + +```sh +# From a checkout of this repo +nix build .#skygqts # build the package +nix run .#skygqts -- workspace-manager --daemon + +# From a remote flake +nix run + +# Add to a system config, inside your flake's inputs +inputs.skygqts.url = ""; + +# then, in a NixOS or Home Manager module +nixpkgs.overlays = [ inputs.skygqts.overlays.default ]; +# environment.systemPackages = [ pkgs.skygqts ]; +``` + +The package installs one binary, `skygqts`, which is the Nushell CLI +described below. + +### From source + +You need these programs on your `PATH`: + +| Program | Why | +| ------------------- | --------------------------------------------------------------------- | +| `quickshell` (`qs`) | Runs the QML | +| `nushell` (`nu`) | Runs the `skygqts` CLI | +| `curl` | Downloads remote app images when caching is on | +| `grim` | Takes window snapshots on Hyprland | +| `niri` or `hyprctl` | Provided by your compositor, used to read/move windows and workspaces | + +You can skip the Nushell CLI entirely and run the QML directly: + +```sh +# app carousel +SKYG_APP_CAROUSEL=/path/to/app-carousel.json qs -p ./app-carousel + +# workspace manager +qs -n -p ./workspace-manager +``` + +--- + +## What's available + +### CLI + +`skygqts` is a Nushell script (`skygqts.nu`). Its subcommands: + +| Command | What it does | +| ------------------------------------------- | ------------------------------------------------- | +| `skygqts carousel ` | Opens the app carousel with the given JSON config | +| `skygqts workspace-manager` | Opens the workspace carousel | +| `skygqts workspace-manager --daemon` | Same, but detached from the terminal | +| `skygqts workspace-manager --config ` | Same, with a JSON config file | +| `skygqts workspace-manager toggle` | Toggles the workspace carousel (also closes it) | +| `skygqts workspace-manager goto` | Opens the workspace carousel | +| `skygqts workspace-manager windows` | Opens the window loop for the focused workspace | +| `skygqts workspace-manager rename` | Opens the carousel with the name field focused | + +The last four talk to an already-running workspace manager over IPC, so start +it as a daemon first (for example from your compositor's startup): + +```sh +skygqts workspace-manager --daemon --config ~/.config/skygqts/workspace-manager.json +``` + +Then bind them in your compositor, e.g.: + +```conf +# Hyprland +bind = SUPER, TAB, exec, skygqts workspace-manager toggle +bind = SUPER, G, exec, skygqts workspace-manager windows +bind = SUPER, N, exec, skygqts workspace-manager rename +``` + +The same calls are available over Quickshell IPC if you prefer not to use the +CLI: + +```sh +qs ipc -p ./workspace-manager call workspace toggle +qs ipc -p ./workspace-manager call workspace goTo +qs ipc -p ./workspace-manager call workspace openWindowSelection +qs ipc -p ./workspace-manager call workspace openWorkspaceRename + +qs ipc -p ./app-carousel call launcher toggle +qs ipc -p ./app-carousel call launcher open +qs ipc -p ./app-carousel call launcher close +``` + +### Environment variables + +| Variable | Used by | Meaning | +| ----------------------------- | ----------------- | ---------------------------------------------- | +| `SKYG_APP_CAROUSEL` | app-carousel | Path to its JSON config | +| `SKYG_WORKSPACE_MANAGER` | workspace-manager | Path to its JSON config (optional) | +| `NIRI_SOCKET` | workspace-manager | Set by niri; used to detect the compositor | +| `HYPRLAND_INSTANCE_SIGNATURE` | workspace-manager | Set by Hyprland; used to detect the compositor | +| `XDG_RUNTIME_DIR` | workspace-manager | Where window snapshots are written | + +--- + +## App carousel + +```sh +skygqts carousel ~/.config/skygqts/app-carousel.json +``` + +A full-screen overlay with one card per app. Move left and right, press Enter +to launch the selected one. + +### Config + +See `example.json`. Top level: + +| Field | Type | Default | Meaning | +| ------------------- | ----- | ------- | ------------------------------------------------------------ | +| `apps` | array | — | The apps. Required. | +| `enableCacheFolder` | bool | `false` | Cache remote images on disk | +| `backgroundMode` | bool | `false` | Keep the carousel on the background layer (see below) | +| `autoStart` | bool | — | Accepted by the parser but has no effect in the current code | + +Each entry in `apps`: + +| Field | Type | Default | Meaning | +| ------------------ | ----------------- | ------------ | ------------------------------------------------------- | +| `name` | string | — | Label under the icon. Required. | +| `image` | string | — | Icon name or image path/URL. Required. | +| `isIcon` | bool | `false` | Treat `image` as a theme icon name instead of a picture | +| `dims` | `[width, height]` | `[100, 100]` | Icon size. Only allowed when `isIcon` is `true` | +| `exec` | string[] | — | Command and arguments to run | +| `hyprlandDispatch` | string | — | Hyprland dispatch to run instead of `exec` | + +Specify **exactly one** of `exec` or `hyprlandDispatch`. + +`image` resolution: + +- `isIcon: true` looks the name up in the icon theme (e.g. `"chromium"`, + `"system-settings"`). +- Otherwise it accepts an `http(s)://` or `file://` URL, a `~/…` path, or a + path relative to the config file's own directory. + +Example: + +```json +{ + "enableCacheFolder": true, + "apps": [ + { + "name": "Chromium", + "image": "chromium", + "isIcon": true, + "exec": ["chromium"] + }, + { + "name": "Netflix", + "image": "https://assets.nflxext.com/us/ffe/siteui/common/icons/nficon2023.ico", + "hyprlandDispatch": "exec chromium --app=https://www.netflix.com" + } + ] +} +``` + +When `enableCacheFolder` is `true`, remote images are downloaded with `curl` +into `~/.config/skygqts/carousel-image-cache` and reused from there. + +### Background mode + +With `"backgroundMode": true` the carousel lives on the _bottom_ layer and is +always visible — it behaves like a wallpaper you can launch from. The +`toggle`/`open` IPC calls then dispatch `workspace empty` on Hyprland instead +of showing a window, and Escape/clicking no longer closes it. + +### Keys + +| Key | Action | +| ------------ | --------------------------------- | +| Left / Right | Move the selection | +| Enter | Launch the selected app | +| Escape | Close (unless in background mode) | +| Scroll | Move the selection horizontally | + +--- + +## Workspace manager + +```sh +skygqts workspace-manager --config ~/.config/skygqts/workspace-manager.json +``` + +It detects your compositor from the environment (`niri` or `hyprland`) and +shows one column of workspace cards per monitor, each card listing the +workspace's windows. From there you can focus a workspace, rename it, or open +a window loop. + +### Config + +The config file is optional. Anything missing or malformed falls back to the +default below, and the file is watched for changes. See +`workspace-manager.example.json`. + +| Field | Type | Default | Meaning | +| ------------------- | ------ | ----------------------------------------- | ------------------------------- | +| `keys.rename` | string | `"Ctrl+N"` | Key that focuses the name field | +| `keys.windows` | string | `"Tab"` | Key that opens the window loop | +| `hints.show` | bool | `true` | Show the small key hints | +| `hints.rename` | string | `"{key}: to switch here"` | Hint text | +| `hints.windows` | string | `"{key}: to see windows"` | Hint text | +| `hints.exitWindows` | string | `"{key} or Esc: to exit window carousel"` | Hint text | + +In any hint, `{key}` is replaced by the matching key. Keys are written as +modifiers plus one key, joined by `+`. Recognised modifiers are `Ctrl` +(`Control`), `Alt`, `Shift`, and `Meta` (`Super`); the key may be a letter, +a digit, `F1`–`F12`, `Space`, or `Tab` (for example `Ctrl+N`, `Super+Space`). + +### Keys + +**Carousel** + +| Key | Action | +| ------------------------------ | -------------------------------------------- | +| Up / Down | Previous / next workspace on this monitor | +| Left / Right | Previous / next monitor | +| Enter | Focus the selected workspace | +| Escape | Close without switching | +| `keys.rename` (default Ctrl+N) | Focus the name field | +| `keys.windows` (default Tab) | Open the window loop | +| Scroll | Vertical = workspaces, horizontal = monitors | + +**Renaming** + +| Key | Action | +| ------ | ---------------------- | +| Enter | Apply the new name | +| Escape | Leave without renaming | + +**Window loop** + +| Key | Action | +| ---------------------------- | ------------------------------------------------------------------- | +| Left / Right | Previous / next window | +| Enter | Focus the selected window | +| Up / Down | Previous / next workspace and show its windows | +| Escape | Fold back to the carousel (closes entirely if opened via `windows`) | +| `keys.windows` (default Tab) | Fold back to the carousel | + +`Tab` and `Shift+Tab` also step windows, unless `keys.windows` is `Tab` (the +default), in which case `Tab` folds the loop back instead. + +### Previews + +The window loop can show window previews: + +- On **Hyprland**, live previews are used. +- **Snapshots** are also taken: with `grim` on Hyprland, and with niri's own + `screenshot-window` on niri. Snapshot files go to `$XDG_RUNTIME_DIR` + (or `/tmp` if that is not set). + +These are toggled by the `livePreviews`, `snapshotPreviewsHyprland`, and +`snapshotPreviewsNiri` properties in `workspace-manager/Theme.qml`. + +--- + +## Theming + +Colors, sizes, and animation timings live in one place per app: + +- `app-carousel/Theme.qml` +- `workspace-manager/Theme.qml` + +Edit those files to restyle the carousel, glass effect, hints, and window +loop. + +## Repository layout + +``` +app-carousel/ # launcher: shell.qml, config, theme, cards +workspace-manager/ # overview: carousel, rename bar, window loop, compositor bridge +skygqts.nu # the `skygqts` CLI (Nushell) +package.nix # package definition +flake.nix # flake: package, overlay, dev shell +example.json # sample app-carousel config +workspace-manager.example.json # sample workspace-manager config +```