config: add resize action
This commit is contained in:
Julian Orth
parent
15c157b7a6
commit
a1905ab971
14 changed files with 344 additions and 264 deletions
360
book/AGENTS.md
360
book/AGENTS.md
|
|
@ -1,299 +1,135 @@
|
|||
# Jay Book -- Agent Instructions
|
||||
|
||||
This file provides context for AI agents working on the Jay user documentation
|
||||
book (mdbook). Read this before making changes.
|
||||
User-facing [mdbook](https://rust-lang.github.io/mdBook/) documentation for
|
||||
the [Jay Wayland compositor](https://github.com/mahkoh/jay). Target audience
|
||||
is end users, not developers. Goal is feature discoverability.
|
||||
|
||||
## What is this?
|
||||
## Quick reference
|
||||
|
||||
An [mdbook](https://rust-lang.github.io/mdBook/) providing comprehensive
|
||||
user-facing documentation for the [Jay Wayland compositor](https://github.com/mahkoh/jay).
|
||||
The target audience is end users, not developers. The goal is feature
|
||||
discoverability: every capability Jay offers should be documented here in a
|
||||
way that users can find and understand.
|
||||
### Book files (`book/src/`)
|
||||
|
||||
## Current status
|
||||
The table of contents is `SUMMARY.md`. Key chapter-to-topic mapping:
|
||||
|
||||
The book is feature-complete. All 29 chapters cover every known Jay feature:
|
||||
a features overview, installation (including AUR packages), running, the
|
||||
control center, all configuration sections, tiling, workspaces, floating
|
||||
windows, mouse interactions, input modes, window/client rules, screen sharing,
|
||||
HDR & color management, the full CLI reference, and troubleshooting.
|
||||
| File | Covers |
|
||||
|------|--------|
|
||||
| `configuration/shortcuts.md` | Shortcuts, actions (simple + parameterized), marks, named actions, virtual outputs, actions in window rules |
|
||||
| `configuration/outputs.md` | Monitor config, VRR, tearing, scaling, transforms |
|
||||
| `configuration/inputs.md` | Input devices, per-device settings |
|
||||
| `configuration/misc.md` | Color management, libei, floating defaults, ui-drag |
|
||||
| `window-rules.md` | Window/client rules, privileges, capabilities |
|
||||
| `control-center.md` | All 11 control center panes |
|
||||
| `cli.md` | All CLI subcommands, JSON output |
|
||||
| `input-modes.md` | Modal keybinding system (push/pop/latch/clear) |
|
||||
| `floating.md` | Floating windows, window management mode |
|
||||
| `hdr.md` | HDR & color management walkthrough |
|
||||
|
||||
Three rounds of source-code verification have been completed and all
|
||||
identified issues have been fixed. The book should be accurate against the
|
||||
codebase as of the latest review.
|
||||
### Source-of-truth files (from repo root)
|
||||
|
||||
A subsequent style and formatting pass has been completed:
|
||||
|
||||
- Converted ~45 two-column tables to mdbook definition lists across 16 files.
|
||||
- Lowercased all keyboard shortcut modifiers to match TOML parser expectations.
|
||||
- Reformatted long inline TOML tables into multiline format with trailing
|
||||
commas and 4-space indentation.
|
||||
- Created a dedicated Features chapter (`features.md`) consolidating content
|
||||
from the old `docs/features.md` and the introduction; removed the duplicated
|
||||
feature list from `introduction.md`.
|
||||
- Added a comprehensive "Granting Privileges" section to `window-rules.md` and
|
||||
privilege troubleshooting to `troubleshooting.md`.
|
||||
- Clarified `jay unlock` usage in `configuration/idle.md` and `cli.md`.
|
||||
- Added AUR package (`jay`, `jay-git`) mentions to `installation.md`.
|
||||
- Added a dedicated HDR & Color Management chapter (`hdr.md`) with
|
||||
end-to-end walkthrough, cross-referenced from `features.md`, `outputs.md`,
|
||||
and `misc.md`.
|
||||
- Integrated remaining information from `docs/` and `README.md` that was
|
||||
missing from the book: `JAY_NO_REALTIME` env var and `config.so`/SCHED_RR
|
||||
interaction in `installation.md`, rule loop client-kill consequences and
|
||||
Xwayland override-redirect auto-focus exception in `window-rules.md`,
|
||||
license (GPLv3) and community Discord link in `introduction.md`, ArchWiki
|
||||
XKB link in `keymaps.md`.
|
||||
|
||||
A third review pass fixed:
|
||||
|
||||
- `window-rules.md`: exec action example used a plain string with spaces
|
||||
(`exec = "notify-send 'Firefox connected'"`) which would be treated as a
|
||||
single program name; changed to array form
|
||||
(`exec = ["notify-send", "Firefox connected"]`).
|
||||
- `window-rules.md`: default capabilities paragraph incorrectly said rule
|
||||
capabilities are "added on top" of defaults; corrected to say they
|
||||
**replace** defaults entirely.
|
||||
- `troubleshooting.md`: said Jay "requires at least one working renderer to
|
||||
start"; corrected to say that without one, no GPU can be initialized and
|
||||
nothing will be displayed (Jay itself still starts).
|
||||
- `outputs.md`: VRR variant3 description said "describes its content as"
|
||||
instead of the correct protocol term "describes its content type as".
|
||||
|
||||
A fourth update documented the new `--json` and `--all-json-fields` global
|
||||
CLI flags, which enable machine-readable JSONL output from all query/status
|
||||
subcommands. A new "JSON Output" section was added to `cli.md` listing all
|
||||
supported commands, the JSONL format, field omission behavior, and `jq`
|
||||
usage examples.
|
||||
|
||||
**Future work might include:**
|
||||
|
||||
- Keeping the book in sync as Jay adds new features or changes behavior.
|
||||
- Adding screenshots or diagrams (especially for the control center and tiling).
|
||||
- Reviewing after spec.yaml changes (the spec is the canonical source for
|
||||
config options).
|
||||
|
||||
## Directory layout
|
||||
|
||||
```
|
||||
book/
|
||||
AGENTS.md -- this file
|
||||
book.toml -- mdbook configuration
|
||||
src/
|
||||
SUMMARY.md -- table of contents (defines chapter ordering)
|
||||
introduction.md
|
||||
features.md -- feature overview, protocol table, CLI help output
|
||||
installation.md -- deps, AUR, crates.io, git builds, CAP_SYS_NICE
|
||||
running.md -- includes control center intro and default keybindings
|
||||
control-center.md -- detailed tour of all 11 panes
|
||||
configuration/
|
||||
index.md -- config overview, jay config init, file semantics, auto-reload
|
||||
keymaps.md
|
||||
shortcuts.md
|
||||
outputs.md
|
||||
inputs.md
|
||||
gpu.md
|
||||
idle.md
|
||||
theme.md
|
||||
environment.md
|
||||
status-bar.md
|
||||
startup.md
|
||||
xwayland.md
|
||||
misc.md -- color management, libei, floating, ui-drag, etc.
|
||||
tiling.md
|
||||
workspaces.md
|
||||
floating.md
|
||||
mouse.md
|
||||
input-modes.md
|
||||
window-rules.md -- includes "Granting Privileges" section
|
||||
cli.md
|
||||
screen-sharing.md
|
||||
hdr.md -- HDR & color management walkthrough
|
||||
troubleshooting.md -- includes privilege troubleshooting
|
||||
```
|
||||
|
||||
## Source of truth
|
||||
|
||||
The authoritative source for what Jay supports is the source code itself. Key
|
||||
reference files:
|
||||
|
||||
- `toml-spec/spec/spec.yaml` -- Full TOML config specification. Every config
|
||||
key, action, match criterion, and type is defined here. The auto-generated
|
||||
`toml-spec/spec/spec.generated.md` is derived from this file.
|
||||
- `toml-config/src/default-config.toml` -- The built-in default configuration.
|
||||
Contains default keybindings, startup actions (mako, wl-tray-bridge), etc.
|
||||
- `src/cli/*.rs` -- CLI subcommands and their arguments (clap definitions).
|
||||
Jay has 24 CLI subcommands with nesting up to 4 levels deep.
|
||||
- `src/control_center/*.rs` -- Control center pane implementations. Each pane
|
||||
has its own file (cc_outputs.rs, cc_gpus.rs, cc_input.rs, cc_clients.rs,
|
||||
cc_window.rs, cc_idle.rs, cc_compositor.rs, cc_look_and_feel.rs,
|
||||
cc_xwayland.rs, cc_color_management.rs, cc_virtual_outputs.rs). When
|
||||
documenting control center fields, always verify against these source files
|
||||
for correct ordering, labels, and conditional visibility.
|
||||
- `toml-config/src/config/parsers/color.rs` -- Color parser. Accepts 3, 4, 6,
|
||||
or 8 hex digits (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`). Note: spec.yaml
|
||||
says `#rrggbba` (7 digits) which is a typo -- the actual format is 8 digits.
|
||||
- `toml-config/src/config/parsers/exec.rs` -- Exec parser. Accepts string,
|
||||
array, or table. Understanding these three forms is important for writing
|
||||
correct TOML examples.
|
||||
- `src/config/handler.rs` -- Contains `update_capabilities`, which shows that
|
||||
client rule capabilities **replace** defaults (accumulator starts from zero).
|
||||
- The `docs/` directory has been removed. All of its content has been
|
||||
integrated into the book. The README now points to the hosted book at
|
||||
`https://mahkoh.github.io/jay/book`.
|
||||
| File | What it tells you |
|
||||
|------|-------------------|
|
||||
| `toml-spec/spec/spec.yaml` | **Canonical** TOML config spec: every key, action, match criterion, type |
|
||||
| `toml-config/src/default-config.toml` | Built-in default config (keybindings, startup actions) |
|
||||
| `toml-config/src/config/parsers/action.rs` | Action parser — see which `type` strings are accepted |
|
||||
| `toml-config/src/lib.rs` | Action dispatch — `window_or_seat!` macro shows which actions work in window rules |
|
||||
| `src/config/handler.rs` | Config handler; `update_capabilities` shows capability replacement semantics |
|
||||
| `src/cli/*.rs` | CLI subcommands (clap definitions) |
|
||||
| `src/control_center/cc_*.rs` | Control center pane implementations (verify field names/ordering here) |
|
||||
| `toml-config/src/config/parsers/exec.rs` | Exec parser (string, array, or table forms) |
|
||||
|
||||
### Known spec.yaml bugs
|
||||
|
||||
- `px-per-wheel-scroll` is listed as `kind: boolean` but the parser
|
||||
(`toml-config/src/config/parsers/input.rs`) uses `fltorint` (a number).
|
||||
The documentation correctly describes it as a numeric value.
|
||||
- `px-per-wheel-scroll`: listed as `kind: boolean` but parser uses `fltorint`
|
||||
(a number). Book correctly documents it as numeric.
|
||||
|
||||
## Critical facts to get right
|
||||
## Critical facts
|
||||
|
||||
1. **Config replacement semantics.** Once `~/.config/jay/config.toml` exists,
|
||||
the entire built-in default configuration is replaced -- not merged. Even an
|
||||
empty config file means no shortcuts, no startup actions, nothing. Users must
|
||||
run `jay config init` to get a config pre-populated with the defaults.
|
||||
1. **Config replacement.** `~/.config/jay/config.toml` replaces the entire
|
||||
built-in default — not merged. Empty file = no shortcuts, nothing.
|
||||
Users must run `jay config init`.
|
||||
|
||||
2. **Config reload.** By default, Jay does not automatically reload
|
||||
config.toml. Reload must be triggered manually via the `alt-shift-r`
|
||||
shortcut (default) or the `reload-config-toml` action. However, setting
|
||||
`auto-reload = true` in config.toml enables inotify-based file watching
|
||||
with a 400 ms debounce (parsed in
|
||||
`toml-config/src/config/parsers/config.rs:209`, acted on in
|
||||
`toml-config/src/lib.rs:1348-1358`).
|
||||
2. **Config reload.** Manual by default (`alt-shift-r` / `reload-config-toml`).
|
||||
`auto-reload = true` enables inotify watching with 400 ms debounce.
|
||||
|
||||
3. **Renderer requirement.** Jay requires at least one working renderer
|
||||
(OpenGL via libEGL+libGLESv2, or Vulkan via libvulkan + a GPU driver).
|
||||
Without one, no GPU can be initialized and nothing will be displayed. (Jay
|
||||
itself still starts -- the metal backend initializes logind, udev, and
|
||||
libinput successfully -- but no DRM devices can be set up, so the user sees
|
||||
a black screen.) These libraries are loaded at runtime, not linked at build
|
||||
time. Vulkan is the recommended renderer; OpenGL is legacy and receives no
|
||||
new features.
|
||||
3. **Actions are composable.** Anywhere an action is accepted, an array works.
|
||||
Named actions (`$name`) add reuse.
|
||||
|
||||
4. **Actions are composable.** Anywhere an action is accepted, an array of
|
||||
actions can be used instead. Named actions (`$name`) add another layer of
|
||||
reuse.
|
||||
4. **Exec action gotcha.** Plain string = program name only (no arg splitting).
|
||||
`exec = "notify-send 'hello'"` is wrong — use array form.
|
||||
|
||||
5. **Match systems.** Outputs, connectors, DRM devices, inputs, clients, and
|
||||
windows each have their own match system. All support the same logical
|
||||
combinators: AND (multiple fields in one table), OR (array of matchers),
|
||||
`not`, `all`, `any`, `exactly`.
|
||||
5. **Capability replacement.** When any client rule matches, its capabilities
|
||||
**replace** defaults entirely (not additive). Verify against
|
||||
`handler.rs:update_capabilities`.
|
||||
|
||||
6. **Input modes.** Jay supports an input mode stack (`push-mode`,
|
||||
`latch-mode`, `pop-mode`, `clear-modes`). Each mode can define its own
|
||||
shortcuts and inherit from a parent mode. This is how vim-style modal
|
||||
keybindings are implemented. Note: there are NO `resize-left/right/up/down`
|
||||
actions -- resizing is mouse-only. Use `move-*` actions in examples.
|
||||
6. **Window rule actions.** Actions using `window_or_seat!` in `lib.rs` work
|
||||
in both shortcuts (focused window) and window rules (matched window).
|
||||
The list in shortcuts.md "Actions in window rules" must stay in sync.
|
||||
|
||||
7. **Window/client rules are reactive.** Rules are re-evaluated whenever the
|
||||
matching criteria change (e.g. a window's title changes). The `latch` action
|
||||
fires when a previously-matching rule stops matching.
|
||||
7. **Window/client rules are reactive.** Re-evaluated when criteria change.
|
||||
`latch` fires when a rule stops matching.
|
||||
|
||||
8. **Control center.** Opened with `alt-c` (default) or `jay control-center`.
|
||||
It is an egui-based GUI with 11 panes: Clients, Color Management,
|
||||
Compositor, GPUs, Idle, Input, Look and Feel, Outputs (with visual
|
||||
arrangement editor), Virtual Outputs, Window Search, and Xwayland.
|
||||
8. **VRR vs tearing subtlety.** VRR variant1/2 use "fullscreen"; tearing
|
||||
variant3 says "a single application is displayed" (not necessarily
|
||||
fullscreen). Always check spec.yaml wording.
|
||||
|
||||
9. **VRR and tearing.** Both have per-output overrides and multiple mode
|
||||
variants (never, always, variant1/2/3). Important distinction: VRR
|
||||
variant1/2 use "fullscreen" as the criterion. Tearing variant3 says "a
|
||||
single application is displayed" (not necessarily fullscreen) -- check the
|
||||
spec.yaml wording carefully.
|
||||
## Style rules
|
||||
|
||||
10. **Input device type flags.** The full list is: `is-keyboard`, `is-pointer`,
|
||||
`is-touch`, `is-tablet-tool`, `is-tablet-pad`, `is-gesture`, `is-switch`.
|
||||
Note that `is-switch` exists in the parser but is missing from spec.yaml.
|
||||
- **Audience:** users, not developers. Explain what, not how.
|
||||
- **Code fences:** ` ```shell ` for commands (prefix `~$`), ` ```toml ` for config.
|
||||
- **Admonitions:** `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!IMPORTANT]`.
|
||||
- **Key combos:** backticks, lowercase modifiers: `alt-shift-c`, `ctrl-alt-F2`,
|
||||
`alt-Return`. Never `Alt+C`.
|
||||
- **Definition lists** for two-column term/description. Tables only for 3+ data columns.
|
||||
- **TOML formatting:** multiline with trailing commas, 4-space indent.
|
||||
- **Examples:** practical, not abstract. Link to
|
||||
[spec.generated.md](https://github.com/mahkoh/jay/blob/master/toml-spec/spec/spec.generated.md)
|
||||
for exhaustive listings.
|
||||
- **Control center docs:** verify field names, ordering, and conditional
|
||||
visibility against `cc_*.rs` source files. Labels must match exactly.
|
||||
|
||||
11. **Features chapter is the single source for the feature list.** The
|
||||
introduction links to `features.md` but does not duplicate any feature
|
||||
bullets. All feature descriptions, the protocol support table, and CLI help
|
||||
output live in `features.md` only.
|
||||
## Common tasks
|
||||
|
||||
12. **Privilege separation.** Jay supports granting elevated Wayland protocol
|
||||
access via three methods: `privileged = true` in window rules with
|
||||
`jay run-privileged`, connection tags with client rules, and client match
|
||||
rules by PID/sandboxing. This is documented in the "Granting Privileges"
|
||||
section of `window-rules.md`. **Important:** when any client rule matches,
|
||||
its capabilities **replace** the defaults entirely (they are not added on
|
||||
top). Multiple matching rules are unioned together, but the defaults
|
||||
(`layer-shell | drm-lease` for unsandboxed, `drm-lease` for sandboxed)
|
||||
are only used when no rule matches at all.
|
||||
### Documenting a new action
|
||||
|
||||
13. **Exec action formats.** The `exec` field in exec actions accepts three
|
||||
forms: a plain string (program name only, no arguments), an array of
|
||||
strings (first element is the program, rest are arguments), or a table
|
||||
with `prog`/`shell`, `args`, `env`, `privileged`, and `tag` fields. A
|
||||
common mistake is using a plain string with spaces like
|
||||
`exec = "notify-send 'hello'"` -- this treats the entire string as the
|
||||
program name. Use the array form instead:
|
||||
`exec = ["notify-send", "hello"]`.
|
||||
1. Read `git diff` for the commit introducing the action. Key files:
|
||||
- `toml-spec/spec/spec.yaml` — spec entry (description, fields, examples)
|
||||
- `toml-config/src/config/parsers/action.rs` — parser (field names, types, defaults)
|
||||
- `toml-config/src/lib.rs` — dispatch (check if `window_or_seat!` is used)
|
||||
- `jay-config/src/input.rs` and/or `jay-config/src/window.rs` — Rust API
|
||||
|
||||
## Style guidelines
|
||||
2. Edit `book/src/configuration/shortcuts.md`:
|
||||
- **Simple actions** (no fields): add to the appropriate list in the
|
||||
"Simple actions" section.
|
||||
- **Parameterized actions** (has fields): add a new `###` subsection before
|
||||
"Other parameterized actions". Include definition list for fields and
|
||||
practical TOML examples.
|
||||
- **Also parameterized but minor:** just add a `- name -- description`
|
||||
bullet to the "Other parameterized actions" list.
|
||||
|
||||
- Write for users, not developers. Explain what things do, not how they are
|
||||
implemented.
|
||||
- Use ` ```shell ` for shell commands, prefixed with `~$` and `sudo` where
|
||||
appropriate.
|
||||
- Use ` ```toml ` for TOML configuration examples.
|
||||
- Use **mdbook admonitions** (`> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`,
|
||||
`> [!IMPORTANT]`) instead of `> **Note:**` blockquote patterns. mdbook
|
||||
0.5.2+ is installed and supports this syntax.
|
||||
- **Keyboard shortcuts** must be enclosed in backticks and use **lowercase
|
||||
modifiers** -- this matches the format the TOML parser expects. Keysym names
|
||||
retain their original case. Examples: `alt-shift-c`, `ctrl-alt-F2`,
|
||||
`alt-Return`. Never write `Alt-Shift-c` or `Alt+C`.
|
||||
- **Tables vs definition lists.** Use mdbook definition lists (`Term\n:
|
||||
Description`) for two-column term-to-description mappings. Keep true
|
||||
grid-like tables only when they have 3+ meaningful data columns (e.g.,
|
||||
package names per distro, the protocol support table with version numbers).
|
||||
- **TOML formatting.** Break long inline TOML tables over multiple lines with
|
||||
trailing commas (TOML 1.1 syntax). Use 4-space indentation inside TOML code
|
||||
blocks, never 2-space.
|
||||
- Keep examples practical -- show real use cases, not abstract syntax.
|
||||
- Link to the auto-generated spec (`spec.generated.md`) for exhaustive field
|
||||
listings. The book should teach concepts and workflows; the spec is the
|
||||
complete reference.
|
||||
- Each chapter should be self-contained enough to be useful on its own, but
|
||||
cross-reference related chapters where helpful.
|
||||
- Avoid duplicating large tables of every possible value. Summarize, give
|
||||
examples, and link to the spec for the full list.
|
||||
- When documenting the control center, always verify field names, ordering,
|
||||
and conditional visibility against the `src/control_center/cc_*.rs` source
|
||||
files. UI labels must match exactly (case-sensitive).
|
||||
3. If `window_or_seat!` is used in `lib.rs`, add the action name to the
|
||||
"Actions in window rules" list at the bottom of `shortcuts.md`.
|
||||
|
||||
## Verification methodology
|
||||
### Documenting a new config field
|
||||
|
||||
When making changes, verify against source code. The most error-prone areas
|
||||
are:
|
||||
1. Read `toml-spec/spec/spec.yaml` for the field definition.
|
||||
2. Identify which book chapter covers that config section (see table above).
|
||||
3. Add the field with a definition-list entry or example, matching the
|
||||
existing style of that chapter.
|
||||
|
||||
1. **Control center pane documentation** -- Field names, ordering, and
|
||||
conditional visibility must match the `show_*` functions in the cc_*.rs
|
||||
files. Fields are often conditional (only shown for certain device types or
|
||||
when certain values are set).
|
||||
### Documenting a new CLI subcommand
|
||||
|
||||
2. **VRR/tearing mode descriptions** -- The exact semantics differ subtly
|
||||
between modes and between VRR vs tearing. Always check spec.yaml wording.
|
||||
1. Read `src/cli/*.rs` for clap definitions.
|
||||
2. Edit `book/src/cli.md`. Follow the existing pattern for subcommand docs.
|
||||
3. If the subcommand has `--json` support, mention it in the "JSON Output" section.
|
||||
|
||||
3. **Exec action examples** -- A plain string is the program name only (no
|
||||
argument splitting). Use arrays or tables when arguments are needed.
|
||||
### Documenting a control center change
|
||||
|
||||
4. **Capability/privilege semantics** -- Capabilities from matching rules
|
||||
replace defaults; they do not add to them. Verify against
|
||||
`src/config/handler.rs:update_capabilities` if in doubt.
|
||||
1. Read the relevant `src/control_center/cc_*.rs` file.
|
||||
2. Edit `book/src/control-center.md`. Match field names, ordering, and
|
||||
conditional visibility exactly.
|
||||
|
||||
## Building the book
|
||||
## Building
|
||||
|
||||
```shell
|
||||
~$ cd book
|
||||
~$ mdbook build # outputs to book/book/
|
||||
~$ mdbook serve # local preview at http://localhost:3000
|
||||
```
|
||||
|
||||
Requires [mdbook](https://github.com/rust-lang/mdBook) to be installed:
|
||||
|
||||
```shell
|
||||
~$ cargo install mdbook
|
||||
~$ cd book && mdbook build # outputs to book/book/
|
||||
~$ cd book && mdbook serve # preview at http://localhost:3000
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue