wip look into Keyboard/PointerTarget

Decided not to pursue this for now. The idea was to extract input handling from
input/mod.rs into the respective modules, plus get rid of manual cursor shape
resetting, but there are some roadblocks:

- The pointer is locked when those methods are called, meaning you can't get
  the current location (have to store from enter/motion) and, more crucially,
  can't set grabs—we need this for the Overview.
- Gesture begin/end is handled at the Wayland object level, meaning
  PointerTargets get to deal with "improper" events themselves, reducing their
  utility. cosmic-comp spawns an idle callback for this which seems awkward and
  is asking for problems.
- We're not actually removing much code at all, only adding more code for the
  blanket wrappers and such.

.gitattributes

@@ -0,0 +1,12 @@
+# LFS configuration for images from the wiki
+*.png filter=lfs diff=lfs merge=lfs -text
+
+# Exclude LFS-tracked files from the tarball
+/wiki/img/ export-ignore
+
+# exclude .gitattributes itself from the tarball
+.gitattributes export-ignore
+
+# tip: can be tested using
+# git archive --format=tar.gz --output=source.tar.gz HEAD && \
+# tar tfvz source.tar.gz | grep -e '.png' -e '.gitattributes'

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Report a bug or a crash
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+<!-- Please describe the issue here at the top, then fill in the system information below. -->
+
+<!-- Attaching your full niri config can help diagnose the problem. -->
+
+<!--
+If you have a problem with a specific app, please verify that it is running on Wayland, rather than X11. An easy way is to run xeyes and mouse over the app: xeyes will be able to "see" only X11 windows.
+
+You can also check what process the window PID belongs to:
+
+$ readlink /proc/$(niri msg --json pick-window | jq .pid)/exe
+
+If this points to xwayland-satellite, then it's an X11 window.
+
+Please report issues with X11 apps to xwayland-satellite instead of niri: https://github.com/Supreeeme/xwayland-satellite/issues
+-->
+
+### System Information
+
+<!-- Paste the output of `niri -V`, e.g. niri 25.02 (b94a5db) -->
+* niri version: 
+
+<!-- Write your distribution, e.g. Fedora 40 Silverblue -->
+* Distro: 
+
+<!-- Write your GPU vendor and model, e.g. AMD RX 6700M -->
+* GPU: 
+
+<!-- Write your CPU vendor and model, e.g. AMD Ryzen 7 6800H -->
+* CPU:

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,10 @@
+contact_links:
+  - name: Feature request
+    url: https://github.com/YaLTeR/niri/discussions/new?category=ideas
+    about: Ideas for new features and functionality (start a Discussion)
+  - name: Ask a question
+    url: https://github.com/YaLTeR/niri/discussions/new?category=q-a
+    about: Question about niri (start a Discussion)
+  - name: Matrix room
+    url: https://matrix.to/#/#niri:matrix.org
+    about: Chat about niri with other users

.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      smithay:
+        patterns:
+          - "smithay"
+          - "smithay-drm-extras"
+      rust-dependencies:
+        update-types:
+          - "minor"
+          - "patch"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    ignore:
+      - dependency-name: "Andrew-Chen-Wang/github-wiki-action"

.github/workflows/ci.yml

@@ -8,22 +8,18 @@ on:
     - cron: '0 0 1 * *' # Monthly
 
 env:
-  RUN_SLOW_TESTS: 1
+  DEPS_APT: curl gcc clang libudev-dev libgbm-dev libxkbcommon-dev libegl1-mesa-dev libwayland-dev libinput-dev libdbus-1-dev libsystemd-dev libseat-dev libpipewire-0.3-dev libpango1.0-dev libdisplay-info-dev
+  DEPS_DNF: cargo gcc clang libudev-devel libgbm-devel libxkbcommon-devel wayland-devel libinput-devel dbus-devel systemd-devel libseat-devel pipewire-devel pango-devel cairo-gobject-devel libdisplay-info-devel
+  DEPS_APK: cargo clang-libclang eudev-dev glib-dev libdisplay-info-dev libinput-dev libseat-dev libxkbcommon-dev mesa-dev pango-dev pipewire-dev tar
+  DEPS_PKG: git curl rust llvm pkgconf pixman libudev-devd libdisplay-info seatd libinput libxkbcommon pipewire mesa-libs cairo devel/glib20 gettext-runtime harfbuzz pango
 
 jobs:
-  build:
+  test:
     strategy:
       fail-fast: false
 
-      matrix:
-        configuration: [debug, release]
-
-        include:
-          - configuration: release
-            release-flag: '--release'
-
-    name: test - ${{ matrix.configuration }}
-    runs-on: ubuntu-22.04
+    name: test
+    runs-on: ubuntu-24.04
 
     steps:
       - uses: actions/checkout@v4
@@ -32,41 +28,171 @@ jobs:
 
       - name: Install dependencies
         run: |
-          sudo apt-get install -y software-properties-common
-          sudo add-apt-repository -y ppa:pipewire-debian/pipewire-upstream
           sudo apt-get update -y
-          sudo apt-get install -y libudev-dev libgbm-dev libxkbcommon-dev libegl1-mesa-dev libwayland-dev libinput-dev libdbus-1-dev libsystemd-dev libseat-dev libpipewire-0.3-dev
+          sudo apt-get install -y ${{ env.DEPS_APT }}
 
-      - name: Install Rust
-        run: |
-          rustup set auto-self-update check-only
-          rustup toolchain install stable --profile minimal
+      - uses: dtolnay/rust-toolchain@stable
 
       - uses: Swatinem/rust-cache@v2
-        with:
-          key: ${{ matrix.configuration }}
 
-      - name: Build (no default features)
-        run: cargo build ${{ matrix.release-flag }} --no-default-features
-
-      - name: Build
-        run: cargo build ${{ matrix.release-flag }}
-
-      - name: Build (with profiling)
-        run: cargo build ${{ matrix.release-flag }} --features profile-with-tracy
-
-      - name: Build Tests
-        run: cargo test --no-run --all ${{ matrix.release-flag }}
+      - name: Build tests
+        run: cargo test --no-run --all --exclude niri-visual-tests
 
       - name: Test
-        run: cargo test --all ${{ matrix.release-flag }} -- --nocapture
+        run: cargo test --all --exclude niri-visual-tests -- --nocapture
+
+  build:
+    strategy:
+      fail-fast: false
+
+    name: check feature combinations
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          show-progress: false
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y ${{ env.DEPS_APT }}
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Check (no default features)
+        run: cargo check --no-default-features
+
+      - name: Check (just dbus)
+        run: cargo check --no-default-features --features dbus
+
+      - name: Check (just systemd)
+        run: cargo check --no-default-features --features systemd
+
+      - name: Check (just dinit)
+        run: cargo check --no-default-features --features dinit
+
+      - name: Check (just xdp-gnome-screencast)
+        run: cargo check --no-default-features --features xdp-gnome-screencast
+
+      - name: Check
+        run: cargo check
+
+      - name: Build (with profiling)
+        run: cargo build --features profile-with-tracy
+
+  build-musl:
+    strategy:
+      fail-fast: false
+
+    name: alpine musl
+    runs-on: ubuntu-24.04
+    container: alpine:3
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          show-progress: false
+
+      - name: Install Deps
+        run: apk add --no-cache ${{ env.DEPS_APK }}
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Build
+        run: cargo build --no-default-features --features dbus,xdp-gnome-screencast
+
+  # Job that runs randomized tests for a longer period of time.
+  # Also runs normal slow tests.
+  randomized-tests:
+    strategy:
+      fail-fast: false
+
+    name: randomized and slow tests
+    runs-on: ubuntu-24.04
+
+    env:
+      RUST_BACKTRACE: 1
+      RUN_SLOW_TESTS: 1
+      PROPTEST_CASES: 200000
+      PROPTEST_MAX_LOCAL_REJECTS: 200000
+      PROPTEST_MAX_GLOBAL_REJECTS: 200000
+      PROPTEST_MAX_SHRINK_ITERS: 200000
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          show-progress: false
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y ${{ env.DEPS_APT }}
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Build tests
+        run: cargo test --no-run --all --exclude niri-visual-tests --release
+
+      - name: Test
+        run: cargo test --all --exclude niri-visual-tests --release
+
+  visual-tests:
+    strategy:
+      fail-fast: false
+
+    name: visual tests
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          show-progress: false
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y ${{ env.DEPS_APT }} libadwaita-1-dev
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Build
+        run: cargo build --package niri-visual-tests
+
+  msrv:
+    strategy:
+      fail-fast: false
+
+    name: msrv
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          show-progress: false
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y ${{ env.DEPS_APT }} libadwaita-1-dev
+
+      - uses: dtolnay/rust-toolchain@1.80.1
+
+      - uses: Swatinem/rust-cache@v2
+
+      - run: cargo check --all-targets
 
   clippy:
     strategy:
       fail-fast: false
 
     name: clippy
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
 
     steps:
       - uses: actions/checkout@v4
@@ -75,15 +201,12 @@ jobs:
 
       - name: Install dependencies
         run: |
-          sudo apt-get install -y software-properties-common
-          sudo add-apt-repository -y ppa:pipewire-debian/pipewire-upstream
           sudo apt-get update -y
-          sudo apt-get install -y libudev-dev libgbm-dev libxkbcommon-dev libegl1-mesa-dev libwayland-dev libinput-dev libdbus-1-dev libsystemd-dev libseat-dev libpipewire-0.3-dev
+          sudo apt-get install -y ${{ env.DEPS_APT }} libadwaita-1-dev
 
-      - name: Install Rust
-        run: |
-          rustup set auto-self-update check-only
-          rustup toolchain install stable --profile minimal --component clippy
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
 
       - uses: Swatinem/rust-cache@v2
 
@@ -91,19 +214,152 @@ jobs:
         run: cargo clippy --all --all-targets
 
   rustfmt:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
 
     steps:
       - uses: actions/checkout@v4
         with:
           show-progress: false
 
-      - name: Install Rust
-        run: |
-          rustup set auto-self-update check-only
-          rustup toolchain install nightly --profile minimal --component rustfmt
-          rustup override set nightly
+      - uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: rustfmt
 
       - name: Run rustfmt
         run: cargo fmt --all -- --check
 
+  fedora:
+    runs-on: ubuntu-24.04
+    container: fedora:41
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          show-progress: false
+
+      - name: Install dependencies
+        run: |
+          sudo dnf update -y
+          sudo dnf install -y ${{ env.DEPS_DNF }} libadwaita-devel
+
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo build --all
+
+  freebsd:
+    runs-on: ubuntu-24.04
+    env:
+      CARGO_HOME: /home/runner/work/niri/niri/cargo-home
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          show-progress: false
+
+      # Required for the rust-cache action to work.
+      - uses: dtolnay/rust-toolchain@stable
+
+      # FIXME: doesn't seem to cache the builds, only the downloads for some unknown reason.
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-all-crates: true
+
+      # Remove man-db triggers to speed up Ubuntu upgrade by a minute or two during vmactions/freebsd-vm action run.
+      - run: |
+          sudo rm /var/lib/dpkg/info/man-db.*
+
+      - name: Build
+        uses: vmactions/freebsd-vm@966989c456d41351f095a421f60e71342d3bce41  # v1.2.1
+        with:
+          prepare: |
+            pkg update -f
+            pkg install -y ${{ env.DEPS_PKG }}
+          run: |
+            curl -o patch-pipewire_init 'https://cgit.freebsd.org/ports/plain/x11-wm/niri/files/patch-pipewire_init?id=f3f7e555b06d9a87d63c047ce3e82e936a11f2fe'
+
+            export CARGO_HOME="$PWD/cargo-home"
+
+            cargo fetch
+
+            ( cd $CARGO_HOME/git/checkouts/pipewire-rs-*/*/; patch -p2 < $CARGO_HOME/../patch-pipewire_init; )
+
+            cargo build \
+              --offline \
+              --no-default-features --features dbus,xdp-gnome-screencast
+
+  nix:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          show-progress: false
+
+      - name: Check flake inputs
+        uses: DeterminateSystems/flake-checker-action@v4
+        continue-on-error: true
+
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@v3
+        continue-on-error: true
+
+      - run: nix flake check
+        continue-on-error: true
+
+  publish-wiki:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs:
+      - publish-docs
+    permissions:
+      contents: write
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          lfs: true
+          show-progress: false
+
+      - uses: Andrew-Chen-Wang/github-wiki-action@b7e552d7cb0fa7f83e459012ffc6840fd87bcb83
+        with:
+          path: docs/wiki/
+
+  publish-docs:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs:
+      - test
+    permissions:
+      contents: write
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          lfs: true
+          show-progress: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+            enable-cache: true
+
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+        working-directory: docs/
+
+      - name: Generate niri documentation
+        run: uv run mkdocs build
+        working-directory: docs/
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Generate rustdoc documentation
+        run: cargo doc --no-deps -p niri-ipc
+
+      - run: mkdir -p publish/niri_ipc
+      - run: cp -r ./target/doc/* ./publish/
+      - run: cp -r ./docs/site/* ./publish/
+
+      - name: Deploy documentation
+        if: github.ref == 'refs/heads/main'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./publish
+          force_orphan: true

.github/workflows/release.yml

@@ -0,0 +1,63 @@
+name: Prepare release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Public version'
+        required: true
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: true
+
+env:
+  RUN_SLOW_TESTS: 1
+
+jobs:
+  prepare-release:
+    runs-on: ubuntu-24.04
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          show-progress: false
+
+      - name: Check for unreplaced "Since:" in the wiki
+        run: |
+          if grep --recursive 'Since: next release' wiki; then
+            exit 1
+          fi
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y curl gcc clang libudev-dev libgbm-dev libxkbcommon-dev libegl1-mesa-dev libwayland-dev libinput-dev libdbus-1-dev libsystemd-dev libseat-dev libpipewire-0.3-dev libpango1.0-dev libdisplay-info-dev libadwaita-1-dev
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Create vendored dependencies archive
+        run: |
+          mkdir .cargo
+          cargo vendor --locked > .cargo/config.toml
+          tar cJf niri-${{ github.event.inputs.version }}-vendored-dependencies.tar.xz vendor/
+
+      - name: Build
+        run: cargo build --all --frozen --release
+
+      - name: Build tests
+        run: cargo test --no-run --all --frozen --release
+
+      - name: Test
+        run: cargo test --all --frozen --release -- --nocapture
+
+      - name: Draft release
+        uses: softprops/action-gh-release@v2
+        with:
+          draft: true
+          tag_name: v${{ github.event.inputs.version }}
+          files: niri-${{ github.event.inputs.version }}-vendored-dependencies.tar.xz
+          fail_on_unmatched_files: true

.gitignore

@@ -1 +1,2 @@
 /target
+/result

CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to niri
+
+Thanks for your interest in niri!
+The project has grown quite a bit, and we could use all help that we can.
+
+Make sure to join our Matrix chat if you have any questions or want to discuss anything: https://matrix.to/#/#niri:matrix.org
+
+## Issues and discussions
+
+This is a good way to help many new and existing users without programming knowledge.
+
+- Answer and help people in GitHub issues and discussions.
+- Check and point out duplicate issues.
+- Check for issues that are likely application bugs (and not niri bugs).
+    - Ask or try to reproduce on another non-Smithay-based compositor (sway, KDE/KWin, GNOME/Mutter). If the issue reproduces, it's likely an application bug.
+    - Ask or try to reproduce on another *Smithay-based* compositor ([cosmic-comp], [anvil]). If the issue reproduces only on Smithay compositors, it may be a Smithay bug.
+    - Make sure you're testing the Wayland version of the app on all compositors. Apps may silently use X11 when an X11 `$DISPLAY` is available.
+    - Problems with X11 apps should be reported to [xwayland-satellite]. When testing xwayland-satellite on different compositors, make sure you use xwayland-satellite's `$DISPLAY` (rather than another compositor's built-in Xwayland `$DISPLAY`).
+    - After testing, mention where you could and couldn't reproduce, as well as the exact steps to reproduce if the issue is missing them.
+- Try to reproduce the issue on your own system and write if you could or couldn't reproduce it.
+- Upvote issues with a thumbs up reaction as you like.
+- Ideas and feature requests from new users should go to Discussions.
+
+If your issue is a duplicate, or not a niri issue (application bug, hardware problem, configuration problem), then please close it.
+
+## Reviewing and testing pull requests
+
+With the growing popularity, the volume of pull requests is honestly more than I can manage myself in my free time.
+I would really appreciate help with testing and reviewing them.
+
+### Testing
+
+Pick a pull request you like, then build it and give it a go.
+The [Developing niri wiki page](https://yalter.github.io/niri/Development:-Developing-niri) has guidance on running niri test builds.
+
+Be really thorough with your testing.
+We're striving for polished features in niri, so point out any issues and bugs, even small ones like animation jank.
+
+- Think of weird edge cases or unexpected interactions and try them to see that they work reasonably.
+- Try to break the feature and check that it behaves well.
+- Where applicable, try different input devices: keyboard, mouse, trackpad, tablet, touchscreen.
+- Watch out for any new performance drops.
+
+For bug fixes, first make sure you can reproduce the bug, then do the same steps in the PR test build, and verify that the bug is fixed.
+Be similarly thorough: test any similar or related edge cases to verify that the fix doesn't introduce any new problems.
+
+Write your findings in the pull request: any issues you found, or if everything worked well.
+Re-test after the author updates the code to see that your issues were fixed.
+
+Don't hesitate to test even if someone else already did; very frequently different people will stumble upon different problems.
+
+### Reviewing
+
+Reviewing pull requests is something I need the most help with since there are a lot of them, and it's quite time-consuming.
+Anyone with code accepted into niri is welcome, but this is not a requirement; even if you aren't familiar with Rust you may find some logic problems.
+
+Pick a pull request, then review its code.
+
+- Check that everything looks good, check various conditions for edge cases.
+- See if there are any scenarios the author forgot to handle.
+- Check that the code fits well into the rest of niri, follows its design and code style.
+    - I understand this is vague. The idea is: look at the surrounding code and at similar modules (e.g. when implementing a new protocol, check other protocol implementations), and try to follow the style and structure.
+- Check for unrelated changes that may be better split into their own pull request.
+- Check that the wiki had been updated if necessary (for example, new config options were documented with examples, and have a correct Since annotation).
+
+Point out everything you find as review comments (don't forget to submit the review).
+Be constructive and respectful; some people may be new to programming and Rust.
+As the author addresses the comments and issues, check the code again to see that the problems were fixed.
+If everything looks good, say that, so I know someone has reviewed the PR.
+
+As with testing, don't hesitate to look through and comment even if someone else already had.
+Extra pairs of eyes catch more problems.
+
+## Writing pull requests
+
+When creating pull requests, please keep the following in mind.
+
+- Make sure new features align with niri's design directions. Ideally, there should be an existing issue or discussion where we settled on that solution.
+- Keep pull requests focused on a single feature or bug fix with no unrelated changes.
+- Try to split your changes into small, self-contained commits. Every commit should build and pass tests. This makes it much easier to review your PR, and bisect for regressions in the future.
+    - When addressing PR comments, try to squash the changes straight into the relevant commits.
+    - In some cases when the requested changes are big/unclear, you can leave them as separate commits on top, but please squash and otherwise clean up the history when the changes are finalized.
+    - To update the main branch, please rebase instead of merging. Try to force-push the main update rebase separately from other changes, this way it's easy to skip during review since it's usually not interesting.
+    - When working on bigger features, I usually start with a big messy commit, then gradually split out smaller self-contained changes from it as the code gets into shape.
+    - [git-rebase.io](https://git-rebase.io/) is a helpful guide for splitting commits and cleaning up history in git.
+- When you address a review comment, mark it as resolved.
+- Remember to [run tests](https://yalter.github.io/niri/Development:-Developing-niri#tests) and format the code with `cargo +nightly fmt --all`.
+- For new layout actions, remember to add them to the randomized tests. For weird Wayland handling, adding client-server tests in `src/tests/` could be very useful.
+- Test your changes by hand thoroughly, including for edge cases and weird interactions. See the Testing section above for some tips.
+- Remember to document new config options on the wiki.
+- When opening a pull request, ensure "Allow edits from maintainers" is enabled, so I can make final tweaks before merging.
+
+
+[cosmic-comp]: https://github.com/pop-os/cosmic-comp
+[anvil]: https://github.com/Smithay/smithay/tree/master/anvil
+[xwayland-satellite]: https://github.com/Supreeeme/xwayland-satellite

Cargo.toml

@@ -1,48 +1,101 @@
-[package]
-name = "niri"
-version = "0.1.0-alpha.1"
+[workspace]
+members = [
+    "niri-config",
+    "niri-ipc",
+    "niri-visual-tests",
+]
+
+[workspace.package]
+version = "25.5.1"
 description = "A scrollable-tiling Wayland compositor"
 authors = ["Ivan Molodetskikh <yalterz@gmail.com>"]
 license = "GPL-3.0-or-later"
 edition = "2021"
-
-readme = "README.md"
 repository = "https://github.com/YaLTeR/niri"
-keywords = ["wayland", "compositor", "tiling", "smithay", "wm"]
+rust-version = "1.80.1"
 
-[dependencies]
-anyhow = { version = "1.0.75" }
-arrayvec = "0.7.4"
-async-channel = { version = "2.1.0", optional = true }
-async-io = { version = "1.13.0", optional = true }
-bitflags = "2.4.1"
-clap = { version = "4.4.8", features = ["derive"] }
-directories = "5.0.1"
-git-version = "0.3.8"
-keyframe = { version = "1.1.1", default-features = false }
-knuffel = "3.2.0"
-libc = "0.2.150"
-logind-zbus = { version = "3.1.2", optional = true }
-log = { version = "0.4.20", features = ["max_level_trace", "release_max_level_debug"] }
-miette = "5.10.0"
-notify-rust = { version = "4.10.0", optional = true }
-pipewire = { version = "0.7.2", optional = true }
-png = "0.17.10"
-portable-atomic = { version = "1.5.1", default-features = false, features = ["float"] }
-profiling = "1.0.11"
-sd-notify = "0.4.1"
-serde = { version = "1.0.193", features = ["derive"] }
-tracing-subscriber = { version = "0.3.18", features = ["env-filter"] }
-tracing = { version = "0.1.40", features = ["max_level_trace", "release_max_level_debug"] }
-tracy-client = { version = "0.16.4", default-features = false }
-url = { version = "2.5.0", optional = true }
-xcursor = "0.3.4"
-zbus = { version = "3.14.1", optional = true }
+[workspace.dependencies]
+anyhow = "1.0.99"
+bitflags = "2.9.2"
+clap = { version = "4.5.45", features = ["derive"] }
+insta = "1.43.1"
+serde = { version = "1.0.219", features = ["derive"] }
+serde_json = "1.0.143"
+tracing = { version = "0.1.41", features = ["max_level_trace", "release_max_level_debug"] }
+tracing-subscriber = { version = "0.3.19", features = ["env-filter"] }
+tracy-client = { version = "0.18.2", default-features = false }
 
-[dependencies.smithay]
+[workspace.dependencies.smithay]
+# version = "0.4.1"
 git = "https://github.com/Smithay/smithay.git"
 # path = "../smithay"
 default-features = false
+
+[workspace.dependencies.smithay-drm-extras]
+# version = "0.1.0"
+git = "https://github.com/Smithay/smithay.git"
+# path = "../smithay/smithay-drm-extras"
+
+[package]
+name = "niri"
+version.workspace = true
+description.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+readme = "README.md"
+keywords = ["wayland", "compositor", "tiling", "smithay", "wm"]
+
+[dependencies]
+anyhow.workspace = true
+arrayvec = "0.7.6"
+async-channel = "2.5.0"
+async-io = { version = "2.5.0", optional = true }
+atomic = "0.6.1"
+bitflags.workspace = true
+bytemuck = { version = "1.23.2", features = ["derive"] }
+calloop = { version = "0.14.3", features = ["executor", "futures-io", "signals"] }
+clap = { workspace = true, features = ["string"] }
+clap_complete = "4.5.57"
+clap_complete_nushell = "4.5.8"
+directories = "6.0.0"
+drm-ffi = "0.9.0"
+fastrand = "2.3.0"
+futures-util = { version = "0.3.31", default-features = false, features = ["std", "io"] }
+git-version = "0.3.9"
+glam = "0.30.5"
+input = { version = "0.9.1", features = ["libinput_1_21"] }
+keyframe = { version = "1.1.1", default-features = false }
+libc = "0.2.175"
+libdisplay-info = "0.2.2"
+log = { version = "0.4.27", features = ["max_level_trace", "release_max_level_debug"] }
+niri-config = { version = "25.5.1", path = "niri-config" }
+niri-ipc = { version = "25.5.1", path = "niri-ipc", features = ["clap"] }
+ordered-float = "5.0.0"
+pango = { version = "0.20.12", features = ["v1_44"] }
+pangocairo = "0.20.10"
+pipewire = { git = "https://gitlab.freedesktop.org/pipewire/pipewire-rs.git", optional = true, features = ["v0_3_33"] }
+png = "0.17.16"
+portable-atomic = { version = "1.11.1", default-features = false, features = ["float"] }
+profiling = "1.0.17"
+sd-notify = "0.4.5"
+serde.workspace = true
+serde_json.workspace = true
+smithay-drm-extras.workspace = true
+tracing-subscriber.workspace = true
+tracing.workspace = true
+tracy-client.workspace = true
+url = { version = "2.5.4", optional = true }
+wayland-backend = "0.3.11"
+wayland-scanner = "0.31.7"
+xcursor = "0.3.10"
+zbus = { version = "5.9.0", optional = true }
+
+[dependencies.smithay]
+workspace = true
 features = [
     "backend_drm",
     "backend_egl",
@@ -52,36 +105,55 @@ features = [
     "backend_udev",
     "backend_winit",
     "desktop",
-    "libinput_1_19",
     "renderer_gl",
+    "renderer_pixman",
     "renderer_multi",
     "use_system_lib",
     "wayland_frontend",
 ]
 
-[dependencies.smithay-drm-extras]
-git = "https://github.com/Smithay/smithay.git"
-# path = "../smithay/smithay-drm-extras"
-
 [dev-dependencies]
-proptest = "1.4.0"
-proptest-derive = "0.4.0"
+approx = "0.5.1"
+calloop-wayland-source = "0.4.0"
+insta.workspace = true
+proptest = "1.7.0"
+proptest-derive = { version = "0.6.0", features = ["boxed_union"] }
+rayon = "1.11.0"
+wayland-client = "0.31.11"
+xshell = "0.2.7"
 
 [features]
-default = ["dbus", "xdp-gnome-screencast"]
-# Enables DBus support (required for xdp-gnome and power button inhibiting).
-dbus = ["zbus", "logind-zbus", "async-channel", "async-io", "notify-rust", "url"]
+default = ["dbus", "systemd", "xdp-gnome-screencast"]
+# Enables D-Bus support (serve various freedesktop and GNOME interfaces, power button handling).
+dbus = ["dep:zbus", "dep:async-io", "dep:url"]
+# Enables systemd integration (global environment, apps in transient scopes).
+systemd = ["dbus"]
 # Enables screencasting support through xdg-desktop-portal-gnome.
 xdp-gnome-screencast = ["dbus", "pipewire"]
 # Enables the Tracy profiler instrumentation.
 profile-with-tracy = ["profiling/profile-with-tracy", "tracy-client/default"]
+# Enables the on-demand Tracy profiler instrumentation.
+profile-with-tracy-ondemand = ["profile-with-tracy", "tracy-client/ondemand", "tracy-client/manual-lifetime"]
+# Enables Tracy allocation profiling.
+profile-with-tracy-allocations = ["profile-with-tracy"]
+# Enables dinit integration (global environment).
+dinit = []
 
 [profile.release]
 debug = "line-tables-only"
 overflow-checks = true
 lto = "thin"
 
+[profile.release.package.niri-config]
+# knuffel with chomsky generates a metric ton of debuginfo.
+debug = false
+
+[profile.dev.package]
+insta.opt-level = 3
+similar.opt-level = 3
+
 [package.metadata.generate-rpm]
+version = "25.05.1"
 assets = [
     { source = "target/release/niri", dest = "/usr/bin/", mode = "755" },
     { source = "resources/niri-session", dest = "/usr/bin/", mode = "755" },
@@ -92,3 +164,15 @@ assets = [
 ]
 [package.metadata.generate-rpm.requires]
 alacritty = "*"
+fuzzel = "*"
+
+[package.metadata.deb]
+depends = "alacritty, fuzzel"
+assets = [
+    ["target/release/niri", "usr/bin/", "755"],
+    ["resources/niri-session", "usr/bin/", "755"],
+    ["resources/niri.desktop", "/usr/share/wayland-sessions/", "644"],
+    ["resources/niri-portals.conf", "/usr/share/xdg-desktop-portal/", "644"],
+    ["resources/niri.service", "/usr/lib/systemd/user/", "644"],
+    ["resources/niri-shutdown.target", "/usr/lib/systemd/user/", "644"],
+]

README.md

@@ -1,151 +1,138 @@
-# niri
+<h1 align="center">niri</h1>
+<p align="center">A scrollable-tiling Wayland compositor.</p>
+<p align="center">
+    <a href="https://matrix.to/#/#niri:matrix.org"><img alt="Matrix" src="https://img.shields.io/badge/matrix-%23niri-blue?logo=matrix"></a>
+    <a href="https://github.com/YaLTeR/niri/blob/main/LICENSE"><img alt="GitHub License" src="https://img.shields.io/github/license/YaLTeR/niri"></a>
+    <a href="https://github.com/YaLTeR/niri/releases"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/YaLTeR/niri?logo=github"></a>
+</p>
 
-A scrollable-tiling Wayland compositor.
+<p align="center">
+    <a href="https://yalter.github.io/niri/Getting-Started.html">Getting Started</a> | <a href="https://yalter.github.io/niri/Configuration%3A-Introduction.html">Configuration</a> | <a href="https://github.com/YaLTeR/niri/discussions/325">Setup&nbsp;Showcase</a>
+</p>
 
-![](https://github.com/YaLTeR/niri/assets/1794388/e35fd9e1-105b-4bd5-94c9-207fd6fb3c18)
+![niri with a few windows open](https://github.com/user-attachments/assets/535e6530-2f44-4b84-a883-1240a3eee6e9)
+
+## About
+
+Windows are arranged in columns on an infinite strip going to the right.
+Opening a new window never causes existing windows to resize.
+
+Every monitor has its own separate window strip.
+Windows can never "overflow" onto an adjacent monitor.
+
+Workspaces are dynamic and arranged vertically.
+Every monitor has an independent set of workspaces, and there's always one empty workspace present all the way down.
+
+The workspace arrangement is preserved across disconnecting and connecting monitors where it makes sense.
+When a monitor disconnects, its workspaces will move to another monitor, but upon reconnection they will move back to the original monitor.
+
+## Features
+
+- Built from the ground up for scrollable tiling
+- [Dynamic workspaces](https://yalter.github.io/niri/Workspaces.html) like in GNOME
+- An [Overview](https://github.com/user-attachments/assets/379a5d1f-acdb-4c11-b36c-e85fd91f0995) that zooms out workspaces and windows
+- Built-in screenshot UI
+- Monitor and window screencasting through xdg-desktop-portal-gnome
+    - You can [block out](https://yalter.github.io/niri/Configuration%3A-Window-Rules.html#block-out-from) sensitive windows from screencasts
+    - [Dynamic cast target](https://yalter.github.io/niri/Screencasting.html#dynamic-screencast-target) that can change what it shows on the go
+- [Touchpad](https://github.com/YaLTeR/niri/assets/1794388/946a910e-9bec-4cd1-a923-4a9421707515) and [mouse](https://github.com/YaLTeR/niri/assets/1794388/8464e65d-4bf2-44fa-8c8e-5883355bd000) gestures
+- Group windows into [tabs](https://yalter.github.io/niri/Tabs.html)
+- Configurable layout: gaps, borders, struts, window sizes
+- [Gradient borders](https://yalter.github.io/niri/Configuration%3A-Layout.html#gradients) with Oklab and Oklch support
+- [Animations](https://github.com/YaLTeR/niri/assets/1794388/ce178da2-af9e-4c51-876f-8709c241d95e) with support for [custom shaders](https://github.com/YaLTeR/niri/assets/1794388/27a238d6-0a22-4692-b794-30dc7a626fad)
+- Live-reloading config
+
+## Video Demo
+
+https://github.com/YaLTeR/niri/assets/1794388/bce834b0-f205-434e-a027-b373495f9729
+
+Also check out this video from Brodie Robertson that showcases a lot of the niri functionality: [Niri Is My New Favorite Wayland Compositor](https://youtu.be/DeYx2exm04M)
 
 ## Status
 
-A lot of the essential functionality is implemented, plus some goodies on top.
-Feel free to give niri a try.
-Have your waybars and fuzzels ready: niri is not a complete desktop environment.
+Niri is stable for day-to-day use and does most things expected of a Wayland compositor.
+Many people are daily-driving niri, and are happy to help in our [Matrix channel].
 
-https://github.com/YaLTeR/niri/assets/1794388/5d355694-7b06-4f00-8920-8dce54a8721c
+Give it a try!
+Follow the instructions on the [Getting Started](https://yalter.github.io/niri/Getting-Started.html) page.
+Have your [waybar]s and [fuzzel]s ready: niri is not a complete desktop environment.
+Also check out [awesome-niri], a list of niri-related links and projects.
 
-## Idea
+Here are some points you may have questions about:
 
-Niri implements scrollable tiling, heavily inspired by [PaperWM].
-Windows are arranged in columns on an infinite strip going to the right.
-Every column takes up a full monitor worth of height, divided among its windows.
+- **Multi-monitor**: yes, a core part of the design from the very start. Mixed DPI works.
+- **Fractional scaling**: yes, plus all niri UI stays pixel-perfect.
+- **NVIDIA**: seems to work fine.
+- **Floating windows**: yes, starting from niri 25.01.
+- **Input devices**: niri supports tablets, touchpads, and touchscreens.
+You can map the tablet to a specific monitor, or use [OpenTabletDriver].
+We have touchpad gestures, but no touchscreen gestures yet.
+- **Wlr protocols**: yes, we have most of the important ones like layer-shell, gamma-control, screencopy.
+You can check on [wayland.app](https://wayland.app) at the bottom of each protocol's page.
+- **Performance**: while I run niri on beefy machines, I try to stay conscious of performance.
+I've seen someone use it fine on an Eee PC 900 from 2008, of all things.
+- **Xwayland**: no built-in support, but xwayland-satellite is [easy to set up](https://yalter.github.io/niri/Xwayland.html#using-xwayland-satellite) and works very well.
+    - Steam and games, including Proton: work perfectly through xwayland-satellite.
+    - JetBrains IDEs, Ghidra: work well through xwayland-satellite.
+    - Discord and other Electron apps: work well through xwayland-satellite.
+    - Chromium and VSCode: work perfectly natively on Wayland with the right flags.
+    - X11 apps that want to position windows or bars at specific screen coordinates: won't work well; you can run them in a nested compositor like [labwc](https://yalter.github.io/niri/Xwayland.html#using-the-labwc-wayland-compositor) or [rootful Xwayland](https://yalter.github.io/niri/Xwayland.html#directly-running-xwayland-in-rootful-mode).
+    - Display scaling (integer or fractional) keeps X11 apps crisp, but you need the latest xwayland-satellite.
+    For games, you can run them in [gamescope] at native resolution, even with display scaling.
 
-With multiple monitors, every monitor has its own separate window strip.
-Windows can never "overflow" onto an adjacent monitor.
+## Media
 
-This is one of the reasons that prompted me to try writing my own compositor.
-PaperWM is a solid implementation, but, being a GNOME Shell extension, it has to work around Shell's global window coordinate space to prevent windows from overflowing.
+[niri: Making a Wayland compositor in Rust](https://youtu.be/Kmz8ODolnDg?list=PLRdS-n5seLRqrmWDQY4KDqtRMfIwU0U3T) · *December 2024*
 
-Niri also has dynamic workspaces which work similar to GNOME Shell.
-Since windows go left-to-right horizontally, workspaces are arranged vertically.
-Every monitor has an independent set of workspaces, and there's always one empty workspace present all the way down.
+My talk from the 2024 Moscow RustCon about niri, and how I do randomized property testing and profiling, and measure input latency.
+The talk is in Russian, but I prepared full English subtitles that you can find in YouTube's subtitle language selector.
 
-Niri tries to preserve the workspace arrangement as much as possible upon disconnecting and connecting monitors.
-When a monitor disconnects, its workspaces will move to another monitor, but upon reconnection they will move back to the original monitor.
+[An interview with Ivan, the developer behind Niri](https://www.trommelspeicher.de/podcast/special_the_developer_behind_niri) · *June 2025*
 
-## Building
+An interview by a German tech podcast Das Triumvirat (in English).
+We talk about niri development and history, and my experience building and maintaining niri.
 
-First, install the dependencies for your distribution.
+[A tour of the niri scrolling-tiling Wayland compositor](https://lwn.net/Articles/1025866/) · *July 2025*
 
-- Ubuntu:
+An LWN article with a nice overview and introduction to niri.
 
-    ```sh
-    sudo apt-get install -y software-properties-common
-    sudo add-apt-repository -y ppa:pipewire-debian/pipewire-upstream
-    sudo apt-get update -y
-    sudo apt-get install -y libudev-dev libgbm-dev libxkbcommon-dev libegl1-mesa-dev libwayland-dev libinput-dev libdbus-1-dev libsystemd-dev libseat-dev libpipewire-0.3-dev
-    ```
+## Contributing
 
-- Fedora:
+If you'd like to help with niri, there are plenty of both coding- and non-coding-related ways to do so.
+See [CONTRIBUTING.md](https://github.com/YaLTeR/niri/blob/main/CONTRIBUTING.md) for an overview.
 
-    ```sh
-    sudo dnf install gcc libudev-devel libgbm-devel libxkbcommon-devel wayland-devel libinput-devel dbus-devel systemd-devel libseat-devel pipewire-devel clang
-    ```
+## Inspiration
 
-Next, build niri with `cargo build --release`.
+Niri is heavily inspired by [PaperWM] which implements scrollable tiling on top of GNOME Shell.
 
-## Installation
+One of the reasons that prompted me to try writing my own compositor is being able to properly separate the monitors.
+Being a GNOME Shell extension, PaperWM has to work against Shell's global window coordinate space to prevent windows from overflowing.
 
-The recommended way to install and run niri is as a standalone desktop session.
-To do that, put files into the correct directories according to this table.
+## Tile Scrollably Elsewhere
 
-| File | Destination |
-| ---- | ----------- |
-| `target/release/niri` | `/usr/bin/` |
-| `resources/niri-session` | `/usr/bin/` |
-| `resources/niri.desktop` | `/usr/share/wayland-sessions/` |
-| `resources/niri-portals.conf` | `/usr/share/xdg-desktop-portal/` |
-| `resources/niri.service` | `/usr/lib/systemd/user/` |
-| `resources/niri-shutdown.target` | `/usr/lib/systemd/user/` |
+Here are some other projects which implement a similar workflow:
 
-Doing this will make niri appear in GDM and, presumably, other display managers.
+- [PaperWM]: scrollable tiling on top of GNOME Shell.
+- [karousel]: scrollable tiling on top of KDE.
+- [scroll](https://github.com/dawsers/scroll) and [papersway]: scrollable tiling on top of sway/i3.
+- [hyprscrolling] and [hyprslidr]: scrollable tiling on top of Hyprland.
+- [PaperWM.spoon]: scrollable tiling on top of macOS.
 
-## Running
+## Contact
 
-`cargo run --release`
+Our main communication channel is a Matrix chat, feel free to join and ask a question: https://matrix.to/#/#niri:matrix.org
 
-Inside an existing desktop session, it will run in a window.
-On a TTY, it will run natively.
-
-To exit when running on a TTY, press <kbd>Super</kbd><kbd>Shift</kbd><kbd>E</kbd>.
-
-### Session
-
-If you followed the recommended installation steps above, niri should appear in your display manager.
-Starting it from there will run niri as a desktop session.
-
-The niri session will autostart apps through the systemd xdg-autostart target.
-You can also autostart systemd services like [mako] by symlinking them into `$HOME/.config/systemd/user/niri.service.wants/`.
-
-Niri also works with some parts of xdg-desktop-portal-gnome.
-In particular, it supports file choosers and monitor screencasting (e.g. to [OBS]).
-
-## Default Hotkeys
-
-When running on a TTY, the Mod key is <kbd>Super</kbd>.
-When running in a window, the Mod key is <kbd>Alt</kbd>.
-
-The general system is: if a hotkey switches somewhere, then adding <kbd>Ctrl</kbd> will move the focused window or column there.
-
-| Hotkey | Description |
-| ------ | ----------- |
-| <kbd>Mod</kbd><kbd>T</kbd> | Spawn `alacritty` (terminal) |
-| <kbd>Mod</kbd><kbd>D</kbd> | Spawn `fuzzel` (application launcher) |
-| <kbd>Mod</kbd><kbd>Alt</kbd><kbd>L</kbd> | Spawn `swaylock` (screen locker) |
-| <kbd>Mod</kbd><kbd>Q</kbd> | Close the focused window |
-| <kbd>Mod</kbd><kbd>H</kbd> or <kbd>Mod</kbd><kbd>←</kbd> | Focus the column to the left |
-| <kbd>Mod</kbd><kbd>L</kbd> or <kbd>Mod</kbd><kbd>→</kbd> | Focus the column to the right |
-| <kbd>Mod</kbd><kbd>J</kbd> or <kbd>Mod</kbd><kbd>↓</kbd> | Focus the window below in a column |
-| <kbd>Mod</kbd><kbd>K</kbd> or <kbd>Mod</kbd><kbd>↑</kbd> | Focus the window above in a column |
-| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>H</kbd> or <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>←</kbd> | Move the focused column to the left |
-| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>L</kbd> or <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>→</kbd> | Move the focused column to the right |
-| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>J</kbd> or <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>↓</kbd> | Move the focused window below in a column |
-| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>K</kbd> or <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>↑</kbd> | Move the focused window above in a column |
-| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>H</kbd><kbd>J</kbd><kbd>K</kbd><kbd>L</kbd> or <kbd>Mod</kbd><kbd>Shift</kbd><kbd>←</kbd><kbd>↓</kbd><kbd>↑</kbd><kbd>→</kbd> | Focus the monitor to the side |
-| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>Shift</kbd><kbd>H</kbd><kbd>J</kbd><kbd>K</kbd><kbd>L</kbd> or <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>Shift</kbd><kbd>←</kbd><kbd>↓</kbd><kbd>↑</kbd><kbd>→</kbd> | Move the focused window to the monitor to the side |
-| <kbd>Mod</kbd><kbd>U</kbd> or <kbd>Mod</kbd><kbd>PageDown</kbd> | Switch to the workspace below |
-| <kbd>Mod</kbd><kbd>I</kbd> or <kbd>Mod</kbd><kbd>PageUp</kbd> | Switch to the workspace above |
-| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>U</kbd> or <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>PageDown</kbd> | Move the focused window to the workspace below |
-| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>I</kbd> or <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>PageUp</kbd> | Move the focused window to the workspace above |
-| <kbd>Mod</kbd><kbd>1</kbd>–<kbd>9</kbd> | Switch to a workspace by index |
-| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>1</kbd>–<kbd>9</kbd> | Move the focused window to a workspace by index |
-| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>U</kbd> or <kbd>Mod</kbd><kbd>Shift</kbd><kbd>PageDown</kbd> | Move the focused workspace down |
-| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>I</kbd> or <kbd>Mod</kbd><kbd>Shift</kbd><kbd>PageUp</kbd> | Move the focused workspace up |
-| <kbd>Mod</kbd><kbd>,</kbd> | Consume the window to the right into the focused column |
-| <kbd>Mod</kbd><kbd>.</kbd> | Expel the focused window into its own column |
-| <kbd>Mod</kbd><kbd>R</kbd> | Toggle between preset column widths |
-| <kbd>Mod</kbd><kbd>F</kbd> | Maximize column |
-| <kbd>Mod</kbd><kbd>C</kbd> | Center column within view |
-| <kbd>Mod</kbd><kbd>-</kbd> | Decrease column width by 10% |
-| <kbd>Mod</kbd><kbd>=</kbd> | Increase column width by 10% |
-| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>-</kbd> | Decrease window height by 10% |
-| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>=</kbd> | Increase window height by 10% |
-| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>F</kbd> | Toggle full-screen on the focused window |
-| <kbd>PrtSc</kbd> | Take an area screenshot. Select the area to screenshot with mouse, then press Space to save the screenshot, or Escape to cancel |
-| <kbd>Alt</kbd><kbd>PrtSc</kbd> | Take a screenshot of the focused window to clipboard and to `~/Pictures/Screenshots/` |
-| <kbd>Ctrl</kbd><kbd>PrtSc</kbd> | Take a screenshot of the focused monitor to clipboard and to `~/Pictures/Screenshots/` |
-| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>Shift</kbd><kbd>T</kbd> | Toggle debug tinting of rendered elements |
-| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>E</kbd> | Exit niri |
-
-## Configuration
-
-Niri will load configuration from `$XDG_CONFIG_HOME/.config/niri/config.kdl` or `~/.config/niri/config.kdl`.
-If this fails, it will load [the default configuration file](resources/default-config.kdl).
-Please use the default configuration file as the starting point for your custom configuration.
-
-Niri will live-reload many of the configuration settings, like key binds or gaps, as you change the config file.
-Though, some settings are still missing live-reload support.
-Notably, output modes and positions will only apply when the output is reconnected.
+We also have a community Discord server: https://discord.gg/vT8Sfjy7sx
 
 [PaperWM]: https://github.com/paperwm/PaperWM
-[mako]: https://github.com/emersion/mako
-[OBS]: https://flathub.org/apps/com.obsproject.Studio
-
+[waybar]: https://github.com/Alexays/Waybar
+[fuzzel]: https://codeberg.org/dnkl/fuzzel
+[awesome-niri]: https://github.com/Vortriz/awesome-niri
+[karousel]: https://github.com/peterfajdiga/karousel
+[papersway]: https://spwhitton.name/tech/code/papersway/
+[hyprscrolling]: https://github.com/hyprwm/hyprland-plugins/tree/main/hyprscrolling
+[hyprslidr]: https://gitlab.com/magus/hyprslidr
+[PaperWM.spoon]: https://github.com/mogenson/PaperWM.spoon
+[Matrix channel]: https://matrix.to/#/#niri:matrix.org
+[OpenTabletDriver]: https://opentabletdriver.net/
+[gamescope]: https://github.com/ValveSoftware/gamescope

clippy.toml

@@ -0,0 +1,5 @@
+ignore-interior-mutability = [
+    "smithay::desktop::Window",
+    "smithay::output::Output",
+    "wayland_server::backend::ClientId",
+]

docs/.gitignore

@@ -0,0 +1,2 @@
+site
+__pycache__

docs/hooks/remove-must-fail.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+import re
+
+# todo: this could be done generically, so that any 
+# ```language,annotation,anything-else 
+# is reduced to
+# ```language
+# which is what's supported by mkdocs/pygments
+# also note: mkdocs provides ways to highlight lines, add line numbers
+# but these are added as 
+# ```language linenums="1"
+# and not split by comma
+def on_page_markdown(
+    markdown: str, *, page, config, files
+):
+    return re.sub(
+        r",must-fail",
+        '', markdown, flags = re.I | re.M
+    )

docs/hooks/shortcodes.py

@@ -0,0 +1,44 @@
+# Copyright (c) 2016-2025 Martin Donath <martin.donath@squidfunk.com>
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+from __future__ import annotations
+import re
+from re import Match
+
+def on_page_markdown(
+    markdown: str, *, page, config, files
+):
+    def replace(match: Match):
+        matches = match.groups()
+        preposition, version = matches[0], matches[1]
+        return _badge_for_version(preposition, version)
+
+    return re.sub(
+        r"<sup>(Until|Since): (.*?)</sup>",
+        replace, markdown, flags = re.I | re.M
+    )
+
+def _badge_for_version(preposition: str, version: str):
+    if version == "next release":
+        # we might fail to make real links to release notes on other cases too, but for now this is the one i've found
+        return f"<span class=\"badge\">{preposition}: {version}</span>"
+    else:
+        path = f"https://github.com/YaLTeR/niri/releases/tag/v{version}"
+        return f"<span class=\"badge\">[{preposition}: {version}]({path})</span>"

docs/mkdocs.yaml

@@ -0,0 +1,109 @@
+site_name: niri
+docs_dir: wiki
+site_url: https://yalter.github.io/niri
+repo_url: https://github.com/YaLTeR/niri
+edit_uri: edit/main/docs/wiki/
+use_directory_urls: false
+
+theme:
+  name: material
+  logo: _assets/icons/logo.svg
+  favicon: _assets/icons/logo.svg
+  features:
+    - navigation.instant
+    - search.suggest
+    - content.code.copy
+    - content.action.edit
+  palette:
+    - media: "(prefers-color-scheme)"
+      primary: custom
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      primary: custom
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      primary: custom
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+markdown_extensions:
+  - github-callouts
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.keys
+  - toc:
+      permalink: '#'
+plugins:
+  - search
+hooks:
+  - hooks/shortcodes.py
+  - hooks/remove-must-fail.py
+extra_css:
+  - _assets/stylesheets/niri.css
+strict: true
+validation:
+  nav:
+    omitted_files: warn
+    not_found: warn
+    absolute_links: relative_to_docs
+  links:
+    not_found: warn
+    anchors: warn
+    absolute_links: relative_to_docs
+    unrecognized_links: warn
+not_in_nav: |
+  _Sidebar.md
+  Configuration:-Overview.md
+  README.md
+# ah, wouldn't it be nice if we could autogenerate this with wiki/_Sidebar.md
+nav:
+  - Usage:
+    - Getting Started: Getting-Started.md
+    - Example systemd Setup: Example-systemd-Setup.md
+    - Important Software: Important-Software.md
+    - Workspaces: Workspaces.md
+    - Floating Windows: Floating-Windows.md
+    - Tabs: Tabs.md
+    - Overview: Overview.md
+    - Screencasting: Screencasting.md
+    - Layer‐Shell Components: Layer‐Shell-Components.md
+    - IPC, niri msg: IPC.md
+    - Application-Specific Issues: Application-Issues.md
+    - Nvidia: Nvidia.md
+    - Xwayland: Xwayland.md
+    - Gestures: Gestures.md
+    - Packaging niri: Packaging-niri.md
+    - FAQ: FAQ.md
+  - Configuration:
+    - Introduction: Configuration:-Introduction.md
+    - Input: Configuration:-Input.md
+    - Outputs: Configuration:-Outputs.md
+    - Key Bindings: Configuration:-Key-Bindings.md
+    - Switch Events: Configuration:-Switch-Events.md
+    - Layout: Configuration:-Layout.md
+    - Named Workspaces: Configuration:-Named-Workspaces.md
+    - Miscellaneous: Configuration:-Miscellaneous.md
+    - Window Rules: Configuration:-Window-Rules.md
+    - Layer Rules: Configuration:-Layer-Rules.md
+    - Animations: Configuration:-Animations.md
+    - Gestures: Configuration:-Gestures.md
+    - Debug Options: Configuration:-Debug-Options.md
+  - Development:
+    - Design Principles: Development:-Design-Principles.md
+    - Developing niri: Development:-Developing-niri.md
+    - Documenting niri: Development:-Documenting-niri.md
+    - Fractional Layout: Development:-Fractional-Layout.md
+    - Redraw Loop: Development:-Redraw-Loop.md
+    - Animation Timing: Development:-Animation-Timing.md

docs/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "niri-docs"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+    "markdown-callouts>=0.4.0",
+    "mkdocs-material>=9.6.15",
+    "pygments",
+]
+
+# for KDL highlighting support
+# TODO: use the official pygments package once https://github.com/pygments/pygments/pull/2936 is merged
+[tool.uv.sources]
+pygments = { git = "https://github.com/chinatsu/pygments", rev = "0f0b0d4da2839e1285881389155bb4605a0a6dc4" }

docs/uv.lock

@@ -0,0 +1,511 @@
+version = 1
+revision = 3
+requires-python = ">=3.10"
+
+[[package]]
+name = "babel"
+version = "2.17.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7d/6b/d52e42361e1aa00709585ecc30b3f9684b3ab62530771402248b1b1d6240/babel-2.17.0.tar.gz", hash = "sha256:0c54cffb19f690cdcc52a3b50bcbf71e07a808d1c80d549f2459b9d2cf0afb9d", size = 9951852, upload-time = "2025-02-01T15:17:41.026Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b7/b8/3fe70c75fe32afc4bb507f75563d39bc5642255d1d94f1f23604725780bf/babel-2.17.0-py3-none-any.whl", hash = "sha256:4d0b53093fdfb4b21c92b5213dba5a1b23885afa8383709427046b21c366e5f2", size = 10182537, upload-time = "2025-02-01T15:17:37.39Z" },
+]
+
+[[package]]
+name = "backrefs"
+version = "5.9"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/eb/a7/312f673df6a79003279e1f55619abbe7daebbb87c17c976ddc0345c04c7b/backrefs-5.9.tar.gz", hash = "sha256:808548cb708d66b82ee231f962cb36faaf4f2baab032f2fbb783e9c2fdddaa59", size = 5765857, upload-time = "2025-06-22T19:34:13.97Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/19/4d/798dc1f30468134906575156c089c492cf79b5a5fd373f07fe26c4d046bf/backrefs-5.9-py310-none-any.whl", hash = "sha256:db8e8ba0e9de81fcd635f440deab5ae5f2591b54ac1ebe0550a2ca063488cd9f", size = 380267, upload-time = "2025-06-22T19:34:05.252Z" },
+    { url = "https://files.pythonhosted.org/packages/55/07/f0b3375bf0d06014e9787797e6b7cc02b38ac9ff9726ccfe834d94e9991e/backrefs-5.9-py311-none-any.whl", hash = "sha256:6907635edebbe9b2dc3de3a2befff44d74f30a4562adbb8b36f21252ea19c5cf", size = 392072, upload-time = "2025-06-22T19:34:06.743Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/12/4f345407259dd60a0997107758ba3f221cf89a9b5a0f8ed5b961aef97253/backrefs-5.9-py312-none-any.whl", hash = "sha256:7fdf9771f63e6028d7fee7e0c497c81abda597ea45d6b8f89e8ad76994f5befa", size = 397947, upload-time = "2025-06-22T19:34:08.172Z" },
+    { url = "https://files.pythonhosted.org/packages/10/bf/fa31834dc27a7f05e5290eae47c82690edc3a7b37d58f7fb35a1bdbf355b/backrefs-5.9-py313-none-any.whl", hash = "sha256:cc37b19fa219e93ff825ed1fed8879e47b4d89aa7a1884860e2db64ccd7c676b", size = 399843, upload-time = "2025-06-22T19:34:09.68Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/24/b29af34b2c9c41645a9f4ff117bae860291780d73880f449e0b5d948c070/backrefs-5.9-py314-none-any.whl", hash = "sha256:df5e169836cc8acb5e440ebae9aad4bf9d15e226d3bad049cf3f6a5c20cc8dc9", size = 411762, upload-time = "2025-06-22T19:34:11.037Z" },
+    { url = "https://files.pythonhosted.org/packages/41/ff/392bff89415399a979be4a65357a41d92729ae8580a66073d8ec8d810f98/backrefs-5.9-py39-none-any.whl", hash = "sha256:f48ee18f6252b8f5777a22a00a09a85de0ca931658f1dd96d4406a34f3748c60", size = 380265, upload-time = "2025-06-22T19:34:12.405Z" },
+]
+
+[[package]]
+name = "certifi"
+version = "2025.7.14"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b3/76/52c535bcebe74590f296d6c77c86dabf761c41980e1347a2422e4aa2ae41/certifi-2025.7.14.tar.gz", hash = "sha256:8ea99dbdfaaf2ba2f9bac77b9249ef62ec5218e7c2b2e903378ed5fccf765995", size = 163981, upload-time = "2025-07-14T03:29:28.449Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4f/52/34c6cf5bb9285074dc3531c437b3919e825d976fde097a7a73f79e726d03/certifi-2025.7.14-py3-none-any.whl", hash = "sha256:6b31f564a415d79ee77df69d757bb49a5bb53bd9f756cbbe24394ffd6fc1f4b2", size = 162722, upload-time = "2025-07-14T03:29:26.863Z" },
+]
+
+[[package]]
+name = "charset-normalizer"
+version = "3.4.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e4/33/89c2ced2b67d1c2a61c19c6751aa8902d46ce3dacb23600a283619f5a12d/charset_normalizer-3.4.2.tar.gz", hash = "sha256:5baececa9ecba31eff645232d59845c07aa030f0c81ee70184a90d35099a0e63", size = 126367, upload-time = "2025-05-02T08:34:42.01Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/95/28/9901804da60055b406e1a1c5ba7aac1276fb77f1dde635aabfc7fd84b8ab/charset_normalizer-3.4.2-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:7c48ed483eb946e6c04ccbe02c6b4d1d48e51944b6db70f697e089c193404941", size = 201818, upload-time = "2025-05-02T08:31:46.725Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/9b/892a8c8af9110935e5adcbb06d9c6fe741b6bb02608c6513983048ba1a18/charset_normalizer-3.4.2-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b2d318c11350e10662026ad0eb71bb51c7812fc8590825304ae0bdd4ac283acd", size = 144649, upload-time = "2025-05-02T08:31:48.889Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/a5/4179abd063ff6414223575e008593861d62abfc22455b5d1a44995b7c101/charset_normalizer-3.4.2-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9cbfacf36cb0ec2897ce0ebc5d08ca44213af24265bd56eca54bee7923c48fd6", size = 155045, upload-time = "2025-05-02T08:31:50.757Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/95/bc08c7dfeddd26b4be8c8287b9bb055716f31077c8b0ea1cd09553794665/charset_normalizer-3.4.2-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:18dd2e350387c87dabe711b86f83c9c78af772c748904d372ade190b5c7c9d4d", size = 147356, upload-time = "2025-05-02T08:31:52.634Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/2d/7a5b635aa65284bf3eab7653e8b4151ab420ecbae918d3e359d1947b4d61/charset_normalizer-3.4.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8075c35cd58273fee266c58c0c9b670947c19df5fb98e7b66710e04ad4e9ff86", size = 149471, upload-time = "2025-05-02T08:31:56.207Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/38/51fc6ac74251fd331a8cfdb7ec57beba8c23fd5493f1050f71c87ef77ed0/charset_normalizer-3.4.2-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:5bf4545e3b962767e5c06fe1738f951f77d27967cb2caa64c28be7c4563e162c", size = 151317, upload-time = "2025-05-02T08:31:57.613Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/17/edee1e32215ee6e9e46c3e482645b46575a44a2d72c7dfd49e49f60ce6bf/charset_normalizer-3.4.2-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:7a6ab32f7210554a96cd9e33abe3ddd86732beeafc7a28e9955cdf22ffadbab0", size = 146368, upload-time = "2025-05-02T08:31:59.468Z" },
+    { url = "https://files.pythonhosted.org/packages/26/2c/ea3e66f2b5f21fd00b2825c94cafb8c326ea6240cd80a91eb09e4a285830/charset_normalizer-3.4.2-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:b33de11b92e9f75a2b545d6e9b6f37e398d86c3e9e9653c4864eb7e89c5773ef", size = 154491, upload-time = "2025-05-02T08:32:01.219Z" },
+    { url = "https://files.pythonhosted.org/packages/52/47/7be7fa972422ad062e909fd62460d45c3ef4c141805b7078dbab15904ff7/charset_normalizer-3.4.2-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:8755483f3c00d6c9a77f490c17e6ab0c8729e39e6390328e42521ef175380ae6", size = 157695, upload-time = "2025-05-02T08:32:03.045Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/42/9f02c194da282b2b340f28e5fb60762de1151387a36842a92b533685c61e/charset_normalizer-3.4.2-cp310-cp310-musllinux_1_2_s390x.whl", hash = "sha256:68a328e5f55ec37c57f19ebb1fdc56a248db2e3e9ad769919a58672958e8f366", size = 154849, upload-time = "2025-05-02T08:32:04.651Z" },
+    { url = "https://files.pythonhosted.org/packages/67/44/89cacd6628f31fb0b63201a618049be4be2a7435a31b55b5eb1c3674547a/charset_normalizer-3.4.2-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:21b2899062867b0e1fde9b724f8aecb1af14f2778d69aacd1a5a1853a597a5db", size = 150091, upload-time = "2025-05-02T08:32:06.719Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/79/4b8da9f712bc079c0f16b6d67b099b0b8d808c2292c937f267d816ec5ecc/charset_normalizer-3.4.2-cp310-cp310-win32.whl", hash = "sha256:e8082b26888e2f8b36a042a58307d5b917ef2b1cacab921ad3323ef91901c71a", size = 98445, upload-time = "2025-05-02T08:32:08.66Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/d7/96970afb4fb66497a40761cdf7bd4f6fca0fc7bafde3a84f836c1f57a926/charset_normalizer-3.4.2-cp310-cp310-win_amd64.whl", hash = "sha256:f69a27e45c43520f5487f27627059b64aaf160415589230992cec34c5e18a509", size = 105782, upload-time = "2025-05-02T08:32:10.46Z" },
+    { url = "https://files.pythonhosted.org/packages/05/85/4c40d00dcc6284a1c1ad5de5e0996b06f39d8232f1031cd23c2f5c07ee86/charset_normalizer-3.4.2-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:be1e352acbe3c78727a16a455126d9ff83ea2dfdcbc83148d2982305a04714c2", size = 198794, upload-time = "2025-05-02T08:32:11.945Z" },
+    { url = "https://files.pythonhosted.org/packages/41/d9/7a6c0b9db952598e97e93cbdfcb91bacd89b9b88c7c983250a77c008703c/charset_normalizer-3.4.2-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:aa88ca0b1932e93f2d961bf3addbb2db902198dca337d88c89e1559e066e7645", size = 142846, upload-time = "2025-05-02T08:32:13.946Z" },
+    { url = "https://files.pythonhosted.org/packages/66/82/a37989cda2ace7e37f36c1a8ed16c58cf48965a79c2142713244bf945c89/charset_normalizer-3.4.2-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:d524ba3f1581b35c03cb42beebab4a13e6cdad7b36246bd22541fa585a56cccd", size = 153350, upload-time = "2025-05-02T08:32:15.873Z" },
+    { url = "https://files.pythonhosted.org/packages/df/68/a576b31b694d07b53807269d05ec3f6f1093e9545e8607121995ba7a8313/charset_normalizer-3.4.2-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:28a1005facc94196e1fb3e82a3d442a9d9110b8434fc1ded7a24a2983c9888d8", size = 145657, upload-time = "2025-05-02T08:32:17.283Z" },
+    { url = "https://files.pythonhosted.org/packages/92/9b/ad67f03d74554bed3aefd56fe836e1623a50780f7c998d00ca128924a499/charset_normalizer-3.4.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:fdb20a30fe1175ecabed17cbf7812f7b804b8a315a25f24678bcdf120a90077f", size = 147260, upload-time = "2025-05-02T08:32:18.807Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/e6/8aebae25e328160b20e31a7e9929b1578bbdc7f42e66f46595a432f8539e/charset_normalizer-3.4.2-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:0f5d9ed7f254402c9e7d35d2f5972c9bbea9040e99cd2861bd77dc68263277c7", size = 149164, upload-time = "2025-05-02T08:32:20.333Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/f2/b3c2f07dbcc248805f10e67a0262c93308cfa149a4cd3d1fe01f593e5fd2/charset_normalizer-3.4.2-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:efd387a49825780ff861998cd959767800d54f8308936b21025326de4b5a42b9", size = 144571, upload-time = "2025-05-02T08:32:21.86Z" },
+    { url = "https://files.pythonhosted.org/packages/60/5b/c3f3a94bc345bc211622ea59b4bed9ae63c00920e2e8f11824aa5708e8b7/charset_normalizer-3.4.2-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:f0aa37f3c979cf2546b73e8222bbfa3dc07a641585340179d768068e3455e544", size = 151952, upload-time = "2025-05-02T08:32:23.434Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/4d/ff460c8b474122334c2fa394a3f99a04cf11c646da895f81402ae54f5c42/charset_normalizer-3.4.2-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:e70e990b2137b29dc5564715de1e12701815dacc1d056308e2b17e9095372a82", size = 155959, upload-time = "2025-05-02T08:32:24.993Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/2b/b964c6a2fda88611a1fe3d4c400d39c66a42d6c169c924818c848f922415/charset_normalizer-3.4.2-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:0c8c57f84ccfc871a48a47321cfa49ae1df56cd1d965a09abe84066f6853b9c0", size = 153030, upload-time = "2025-05-02T08:32:26.435Z" },
+    { url = "https://files.pythonhosted.org/packages/59/2e/d3b9811db26a5ebf444bc0fa4f4be5aa6d76fc6e1c0fd537b16c14e849b6/charset_normalizer-3.4.2-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:6b66f92b17849b85cad91259efc341dce9c1af48e2173bf38a85c6329f1033e5", size = 148015, upload-time = "2025-05-02T08:32:28.376Z" },
+    { url = "https://files.pythonhosted.org/packages/90/07/c5fd7c11eafd561bb51220d600a788f1c8d77c5eef37ee49454cc5c35575/charset_normalizer-3.4.2-cp311-cp311-win32.whl", hash = "sha256:daac4765328a919a805fa5e2720f3e94767abd632ae410a9062dff5412bae65a", size = 98106, upload-time = "2025-05-02T08:32:30.281Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/05/5e33dbef7e2f773d672b6d79f10ec633d4a71cd96db6673625838a4fd532/charset_normalizer-3.4.2-cp311-cp311-win_amd64.whl", hash = "sha256:e53efc7c7cee4c1e70661e2e112ca46a575f90ed9ae3fef200f2a25e954f4b28", size = 105402, upload-time = "2025-05-02T08:32:32.191Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/a4/37f4d6035c89cac7930395a35cc0f1b872e652eaafb76a6075943754f095/charset_normalizer-3.4.2-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:0c29de6a1a95f24b9a1aa7aefd27d2487263f00dfd55a77719b530788f75cff7", size = 199936, upload-time = "2025-05-02T08:32:33.712Z" },
+    { url = "https://files.pythonhosted.org/packages/ee/8a/1a5e33b73e0d9287274f899d967907cd0bf9c343e651755d9307e0dbf2b3/charset_normalizer-3.4.2-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:cddf7bd982eaa998934a91f69d182aec997c6c468898efe6679af88283b498d3", size = 143790, upload-time = "2025-05-02T08:32:35.768Z" },
+    { url = "https://files.pythonhosted.org/packages/66/52/59521f1d8e6ab1482164fa21409c5ef44da3e9f653c13ba71becdd98dec3/charset_normalizer-3.4.2-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:fcbe676a55d7445b22c10967bceaaf0ee69407fbe0ece4d032b6eb8d4565982a", size = 153924, upload-time = "2025-05-02T08:32:37.284Z" },
+    { url = "https://files.pythonhosted.org/packages/86/2d/fb55fdf41964ec782febbf33cb64be480a6b8f16ded2dbe8db27a405c09f/charset_normalizer-3.4.2-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d41c4d287cfc69060fa91cae9683eacffad989f1a10811995fa309df656ec214", size = 146626, upload-time = "2025-05-02T08:32:38.803Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/73/6ede2ec59bce19b3edf4209d70004253ec5f4e319f9a2e3f2f15601ed5f7/charset_normalizer-3.4.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:4e594135de17ab3866138f496755f302b72157d115086d100c3f19370839dd3a", size = 148567, upload-time = "2025-05-02T08:32:40.251Z" },
+    { url = "https://files.pythonhosted.org/packages/09/14/957d03c6dc343c04904530b6bef4e5efae5ec7d7990a7cbb868e4595ee30/charset_normalizer-3.4.2-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:cf713fe9a71ef6fd5adf7a79670135081cd4431c2943864757f0fa3a65b1fafd", size = 150957, upload-time = "2025-05-02T08:32:41.705Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/c8/8174d0e5c10ccebdcb1b53cc959591c4c722a3ad92461a273e86b9f5a302/charset_normalizer-3.4.2-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:a370b3e078e418187da8c3674eddb9d983ec09445c99a3a263c2011993522981", size = 145408, upload-time = "2025-05-02T08:32:43.709Z" },
+    { url = "https://files.pythonhosted.org/packages/58/aa/8904b84bc8084ac19dc52feb4f5952c6df03ffb460a887b42615ee1382e8/charset_normalizer-3.4.2-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:a955b438e62efdf7e0b7b52a64dc5c3396e2634baa62471768a64bc2adb73d5c", size = 153399, upload-time = "2025-05-02T08:32:46.197Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/26/89ee1f0e264d201cb65cf054aca6038c03b1a0c6b4ae998070392a3ce605/charset_normalizer-3.4.2-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:7222ffd5e4de8e57e03ce2cef95a4c43c98fcb72ad86909abdfc2c17d227fc1b", size = 156815, upload-time = "2025-05-02T08:32:48.105Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/07/68e95b4b345bad3dbbd3a8681737b4338ff2c9df29856a6d6d23ac4c73cb/charset_normalizer-3.4.2-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:bee093bf902e1d8fc0ac143c88902c3dfc8941f7ea1d6a8dd2bcb786d33db03d", size = 154537, upload-time = "2025-05-02T08:32:49.719Z" },
+    { url = "https://files.pythonhosted.org/packages/77/1a/5eefc0ce04affb98af07bc05f3bac9094513c0e23b0562d64af46a06aae4/charset_normalizer-3.4.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:dedb8adb91d11846ee08bec4c8236c8549ac721c245678282dcb06b221aab59f", size = 149565, upload-time = "2025-05-02T08:32:51.404Z" },
+    { url = "https://files.pythonhosted.org/packages/37/a0/2410e5e6032a174c95e0806b1a6585eb21e12f445ebe239fac441995226a/charset_normalizer-3.4.2-cp312-cp312-win32.whl", hash = "sha256:db4c7bf0e07fc3b7d89ac2a5880a6a8062056801b83ff56d8464b70f65482b6c", size = 98357, upload-time = "2025-05-02T08:32:53.079Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/4f/c02d5c493967af3eda9c771ad4d2bbc8df6f99ddbeb37ceea6e8716a32bc/charset_normalizer-3.4.2-cp312-cp312-win_amd64.whl", hash = "sha256:5a9979887252a82fefd3d3ed2a8e3b937a7a809f65dcb1e068b090e165bbe99e", size = 105776, upload-time = "2025-05-02T08:32:54.573Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/12/a93df3366ed32db1d907d7593a94f1fe6293903e3e92967bebd6950ed12c/charset_normalizer-3.4.2-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:926ca93accd5d36ccdabd803392ddc3e03e6d4cd1cf17deff3b989ab8e9dbcf0", size = 199622, upload-time = "2025-05-02T08:32:56.363Z" },
+    { url = "https://files.pythonhosted.org/packages/04/93/bf204e6f344c39d9937d3c13c8cd5bbfc266472e51fc8c07cb7f64fcd2de/charset_normalizer-3.4.2-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:eba9904b0f38a143592d9fc0e19e2df0fa2e41c3c3745554761c5f6447eedabf", size = 143435, upload-time = "2025-05-02T08:32:58.551Z" },
+    { url = "https://files.pythonhosted.org/packages/22/2a/ea8a2095b0bafa6c5b5a55ffdc2f924455233ee7b91c69b7edfcc9e02284/charset_normalizer-3.4.2-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:3fddb7e2c84ac87ac3a947cb4e66d143ca5863ef48e4a5ecb83bd48619e4634e", size = 153653, upload-time = "2025-05-02T08:33:00.342Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/57/1b090ff183d13cef485dfbe272e2fe57622a76694061353c59da52c9a659/charset_normalizer-3.4.2-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:98f862da73774290f251b9df8d11161b6cf25b599a66baf087c1ffe340e9bfd1", size = 146231, upload-time = "2025-05-02T08:33:02.081Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/28/ffc026b26f441fc67bd21ab7f03b313ab3fe46714a14b516f931abe1a2d8/charset_normalizer-3.4.2-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6c9379d65defcab82d07b2a9dfbfc2e95bc8fe0ebb1b176a3190230a3ef0e07c", size = 148243, upload-time = "2025-05-02T08:33:04.063Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/0f/9abe9bd191629c33e69e47c6ef45ef99773320e9ad8e9cb08b8ab4a8d4cb/charset_normalizer-3.4.2-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e635b87f01ebc977342e2697d05b56632f5f879a4f15955dfe8cef2448b51691", size = 150442, upload-time = "2025-05-02T08:33:06.418Z" },
+    { url = "https://files.pythonhosted.org/packages/67/7c/a123bbcedca91d5916c056407f89a7f5e8fdfce12ba825d7d6b9954a1a3c/charset_normalizer-3.4.2-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:1c95a1e2902a8b722868587c0e1184ad5c55631de5afc0eb96bc4b0d738092c0", size = 145147, upload-time = "2025-05-02T08:33:08.183Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/fe/1ac556fa4899d967b83e9893788e86b6af4d83e4726511eaaad035e36595/charset_normalizer-3.4.2-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:ef8de666d6179b009dce7bcb2ad4c4a779f113f12caf8dc77f0162c29d20490b", size = 153057, upload-time = "2025-05-02T08:33:09.986Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/ff/acfc0b0a70b19e3e54febdd5301a98b72fa07635e56f24f60502e954c461/charset_normalizer-3.4.2-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:32fc0341d72e0f73f80acb0a2c94216bd704f4f0bce10aedea38f30502b271ff", size = 156454, upload-time = "2025-05-02T08:33:11.814Z" },
+    { url = "https://files.pythonhosted.org/packages/92/08/95b458ce9c740d0645feb0e96cea1f5ec946ea9c580a94adfe0b617f3573/charset_normalizer-3.4.2-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:289200a18fa698949d2b39c671c2cc7a24d44096784e76614899a7ccf2574b7b", size = 154174, upload-time = "2025-05-02T08:33:13.707Z" },
+    { url = "https://files.pythonhosted.org/packages/78/be/8392efc43487ac051eee6c36d5fbd63032d78f7728cb37aebcc98191f1ff/charset_normalizer-3.4.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:4a476b06fbcf359ad25d34a057b7219281286ae2477cc5ff5e3f70a246971148", size = 149166, upload-time = "2025-05-02T08:33:15.458Z" },
+    { url = "https://files.pythonhosted.org/packages/44/96/392abd49b094d30b91d9fbda6a69519e95802250b777841cf3bda8fe136c/charset_normalizer-3.4.2-cp313-cp313-win32.whl", hash = "sha256:aaeeb6a479c7667fbe1099af9617c83aaca22182d6cf8c53966491a0f1b7ffb7", size = 98064, upload-time = "2025-05-02T08:33:17.06Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/b0/0200da600134e001d91851ddc797809e2fe0ea72de90e09bec5a2fbdaccb/charset_normalizer-3.4.2-cp313-cp313-win_amd64.whl", hash = "sha256:aa6af9e7d59f9c12b33ae4e9450619cf2488e2bbe9b44030905877f0b2324980", size = 105641, upload-time = "2025-05-02T08:33:18.753Z" },
+    { url = "https://files.pythonhosted.org/packages/20/94/c5790835a017658cbfabd07f3bfb549140c3ac458cfc196323996b10095a/charset_normalizer-3.4.2-py3-none-any.whl", hash = "sha256:7f56930ab0abd1c45cd15be65cc741c28b1c9a34876ce8c17a2fa107810c0af0", size = 52626, upload-time = "2025-05-02T08:34:40.053Z" },
+]
+
+[[package]]
+name = "click"
+version = "8.2.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/60/6c/8ca2efa64cf75a977a0d7fac081354553ebe483345c734fb6b6515d96bbc/click-8.2.1.tar.gz", hash = "sha256:27c491cc05d968d271d5a1db13e3b5a184636d9d930f148c50b038f0d0646202", size = 286342, upload-time = "2025-05-20T23:19:49.832Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/85/32/10bb5764d90a8eee674e9dc6f4db6a0ab47c8c4d0d83c27f7c39ac415a4d/click-8.2.1-py3-none-any.whl", hash = "sha256:61a3265b914e850b85317d0b3109c7f8cd35a670f963866005d6ef1d5175a12b", size = 102215, upload-time = "2025-05-20T23:19:47.796Z" },
+]
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "ghp-import"
+version = "2.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "python-dateutil" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d9/29/d40217cbe2f6b1359e00c6c307bb3fc876ba74068cbab3dde77f03ca0dc4/ghp-import-2.1.0.tar.gz", hash = "sha256:9c535c4c61193c2df8871222567d7fd7e5014d835f97dc7b7439069e2413d343", size = 10943, upload-time = "2022-05-02T15:47:16.11Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f7/ec/67fbef5d497f86283db54c22eec6f6140243aae73265799baaaa19cd17fb/ghp_import-2.1.0-py3-none-any.whl", hash = "sha256:8337dd7b50877f163d4c0289bc1f1c7f127550241988d568c1db512c4324a619", size = 11034, upload-time = "2022-05-02T15:47:14.552Z" },
+]
+
+[[package]]
+name = "idna"
+version = "3.10"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f1/70/7703c29685631f5a7590aa73f1f1d3fa9a380e654b86af429e0934a32f7d/idna-3.10.tar.gz", hash = "sha256:12f65c9b470abda6dc35cf8e63cc574b1c52b11df2c86030af0ac09b01b13ea9", size = 190490, upload-time = "2024-09-15T18:07:39.745Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/76/c6/c88e154df9c4e1a2a66ccf0005a88dfb2650c1dffb6f5ce603dfbd452ce3/idna-3.10-py3-none-any.whl", hash = "sha256:946d195a0d259cbba61165e88e65941f16e9b36ea6ddb97f00452bae8b1287d3", size = 70442, upload-time = "2024-09-15T18:07:37.964Z" },
+]
+
+[[package]]
+name = "jinja2"
+version = "3.1.6"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markupsafe" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/df/bf/f7da0350254c0ed7c72f3e33cef02e048281fec7ecec5f032d4aac52226b/jinja2-3.1.6.tar.gz", hash = "sha256:0137fb05990d35f1275a587e9aee6d56da821fc83491a0fb838183be43f66d6d", size = 245115, upload-time = "2025-03-05T20:05:02.478Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/62/a1/3d680cbfd5f4b8f15abc1d571870c5fc3e594bb582bc3b64ea099db13e56/jinja2-3.1.6-py3-none-any.whl", hash = "sha256:85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67", size = 134899, upload-time = "2025-03-05T20:05:00.369Z" },
+]
+
+[[package]]
+name = "markdown"
+version = "3.8.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d7/c2/4ab49206c17f75cb08d6311171f2d65798988db4360c4d1485bd0eedd67c/markdown-3.8.2.tar.gz", hash = "sha256:247b9a70dd12e27f67431ce62523e675b866d254f900c4fe75ce3dda62237c45", size = 362071, upload-time = "2025-06-19T17:12:44.483Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/96/2b/34cc11786bc00d0f04d0f5fdc3a2b1ae0b6239eef72d3d345805f9ad92a1/markdown-3.8.2-py3-none-any.whl", hash = "sha256:5c83764dbd4e00bdd94d85a19b8d55ccca20fe35b2e678a1422b380324dd5f24", size = 106827, upload-time = "2025-06-19T17:12:42.994Z" },
+]
+
+[[package]]
+name = "markdown-callouts"
+version = "0.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markdown" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/87/73/ae5aa379f6f7fea9d0bf4cba888f9a31d451d90f80033ae60ae3045770d5/markdown_callouts-0.4.0.tar.gz", hash = "sha256:7ed2c90486967058a73a547781121983839522d67041ae52c4979616f1b2b746", size = 9768, upload-time = "2024-01-22T23:18:18.513Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1d/b5/7b0a0a52c82bfccd830af2a8cc8add1c5bc932e0204922434954a631dd51/markdown_callouts-0.4.0-py3-none-any.whl", hash = "sha256:ed0da38f29158d93116a0d0c6ecaf9df90b37e0d989b5337d678ee6e6d6550b7", size = 7108, upload-time = "2024-01-22T23:18:17.465Z" },
+]
+
+[[package]]
+name = "markupsafe"
+version = "3.0.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b2/97/5d42485e71dfc078108a86d6de8fa46db44a1a9295e89c5d6d4a06e23a62/markupsafe-3.0.2.tar.gz", hash = "sha256:ee55d3edf80167e48ea11a923c7386f4669df67d7994554387f84e7d8b0a2bf0", size = 20537, upload-time = "2024-10-18T15:21:54.129Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/90/d08277ce111dd22f77149fd1a5d4653eeb3b3eaacbdfcbae5afb2600eebd/MarkupSafe-3.0.2-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:7e94c425039cde14257288fd61dcfb01963e658efbc0ff54f5306b06054700f8", size = 14357, upload-time = "2024-10-18T15:20:51.44Z" },
+    { url = "https://files.pythonhosted.org/packages/04/e1/6e2194baeae0bca1fae6629dc0cbbb968d4d941469cbab11a3872edff374/MarkupSafe-3.0.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:9e2d922824181480953426608b81967de705c3cef4d1af983af849d7bd619158", size = 12393, upload-time = "2024-10-18T15:20:52.426Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/69/35fa85a8ece0a437493dc61ce0bb6d459dcba482c34197e3efc829aa357f/MarkupSafe-3.0.2-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:38a9ef736c01fccdd6600705b09dc574584b89bea478200c5fbf112a6b0d5579", size = 21732, upload-time = "2024-10-18T15:20:53.578Z" },
+    { url = "https://files.pythonhosted.org/packages/22/35/137da042dfb4720b638d2937c38a9c2df83fe32d20e8c8f3185dbfef05f7/MarkupSafe-3.0.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:bbcb445fa71794da8f178f0f6d66789a28d7319071af7a496d4d507ed566270d", size = 20866, upload-time = "2024-10-18T15:20:55.06Z" },
+    { url = "https://files.pythonhosted.org/packages/29/28/6d029a903727a1b62edb51863232152fd335d602def598dade38996887f0/MarkupSafe-3.0.2-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:57cb5a3cf367aeb1d316576250f65edec5bb3be939e9247ae594b4bcbc317dfb", size = 20964, upload-time = "2024-10-18T15:20:55.906Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/cd/07438f95f83e8bc028279909d9c9bd39e24149b0d60053a97b2bc4f8aa51/MarkupSafe-3.0.2-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:3809ede931876f5b2ec92eef964286840ed3540dadf803dd570c3b7e13141a3b", size = 21977, upload-time = "2024-10-18T15:20:57.189Z" },
+    { url = "https://files.pythonhosted.org/packages/29/01/84b57395b4cc062f9c4c55ce0df7d3108ca32397299d9df00fedd9117d3d/MarkupSafe-3.0.2-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:e07c3764494e3776c602c1e78e298937c3315ccc9043ead7e685b7f2b8d47b3c", size = 21366, upload-time = "2024-10-18T15:20:58.235Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/6e/61ebf08d8940553afff20d1fb1ba7294b6f8d279df9fd0c0db911b4bbcfd/MarkupSafe-3.0.2-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:b424c77b206d63d500bcb69fa55ed8d0e6a3774056bdc4839fc9298a7edca171", size = 21091, upload-time = "2024-10-18T15:20:59.235Z" },
+    { url = "https://files.pythonhosted.org/packages/11/23/ffbf53694e8c94ebd1e7e491de185124277964344733c45481f32ede2499/MarkupSafe-3.0.2-cp310-cp310-win32.whl", hash = "sha256:fcabf5ff6eea076f859677f5f0b6b5c1a51e70a376b0579e0eadef8db48c6b50", size = 15065, upload-time = "2024-10-18T15:21:00.307Z" },
+    { url = "https://files.pythonhosted.org/packages/44/06/e7175d06dd6e9172d4a69a72592cb3f7a996a9c396eee29082826449bbc3/MarkupSafe-3.0.2-cp310-cp310-win_amd64.whl", hash = "sha256:6af100e168aa82a50e186c82875a5893c5597a0c1ccdb0d8b40240b1f28b969a", size = 15514, upload-time = "2024-10-18T15:21:01.122Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/28/bbf83e3f76936960b850435576dd5e67034e200469571be53f69174a2dfd/MarkupSafe-3.0.2-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:9025b4018f3a1314059769c7bf15441064b2207cb3f065e6ea1e7359cb46db9d", size = 14353, upload-time = "2024-10-18T15:21:02.187Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/30/316d194b093cde57d448a4c3209f22e3046c5bb2fb0820b118292b334be7/MarkupSafe-3.0.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:93335ca3812df2f366e80509ae119189886b0f3c2b81325d39efdb84a1e2ae93", size = 12392, upload-time = "2024-10-18T15:21:02.941Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/96/9cdafba8445d3a53cae530aaf83c38ec64c4d5427d975c974084af5bc5d2/MarkupSafe-3.0.2-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2cb8438c3cbb25e220c2ab33bb226559e7afb3baec11c4f218ffa7308603c832", size = 23984, upload-time = "2024-10-18T15:21:03.953Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/a4/aefb044a2cd8d7334c8a47d3fb2c9f328ac48cb349468cc31c20b539305f/MarkupSafe-3.0.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a123e330ef0853c6e822384873bef7507557d8e4a082961e1defa947aa59ba84", size = 23120, upload-time = "2024-10-18T15:21:06.495Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/21/5e4851379f88f3fad1de30361db501300d4f07bcad047d3cb0449fc51f8c/MarkupSafe-3.0.2-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1e084f686b92e5b83186b07e8a17fc09e38fff551f3602b249881fec658d3eca", size = 23032, upload-time = "2024-10-18T15:21:07.295Z" },
+    { url = "https://files.pythonhosted.org/packages/00/7b/e92c64e079b2d0d7ddf69899c98842f3f9a60a1ae72657c89ce2655c999d/MarkupSafe-3.0.2-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:d8213e09c917a951de9d09ecee036d5c7d36cb6cb7dbaece4c71a60d79fb9798", size = 24057, upload-time = "2024-10-18T15:21:08.073Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/ac/46f960ca323037caa0a10662ef97d0a4728e890334fc156b9f9e52bcc4ca/MarkupSafe-3.0.2-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:5b02fb34468b6aaa40dfc198d813a641e3a63b98c2b05a16b9f80b7ec314185e", size = 23359, upload-time = "2024-10-18T15:21:09.318Z" },
+    { url = "https://files.pythonhosted.org/packages/69/84/83439e16197337b8b14b6a5b9c2105fff81d42c2a7c5b58ac7b62ee2c3b1/MarkupSafe-3.0.2-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:0bff5e0ae4ef2e1ae4fdf2dfd5b76c75e5c2fa4132d05fc1b0dabcd20c7e28c4", size = 23306, upload-time = "2024-10-18T15:21:10.185Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/34/a15aa69f01e2181ed8d2b685c0d2f6655d5cca2c4db0ddea775e631918cd/MarkupSafe-3.0.2-cp311-cp311-win32.whl", hash = "sha256:6c89876f41da747c8d3677a2b540fb32ef5715f97b66eeb0c6b66f5e3ef6f59d", size = 15094, upload-time = "2024-10-18T15:21:11.005Z" },
+    { url = "https://files.pythonhosted.org/packages/da/b8/3a3bd761922d416f3dc5d00bfbed11f66b1ab89a0c2b6e887240a30b0f6b/MarkupSafe-3.0.2-cp311-cp311-win_amd64.whl", hash = "sha256:70a87b411535ccad5ef2f1df5136506a10775d267e197e4cf531ced10537bd6b", size = 15521, upload-time = "2024-10-18T15:21:12.911Z" },
+    { url = "https://files.pythonhosted.org/packages/22/09/d1f21434c97fc42f09d290cbb6350d44eb12f09cc62c9476effdb33a18aa/MarkupSafe-3.0.2-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:9778bd8ab0a994ebf6f84c2b949e65736d5575320a17ae8984a77fab08db94cf", size = 14274, upload-time = "2024-10-18T15:21:13.777Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/b0/18f76bba336fa5aecf79d45dcd6c806c280ec44538b3c13671d49099fdd0/MarkupSafe-3.0.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:846ade7b71e3536c4e56b386c2a47adf5741d2d8b94ec9dc3e92e5e1ee1e2225", size = 12348, upload-time = "2024-10-18T15:21:14.822Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/25/dd5c0f6ac1311e9b40f4af06c78efde0f3b5cbf02502f8ef9501294c425b/MarkupSafe-3.0.2-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1c99d261bd2d5f6b59325c92c73df481e05e57f19837bdca8413b9eac4bd8028", size = 24149, upload-time = "2024-10-18T15:21:15.642Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/f0/89e7aadfb3749d0f52234a0c8c7867877876e0a20b60e2188e9850794c17/MarkupSafe-3.0.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e17c96c14e19278594aa4841ec148115f9c7615a47382ecb6b82bd8fea3ab0c8", size = 23118, upload-time = "2024-10-18T15:21:17.133Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/da/f2eeb64c723f5e3777bc081da884b414671982008c47dcc1873d81f625b6/MarkupSafe-3.0.2-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:88416bd1e65dcea10bc7569faacb2c20ce071dd1f87539ca2ab364bf6231393c", size = 22993, upload-time = "2024-10-18T15:21:18.064Z" },
+    { url = "https://files.pythonhosted.org/packages/da/0e/1f32af846df486dce7c227fe0f2398dc7e2e51d4a370508281f3c1c5cddc/MarkupSafe-3.0.2-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:2181e67807fc2fa785d0592dc2d6206c019b9502410671cc905d132a92866557", size = 24178, upload-time = "2024-10-18T15:21:18.859Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/f6/bb3ca0532de8086cbff5f06d137064c8410d10779c4c127e0e47d17c0b71/MarkupSafe-3.0.2-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:52305740fe773d09cffb16f8ed0427942901f00adedac82ec8b67752f58a1b22", size = 23319, upload-time = "2024-10-18T15:21:19.671Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/82/8be4c96ffee03c5b4a034e60a31294daf481e12c7c43ab8e34a1453ee48b/MarkupSafe-3.0.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:ad10d3ded218f1039f11a75f8091880239651b52e9bb592ca27de44eed242a48", size = 23352, upload-time = "2024-10-18T15:21:20.971Z" },
+    { url = "https://files.pythonhosted.org/packages/51/ae/97827349d3fcffee7e184bdf7f41cd6b88d9919c80f0263ba7acd1bbcb18/MarkupSafe-3.0.2-cp312-cp312-win32.whl", hash = "sha256:0f4ca02bea9a23221c0182836703cbf8930c5e9454bacce27e767509fa286a30", size = 15097, upload-time = "2024-10-18T15:21:22.646Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/80/a61f99dc3a936413c3ee4e1eecac96c0da5ed07ad56fd975f1a9da5bc630/MarkupSafe-3.0.2-cp312-cp312-win_amd64.whl", hash = "sha256:8e06879fc22a25ca47312fbe7c8264eb0b662f6db27cb2d3bbbc74b1df4b9b87", size = 15601, upload-time = "2024-10-18T15:21:23.499Z" },
+    { url = "https://files.pythonhosted.org/packages/83/0e/67eb10a7ecc77a0c2bbe2b0235765b98d164d81600746914bebada795e97/MarkupSafe-3.0.2-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:ba9527cdd4c926ed0760bc301f6728ef34d841f405abf9d4f959c478421e4efd", size = 14274, upload-time = "2024-10-18T15:21:24.577Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/6d/9409f3684d3335375d04e5f05744dfe7e9f120062c9857df4ab490a1031a/MarkupSafe-3.0.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:f8b3d067f2e40fe93e1ccdd6b2e1d16c43140e76f02fb1319a05cf2b79d99430", size = 12352, upload-time = "2024-10-18T15:21:25.382Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/f5/6eadfcd3885ea85fe2a7c128315cc1bb7241e1987443d78c8fe712d03091/MarkupSafe-3.0.2-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:569511d3b58c8791ab4c2e1285575265991e6d8f8700c7be0e88f86cb0672094", size = 24122, upload-time = "2024-10-18T15:21:26.199Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/91/96cf928db8236f1bfab6ce15ad070dfdd02ed88261c2afafd4b43575e9e9/MarkupSafe-3.0.2-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:15ab75ef81add55874e7ab7055e9c397312385bd9ced94920f2802310c930396", size = 23085, upload-time = "2024-10-18T15:21:27.029Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/cf/c9d56af24d56ea04daae7ac0940232d31d5a8354f2b457c6d856b2057d69/MarkupSafe-3.0.2-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f3818cb119498c0678015754eba762e0d61e5b52d34c8b13d770f0719f7b1d79", size = 22978, upload-time = "2024-10-18T15:21:27.846Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/9f/8619835cd6a711d6272d62abb78c033bda638fdc54c4e7f4272cf1c0962b/MarkupSafe-3.0.2-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:cdb82a876c47801bb54a690c5ae105a46b392ac6099881cdfb9f6e95e4014c6a", size = 24208, upload-time = "2024-10-18T15:21:28.744Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/bf/176950a1792b2cd2102b8ffeb5133e1ed984547b75db47c25a67d3359f77/MarkupSafe-3.0.2-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:cabc348d87e913db6ab4aa100f01b08f481097838bdddf7c7a84b7575b7309ca", size = 23357, upload-time = "2024-10-18T15:21:29.545Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/4f/9a02c1d335caabe5c4efb90e1b6e8ee944aa245c1aaaab8e8a618987d816/MarkupSafe-3.0.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:444dcda765c8a838eaae23112db52f1efaf750daddb2d9ca300bcae1039adc5c", size = 23344, upload-time = "2024-10-18T15:21:30.366Z" },
+    { url = "https://files.pythonhosted.org/packages/ee/55/c271b57db36f748f0e04a759ace9f8f759ccf22b4960c270c78a394f58be/MarkupSafe-3.0.2-cp313-cp313-win32.whl", hash = "sha256:bcf3e58998965654fdaff38e58584d8937aa3096ab5354d493c77d1fdd66d7a1", size = 15101, upload-time = "2024-10-18T15:21:31.207Z" },
+    { url = "https://files.pythonhosted.org/packages/29/88/07df22d2dd4df40aba9f3e402e6dc1b8ee86297dddbad4872bd5e7b0094f/MarkupSafe-3.0.2-cp313-cp313-win_amd64.whl", hash = "sha256:e6a2a455bd412959b57a172ce6328d2dd1f01cb2135efda2e4576e8a23fa3b0f", size = 15603, upload-time = "2024-10-18T15:21:32.032Z" },
+    { url = "https://files.pythonhosted.org/packages/62/6a/8b89d24db2d32d433dffcd6a8779159da109842434f1dd2f6e71f32f738c/MarkupSafe-3.0.2-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:b5a6b3ada725cea8a5e634536b1b01c30bcdcd7f9c6fff4151548d5bf6b3a36c", size = 14510, upload-time = "2024-10-18T15:21:33.625Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/06/a10f955f70a2e5a9bf78d11a161029d278eeacbd35ef806c3fd17b13060d/MarkupSafe-3.0.2-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:a904af0a6162c73e3edcb969eeeb53a63ceeb5d8cf642fade7d39e7963a22ddb", size = 12486, upload-time = "2024-10-18T15:21:34.611Z" },
+    { url = "https://files.pythonhosted.org/packages/34/cf/65d4a571869a1a9078198ca28f39fba5fbb910f952f9dbc5220afff9f5e6/MarkupSafe-3.0.2-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4aa4e5faecf353ed117801a068ebab7b7e09ffb6e1d5e412dc852e0da018126c", size = 25480, upload-time = "2024-10-18T15:21:35.398Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/e3/90e9651924c430b885468b56b3d597cabf6d72be4b24a0acd1fa0e12af67/MarkupSafe-3.0.2-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:c0ef13eaeee5b615fb07c9a7dadb38eac06a0608b41570d8ade51c56539e509d", size = 23914, upload-time = "2024-10-18T15:21:36.231Z" },
+    { url = "https://files.pythonhosted.org/packages/66/8c/6c7cf61f95d63bb866db39085150df1f2a5bd3335298f14a66b48e92659c/MarkupSafe-3.0.2-cp313-cp313t-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:d16a81a06776313e817c951135cf7340a3e91e8c1ff2fac444cfd75fffa04afe", size = 23796, upload-time = "2024-10-18T15:21:37.073Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/35/cbe9238ec3f47ac9a7c8b3df7a808e7cb50fe149dc7039f5f454b3fba218/MarkupSafe-3.0.2-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:6381026f158fdb7c72a168278597a5e3a5222e83ea18f543112b2662a9b699c5", size = 25473, upload-time = "2024-10-18T15:21:37.932Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/32/7621a4382488aa283cc05e8984a9c219abad3bca087be9ec77e89939ded9/MarkupSafe-3.0.2-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:3d79d162e7be8f996986c064d1c7c817f6df3a77fe3d6859f6f9e7be4b8c213a", size = 24114, upload-time = "2024-10-18T15:21:39.799Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/80/0985960e4b89922cb5a0bac0ed39c5b96cbc1a536a99f30e8c220a996ed9/MarkupSafe-3.0.2-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:131a3c7689c85f5ad20f9f6fb1b866f402c445b220c19fe4308c0b147ccd2ad9", size = 24098, upload-time = "2024-10-18T15:21:40.813Z" },
+    { url = "https://files.pythonhosted.org/packages/82/78/fedb03c7d5380df2427038ec8d973587e90561b2d90cd472ce9254cf348b/MarkupSafe-3.0.2-cp313-cp313t-win32.whl", hash = "sha256:ba8062ed2cf21c07a9e295d5b8a2a5ce678b913b45fdf68c32d95d6c1291e0b6", size = 15208, upload-time = "2024-10-18T15:21:41.814Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/65/6079a46068dfceaeabb5dcad6d674f5f5c61a6fa5673746f42a9f4c233b3/MarkupSafe-3.0.2-cp313-cp313t-win_amd64.whl", hash = "sha256:e444a31f8db13eb18ada366ab3cf45fd4b31e4db1236a4448f68778c1d1a5a2f", size = 15739, upload-time = "2024-10-18T15:21:42.784Z" },
+]
+
+[[package]]
+name = "mergedeep"
+version = "1.3.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/3a/41/580bb4006e3ed0361b8151a01d324fb03f420815446c7def45d02f74c270/mergedeep-1.3.4.tar.gz", hash = "sha256:0096d52e9dad9939c3d975a774666af186eda617e6ca84df4c94dec30004f2a8", size = 4661, upload-time = "2021-02-05T18:55:30.623Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2c/19/04f9b178c2d8a15b076c8b5140708fa6ffc5601fb6f1e975537072df5b2a/mergedeep-1.3.4-py3-none-any.whl", hash = "sha256:70775750742b25c0d8f36c55aed03d24c3384d17c951b3175d898bd778ef0307", size = 6354, upload-time = "2021-02-05T18:55:29.583Z" },
+]
+
+[[package]]
+name = "mkdocs"
+version = "1.6.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "ghp-import" },
+    { name = "jinja2" },
+    { name = "markdown" },
+    { name = "markupsafe" },
+    { name = "mergedeep" },
+    { name = "mkdocs-get-deps" },
+    { name = "packaging" },
+    { name = "pathspec" },
+    { name = "pyyaml" },
+    { name = "pyyaml-env-tag" },
+    { name = "watchdog" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/bc/c6/bbd4f061bd16b378247f12953ffcb04786a618ce5e904b8c5a01a0309061/mkdocs-1.6.1.tar.gz", hash = "sha256:7b432f01d928c084353ab39c57282f29f92136665bdd6abf7c1ec8d822ef86f2", size = 3889159, upload-time = "2024-08-30T12:24:06.899Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/22/5b/dbc6a8cddc9cfa9c4971d59fb12bb8d42e161b7e7f8cc89e49137c5b279c/mkdocs-1.6.1-py3-none-any.whl", hash = "sha256:db91759624d1647f3f34aa0c3f327dd2601beae39a366d6e064c03468d35c20e", size = 3864451, upload-time = "2024-08-30T12:24:05.054Z" },
+]
+
+[[package]]
+name = "mkdocs-get-deps"
+version = "0.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "mergedeep" },
+    { name = "platformdirs" },
+    { name = "pyyaml" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/98/f5/ed29cd50067784976f25ed0ed6fcd3c2ce9eb90650aa3b2796ddf7b6870b/mkdocs_get_deps-0.2.0.tar.gz", hash = "sha256:162b3d129c7fad9b19abfdcb9c1458a651628e4b1dea628ac68790fb3061c60c", size = 10239, upload-time = "2023-11-20T17:51:09.981Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9f/d4/029f984e8d3f3b6b726bd33cafc473b75e9e44c0f7e80a5b29abc466bdea/mkdocs_get_deps-0.2.0-py3-none-any.whl", hash = "sha256:2bf11d0b133e77a0dd036abeeb06dec8775e46efa526dc70667d8863eefc6134", size = 9521, upload-time = "2023-11-20T17:51:08.587Z" },
+]
+
+[[package]]
+name = "mkdocs-material"
+version = "9.6.15"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "babel" },
+    { name = "backrefs" },
+    { name = "colorama" },
+    { name = "jinja2" },
+    { name = "markdown" },
+    { name = "mkdocs" },
+    { name = "mkdocs-material-extensions" },
+    { name = "paginate" },
+    { name = "pygments" },
+    { name = "pymdown-extensions" },
+    { name = "requests" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/95/c1/f804ba2db2ddc2183e900befe7dad64339a34fa935034e1ab405289d0a97/mkdocs_material-9.6.15.tar.gz", hash = "sha256:64adf8fa8dba1a17905b6aee1894a5aafd966d4aeb44a11088519b0f5ca4f1b5", size = 3951836, upload-time = "2025-07-01T10:14:15.671Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1d/30/dda19f0495a9096b64b6b3c07c4bfcff1c76ee0fc521086d53593f18b4c0/mkdocs_material-9.6.15-py3-none-any.whl", hash = "sha256:ac969c94d4fe5eb7c924b6d2f43d7db41159ea91553d18a9afc4780c34f2717a", size = 8716840, upload-time = "2025-07-01T10:14:13.18Z" },
+]
+
+[[package]]
+name = "mkdocs-material-extensions"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/79/9b/9b4c96d6593b2a541e1cb8b34899a6d021d208bb357042823d4d2cabdbe7/mkdocs_material_extensions-1.3.1.tar.gz", hash = "sha256:10c9511cea88f568257f960358a467d12b970e1f7b2c0e5fb2bb48cab1928443", size = 11847, upload-time = "2023-11-22T19:09:45.208Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5b/54/662a4743aa81d9582ee9339d4ffa3c8fd40a4965e033d77b9da9774d3960/mkdocs_material_extensions-1.3.1-py3-none-any.whl", hash = "sha256:adff8b62700b25cb77b53358dad940f3ef973dd6db797907c49e3c2ef3ab4e31", size = 8728, upload-time = "2023-11-22T19:09:43.465Z" },
+]
+
+[[package]]
+name = "niri-docs"
+version = "0.1.0"
+source = { virtual = "." }
+dependencies = [
+    { name = "markdown-callouts" },
+    { name = "mkdocs-material" },
+    { name = "pygments" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "markdown-callouts", specifier = ">=0.4.0" },
+    { name = "mkdocs-material", specifier = ">=9.6.15" },
+    { name = "pygments", git = "https://github.com/chinatsu/pygments?rev=0f0b0d4da2839e1285881389155bb4605a0a6dc4" },
+]
+
+[[package]]
+name = "packaging"
+version = "25.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a1/d4/1fc4078c65507b51b96ca8f8c3ba19e6a61c8253c72794544580a7b6c24d/packaging-25.0.tar.gz", hash = "sha256:d443872c98d677bf60f6a1f2f8c1cb748e8fe762d2bf9d3148b5599295b0fc4f", size = 165727, upload-time = "2025-04-19T11:48:59.673Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/20/12/38679034af332785aac8774540895e234f4d07f7545804097de4b666afd8/packaging-25.0-py3-none-any.whl", hash = "sha256:29572ef2b1f17581046b3a2227d5c611fb25ec70ca1ba8554b24b0e69331a484", size = 66469, upload-time = "2025-04-19T11:48:57.875Z" },
+]
+
+[[package]]
+name = "paginate"
+version = "0.5.7"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ec/46/68dde5b6bc00c1296ec6466ab27dddede6aec9af1b99090e1107091b3b84/paginate-0.5.7.tar.gz", hash = "sha256:22bd083ab41e1a8b4f3690544afb2c60c25e5c9a63a30fa2f483f6c60c8e5945", size = 19252, upload-time = "2024-08-25T14:17:24.139Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/90/96/04b8e52da071d28f5e21a805b19cb9390aa17a47462ac87f5e2696b9566d/paginate-0.5.7-py2.py3-none-any.whl", hash = "sha256:b885e2af73abcf01d9559fd5216b57ef722f8c42affbb63942377668e35c7591", size = 13746, upload-time = "2024-08-25T14:17:22.55Z" },
+]
+
+[[package]]
+name = "pathspec"
+version = "0.12.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ca/bc/f35b8446f4531a7cb215605d100cd88b7ac6f44ab3fc94870c120ab3adbf/pathspec-0.12.1.tar.gz", hash = "sha256:a482d51503a1ab33b1c67a6c3813a26953dbdc71c31dacaef9a838c4e29f5712", size = 51043, upload-time = "2023-12-10T22:30:45Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cc/20/ff623b09d963f88bfde16306a54e12ee5ea43e9b597108672ff3a408aad6/pathspec-0.12.1-py3-none-any.whl", hash = "sha256:a0d503e138a4c123b27490a4f7beda6a01c6f288df0e4a8b79c7eb0dc7b4cc08", size = 31191, upload-time = "2023-12-10T22:30:43.14Z" },
+]
+
+[[package]]
+name = "platformdirs"
+version = "4.3.8"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/fe/8b/3c73abc9c759ecd3f1f7ceff6685840859e8070c4d947c93fae71f6a0bf2/platformdirs-4.3.8.tar.gz", hash = "sha256:3d512d96e16bcb959a814c9f348431070822a6496326a4be0911c40b5a74c2bc", size = 21362, upload-time = "2025-05-07T22:47:42.121Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fe/39/979e8e21520d4e47a0bbe349e2713c0aac6f3d853d0e5b34d76206c439aa/platformdirs-4.3.8-py3-none-any.whl", hash = "sha256:ff7059bb7eb1179e2685604f4aaf157cfd9535242bd23742eadc3c13542139b4", size = 18567, upload-time = "2025-05-07T22:47:40.376Z" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.19.2"
+source = { git = "https://github.com/chinatsu/pygments?rev=0f0b0d4da2839e1285881389155bb4605a0a6dc4#0f0b0d4da2839e1285881389155bb4605a0a6dc4" }
+
+[[package]]
+name = "pymdown-extensions"
+version = "10.16"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markdown" },
+    { name = "pyyaml" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/1a/0a/c06b542ac108bfc73200677309cd9188a3a01b127a63f20cadc18d873d88/pymdown_extensions-10.16.tar.gz", hash = "sha256:71dac4fca63fabeffd3eb9038b756161a33ec6e8d230853d3cecf562155ab3de", size = 853197, upload-time = "2025-06-21T17:56:36.974Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/98/d4/10bb14004d3c792811e05e21b5e5dcae805aacb739bd12a0540967b99592/pymdown_extensions-10.16-py3-none-any.whl", hash = "sha256:f5dd064a4db588cb2d95229fc4ee63a1b16cc8b4d0e6145c0899ed8723da1df2", size = 266143, upload-time = "2025-06-21T17:56:35.356Z" },
+]
+
+[[package]]
+name = "python-dateutil"
+version = "2.9.0.post0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "six" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/66/c0/0c8b6ad9f17a802ee498c46e004a0eb49bc148f2fd230864601a86dcf6db/python-dateutil-2.9.0.post0.tar.gz", hash = "sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3", size = 342432, upload-time = "2024-03-01T18:36:20.211Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" },
+]
+
+[[package]]
+name = "pyyaml"
+version = "6.0.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/54/ed/79a089b6be93607fa5cdaedf301d7dfb23af5f25c398d5ead2525b063e17/pyyaml-6.0.2.tar.gz", hash = "sha256:d584d9ec91ad65861cc08d42e834324ef890a082e591037abe114850ff7bbc3e", size = 130631, upload-time = "2024-08-06T20:33:50.674Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9b/95/a3fac87cb7158e231b5a6012e438c647e1a87f09f8e0d123acec8ab8bf71/PyYAML-6.0.2-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:0a9a2848a5b7feac301353437eb7d5957887edbf81d56e903999a75a3d743086", size = 184199, upload-time = "2024-08-06T20:31:40.178Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/7a/68bd47624dab8fd4afbfd3c48e3b79efe09098ae941de5b58abcbadff5cb/PyYAML-6.0.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:29717114e51c84ddfba879543fb232a6ed60086602313ca38cce623c1d62cfbf", size = 171758, upload-time = "2024-08-06T20:31:42.173Z" },
+    { url = "https://files.pythonhosted.org/packages/49/ee/14c54df452143b9ee9f0f29074d7ca5516a36edb0b4cc40c3f280131656f/PyYAML-6.0.2-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8824b5a04a04a047e72eea5cec3bc266db09e35de6bdfe34c9436ac5ee27d237", size = 718463, upload-time = "2024-08-06T20:31:44.263Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/61/de363a97476e766574650d742205be468921a7b532aa2499fcd886b62530/PyYAML-6.0.2-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:7c36280e6fb8385e520936c3cb3b8042851904eba0e58d277dca80a5cfed590b", size = 719280, upload-time = "2024-08-06T20:31:50.199Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/4e/1523cb902fd98355e2e9ea5e5eb237cbc5f3ad5f3075fa65087aa0ecb669/PyYAML-6.0.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ec031d5d2feb36d1d1a24380e4db6d43695f3748343d99434e6f5f9156aaa2ed", size = 751239, upload-time = "2024-08-06T20:31:52.292Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/33/5504b3a9a4464893c32f118a9cc045190a91637b119a9c881da1cf6b7a72/PyYAML-6.0.2-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:936d68689298c36b53b29f23c6dbb74de12b4ac12ca6cfe0e047bedceea56180", size = 695802, upload-time = "2024-08-06T20:31:53.836Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/20/8347dcabd41ef3a3cdc4f7b7a2aff3d06598c8779faa189cdbf878b626a4/PyYAML-6.0.2-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:23502f431948090f597378482b4812b0caae32c22213aecf3b55325e049a6c68", size = 720527, upload-time = "2024-08-06T20:31:55.565Z" },
+    { url = "https://files.pythonhosted.org/packages/be/aa/5afe99233fb360d0ff37377145a949ae258aaab831bde4792b32650a4378/PyYAML-6.0.2-cp310-cp310-win32.whl", hash = "sha256:2e99c6826ffa974fe6e27cdb5ed0021786b03fc98e5ee3c5bfe1fd5015f42b99", size = 144052, upload-time = "2024-08-06T20:31:56.914Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/84/0fa4b06f6d6c958d207620fc60005e241ecedceee58931bb20138e1e5776/PyYAML-6.0.2-cp310-cp310-win_amd64.whl", hash = "sha256:a4d3091415f010369ae4ed1fc6b79def9416358877534caf6a0fdd2146c87a3e", size = 161774, upload-time = "2024-08-06T20:31:58.304Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/aa/7af4e81f7acba21a4c6be026da38fd2b872ca46226673c89a758ebdc4fd2/PyYAML-6.0.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:cc1c1159b3d456576af7a3e4d1ba7e6924cb39de8f67111c735f6fc832082774", size = 184612, upload-time = "2024-08-06T20:32:03.408Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/62/b9faa998fd185f65c1371643678e4d58254add437edb764a08c5a98fb986/PyYAML-6.0.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:1e2120ef853f59c7419231f3bf4e7021f1b936f6ebd222406c3b60212205d2ee", size = 172040, upload-time = "2024-08-06T20:32:04.926Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/0c/c804f5f922a9a6563bab712d8dcc70251e8af811fce4524d57c2c0fd49a4/PyYAML-6.0.2-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5d225db5a45f21e78dd9358e58a98702a0302f2659a3c6cd320564b75b86f47c", size = 736829, upload-time = "2024-08-06T20:32:06.459Z" },
+    { url = "https://files.pythonhosted.org/packages/51/16/6af8d6a6b210c8e54f1406a6b9481febf9c64a3109c541567e35a49aa2e7/PyYAML-6.0.2-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:5ac9328ec4831237bec75defaf839f7d4564be1e6b25ac710bd1a96321cc8317", size = 764167, upload-time = "2024-08-06T20:32:08.338Z" },
+    { url = "https://files.pythonhosted.org/packages/75/e4/2c27590dfc9992f73aabbeb9241ae20220bd9452df27483b6e56d3975cc5/PyYAML-6.0.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3ad2a3decf9aaba3d29c8f537ac4b243e36bef957511b4766cb0057d32b0be85", size = 762952, upload-time = "2024-08-06T20:32:14.124Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/97/ecc1abf4a823f5ac61941a9c00fe501b02ac3ab0e373c3857f7d4b83e2b6/PyYAML-6.0.2-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:ff3824dc5261f50c9b0dfb3be22b4567a6f938ccce4587b38952d85fd9e9afe4", size = 735301, upload-time = "2024-08-06T20:32:16.17Z" },
+    { url = "https://files.pythonhosted.org/packages/45/73/0f49dacd6e82c9430e46f4a027baa4ca205e8b0a9dce1397f44edc23559d/PyYAML-6.0.2-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:797b4f722ffa07cc8d62053e4cff1486fa6dc094105d13fea7b1de7d8bf71c9e", size = 756638, upload-time = "2024-08-06T20:32:18.555Z" },
+    { url = "https://files.pythonhosted.org/packages/22/5f/956f0f9fc65223a58fbc14459bf34b4cc48dec52e00535c79b8db361aabd/PyYAML-6.0.2-cp311-cp311-win32.whl", hash = "sha256:11d8f3dd2b9c1207dcaf2ee0bbbfd5991f571186ec9cc78427ba5bd32afae4b5", size = 143850, upload-time = "2024-08-06T20:32:19.889Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/23/8da0bbe2ab9dcdd11f4f4557ccaf95c10b9811b13ecced089d43ce59c3c8/PyYAML-6.0.2-cp311-cp311-win_amd64.whl", hash = "sha256:e10ce637b18caea04431ce14fabcf5c64a1c61ec9c56b071a4b7ca131ca52d44", size = 161980, upload-time = "2024-08-06T20:32:21.273Z" },
+    { url = "https://files.pythonhosted.org/packages/86/0c/c581167fc46d6d6d7ddcfb8c843a4de25bdd27e4466938109ca68492292c/PyYAML-6.0.2-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:c70c95198c015b85feafc136515252a261a84561b7b1d51e3384e0655ddf25ab", size = 183873, upload-time = "2024-08-06T20:32:25.131Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/0c/38374f5bb272c051e2a69281d71cba6fdb983413e6758b84482905e29a5d/PyYAML-6.0.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:ce826d6ef20b1bc864f0a68340c8b3287705cae2f8b4b1d932177dcc76721725", size = 173302, upload-time = "2024-08-06T20:32:26.511Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/93/9916574aa8c00aa06bbac729972eb1071d002b8e158bd0e83a3b9a20a1f7/PyYAML-6.0.2-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1f71ea527786de97d1a0cc0eacd1defc0985dcf6b3f17bb77dcfc8c34bec4dc5", size = 739154, upload-time = "2024-08-06T20:32:28.363Z" },
+    { url = "https://files.pythonhosted.org/packages/95/0f/b8938f1cbd09739c6da569d172531567dbcc9789e0029aa070856f123984/PyYAML-6.0.2-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9b22676e8097e9e22e36d6b7bda33190d0d400f345f23d4065d48f4ca7ae0425", size = 766223, upload-time = "2024-08-06T20:32:30.058Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/2b/614b4752f2e127db5cc206abc23a8c19678e92b23c3db30fc86ab731d3bd/PyYAML-6.0.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:80bab7bfc629882493af4aa31a4cfa43a4c57c83813253626916b8c7ada83476", size = 767542, upload-time = "2024-08-06T20:32:31.881Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/00/dd137d5bcc7efea1836d6264f049359861cf548469d18da90cd8216cf05f/PyYAML-6.0.2-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:0833f8694549e586547b576dcfaba4a6b55b9e96098b36cdc7ebefe667dfed48", size = 731164, upload-time = "2024-08-06T20:32:37.083Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/1f/4f998c900485e5c0ef43838363ba4a9723ac0ad73a9dc42068b12aaba4e4/PyYAML-6.0.2-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8b9c7197f7cb2738065c481a0461e50ad02f18c78cd75775628afb4d7137fb3b", size = 756611, upload-time = "2024-08-06T20:32:38.898Z" },
+    { url = "https://files.pythonhosted.org/packages/df/d1/f5a275fdb252768b7a11ec63585bc38d0e87c9e05668a139fea92b80634c/PyYAML-6.0.2-cp312-cp312-win32.whl", hash = "sha256:ef6107725bd54b262d6dedcc2af448a266975032bc85ef0172c5f059da6325b4", size = 140591, upload-time = "2024-08-06T20:32:40.241Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/e8/4f648c598b17c3d06e8753d7d13d57542b30d56e6c2dedf9c331ae56312e/PyYAML-6.0.2-cp312-cp312-win_amd64.whl", hash = "sha256:7e7401d0de89a9a855c839bc697c079a4af81cf878373abd7dc625847d25cbd8", size = 156338, upload-time = "2024-08-06T20:32:41.93Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/e3/3af305b830494fa85d95f6d95ef7fa73f2ee1cc8ef5b495c7c3269fb835f/PyYAML-6.0.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:efdca5630322a10774e8e98e1af481aad470dd62c3170801852d752aa7a783ba", size = 181309, upload-time = "2024-08-06T20:32:43.4Z" },
+    { url = "https://files.pythonhosted.org/packages/45/9f/3b1c20a0b7a3200524eb0076cc027a970d320bd3a6592873c85c92a08731/PyYAML-6.0.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:50187695423ffe49e2deacb8cd10510bc361faac997de9efef88badc3bb9e2d1", size = 171679, upload-time = "2024-08-06T20:32:44.801Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/9a/337322f27005c33bcb656c655fa78325b730324c78620e8328ae28b64d0c/PyYAML-6.0.2-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0ffe8360bab4910ef1b9e87fb812d8bc0a308b0d0eef8c8f44e0254ab3b07133", size = 733428, upload-time = "2024-08-06T20:32:46.432Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/69/864fbe19e6c18ea3cc196cbe5d392175b4cf3d5d0ac1403ec3f2d237ebb5/PyYAML-6.0.2-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:17e311b6c678207928d649faa7cb0d7b4c26a0ba73d41e99c4fff6b6c3276484", size = 763361, upload-time = "2024-08-06T20:32:51.188Z" },
+    { url = "https://files.pythonhosted.org/packages/04/24/b7721e4845c2f162d26f50521b825fb061bc0a5afcf9a386840f23ea19fa/PyYAML-6.0.2-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:70b189594dbe54f75ab3a1acec5f1e3faa7e8cf2f1e08d9b561cb41b845f69d5", size = 759523, upload-time = "2024-08-06T20:32:53.019Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/b2/e3234f59ba06559c6ff63c4e10baea10e5e7df868092bf9ab40e5b9c56b6/PyYAML-6.0.2-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:41e4e3953a79407c794916fa277a82531dd93aad34e29c2a514c2c0c5fe971cc", size = 726660, upload-time = "2024-08-06T20:32:54.708Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/0f/25911a9f080464c59fab9027482f822b86bf0608957a5fcc6eaac85aa515/PyYAML-6.0.2-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:68ccc6023a3400877818152ad9a1033e3db8625d899c72eacb5a668902e4d652", size = 751597, upload-time = "2024-08-06T20:32:56.985Z" },
+    { url = "https://files.pythonhosted.org/packages/14/0d/e2c3b43bbce3cf6bd97c840b46088a3031085179e596d4929729d8d68270/PyYAML-6.0.2-cp313-cp313-win32.whl", hash = "sha256:bc2fa7c6b47d6bc618dd7fb02ef6fdedb1090ec036abab80d4681424b84c1183", size = 140527, upload-time = "2024-08-06T20:33:03.001Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/de/02b54f42487e3d3c6efb3f89428677074ca7bf43aae402517bc7cca949f3/PyYAML-6.0.2-cp313-cp313-win_amd64.whl", hash = "sha256:8388ee1976c416731879ac16da0aff3f63b286ffdd57cdeb95f3f2e085687563", size = 156446, upload-time = "2024-08-06T20:33:04.33Z" },
+]
+
+[[package]]
+name = "pyyaml-env-tag"
+version = "1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pyyaml" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/eb/2e/79c822141bfd05a853236b504869ebc6b70159afc570e1d5a20641782eaa/pyyaml_env_tag-1.1.tar.gz", hash = "sha256:2eb38b75a2d21ee0475d6d97ec19c63287a7e140231e4214969d0eac923cd7ff", size = 5737, upload-time = "2025-05-13T15:24:01.64Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/11/432f32f8097b03e3cd5fe57e88efb685d964e2e5178a48ed61e841f7fdce/pyyaml_env_tag-1.1-py3-none-any.whl", hash = "sha256:17109e1a528561e32f026364712fee1264bc2ea6715120891174ed1b980d2e04", size = 4722, upload-time = "2025-05-13T15:23:59.629Z" },
+]
+
+[[package]]
+name = "requests"
+version = "2.32.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "certifi" },
+    { name = "charset-normalizer" },
+    { name = "idna" },
+    { name = "urllib3" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e1/0a/929373653770d8a0d7ea76c37de6e41f11eb07559b103b1c02cafb3f7cf8/requests-2.32.4.tar.gz", hash = "sha256:27d0316682c8a29834d3264820024b62a36942083d52caf2f14c0591336d3422", size = 135258, upload-time = "2025-06-09T16:43:07.34Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7c/e4/56027c4a6b4ae70ca9de302488c5ca95ad4a39e190093d6c1a8ace08341b/requests-2.32.4-py3-none-any.whl", hash = "sha256:27babd3cda2a6d50b30443204ee89830707d396671944c998b5975b031ac2b2c", size = 64847, upload-time = "2025-06-09T16:43:05.728Z" },
+]
+
+[[package]]
+name = "six"
+version = "1.17.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/94/e7/b2c673351809dca68a0e064b6af791aa332cf192da575fd474ed7d6f16a2/six-1.17.0.tar.gz", hash = "sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81", size = 34031, upload-time = "2024-12-04T17:35:28.174Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" },
+]
+
+[[package]]
+name = "urllib3"
+version = "2.5.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/15/22/9ee70a2574a4f4599c47dd506532914ce044817c7752a79b6a51286319bc/urllib3-2.5.0.tar.gz", hash = "sha256:3fc47733c7e419d4bc3f6b3dc2b4f890bb743906a30d56ba4a5bfa4bbff92760", size = 393185, upload-time = "2025-06-18T14:07:41.644Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a7/c2/fe1e52489ae3122415c51f387e221dd0773709bad6c6cdaa599e8a2c5185/urllib3-2.5.0-py3-none-any.whl", hash = "sha256:e6b01673c0fa6a13e374b50871808eb3bf7046c4b125b216f6bf1cc604cff0dc", size = 129795, upload-time = "2025-06-18T14:07:40.39Z" },
+]
+
+[[package]]
+name = "watchdog"
+version = "6.0.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/db/7d/7f3d619e951c88ed75c6037b246ddcf2d322812ee8ea189be89511721d54/watchdog-6.0.0.tar.gz", hash = "sha256:9ddf7c82fda3ae8e24decda1338ede66e1c99883db93711d8fb941eaa2d8c282", size = 131220, upload-time = "2024-11-01T14:07:13.037Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0c/56/90994d789c61df619bfc5ce2ecdabd5eeff564e1eb47512bd01b5e019569/watchdog-6.0.0-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:d1cdb490583ebd691c012b3d6dae011000fe42edb7a82ece80965b42abd61f26", size = 96390, upload-time = "2024-11-01T14:06:24.793Z" },
+    { url = "https://files.pythonhosted.org/packages/55/46/9a67ee697342ddf3c6daa97e3a587a56d6c4052f881ed926a849fcf7371c/watchdog-6.0.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:bc64ab3bdb6a04d69d4023b29422170b74681784ffb9463ed4870cf2f3e66112", size = 88389, upload-time = "2024-11-01T14:06:27.112Z" },
+    { url = "https://files.pythonhosted.org/packages/44/65/91b0985747c52064d8701e1075eb96f8c40a79df889e59a399453adfb882/watchdog-6.0.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:c897ac1b55c5a1461e16dae288d22bb2e412ba9807df8397a635d88f671d36c3", size = 89020, upload-time = "2024-11-01T14:06:29.876Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/24/d9be5cd6642a6aa68352ded4b4b10fb0d7889cb7f45814fb92cecd35f101/watchdog-6.0.0-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:6eb11feb5a0d452ee41f824e271ca311a09e250441c262ca2fd7ebcf2461a06c", size = 96393, upload-time = "2024-11-01T14:06:31.756Z" },
+    { url = "https://files.pythonhosted.org/packages/63/7a/6013b0d8dbc56adca7fdd4f0beed381c59f6752341b12fa0886fa7afc78b/watchdog-6.0.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:ef810fbf7b781a5a593894e4f439773830bdecb885e6880d957d5b9382a960d2", size = 88392, upload-time = "2024-11-01T14:06:32.99Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/40/b75381494851556de56281e053700e46bff5b37bf4c7267e858640af5a7f/watchdog-6.0.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:afd0fe1b2270917c5e23c2a65ce50c2a4abb63daafb0d419fde368e272a76b7c", size = 89019, upload-time = "2024-11-01T14:06:34.963Z" },
+    { url = "https://files.pythonhosted.org/packages/39/ea/3930d07dafc9e286ed356a679aa02d777c06e9bfd1164fa7c19c288a5483/watchdog-6.0.0-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:bdd4e6f14b8b18c334febb9c4425a878a2ac20efd1e0b231978e7b150f92a948", size = 96471, upload-time = "2024-11-01T14:06:37.745Z" },
+    { url = "https://files.pythonhosted.org/packages/12/87/48361531f70b1f87928b045df868a9fd4e253d9ae087fa4cf3f7113be363/watchdog-6.0.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:c7c15dda13c4eb00d6fb6fc508b3c0ed88b9d5d374056b239c4ad1611125c860", size = 88449, upload-time = "2024-11-01T14:06:39.748Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/7e/8f322f5e600812e6f9a31b75d242631068ca8f4ef0582dd3ae6e72daecc8/watchdog-6.0.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6f10cb2d5902447c7d0da897e2c6768bca89174d0c6e1e30abec5421af97a5b0", size = 89054, upload-time = "2024-11-01T14:06:41.009Z" },
+    { url = "https://files.pythonhosted.org/packages/68/98/b0345cabdce2041a01293ba483333582891a3bd5769b08eceb0d406056ef/watchdog-6.0.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:490ab2ef84f11129844c23fb14ecf30ef3d8a6abafd3754a6f75ca1e6654136c", size = 96480, upload-time = "2024-11-01T14:06:42.952Z" },
+    { url = "https://files.pythonhosted.org/packages/85/83/cdf13902c626b28eedef7ec4f10745c52aad8a8fe7eb04ed7b1f111ca20e/watchdog-6.0.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:76aae96b00ae814b181bb25b1b98076d5fc84e8a53cd8885a318b42b6d3a5134", size = 88451, upload-time = "2024-11-01T14:06:45.084Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/c4/225c87bae08c8b9ec99030cd48ae9c4eca050a59bf5c2255853e18c87b50/watchdog-6.0.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a175f755fc2279e0b7312c0035d52e27211a5bc39719dd529625b1930917345b", size = 89057, upload-time = "2024-11-01T14:06:47.324Z" },
+    { url = "https://files.pythonhosted.org/packages/30/ad/d17b5d42e28a8b91f8ed01cb949da092827afb9995d4559fd448d0472763/watchdog-6.0.0-pp310-pypy310_pp73-macosx_10_15_x86_64.whl", hash = "sha256:c7ac31a19f4545dd92fc25d200694098f42c9a8e391bc00bdd362c5736dbf881", size = 87902, upload-time = "2024-11-01T14:06:53.119Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/ca/c3649991d140ff6ab67bfc85ab42b165ead119c9e12211e08089d763ece5/watchdog-6.0.0-pp310-pypy310_pp73-macosx_11_0_arm64.whl", hash = "sha256:9513f27a1a582d9808cf21a07dae516f0fab1cf2d7683a742c498b93eedabb11", size = 88380, upload-time = "2024-11-01T14:06:55.19Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/c7/ca4bf3e518cb57a686b2feb4f55a1892fd9a3dd13f470fca14e00f80ea36/watchdog-6.0.0-py3-none-manylinux2014_aarch64.whl", hash = "sha256:7607498efa04a3542ae3e05e64da8202e58159aa1fa4acddf7678d34a35d4f13", size = 79079, upload-time = "2024-11-01T14:06:59.472Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/51/d46dc9332f9a647593c947b4b88e2381c8dfc0942d15b8edc0310fa4abb1/watchdog-6.0.0-py3-none-manylinux2014_armv7l.whl", hash = "sha256:9041567ee8953024c83343288ccc458fd0a2d811d6a0fd68c4c22609e3490379", size = 79078, upload-time = "2024-11-01T14:07:01.431Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/57/04edbf5e169cd318d5f07b4766fee38e825d64b6913ca157ca32d1a42267/watchdog-6.0.0-py3-none-manylinux2014_i686.whl", hash = "sha256:82dc3e3143c7e38ec49d61af98d6558288c415eac98486a5c581726e0737c00e", size = 79076, upload-time = "2024-11-01T14:07:02.568Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/cc/da8422b300e13cb187d2203f20b9253e91058aaf7db65b74142013478e66/watchdog-6.0.0-py3-none-manylinux2014_ppc64.whl", hash = "sha256:212ac9b8bf1161dc91bd09c048048a95ca3a4c4f5e5d4a7d1b1a7d5752a7f96f", size = 79077, upload-time = "2024-11-01T14:07:03.893Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/3b/b8964e04ae1a025c44ba8e4291f86e97fac443bca31de8bd98d3263d2fcf/watchdog-6.0.0-py3-none-manylinux2014_ppc64le.whl", hash = "sha256:e3df4cbb9a450c6d49318f6d14f4bbc80d763fa587ba46ec86f99f9e6876bb26", size = 79078, upload-time = "2024-11-01T14:07:05.189Z" },
+    { url = "https://files.pythonhosted.org/packages/62/ae/a696eb424bedff7407801c257d4b1afda455fe40821a2be430e173660e81/watchdog-6.0.0-py3-none-manylinux2014_s390x.whl", hash = "sha256:2cce7cfc2008eb51feb6aab51251fd79b85d9894e98ba847408f662b3395ca3c", size = 79077, upload-time = "2024-11-01T14:07:06.376Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/e8/dbf020b4d98251a9860752a094d09a65e1b436ad181faf929983f697048f/watchdog-6.0.0-py3-none-manylinux2014_x86_64.whl", hash = "sha256:20ffe5b202af80ab4266dcd3e91aae72bf2da48c0d33bdb15c66658e685e94e2", size = 79078, upload-time = "2024-11-01T14:07:07.547Z" },
+    { url = "https://files.pythonhosted.org/packages/07/f6/d0e5b343768e8bcb4cda79f0f2f55051bf26177ecd5651f84c07567461cf/watchdog-6.0.0-py3-none-win32.whl", hash = "sha256:07df1fdd701c5d4c8e55ef6cf55b8f0120fe1aef7ef39a1c6fc6bc2e606d517a", size = 79065, upload-time = "2024-11-01T14:07:09.525Z" },
+    { url = "https://files.pythonhosted.org/packages/db/d9/c495884c6e548fce18a8f40568ff120bc3a4b7b99813081c8ac0c936fa64/watchdog-6.0.0-py3-none-win_amd64.whl", hash = "sha256:cbafb470cf848d93b5d013e2ecb245d4aa1c8fd0504e863ccefa32445359d680", size = 79070, upload-time = "2024-11-01T14:07:10.686Z" },
+    { url = "https://files.pythonhosted.org/packages/33/e8/e40370e6d74ddba47f002a32919d91310d6074130fe4e17dabcafc15cbf1/watchdog-6.0.0-py3-none-win_ia64.whl", hash = "sha256:a1914259fa9e1454315171103c6a30961236f508b9b623eae470268bbcc6a22f", size = 79067, upload-time = "2024-11-01T14:07:11.845Z" },
+]

docs/wiki/Application-Issues.md

@@ -0,0 +1,95 @@
+### Electron applications
+
+Electron-based applications can run directly on Wayland, but it's not the default.
+
+For Electron > 28, you can set an environment variable:
+```kdl
+environment {
+    ELECTRON_OZONE_PLATFORM_HINT "auto"
+}
+```
+
+For previous versions, you need to pass command-line flags to the target application:
+```
+--enable-features=UseOzonePlatform --ozone-platform-hint=auto
+```
+
+If the application has a [desktop entry](https://specifications.freedesktop.org/menu-spec/latest/menu-add-example.html), you can put the command-line arguments into the `Exec` section.
+
+### VSCode
+
+If you're having issues with some VSCode hotkeys, try starting `Xwayland` and setting the `DISPLAY=:0` environment variable for VSCode.
+That is, still running VSCode with the Wayland backend, but with `DISPLAY` set to a running Xwayland instance.
+Apparently, VSCode currently unconditionally queries the X server for a keymap.
+
+### WezTerm
+
+> [!NOTE]
+> Both of these issues seem to be fixed in the nightly build of WezTerm.
+
+There's [a bug](https://github.com/wezterm/wezterm/issues/4708) in WezTerm that it waits for a zero-sized Wayland configure event, so its window never shows up in niri. To work around it, put this window rule in the niri config (included in the default config):
+
+```kdl
+window-rule {
+    match app-id=r#"^org\.wezfurlong\.wezterm$"#
+    default-column-width {}
+}
+```
+
+This empty default column width lets WezTerm pick its own initial width which makes it show up properly.
+
+There's [another bug](https://github.com/wezterm/wezterm/issues/6472) in WezTerm that causes it to choose a wrong size when it's in a tiled state, and prevent resizing it.
+Niri puts windows in the tiled state with [`prefer-no-csd`](./Configuration:-Miscellaneous.md#prefer-no-csd).
+So if you hit this problem, comment out `prefer-no-csd` in the niri config and restart WezTerm.
+
+### Ghidra
+
+Some Java apps like Ghidra can show up blank under xwayland-satellite.
+To fix this, run them with the `_JAVA_AWT_WM_NONREPARENTING=1` environment variable.
+
+### rofi-wayland
+
+There's a bug in rofi-wayland that prevents it from accepting keyboard input on niri with errors in the output.
+It's been fixed in rofi, but [the fix had not been released yet](https://github.com/davatorium/rofi/discussions/2008).
+
+### Zen Browser
+
+For some reason, DMABUF screencasts are disabled in the Zen Browser, so screencasting doesn't work out of the box on niri.
+To fix it, open `about:config` and set `widget.dmabuf.force-enabled` to `true`.
+
+### Fullscreen games
+
+Some video games, both Linux-native and on Wine, have various issues when using non-stacking desktop environments.
+Most of these can be avoided with Valve's [gamescope](https://github.com/ValveSoftware/gamescope), for example:
+
+```sh
+gamescope -f -w 1920 -h 1080 -W 1920 -H 1080 --force-grab-cursor --backend sdl -- <game>
+```
+
+This command will run *<game>* in 1080p fullscreen—make sure to replace the width and height values to match your desired resolution.
+`--force-grab-cursor` forces gamescope to use relative mouse movement which prevents the cursor from escaping the game's window on multi-monitor setups.
+Note that `--backend sdl` is currently also required as gamescope's default Wayland backend doesn't lock the cursor properly (possibly related to https://github.com/ValveSoftware/gamescope/issues/1711).
+
+Steam users should use gamescope through a game's [launch options](https://help.steampowered.com/en/faqs/view/7D01-D2DD-D75E-2955) by replacing the game executable with `%command%`.
+Other game launchers such as [Lutris](https://lutris.net/) have their own ways of setting gamescope options.
+
+Running X11-based games with this method doesn't require Xwayland as gamescope creates its own Xwayland server.
+You can run Wayland-native games as well by passing `--expose-wayland` to gamescope, therefore eliminating X11 from the equation.
+
+### Steam
+
+On some systems, Steam will show a fully black window.
+To fix this, navigate to Settings -> Interface (via Steam's tray icon, or by blindly finding the Steam menu at the top left of the window), then **disable** GPU accelerated rendering in web views.
+Restart Steam and it should now work fine.
+
+If you do not want to disable GPU accelerated rendering you can instead try to pass the launch argument `-system-composer` instead.
+
+Steam notifications don't run through the standard notification daemon and show up as floating windows in the center of the screen.
+You can move them to a more convenient location by adding a window rule in your niri config:
+
+```kdl
+window-rule {
+    match app-id="steam" title=r#"^notificationtoasts_\d+_desktop$"#
+    default-floating-position x=10 y=10 relative-to="bottom-right"
+}
+```

docs/wiki/Configuration:-Animations.md

@@ -0,0 +1,412 @@
+### Overview
+
+Niri has several animations which you can configure in the same way.
+Additionally, you can disable or slow down all animations at once.
+
+Here's a quick glance at the available animations with their default values.
+
+```kdl
+animations {
+    // Uncomment to turn off all animations.
+    // You can also put "off" into each individual animation to disable it.
+    // off
+
+    // Slow down all animations by this factor. Values below 1 speed them up instead.
+    // slowdown 3.0
+
+    // Individual animations.
+
+    workspace-switch {
+        spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
+    }
+
+    window-open {
+        duration-ms 150
+        curve "ease-out-expo"
+    }
+
+    window-close {
+        duration-ms 150
+        curve "ease-out-quad"
+    }
+
+    horizontal-view-movement {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+
+    window-movement {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+
+    window-resize {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+
+    config-notification-open-close {
+        spring damping-ratio=0.6 stiffness=1000 epsilon=0.001
+    }
+
+    screenshot-ui-open {
+        duration-ms 200
+        curve "ease-out-quad"
+    }
+
+    overview-open-close {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+}
+```
+
+### Animation Types
+
+There are two animation types: easing and spring.
+Each animation can be either an easing or a spring.
+
+#### Easing
+
+This is a relatively common animation type that changes the value over a set duration using an interpolation curve.
+
+To use this animation, set the following parameters:
+
+- `duration-ms`: duration of the animation in milliseconds.
+- `curve`: the easing curve to use.
+
+```kdl
+animations {
+    window-open {
+        duration-ms 150
+        curve "ease-out-expo"
+    }
+}
+```
+
+Currently, niri only supports four curves:
+
+- `ease-out-quad` <sup>Since: 0.1.5</sup>
+- `ease-out-cubic`
+- `ease-out-expo`
+- `linear` <sup>Since: 0.1.6</sup>
+
+You can get a feel for them on pages like [easings.net](https://easings.net/).
+
+#### Spring
+
+Spring animations use a model of a physical spring to animate the value.
+They notably feel better with touchpad gestures, because they take into account the velocity of your fingers as you release the swipe.
+Springs can also oscillate / bounce at the end with the right parameters if you like that sort of thing, but they don't have to (and by default they mostly don't).
+
+Due to springs using a physical model, the animation parameters are less obvious and generally should be tuned with trial and error.
+Notably, you cannot directly set the duration.
+You can use the [Elastic](https://flathub.org/apps/app.drey.Elastic) app to help visualize how the spring parameters change the animation.
+
+A spring animation is configured like this, with three mandatory parameters:
+
+```kdl
+animations {
+    workspace-switch {
+        spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
+    }
+}
+```
+
+The `damping-ratio` goes from 0.1 to 10.0 and has the following properties:
+
+- below 1.0: underdamped spring, will oscillate in the end.
+- above 1.0: overdamped spring, won't oscillate.
+- 1.0: critically damped spring, comes to rest in minimum possible time without oscillations.
+
+However, even with damping ratio = 1.0, the spring animation may oscillate if "launched" with enough velocity from a touchpad swipe.
+
+> [!WARNING]
+> Overdamped springs currently have some numerical stability issues and may cause graphical glitches.
+> Therefore, setting `damping-ratio` above `1.0` is not recommended.
+
+Lower `stiffness` will result in a slower animation more prone to oscillation.
+
+Set `epsilon` to a lower value if the animation "jumps" at the end.
+
+> [!TIP]
+> The spring *mass* (which you can see in Elastic) is hardcoded to 1.0 and cannot be changed.
+> Instead, change `stiffness` proportionally.
+> E.g. increasing mass by 2× is the same as decreasing stiffness by 2×.
+
+### Animations
+
+Now let's go into more detail on the animations that you can configure.
+
+#### `workspace-switch`
+
+Animation when switching workspaces up and down, including after the vertical touchpad gesture (a spring is recommended).
+
+```kdl
+animations {
+    workspace-switch {
+        spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
+    }
+}
+```
+
+#### `window-open`
+
+Window opening animation.
+
+This one uses an easing type by default.
+
+```kdl
+animations {
+    window-open {
+        duration-ms 150
+        curve "ease-out-expo"
+    }
+}
+```
+
+##### `custom-shader`
+
+<sup>Since: 0.1.6</sup>
+
+You can write a custom shader for drawing the window during an open animation.
+
+See [this example shader](./examples/open_custom_shader.frag) for a full documentation with several animations to experiment with.
+
+If a custom shader fails to compile, niri will print a warning and fall back to the default, or previous successfully compiled shader.
+When running niri as a systemd service, you can see the warnings in the journal: `journalctl -ef /usr/bin/niri`
+
+> [!WARNING]
+>
+> Custom shaders do not have a backwards compatibility guarantee.
+> I may need to change their interface as I'm developing new features.
+
+Example: open will fill the current geometry with a solid gradient that gradually fades in.
+
+```kdl
+animations {
+    window-open {
+        duration-ms 250
+        curve "linear"
+
+        custom-shader r"
+            vec4 open_color(vec3 coords_geo, vec3 size_geo) {
+                vec4 color = vec4(0.0);
+
+                if (0.0 <= coords_geo.x && coords_geo.x <= 1.0
+                        && 0.0 <= coords_geo.y && coords_geo.y <= 1.0)
+                {
+                    vec4 from = vec4(1.0, 0.0, 0.0, 1.0);
+                    vec4 to = vec4(0.0, 1.0, 0.0, 1.0);
+                    color = mix(from, to, coords_geo.y);
+                }
+
+                return color * niri_clamped_progress;
+            }
+        "
+    }
+}
+```
+
+#### `window-close`
+
+<sup>Since: 0.1.5</sup>
+
+Window closing animation.
+
+This one uses an easing type by default.
+
+```kdl
+animations {
+    window-close {
+        duration-ms 150
+        curve "ease-out-quad"
+    }
+}
+```
+
+##### `custom-shader`
+
+<sup>Since: 0.1.6</sup>
+
+You can write a custom shader for drawing the window during a close animation.
+
+See [this example shader](./examples/close_custom_shader.frag) for a full documentation with several animations to experiment with.
+
+If a custom shader fails to compile, niri will print a warning and fall back to the default, or previous successfully compiled shader.
+When running niri as a systemd service, you can see the warnings in the journal: `journalctl -ef /usr/bin/niri`
+
+> [!WARNING]
+>
+> Custom shaders do not have a backwards compatibility guarantee.
+> I may need to change their interface as I'm developing new features.
+
+Example: close will fill the current geometry with a solid gradient that gradually fades away.
+
+```kdl
+animations {
+    window-close {
+        custom-shader r"
+            vec4 close_color(vec3 coords_geo, vec3 size_geo) {
+                vec4 color = vec4(0.0);
+
+                if (0.0 <= coords_geo.x && coords_geo.x <= 1.0
+                        && 0.0 <= coords_geo.y && coords_geo.y <= 1.0)
+                {
+                    vec4 from = vec4(1.0, 0.0, 0.0, 1.0);
+                    vec4 to = vec4(0.0, 1.0, 0.0, 1.0);
+                    color = mix(from, to, coords_geo.y);
+                }
+
+                return color * (1.0 - niri_clamped_progress);
+            }
+        "
+    }
+}
+```
+
+#### `horizontal-view-movement`
+
+All horizontal camera view movement animations, such as:
+
+- When a window off-screen is focused and the camera scrolls to it.
+- When a new window appears off-screen and the camera scrolls to it.
+- After a horizontal touchpad gesture (a spring is recommended).
+
+```kdl
+animations {
+    horizontal-view-movement {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+}
+```
+
+#### `window-movement`
+
+<sup>Since: 0.1.5</sup>
+
+Movement of individual windows within a workspace.
+
+Includes:
+
+- Moving window columns with `move-column-left` and `move-column-right`.
+- Moving windows inside a column with `move-window-up` and `move-window-down`.
+- Moving windows out of the way upon window opening and closing.
+- Window movement between columns when consuming/expelling.
+
+This animation *does not* include the camera view movement, such as scrolling the workspace left and right.
+
+```kdl
+animations {
+    window-movement {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+}
+```
+
+#### `window-resize`
+
+<sup>Since: 0.1.5</sup>
+
+Window resize animation.
+
+Only manual window resizes are animated, i.e. when you resize the window with `switch-preset-column-width` or `maximize-column`.
+Also, very small resizes (up to 10 pixels) are not animated.
+
+```kdl
+animations {
+    window-resize {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+}
+```
+
+##### `custom-shader`
+
+<sup>Since: 0.1.6</sup>
+
+You can write a custom shader for drawing the window during a resize animation.
+
+See [this example shader](./examples/resize_custom_shader.frag) for a full documentation with several animations to experiment with.
+
+If a custom shader fails to compile, niri will print a warning and fall back to the default, or previous successfully compiled shader.
+When running niri as a systemd service, you can see the warnings in the journal: `journalctl -ef /usr/bin/niri`
+
+> [!WARNING]
+>
+> Custom shaders do not have a backwards compatibility guarantee.
+> I may need to change their interface as I'm developing new features.
+
+Example: resize will show the next (after resize) window texture right away, stretched to the current geometry.
+
+```kdl
+animations {
+    window-resize {
+        custom-shader r"
+            vec4 resize_color(vec3 coords_curr_geo, vec3 size_curr_geo) {
+                vec3 coords_tex_next = niri_geo_to_tex_next * coords_curr_geo;
+                vec4 color = texture2D(niri_tex_next, coords_tex_next.st);
+                return color;
+            }
+        "
+    }
+}
+```
+
+#### `config-notification-open-close`
+
+The open/close animation of the config parse error and new default config notifications.
+
+This one uses an underdamped spring by default (`damping-ratio=0.6`) which causes a slight oscillation in the end.
+
+```kdl
+animations {
+    config-notification-open-close {
+        spring damping-ratio=0.6 stiffness=1000 epsilon=0.001
+    }
+}
+```
+
+#### `screenshot-ui-open`
+
+<sup>Since: 0.1.8</sup>
+
+The open (fade-in) animation of the screenshot UI.
+
+```kdl
+animations {
+    screenshot-ui-open {
+        duration-ms 200
+        curve "ease-out-quad"
+    }
+}
+```
+
+#### `overview-open-close`
+
+<sup>Since: 25.05</sup>
+
+The open/close zoom animation of the [Overview](./Overview.md).
+
+```kdl
+animations {
+    overview-open-close {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+}
+```
+
+### Synchronized Animations
+
+<sup>Since: 0.1.5</sup>
+
+Sometimes, when two animations are meant to play together synchronized, niri will drive them both with the same configuration.
+
+For example, if a window resize causes the view to move, then that view movement animation will also use the `window-resize` configuration (rather than the `horizontal-view-movement` configuration).
+This is especially important for animated resizes to look good when using `center-focused-column "always"`.
+
+As another example, resizing a window in a column vertically causes other windows to move up or down into their new position.
+This movement will use the `window-resize` configuration, rather than the `window-movement` configuration, to keep the animations synchronized.
+
+A few actions are still missing this synchronization logic, since in some cases it is difficult to implement properly.
+Therefore, for the best results, consider using the same parameters for related animations (they are all the same by default):
+
+- `horizontal-view-movement`
+- `window-movement`
+- `window-resize`

docs/wiki/Configuration:-Debug-Options.md

@@ -0,0 +1,353 @@
+### Overview
+
+Niri has several options that are only useful for debugging, or are experimental and have known issues.
+They are not meant for normal use.
+
+> [!CAUTION]
+> These options are **not** covered by the [config breaking change policy](./Configuration:-Introduction.md#breaking-change-policy).
+> They can change or stop working at any point with little notice.
+
+Here are all the options at a glance:
+
+```kdl
+debug {
+    preview-render "screencast"
+    // preview-render "screen-capture"
+    enable-overlay-planes
+    disable-cursor-plane
+    disable-direct-scanout
+    restrict-primary-scanout-to-matching-format
+    render-drm-device "/dev/dri/renderD129"
+    force-pipewire-invalid-modifier
+    dbus-interfaces-in-non-session-instances
+    wait-for-frame-completion-before-queueing
+    emulate-zero-presentation-time
+    disable-resize-throttling
+    disable-transactions
+    keep-laptop-panel-on-when-lid-is-closed
+    disable-monitor-names
+    strict-new-window-focus-policy
+    honor-xdg-activation-with-invalid-serial
+    skip-cursor-only-updates-during-vrr
+    deactivate-unfocused-windows
+    keep-max-bpc-unchanged
+}
+
+binds {
+    Mod+Shift+Ctrl+T { toggle-debug-tint; }
+    Mod+Shift+Ctrl+O { debug-toggle-opaque-regions; }
+    Mod+Shift+Ctrl+D { debug-toggle-damage; }
+}
+```
+
+### `preview-render`
+
+Make niri render the monitors the same way as for a screencast or a screen capture.
+
+Useful for previewing the `block-out-from` window rule.
+
+```kdl
+debug {
+    preview-render "screencast"
+    // preview-render "screen-capture"
+}
+```
+
+### `enable-overlay-planes`
+
+Enable direct scanout into overlay planes.
+May cause frame drops during some animations on some hardware (which is why it is not the default).
+
+Direct scanout into the primary plane is always enabled.
+
+```kdl
+debug {
+    enable-overlay-planes
+}
+```
+
+### `disable-cursor-plane`
+
+Disable the use of the cursor plane.
+The cursor will be rendered together with the rest of the frame.
+
+Useful to work around driver bugs on specific hardware.
+
+```kdl
+debug {
+    disable-cursor-plane
+}
+```
+
+### `disable-direct-scanout`
+
+Disable direct scanout to both the primary plane and the overlay planes.
+
+```kdl
+debug {
+    disable-direct-scanout
+}
+```
+
+### `restrict-primary-scanout-to-matching-format`
+
+Restricts direct scanout to the primary plane to when the window buffer exactly matches the composition swapchain format.
+
+This flag may prevent unexpected bandwidth changes when going between composition and scanout.
+The plan is to make it default in the future, when we implement a way to tell the clients the composition swapchain format.
+As is, it may prevent some clients (mpv on my machine) from scanning out to the primary plane.
+
+```kdl
+debug {
+    restrict-primary-scanout-to-matching-format
+}
+```
+
+### `render-drm-device`
+
+Override the DRM device that niri will use for all rendering.
+
+You can set this to make niri use a different primary GPU than the default one.
+
+```kdl
+debug {
+    render-drm-device "/dev/dri/renderD129"
+}
+```
+
+### `force-pipewire-invalid-modifier`
+
+<sup>Since: 25.01</sup>
+
+Forces PipeWire screencasting to use the invalid modifier, even when DRM offers more modifiers.
+
+Useful for testing the invalid modifier code path that is hit by drivers that don't support modifiers.
+
+```kdl
+debug {
+    force-pipewire-invalid-modifier
+}
+```
+
+### `dbus-interfaces-in-non-session-instances`
+
+Make niri create its D-Bus interfaces even if it's not running as a `--session`.
+
+Useful for testing screencasting changes without having to relogin.
+
+The main niri instance will *not* currently take back the interfaces when you close the test instance, so you will need to relogin in the end to make screencasting work again.
+
+```kdl
+debug {
+    dbus-interfaces-in-non-session-instances
+}
+```
+
+### `wait-for-frame-completion-before-queueing`
+
+Wait until every frame is done rendering before handing it over to DRM.
+
+Useful for diagnosing certain synchronization and performance problems.
+
+```kdl
+debug {
+    wait-for-frame-completion-before-queueing
+}
+```
+
+### `emulate-zero-presentation-time`
+
+Emulate zero (unknown) presentation time returned from DRM.
+
+This is a thing on NVIDIA proprietary drivers, so this flag can be used to test that niri doesn't break too hard on those systems.
+
+```kdl
+debug {
+    emulate-zero-presentation-time
+}
+```
+
+### `disable-resize-throttling`
+
+<sup>Since: 0.1.9</sup>
+
+Disable throttling resize events sent to windows.
+
+By default, when resizing quickly (e.g. interactively), a window will only receive the next size once it has made a commit for the previously requested size.
+This is required for resize transactions to work properly, and it also helps certain clients which don't batch incoming resizes from the compositor.
+
+Disabling resize throttling will send resizes to windows as fast as possible, which is potentially very fast (for example, on a 1000 Hz mouse).
+
+```kdl
+debug {
+    disable-resize-throttling
+}
+```
+
+### `disable-transactions`
+
+<sup>Since: 0.1.9</sup>
+
+Disable transactions (resize and close).
+
+By default, windows which must resize together, do resize together.
+For example, all windows in a column must resize at the same time to maintain the combined column height equal to the screen height, and to maintain the same window width.
+
+Transactions make niri wait until all windows finish resizing before showing them all on screen in one, synchronized frame.
+For them to work properly, resize throttling shouldn't be disabled (with the previous debug flag).
+
+```kdl
+debug {
+    disable-transactions
+}
+```
+
+### `keep-laptop-panel-on-when-lid-is-closed`
+
+<sup>Since: 0.1.10</sup>
+
+By default, niri will disable the internal laptop monitor when the laptop lid is closed.
+This flag turns off this behavior and will leave the internal laptop monitor on.
+
+```kdl
+debug {
+    keep-laptop-panel-on-when-lid-is-closed
+}
+```
+
+### `disable-monitor-names`
+
+<sup>Since: 0.1.10</sup>
+
+Disables the make/model/serial monitor names, as if niri fails to read them from the EDID.
+
+Use this flag to work around a crash present in 0.1.9 and 0.1.10 when connecting two monitors with matching make/model/serial.
+
+```kdl
+debug {
+    disable-monitor-names
+}
+```
+
+### `strict-new-window-focus-policy`
+
+<sup>Since: 25.01</sup>
+
+Disables heuristic automatic focusing for new windows.
+Only windows that activate themselves with a valid xdg-activation token will be focused.
+
+```kdl
+debug {
+    strict-new-window-focus-policy
+}
+```
+
+### `honor-xdg-activation-with-invalid-serial`
+
+<sup>Since: 25.05</sup>
+
+Widely-used clients such as Discord and Telegram make fresh xdg-activation tokens upon clicking on their tray icon or on their notification.
+Most of the time, these fresh tokens will have invalid serials, because the app needs to be focused to get a valid serial, and if the user clicks on a tray icon or a notification, it is usually because the app *isn't* focused, and the user wants to focus it.
+
+By default, niri ignores xdg-activation tokens with invalid serials, to prevent windows from randomly stealing focus.
+This debug flag makes niri honor such tokens, making the aforementioned widely-used apps get focus when clicking on their tray icon or notification.
+
+Amusingly, clicking on a notification sends the app a perfectly valid activation token from the notification daemon, but these apps seem to simply ignore it.
+Maybe in the future these apps/toolkits (Electron, Qt) are fixed, making this debug flag unnecessary.
+
+```kdl
+debug {
+    honor-xdg-activation-with-invalid-serial
+}
+```
+
+### `skip-cursor-only-updates-during-vrr`
+
+<sup>Since: next release</sup>
+
+Skips redrawing the screen from cursor input while variable refresh rate is active.
+
+Useful for games where the cursor isn't drawn internally to prevent erratic VRR shifts in response to cursor movement.
+
+Note that the current implementation has some issues, for example when there's nothing redrawing the screen (like a game), the rendering will appear to completely freeze (since cursor movements won't cause redraws).
+
+```kdl
+debug {
+    skip-cursor-only-updates-during-vrr
+}
+```
+
+### `deactivate-unfocused-windows`
+
+<sup>Since: next release</sup>
+
+Some clients (notably, Chromium- and Electron-based, like Teams or Slack) erroneously use the Activated xdg window state instead of keyboard focus for things like deciding whether to send notifications for new messages, or for picking where to show an IME popup.
+Niri keeps the Activated state on unfocused workspaces and invisible tabbed windows (to reduce unwanted animations), surfacing bugs in these applications.
+
+Set this debug flag to work around these problems.
+It will cause niri to drop the Activated state for all unfocused windows.
+
+```kdl
+debug {
+    deactivate-unfocused-windows
+}
+```
+
+### `keep-max-bpc-unchanged`
+
+<sup>Since: next release</sup>
+
+When connecting monitors, niri sets their max bpc to 8 in order to reduce display bandwidth and to potentially allow more monitors to be connected at once.
+Restricting bpc to 8 is not a problem since we don't support HDR or color management yet and can't really make use of higher bpc.
+
+Apparently, setting max bpc to 8 breaks some displays driven by AMDGPU.
+If this happens to you, set this debug flag, which will prevent niri from changing max bpc.
+AMDGPU bug report: https://gitlab.freedesktop.org/drm/amd/-/issues/4487.
+
+```kdl
+debug {
+    keep-max-bpc-unchanged
+}
+```
+
+### Key Bindings
+
+These are not debug options, but rather key bindings.
+
+#### `toggle-debug-tint`
+
+Tints all surfaces green, unless they are being directly scanned out.
+
+Useful to check if direct scanout is working.
+
+```kdl
+binds {
+    Mod+Shift+Ctrl+T { toggle-debug-tint; }
+}
+```
+
+#### `debug-toggle-opaque-regions`
+
+<sup>Since: 0.1.6</sup>
+
+Tints regions marked as opaque with blue and the rest of the render elements with red.
+
+Useful to check how Wayland surfaces and internal render elements mark their parts as opaque, which is a rendering performance optimization.
+
+```kdl
+binds {
+    Mod+Shift+Ctrl+O { debug-toggle-opaque-regions; }
+}
+```
+
+#### `debug-toggle-damage`
+
+<sup>Since: 0.1.6</sup>
+
+Tints damaged regions with red.
+
+```kdl
+binds {
+    Mod+Shift+Ctrl+D { debug-toggle-damage; }
+}
+```

docs/wiki/Configuration:-Gestures.md

@@ -0,0 +1,96 @@
+### Overview
+
+<sup>Since: 25.02</sup>
+
+The `gestures` config section contains gesture settings.
+For an overview of all niri gestures, see the [Gestures](./Gestures.md) wiki page.
+
+Here's a quick glance at the available settings along with their default values.
+
+```kdl
+gestures {
+    dnd-edge-view-scroll {
+        trigger-width 30
+        delay-ms 100
+        max-speed 1500
+    }
+
+    dnd-edge-workspace-switch {
+        trigger-height 50
+        delay-ms 100
+        max-speed 1500
+    }
+
+    hot-corners {
+        // off
+    }
+}
+```
+
+### `dnd-edge-view-scroll`
+
+Scroll the tiling view when moving the mouse cursor against a monitor edge during drag-and-drop (DnD).
+Also works on a touchscreen.
+
+This will work for regular drag-and-drop (e.g. dragging a file from a file manager), and for window interactive move when targeting the tiling layout.
+
+The options are:
+
+- `trigger-width`: size of the area near the monitor edge that will trigger the scrolling, in logical pixels.
+- `delay-ms`: delay in milliseconds before the scrolling starts.
+Avoids unwanted scrolling when dragging things across monitors.
+- `max-speed`: maximum scrolling speed in logical pixels per second.
+The scrolling speed increases linearly as you move your mouse cursor from `trigger-width` to the very edge of the monitor.
+
+```kdl
+gestures {
+    // Increase the trigger area and maximum speed.
+    dnd-edge-view-scroll {
+        trigger-width 100
+        max-speed 3000
+    }
+}
+```
+
+### `dnd-edge-workspace-switch`
+
+<sup>Since: 25.05</sup>
+
+Scroll the workspaces up/down when moving the mouse cursor against a monitor edge during drag-and-drop (DnD) while in the overview.
+Also works on a touchscreen.
+
+The options are:
+
+- `trigger-height`: size of the area near the monitor edge that will trigger the scrolling, in logical pixels.
+- `delay-ms`: delay in milliseconds before the scrolling starts.
+Avoids unwanted scrolling when dragging things across monitors.
+- `max-speed`: maximum scrolling speed; 1500 corresponds to one screen height per second.
+The scrolling speed increases linearly as you move your mouse cursor from `trigger-width` to the very edge of the monitor.
+
+```kdl
+gestures {
+    // Increase the trigger area and maximum speed.
+    dnd-edge-workspace-switch {
+        trigger-height 100
+        max-speed 3000
+    }
+}
+```
+
+### `hot-corners`
+
+<sup>Since: 25.05</sup>
+
+Put your mouse at the very top-left corner of a monitor to toggle the overview.
+Also works during drag-and-dropping something.
+
+`off` disables the hot corners.
+
+```kdl
+// Disable the hot corners.
+gestures {
+    hot-corners {
+        off
+    }
+}
+```

docs/wiki/Configuration:-Input.md

@@ -0,0 +1,383 @@
+### Overview
+
+In this section you can configure input devices like keyboard and mouse, and some input-related options.
+
+There's a section for each device type: `keyboard`, `touchpad`, `mouse`, `trackpoint`, `tablet`, `touch`.
+Settings in those sections will apply to every device of that type.
+Currently, there's no way to configure specific devices individually (but that is planned).
+
+All settings at a glance:
+
+```kdl
+input {
+    keyboard {
+        xkb {
+            // layout "us"
+            // variant "colemak_dh_ortho"
+            // options "compose:ralt,ctrl:nocaps"
+            // model ""
+            // rules ""
+            // file "~/.config/keymap.xkb"
+        }
+
+        // repeat-delay 600
+        // repeat-rate 25
+        // track-layout "global"
+        numlock
+    }
+
+    touchpad {
+        // off
+        tap
+        // dwt
+        // dwtp
+        // drag false
+        // drag-lock
+        natural-scroll
+        // accel-speed 0.2
+        // accel-profile "flat"
+        // scroll-factor 1.0
+        // scroll-factor vertical=1.0 horizontal=-2.0
+        // scroll-method "two-finger"
+        // scroll-button 273
+        // scroll-button-lock
+        // tap-button-map "left-middle-right"
+        // click-method "clickfinger"
+        // left-handed
+        // disabled-on-external-mouse
+        // middle-emulation
+    }
+
+    mouse {
+        // off
+        // natural-scroll
+        // accel-speed 0.2
+        // accel-profile "flat"
+        // scroll-factor 1.0
+        // scroll-factor vertical=1.0 horizontal=-2.0
+        // scroll-method "no-scroll"
+        // scroll-button 273
+        // scroll-button-lock
+        // left-handed
+        // middle-emulation
+    }
+
+    trackpoint {
+        // off
+        // natural-scroll
+        // accel-speed 0.2
+        // accel-profile "flat"
+        // scroll-method "on-button-down"
+        // scroll-button 273
+        // scroll-button-lock
+        // left-handed
+        // middle-emulation
+    }
+
+    trackball {
+        // off
+        // natural-scroll
+        // accel-speed 0.2
+        // accel-profile "flat"
+        // scroll-method "on-button-down"
+        // scroll-button 273
+        // scroll-button-lock
+        // left-handed
+        // middle-emulation
+    }
+
+    tablet {
+        // off
+        map-to-output "eDP-1"
+        // left-handed
+        // calibration-matrix 1.0 0.0 0.0 0.0 1.0 0.0
+    }
+
+    touch {
+        // off
+        map-to-output "eDP-1"
+    }
+
+    // disable-power-key-handling
+    // warp-mouse-to-focus
+    // focus-follows-mouse max-scroll-amount="0%"
+    // workspace-auto-back-and-forth
+
+    // mod-key "Super"
+    // mod-key-nested "Alt"
+}
+```
+
+### Keyboard
+
+#### Layout
+
+In the `xkb` section, you can set layout, variant, options, model and rules.
+These are passed directly to libxkbcommon, which is also used by most other Wayland compositors.
+See the `xkeyboard-config(7)` manual for more information.
+
+```kdl
+input {
+    keyboard {
+        xkb {
+            layout "us"
+            variant "colemak_dh_ortho"
+            options "compose:ralt,ctrl:nocaps"
+        }
+    }
+}
+```
+
+> [!TIP]
+>
+> <sup>Since: 25.02</sup>
+>
+> Alternatively, you can directly set a path to a .xkb file containing an xkb keymap.
+> This overrides all other xkb settings.
+>
+> ```kdl
+> input {
+>     keyboard {
+>         xkb {
+>             file "~/.config/keymap.xkb"
+>         }
+>     }
+> }
+> ```
+
+> [!NOTE]
+>
+> <sup>Since: next release</sup>
+>
+> If the `xkb` section is empty (like it is by default), niri will fetch xkb settings from systemd-localed at `org.freedesktop.locale1` over D-Bus.
+> This way, for example, system installers can dynamically set the niri keyboard layout.
+> You can see this layout in `localectl` and change it with `localectl set-x11-keymap`, for example:
+>
+> ```sh
+> $ localectl set-x11-keymap "us" "" "colemak_dh_ortho" "compose:ralt,ctrl:nocaps"
+> $ localectl
+> System Locale: LANG=en_US.UTF-8
+>                LC_NUMERIC=ru_RU.UTF-8
+>                LC_TIME=ru_RU.UTF-8
+>                LC_MONETARY=ru_RU.UTF-8
+>                LC_PAPER=ru_RU.UTF-8
+>                LC_MEASUREMENT=ru_RU.UTF-8
+>     VC Keymap: us-colemak_dh_ortho
+>    X11 Layout: us
+>   X11 Variant: colemak_dh_ortho
+>   X11 Options: compose:ralt,ctrl:nocaps
+> ```
+>
+> By default, `localectl` will set the TTY keymap to the closest match of the XKB keymap.
+> You can prevent that with a `--no-convert` flag, for example: `localectl set-x11-keymap --no-convert "us,ru"`.
+>
+> These settings are picked up by some other programs too, like GDM.
+
+When using multiple layouts, niri can remember the current layout globally (the default) or per-window.
+You can control this with the `track-layout` option.
+
+- `global`: layout change is global for all windows.
+- `window`: layout is tracked for each window individually.
+
+```kdl
+input {
+    keyboard {
+        track-layout "global"
+    }
+}
+```
+
+#### Repeat
+
+Delay is in milliseconds before the keyboard repeat starts.
+Rate is in characters per second.
+
+```kdl
+input {
+    keyboard {
+        repeat-delay 600
+        repeat-rate 25
+    }
+}
+```
+
+#### Num Lock
+
+<sup>Since: 25.05</sup>
+
+Set the `numlock` flag to turn on Num Lock automatically at startup.
+
+You might want to disable (comment out) `numlock` if you're using a laptop with a keyboard that overlays Num Lock keys on top of regular keys.
+
+```kdl
+input {
+    keyboard {
+        numlock
+    }
+}
+```
+
+### Pointing Devices
+
+Most settings for the pointing devices are passed directly to libinput.
+Other Wayland compositors also use libinput, so it's likely you will find the same settings there.
+For flags like `tap`, omit them or comment them out to disable the setting.
+
+A few settings are common between input devices:
+
+- `off`: if set, no events will be sent from this device.
+
+A few settings are common between `touchpad`, `mouse`, `trackpoint`, and `trackball`:
+
+- `natural-scroll`: if set, inverts the scrolling direction.
+- `accel-speed`: pointer acceleration speed, valid values are from `-1.0` to `1.0` where the default is `0.0`.
+- `accel-profile`: can be `adaptive` (the default) or `flat` (disables pointer acceleration).
+- `scroll-method`: when to generate scroll events instead of pointer motion events, can be `no-scroll`, `two-finger`, `edge`, or `on-button-down`.
+  The default and supported methods vary depending on the device type.
+- `scroll-button`: <sup>Since: 0.1.10</sup> the button code used for the `on-button-down` scroll method. You can find it in `libinput debug-events`.
+- `scroll-button-lock`: <sup>Since: next release</sup> when enabled, the button does not need to be held down. Pressing once engages scrolling, pressing a second time disengages it, and double click acts as single click of the the underlying button.
+- `left-handed`: if set, changes the device to left-handed mode.
+- `middle-emulation`: emulate a middle mouse click by pressing left and right mouse buttons at once.
+
+Settings specific to `touchpad`s:
+
+- `tap`: tap-to-click.
+- `dwt`: disable-when-typing.
+- `dwtp`: disable-when-trackpointing.
+- `drag`: <sup>Since: 25.05</sup> can be `true` or `false`, controls if tap-and-drag is enabled.
+- `drag-lock`: <sup>Since: 25.02</sup> if set, lifting the finger off for a short time while dragging will not drop the dragged item. See the [libinput documentation](https://wayland.freedesktop.org/libinput/doc/latest/tapping.html#tap-and-drag).
+- `tap-button-map`: can be `left-right-middle` or `left-middle-right`, controls which button corresponds to a two-finger tap and a three-finger tap.
+- `click-method`: can be `button-areas` or `clickfinger`, changes the [click method](https://wayland.freedesktop.org/libinput/doc/latest/clickpad-softbuttons.html).
+- `disabled-on-external-mouse`: do not send events while external pointer device is plugged in.
+
+Settings specific to `touchpad` and `mouse`:
+
+- `scroll-factor`: <sup>Since: 0.1.10</sup> scales the scrolling speed by this value.
+
+    <sup>Since: next release</sup> You can also override horizontal and vertical scroll factor separately like so: `scroll-factor horizontal=2.0 vertical=-1.0`
+
+Settings specific to `tablet`s:
+
+- `calibration-matrix`: <sup>Since: 25.02</sup> set to six floating point numbers to change the calibration matrix. See the [`LIBINPUT_CALIBRATION_MATRIX` documentation](https://wayland.freedesktop.org/libinput/doc/latest/device-configuration-via-udev.html) for examples.
+
+Tablets and touchscreens are absolute pointing devices that can be mapped to a specific output like so:
+
+```kdl
+input {
+    tablet {
+        map-to-output "eDP-1"
+    }
+
+    touch {
+        map-to-output "eDP-1"
+    }
+}
+```
+
+Valid output names are the same as the ones used for output configuration.
+
+<sup>Since: 0.1.7</sup> When a tablet is not mapped to any output, it will map to the union of all connected outputs, without aspect ratio correction.
+
+### General Settings
+
+These settings are not specific to a particular input device.
+
+#### `disable-power-key-handling`
+
+By default, niri will take over the power button to make it sleep instead of power off.
+Set this if you would like to configure the power button elsewhere (i.e. `logind.conf`).
+
+```kdl
+input {
+    disable-power-key-handling
+}
+```
+
+#### `warp-mouse-to-focus`
+
+Makes the mouse warp to newly focused windows.
+
+Does not make the cursor visible if it had been hidden.
+
+```kdl
+input {
+    warp-mouse-to-focus
+}
+```
+
+By default, the cursor warps *separately* horizontally and vertically.
+I.e. if moving the mouse only horizontally is enough to put it inside the newly focused window, then the mouse will move only horizontally, and not vertically.
+
+<sup>Since: 25.05</sup> You can customize this with the `mode` property.
+
+- `mode="center-xy"`: warps by both X and Y coordinates together.
+So if the mouse was anywhere outside the newly focused window, it will warp to the center of the window.
+- `mode="center-xy-always"`: warps by both X and Y coordinates together, even if the mouse was already somewhere inside the newly focused window.
+
+```kdl
+input {
+    warp-mouse-to-focus mode="center-xy"
+}
+```
+
+#### `focus-follows-mouse`
+
+Focuses windows and outputs automatically when moving the mouse over them.
+
+```kdl
+input {
+    focus-follows-mouse
+}
+```
+
+<sup>Since: 0.1.8</sup> You can optionally set `max-scroll-amount`.
+Then, focus-follows-mouse won't focus a window if it will result in the view scrolling more than the set amount.
+The value is a percentage of the working area width.
+
+```kdl
+input {
+    // Allow focus-follows-mouse when it results in scrolling at most 10% of the screen.
+    focus-follows-mouse max-scroll-amount="10%"
+}
+```
+
+```kdl
+input {
+    // Allow focus-follows-mouse only when it will not scroll the view.
+    focus-follows-mouse max-scroll-amount="0%"
+}
+```
+
+#### `workspace-auto-back-and-forth`
+
+Normally, switching to the same workspace by index twice will do nothing (since you're already on that workspace).
+If this flag is enabled, switching to the same workspace by index twice will switch back to the previous workspace.
+
+Niri will correctly switch to the workspace you came from, even if workspaces were reordered in the meantime.
+
+```kdl
+input {
+    workspace-auto-back-and-forth
+}
+```
+
+#### `mod-key`, `mod-key-nested`
+
+<sup>Since: 25.05</sup>
+
+Customize the `Mod` key for [key bindings](./Configuration:-Key-Bindings.md).
+Only valid modifiers are allowed, e.g. `Super`, `Alt`, `Mod3`, `Mod5`, `Ctrl`, `Shift`.
+
+By default, `Mod` is equal to `Super` when running niri on a TTY, and to `Alt` when running niri as a nested winit window.
+
+> [!NOTE]
+> There are a lot of default bindings with Mod, none of them "make it through" to the underlying window.
+> You probably don't want to set `mod-key` to Ctrl or Shift, since Ctrl is commonly used for app hotkeys, and Shift is used for, well, regular typing.
+
+```kdl
+// Switch the mod keys around: use Alt normally, and Super inside a nested window.
+input {
+    mod-key "Alt"
+    mod-key-nested "Super"
+}
+```

docs/wiki/Configuration:-Introduction.md

@@ -0,0 +1,150 @@
+### Per-Section Documentation
+
+You can find documentation for various sections of the config on these wiki pages:
+
+* [`input {}`](./Configuration:-Input.md)
+* [`output "eDP-1" {}`](./Configuration:-Outputs.md)
+* [`binds {}`](./Configuration:-Key-Bindings.md)
+* [`switch-events {}`](./Configuration:-Switch-Events.md)
+* [`layout {}`](./Configuration:-Layout.md)
+* [top-level options](./Configuration:-Miscellaneous.md)
+* [`window-rule {}`](./Configuration:-Window-Rules.md)
+* [`layer-rule {}`](./Configuration:-Layer-Rules.md)
+* [`animations {}`](./Configuration:-Animations.md)
+* [`gestures {}`](./Configuration:-Gestures.md)
+* [`debug {}`](./Configuration:-Debug-Options.md)
+
+### Loading
+
+Niri will load configuration from `$XDG_CONFIG_HOME/niri/config.kdl` or `~/.config/niri/config.kdl`, falling back to `/etc/niri/config.kdl`.
+If both of these files are missing, niri will create `$XDG_CONFIG_HOME/niri/config.kdl` with the contents of [the default configuration file](https://github.com/YaLTeR/niri/blob/main/resources/default-config.kdl), which are embedded into the niri binary at build time.
+Please use the default configuration file as the starting point for your custom configuration.
+
+The configuration is live-reloaded.
+Simply edit and save the config file, and your changes will be applied.
+This includes key bindings, output settings like mode, window rules, and everything else.
+
+You can run `niri validate` to parse the config and see any errors.
+
+To use a different config file path, pass it in the `--config` or `-c` argument to `niri`.
+
+You can also set `$NIRI_CONFIG` to the path of the config file.
+`--config` always takes precedence.
+If `--config` or `$NIRI_CONFIG` doesn't point to a real file, the config will not be loaded.
+If `$NIRI_CONFIG` is set to an empty string, it is ignored and the default config location is used instead.
+
+### Syntax
+
+The config is written in [KDL].
+
+#### Comments
+
+Lines starting with `//` are comments; they are ignored.
+
+Also, you can put `/-` in front of a section to comment out the entire section:
+
+```kdl
+/-output "eDP-1" {
+    // Everything inside here is ignored.
+    // The display won't be turned off
+    // as the whole section is commented out.
+    off
+}
+```
+
+#### Flags
+
+Toggle options in niri are commonly represented as flags.
+Writing out the flag enables it, and omitting it or commenting it out disables it.
+For example:
+
+```kdl
+// "Focus follows mouse" is enabled.
+input {
+    focus-follows-mouse
+
+    // Other settings...
+}
+```
+
+```kdl
+// "Focus follows mouse" is disabled.
+input {
+    // focus-follows-mouse
+
+    // Other settings...
+}
+```
+
+#### Sections
+
+Most sections cannot be repeated. For example:
+
+```kdl
+// This is valid: every section appears once.
+input {
+    keyboard {
+        // ...
+    }
+
+    touchpad {
+        // ...
+    }
+}
+```
+
+```kdl,must-fail
+// This is NOT valid: input section appears twice.
+input {
+    keyboard {
+        // ...
+    }
+}
+
+input {
+    touchpad {
+        // ...
+    }
+}
+```
+
+Exceptions are, for example, sections that configure different devices by name:
+
+<!-- NOTE: this may break in the future -->
+```kdl
+output "eDP-1" {
+    // ...
+}
+
+// This is valid: this section configures a different output.
+output "HDMI-A-1" {
+    // ...
+}
+
+// This is NOT valid: "eDP-1" already appeared above.
+// It will either throw a config parsing error, or otherwise not work.
+output "eDP-1" {
+    // ...
+}
+```
+
+### Defaults
+
+Omitting most of the sections of the config file will leave you with the default values for that section.
+A notable exception is [`binds {}`](./Configuration:-Key-Bindings.md): they do not get filled with defaults, so make sure you do not erase this section.
+
+### Breaking Change Policy
+
+As a rule, niri updates should not break existing config files.
+(For example, the default config from niri v0.1.0 still parses fine on v25.02 as I'm writing this.)
+
+Exceptions can be made for parsing bugs.
+For example, niri used to accept multiple binds to the same key, but this was not intended and did not do anything (the first bind was always used).
+A patch release changed niri from silently accepting this to causing a parsing failure.
+This is not a blanket rule, I will consider the potential impact of every breaking change like this before deciding to carry on with it.
+
+Keep in mind that the breaking change policy applies only to niri releases.
+Commits between releases can and do occasionally break the config as new features are ironed out.
+However, I do try to limit these, since several people are running git builds.
+
+[KDL]: https://kdl.dev/

docs/wiki/Configuration:-Key-Bindings.md

@@ -0,0 +1,407 @@
+### Overview
+
+Key bindings are declared in the `binds {}` section of the config.
+
+> [!NOTE]
+> This is one of the few sections that *does not* get automatically filled with defaults if you omit it, so make sure to copy it from the default config.
+
+Each bind is a hotkey followed by one action enclosed in curly brackets.
+For example:
+
+```kdl
+binds {
+    Mod+Left { focus-column-left; }
+    Super+Alt+L { spawn "swaylock"; }
+}
+```
+
+The hotkey consists of modifiers separated by `+` signs, followed by an XKB key name in the end.
+
+Valid modifiers are:
+
+- `Ctrl` or `Control`;
+- `Shift`;
+- `Alt`;
+- `Super` or `Win`;
+- `ISO_Level3_Shift` or `Mod5`—this is the AltGr key on certain layouts;
+- `ISO_Level5_Shift`: can be used with an xkb lv5 option like `lv5:caps_switch`;
+- `Mod`.
+
+`Mod` is a special modifier that is equal to `Super` when running niri on a TTY, and to `Alt` when running niri as a nested winit window.
+This way, you can test niri in a window without causing too many conflicts with the host compositor's key bindings.
+For this reason, most of the default keys use the `Mod` modifier.
+
+<sup>Since: 25.05</sup> You can customize the `Mod` key [in the `input` section of the config](./Configuration:-Input.md#mod-key-mod-key-nested).
+
+> [!TIP]
+> To find an XKB name for a particular key, you may use a program like [`wev`](https://git.sr.ht/~sircmpwn/wev).
+>
+> Open it from a terminal and press the key that you want to detect.
+> In the terminal, you will see output like this:
+>
+> ```
+> [14:     wl_keyboard] key: serial: 757775; time: 44940343; key: 113; state: 1 (pressed)
+>                       sym: Left         (65361), utf8: ''
+> [14:     wl_keyboard] key: serial: 757776; time: 44940432; key: 113; state: 0 (released)
+>                       sym: Left         (65361), utf8: ''
+> [14:     wl_keyboard] key: serial: 757777; time: 44940753; key: 114; state: 1 (pressed)
+>                       sym: Right        (65363), utf8: ''
+> [14:     wl_keyboard] key: serial: 757778; time: 44940846; key: 114; state: 0 (released)
+>                       sym: Right        (65363), utf8: ''
+> ```
+>
+> Here, look at `sym: Left` and `sym: Right`: these are the key names.
+> I was pressing the left and the right arrow in this example.
+>
+> Keep in mind that binding shifted keys requires spelling out Shift and the unshifted version of the key, according to your XKB layout.
+> For example, on the US QWERTY layout, <kbd>&lt;</kbd> is on <kbd>Shift</kbd> + <kbd>,</kbd>, so to bind it, you spell out something like `Mod+Shift+Comma`.
+>
+> As another example, if you've configured the French [BÉPO](https://en.wikipedia.org/wiki/B%C3%89PO) XKB layout, your <kbd>&lt;</kbd> is on <kbd>AltGr</kbd> + <kbd>«</kbd>.
+> <kbd>AltGr</kbd> is `ISO_Level3_Shift`, or equivalently `Mod5`, so to bind it, you spell out something like `Mod+Mod5+guillemotleft`.
+>
+> When resolving latin keys, niri will search for the *first* configured XKB layout that has the latin key.
+> So for example with US QWERTY and RU layouts configured, US QWERTY will be used for latin binds.
+
+<sup>Since: 0.1.8</sup> Binds will repeat by default (i.e. holding down a bind will make it trigger repeatedly).
+You can disable that for specific binds with `repeat=false`:
+
+```kdl
+binds {
+    Mod+T repeat=false { spawn "alacritty"; }
+}
+```
+
+Binds can also have a cooldown, which will rate-limit the bind and prevent it from repeatedly triggering too quickly.
+
+```kdl
+binds {
+    Mod+T cooldown-ms=500 { spawn "alacritty"; }
+}
+```
+
+This is mostly useful for the scroll bindings.
+
+### Scroll Bindings
+
+You can bind mouse wheel scroll ticks using the following syntax.
+These binds will change direction based on the `natural-scroll` setting.
+
+```kdl
+binds {
+    Mod+WheelScrollDown cooldown-ms=150 { focus-workspace-down; }
+    Mod+WheelScrollUp   cooldown-ms=150 { focus-workspace-up; }
+    Mod+WheelScrollRight                { focus-column-right; }
+    Mod+WheelScrollLeft                 { focus-column-left; }
+}
+```
+
+Similarly, you can bind touchpad scroll "ticks".
+Touchpad scrolling is continuous, so for these binds it is split into discrete intervals based on distance travelled.
+
+These binds are also affected by touchpad's `natural-scroll`, so these example binds are "inverted", since niri has `natural-scroll` enabled for touchpads by default.
+
+```kdl
+binds {
+    Mod+TouchpadScrollDown { spawn "wpctl" "set-volume" "@DEFAULT_AUDIO_SINK@" "0.02+"; }
+    Mod+TouchpadScrollUp   { spawn "wpctl" "set-volume" "@DEFAULT_AUDIO_SINK@" "0.02-"; }
+}
+```
+
+Both mouse wheel and touchpad scroll binds will prevent applications from receiving any scroll events when their modifiers are held down.
+For example, if you have a `Mod+WheelScrollDown` bind, then while holding `Mod`, all mouse wheel scrolling will be consumed by niri.
+
+### Mouse Click Bindings
+
+<sup>Since: 25.01</sup>
+
+You can bind mouse clicks using the following syntax.
+
+```kdl
+binds {
+    Mod+MouseLeft    { close-window; }
+    Mod+MouseRight   { close-window; }
+    Mod+MouseMiddle  { close-window; }
+    Mod+MouseForward { close-window; }
+    Mod+MouseBack    { close-window; }
+}
+```
+
+Mouse clicks operate on the window that was focused at the time of the click, not the window you're clicking.
+
+Note that binding `Mod+MouseLeft` or `Mod+MouseRight` will override the corresponding gesture (moving or resizing the window).
+
+### Custom Hotkey Overlay Titles
+
+<sup>Since: 25.02</sup>
+
+The hotkey overlay (the Important Hotkeys dialog) shows a hardcoded list of binds.
+You can customize this list using the `hotkey-overlay-title` property.
+
+To add a bind to the hotkey overlay, set the property to the title that you want to show:
+```kdl
+binds {
+    Mod+Shift+S hotkey-overlay-title="Toggle Dark/Light Style" { spawn "some-script.sh"; }
+}
+```
+
+Binds with custom titles are listed after the hardcoded binds and before non-customized Spawn binds.
+
+To remove a hardcoded bind from the hotkey overlay, set the property to null:
+```kdl
+binds {
+    Mod+Q hotkey-overlay-title=null { close-window; }
+}
+```
+
+> [!TIP]
+> When multiple key combinations are bound to the same action:
+> - If any of the binds has a custom hotkey overlay title, niri will show that bind.
+> - Otherwise, if any of the binds has a null title, niri will hide the bind.
+> - Otherwise, niri will show the first key combination.
+
+Custom titles support [Pango markup](https://docs.gtk.org/Pango/pango_markup.html):
+
+```kdl
+binds {
+    Mod+Shift+S hotkey-overlay-title="<b>Toggle</b> <span foreground='red'>Dark</span>/Light Style" { spawn "some-script.sh"; }
+}
+```
+
+![Custom markup example.](https://github.com/user-attachments/assets/2a2ba914-bfa7-4dfa-bb5e-49839034765d)
+
+### Actions
+
+Every action that you can bind is also available for programmatic invocation via `niri msg action`.
+Run `niri msg action` to get a full list of actions along with their short descriptions.
+
+Here are a few actions that benefit from more explanation.
+
+#### `spawn`
+
+Run a program.
+
+`spawn` accepts a path to the program binary as the first argument, followed by arguments to the program.
+For example:
+
+```kdl
+binds {
+    // Run alacritty.
+    Mod+T { spawn "alacritty"; }
+
+    // Run `wpctl set-volume @DEFAULT_AUDIO_SINK@ 0.1+`.
+    XF86AudioRaiseVolume { spawn "wpctl" "set-volume" "@DEFAULT_AUDIO_SINK@" "0.1+"; }
+}
+```
+
+> [!TIP]
+>
+> <sup>Since: 0.1.5</sup>
+>
+> Spawn bindings have a special `allow-when-locked=true` property that makes them work even while the session is locked:
+>
+> ```kdl
+> binds {
+>     // This mute bind will work even when the session is locked.
+>     XF86AudioMute allow-when-locked=true { spawn "wpctl" "set-mute" "@DEFAULT_AUDIO_SINK@" "toggle"; }
+> }
+> ```
+
+For `spawn`, niri *does not* use a shell to run commands, which means that you need to manually separate arguments.
+See [`spawn-sh`](#spawn-sh) below for an action that uses a shell.
+
+```kdl
+binds {
+    // Correct: every argument is in its own quotes.
+    Mod+T { spawn "alacritty" "-e" "/usr/bin/fish"; }
+
+    // Wrong: will interpret the whole `alacritty -e /usr/bin/fish` string as the binary path.
+    Mod+D { spawn "alacritty -e /usr/bin/fish"; }
+
+    // Wrong: will pass `-e /usr/bin/fish` as one argument, which alacritty won't understand.
+    Mod+Q { spawn "alacritty" "-e /usr/bin/fish"; }
+}
+```
+
+This also means that you cannot expand environment variables or `~`.
+If you need this, you can run the command through a shell manually.
+
+```kdl
+binds {
+    // Wrong: no shell expansion here. These strings will be passed literally to the program.
+    Mod+T { spawn "grim" "-o" "$MAIN_OUTPUT" "~/screenshot.png"; }
+
+    // Correct: run this through a shell manually so that it can expand the arguments.
+    // Note that the entire command is passed as a SINGLE argument,
+    // because shell will do its own argument splitting by whitespace.
+    Mod+D { spawn "sh" "-c" "grim -o $MAIN_OUTPUT ~/screenshot.png"; }
+
+    // You can also use a shell to run multiple commands,
+    // use pipes, process substitution, and so on.
+    Mod+Q { spawn "sh" "-c" "notify-send clipboard \"$(wl-paste)\""; }
+}
+```
+
+As a special case, niri will expand `~` to the home directory *only* at the beginning of the program name.
+
+```kdl
+binds {
+    // This will work: one ~ at the very beginning.
+    Mod+T { spawn "~/scripts/do-something.sh"; }
+}
+```
+
+#### `spawn-sh`
+
+<sup>Since: next release</sup>
+
+Run a command through the shell.
+
+The argument is a single string that is passed verbatim to `sh`.
+You can use shell variables, pipelines, `~` expansion, and everything else as expected.
+
+```kdl
+binds {
+    // Works with spawn-sh: all arguments in the same string.
+    Mod+D { spawn-sh "alacritty -e /usr/bin/fish"; }
+
+    // Works with spawn-sh: shell variable ($MAIN_OUTPUT), ~ expansion.
+    Mod+T { spawn-sh "grim -o $MAIN_OUTPUT ~/screenshot.png"; }
+
+    // Works with spawn-sh: process substitution.
+    Mod+Q { spawn-sh "notify-send clipboard \"$(wl-paste)\""; }
+
+    // Works with spawn-sh: multiple commands.
+    Super+Alt+S { spawn-sh "pkill orca || exec orca"; }
+}
+```
+
+`spawn-sh "some command"` is equivalent to `spawn "sh" "-c" "some command"`—it's just a less confusing shorthand.
+Keep in mind that going through the shell incurs a tiny performance penalty compared to directly `spawn`ing some binary.
+
+Using `sh` is hardcoded, consistent with other compositors.
+If you want a different shell, write it out using `spawn`, e.g. `spawn "fish" "-c" "some fish command"`.
+
+#### `quit`
+
+Exit niri after showing a confirmation dialog to avoid accidentally triggering it.
+
+```kdl
+binds {
+    Mod+Shift+E { quit; }
+}
+```
+
+If you want to skip the confirmation dialog, set the flag like so:
+
+```kdl
+binds {
+    Mod+Shift+E { quit skip-confirmation=true; }
+}
+```
+
+#### `do-screen-transition`
+
+<sup>Since: 0.1.6</sup>
+
+Freeze the screen for a brief moment then crossfade to the new contents.
+
+```kdl
+binds {
+    Mod+Return { do-screen-transition; }
+}
+```
+
+This action is mainly useful to trigger from scripts changing the system theme or style (between light and dark for example).
+It makes transitions like this, where windows change their style one by one, look smooth and synchronized.
+
+For example, using the GNOME color scheme setting:
+
+```shell
+niri msg action do-screen-transition
+dconf write /org/gnome/desktop/interface/color-scheme "\"prefer-dark\""
+```
+
+By default, the screen is frozen for 250 ms to give windows time to redraw, before the crossfade.
+You can set this delay like this:
+
+```kdl
+binds {
+    Mod+Return { do-screen-transition delay-ms=100; }
+}
+```
+
+Or, in scripts:
+
+```shell
+niri msg action do-screen-transition --delay-ms 100
+```
+
+#### `toggle-window-rule-opacity`
+
+<sup>Since: 25.02</sup>
+
+Toggle the opacity window rule of the focused window.
+This only has an effect if the window's opacity window rule is already set to semitransparent.
+
+```kdl
+binds {
+    Mod+O { toggle-window-rule-opacity; }
+}
+```
+
+#### `screenshot`, `screenshot-screen`, `screenshot-window`
+
+Actions for taking screenshots.
+
+- `screenshot`: opens the built-in interactive screenshot UI.
+- `screenshot-screen`, `screenshow-window`: takes a screenshot of the focused screen or window respectively.
+
+The screenshot is both stored to the clipboard and saved to disk, according to the [`screenshot-path` option](./Configuration:-Miscellaneous.md#screenshot-path).
+
+<sup>Since: 25.02</sup> You can disable saving to disk for a specific bind with the `write-to-disk=false` property:
+
+```kdl
+binds {
+    Ctrl+Print { screenshot-screen write-to-disk=false; }
+    Alt+Print { screenshot-window write-to-disk=false; }
+}
+```
+
+In the interactive screenshot UI, pressing <kbd>Ctrl</kbd><kbd>C</kbd> will copy the screenshot to the clipboard without writing it to disk.
+
+<sup>Since: 25.05</sup> You can hide the mouse pointer in screenshots with the `show-pointer=false` property:
+
+```kdl
+binds {
+    // The pointer will be hidden by default
+    // (you can still show it by pressing P).
+    Print { screenshot show-pointer=false; }
+
+    // The pointer will be hidden on the screenshot.
+    Ctrl+Print { screenshot-screen show-pointer=false; }
+}
+```
+
+#### `toggle-keyboard-shortcuts-inhibit`
+
+<sup>Since: 25.02</sup>
+
+Applications such as remote-desktop clients and software KVM switches may request that niri stops processing its keyboard shortcuts so that they may, for example, forward the key presses as-is to a remote machine.
+`toggle-keyboard-shortcuts-inhibit` is an escape hatch that toggles the inhibitor.
+It's a good idea to bind it, so a buggy application can't hold your session hostage.
+
+```kdl
+binds {
+    Mod+Escape { toggle-keyboard-shortcuts-inhibit; }
+}
+```
+
+You can also make certain binds ignore inhibiting with the `allow-inhibiting=false` property.
+They will always be handled by niri and never passed to the window.
+
+```kdl
+binds {
+    // This bind will always work, even when using a virtual machine.
+    Super+Alt+L allow-inhibiting=false { spawn "swaylock"; }
+}
+```

docs/wiki/Configuration:-Layer-Rules.md

@@ -0,0 +1,193 @@
+### Overview
+
+<sup>Since: 25.01</sup>
+
+Layer rules let you adjust behavior for individual layer-shell surfaces.
+They have `match` and `exclude` directives that control which layer-shell surfaces the rule should apply to, and a number of properties that you can set.
+
+Layer rules are processed and work very similarly to window rules, just with different matchers and properties.
+Please read the [window rules wiki page](./Configuration:-Window-Rules.md) to learn how matching works.
+
+Here are all matchers and properties that a layer rule could have:
+
+```kdl
+layer-rule {
+    match namespace="waybar"
+    match at-startup=true
+
+    // Properties that apply continuously.
+    opacity 0.5
+    block-out-from "screencast"
+    // block-out-from "screen-capture"
+
+    shadow {
+        on
+        // off
+        softness 40
+        spread 5
+        offset x=0 y=5
+        draw-behind-window true
+        color "#00000064"
+        // inactive-color "#00000064"
+    }
+
+    geometry-corner-radius 12
+    place-within-backdrop true
+    baba-is-float true
+}
+```
+
+### Layer Surface Matching
+
+Let's look at the matchers in more detail.
+
+#### `namespace`
+
+This is a regular expression that should match anywhere in the surface namespace.
+You can read about the supported regular expression syntax [here](https://docs.rs/regex/latest/regex/#syntax).
+
+```kdl
+// Match surfaces with namespace containing "waybar",
+layer-rule {
+    match namespace="waybar"
+}
+```
+
+You can find the namespaces of all open layer-shell surfaces by running `niri msg layers`.
+
+#### `at-startup`
+
+Can be `true` or `false`.
+Matches during the first 60 seconds after starting niri.
+
+```kdl
+// Show layer-shell surfaces with 0.5 opacity at niri startup, but not afterwards.
+layer-rule {
+    match at-startup=true
+
+    opacity 0.5
+}
+```
+
+### Dynamic Properties
+
+These properties apply continuously to open layer-shell surfaces.
+
+#### `block-out-from`
+
+You can block out surfaces from xdg-desktop-portal screencasts or all screen captures.
+They will be replaced with solid black rectangles.
+
+This can be useful for notifications.
+
+The same caveats and instructions apply as for the [`block-out-from` window rule](./Configuration:-Window-Rules.md#block-out-from), so check the documentation there.
+
+![Screenshot showing a notification visible normally, but blocked out on OBS.](./img/layer-block-out-from-screencast.png)
+
+```kdl
+// Block out mako notifications from screencasts.
+layer-rule {
+    match namespace="^notifications$"
+
+    block-out-from "screencast"
+}
+```
+
+#### `opacity`
+
+Set the opacity of the surface.
+`0.0` is fully transparent, `1.0` is fully opaque.
+This is applied on top of the surface's own opacity, so semitransparent surfaces will become even more transparent.
+
+Opacity is applied to every child of the layer-shell surface individually, so subsurfaces and pop-up menus will show window content behind them.
+
+```kdl
+// Make fuzzel semitransparent.
+layer-rule {
+    match namespace="^launcher$"
+
+    opacity 0.95
+}
+```
+
+#### `shadow`
+
+<sup>Since: 25.02</sup>
+
+Override the shadow options for the surface.
+
+These rules have the same options as the normal [`shadow` config in the layout section](./Configuration:-Layout.md#shadow), so check the documentation there.
+
+Unlike window shadows, layer surface shadows always need to be enabled with a layer rule.
+That is, enabling shadows in the layout config section won't automatically enable them for layer surfaces.
+
+> [!NOTE]
+> Layer surfaces have no way to tell niri about their *visual geometry*.
+> For example, if a layer surface includes some invisible margins (like mako), niri has no way of knowing that, and will draw the shadow behind the entire surface, including the invisible margins.
+>
+> So to use niri shadows, you'll need to configure layer-shell clients to remove their own margins or shadows.
+
+```kdl
+// Add a shadow for fuzzel.
+layer-rule {
+    match namespace="^launcher$"
+
+    shadow {
+        on
+    }
+
+    // Fuzzel defaults to 10 px rounded corners.
+    geometry-corner-radius 10
+}
+```
+
+#### `geometry-corner-radius`
+
+<sup>Since: 25.02</sup>
+
+Set the corner radius of the surface.
+
+This setting will only affect the shadow—it will round its corners to match the geometry corner radius.
+
+```kdl
+layer-rule {
+    match namespace="^launcher$"
+
+    geometry-corner-radius 12
+}
+```
+
+#### `place-within-backdrop`
+
+<sup>Since: 25.05</sup>
+
+Set to `true` to place the surface into the backdrop visible in the [Overview](./Overview.md) and between workspaces.
+
+This will only work for *background* layer surfaces that ignore exclusive zones (typical for wallpaper tools).
+Layers within the backdrop will ignore all input.
+
+```kdl
+// Put swaybg inside the overview backdrop.
+layer-rule {
+    match namespace="^wallpaper$"
+
+    place-within-backdrop true
+}
+```
+
+#### `baba-is-float`
+
+<sup>Since: 25.05</sup>
+
+Make your layer surfaces FLOAT up and down.
+
+This is a natural extension of the [April Fools' 2025 feature](./Configuration:-Window-Rules.md#baba-is-float).
+
+```kdl
+// Make fuzzel FLOAT.
+layer-rule {
+    match namespace="^launcher$"
+
+    baba-is-float true
+}
+```

docs/wiki/Configuration:-Layout.md

@@ -0,0 +1,553 @@
+### Overview
+
+In the `layout {}` section you can change various settings that influence how windows are positioned and sized.
+
+Here are the contents of this section at a glance:
+
+```kdl
+layout {
+    gaps 16
+    center-focused-column "never"
+    always-center-single-column
+    empty-workspace-above-first
+    default-column-display "tabbed"
+    background-color "#003300"
+
+    preset-column-widths {
+        proportion 0.33333
+        proportion 0.5
+        proportion 0.66667
+    }
+
+    default-column-width { proportion 0.5; }
+
+    preset-window-heights {
+        proportion 0.33333
+        proportion 0.5
+        proportion 0.66667
+    }
+
+    focus-ring {
+        // off
+        width 4
+        active-color "#7fc8ff"
+        inactive-color "#505050"
+        urgent-color "#9b0000"
+        // active-gradient from="#80c8ff" to="#bbddff" angle=45
+        // inactive-gradient from="#505050" to="#808080" angle=45 relative-to="workspace-view"
+        // urgent-gradient from="#800" to="#a33" angle=45
+    }
+
+    border {
+        off
+        width 4
+        active-color "#ffc87f"
+        inactive-color "#505050"
+        urgent-color "#9b0000"
+        // active-gradient from="#ffbb66" to="#ffc880" angle=45 relative-to="workspace-view"
+        // inactive-gradient from="#505050" to="#808080" angle=45 relative-to="workspace-view" in="srgb-linear"
+        // urgent-gradient from="#800" to="#a33" angle=45
+    }
+
+    shadow {
+        // on
+        softness 30
+        spread 5
+        offset x=0 y=5
+        draw-behind-window true
+        color "#00000070"
+        // inactive-color "#00000054"
+    }
+
+    tab-indicator {
+        // off
+        hide-when-single-tab
+        place-within-column
+        gap 5
+        width 4
+        length total-proportion=1.0
+        position "right"
+        gaps-between-tabs 2
+        corner-radius 8
+        active-color "red"
+        inactive-color "gray"
+        urgent-color "blue"
+        // active-gradient from="#80c8ff" to="#bbddff" angle=45
+        // inactive-gradient from="#505050" to="#808080" angle=45 relative-to="workspace-view"
+        // urgent-gradient from="#800" to="#a33" angle=45
+    }
+
+    insert-hint {
+        // off
+        color "#ffc87f80"
+        // gradient from="#ffbb6680" to="#ffc88080" angle=45 relative-to="workspace-view"
+    }
+
+    struts {
+        // left 64
+        // right 64
+        // top 64
+        // bottom 64
+    }
+}
+```
+
+### `gaps`
+
+Set gaps around (inside and outside) windows in logical pixels.
+
+<sup>Since: 0.1.7</sup> You can use fractional values.
+The value will be rounded to physical pixels according to the scale factor of every output.
+For example, `gaps 0.5` on an output with `scale 2` will result in one physical-pixel wide gaps.
+
+<sup>Since: 0.1.8</sup> You can emulate "inner" vs. "outer" gaps with negative `struts` values (see the struts section below).
+
+```kdl
+layout {
+    gaps 16
+}
+```
+
+### `center-focused-column`
+
+When to center a column when changing focus.
+This can be set to:
+
+- `"never"`: no special centering, focusing an off-screen column will scroll it to the left or right edge of the screen. This is the default.
+- `"always"`, the focused column will always be centered.
+- `"on-overflow"`, focusing a column will center it if it doesn't fit on screen together with the previously focused column.
+
+```kdl
+layout {
+    center-focused-column "always"
+}
+```
+
+### `always-center-single-column`
+
+<sup>Since: 0.1.9</sup>
+
+If set, niri will always center a single column on a workspace, regardless of the `center-focused-column` option.
+
+```kdl
+layout {
+    always-center-single-column
+}
+```
+
+### `empty-workspace-above-first`
+
+<sup>Since: 25.01</sup>
+
+If set, niri will always add an empty workspace at the very start, in addition to the empty workspace at the very end.
+
+```kdl
+layout {
+    empty-workspace-above-first
+}
+```
+
+### `default-column-display`
+
+<sup>Since: 25.02</sup>
+
+Sets the default display mode for new columns.
+Can be `normal` or `tabbed`.
+
+```kdl
+// Make all new columns tabbed by default.
+layout {
+    default-column-display "tabbed"
+
+    // You may also want to hide the tab indicator
+    // when there's only a single window in a column.
+    tab-indicator {
+        hide-when-single-tab
+    }
+}
+```
+
+### `preset-column-widths`
+
+Set the widths that the `switch-preset-column-width` action (Mod+R) toggles between.
+
+`proportion` sets the width as a fraction of the output width, taking gaps into account.
+For example, you can perfectly fit four windows sized `proportion 0.25` on an output, regardless of the gaps setting.
+The default preset widths are <sup>1</sup>&frasl;<sub>3</sub>, <sup>1</sup>&frasl;<sub>2</sub> and <sup>2</sup>&frasl;<sub>3</sub> of the output.
+
+`fixed` sets the window width in logical pixels exactly.
+
+```kdl
+layout {
+    // Cycle between 1/3, 1/2, 2/3 of the output, and a fixed 1280 logical pixels.
+    preset-column-widths {
+        proportion 0.33333
+        proportion 0.5
+        proportion 0.66667
+        fixed 1280
+    }
+}
+```
+
+### `default-column-width`
+
+Set the default width of the new windows.
+
+The syntax is the same as in `preset-column-widths` above.
+
+```kdl
+layout {
+    // Open new windows sized 1/3 of the output.
+    default-column-width { proportion 0.33333; }
+}
+```
+
+You can also leave the brackets empty, then the windows themselves will decide their initial width.
+
+```kdl
+layout {
+    // New windows decide their initial width themselves.
+    default-column-width {}
+}
+```
+
+> [!NOTE]
+> `default-column-width {}` causes niri to send a (0, H) size in the initial configure request.
+>
+> This is a bit [unclearly defined](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/issues/155) in the Wayland protocol, so some clients may misinterpret it.
+> Either way, `default-column-width {}` is most useful for specific windows, in form of a [window rule](./Configuration:-Window-Rules.md#default-column-width) with the same syntax.
+
+### `preset-window-heights`
+
+<sup>Since: 0.1.9</sup>
+
+Set the heights that the `switch-preset-window-height` action (Mod+Shift+R) toggles between.
+
+`proportion` sets the height as a fraction of the output height, taking gaps into account.
+The default preset heights are <sup>1</sup>&frasl;<sub>3</sub>, <sup>1</sup>&frasl;<sub>2</sub> and <sup>2</sup>&frasl;<sub>3</sub> of the output.
+
+`fixed` sets the height in logical pixels exactly.
+
+```kdl
+layout {
+    // Cycle between 1/3, 1/2, 2/3 of the output, and a fixed 720 logical pixels.
+    preset-window-heights {
+        proportion 0.33333
+        proportion 0.5
+        proportion 0.66667
+        fixed 720
+    }
+}
+```
+
+### `focus-ring` and `border`
+
+Focus ring and border are drawn around windows and indicate the active window.
+They are very similar and have the same options.
+
+The difference is that the focus ring is drawn only around the active window, whereas borders are drawn around all windows and affect their sizes (windows shrink to make space for the borders).
+
+| Focus Ring                | Border                |
+| ------------------------- | --------------------- |
+| ![Screenshot showing a focused image in the center row using focus ring](./img/focus-ring.png) | ![Screenshot showing a focused image in the center row using border, while top and bottom windows have the inactive color](./img/border.png) |
+
+> [!TIP]
+> By default, focus ring and border are rendered as a solid background rectangle behind windows.
+> That is, they will show up through semitransparent windows.
+> This is because windows using client-side decorations can have an arbitrary shape.
+>
+> If you don't like that, you should uncomment the [`prefer-no-csd` setting](./Configuration:-Miscellaneous.md#prefer-no-csd) at the top level of the config.
+> Niri will draw focus rings and borders *around* windows that agree to omit their client-side decorations.
+>
+> Alternatively, you can override this behavior with the [`draw-border-with-background` window rule](./Configuration:-Window-Rules.md#draw-border-with-background).
+
+Focus ring and border have the following options.
+
+```kdl
+layout {
+    // focus-ring has the same options.
+    border {
+        // Uncomment this line to disable the border.
+        // off
+
+        // Width of the border in logical pixels.
+        width 4
+
+        active-color "#ffc87f"
+        inactive-color "#505050"
+
+        // Color of the border around windows that request your attention.
+        urgent-color "#9b0000"
+
+        // active-gradient from="#ffbb66" to="#ffc880" angle=45 relative-to="workspace-view"
+        // inactive-gradient from="#505050" to="#808080" angle=45 relative-to="workspace-view" in="srgb-linear"
+    }
+}
+```
+
+#### Width
+
+Set the thickness of the border in logical pixels.
+
+<sup>Since: 0.1.7</sup> You can use fractional values.
+The value will be rounded to physical pixels according to the scale factor of every output.
+For example, `width 0.5` on an output with `scale 2` will result in one physical-pixel thick borders.
+
+```kdl
+layout {
+    border {
+        width 2
+    }
+}
+```
+
+#### Colors
+
+Colors can be set in a variety of ways:
+
+- CSS named colors: `"red"`
+- RGB hex: `"#rgb"`, `"#rgba"`, `"#rrggbb"`, `"#rrggbbaa"`
+- CSS-like notation: `"rgb(255, 127, 0)"`, `"rgba()"`, `"hsl()"` and a few others.
+
+`active-color` is the color of the focus ring / border around the active window, and `inactive-color` is the color of the focus ring / border around all other windows.
+
+The *focus ring* is only drawn around the active window on each monitor, so with a single monitor you will never see its `inactive-color`.
+You will see it if you have multiple monitors, though.
+
+There's also a *deprecated* syntax for setting colors with four numbers representing R, G, B and A: `active-color 127 200 255 255`.
+
+#### Gradients
+
+Similarly to colors, you can set `active-gradient` and `inactive-gradient`, which will take precedence.
+
+Gradients are rendered the same as CSS [`linear-gradient(angle, from, to)`](https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/linear-gradient).
+The angle works the same as in `linear-gradient`, and is optional, defaulting to `180` (top-to-bottom gradient).
+You can use any CSS linear-gradient tool on the web to set these up, like [css-gradient.com](https://www.css-gradient.com/).
+
+```kdl
+layout {
+    focus-ring {
+        active-gradient from="#80c8ff" to="#bbddff" angle=45
+    }
+}
+```
+
+Gradients can be colored relative to windows individually (the default), or to the whole view of the workspace.
+To do that, set `relative-to="workspace-view"`.
+Here's a visual example:
+
+| Default                          | `relative-to="workspace-view"`                      |
+| -------------------------------- | --------------------------------------------------- |
+| ![Screenshot displaying 4 windows, each with individual gradient borders](./img/gradients-default.png) | ![Screenshot displaying 4 windows, with a shared gradient across their borders](./img/gradients-relative-to-workspace-view.png) |
+
+```kdl
+layout {
+    border {
+        active-gradient from="#ffbb66" to="#ffc880" angle=45 relative-to="workspace-view"
+        inactive-gradient from="#505050" to="#808080" angle=45 relative-to="workspace-view"
+    }
+}
+```
+
+<sup>Since: 0.1.8</sup> You can set the gradient interpolation color space using syntax like `in="srgb-linear"` or `in="oklch longer hue"`.
+Supported color spaces are:
+
+- `srgb` (the default),
+- `srgb-linear`,
+- `oklab`,
+- `oklch` with `shorter hue` or `longer hue` or `increasing hue` or `decreasing hue`.
+
+They are rendered the same as CSS.
+For example, `active-gradient from="#f00f" to="#0f05" angle=45 in="oklch longer hue"` will look the same as CSS `linear-gradient(45deg in oklch longer hue, #f00f, #0f05)`.
+
+![Screenshot showing a window with a border using a gradient in the oklch color space](./img/gradients-oklch.png)
+
+```kdl
+layout {
+    border {
+        active-gradient from="#f00f" to="#0f05" angle=45 in="oklch longer hue"
+    }
+}
+```
+
+### `shadow`
+
+<sup>Since: 25.02</sup>
+
+Shadow rendered behind a window.
+
+Set `on` to enable the shadow.
+
+`softness` controls the shadow softness/size in logical pixels, same as [CSS box-shadow] *blur radius*.
+Setting `softness 0` will give you hard shadows.
+
+`spread` is the distance to expand the window rectangle in logical pixels, same as CSS box-shadow spread.
+<sup>Since: 25.05</sup> Spread can be negative.
+
+`offset` moves the shadow relative to the window in logical pixels, same as CSS box-shadow offset.
+For example, `offset x=2 y=2` will move the shadow 2 logical pixels downwards and to the right.
+
+Set `draw-behind-window` to `true` to make shadows draw behind the window rather than just around it.
+Note that niri has no way of knowing about the CSD window corner radius.
+It has to assume that windows have square corners, leading to shadow artifacts inside the CSD rounded corners.
+This setting fixes those artifacts.
+
+However, instead you may want to set `prefer-no-csd` and/or `geometry-corner-radius`.
+Then, niri will know the corner radius and draw the shadow correctly, without having to draw it behind the window.
+These will also remove client-side shadows if the window draws any.
+
+`color` is the shadow color and opacity.
+
+`inactive-color` lets you override the shadow color for inactive windows; by default, a more transparent `color` is used.
+
+Shadow drawing will follow the window corner radius set with the [`geometry-corner-radius` window rule](./Configuration:-Window-Rules.md#geometry-corner-radius).
+
+> [!NOTE]
+> Currently, shadow drawing only supports matching radius for all corners. If you set `geometry-corner-radius` to four values instead of one, the first (top-left) corner radius will be used for shadows.
+
+```kdl
+// Enable shadows.
+layout {
+    shadow {
+        on
+    }
+}
+
+// Also ask windows to omit client-side decorations, so that
+// they don't draw their own window shadows.
+prefer-no-csd
+```
+
+[CSS box-shadow]: https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow
+
+### `tab-indicator`
+
+<sup>Since: 25.02</sup>
+
+Controls the appearance of the tab indicator that appears next to columns in tabbed display mode.
+
+Set `off` to hide the tab indicator.
+
+Set `hide-when-single-tab` to hide the indicator for tabbed columns that only have a single window.
+
+Set `place-within-column` to put the tab indicator "within" the column, rather than outside.
+This will include it in column sizing and avoid overlaying adjacent columns.
+
+`gap` sets the gap between the tab indicator and the window in logical pixels.
+The gap can be negative, this will put the tab indicator on top of the window.
+
+`width` sets the thickness of the indicator in logical pixels.
+
+`length` controls the length of the indicator.
+Set the `total-proportion` property to make tabs take up this much length relative to the window size.
+By default, the tab indicator has length equal to half of the window size, or `length total-proportion=0.5`.
+
+`position` sets the position of the tab indicator relative to the window.
+It can be `left`, `right`, `top`, or `bottom`.
+
+`gaps-between-tabs` controls the gap between individual tabs in logical pixels.
+
+`corner-radius` sets the rounded corner radius for tabs in the indicator in logical pixels.
+When `gaps-between-tabs` is zero, only the first and the last tabs have rounded corners, otherwise all tabs do.
+
+`active-color`, `inactive-color`, `urgent-color`, `active-gradient`, `inactive-gradient`, `urgent-gradient` let you override the colors for the tabs.
+They have the same semantics as the border and focus ring colors and gradients.
+
+Tab colors are picked in this order:
+1. Colors from the `tab-indicator` window rule, if set.
+1. Colors from the `tab-indicator` layout options, if set (you're here).
+1. If neither are set, niri picks the color matching the window border or focus ring, whichever one is active.
+
+```kdl
+// Make the tab indicator wider and match the window height,
+// also put it at the top and within the column.
+layout {
+    tab-indicator {
+        width 8
+        gap 8
+        length total-proportion=1.0
+        position "top"
+        place-within-column
+    }
+}
+```
+
+### `insert-hint`
+
+<sup>Since: 0.1.10</sup> 
+
+Settings for the window insert position hint during an interactive window move.
+
+`off` disables the insert hint altogether.
+
+`color` and `gradient` let you change the color of the hint and have the same syntax as colors and gradients in border and focus ring.
+
+```kdl
+layout {
+    insert-hint {
+        // off
+        color "#ffc87f80"
+        gradient from="#ffbb6680" to="#ffc88080" angle=45 relative-to="workspace-view"
+    }
+}
+```
+
+### `struts`
+
+Struts shrink the area occupied by windows, similarly to layer-shell panels.
+You can think of them as a kind of outer gaps.
+They are set in logical pixels.
+
+Left and right struts will cause the next window to the side to always peek out slightly.
+Top and bottom struts will simply add outer gaps in addition to the area occupied by layer-shell panels and regular gaps.
+
+<sup>Since: 0.1.7</sup> You can use fractional values.
+The value will be rounded to physical pixels according to the scale factor of every output.
+For example, `top 0.5` on an output with `scale 2` will result in one physical-pixel wide top strut.
+
+```kdl
+layout {
+    struts {
+        left 64
+        right 64
+        top 64
+        bottom 64
+    }
+}
+```
+
+![A screenshot illustrating the effects of struts, as explained in the second paragraph in this section](./img/struts.png)
+
+<sup>Since: 0.1.8</sup> You can use negative values.
+They will push the windows outwards, even outside the edges of the screen.
+
+You can use negative struts with matching gaps value to emulate "inner" vs. "outer" gaps.
+For example, use this for inner gaps without outer gaps:
+
+```kdl
+layout {
+    gaps 16
+
+    struts {
+        left -16
+        right -16
+        top -16
+        bottom -16
+    }
+}
+```
+
+### `background-color`
+
+<sup>Since: 25.05</sup>
+
+Set the default background color that niri draws for workspaces.
+This is visible when you're not using any background tools like swaybg.
+
+```kdl
+layout {
+    background-color "#003300"
+}
+```
+
+You can also set the color per-output [in the output config](./Configuration:-Outputs.md#background-color).

docs/wiki/Configuration:-Miscellaneous.md

@@ -0,0 +1,315 @@
+This page documents all top-level options that don't otherwise have dedicated pages.
+
+Here are all of these options at a glance:
+
+```kdl
+spawn-at-startup "waybar"
+spawn-at-startup "alacritty"
+spawn-sh-at-startup "qs -c ~/source/qs/MyAwesomeShell"
+
+prefer-no-csd
+
+screenshot-path "~/Pictures/Screenshots/Screenshot from %Y-%m-%d %H-%M-%S.png"
+
+environment {
+    QT_QPA_PLATFORM "wayland"
+    DISPLAY null
+}
+
+cursor {
+    xcursor-theme "breeze_cursors"
+    xcursor-size 48
+
+    hide-when-typing
+    hide-after-inactive-ms 1000
+}
+
+overview {
+    zoom 0.5
+    backdrop-color "#262626"
+
+    workspace-shadow {
+        // off
+        softness 40
+        spread 10
+        offset x=0 y=10
+        color "#00000050"
+    }
+}
+
+xwayland-satellite {
+    // off
+    path "xwayland-satellite"
+}
+
+clipboard {
+    disable-primary
+}
+
+hotkey-overlay {
+    skip-at-startup
+    hide-not-bound
+}
+
+config-notification {
+    disable-failed
+}
+```
+
+### `spawn-at-startup`
+
+Add lines like this to spawn processes at niri startup.
+
+`spawn-at-startup` accepts a path to the program binary as the first argument, followed by arguments to the program.
+
+This option works the same way as the [`spawn` key binding action](./Configuration:-Key-Bindings.md#spawn), so please read about all its subtleties there.
+
+```kdl
+spawn-at-startup "waybar"
+spawn-at-startup "alacritty"
+```
+
+Note that running niri as a systemd session supports xdg-desktop-autostart out of the box, which may be more convenient to use.
+Thanks to this, apps that you configured to autostart in GNOME will also "just work" in niri, without any manual `spawn-at-startup` configuration.
+
+### `spawn-sh-at-startup`
+
+<sup>Since: next release</sup>
+
+Add lines like this to run shell commands at niri startup.
+
+The argument is a single string that is passed verbatim to `sh`.
+You can use shell variables, pipelines, `~` expansion and everything else as expected.
+
+See detailed description in the docs for the [`spawn-sh` key binding action](./Configuration:-Key-Bindings.md#spawn-sh).
+
+```kdl
+// Pass all arguments in the same string.
+spawn-sh-at-startup "qs -c ~/source/qs/MyAwesomeShell"
+```
+
+### `prefer-no-csd`
+
+This flag will make niri ask the applications to omit their client-side decorations.
+
+If an application will specifically ask for CSD, the request will be honored.
+Additionally, clients will be informed that they are tiled, removing some rounded corners.
+
+With `prefer-no-csd` set, applications that negotiate server-side decorations through the xdg-decoration protocol will have focus ring and border drawn around them *without* a solid colored background.
+
+> [!NOTE]
+> Unlike most other options, changing `prefer-no-csd` will not entirely affect already running applications.
+> It will make some windows rectangular, but won't remove the title bars.
+> This mainly has to do with niri working around a [bug in SDL2](https://github.com/libsdl-org/SDL/issues/8173) that prevents SDL2 applications from starting.
+>
+> Restart applications after changing `prefer-no-csd` in the config to fully apply it.
+
+```kdl
+prefer-no-csd
+```
+
+### `screenshot-path`
+
+Set the path where screenshots are saved.
+A `~` at the front will be expanded to the home directory.
+
+The path is formatted with `strftime(3)` to give you the screenshot date and time.
+
+Niri will create the last folder of the path if it doesn't exist.
+
+```kdl
+screenshot-path "~/Pictures/Screenshots/Screenshot from %Y-%m-%d %H-%M-%S.png"
+```
+
+You can also set this option to `null` to disable saving screenshots to disk.
+
+```kdl
+screenshot-path null
+```
+
+### `environment`
+
+Override environment variables for processes spawned by niri.
+
+```kdl
+environment {
+    // Set a variable like this:
+    // QT_QPA_PLATFORM "wayland"
+
+    // Remove a variable by using null as the value:
+    // DISPLAY null
+}
+```
+
+### `cursor`
+
+Change the theme and size of the cursor as well as set the `XCURSOR_THEME` and `XCURSOR_SIZE` environment variables.
+
+```kdl
+cursor {
+    xcursor-theme "breeze_cursors"
+    xcursor-size 48
+}
+```
+
+#### `hide-when-typing`
+
+<sup>Since: 0.1.10</sup>
+
+If set, hides the cursor when pressing a key on the keyboard.
+
+> [!NOTE]
+> This setting might interfere with games running in Wine in native Wayland mode that use mouselook, such as first-person games.
+> If your character's point of view jumps down when you press a key and move the mouse simultaneously, try disabling this setting.
+
+```kdl
+cursor {
+    hide-when-typing
+}
+```
+
+#### `hide-after-inactive-ms`
+
+<sup>Since: 0.1.10</sup>
+
+If set, the cursor will automatically hide once this number of milliseconds passes since the last cursor movement.
+
+```kdl
+cursor {
+    // Hide the cursor after one second of inactivity.
+    hide-after-inactive-ms 1000
+}
+```
+
+### `overview`
+
+<sup>Since: 25.05</sup>
+
+Settings for the [Overview](./Overview.md).
+
+#### `zoom`
+
+Control how much the workspaces zoom out in the overview.
+`zoom` ranges from 0 to 0.75 where lower values make everything smaller.
+
+```kdl
+// Make workspaces four times smaller than normal in the overview.
+overview {
+    zoom 0.25
+}
+```
+
+#### `backdrop-color`
+
+Set the backdrop color behind workspaces in the overview.
+The backdrop is also visible between workspaces when switching.
+
+The alpha channel for this color will be ignored.
+
+```kdl
+// Make the backdrop light.
+overview {
+    backdrop-color "#777777"
+}
+```
+
+You can also set the color per-output [in the output config](./Configuration:-Outputs.md#backdrop-color).
+
+#### `workspace-shadow`
+
+Control the shadow behind workspaces visible in the overview.
+
+Settings here mirror the normal [`shadow` config in the layout section](./Configuration:-Layout.md#shadow), so check the documentation there.
+
+Workspace shadows are configured for a workspace size normalized to 1080 pixels tall, then zoomed out together with the workspace.
+Practically, this means that you'll want bigger spread, offset, and softness compared to window shadows.
+
+```kdl
+// Disable workspace shadows in the overview.
+overview {
+    workspace-shadow {
+        off
+    }
+}
+```
+
+### `xwayland-satellite`
+
+<sup>Since: next release</sup>
+
+Settings for integration with [xwayland-satellite](https://github.com/Supreeeme/xwayland-satellite).
+
+When a recent enough xwayland-satellite is detected, niri will create the X11 sockets and set `DISPLAY`, then automatically spawn `xwayland-satellite` when an X11 client tries to connect.
+If Xwayland dies, niri will keep watching the X11 socket and restart `xwayland-satellite` as needed.
+This is very similar to how built-in Xwayland works in other compositors.
+
+`off` disables the integration: niri won't create an X11 socket and won't set the `DISPLAY` environment variable.
+
+`path` sets the path to the `xwayland-satellite` binary.
+By default, it's just `xwayland-satellite`, so it's looked up like any other non-absolute program name.
+
+```kdl
+// Use a custom build of xwayland-satellite.
+xwayland-satellite {
+    path "~/source/rs/xwayland-satellite/target/release/xwayland-satellite"
+}
+```
+
+### `clipboard`
+
+<sup>Since: 25.02</sup>
+
+Clipboard settings.
+
+Set the `disable-primary` flag to disable the primary clipboard (middle-click paste).
+Toggling this flag will only apply to applications started afterward.
+
+```kdl
+clipboard {
+    disable-primary
+}
+```
+
+### `hotkey-overlay`
+
+Settings for the "Important Hotkeys" overlay.
+
+#### `skip-at-startup`
+
+Set the `skip-at-startup` flag if you don't want to see the hotkey help at niri startup.
+
+```kdl
+hotkey-overlay {
+    skip-at-startup
+}
+```
+
+#### `hide-not-bound`
+
+<sup>Since: next release</sup>
+
+By default, niri will show the most important actions even if they aren't bound to any key, to prevent confusion.
+Set the `hide-not-bound` flag if you want to hide all actions not bound to any key.
+
+```kdl
+hotkey-overlay {
+    hide-not-bound
+}
+```
+
+You can customize which binds the hotkey overlay shows using the [`hotkey-overlay-title` property](./Configuration:-Key-Bindings.md#custom-hotkey-overlay-titles).
+
+### `config-notification`
+
+<sup>Since: next release</sup>
+
+Settings for the config created/failed notification.
+
+Set the `disable-failed` flag to disable the "Failed to parse the config file" notification.
+For example, if you have a custom one.
+
+```kdl
+config-notification {
+    disable-failed
+}
+```

docs/wiki/Configuration:-Named-Workspaces.md

@@ -0,0 +1,47 @@
+### Overview
+
+<sup>Since: 0.1.6</sup>
+
+You can declare named workspaces at the top level of the config:
+
+```kdl
+workspace "browser"
+
+workspace "chat" {
+    open-on-output "Some Company CoolMonitor 1234"
+}
+```
+
+Contrary to normal dynamic workspaces, named workspaces always exist, even when they have no windows.
+Otherwise, they behave like any other workspace: you can move them around, move to a different monitor, and so on.
+
+Actions like `focus-workspace` or `move-column-to-workspace` can refer to workspaces by name.
+Also, you can use an `open-on-workspace` window rule to make a window open on a specific named workspace:
+
+```kdl
+// Declare a workspace named "chat" that opens on the "DP-2" output.
+workspace "chat" {
+    open-on-output "DP-2"
+}
+
+// Open Fractal on the "chat" workspace, if it runs at niri startup.
+window-rule {
+    match at-startup=true app-id=r#"^org\.gnome\.Fractal$"#
+    open-on-workspace "chat"
+}
+```
+
+Named workspaces initially appear in the order they are declared in the config file.
+When editing the config while niri is running, newly declared named workspaces will appear at the very top of a monitor.
+
+If you delete some named workspace from the config, the workspace will become normal (unnamed), and if there are no windows on it, it will be removed (as any other normal workspace).
+There's no way to give a name to an already existing workspace, but you can simply move windows that you want to a new, empty named workspace.
+
+<sup>Since: 0.1.9</sup> `open-on-output` can now use monitor manufacturer, model, and serial.
+Before, it could only use the connector name.
+
+<sup>Since: 25.01</sup> You can use `set-workspace-name` and `unset-workspace-name` actions to change workspace names dynamically.
+
+<sup>Since: 25.02</sup> Named workspaces no longer update/forget their original output when opening a new window on them (unnamed workspaces will keep doing that).
+This means that named workspaces "stick" to their original output in more cases, reflecting their more permanent nature.
+Explicitly moving a named workspace to a different monitor will still update its original output.

docs/wiki/Configuration:-Outputs.md

@@ -0,0 +1,219 @@
+### Overview
+
+By default, niri will attempt to turn on all connected monitors using their preferred modes.
+You can disable or adjust this with `output` sections.
+
+Here's what it looks like with all properties written out:
+
+```kdl
+output "eDP-1" {
+    // off
+    mode "1920x1080@120.030"
+    scale 2.0
+    transform "90"
+    position x=1280 y=0
+    variable-refresh-rate // on-demand=true
+    focus-at-startup
+    background-color "#003300"
+    backdrop-color "#001100"
+}
+
+output "HDMI-A-1" {
+    // ...settings for HDMI-A-1...
+}
+
+output "Some Company CoolMonitor 1234" {
+    // ...settings for CoolMonitor...
+}
+```
+
+Outputs are matched by connector name (i.e. `eDP-1`, `HDMI-A-1`), or by monitor manufacturer, model, and serial, separated by a single space each.
+You can find all of these by running `niri msg outputs`.
+
+Usually, the built-in monitor in laptops will be called `eDP-1`.
+
+<sup>Since: 0.1.6</sup> The output name is case-insensitive.
+
+<sup>Since: 0.1.9</sup> Outputs can be matched by manufacturer, model, and serial.
+Before, they could be matched only by the connector name.
+
+### `off`
+
+This flag turns off that output entirely.
+
+```kdl
+// Turn off that monitor.
+output "HDMI-A-1" {
+    off
+}
+```
+
+### `mode`
+
+Set the monitor resolution and refresh rate.
+
+The format is `<width>x<height>` or `<width>x<height>@<refresh rate>`.
+If the refresh rate is omitted, niri will pick the highest refresh rate for the resolution.
+
+If the mode is omitted altogether or doesn't work, niri will try to pick one automatically.
+
+Run `niri msg outputs` while inside a niri instance to list all outputs and their modes.
+The refresh rate that you set here must match *exactly*, down to the three decimal digits, to what you see in `niri msg outputs`.
+
+```kdl
+// Set a high refresh rate for this monitor.
+// High refresh rate monitors tend to use 60 Hz as their preferred mode,
+// requiring a manual mode setting.
+output "HDMI-A-1" {
+    mode "2560x1440@143.912"
+}
+
+// Use a lower resolution on the built-in laptop monitor
+// (for example, for testing purposes).
+output "eDP-1" {
+    mode "1280x720"
+}
+```
+
+### `scale`
+
+Set the scale of the monitor.
+
+<sup>Since: 0.1.6</sup> If scale is unset, niri will guess an appropriate scale based on the physical dimensions and the resolution of the monitor.
+
+<sup>Since: 0.1.7</sup> You can use fractional scale values, for example `scale 1.5` for 150% scale.
+
+<sup>Since: 0.1.7</sup> Dot is no longer needed for integer scale, for example you can write `scale 2` instead of `scale 2.0`.
+
+<sup>Since: 0.1.7</sup> Scale below 0 and above 10 will now fail during config parsing. Scale was previously clamped to these values anyway.
+
+```kdl
+output "eDP-1" {
+    scale 2.0
+}
+```
+
+### `transform`
+
+Rotate the output counter-clockwise.
+
+Valid values are: `"normal"`, `"90"`, `"180"`, `"270"`, `"flipped"`, `"flipped-90"`, `"flipped-180"` and `"flipped-270"`.
+Values with `flipped` additionally flip the output.
+
+```kdl
+output "HDMI-A-1" {
+    transform "90"
+}
+```
+
+### `position`
+
+Set the position of the output in the global coordinate space.
+
+This affects directional monitor actions like `focus-monitor-left`, and cursor movement.
+The cursor can only move between directly adjacent outputs.
+
+> [!NOTE]
+> Output scale and rotation has to be taken into account for positioning: outputs are sized in logical, or scaled, pixels.
+> For example, a 3840×2160 output with scale 2.0 will have a logical size of 1920×1080, so to put another output directly adjacent to it on the right, set its x to 1920.
+> If the position is unset or results in an overlap, the output is instead placed automatically.
+
+```kdl
+output "HDMI-A-1" {
+    position x=1280 y=0
+}
+```
+
+#### Automatic Positioning
+
+Niri repositions outputs from scratch every time the output configuration changes (which includes monitors disconnecting and connecting).
+The following algorithm is used for positioning outputs.
+
+1. Collect all connected monitors and their logical sizes.
+1. Sort them by their name. This makes it so the automatic positioning does not depend on the order the monitors are connected. This is important because the connection order is non-deterministic at compositor startup.
+1. Try to place every output with explicitly configured `position`, in order. If the output overlaps previously placed outputs, place it to the right of all previously placed outputs. In this case, niri will also print a warning.
+1. Place every output without explicitly configured `position` by putting it to the right of all previously placed outputs.
+
+### `variable-refresh-rate`
+
+<sup>Since: 0.1.5</sup>
+
+This flag enables variable refresh rate (VRR, also known as adaptive sync, FreeSync, or G-Sync), if the output supports it.
+
+You can check whether an output supports VRR in `niri msg outputs`.
+
+> [!NOTE]
+> Some drivers have various issues with VRR.
+>
+> If the cursor moves at a low framerate with VRR, try setting the [`disable-cursor-plane` debug flag](./Configuration:-Debug-Options.md#disable-cursor-plane) and reconnecting the monitor.
+>
+> If a monitor is not detected as VRR-capable when it should, sometimes unplugging a different monitor fixes it.
+>
+> Some monitors will continuously modeset (flash black) with VRR enabled; I'm not sure if there's a way to fix it.
+
+```kdl
+output "HDMI-A-1" {
+    variable-refresh-rate
+}
+```
+
+<sup>Since: 0.1.9</sup> You can also set the `on-demand=true` property, which will only enable VRR when this output shows a window matching the `variable-refresh-rate` window rule.
+This is helpful to avoid various issues with VRR, since it can be disabled most of the time, and only enabled for specific windows, like games or video players.
+
+```kdl
+output "HDMI-A-1" {
+    variable-refresh-rate on-demand=true
+}
+```
+
+### `focus-at-startup`
+
+<sup>Since: 25.05</sup>
+
+Focus this output by default when niri starts.
+
+If multiple outputs with `focus-at-startup` are connected, they are prioritized in the order that they appear in the config.
+
+When none of the connected outputs are explicitly `focus-at-startup`, niri will focus the first one sorted by name (same output sorting as used elsewhere in niri).
+
+```kdl
+// Focus HDMI-A-1 by default.
+output "HDMI-A-1" {
+    focus-at-startup
+}
+
+// ...if HDMI-A-1 wasn't connected, focus DP-2 instead.
+output "DP-2" {
+    focus-at-startup
+}
+```
+
+### `background-color`
+
+<sup>Since: 0.1.8</sup>
+
+Set the background color that niri draws for workspaces on this output.
+This is visible when you're not using any background tools like swaybg.
+
+<sup>Until: 25.05</sup> The alpha channel for this color will be ignored.
+
+```kdl
+output "HDMI-A-1" {
+    background-color "#003300"
+}
+```
+
+### `backdrop-color`
+
+<sup>Since: 25.05</sup>
+
+Set the backdrop color that niri draws for this output.
+This is visible between workspaces or in the overview.
+
+The alpha channel for this color will be ignored.
+
+```kdl
+output "HDMI-A-1" {
+    backdrop-color "#001100"
+}
+```

docs/wiki/Configuration:-Overview.md

@@ -0,0 +1 @@
+This wiki page has moved to: [Introduction](./Configuration:-Introduction.md).

docs/wiki/Configuration:-Switch-Events.md

@@ -0,0 +1,47 @@
+### Overview
+
+<sup>Since: 0.1.10</sup>
+
+Switch event bindings are declared in the `switch-events {}` section of the config.
+
+Here are all the events that you can bind at a glance:
+
+```kdl
+switch-events {
+    lid-close { spawn "notify-send" "The laptop lid is closed!"; }
+    lid-open { spawn "notify-send" "The laptop lid is open!"; }
+    tablet-mode-on { spawn "bash" "-c" "gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled true"; }
+    tablet-mode-off { spawn "bash" "-c" "gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled false"; }
+}
+```
+
+The syntax is similar to key bindings.
+Currently, only the [`spawn` action](./Configuration:-Key-Bindings.md#spawn) are supported.
+
+> [!NOTE]
+> In contrast to key bindings, switch event bindings are *always* executed, even when the session is locked.
+
+### `lid-close`, `lid-open`
+
+These events correspond to closing and opening of the laptop lid.
+
+Note that niri will already automatically turn the internal laptop monitor on and off in accordance with the laptop lid.
+
+```kdl
+switch-events {
+    lid-close { spawn "notify-send" "The laptop lid is closed!"; }
+    lid-open { spawn "notify-send" "The laptop lid is open!"; }
+}
+```
+
+### `tablet-mode-on`, `tablet-mode-off`
+
+These events trigger when a convertible laptop goes into or out of tablet mode.
+In tablet mode, the keyboard and mouse are usually inaccessible, so you can use these events to activate the on-screen keyboard.
+
+```kdl
+switch-events {
+    tablet-mode-on { spawn "bash" "-c" "gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled true"; }
+    tablet-mode-off { spawn "bash" "-c" "gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled false"; }
+}
+```

docs/wiki/Configuration:-Window-Rules.md

@@ -0,0 +1,919 @@
+### Overview
+
+Window rules let you adjust behavior for individual windows.
+They have `match` and `exclude` directives that control which windows the rule should apply to, and a number of properties that you can set.
+
+Window rules are processed in order of appearance in the config file.
+This means that you can put more generic rules first, then override them for specific windows later.
+For example:
+
+```kdl
+// Set open-maximized to true for all windows.
+window-rule {
+    open-maximized true
+}
+
+// Then, for Alacritty, set open-maximized back to false.
+window-rule {
+    match app-id="Alacritty"
+    open-maximized false
+}
+```
+
+> [!TIP]
+> In general, you cannot "unset" a property in a later rule, only set it to a different value.
+> Use the `exclude` directives to avoid applying a rule for specific windows.
+
+Here are all matchers and properties that a window rule could have:
+
+```kdl
+window-rule {
+    match title="Firefox"
+    match app-id="Alacritty"
+    match is-active=true
+    match is-focused=false
+    match is-active-in-column=true
+    match is-floating=true
+    match is-window-cast-target=true
+    match is-urgent=true
+    match at-startup=true
+
+    // Properties that apply once upon window opening.
+    default-column-width { proportion 0.75; }
+    default-window-height { fixed 500; }
+    open-on-output "Some Company CoolMonitor 1234"
+    open-on-workspace "chat"
+    open-maximized true
+    open-fullscreen true
+    open-floating true
+    open-focused false
+
+    // Properties that apply continuously.
+    draw-border-with-background false
+    opacity 0.5
+    block-out-from "screencast"
+    // block-out-from "screen-capture"
+    variable-refresh-rate true
+    default-column-display "tabbed"
+    default-floating-position x=100 y=200 relative-to="bottom-left"
+    scroll-factor 0.75
+
+    focus-ring {
+        // off
+        on
+        width 4
+        active-color "#7fc8ff"
+        inactive-color "#505050"
+        urgent-color "#9b0000"
+        // active-gradient from="#80c8ff" to="#bbddff" angle=45
+        // inactive-gradient from="#505050" to="#808080" angle=45 relative-to="workspace-view"
+        // urgent-gradient from="#800" to="#a33" angle=45
+    }
+
+    border {
+        // Same as focus-ring.
+    }
+
+    shadow {
+        // on
+        off
+        softness 40
+        spread 5
+        offset x=0 y=5
+        draw-behind-window true
+        color "#00000064"
+        // inactive-color "#00000064"
+    }
+
+    tab-indicator {
+        active-color "red"
+        inactive-color "gray"
+        urgent-color "blue"
+        // active-gradient from="#80c8ff" to="#bbddff" angle=45
+        // inactive-gradient from="#505050" to="#808080" angle=45 relative-to="workspace-view"
+        // urgent-gradient from="#800" to="#a33" angle=45
+    }
+
+    geometry-corner-radius 12
+    clip-to-geometry true
+    tiled-state true
+    baba-is-float true
+
+    min-width 100
+    max-width 200
+    min-height 300
+    max-height 300
+}
+```
+
+### Window Matching
+
+Each window rule can have several `match` and `exclude` directives.
+In order for the rule to apply, a window needs to match *any* of the `match` directives, and *none* of the `exclude` directives.
+
+```kdl
+window-rule {
+    // Match all Telegram windows...
+    match app-id=r#"^org\.telegram\.desktop$"#
+
+    // ...except the media viewer window.
+    exclude title="^Media viewer$"
+
+    // Properties to apply.
+    open-on-output "HDMI-A-1"
+}
+```
+
+Match and exclude directives have the same syntax.
+There can be multiple *matchers* in one directive, then the window should match all of them for the directive to apply.
+
+```kdl
+window-rule {
+    // Match Firefox windows with Gmail in title.
+    match app-id="firefox" title="Gmail"
+}
+
+window-rule {
+    // Match Firefox, but only when it is active...
+    match app-id="firefox" is-active=true
+
+    // ...or match Telegram...
+    match app-id=r#"^org\.telegram\.desktop$"#
+
+    // ...but don't match the Telegram media viewer.
+    // If you open a tab in Firefox titled "Media viewer",
+    // it will not be excluded because it doesn't match the app-id
+    // of this exclude directive.
+    exclude app-id=r#"^org\.telegram\.desktop$"# title="Media viewer"
+}
+```
+
+Let's look at the matchers in more detail.
+
+#### `title` and `app-id`
+
+These are regular expressions that should match anywhere in the window title and app ID respectively.
+You can read about the supported regular expression syntax [here](https://docs.rs/regex/latest/regex/#syntax).
+
+```kdl
+// Match windows with title containing "Mozilla Firefox",
+// or windows with app ID containing "Alacritty".
+window-rule {
+    match title="Mozilla Firefox"
+    match app-id="Alacritty"
+}
+```
+
+Raw KDL strings can be helpful for writing out regular expressions:
+
+```kdl
+window-rule {
+    exclude app-id=r#"^org\.keepassxc\.KeePassXC$"#
+}
+```
+
+You can find the title and the app ID of the currently focused window by running `niri msg focused-window`.
+
+> [!TIP]
+> Another way to find the window title and app ID is to configure the `wlr/taskbar` module in [Waybar](https://github.com/Alexays/Waybar) to include them in the tooltip:
+> 
+> ```json
+> "wlr/taskbar": {
+>     "tooltip-format": "{title} | {app_id}",
+> }
+> ```
+
+#### `is-active`
+
+Can be `true` or `false`.
+Matches active windows (same windows that have the active border / focus ring color).
+
+Every workspace on the focused monitor will have one active window.
+This means that you will usually have multiple active windows (one per workspace), and when you switch between workspaces, you can see two active windows at once.
+
+```kdl
+window-rule {
+    match is-active=true
+}
+```
+
+#### `is-focused`
+
+Can be `true` or `false`.
+Matches the window that has the keyboard focus.
+
+Contrary to `is-active`, there can only be a single focused window.
+Also, when opening a layer-shell application launcher or pop-up menu, the keyboard focus goes to layer-shell.
+While layer-shell has the keyboard focus, windows will not match this rule.
+
+```kdl
+window-rule {
+    match is-focused=true
+}
+```
+
+#### `is-active-in-column`
+
+<sup>Since: 0.1.6</sup>
+
+Can be `true` or `false`.
+Matches the window that is the "active" window in its column.
+
+Contrary to `is-active`, there is always one `is-active-in-column` window in each column.
+It is the window that was last focused in the column, i.e. the one that will gain focus if this column is focused.
+
+<sup>Since: 25.01</sup> This rule will match `true` during the initial window opening.
+
+```kdl
+window-rule {
+    match is-active-in-column=true
+}
+```
+
+#### `is-floating`
+
+<sup>Since: 25.01</sup>
+
+Can be `true` or `false`.
+Matches floating windows.
+
+> [!NOTE]
+> This matcher will apply only after the window is already open.
+> This means that you cannot use it to change the window opening properties like `default-window-height` or `open-on-workspace`.
+
+```kdl
+window-rule {
+    match is-floating=true
+}
+```
+
+#### `is-window-cast-target`
+
+<sup>Since: 25.02</sup>
+
+Can be `true` or `false`.
+Matches `true` for windows that are target of an ongoing window screencast.
+
+> [!NOTE]
+> This only matches individual-window screencasts.
+> It will not match windows that happen to be visible in a monitor screencast, for example.
+
+```kdl
+// Indicate screencasted windows with red colors.
+window-rule {
+    match is-window-cast-target=true
+
+    focus-ring {
+        active-color "#f38ba8"
+        inactive-color "#7d0d2d"
+    }
+
+    border {
+        inactive-color "#7d0d2d"
+    }
+
+    shadow {
+        color "#7d0d2d70"
+    }
+
+    tab-indicator {
+        active-color "#f38ba8"
+        inactive-color "#7d0d2d"
+    }
+}
+```
+
+Example:
+
+![A screenshot showing that only the is-window-cast-target=true windows receive the special border colors](https://github.com/user-attachments/assets/375b381e-3a87-4e94-8676-44404971d893)
+
+#### `is-urgent`
+
+<sup>Since: 25.05</sup>
+
+Can be `true` or `false`.
+Matches windows that request the user's attention.
+
+```kdl
+window-rule {
+    match is-urgent=true
+}
+```
+
+#### `at-startup`
+
+<sup>Since: 0.1.6</sup>
+
+Can be `true` or `false`.
+Matches during the first 60 seconds after starting niri.
+
+This is useful for properties like `open-on-output` which you may want to apply only right after starting niri.
+
+```kdl
+// Open windows on the HDMI-A-1 monitor at niri startup, but not afterwards.
+window-rule {
+    match at-startup=true
+    open-on-output "HDMI-A-1"
+}
+```
+
+### Window Opening Properties
+
+These properties apply once, when a window first opens.
+
+To be precise, they apply at the point when niri sends the initial configure request to the window.
+
+#### `default-column-width`
+
+Set the default width for the new window.
+
+This works for floating windows too, despite the word "column" in the name.
+
+```kdl
+// Give Blender and GIMP some guaranteed width on opening.
+window-rule {
+    match app-id="^blender$"
+
+    // GIMP app ID contains the version like "gimp-2.99",
+    // so we only match the beginning (with ^) and not the end.
+    match app-id="^gimp"
+
+    default-column-width { fixed 1200; }
+}
+```
+
+#### `default-window-height`
+
+<sup>Since: 25.01</sup>
+
+Set the default height for the new window.
+
+```kdl
+// Open the Firefox picture-in-picture window as floating with 480×270 size.
+window-rule {
+    match app-id="firefox$" title="^Picture-in-Picture$"
+
+    open-floating true
+    default-column-width { fixed 480; }
+    default-window-height { fixed 270; }
+}
+```
+
+#### `open-on-output`
+
+Make the window open on a specific output.
+
+If such an output does not exist, the window will open on the currently focused output as usual.
+
+If the window opens on an output that is not currently focused, the window will not be automatically focused.
+
+```kdl
+// Open Firefox and Telegram (but not its Media Viewer)
+// on a specific monitor.
+window-rule {
+    match app-id="firefox$"
+    match app-id=r#"^org\.telegram\.desktop$"#
+    exclude app-id=r#"^org\.telegram\.desktop$"# title="^Media viewer$"
+
+    open-on-output "HDMI-A-1"
+    // Or:
+    // open-on-output "Some Company CoolMonitor 1234"
+}
+```
+
+<sup>Since: 0.1.9</sup> `open-on-output` can now use monitor manufacturer, model, and serial.
+Before, it could only use the connector name.
+
+#### `open-on-workspace`
+
+<sup>Since: 0.1.6</sup>
+
+Make the window open on a specific [named workspace](./Configuration:-Named-Workspaces.md).
+
+If such a workspace does not exist, the window will open on the currently focused workspace as usual.
+
+If the window opens on an output that is not currently focused, the window will not be automatically focused.
+
+```kdl
+// Open Fractal on the "chat" workspace.
+window-rule {
+    match app-id=r#"^org\.gnome\.Fractal$"#
+
+    open-on-workspace "chat"
+}
+```
+
+#### `open-maximized`
+
+Make the window open as a maximized column.
+
+```kdl
+// Maximize Firefox by default.
+window-rule {
+    match app-id="firefox$"
+
+    open-maximized true
+}
+```
+
+#### `open-fullscreen`
+
+Make the window open fullscreen.
+
+```kdl
+window-rule {
+    open-fullscreen true
+}
+```
+
+You can also set this to `false` to *prevent* a window from opening fullscreen.
+
+```kdl
+// Make the Telegram media viewer open in windowed mode.
+window-rule {
+    match app-id=r#"^org\.telegram\.desktop$"# title="^Media viewer$"
+
+    open-fullscreen false
+}
+```
+
+#### `open-floating`
+
+<sup>Since: 25.01</sup>
+
+Make the window open in the floating layout.
+
+```kdl
+// Open the Firefox picture-in-picture window as floating.
+window-rule {
+    match app-id="firefox$" title="^Picture-in-Picture$"
+
+    open-floating true
+}
+```
+
+You can also set this to `false` to *prevent* a window from opening in the floating layout.
+
+```kdl
+// Open all windows in the tiling layout, overriding any auto-floating logic.
+window-rule {
+    open-floating false
+}
+```
+
+#### `open-focused`
+
+<sup>Since: 25.01</sup>
+
+Set this to `false` to prevent this window from being automatically focused upon opening.
+
+```kdl
+// Don't give focus to the GIMP startup splash screen.
+window-rule {
+    match app-id="^gimp" title="^GIMP Startup$"
+
+    open-focused false
+}
+```
+
+You can also set this to `true` to focus the window, even if normally it wouldn't get auto-focused.
+
+```kdl
+// Always focus the KeePassXC-Browser unlock dialog.
+//
+// This dialog opens parented to the KeePassXC window rather than the browser,
+// so it doesn't get auto-focused by default.
+window-rule {
+    match app-id=r#"^org\.keepassxc\.KeePassXC$"# title="^Unlock Database - KeePassXC$"
+
+    open-focused true
+}
+```
+
+### Dynamic Properties
+
+These properties apply continuously to open windows.
+
+#### `block-out-from`
+
+You can block out windows from xdg-desktop-portal screencasts.
+They will be replaced with solid black rectangles.
+
+This can be useful for password managers or messenger windows, etc.
+For layer-shell notification pop-ups and the like, you can use a [`block-out-from` layer rule](./Configuration:-Layer-Rules.md#block-out-from).
+
+![Screenshot showing a window visible normally, but blocked out on OBS.](./img/block-out-from-screencast.png)
+
+To preview and set up this rule, check the `preview-render` option in the debug section of the config.
+
+> [!CAUTION]
+> The window is **not** blocked out from third-party screenshot tools.
+> If you open some screenshot tool with preview while screencasting, blocked out windows **will be visible** on the screencast.
+
+The built-in screenshot UI is not affected by this problem though.
+If you open the screenshot UI while screencasting, you will be able to select the area to screenshot while seeing all windows normally, but on a screencast the selection UI will display with windows blocked out.
+
+```kdl
+// Block out password managers from screencasts.
+window-rule {
+    match app-id=r#"^org\.keepassxc\.KeePassXC$"#
+    match app-id=r#"^org\.gnome\.World\.Secrets$"#
+
+    block-out-from "screencast"
+}
+```
+
+Alternatively, you can block out the window out of *all* screen captures, including third-party screenshot tools.
+This way you avoid accidentally showing the window on a screencast when opening a third-party screenshot preview.
+
+This setting will still let you use the interactive built-in screenshot UI, but it will block out the window from the fully automatic screenshot actions, such as `screenshot-screen` and `screenshot-window`.
+The reasoning is that with an interactive selection, you can make sure that you avoid screenshotting sensitive content.
+
+```kdl
+window-rule {
+    block-out-from "screen-capture"
+}
+```
+
+> [!WARNING]
+> Be careful when blocking out windows based on a dynamically changing window title.
+>
+> For example, you might try to block out specific Firefox tabs like this:
+>
+> ```kdl
+> window-rule {
+>     // Doesn't quite work! Try to block out the Gmail tab.
+>     match app-id="firefox$" title="- Gmail "
+>
+>     block-out-from "screencast"
+> }
+> ```
+>
+> It will work, but when switching from a sensitive tab to a regular tab, the contents of the sensitive tab **will show up on a screencast** for an instant.
+>
+> This is because window title (and app ID) are not double-buffered in the Wayland protocol, so they are not tied to specific window contents.
+> There's no robust way for Firefox to synchronize visibly showing a different tab and changing the window title.
+
+#### `opacity`
+
+Set the opacity of the window.
+`0.0` is fully transparent, `1.0` is fully opaque.
+This is applied on top of the window's own opacity, so semitransparent windows will become even more transparent.
+
+Opacity is applied to every surface of the window individually, so subsurfaces and pop-up menus will show window content behind them.
+
+![Screenshot showing Adwaita Demo with a semitransparent pop-up menu.](./img/opacity-popup.png)
+
+Also, focus ring and border with background will show through semitransparent windows (see `prefer-no-csd` and the `draw-border-with-background` window rule below).
+
+Opacity can be toggled on or off for a window using the [`toggle-window-rule-opacity`](./Configuration:-Key-Bindings.md#toggle-window-rule-opacity) action.
+
+```kdl
+// Make inactive windows semitransparent.
+window-rule {
+    match is-active=false
+
+    opacity 0.95
+}
+```
+
+#### `variable-refresh-rate`
+
+<sup>Since: 0.1.9</sup>
+
+If set to true, whenever this window displays on an output with on-demand VRR, it will enable VRR on that output.
+
+```kdl
+// Configure some output with on-demand VRR.
+output "HDMI-A-1" {
+    variable-refresh-rate on-demand=true
+}
+
+// Enable on-demand VRR when mpv displays on the output.
+window-rule {
+    match app-id="^mpv$"
+
+    variable-refresh-rate true
+}
+```
+
+#### `default-column-display`
+
+<sup>Since: 25.02</sup>
+
+Set the default display mode for columns created from this window.
+
+This is used any time a window goes into its own column.
+For example:
+- Opening a new window.
+- Expelling a window into its own column.
+- Moving a window from the floating layout to the tiling layout.
+
+```kdl
+// Make Evince windows open as tabbed columns.
+window-rule {
+    match app-id="^evince$"
+
+    default-column-display "tabbed"
+}
+```
+
+#### `default-floating-position`
+
+<sup>Since: 25.01</sup>
+
+Set the initial position for this window when it opens on, or moves to the floating layout.
+
+Afterward, the window will remember its last floating position.
+
+By default, new floating windows open at the center of the screen, and windows from the tiling layout open close to their visual screen position.
+
+The position uses logical coordinates relative to the working area.
+By default, they are relative to the top-left corner of the working area, but you can change this by setting `relative-to` to one of these values: `top-left`, `top-right`, `bottom-left`, `bottom-right`, `top`, `bottom`, `left`, or `right`.
+
+For example, if you have a bar at the top, then `x=0 y=0` will put the top-left corner of the window directly below the bar.
+If instead you write `x=0 y=0 relative-to="top-right"`, then the top-right corner of the window will align with the top-right corner of the workspace, also directly below the bar.
+When only one side is specified (e.g. top) the window will align to the center of that side.
+
+The coordinates change direction based on `relative-to`.
+For example, by default (top-left), `x=100 y=200` will put the window 100 pixels to the right and 200 pixels down from the top-left corner.
+If you use `x=100 y=200 relative-to="bottom-left"`, it will put the window 100 pixels to the right and 200 pixels *up* from the bottom-left corner.
+
+```kdl
+// Open the Firefox picture-in-picture window at the bottom-left corner of the screen
+// with a small gap.
+window-rule {
+    match app-id="firefox$" title="^Picture-in-Picture$"
+
+    default-floating-position x=32 y=32 relative-to="bottom-left"
+}
+```
+
+You can use single-side `relative-to` to get a dropdown-like effect.
+
+```kdl
+// Example: a "dropdown" terminal.
+window-rule {
+    // Match by "dropdown" app ID.
+    // You need to set this app ID when running your terminal, e.g.:
+    // spawn "alacritty" "--class" "dropdown"
+    match app-id="^dropdown$"
+
+    // Open it as floating.
+    open-floating true
+    // Anchor to the top edge of the screen.
+    default-floating-position x=0 y=0 relative-to="top"
+    // Half of the screen high.
+    default-window-height { proportion 0.5; }
+    // 80% of the screen wide.
+    default-column-width { proportion 0.8; }
+}
+```
+
+#### `scroll-factor`
+
+<sup>Since: 25.02</sup>
+
+Set a scroll factor for all scroll events sent to a window.
+
+This will be multiplied with the scroll factor set for your input device in the [input section](./Configuration:-Input.md#pointing-devices).
+
+```kdl
+// Make scrolling in Firefox a bit slower.
+window-rule {
+    match app-id="firefox$"
+
+    scroll-factor 0.75
+}
+```
+
+#### `draw-border-with-background`
+
+Override whether the border and the focus ring draw with a background.
+
+Set this to `true` to draw them as solid colored rectangles even for windows which agreed to omit their client-side decorations.
+Set this to `false` to draw them as borders around the window even for windows which use client-side decorations.
+
+This property can be useful for rectangular windows that do not support the xdg-decoration protocol.
+
+| With Background                                  | Without Background                                  |
+| ------------------------------------------------ | --------------------------------------------------- |
+| ![A screenshot displaying a window with draw-border-with-background set to true](./img/simple-egl-border-with-background.png) | ![A screenshot displaying a window with draw-border-with-background set to false](./img/simple-egl-border-without-background.png) |
+
+```kdl
+window-rule {
+    draw-border-with-background false
+}
+```
+
+#### `focus-ring` and `border`
+
+<sup>Since: 0.1.6</sup>
+
+Override the focus ring and border options for the window.
+
+These rules have the same options as the normal [`focus-ring` and `border` config in the layout section](./Configuration:-Layout.md#focus-ring-and-border), so check the documentation there.
+
+However, in addition to `off` to disable the border/focus ring, this window rule has an `on` flag that enables the border/focus ring for the window even if it was otherwise disabled.
+The `on` flag has precedence over the `off` flag, in case both are set.
+
+```kdl
+window-rule {
+    focus-ring {
+        off
+        width 2
+    }
+}
+
+window-rule {
+    border {
+        on
+        width 8
+    }
+}
+```
+
+#### `shadow`
+
+<sup>Since: 25.02</sup>
+
+Override the shadow options for the window.
+
+This rule has the same options as the normal [`shadow` config in the layout section](./Configuration:-Layout.md#shadow), so check the documentation there.
+
+However, in addition to `on` to enable the shadow, this window rule has an `off` flag that disables the shadow for the window even if it was otherwise enabled.
+The `on` flag has precedence over the `off` flag, in case both are set.
+
+```kdl
+// Turn on shadows for floating windows.
+window-rule {
+    match is-floating=true
+
+    shadow {
+        on
+    }
+}
+```
+
+#### `tab-indicator`
+
+<sup>Since: 25.02</sup>
+
+Override the tab indicator options for the window.
+
+Options in this rule match the same options as the normal [`tab-indicator` config in the layout section](./Configuration:-Layout.md#tab-indicator), so check the documentation there.
+
+```kdl
+// Make KeePassXC tab have a dark red inactive color.
+window-rule {
+    match app-id=r#"^org\.keepassxc\.KeePassXC$"#
+
+    tab-indicator {
+        inactive-color "darkred"
+    }
+}
+```
+
+#### `geometry-corner-radius`
+
+<sup>Since: 0.1.6</sup>
+
+Set the corner radius of the window.
+
+On its own, this setting will only affect the border and the focus ring—they will round their corners to match the geometry corner radius.
+If you'd like to force-round the corners of the window itself, set [`clip-to-geometry true`](#clip-to-geometry) in addition to this setting.
+
+```kdl
+window-rule {
+    geometry-corner-radius 12
+}
+```
+
+The radius is set in logical pixels, and controls the radius of the window itself, that is, the inner radius of the border:
+
+![A screenshot showing a window with every corner rounded](./img/geometry-corner-radius.png)
+
+Instead of one radius, you can set four, for each corner.
+The order is the same as in CSS: top-left, top-right, bottom-right, bottom-left.
+
+```kdl
+window-rule {
+    geometry-corner-radius 8 8 0 0
+}
+```
+
+This way, you can match GTK 3 applications which have square bottom corners:
+
+![A screenshot showing a window with only the top corners rounded](./img/different-corner-radius.png)
+
+#### `clip-to-geometry`
+
+<sup>Since: 0.1.6</sup>
+
+Clips the window to its visual geometry.
+
+This will cut out any client-side window shadows, and also round window corners according to `geometry-corner-radius`.
+
+![A screenshot showing a window with rounded corners, clipped to the visual geometry](./img/clip-to-geometry.png)
+
+```kdl
+window-rule {
+    clip-to-geometry true
+}
+```
+
+Enable border, set [`geometry-corner-radius`](#geometry-corner-radius) and `clip-to-geometry`, and you've got a classic setup:
+
+![A screenshot showing a window with rounded corners, and a border](./img/border-radius-clip.png)
+
+```kdl
+prefer-no-csd
+
+layout {
+    focus-ring {
+        off
+    }
+
+    border {
+        width 2
+    }
+}
+
+window-rule {
+    geometry-corner-radius 12
+    clip-to-geometry true
+}
+```
+
+#### `tiled-state`
+
+<sup>Since: 25.05</sup>
+
+Informs the window that it is tiled.
+Usually, windows will react by becoming rectangular and hiding their client-side shadows.
+Windows that snap their size to a grid (e.g. terminals like [foot](https://codeberg.org/dnkl/foot)) will usually disable this snapping when they are tiled.
+
+By default, niri will set the tiled state to `true` together with [`prefer-no-csd`](./Configuration:-Miscellaneous.md#prefer-no-csd) in order to improve behavior for apps that don't support server-side decorations.
+You can use this window rule to override this, for example to get rectangular windows with CSD.
+
+```kdl
+// Make tiled windows rectangular while using CSD.
+window-rule {
+    match is-floating=false
+
+    tiled-state true
+}
+```
+
+#### `baba-is-float`
+
+<sup>Since: 25.02</sup>
+
+Make your windows FLOAT up and down.
+
+This is an April Fools' 2025 feature.
+
+```kdl
+window-rule {
+    match is-floating=true
+
+    baba-is-float true
+}
+```
+
+<video controls src="https://github.com/user-attachments/assets/3f4cb1a4-40b2-4766-98b7-eec014c19509">
+
+https://github.com/user-attachments/assets/3f4cb1a4-40b2-4766-98b7-eec014c19509
+
+</video>
+
+#### Size Overrides
+
+You can amend the window's minimum and maximum size in logical pixels.
+
+Keep in mind that the window itself always has a final say in its size.
+These values instruct niri to never ask the window to be smaller than the minimum you set, or to be bigger than the maximum you set.
+
+> [!NOTE]
+> `max-height` will only apply to automatically-sized windows if it is equal to `min-height`.
+> Either set it equal to `min-height`, or change the window height manually after opening it with `set-window-height`.
+>
+> This is a limitation of niri's window height distribution algorithm.
+
+```kdl
+window-rule {
+    min-width 100
+    max-width 200
+    min-height 300
+    max-height 300
+}
+```
+
+```kdl
+// Fix OBS with server-side decorations missing a minimum width.
+window-rule {
+    match app-id=r#"^com\.obsproject\.Studio$"#
+
+    min-width 876
+}
+```

docs/wiki/Development:-Animation-Timing.md

@@ -0,0 +1,46 @@
+> *Time, Dr. Freeman? Is it really that... time again?*
+
+A compositor deals with one or more monitors on mostly fixed refresh cycles.
+For example, a 170 Hz monitor can draw a frame every ~5.88 ms.
+
+Most of the time, the compositor doesn't actually redraw the monitor: when nothing changes on screen (e.g. you're reading a document and aren't moving your cursor), it would be wasteful to wake up the GPU to composite the same image.
+During an animation however, screen contents do change every frame.
+Niri will generally start drawing the next frame as soon as the previous one shows up on screen.
+
+Since the monitor refresh cycle is fixed in most cases (even with VRR, there's a maximum refresh rate), the compositor can predict when the next frame will show up on the monitor, and render ongoing animations for that exact moment in time.
+This way, all animation frames are perfectly timed with no jitter, regardless of when exactly the rendering code had a chance to run.
+For example, even if the compositor has to process new window events, delaying the rendering by a few ms, the animation timing will remain exactly aligned to the monitor refresh cycle.
+
+There are hence several properties that a compositor wants from its timing system.
+
+1. It should be possible to get the state of the animations at a specific time in the near future, for rendering a frame exactly timed to when the monitor will show it.
+    - This time override ability should be usable in tests to advance the time in a fully controlled fashion.
+1. Animations in response to user actions should begin at the moment when the action happens.
+   For example, pressing a workspace switch key should start the animation at the instant when the user pressed the key (rather than, say, slightly in the future where we predicted the next monitor frame, which we had already rendered by now).
+1. During the processing of a single action, querying the current time should return the exact same value.
+   Even if the processing finishes a few microseconds after it started, querying the time in the end should return the same thing.
+   This generally makes writing code much more sane; otherwise you'd need to for example avoid reading the position of some element twice in a row, since it could have moved by one pixel in-between, screwing with the logic.
+   Also, fetching the current system time [can be quite expensive](https://mastodon.online/@YaLTeR/109934977035721850) in terms of overhead.
+1. It should be reasonably easy to implement an animation slow-down preference, so all animations can be slowed down or sped up by the same factor.
+
+The solution in niri is a `LazyClock`, a clock that remembers one timestamp.
+Initially, the timestamp is empty, so when you ask `LazyClock` for the current time, it will fetch and return the system time, and also remember it.
+Subsequently, it will keep returning the same timestamp that it had remembered.
+
+You can also clear the timestamp, then `LazyClock` will fetch the system time anew when it's needed.
+In niri, the timestamp is cleared at the end of every event loop iteration, right before going to sleep waiting for new events.
+This way, anything that happens next (like a user key press) will fetch and use the most up-to-date timestamp as soon as one is needed, but then the processing code will keep getting the exact same timestamp, since `LazyClock` stores it.
+
+You can also just manually set the timestamp to a specific value.
+This is how we render a frame for the predicted time of when the monitor will show it.
+Also, this is used by tests: they simply always set the timestamp and never use the system time.
+
+Finally, there's an `AdjustableClock` wrapper on top that provides the ability to control the slow-down rate by modifying the timestamps returned by the clock.
+
+An important detail is that with rate changes, timestamps from the `AdjustableClock` will drift away and become unrelated to the system time.
+However, our target timestamp (for rendering) comes from the system time, so the override works directly on the underlying `LazyClock`.
+That is, overriding the timestamp and then querying the `AdjustableClock` will return a *different* timestamp that is correct and consistent with the adjustments made by `AdjustableClock`.
+This is reflected in the API by naming the function `Clock::set_unadjusted()` (and there's also `Clock::now_unadjusted()` to get the raw timestamp).
+
+The clock is shared among all animations in niri through passing around and storing a reference-counted pointer.
+This way, overriding the time automatically applies to everything, whereas in tests we can use a separate clock per test so that they don't interfere with each other.

docs/wiki/Development:-Design-Principles.md

@@ -0,0 +1,30 @@
+These are some of the general principles for the design of niri's window layout.
+They can be sidestepped in specific circumstances if there's a good reason.
+
+1. Opening a new window should not affect the sizes of any existing windows.
+1. The focused window should not move around on its own.
+    - In particular: windows opening, closing, and resizing to the left of the focused window should not cause it to visually move.
+1. Actions should apply immediately.
+    - Things like resizing or consuming into column take effect immediately, even if the window needs time to catch up.
+    - This is important both for compositor responsiveness and predictability, and for keeping the code sane and free of edge cases and unnecessary asynchrony.
+1. If a window or popup is larger than the screen, it should be aligned in the top left corner.
+    - The top left area of a window is more likely to contain something important, so it should always be visible.
+1. Setting window width or height to a fixed pixel size (e.g. `set-column-width 1280` or `default-column-width { fixed 1280; }`) will set the size of the window itself, however setting to a proportional size (e.g. `set-column-width 50%`) will set the size of the tile, including the border added by niri.
+    - With proportions, the user is looking to tile multiple windows on the screen, so they should include borders.
+    - With fixed sizes, the user wants to test a specific client size or take a specifically sized screenshot, so they should affect the window directly.
+    - After the size is set, it is always converted to a value that includes the borders, to make the code sane. That is, `set-column-width 1000` followed by changing the niri border width will resize the window accordingly.
+
+And here are some more principles I try to follow throughout niri.
+
+1. When disabled, eye-candy features should not affect the performance.
+    - Things like animations and custom shaders do not run and are not present in the render tree when disabled. Extra offscreen rendering is avoided.
+    - Animations specifically are still "started" even when disabled, but with a duration of 0 (this way, they end as soon as the time is advanced). This does not impact performance, but helps avoid a lot of edge cases in the code.
+1. Eye-candy features should not cause unreasonable excessive rendering.
+    - For example, clip-to-geometry will prevent direct scanout in many cases (since the window surface is not completely visible). But in the cases where the surface or the subsurface *is* completely visible (fully within the clipped region), it will still allow for direct scanout.
+    - For example, animations *can* cause damage and even draw to an offscreen every frame, because they are expected to be short (and can be disabled). However, something like the rounded corners shader should not offscreen or cause excessive damage every frame, because it is long-running and constantly active.
+1. Be mindful of invisible state.
+
+    This is niri state that is not immediately apparent from looking at the screen. This is not bad per se, but you should carefully consider how to reduce the surprise factor.
+
+    - For example, when a monitor disconnects, all its workspaces move to another connected monitor. In order to be able to restore these workspaces when the first monitor connects again, these workspaces keep the knowledge of which was their *original monitor*—this is an example of invisible state, since you can't tell it in any way by looking at the screen. This can have surprising consequences: imagine disconnecting a monitor at home, going to work, completely rearranging the windows there, then coming back home, and suddenly some random workspaces end up on your home monitor. In order to reduce this surprise factor, whenever a new window appears on a workspace, that workspace resets its *original monitor* to its current monitor. This way, the workspaces you actively worked on remain where they were.
+    - For example, niri preserves the view position whenever a window appears, or whenever a window goes full-screen, to restore it afterward. This way, dealing with temporary things like dialogs opening and closing, or toggling full-screen, becomes less annoying, since it doesn't mess up the view position. This is also invisible state, as you cannot tell by looking at the screen where closing a window will restore the view position. If taken to the extreme (previous view position saved forever for every open window), this can be surprising, as closing long-running windows would result in the view shifting around pretty much randomly. To reduce this surprise factor, niri remembers only one last view position per workspace, and forgets this stored view position upon window focus change.

docs/wiki/Development:-Developing-niri.md

@@ -0,0 +1,76 @@
+## Running a Local Build
+
+The main way of testing niri during development is running it as a nested window. The second step is usually switching to a different TTY and running niri there.
+
+Once a feature or fix is reasonably complete, you generally want to run a local build as your main compositor for proper testing. The easiest way to do that is to install niri normally (from a distro package for example), then overwrite the binary with `sudo cp ./target/release/niri /usr/bin/niri`. Do make sure that you know how to revert to a working version in case everything breaks though.
+
+If you use an RPM-based distro, you can generate an RPM package for a local build with `cargo generate-rpm`.
+
+## Logging Levels
+
+Niri uses [`tracing`](https://lib.rs/crates/tracing) for logging. This is how logging levels are used:
+
+- `error!`: programming errors and bugs that are recoverable. Things you'd normally use `unwrap()` for. However, when a Wayland compositor crashes, it brings down the entire session, so it's better to recover and log an `error!` whenever reasonable. If you see an `ERROR` in the niri log, that always indicates a *bug*.
+- `warn!`: something bad but still *possible* happened. Informing the user that they did something wrong, or that their hardware did something weird, falls into this category. For example, config parsing errors should be indicated with a `warn!`.
+- `info!`: the most important messages related to normal operation. Running niri with `RUST_LOG=niri=info` should not make the user want to disable logging altogether.
+- `debug!`: less important messages related to normal operation. Running niri with `debug!` messages hidden should not negatively impact the UX.
+- `trace!`: everything that can be useful for debugging but is otherwise too spammy or performance intensive. `trace!` messages are *compiled out* of release builds.
+
+## Tests
+
+We have some unit tests, most prominently for the layout code and for config parsing.
+
+When adding new operations to the layout, add them to the `Op` enum at the bottom of `src/layout/mod.rs` (this will automatically include it in the randomized tests), and if applicable to the `every_op` arrays below.
+
+When adding new config options, include them in the config parsing test.
+
+### Running Tests
+
+Make sure to run `cargo test --all` to run tests from sub-crates too.
+
+Some tests are a bit too slow to run normally, like the randomized tests of the layout code, so they are normally skipped. Set the `RUN_SLOW_TESTS` variable to run them:
+
+```
+env RUN_SLOW_TESTS=1 cargo test --all
+```
+
+It also usually helps to run the randomized tests for a longer period, so that they can explore more inputs. You can control this with environment variables. This is how I usually run tests before pushing:
+
+```
+env RUN_SLOW_TESTS=1 PROPTEST_CASES=200000 PROPTEST_MAX_GLOBAL_REJECTS=200000 RUST_BACKTRACE=1 cargo test --release --all
+```
+
+### Visual Tests
+
+The `niri-visual-tests` sub-crate is a GTK application that runs hard-coded test cases so that you can visually check that they look right. It uses mock windows with the real layout and rendering code. It is especially helpful when working on animations.
+
+## Profiling
+
+We have integration with the [Tracy](https://github.com/wolfpld/tracy) profiler which you can enable by building niri with a feature flag:
+
+```
+cargo build --release --features=profile-with-tracy-ondemand
+```
+
+Then you can open Tracy (you will need the latest stable release) and attach to a running niri instance to collect profiling data. Profiling data is collected "on demand"—that is, only when Tracy is connected. You can run a niri build like this as your main compositor if you'd like.
+
+> [!NOTE]
+> If you need to profile niri startup or the niri CLI, you can opt for "always on" profiling instead, using this feature flag:
+>
+> ```
+> cargo build --release --features=profile-with-tracy
+> ```
+>
+> When compiled this way, niri will **always** collect profiling data, so you can't run a build like this as your main compositor.
+
+To make a niri function show up in Tracy, instrument it like this:
+
+```rust
+pub fn some_function() {
+    let _span = tracy_client::span!("some_function");
+
+    // Code of the function.
+}
+```
+
+You can also enable Rust memory allocation profiling with `--features=profile-with-tracy-allocations`.

docs/wiki/Development:-Documenting-niri.md

@@ -0,0 +1,85 @@
+niri's documentation files are found in `docs/wiki/` and should be viewable and browsable in at least three systems:
+
+- The GitHub repo's markdown file preview
+- [The GitHub repo's wiki](https://github.com/YaLTeR/niri/wiki)
+- [The documentation site](https://yalter.github.io/niri/)
+
+## The GitHub repo's wiki
+
+This is generated with the `publish-wiki` job in `.github/workflows/ci.yml`.
+In order to have this job run as expected in your fork, you'll need to enable the wiki feature in your repo's settings on GitHub.
+This could be useful as a contributor to verify that the wiki generates the way you expect it to.
+
+## The documentation site
+
+The documentation site is generated with [mkdocs](https://www.mkdocs.org/).
+The configuration files are found in `docs/`.
+
+To set up and run the documentation site locally, it is recommended to use [uv](https://docs.astral.sh/uv/).
+
+### Serving the site locally with uv
+
+In the `docs/` subdirectory:
+
+- `uv sync`
+- `uv run mkdocs serve`
+
+The documentation site should now be available on http://127.0.0.1:8000/niri/
+
+Changes made to the documentation while the development server is running will cause an automatic page refresh in the browser.
+
+> [!TIP]
+> Images may not be visible, as they are stored on Git LFS.
+> If this is the case, run `git lfs pull`.
+
+## Elements
+
+Elements such as links, admonitions, images, and snippets should work as expected in markdown file previews on GitHub, the GitHub repo's wiki, and in the documentation site.
+
+### Links
+
+Links should in all cases be relative (e.g. `./FAQ.md`), unless it's an external one.
+Links should have anchors if they are meant to lead the user to a specific section on a page (e.g. `./Getting-Started.md#nvidia`).
+
+> [!TIP]
+> mkdocs will terminate if relative links lead to non-existing documents or non-existing anchors.
+> This means that the CI pipeline will fail when building documentation, as will `mkdocs serve` locally.
+
+### Admonitions
+
+> [!IMPORTANT]
+> This is an important distinction from other `mkdocs`-based documentation you might have encountered.
+
+Admonitions, or alerts should be written [the way GitHub defines them](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts).
+The above admonition is written like this:
+
+```
+> [!IMPORTANT]
+> This is an important distinction from other `mkdocs`-based documentation you might have encountered.
+```
+
+### Images
+
+Images should have relative links to resources in `docs/wiki/img/`, and should contain sensible alt-text.
+
+### Videos
+
+For compatibility with both mkdocs and GitHub Wiki, videos need to be wrapped in a `<video>` tag (displayed by mkdocs) and have the video link again as fallback text (displayed by GitHub Wiki) padded with blank lines.
+
+```html
+<video controls src="https://github.com/user-attachments/assets/379a5d1f-acdb-4c11-b36c-e85fd91f0995">
+
+https://github.com/user-attachments/assets/379a5d1f-acdb-4c11-b36c-e85fd91f0995
+
+</video>
+```
+
+### Snippets
+
+Configuration and code snippets in general should be annotated with a language.
+
+If the language used in the snippet is KDL, open the code block like this:
+
+```md
+```kdl
+```

docs/wiki/Development:-Fractional-Layout.md

@@ -0,0 +1,35 @@
+There are two main coordinate spaces in niri: physical (pixels of every individual output) and logical (shared among all outputs, takes into account the scale of every output).
+Wayland clients mostly work in the logical space, and it's the most convenient space to do all the layout in, since it bakes in the output scaling factor.
+
+However, many things need to be sized or positioned at integer physical coordinates.
+For example, Wayland toplevel buffers are assumed to be placed at an integer physical pixel on an output (and `WaylandSurfaceRenderElement` will do that for you).
+Borders and focus rings should also have a width equal to an integer number of physical pixels to stay crisp (not to mention that `SolidColorRenderElement` does not anti-alias lines at fractional pixel positions).
+
+Integer physical coordinates do not necessarily correspond to integer logical coordinates though.
+Even with an integer scale = 2, a physical pixel at (1, 1) will be at the logical position of (0.5, 0.5).
+This problem becomes much worse with fractional scale factors where most integer logical coordinates will fall on fractional physical coordinates.
+
+Thus, niri uses fractional logical coordinates for most of its layout.
+However, one needs to be very careful to keep things aligned to the physical grid to avoid artifacts like:
+
+* Border width alternating 1 px thicker/thinner
+* Border showing 1 px off from the window at certain positions
+* 1 px gaps around rounded corners
+* Slightly blurry window contents during resizes
+* And so on...
+
+The way it's handled in niri is:
+
+1. All relevant sizes on a workspace are rounded to an integer physical coordinate according to the current output scale. Things like struts, gaps, border widths, working area location.
+
+    It's important to understand that they remain fractional numbers in the logical space, but these numbers correspond to an integer number of pixels in the physical space.
+    The rounding looks something like: `(logical_size * scale).round() / scale`.
+    Whenever a workspace moves to an output with a different scale (or the output scale changes), all sizes are re-rounded from their original configured values to align with the new physical space.
+
+2. The view offset and individual column/tile render offsets are *not* rounded to physical pixels, but:
+3. `tiles_with_render_positions()` rounds tile positions to physical pixels as it returns them,
+4. Custom shaders like opening, closing and resizing windows, are also careful to keep positions and sizes rounded to the physical pixels.
+
+The idea is that every tile can assume that it is rendered at an integer physical coordinate, therefore when shifting the position by, say, border width (also rounded to integer physical coordinates), the new position will stay rounded to integer physical coordinates.
+The same logic works for the rest of the layout thanks to gaps, struts and working area being similarly rounded.
+This way, the entire layout is always aligned, as long as it is positioned at an integer physical coordinate (which rounding the tile positions effectively achieves).

docs/wiki/Development:-Redraw-Loop.md

@@ -0,0 +1,22 @@
+On a TTY, only one frame can be submitted to an output at a time, and the compositor must wait until the output repaints (indicated by a VBlank) to be able to submit the next frame.
+In niri we keep track of this via the `RedrawState` enum that you can find in an `OutputState`.
+
+Here's a diagram of state transitions for the `RedrawState` state machine:
+
+<picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./img/RedrawState-dark.drawio.png">
+    <img alt="RedrawState state transition diagram" src="./img/RedrawState-light.drawio.png">
+</picture>
+
+`Idle` is the default state, when the output does not need to be repainted.
+Any operation that may cause the screen to update calls `queue_redraw()`, which moves the output to a `Queued` state.
+Then, at the end of an event loop dispatch, niri calls `redraw()` for every `Queued` output.
+
+If the redraw causes damage (i.e. something on the output changed), we move into the `WaitingForVBlank` state, since we cannot redraw until we receive a VBlank event.
+However, if there's no damage, we do not return to `Idle` right away.
+Instead, we set a timer to fire roughly at when the next VBlank would occur, and transition to a `WaitingForEstimatedVBlank` state.
+
+This is necessary in order to throttle frame callbacks sent to applications to at most once per output refresh cycle.
+Without this throttling, applications can start continuously redrawing without damage (for instance, if the application window is partially off-screen, and it is only the off-screen part that changes), and eating a lot of CPU in the process.
+
+Then, either the estimated VBlank timer completes, and we go back to `Idle`, or maybe we call `queue_redraw()` once more and try to redraw again.

docs/wiki/Example-systemd-Setup.md

@@ -0,0 +1,76 @@
+When starting niri from a display manager like GDM, or otherwise through the `niri-session` binary, it runs as a systemd service.
+This provides the necessary systemd integration to run programs like `mako` and services like `xdg-desktop-portal` bound to the graphical session.
+
+Here's an example on how you might set up [`mako`](https://github.com/emersion/mako), [`waybar`](https://github.com/Alexays/Waybar), [`swaybg`](https://github.com/swaywm/swaybg) and [`swayidle`](https://github.com/swaywm/swayidle) to run as systemd services with niri.
+Unlike [`spawn-at-startup`](./Configuration:-Miscellaneous.md#spawn-at-startup), this lets you easily monitor their status and output, and restart or reload them.
+
+1. Install them, i.e. `sudo dnf install mako waybar swaybg swayidle`
+2. `mako` and `waybar` provide systemd units out of the box, so you can simply add them to the niri session:
+
+    ```
+    systemctl --user add-wants niri.service mako.service
+    systemctl --user add-wants niri.service waybar.service
+    ```
+
+    This will create links in `~/.config/systemd/user/niri.service.wants/`, a special systemd folder for services that need to start together with `niri.service`.
+
+3. `swaybg` does not provide a systemd unit, since you need to pass the background image as a command-line argument.
+    So we will make our own.
+    Create `~/.config/systemd/user/swaybg.service` with the following contents:
+
+    ```systemd
+    [Unit]
+    PartOf=graphical-session.target
+    After=graphical-session.target
+    Requisite=graphical-session.target
+
+    [Service]
+    ExecStart=/usr/bin/swaybg -m fill -i "%h/Pictures/LakeSide.png"
+    Restart=on-failure
+    ```
+
+    Replace the image path with the one you want.
+    `%h` is expanded to your home directory.
+
+    After editing `swaybg.service`, run `systemctl --user daemon-reload` so systemd picks up the changes in the file.
+
+    Now, add it to the niri session:
+
+    ```
+    systemctl --user add-wants niri.service swaybg.service
+    ```
+
+4. `swayidle` similarly does not provide a service, so we will also make our own.
+    Create `~/.config/systemd/user/swayidle.service` with the following contents:
+
+    ```systemd
+    [Unit]
+    PartOf=graphical-session.target
+    After=graphical-session.target
+    Requisite=graphical-session.target
+
+    [Service]
+    ExecStart=/usr/bin/swayidle -w timeout 601 'niri msg action power-off-monitors' timeout 600 'swaylock -f' before-sleep 'swaylock -f'
+    Restart=on-failure
+    ```
+
+    Then, run `systemctl --user daemon-reload` and add it to the niri session:
+
+    ```
+    systemctl --user add-wants niri.service swayidle.service
+    ```
+
+That's it!
+Now these three utilities will be started together with the niri session and stopped when it exits.
+You can also restart them with a command like `systemctl --user restart waybar.service`, for example after editing their config files.
+
+To remove a service from niri startup, remove its symbolic link from `~/.config/systemd/user/niri.service.wants/`.
+Then, run `systemctl --user daemon-reload`.
+
+### Running Programs Across Logout
+
+When running niri as a session, exiting it (logging out) will kill all programs that you've started within. However, sometimes you want a program, like `tmux`, `dtach` or similar, to persist in this case. To do this, run it in a transient systemd scope:
+
+```
+systemd-run --user --scope tmux new-session
+```

docs/wiki/FAQ.md

@@ -0,0 +1,85 @@
+### How to disable client-side decorations/make windows rectangular?
+
+Uncomment the [`prefer-no-csd` setting](./Configuration:-Miscellaneous.md#prefer-no-csd) at the top level of the config, and then restart your apps.
+Then niri will ask windows to omit client-side decorations, and also inform them that they are being tiled (which makes some windows rectangular, even if they cannot omit the decorations).
+
+Note that currently this will prevent edge window resize handles from showing up.
+You can still resize windows by holding <kbd>Mod</kbd> and the right mouse button.
+
+### Why are transparent windows tinted? / Why is the border/focus ring showing up through semitransparent windows?
+
+Uncomment the [`prefer-no-csd` setting](./Configuration:-Miscellaneous.md#prefer-no-csd) at the top level of the config, and then restart your apps.
+Niri will draw focus rings and borders *around* windows that agree to omit their client-side decorations.
+
+By default, focus ring and border are rendered as a solid background rectangle behind windows.
+That is, they will show up through semitransparent windows.
+This is because windows using client-side decorations can have an arbitrary shape.
+
+You can also override this behavior with the [`draw-border-with-background` window rule](./Configuration:-Window-Rules.md#draw-border-with-background).
+
+### How to enable rounded corners for all windows?
+
+Put this window rule in your config:
+
+```kdl
+window-rule {
+    geometry-corner-radius 12
+    clip-to-geometry true
+}
+```
+
+For more information, check the [`geometry-corner-radius` window rule](./Configuration:-Window-Rules.md#geometry-corner-radius).
+
+### How to hide the "Important Hotkeys" pop-up at the start?
+
+Put this into your config:
+
+```kdl
+hotkey-overlay {
+    skip-at-startup
+}
+```
+
+### How to run X11 apps like Steam or Discord?
+
+To run X11 apps, you can use [xwayland-satellite](https://github.com/Supreeeme/xwayland-satellite).
+Check [the Xwayland wiki page](./Xwayland.md) for instructions.
+
+Keep in mind that you can run many Electron apps such as VSCode natively on Wayland by passing the right flags, e.g. `code --ozone-platform-hint=auto`
+
+### Why doesn't niri integrate Xwayland like other compositors?
+
+A combination of factors:
+
+- Integrating Xwayland is quite a bit of work, as the compositor needs to implement parts of an X11 window manager.
+- You need to appease the X11 ideas of windowing, whereas for niri I want to have the best code for Wayland.
+- niri doesn't have a good global coordinate system required by X11.
+- You tend to get an endless stream of X11 bugs that take further time and effort away from other tasks.
+- There aren't actually that many X11-only clients nowadays, and xwayland-satellite takes perfect care of most of those.
+- niri isn't a Big Serious Desktop Environment which Must Support All Use Cases (and is Backed By Some Corporation).
+
+All in all, the situation works out in favor of avoiding Xwayland integration.
+
+Also, in the next release niri will have seamless built-in xwayland-satellite integration, that will solve the big rough edge of having to set it up manually.
+
+Besides, I wouldn't be too surprised if, down the road, xwayland-satellite becomes the standard way of integrating Xwayland into new compositors, since it takes on the bulk of the annoying work, and isolates the compositor from misbehaving clients.
+
+### Can I enable blur behind semitransparent windows?
+
+Not yet, follow/upvote [this issue](https://github.com/YaLTeR/niri/issues/54).
+
+There's also [a PR](https://github.com/YaLTeR/niri/pull/1634) adding blur to niri which you can build and run manually.
+Keep in mind that it's an experimental implementation that may have problems and performance concerns.
+
+### Can I make a window sticky / pinned / always on top / appear on all workspaces?
+
+Not yet, follow/upvote [this issue](https://github.com/YaLTeR/niri/issues/932).
+
+You can emulate this with a script that uses the niri IPC.
+For example, [nirius](https://git.sr.ht/~tsdh/nirius) seems to have this feature (`toggle-follow-mode`).
+
+### How do I make the Bitwarden window in Firefox open as floating?
+
+Firefox seems to first open the Bitwarden window with a generic Firefox title, and only later change the window title to Bitwarden, so you can't effectively target it with an `open-floating` window rule.
+
+You'll need to use a script, for example [this one](https://github.com/YaLTeR/niri/discussions/1599) or other ones (search niri issues and discussions for Bitwarden).

docs/wiki/Floating-Windows.md

@@ -0,0 +1,16 @@
+### Overview
+
+<sup>Since: 25.01</sup>
+
+Floating windows in niri always show on top of the tiled windows.
+The floating layout does not scroll.
+Each workspace/monitor has its own floating layout, just like each workspace/monitor has its own tiling layout.
+
+New windows will automatically float if they have a parent (e.g. dialogs) or if they are fixed size (e.g. splash screens).
+To change a window between floating and tiling, you can use the `toggle-window-floating` bind or right click while dragging/moving the window.
+You can also use the `open-floating true/false` window rule to either force a window to open as floating, or to disable the automatic floating logic.
+
+Use `switch-focus-between-floating-and-tiling` to switch the focus between the two layouts.
+When focused on the floating layout, binds (like `focus-column-right`) will operate on the floating window.
+
+You can precisely position a floating window with a command like `niri msg action move-floating-window -x 100 -y 200`.

docs/wiki/Gestures.md

@@ -0,0 +1,93 @@
+### Overview
+
+There are several gestures in niri.
+
+Also see the [gestures configuration](./Configuration:-Gestures.md) wiki page.
+
+### Mouse
+
+#### Interactive Move
+
+<sup>Since: 0.1.10</sup>
+
+You can move windows by holding <kbd>Mod</kbd> and the left mouse button.
+
+You can customize the look of the window insertion preview in the [`insert-hint` layout config](./Configuration:-Layout.md#insert-hint).
+
+<sup>Since: 25.01</sup> Right click while moving to toggle between floating and tiling layout to put the window into.
+
+#### Interactive Resize
+
+<sup>Since: 0.1.6</sup>
+
+You can resize windows by holding <kbd>Mod</kbd> and the right mouse button.
+
+#### Reset Window Height
+
+<sup>Since: 0.1.6</sup>
+
+If you double-click on a top or bottom tiled window resize edge, the window height will reset to automatic.
+
+This works with both window-initiated resizes (when using client-side decorations), and niri-initiated <kbd>Mod</kbd> + right click resizes.
+
+#### Toggle Full Width
+
+<sup>Since: 0.1.6</sup>
+
+If you double-click on a left or right tiled window resize edge, the column will expand to the full workspace width.
+
+This works with both window-initiated resizes (when using client-side decorations), and niri-initiated <kbd>Mod</kbd> + right click resizes.
+
+#### Horizontal View Movement
+
+<sup>Since: 0.1.6</sup>
+
+Move the view horizontally by holding <kbd>Mod</kbd> and the middle mouse button (or the wheel) and dragging the mouse horizontally.
+
+#### Workspace Switch
+
+<sup>Since: 0.1.7</sup>
+
+Switch workspaces by holding <kbd>Mod</kbd> and the middle mouse button (or the wheel) and dragging the mouse vertically.
+
+### Touchpad
+
+#### Workspace Switch
+
+Switch workspaces with three-finger vertical swipes.
+
+#### Horizontal View Movement
+
+Move the view horizontally with three-finger horizontal swipes.
+
+### All Pointing Devices
+
+#### Drag-and-Drop Edge View Scroll
+
+<sup>Since: 25.02</sup>
+
+Scroll the tiling view when moving the mouse cursor against a monitor edge during drag-and-drop (DnD).
+Also works on a touchscreen.
+
+#### Drag-and-Drop Edge Workspace Switch
+
+<sup>Since: 25.05</sup>
+
+Scroll the workspaces up/down when moving the mouse cursor against a monitor edge during drag-and-drop (DnD) while in the overview.
+Also works on a touchscreen.
+
+#### Drag-and-Drop Hold to Activate
+
+<sup>Since: 25.05</sup>
+
+While drag-and-dropping, hold your mouse over a window to activate it.
+This will bring a floating window to the top for example.
+
+In the overview, you can also hold the mouse over a workspace to switch to it.
+
+#### Hot Corner to Toggle the Overview
+
+<sup>Since: 25.05</sup>
+
+Put your mouse at the very top-left corner of a monitor to toggle the overview.
+Also works during drag-and-dropping something.

docs/wiki/Getting-Started.md

@@ -0,0 +1,196 @@
+The easiest way to get niri is to install one of the distribution packages.
+Here are some of them: [Fedora COPR](https://copr.fedorainfracloud.org/coprs/yalter/niri/) and [nightly COPR](https://copr.fedorainfracloud.org/coprs/yalter/niri-git/) (which I maintain myself), [NixOS Flake](https://github.com/sodiboo/niri-flake), and some more from repology below.
+See the [Building](#building) section if you'd like to compile niri yourself and the [Packaging niri](./Packaging-niri.md) page if you want to package niri.
+
+[![Packaging status](https://repology.org/badge/vertical-allrepos/niri.svg)](https://repology.org/project/niri/versions)
+
+After installing, start niri from your display manager like GDM.
+Press <kbd>Super</kbd><kbd>T</kbd> to run a terminal ([Alacritty]) and <kbd>Super</kbd><kbd>D</kbd> to run an application launcher ([fuzzel]).
+To exit niri, press <kbd>Super</kbd><kbd>Shift</kbd><kbd>E</kbd>.
+
+If you're not using a display manager, you should run `niri-session` (systemd/dinit) or `niri --session` (others) from a TTY.
+The `--session` flag will make niri import its environment variables globally into the system manager and D-Bus, and start its D-Bus services.
+The `niri-session` script will additionally start niri as a systemd/dinit service, which starts up a graphical session target required by some services like portals.
+
+You can also run `niri` inside an existing desktop session.
+Then it will open as a window, where you can give it a try.
+Note that this windowed mode is mainly meant for development, so it is a bit buggy (in particular, there are issues with hotkeys).
+
+Next, see the [list of important software](./Important-Software.md) required for normal desktop use, like a notification daemon and portals.
+Also, check the [configuration introduction](./Configuration:-Introduction.md) page to get started configuring niri.
+There you can find links to other pages containing thorough documentation and examples for all options.
+Finally, the [Xwayland](./Xwayland.md) page explains how to run X11 applications on niri.
+
+### Desktop environments
+
+Some desktop environments and shells work with niri and can give a more out-of-the-box experience:
+
+- [LXQt](https://lxqt-project.org/) officially supports niri, see [their wiki](https://github.com/lxqt/lxqt/wiki/ConfigWaylandSettings#general) for details on setting it up.
+- Many [XFCE](https://www.xfce.org/) components work on Wayland, including niri. See [their wiki](https://wiki.xfce.org/releng/wayland_roadmap#component_specific_status) for details.
+- There are complete desktop shells based on Quickshell that support niri, for example [DankMaterialShell](https://github.com/AvengeMedia/DankMaterialShell) and [Noctalia](https://github.com/noctalia-dev/noctalia-shell).
+- You can run a [COSMIC](https://system76.com/cosmic/) session with niri using [cosmic-ext-extra-sessions](https://github.com/Drakulix/cosmic-ext-extra-sessions).
+
+### NVIDIA
+
+The NVIDIA drivers currently have an issue with high VRAM usage due to a heap reuse quirk.
+You're recommended to apply a manual fix documented [here](./Nvidia.md) if you run niri on an NVIDIA GPU.
+
+NVIDIA GPUs can have problems running niri (for example, the screen remains black upon starting from a TTY).
+Sometimes, the problems can be fixed.
+You can try the following:
+
+1. Update NVIDIA drivers. You need a GPU and drivers recent enough to support GBM.
+2. Make sure kernel modesetting is enabled. This usually involves adding `nvidia-drm.modeset=1` to the kernel command line. Find and follow a guide for your distribution. Guides from other Wayland compositors can help.
+
+### Asahi, ARM, and other kmsro devices
+
+On some of these systems, niri fails to correctly detect the primary render device.
+If you're getting a black screen when starting niri on a TTY, you can try to set the device manually.
+
+First, find which devices you have:
+
+```
+$ ls -l /dev/dri/
+drwxr-xr-x@       - root 14 мая 07:07 by-path
+crw-rw----@   226,0 root 14 мая 07:07 card0
+crw-rw----@   226,1 root 14 мая 07:07 card1
+crw-rw-rw-@ 226,128 root 14 мая 07:07 renderD128
+crw-rw-rw-@ 226,129 root 14 мая 07:07 renderD129
+```
+
+You will likely have one `render` device and two `card` devices.
+
+Open the niri config file at `~/.config/niri/config.kdl` and put your `render` device path like this:
+
+```kdl
+debug {
+    render-drm-device "/dev/dri/renderD128"
+}
+```
+
+Save, then try to start niri again.
+If you still get a black screen, try using each of the `card` devices.
+
+### Nix/NixOS
+
+There's a common problem of mesa drivers going out of sync with niri, so make sure your system mesa version matches the niri mesa version.
+When this happens, you usually see a black screen when trying to start niri from a TTY.
+
+Also, on Intel graphics, you may need a workaround described [here](https://nixos.wiki/wiki/Intel_Graphics).
+
+### Virtual Machines
+
+To run niri in a VM, make sure to enable 3D acceleration.
+
+## Main Default Hotkeys
+
+When running on a TTY, the Mod key is <kbd>Super</kbd>.
+When running in a window, the Mod key is <kbd>Alt</kbd>.
+
+The general system is: if a hotkey switches somewhere, then adding <kbd>Ctrl</kbd> will move the focused window or column there.
+
+| Hotkey | Description |
+| ------ | ----------- |
+| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>/</kbd> | Show a list of important niri hotkeys |
+| <kbd>Mod</kbd><kbd>T</kbd> | Spawn `alacritty` (terminal) |
+| <kbd>Mod</kbd><kbd>D</kbd> | Spawn `fuzzel` (application launcher) |
+| <kbd>Super</kbd><kbd>Alt</kbd><kbd>L</kbd> | Spawn `swaylock` (screen locker) |
+| <kbd>Mod</kbd><kbd>Q</kbd> | Close the focused window |
+| <kbd>Mod</kbd><kbd>H</kbd> or <kbd>Mod</kbd><kbd>←</kbd> | Focus the column to the left |
+| <kbd>Mod</kbd><kbd>L</kbd> or <kbd>Mod</kbd><kbd>→</kbd> | Focus the column to the right |
+| <kbd>Mod</kbd><kbd>J</kbd> or <kbd>Mod</kbd><kbd>↓</kbd> | Focus the window below in a column |
+| <kbd>Mod</kbd><kbd>K</kbd> or <kbd>Mod</kbd><kbd>↑</kbd> | Focus the window above in a column |
+| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>H</kbd> or <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>←</kbd> | Move the focused column to the left |
+| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>L</kbd> or <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>→</kbd> | Move the focused column to the right |
+| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>J</kbd> or <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>↓</kbd> | Move the focused window below in a column |
+| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>K</kbd> or <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>↑</kbd> | Move the focused window above in a column |
+| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>H</kbd><kbd>J</kbd><kbd>K</kbd><kbd>L</kbd> or <kbd>Mod</kbd><kbd>Shift</kbd><kbd>←</kbd><kbd>↓</kbd><kbd>↑</kbd><kbd>→</kbd> | Focus the monitor to the side |
+| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>Shift</kbd><kbd>H</kbd><kbd>J</kbd><kbd>K</kbd><kbd>L</kbd> or <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>Shift</kbd><kbd>←</kbd><kbd>↓</kbd><kbd>↑</kbd><kbd>→</kbd> | Move the focused column to the monitor to the side |
+| <kbd>Mod</kbd><kbd>U</kbd> or <kbd>Mod</kbd><kbd>PageDown</kbd> | Switch to the workspace below |
+| <kbd>Mod</kbd><kbd>I</kbd> or <kbd>Mod</kbd><kbd>PageUp</kbd> | Switch to the workspace above |
+| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>U</kbd> or <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>PageDown</kbd> | Move the focused column to the workspace below |
+| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>I</kbd> or <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>PageUp</kbd> | Move the focused column to the workspace above |
+| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>U</kbd> or <kbd>Mod</kbd><kbd>Shift</kbd><kbd>PageDown</kbd> | Move the focused workspace down |
+| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>I</kbd> or <kbd>Mod</kbd><kbd>Shift</kbd><kbd>PageUp</kbd> | Move the focused workspace up |
+| <kbd>Mod</kbd><kbd>,</kbd> | Consume the window to the right into the focused column |
+| <kbd>Mod</kbd><kbd>.</kbd> | Expel the bottom window in the focused column into its own column |
+| <kbd>Mod</kbd><kbd>[</kbd> | Consume or expel the focused window to the left |
+| <kbd>Mod</kbd><kbd>]</kbd> | Consume or expel the focused window to the right |
+| <kbd>Mod</kbd><kbd>R</kbd> | Toggle between preset column widths |
+| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>R</kbd> | Toggle between preset column heights |
+| <kbd>Mod</kbd><kbd>F</kbd> | Maximize column |
+| <kbd>Mod</kbd><kbd>C</kbd> | Center column within view |
+| <kbd>Mod</kbd><kbd>-</kbd> | Decrease column width by 10% |
+| <kbd>Mod</kbd><kbd>=</kbd> | Increase column width by 10% |
+| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>-</kbd> | Decrease window height by 10% |
+| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>=</kbd> | Increase window height by 10% |
+| <kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>R</kbd> | Reset window height back to automatic |
+| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>F</kbd> | Toggle full-screen on the focused window |
+| <kbd>Mod</kbd><kbd>V</kbd> | Move the focused window between the floating and the tiling layout |
+| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>V</kbd> | Switch focus between the floating and the tiling layout |
+| <kbd>PrtSc</kbd> | Take an area screenshot. Select the area to screenshot with mouse, then press Space to save the screenshot, or Escape to cancel |
+| <kbd>Alt</kbd><kbd>PrtSc</kbd> | Take a screenshot of the focused window to clipboard and to `~/Pictures/Screenshots/` |
+| <kbd>Ctrl</kbd><kbd>PrtSc</kbd> | Take a screenshot of the focused monitor to clipboard and to `~/Pictures/Screenshots/` |
+| <kbd>Mod</kbd><kbd>Shift</kbd><kbd>E</kbd> or <kbd>Ctrl</kbd><kbd>Alt</kbd><kbd>Delete</kbd> | Exit niri |
+
+## Building
+
+First, install the dependencies for your distribution.
+
+- Ubuntu 24.04:
+
+    ```sh
+    sudo apt-get install -y gcc clang libudev-dev libgbm-dev libxkbcommon-dev libegl1-mesa-dev libwayland-dev libinput-dev libdbus-1-dev libsystemd-dev libseat-dev libpipewire-0.3-dev libpango1.0-dev libdisplay-info-dev
+    ```
+
+- Fedora:
+
+    ```sh
+    sudo dnf install gcc libudev-devel libgbm-devel libxkbcommon-devel wayland-devel libinput-devel dbus-devel systemd-devel libseat-devel pipewire-devel pango-devel cairo-gobject-devel clang libdisplay-info-devel
+    ```
+
+Next, get latest stable Rust: https://rustup.rs/
+
+Then, build niri with `cargo build --release`.
+
+Check Cargo.toml for a list of build features.
+For example, you can replace systemd integration with dinit integration using `cargo build --release --no-default-features --features dinit,dbus,xdp-gnome-screencast`.
+
+> [!WARNING]
+> Do NOT build with `--all-features`!
+>
+> Some features are meant only for development use.
+> For example, one of the features enables collection of profiling data into a memory buffer that will grow indefinitely until you run out of memory.
+
+### NixOS/Nix
+
+We have a community-maintained flake which provides a devshell with required dependencies. Use `nix build` to build niri, and then run `./results/bin/niri`.
+
+If you're not on NixOS, you may need [NixGL](https://github.com/nix-community/nixGL) to run the resulting binary:
+
+```sh
+nix run --impure github:guibou/nixGL -- ./results/bin/niri
+```
+
+### Manual Installation
+
+If installing directly without a package, the recommended file destinations are slightly different.
+In this case, put the files in the directories indicated in the table below.
+These may vary depending on your distribution.
+
+Don't forget to make sure that the path to `niri` in niri.service is correct.
+This defaults to `/usr/bin/niri`.
+
+| File | Destination |
+| ---- | ----------- |
+| `target/release/niri` | `/usr/local/bin/` |
+| `resources/niri-session` | `/usr/local/bin/` |
+| `resources/niri.desktop`  | `/usr/local/share/wayland-sessions/` |
+| `resources/niri-portals.conf` | `/usr/local/share/xdg-desktop-portal/` |
+| `resources/niri.service` (systemd) | `/etc/systemd/user/` |
+| `resources/niri-shutdown.target` (systemd) | `/etc/systemd/user/` |
+| `resources/dinit/niri` (dinit) | `/etc/dinit.d/user/` |
+| `resources/dinit/niri-shutdown` (dinit) | `/etc/dinit.d/user/` |
+
+[Alacritty]: https://github.com/alacritty/alacritty
+[fuzzel]: https://codeberg.org/dnkl/fuzzel

docs/wiki/IPC.md

@@ -0,0 +1,75 @@
+You can communicate with the running niri instance over an IPC socket.
+Check `niri msg --help` for available commands.
+
+The `--json` flag prints the response in JSON, rather than formatted.
+For example, `niri msg --json outputs`.
+
+> [!TIP]
+> If you're getting parsing errors from `niri msg` after upgrading niri, make sure that you've restarted niri itself.
+> You might be trying to run a newer `niri msg` against an older `niri` compositor.
+
+### Event Stream
+
+<sup>Since: 0.1.9</sup>
+
+While most niri IPC requests return a single response, the event stream request will make niri continuously stream events into the IPC connection until it is closed.
+This is useful for implementing various bars and indicators that update as soon as something happens, without continuous polling.
+
+The event stream IPC is designed to give you the complete current state up-front, then follow up with updates to that state.
+This way, your state can never "desync" from niri, and you don't need to make any other IPC information requests.
+
+Where reasonable, event stream state updates are atomic, though this is not always the case.
+For example, a window may end up with a workspace id for a workspace that had already been removed.
+This can happen if the corresponding workspaces-changed event arrives before the corresponding window-changed event.
+
+To get a taste of the events, run `niri msg event-stream`.
+Though, this is more of a debug function than anything.
+You can get raw events from `niri msg --json event-stream`, or by connecting to the niri socket and requesting an event stream manually.
+
+You can find the full list of events along with documentation [here](https://yalter.github.io/niri/niri_ipc/enum.Event.html).
+
+### Programmatic Access
+
+`niri msg --json` is a thin wrapper over writing and reading to a socket.
+When implementing more complex scripts and modules, you're encouraged to access the socket directly.
+
+Connect to the UNIX domain socket located at `$NIRI_SOCKET` in the filesystem.
+Write your request encoded in JSON on a single line, followed by a newline character, or by flushing and shutting down the write end of the connection.
+Read the reply as JSON, also on a single line.
+
+You can use `socat` to test communicating with niri directly:
+
+```sh
+$ socat STDIO "$NIRI_SOCKET"
+"FocusedWindow"
+{"Ok":{"FocusedWindow":{"id":12,"title":"t socat STDIO /run/u ~","app_id":"Alacritty","workspace_id":6,"is_focused":true}}}
+```
+
+The reply is an `Ok` or an `Err` wrapping the same JSON object as you get from `niri msg --json`.
+
+For more complex requests, you can use `socat` to find how `niri msg` formats them:
+
+```sh
+$ socat STDIO UNIX-LISTEN:temp.sock
+# then, in a different terminal:
+$ env NIRI_SOCKET=./temp.sock niri msg action focus-workspace 2
+# then, look in the socat terminal:
+{"Action":{"FocusWorkspace":{"reference":{"Index":2}}}}
+```
+
+You can find all available requests and response types in the [niri-ipc sub-crate documentation](https://yalter.github.io/niri/niri_ipc/).
+
+### Backwards Compatibility
+
+The JSON output *should* remain stable, as in:
+
+- existing fields and enum variants should not be renamed
+- non-optional existing fields should not be removed
+
+However, new fields and enum variants will be added, so you should handle unknown fields or variants gracefully where reasonable.
+
+The formatted/human-readable output (i.e. without `--json` flag) is **not** considered stable.
+Please prefer the JSON output for scripts, since I reserve the right to make any changes to the human-readable output.
+
+The `niri-ipc` sub-crate (like other niri sub-crates) is *not* API-stable in terms of the Rust semver; rather, it follows the version of niri itself.
+In particular, new struct fields and enum variants will be added.

docs/wiki/Important-Software.md

@@ -0,0 +1,46 @@
+Since niri is not a complete desktop environment, you will very likely want to run the following software to make sure that other apps work fine.
+
+### Notification Daemon
+
+Many apps need one. For example, [mako](https://github.com/emersion/mako) works well. Use [a systemd setup](./Example-systemd-Setup.md) or [`spawn-at-startup`](./Configuration:-Miscellaneous.md#spawn-at-startup).
+
+### Portals
+
+These provide a cross-desktop API for apps to use for various things like file pickers or UI settings. Flatpak apps in particular require working portals.
+
+Portals **require** [running niri as a session](./Getting-Started.md), which means through the `niri-session` script or from a display manager. You will want the following portals installed:
+
+* `xdg-desktop-portal-gtk`: implements most of the basic functionality, this is the "default fallback portal".
+* `xdg-desktop-portal-gnome`: required for screencasting support.
+* `gnome-keyring`: implements the Secret portal, required for certain apps to work.
+
+Then systemd should start them on-demand automatically. These particular portals are configured in `niri-portals.conf` which [must be installed](./Getting-Started.md#manual-installation) in the correct location.
+
+Since we're using `xdg-desktop-portal-gnome`, Flatpak apps will read the GNOME UI settings. For example, to enable the dark style, run:
+
+```
+dconf write /org/gnome/desktop/interface/color-scheme '"prefer-dark"'
+```
+
+Note that if you're using the provided `resources/niri-portals.conf`, you also need to install the `nautilus` file manager in order for file chooser dialogues to work properly. This is necessary because xdg-desktop-portal-gnome uses nautilus as the file chooser by default starting from version 47.0.
+
+If you do not want to install `nautilus` (say you use `nemo` instead), you can set `org.freedesktop.impl.portal.FileChooser=gtk;` in `niri-portals.conf` to use the GTK portal for file chooser dialogues.
+
+### Authentication Agent
+
+Required when apps need to ask for root permissions. Something like `plasma-polkit-agent` works fine. Start it [with systemd](./Example-systemd-Setup.md) or with [`spawn-at-startup`](./Configuration:-Miscellaneous.md#spawn-at-startup).
+
+Note that to start `plasma-polkit-agent` with systemd on Fedora, you'll need to override its systemd service to add the correct dependency. Run:
+
+```
+systemctl --user edit --full plasma-polkit-agent.service
+```
+
+Then add `After=graphical-session.target`.
+
+### Xwayland
+
+To run X11 apps like Steam or Discord, you can use [xwayland-satellite].
+Check [the Xwayland wiki page](./Xwayland.md) for instructions.
+
+[xwayland-satellite]: https://github.com/Supreeeme/xwayland-satellite

docs/wiki/Layer‐Shell-Components.md

@@ -0,0 +1,5 @@
+Things to keep in mind with layer-shell components (bars, launchers, etc.):
+
+1. When a full-screen window is active and covers the entire screen, it will render above the top layer, and it will be prioritized for keyboard focus. If your launcher uses the top layer, and you try to run it while looking at a full-screen window, it won't show up. Only the overlay layer will show up on top of full-screen windows.
+1. Components on the bottom and background layers will receive *on-demand* keyboard focus as expected. However, they will only receive *exclusive* keyboard focus when there are no windows on the workspace.
+1. When opening the [Overview](./Overview.md), components on the bottom and background layers will zoom out and remain on the workspaces, while the top and overlay layers remain on top of the Overview. So, if you want the bar to remain on top, put it on the *top* layer.

docs/wiki/Nvidia.md

@@ -0,0 +1,55 @@
+### High VRAM usage fix
+
+Presently, there is a quirk in the NVIDIA drivers that affects niri's VRAM usage (the driver does not properly release VRAM back into the pool). Niri *should* use on the order of 100 MiB of VRAM (as checked in [nvtop](https://github.com/Syllo/nvtop)); if you see anywhere close to 1 GiB of VRAM in use, you are likely hitting this issue (heap not returning freed buffers to the driver).
+
+Luckily, you can mitigate this by configuring the NVIDIA drivers with a per-process application profile as follows:
+
+* `sudo mkdir -p /etc/nvidia/nvidia-application-profiles-rc.d` to make the config dir if it does not exist (it most likely does not if you are reading this)
+* write the following JSON blob to set the `GLVidHeapReuseRatio` config value for the `niri` process into the file `/etc/nvidia/nvidia-application-profiles-rc.d/50-limit-free-buffer-pool-in-wayland-compositors.json`:
+    
+    ```json
+    {
+        "rules": [
+            {
+                "pattern": {
+                    "feature": "procname",
+                    "matches": "niri"
+                },
+                "profile": "Limit Free Buffer Pool On Wayland Compositors"
+            }
+        ],
+        "profiles": [
+            {
+                "name": "Limit Free Buffer Pool On Wayland Compositors",
+                "settings": [
+                    {
+                        "key": "GLVidHeapReuseRatio",
+                        "value": 0
+                    }
+                ]
+            }
+        ]
+    }
+    ```
+    
+    (The file in `/etc/nvidia/nvidia-application-profiles-rc.d/` can be named anything, and does not actually need an extension).
+
+Restart niri after writing the config file to apply the change.
+
+The upstream issue that this solution was pulled from is [here](https://github.com/NVIDIA/egl-wayland/issues/126#issuecomment-2379945259). There is a (slim) chance that NVIDIA updates their built-in application profiles to apply this to niri automatically; it is unlikely that the underlying heuristic will see a proper fix.
+
+The fix shipped in the driver at the time of writing uses a value of 0, while the initial config posted by an Nvidia engineer approximately a year prior used a value of 1. 
+
+### Screencast flickering fix
+
+<sup>Until: next release</sup>
+
+If you have screencast glitches or flickering on NVIDIA, set this in the niri config:
+
+```kdl,must-fail
+debug {
+    wait-for-frame-completion-in-pipewire
+}
+```
+
+This will become unnecessary once niri supports explicit sync for PipeWire screencasts: https://github.com/YaLTeR/niri/issues/1432

docs/wiki/Overview.md

@@ -0,0 +1,116 @@
+### Overview
+
+<sup>Since: 25.05</sup>
+
+The Overview is a zoomed-out view of your workspaces and windows.
+It lets you see what's going on at a glance, navigate, and drag windows around.
+
+<video controls src="https://github.com/user-attachments/assets/379a5d1f-acdb-4c11-b36c-e85fd91f0995">
+
+https://github.com/user-attachments/assets/379a5d1f-acdb-4c11-b36c-e85fd91f0995
+
+</video>
+
+Open it with the `toggle-overview` bind, via the top-left hot corner, or using a touchpad four-finger swipe up.
+While in the overview, all keyboard shortcuts keep working, while pointing devices get easier:
+
+- Mouse: left click and drag windows to move them, right click and drag to scroll workspaces left/right, scroll to switch workspaces (no holding Mod required).
+- Touchpad: two-finger scrolling that matches the normal three-finger gestures.
+- Touchscreen: one-finger scrolling, or one-finger long press to move a window.
+
+> [!TIP]
+> The overview needs to draw a background under every workspace.
+> So, layer-shell surfaces work this way: the *background* and *bottom* layers zoom out together with the workspaces, while the *top* and *overlay* layers remain on top of the overview.
+>
+> Put your bar on the *top* layer.
+
+Drag-and-drop will scroll the workspaces up/down in the overview, and will activate a workspace when holding it for a moment.
+Combined with the hot corner, this lets you do a mouse-only DnD across workspaces.
+
+<video controls src="https://github.com/user-attachments/assets/5f09c5b7-ff40-462b-8b9c-f1b8073a2cbb">
+
+https://github.com/user-attachments/assets/5f09c5b7-ff40-462b-8b9c-f1b8073a2cbb
+
+</video>
+
+You can also drag-and-drop a window to a new workspace above, below, or between existing workspaces.
+
+<video controls src="https://github.com/user-attachments/assets/b76d5349-aa20-4889-ab90-0a51554c789d">
+
+https://github.com/user-attachments/assets/b76d5349-aa20-4889-ab90-0a51554c789d
+
+</video>
+
+### Configuration
+
+See the full documentation for the `overview {}` section [here](./Configuration:-Miscellaneous.md#overview).
+
+You can set the zoom-out level like this:
+
+```kdl
+// Make workspaces four times smaller than normal in the overview.
+overview {
+    zoom 0.25
+}
+```
+
+To change the color behind the workspaces, use the `backdrop-color` setting:
+
+```kdl
+// Make the backdrop light.
+overview {
+    backdrop-color "#777777"
+}
+```
+
+You can also disable the hot corner:
+
+```kdl
+// Disable the hot corners.
+gestures {
+    hot-corners {
+        off
+    }
+}
+```
+
+### Backdrop customization
+
+Apart from setting a custom backdrop color like described above, you can also put a layer-shell wallpaper into the backdrop with a [layer rule](./Configuration:-Layer-Rules.md#place-within-backdrop), for example:
+
+```kdl
+// Put swaybg inside the overview backdrop.
+layer-rule {
+    match namespace="^wallpaper$"
+    place-within-backdrop true
+}
+```
+
+This will only work for *background* layer surfaces that ignore exclusive zones (typical for wallpaper tools).
+
+You can run two different wallpaper tools (like swaybg and swww), one for the backdrop and one for the normal workspace background.
+This way you could set the backdrop one to a blurred version of the wallpaper for a nice effect.
+
+You can also combine this with a transparent background color if you don't like the wallpaper moving together with workspaces:
+
+```kdl
+// Make the wallpaper stationary, rather than moving with workspaces.
+layer-rule {
+    // This is for swaybg; change for other wallpaper tools.
+    // Find the right namespace by running niri msg layers.
+    match namespace="^wallpaper$"
+    place-within-backdrop true
+}
+
+// Set transparent workspace background color.
+layout {
+    background-color "transparent"
+}
+
+// Optionally, disable the workspace shadows in the overview.
+overview {
+    workspace-shadow {
+        off
+    }
+}
+```

docs/wiki/Packaging-niri.md

@@ -0,0 +1,123 @@
+### Overview
+
+When building niri, check `Cargo.toml` for a list of build features.
+For example, you can replace systemd integration with dinit integration using `cargo build --release --no-default-features --features dinit,dbus,xdp-gnome-screencast`.
+The defaults however should work fine for most distributions.
+
+> [!WARNING]
+> Do NOT build with `--all-features`!
+>
+> Some features are meant only for development use.
+> For example, one of the features enables collection of profiling data into a memory buffer that will grow indefinitely until you run out of memory.
+
+The `niri-visual-tests` sub-crate/binary is development-only and should not be packaged.
+
+The recommended way to package niri is so that it runs as a standalone desktop session.
+To do that, put files into the correct directories according to this table.
+
+| File | Destination |
+| ---- | ----------- |
+| `target/release/niri` | `/usr/bin/` |
+| `resources/niri-session` | `/usr/bin/` |
+| `resources/niri.desktop` | `/usr/share/wayland-sessions/` |
+| `resources/niri-portals.conf` | `/usr/share/xdg-desktop-portal/` |
+| `resources/niri.service` (systemd) | `/usr/lib/systemd/user/` |
+| `resources/niri-shutdown.target` (systemd) | `/usr/lib/systemd/user/` |
+| `resources/dinit/niri` (dinit) | `/usr/lib/dinit.d/user/` |
+| `resources/dinit/niri-shutdown` (dinit) | `/usr/lib/dinit.d/user/` |
+
+Doing this will make niri appear in GDM and other display managers.
+
+### Running tests
+
+A bulk of our tests spawn niri compositor instances and test Wayland clients.
+This does not require a graphical session, however due to test parallelism, it can run into file descriptor limits on high core count systems.
+
+If you run into this problem, you may need to limit not just the Rust test harness thread count, but also the Rayon thread count, since some niri tests use internal Rayon threading:
+
+```
+$ export RAYON_NUM_THREADS=2
+...proceed to run cargo test, perhaps with --test-threads=2
+```
+
+Don't forget to exclude the development-only `niri-visual-tests` crate when running tests.
+
+You may also want to set the `RUN_SLOW_TESTS=1` environment variable to run the slower tests.
+
+### Version string
+
+The niri version string includes its version and commit hash:
+
+```
+$ niri --version
+niri 25.01 (e35c630)
+```
+
+When building in a packaging system, there's usually no repository, so the commit hash is unavailable and the version will show "unknown commit".
+In this case, please set the commit hash manually:
+
+```
+$ export NIRI_BUILD_COMMIT="e35c630"
+...proceed to build niri
+```
+
+You can also override the version string entirely, in this case please make sure the corresponding niri version stays intact:
+
+```
+$ export NIRI_BUILD_VERSION_STRING="25.01-1 (e35c630)"
+...proceed to build niri
+```
+
+Remember to set this variable for both `cargo build` and `cargo install` since the latter will rebuild niri if the environment changes.
+
+### Panics
+
+Good panic backtraces are required for diagnosing niri crashes.
+Please use the `niri panic` command to test that your package produces good backtraces.
+
+```
+$ niri panic
+thread 'main' panicked at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/core/src/time.rs:1142:31:
+overflow when subtracting durations
+stack backtrace:
+   0: rust_begin_unwind
+             at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/std/src/panicking.rs:665:5
+   1: core::panicking::panic_fmt
+             at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/core/src/panicking.rs:74:14
+   2: core::panicking::panic_display
+             at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/core/src/panicking.rs:264:5
+   3: core::option::expect_failed
+             at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/core/src/option.rs:2021:5
+   4: expect<core::time::Duration>
+             at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/core/src/option.rs:933:21
+   5: sub
+             at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/core/src/time.rs:1142:31
+   6: cause_panic
+             at /builddir/build/BUILD/niri-0.0.git.1699.279c8b6a-build/niri/src/utils/mod.rs:382:13
+   7: main
+             at /builddir/build/BUILD/niri-0.0.git.1699.279c8b6a-build/niri/src/main.rs:107:27
+   8: call_once<fn() -> core::result::Result<(), alloc::boxed::Box<dyn core::error::Error, alloc::alloc::Global>>, ()>
+             at /builddir/build/BUILD/rust-1.83.0-build/rustc-1.83.0-src/library/core/src/ops/function.rs:250:5
+note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.
+```
+
+Important things to look for:
+
+- The panic message is there: "overflow when subtracting durations".
+- The backtrace goes all the way up to `main` and includes `cause_panic`.
+- The backtrace includes the file and line number for `cause_panic`: `at /.../src/utils/mod.rs:382:13`.
+
+If possible, please ensure that your niri package on its own has good panics, i.e. *without* installing debuginfo or other packages.
+The user likely won't have debuginfo installed when their compositor first crashes, and we really want to be able to diagnose and fix all crashes right away.
+
+### Rust dependencies
+
+Every niri release comes with a vendored dependencies archive from `cargo vendor`.
+You can use it to build the corresponding niri release completely offline.
+
+If you don't want to use vendored dependencies, consider following the niri release's `Cargo.lock`.
+It contains the exact dependency versions that I used when testing the release.
+
+If you need to change the versions of some dependencies, pay extra attention to `smithay` and `smithay-drm-extras` commit hash.
+These crates don't currently have regular stable releases, so niri uses git snapshots.
+Upstream frequently has breaking changes (API and behavior), so you're strongly advised to use the exact commit hash from the niri release's `Cargo.lock`.

docs/wiki/README.md

@@ -0,0 +1,15 @@
+Welcome to the niri documentation!
+
+Feel free to look through usage and [Getting started](./Getting-Started.md).
+If you're looking for ways to configure niri, check out the [introduction to configuration](./Configuration:-Introduction.md).
+
+If you'd like to help with niri, there are plenty of both coding- and non-coding-related ways to do so.
+See [CONTRIBUTING.md](https://github.com/YaLTeR/niri/blob/main/CONTRIBUTING.md) for an overview.
+
+If you're not already here, check out our new wiki website! https://yalter.github.io/niri/
+
+---
+
+The documentation is open to contribution, see [Documenting niri](./Development:-Documenting-niri.md).
+Please discuss bigger changes in [our Matrix room](https://matrix.to/#/#niri:matrix.org) first!
+The wiki is generated from files in the `docs/wiki/` folder of the repository, so you can open a pull request modifying it there.

docs/wiki/Screencasting.md

@@ -0,0 +1,140 @@
+### Overview
+
+The primary screencasting interface that niri offers is through portals and pipewire.
+It is supported by [OBS], Firefox, Chromium, Electron, Telegram, and other apps.
+You can screencast both monitors and individual windows.
+
+In order to use it, you need a working D-Bus session, pipewire, `xdg-desktop-portal-gnome`, and [running niri as a session](./Getting-Started.md) (i.e. through `niri-session` or from a display manager).
+On widely used distros this should all "just work".
+
+Alternatively, you can use tools that rely on the `wlr-screencopy` protocol, which niri also supports.
+
+There are several features in niri designed for screencasting.
+Let's take a look!
+
+### Block out windows
+
+You can block out specific windows from screencasts, replacing them with solid black rectangles.
+This can be useful for password managers or messenger windows, etc.
+
+![Screenshot showing a window visible normally, but blocked out on OBS.](./img/block-out-from-screencast.png)
+
+This is controlled through the `block-out-from` window rule, for example:
+
+```kdl
+// Block out password managers from screencasts.
+window-rule {
+    match app-id=r#"^org\.keepassxc\.KeePassXC$"#
+    match app-id=r#"^org\.gnome\.World\.Secrets$"#
+
+    block-out-from "screencast"
+}
+```
+
+You can similarly block out layer surfaces, using a layer rule:
+
+```kdl
+// Block out mako notifications from screencasts.
+layer-rule {
+    match namespace="^notifications$"
+
+    block-out-from "screencast"
+}
+```
+
+Check [the corresponding wiki section](./Configuration:-Window-Rules.md#block-out-from) for more details and examples.
+
+### Dynamic screencast target
+
+<sup>Since: 25.05</sup>
+
+Niri provides a special screencast stream that you can change dynamically.
+It shows up as "niri Dynamic Cast Target" in the screencast window dialog.
+
+![Screencast dialog showing niri Dynamic Cast Target.](https://github.com/user-attachments/assets/e236ce74-98ec-4f3a-a99b-29ac1ff324dd)
+
+When you select it, it will start as an empty, transparent video stream.
+Then, you can use the following binds to change what it shows:
+
+- `set-dynamic-cast-window` to cast the focused window.
+- `set-dynamic-cast-monitor` to cast the focused monitor.
+- `clear-dynamic-cast-target` to go back to an empty stream.
+
+You can also use these actions from the command line, for example to interactively pick which window to cast:
+
+```sh
+$ niri msg action set-dynamic-cast-window --id $(niri msg --json pick-window | jq .id)
+```
+
+<video controls src="https://github.com/user-attachments/assets/c617a9d6-7d5e-4f1f-b8cc-9301182d9634">
+
+https://github.com/user-attachments/assets/c617a9d6-7d5e-4f1f-b8cc-9301182d9634
+
+</video>
+
+If the cast target disappears (e.g. the target window closes), the stream goes back to empty.
+
+All dynamic casts share the same target, but new ones start out empty until the next time you change it (to avoid surprises and sharing something sensitive by mistake).
+
+### Indicate screencasted windows
+
+<sup>Since: 25.02</sup>
+
+The [`is-window-cast-target=true` window rule](./Configuration:-Window-Rules.md#is-window-cast-target) matches windows targeted by an ongoing window screencast.
+You use it with a special border color to clearly indicate screencasted windows.
+
+This also works for windows targeted by dynamic screencasts.
+However, it will not work for windows that just happen to be visible in a full-monitor screencast.
+
+```kdl
+// Indicate screencasted windows with red colors.
+window-rule {
+    match is-window-cast-target=true
+
+    focus-ring {
+        active-color "#f38ba8"
+        inactive-color "#7d0d2d"
+    }
+
+    border {
+        inactive-color "#7d0d2d"
+    }
+
+    shadow {
+        color "#7d0d2d70"
+    }
+
+    tab-indicator {
+        active-color "#f38ba8"
+        inactive-color "#7d0d2d"
+    }
+}
+```
+
+Example:
+
+![Screencasted window indicated with a red border and shadow.](https://github.com/user-attachments/assets/375b381e-3a87-4e94-8676-44404971d893)
+
+### Windowed (fake/detached) fullscreen
+
+<sup>Since: 25.05</sup>
+
+When screencasting browser-based presentations like Google Slides, you usually want to hide the browser UI, which requires making the browser fullscreen.
+This is not always convenient, for example if you have an ultrawide monitor, or just want to leave the browser as a smaller window, without taking up an entire monitor.
+
+The `toggle-windowed-fullscreen` bind helps with this.
+It tells the app that it went fullscreen, while in reality leaving it as a normal window that you can resize and put wherever you want.
+
+```kdl
+binds {
+    Mod+Ctrl+Shift+F { toggle-windowed-fullscreen; }
+}
+```
+
+Keep in mind that not all apps react to fullscreening, so it may sometimes look as if the bind did nothing.
+
+Here's an example showing a windowed-fullscreen Google Slides [presentation](https://youtu.be/Kmz8ODolnDg), along with the presenter view and a meeting app:
+
+![Windowed Google Slides presentation, another window showing the presenter view, and another window showing Zoom UI casting the presentation.](https://github.com/user-attachments/assets/b2b49eea-f5a0-4c0a-b537-51fd1949a59d)
+
+[OBS]: https://obsproject.com/

docs/wiki/Tabs.md

@@ -0,0 +1,35 @@
+### Overview
+
+<sup>Since: 25.02</sup>
+
+You can switch a column to present windows as tabs, rather than as vertical tiles.
+All tabs in a column have the same window size, so this is useful to get more vertical space.
+
+![Terminal with a tab indicator on the left.](https://github.com/user-attachments/assets/0e94ac0d-796d-4f85-a264-c105ef41c13f)
+
+Use this bind to toggle a column between normal and tabbed display:
+
+```kdl
+binds {
+   Mod+W { toggle-column-tabbed-display; }
+}
+```
+
+All other binds remain the same: switch tabs with `focus-window-down/up`, add or remove windows with `consume-window-into-column`/`expel-window-from-column`, and so on.
+
+Unlike regular columns, tabbed columns can go full-screen with multiple windows.
+
+### Tab indicator
+
+Tabbed columns show a tab indicator on the side.
+You can click on the indicator to switch tabs.
+
+See the [`tab-indicator` section in the layout section](./Configuration:-Layout.md#tab-indicator) to configure it.
+
+By default, the indicator draws "outside" the column, so it can overlay other windows or go off-screen.
+The `place-within-column` flag puts the indicator "inside" the column, adjusting the window size to make space for it.
+This is especially useful for thicker tab indicators, or when you have very small gaps.
+
+| Default | `place-within-column` |
+| --- | --- |
+| ![A screenshot showing 4 windows, with the middle column being focused. The tab indicator overflows onto the left column](https://github.com/user-attachments/assets/c2f51f50-3d87-403a-8beb-cbbe5ec5c880) | ![A screenshot showing 4 windows, with the middle column being focused. The tab indicator is contained within its respective column](https://github.com/user-attachments/assets/f1797cd0-d518-4be6-95b4-3540523c4370) |

docs/wiki/Workspaces.md

@@ -0,0 +1,61 @@
+### Overview
+
+Niri has dynamic workspaces that can move between monitors.
+
+Each monitor contains an independent set of workspaces arranged vertically.
+You can switch between workspaces on a monitor with `focus-workspace-down` and `focus-workspace-up`.
+Empty workspaces "in the middle" automatically disappear when you switch away from them.
+
+There's always one empty workspace at the end (at the bottom) of every monitor.
+When you open a window on this empty workspace, a new empty workspace will immediately appear further below it.
+
+You can move workspaces up and down on the monitor with `move-workspace-up/down`.
+The way to put a window on a new workspace "in the middle" is to put it on the last (empty) workspace, then move the workspace up to where you need.
+
+Here's a visual representation that shows two monitors and their workspaces.
+The left monitor has three workspaces (two with windows, plus one empty), and the right monitor has two workspaces (one with windows, plus one empty).
+
+<picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./img/workspaces-dark.png">
+    <img alt="Two monitors. First with three workspaces, second with two workspaces." src="./img/workspaces-light.png">
+</picture>
+
+You can move a workspace to a different monitor using binds like `move-workspace-to-monitor-left/right/up/down` and `move-workspace-to-monitor-next/previous`.
+
+When you disconnect a monitor, its workspaces will automatically move to a different monitor.
+But, they will also "remember" their original monitor, so when you reconnect it, the workspaces will automatically move back to it.
+
+> [!TIP]
+> From other tiling WMs, you may be used to thinking about workspaces like this: "These are all of my workspaces. I can show workspace X on my first monitor, and workspace Y on my second monitor."
+> In niri, instead, think like this: "My first monitor contains these workspaces, including X and Y, and my second monitor contains these other workspaces. I can switch my first monitor to workspace X or Y. I can move workspace Y to my second monitor to show it there."
+
+### Addressing workspaces by index
+
+Several actions in niri can address workspaces "by index": `focus-workspace 2`, `move-column-to-workspace 4`.
+This index refers to whichever workspace *currently happens to be* at this position on the focused monitor.
+So, `focus-workspace 2` will always put you on the second workspace of the monitor, whichever workspace that currently is.
+
+This is an important distinction from WMs with static workspace systems.
+In niri, workspaces *do not have indices on their own*.
+If you take the first workspace and move it further down on the monitor, `focus-workspace 1` will now put you on a different workspace (the one that was below the first workspace before you moved it).
+
+When you want to have a more permanent workspace in niri, you can create a [named workspace](./Configuration:-Named-Workspaces.md) in the config or via the `set-workspace-name` action.
+You can refer to named workspaces by name, e.g. `focus-workspace "browser"`, and they won't disappear when they become empty.
+
+> [!TIP]
+> You can try to emulate static workspaces by creating workspaces named "one", "two", "three", ..., and binding keys to `focus-workspace "one"`, `focus-workspace "two"`, ...
+> This can work to some extent, but it can become somewhat confusing, since you can still move these workspaces up and down and between monitors.
+>
+> If you're coming from a static workspace WM, I suggest *not* doing that, but instead trying the "niri way" with dynamic workspaces, focusing and moving up/down instead of by index.
+> Thanks to scrollable tiling, you generally need fewer workspaces than on a traditional tiling WM.
+
+### Example workflow
+
+This is how I like to use workspaces.
+
+I will usually have my browser on the topmost workspace, then one workspace per project (or a "thing") I'm working on.
+On a single workspace I have 1–2 windows that fit inside a monitor that I switch between frequently, and maybe extra windows scrolled outside the view, usually either ones I need rarely, or temporary windows that I quickly close.
+When I need another permanent window, I'll put it on a new workspace.
+
+I actively move workspaces up and down as I'm working on things to make what I need accessible in one motion.
+For example, I usually frequently switch between the browser and whatever I'm doing, so I always move whatever I'm currently doing to right below the browser, so a single `focus-workspace-up/down` gets me where I want.

docs/wiki/Xwayland.md

@@ -0,0 +1,159 @@
+X11 is very cursed, so built-in Xwayland support [is not planned at the moment](./FAQ.md#why-doesnt-niri-integrate-xwayland-like-other-compositors).
+However, there are multiple solutions to running X11 apps in niri.
+
+## Using xwayland-satellite
+
+[xwayland-satellite] implements rootless Xwayland in a separate application, without the host compositor's involvement.
+It makes X11 windows appear as normal windows, just like a native Xwayland integration.
+xwayland-satellite works well with most applications: Steam, games, Discord, even more exotic things like Ardour with wine Windows VST plugins.
+However, X11 apps that want to position windows or bars at specific screen coordinates won't behave correctly.
+
+> [!NOTE]
+> In the next release, niri will have [built-in xwayland-satellite integration](./Configuration:-Miscellaneous.md#xwayland-satellite).
+> You can try it by installing git versions of both niri and xwayland-satellite.
+> With no further configuration, niri will create X11 sockets, then when an X11 client connects, automatically start xwayland-satellite.
+>
+> This matches how other compositors run Xwayland (but in niri's case, it's xwayland-satellite rather than Xwayland itself).
+> It also makes X11 apps work fine in `spawn-at-startup` and in XDG autostart.
+
+Install it from your package manager, or build it according to instructions from its README, then run the `xwayland-satellite` binary.
+Look for a log message like: `Connected to Xwayland on :0`.
+Now you can start X11 applications on this X11 DISPLAY:
+
+```
+env DISPLAY=:0 flatpak run com.valvesoftware.Steam
+```
+
+![xwayland-satellite running Steam and Half-Life.](https://github.com/user-attachments/assets/57db8f96-40d4-4621-a389-373c169349a4)
+
+You can also automatically run it at startup, and set `DISPLAY` by default for all apps by adding it to the [`environment`](./Configuration:-Miscellaneous.md#environment) section of the niri config:
+
+```kdl
+spawn-at-startup "xwayland-satellite"
+// Or, if you built it by hand:
+// spawn-at-startup "~/path/to/code/target/release/xwayland-satellite"
+
+environment {
+    DISPLAY ":0"
+}
+```
+
+> [!NOTE]
+> If the `:0` DISPLAY is already taken (for example, by some other Xwayland server like `xwayland-run`), `xwayland-satellite` will try the next DISPLAY numbers in order: `:1`, `:2`, etc. and tell you which one it used in its output.
+> Then, you will need to use that DISPLAY number for the `env` command or for the niri [`environment`](./Configuration:-Miscellaneous.md#environment) section.
+>
+> You can also force a specific DISPLAY number like so: `xwayland-satellite :12` will start on `DISPLAY=:12`.
+
+## Using the labwc Wayland compositor
+
+[Labwc](https://github.com/labwc/labwc) is a traditional stacking Wayland compositor with Xwayland.
+You can run it as a window, then run X11 apps inside.
+
+1. Install labwc from your distribution packages.
+1. Run it inside niri with the `labwc` command.
+It will open as a new window.
+1. Run an X11 application on the X11 DISPLAY that it provides, e.g. `env DISPLAY=:0 glxgears`
+
+![Labwc running X11 apps.](https://github.com/user-attachments/assets/aecbcecb-f0cb-4909-867f-09d34b5a2d7e)
+
+## Directly running Xwayland in rootful mode
+
+This method involves invoking XWayland directly and running it as its own window, it also requires an extra X11 window manager running inside it.
+
+![Xwayland running in rootful mode.](https://github.com/YaLTeR/niri/assets/1794388/b64e96c4-a0bb-4316-94a0-ff445d4c7da7)
+
+Here's how you do it:
+
+1. Run `Xwayland` (just the binary on its own without flags).
+This will spawn a black window which you can resize and fullscreen (with Mod+Shift+F) for convenience.
+On older Xwayland versions the window will be screen-sized and non-resizable.
+1. Run some X11 window manager in there, e.g. `env DISPLAY=:0 i3`.
+This way you can manage X11 windows inside the Xwayland instance.
+1. Run an X11 application there, e.g. `env DISPLAY=:0 flatpak run com.valvesoftware.Steam`.
+
+With fullscreen game inside a fullscreen Xwayland you get pretty much a normal gaming experience.
+
+> [!TIP]
+> If you don't run an X11 window manager, Xwayland will close and re-open its window every time all X11 windows close and a new one opens.
+> To prevent this, start an X11 WM inside as mentioned above, or open some other long-running X11 window.
+
+One caveat is that currently rootful Xwayland doesn't seem to share clipboard with the compositor.
+For textual data you can do it manually using [wl-clipboard](https://github.com/bugaevc/wl-clipboard), for example:
+
+- `env DISPLAY=:0 xsel -ob | wl-copy` to copy from Xwayland to niri clipboard
+- `wl-paste -n | env DISPLAY=:0 xsel -ib` to copy from niri to Xwayland clipboard
+
+You can also bind these to hotkeys if you want:
+
+```
+binds {
+    Mod+Shift+C { spawn "sh" "-c" "env DISPLAY=:0 xsel -ob | wl-copy"; }
+    Mod+Shift+V { spawn "sh" "-c" "wl-paste -n | env DISPLAY=:0 xsel -ib"; }
+}
+```
+
+## Using xwayland-run to run Xwayland
+
+[xwayland-run] is a helper utility to run an X11 client within a dedicated Xwayland rootful server.
+It takes care of starting Xwayland, setting the X11 DISPLAY environment variable, setting up xauth and running the specified X11 client using the newly started Xwayland instance.
+When the X11 client terminates, xwayland-run will automatically close the dedicated Xwayland server.
+
+It works like this:
+
+```
+xwayland-run <Xwayland arguments> -- your-x11-app <X11 app arguments>
+```
+
+For example:
+
+```
+xwayland-run -geometry 800x600 -fullscreen -- wine wingame.exe
+```
+
+## Using the Cage Wayland compositor
+
+It is also possible to run the X11 application in [Cage](https://github.com/cage-kiosk/cage), which runs a nested Wayland session which also supports Xwayland, where the X11 application can run in.
+
+Compared to the Xwayland rootful method, this does not require running an extra X11 window manager, and can be used with one command `cage -- /path/to/application`. However, it can also cause issues if multiple windows are launched inside Cage, since Cage is meant to be used in kiosks, every new window will be automatically full-screened and take over the previously opened window.
+
+To use Cage you need to:
+
+1. Install `cage`, it should be in most repositories.
+2. Run `cage -- /path/to/application` and enjoy your X11 program on niri.
+
+Optionally one can also modify the desktop entry for the application and add the `cage --` prefix to the `Exec` property. The Spotify Flatpak for example would look something like this:
+
+```ini
+[Desktop Entry]
+Type=Application
+Name=Spotify
+GenericName=Online music streaming service
+Comment=Access all of your favorite music
+Icon=com.spotify.Client
+Exec=cage -- flatpak run com.spotify.Client
+Terminal=false
+```
+
+## Using gamescope
+
+You can use [gamescope](https://github.com/ValveSoftware/gamescope) to run X11 games and even Steam itself.
+
+Similar to Cage, gamescope will only show a single, topmost window, so it's not very suitable to running regular apps.
+But you can run Steam in gamescope and then start some game from Steam just fine.
+
+```
+gamescope -- flatpak run com.valvesoftware.Steam
+```
+
+To run gamescope fullscreen, you can pass flags that set the necessary resolution, and a flag that starts it in fullscreen mode:
+
+```
+gamescope -W 2560 -H 1440 -w 2560 -h 1440 -f  -- flatpak run com.valvesoftware.Steam
+```
+
+> [!NOTE]
+> If Steam terminates abnormally while running in gamescope, it seems that subsequent gamescope invocations will sometimes fail to start it properly.
+> If this happens, run Steam inside a rootful Xwayland as described above, then exit it normally, and then you will be able to use gamescope again.
+
+[xwayland-run]: https://gitlab.freedesktop.org/ofourdan/xwayland-run
+[xwayland-satellite]: https://github.com/Supreeeme/xwayland-satellite

docs/wiki/_Sidebar.md

@@ -0,0 +1,40 @@
+## Usage
+* [Getting Started](./Getting-Started.md)
+* [Example systemd Setup](./Example-systemd-Setup.md)
+* [Important Software](./Important-Software.md)
+* [Workspaces](./Workspaces.md)
+* [Floating Windows](./Floating-Windows.md)
+* [Tabs](./Tabs.md)
+* [Overview](./Overview.md)
+* [Screencasting](./Screencasting.md)
+* [Layer‐Shell Components](./Layer%E2%80%90Shell-Components.md)
+* [IPC, `niri msg`](./IPC.md)
+* [Application-Specific Issues](./Application-Issues.md)
+* [Nvidia](./Nvidia.md)
+* [Xwayland](./Xwayland.md)
+* [Gestures](./Gestures.md)
+* [Packaging niri](./Packaging-niri.md)
+* [FAQ](./FAQ.md)
+
+## Configuration
+* [Introduction](./Configuration:-Introduction.md)
+* [Input](./Configuration:-Input.md)
+* [Outputs](./Configuration:-Outputs.md)
+* [Key Bindings](./Configuration:-Key-Bindings.md)
+* [Switch Events](./Configuration:-Switch-Events.md)
+* [Layout](./Configuration:-Layout.md)
+* [Named Workspaces](./Configuration:-Named-Workspaces.md)
+* [Miscellaneous](./Configuration:-Miscellaneous.md)
+* [Window Rules](./Configuration:-Window-Rules.md)
+* [Layer Rules](./Configuration:-Layer-Rules.md)
+* [Animations](./Configuration:-Animations.md)
+* [Gestures](./Configuration:-Gestures.md)
+* [Debug Options](./Configuration:-Debug-Options.md)
+
+## Development
+* [Design Principles](./Development:-Design-Principles.md)
+* [Developing niri](./Development:-Developing-niri.md)
+* [Documenting niri](./Development:-Documenting-niri.md)
+* [Fractional Layout](./Development:-Fractional-Layout.md)
+* [Redraw Loop](./Development:-Redraw-Loop.md)
+* [Animation Timing](./Development:-Animation-Timing.md)

docs/wiki/_assets/icons/logo.svg

@@ -0,0 +1,405 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="512"
+   height="512.00006"
+   viewBox="0 0 135.46667 135.46668"
+   version="1.1"
+   id="svg1"
+   sodipodi:docname="icon.svg"
+   inkscape:version="1.4.2 (ebf0e940d0, 2025-05-08)"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <sodipodi:namedview
+     id="namedview1"
+     borderopacity="1"
+     inkscape:showpageshadow="0"
+     inkscape:pageopacity="0"
+     inkscape:pagecheckerboard="1"
+     inkscape:zoom="0.8030909"
+     inkscape:cx="26.14897"
+     inkscape:cy="535.43129"
+     inkscape:window-width="2528"
+     inkscape:window-height="1408"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="0"
+     inkscape:current-layer="g71" />
+  <defs
+     id="defs1">
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter21"
+       x="-0.35129357"
+       y="-0.93287114"
+       width="1.7025871"
+       height="2.8657423">
+      <feGaussianBlur
+         stdDeviation="5.0792937"
+         id="feGaussianBlur21" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter22"
+       x="-0.42891072"
+       y="-0.64938287"
+       width="1.8578214"
+       height="2.2987657">
+      <feGaussianBlur
+         stdDeviation="6.5904956"
+         id="feGaussianBlur22" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter23"
+       x="-0.41511482"
+       y="-0.64325018"
+       width="1.8302296"
+       height="2.2865004">
+      <feGaussianBlur
+         stdDeviation="7.8584288"
+         id="feGaussianBlur23" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter24"
+       x="-0.36140346"
+       y="-0.92623631"
+       width="1.7228069"
+       height="2.8524726">
+      <feGaussianBlur
+         stdDeviation="5.269127"
+         id="feGaussianBlur24" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter27"
+       x="-0.17576354"
+       y="-0.83601771"
+       width="1.3515271"
+       height="2.6720354">
+      <feGaussianBlur
+         stdDeviation="4.753432"
+         id="feGaussianBlur26" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter52"
+       x="-0.33025388"
+       y="-1.0968854"
+       width="1.6605078"
+       height="3.1937708">
+      <feGaussianBlur
+         stdDeviation="4.2575558"
+         id="feGaussianBlur52" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter53"
+       x="-0.34014132"
+       y="-1.0243618"
+       width="1.6802826"
+       height="3.0487236">
+      <feGaussianBlur
+         stdDeviation="4.3187927"
+         id="feGaussianBlur54" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter55"
+       x="-0.33171227"
+       y="-1.0929411"
+       width="1.6634245"
+       height="3.1858823">
+      <feGaussianBlur
+         stdDeviation="4.4263355"
+         id="feGaussianBlur55" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter56"
+       x="-0.34596671"
+       y="-0.98818076"
+       width="1.6919334"
+       height="2.9763615">
+      <feGaussianBlur
+         stdDeviation="4.9267071"
+         id="feGaussianBlur56" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter57"
+       x="-0.50604737"
+       y="-0.53225252"
+       width="2.0120947"
+       height="2.064505">
+      <feGaussianBlur
+         stdDeviation="5.8261111"
+         id="feGaussianBlur57" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter58"
+       x="-0.32130078"
+       y="-1.1307663"
+       width="1.6426016"
+       height="3.2615325">
+      <feGaussianBlur
+         stdDeviation="4.2390405"
+         id="feGaussianBlur58" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter59"
+       x="-0.4030115"
+       y="-0.71156066"
+       width="1.806023"
+       height="2.4231213">
+      <feGaussianBlur
+         stdDeviation="4.4950086"
+         id="feGaussianBlur59" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter60"
+       x="-0.1759294"
+       y="-1.0177407"
+       width="1.3518588"
+       height="3.0354814">
+      <feGaussianBlur
+         stdDeviation="4.8003951"
+         id="feGaussianBlur60" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter70"
+       x="-0.43159762"
+       y="-0.3122953"
+       width="1.8631952"
+       height="1.6245906">
+      <feGaussianBlur
+         stdDeviation="18.461288"
+         id="feGaussianBlur70" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter72"
+       x="-0.43271319"
+       y="-0.31310251"
+       width="1.8654264"
+       height="1.626205">
+      <feGaussianBlur
+         stdDeviation="18.509006"
+         id="feGaussianBlur72" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter1"
+       x="-0.45705071"
+       y="-0.57220236"
+       width="1.9141014"
+       height="2.1444047">
+      <feGaussianBlur
+         stdDeviation="8.5810337"
+         id="feGaussianBlur1" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter2"
+       x="-0.545201"
+       y="-0.88686217"
+       width="2.090402"
+       height="2.7737243">
+      <feGaussianBlur
+         stdDeviation="4.3199889"
+         id="feGaussianBlur2" />
+    </filter>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath1">
+      <path
+         style="font-size:224.608px;line-height:393.415px;font-family:'Cherry Bomb One';-inkscape-font-specification:'Cherry Bomb One';letter-spacing:0px;fill:#259eb4;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 452.78682,224.36663 q -8.98432,0 -12.80266,-4.94138 -3.59373,-5.16598 -4.26757,-12.80265 -0.67381,-7.86128 -0.67381,-15.72256 0,-11.90423 -3.36913,-19.09168 -3.36912,-7.41207 -11.90421,-7.41207 -7.63667,0 -11.2304,7.41207 -3.59373,7.18745 -3.59373,19.09168 0,7.86128 -0.67384,15.49795 -0.44921,7.63667 -4.04294,12.80266 -3.59373,4.94137 -13.02726,4.94137 -6.96286,0 -11.67961,-5.16598 -4.49217,-5.16599 -6.96285,-13.47648 -2.47068,-8.3105 -3.59373,-17.96864 -0.89842,-9.65815 -0.89842,-18.64247 0,-8.98432 0.89842,-18.41785 0.89844,-9.43354 3.14452,-17.51943 2.47068,-8.08588 6.96285,-13.02726 4.49215,-4.94138 11.67961,-4.94138 12.80266,0 15.94715,11.67962 2.69531,-2.9199 8.53512,-5.39059 6.0644,-2.6953 13.70107,-2.6953 17.29484,0 28.30063,8.75971 11.00577,8.75972 15.94715,24.25767 5.16599,15.27334 4.94139,35.48806 0,10.33197 -2.02147,18.86707 -1.79687,8.3105 -6.51365,13.47648 -4.49215,4.94138 -12.80263,4.94138 z"
+         id="path5" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath5">
+      <path
+         style="font-size:224.608px;line-height:393.415px;font-family:'Cherry Bomb One';-inkscape-font-specification:'Cherry Bomb One';letter-spacing:0px;fill:#259eb4;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 452.78682,224.36663 q -8.98432,0 -12.80266,-4.94138 -3.59373,-5.16598 -4.26757,-12.80265 -0.67381,-7.86128 -0.67381,-15.72256 0,-11.90423 -3.36913,-19.09168 -3.36912,-7.41207 -11.90421,-7.41207 -7.63667,0 -11.2304,7.41207 -3.59373,7.18745 -3.59373,19.09168 0,7.86128 -0.67384,15.49795 -0.44921,7.63667 -4.04294,12.80266 -3.59373,4.94137 -13.02726,4.94137 -6.96286,0 -11.67961,-5.16598 -4.49217,-5.16599 -6.96285,-13.47648 -2.47068,-8.3105 -3.59373,-17.96864 -0.89842,-9.65815 -0.89842,-18.64247 0,-8.98432 0.89842,-18.41785 0.89844,-9.43354 3.14452,-17.51943 2.47068,-8.08588 6.96285,-13.02726 4.49215,-4.94138 11.67961,-4.94138 12.80266,0 15.94715,11.67962 2.69531,-2.9199 8.53512,-5.39059 6.0644,-2.6953 13.70107,-2.6953 17.29484,0 28.30063,8.75971 11.00577,8.75972 15.94715,24.25767 5.16599,15.27334 4.94139,35.48806 0,10.33197 -2.02147,18.86707 -1.79687,8.3105 -6.51365,13.47648 -4.49215,4.94138 -12.80263,4.94138 z"
+         id="path8" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath8">
+      <path
+         style="font-size:224.608px;line-height:393.415px;font-family:'Cherry Bomb One';-inkscape-font-specification:'Cherry Bomb One';letter-spacing:0px;fill:#259eb4;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 452.78682,224.36663 q -8.98432,0 -12.80266,-4.94138 -3.59373,-5.16598 -4.26757,-12.80265 -0.67381,-7.86128 -0.67381,-15.72256 0,-11.90423 -3.36913,-19.09168 -3.36912,-7.41207 -11.90421,-7.41207 -7.63667,0 -11.2304,7.41207 -3.59373,7.18745 -3.59373,19.09168 0,7.86128 -0.67384,15.49795 -0.44921,7.63667 -4.04294,12.80266 -3.59373,4.94137 -13.02726,4.94137 -6.96286,0 -11.67961,-5.16598 -4.49217,-5.16599 -6.96285,-13.47648 -2.47068,-8.3105 -3.59373,-17.96864 -0.89842,-9.65815 -0.89842,-18.64247 0,-8.98432 0.89842,-18.41785 0.89844,-9.43354 3.14452,-17.51943 2.47068,-8.08588 6.96285,-13.02726 4.49215,-4.94138 11.67961,-4.94138 12.80266,0 15.94715,11.67962 2.69531,-2.9199 8.53512,-5.39059 6.0644,-2.6953 13.70107,-2.6953 17.29484,0 28.30063,8.75971 11.00577,8.75972 15.94715,24.25767 5.16599,15.27334 4.94139,35.48806 0,10.33197 -2.02147,18.86707 -1.79687,8.3105 -6.51365,13.47648 -4.49215,4.94138 -12.80263,4.94138 z"
+         id="path11" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath11">
+      <path
+         style="font-size:224.608px;line-height:393.415px;font-family:'Cherry Bomb One';-inkscape-font-specification:'Cherry Bomb One';letter-spacing:0px;fill:#259eb4;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 452.78682,224.36663 q -8.98432,0 -12.80266,-4.94138 -3.59373,-5.16598 -4.26757,-12.80265 -0.67381,-7.86128 -0.67381,-15.72256 0,-11.90423 -3.36913,-19.09168 -3.36912,-7.41207 -11.90421,-7.41207 -7.63667,0 -11.2304,7.41207 -3.59373,7.18745 -3.59373,19.09168 0,7.86128 -0.67384,15.49795 -0.44921,7.63667 -4.04294,12.80266 -3.59373,4.94137 -13.02726,4.94137 -6.96286,0 -11.67961,-5.16598 -4.49217,-5.16599 -6.96285,-13.47648 -2.47068,-8.3105 -3.59373,-17.96864 -0.89842,-9.65815 -0.89842,-18.64247 0,-8.98432 0.89842,-18.41785 0.89844,-9.43354 3.14452,-17.51943 2.47068,-8.08588 6.96285,-13.02726 4.49215,-4.94138 11.67961,-4.94138 12.80266,0 15.94715,11.67962 2.69531,-2.9199 8.53512,-5.39059 6.0644,-2.6953 13.70107,-2.6953 17.29484,0 28.30063,8.75971 11.00577,8.75972 15.94715,24.25767 5.16599,15.27334 4.94139,35.48806 0,10.33197 -2.02147,18.86707 -1.79687,8.3105 -6.51365,13.47648 -4.49215,4.94138 -12.80263,4.94138 z"
+         id="path12" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath12">
+      <path
+         style="font-size:224.608px;line-height:393.415px;font-family:'Cherry Bomb One';-inkscape-font-specification:'Cherry Bomb One';letter-spacing:0px;fill:#259eb4;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 452.78682,224.36663 q -8.98432,0 -12.80266,-4.94138 -3.59373,-5.16598 -4.26757,-12.80265 -0.67381,-7.86128 -0.67381,-15.72256 0,-11.90423 -3.36913,-19.09168 -3.36912,-7.41207 -11.90421,-7.41207 -7.63667,0 -11.2304,7.41207 -3.59373,7.18745 -3.59373,19.09168 0,7.86128 -0.67384,15.49795 -0.44921,7.63667 -4.04294,12.80266 -3.59373,4.94137 -13.02726,4.94137 -6.96286,0 -11.67961,-5.16598 -4.49217,-5.16599 -6.96285,-13.47648 -2.47068,-8.3105 -3.59373,-17.96864 -0.89842,-9.65815 -0.89842,-18.64247 0,-8.98432 0.89842,-18.41785 0.89844,-9.43354 3.14452,-17.51943 2.47068,-8.08588 6.96285,-13.02726 4.49215,-4.94138 11.67961,-4.94138 12.80266,0 15.94715,11.67962 2.69531,-2.9199 8.53512,-5.39059 6.0644,-2.6953 13.70107,-2.6953 17.29484,0 28.30063,8.75971 11.00577,8.75972 15.94715,24.25767 5.16599,15.27334 4.94139,35.48806 0,10.33197 -2.02147,18.86707 -1.79687,8.3105 -6.51365,13.47648 -4.49215,4.94138 -12.80263,4.94138 z"
+         id="path14" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath15">
+      <path
+         style="font-size:224.608px;line-height:393.415px;font-family:'Cherry Bomb One';-inkscape-font-specification:'Cherry Bomb One';letter-spacing:0px;fill:#259eb4;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 511.63431,224.36663 q -8.98433,0 -13.47647,-5.16598 -4.26755,-5.16599 -5.83981,-15.72256 -1.34765,-10.78119 -1.57226,-27.62679 0,-16.8456 1.34763,-27.62678 1.57226,-10.78119 6.06444,-15.72256 4.49214,-5.16599 13.47647,-5.16599 8.98432,0 13.25187,5.16599 4.49217,4.94137 6.06443,15.72256 1.57223,10.78118 1.57223,27.62678 0.22461,16.8456 -1.34762,27.62679 -1.57226,10.55657 -6.06444,15.72256 -4.49215,5.16598 -13.47647,5.16598 z"
+         id="path16" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath17">
+      <path
+         style="font-size:224.608px;line-height:393.415px;font-family:'Cherry Bomb One';-inkscape-font-specification:'Cherry Bomb One';letter-spacing:0px;fill:#259eb4;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 681.32926,224.3022 q -8.98433,0 -13.47647,-5.16597 -4.26755,-5.16599 -5.83981,-15.72257 -1.34765,-10.78118 -1.57226,-27.62678 0,-16.8456 1.34763,-27.62678 1.57226,-10.78119 6.06444,-15.72257 4.49214,-5.16598 13.47647,-5.16598 8.98432,0 13.25187,5.16598 4.49217,4.94138 6.06443,15.72257 1.57223,10.78118 1.57223,27.62678 0.22461,16.8456 -1.34762,27.62678 -1.57226,10.55658 -6.06444,15.72257 -4.49215,5.16597 -13.47647,5.16597 z"
+         id="path17" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath18">
+      <path
+         style="font-size:224.608px;line-height:393.415px;font-family:'Cherry Bomb One';-inkscape-font-specification:'Cherry Bomb One';letter-spacing:0px;fill:#259eb4;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 573.177,224.36663 q -7.63667,0 -12.57805,-4.94138 -4.71678,-5.16598 -7.18746,-13.70108 -2.47068,-8.53511 -3.36913,-19.5409 -0.89842,-11.00579 -0.89842,-22.68541 0,-7.86128 0.22461,-15.94717 0.44921,-8.31049 2.24607,-15.27334 2.02147,-6.96285 6.51362,-11.2304 4.71678,-4.49216 13.25187,-4.49216 6.06443,0 11.00582,2.9199 4.94136,2.6953 6.28901,8.3105 5.16599,-4.71677 13.02727,-6.73824 8.08587,-2.24608 16.62099,-2.24608 7.18746,0 14.59952,3.59373 7.41207,3.36912 12.57803,9.43353 5.16599,6.06442 5.16599,13.70109 0,6.51363 -4.94136,12.35344 -4.71678,5.83981 -13.4765,5.83981 -3.81831,0 -6.28901,-0.89843 -2.47068,-1.12304 -4.71676,-2.02147 -2.2461,-0.89844 -5.39059,-0.89844 -8.31051,0 -15.27337,6.73824 -6.73822,6.51364 -6.73822,17.74404 0,5.8398 -0.44921,12.80265 -0.22463,6.73824 -2.02147,13.02727 -1.57226,6.28902 -5.83983,10.33196 -4.26754,3.81834 -12.35342,3.81834 z"
+         id="path19" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath19">
+      <path
+         style="font-size:224.608px;line-height:393.415px;font-family:'Cherry Bomb One';-inkscape-font-specification:'Cherry Bomb One';letter-spacing:0px;fill:#259eb4;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 573.177,224.36663 q -7.63667,0 -12.57805,-4.94138 -4.71678,-5.16598 -7.18746,-13.70108 -2.47068,-8.53511 -3.36913,-19.5409 -0.89842,-11.00579 -0.89842,-22.68541 0,-7.86128 0.22461,-15.94717 0.44921,-8.31049 2.24607,-15.27334 2.02147,-6.96285 6.51362,-11.2304 4.71678,-4.49216 13.25187,-4.49216 6.06443,0 11.00582,2.9199 4.94136,2.6953 6.28901,8.3105 5.16599,-4.71677 13.02727,-6.73824 8.08587,-2.24608 16.62099,-2.24608 7.18746,0 14.59952,3.59373 7.41207,3.36912 12.57803,9.43353 5.16599,6.06442 5.16599,13.70109 0,6.51363 -4.94136,12.35344 -4.71678,5.83981 -13.4765,5.83981 -3.81831,0 -6.28901,-0.89843 -2.47068,-1.12304 -4.71676,-2.02147 -2.2461,-0.89844 -5.39059,-0.89844 -8.31051,0 -15.27337,6.73824 -6.73822,6.51364 -6.73822,17.74404 0,5.8398 -0.44921,12.80265 -0.22463,6.73824 -2.02147,13.02727 -1.57226,6.28902 -5.83983,10.33196 -4.26754,3.81834 -12.35342,3.81834 z"
+         id="path20" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath20">
+      <path
+         style="font-size:224.608px;line-height:393.415px;font-family:'Cherry Bomb One';-inkscape-font-specification:'Cherry Bomb One';letter-spacing:0px;fill:#259eb4;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 573.177,224.36663 q -7.63667,0 -12.57805,-4.94138 -4.71678,-5.16598 -7.18746,-13.70108 -2.47068,-8.53511 -3.36913,-19.5409 -0.89842,-11.00579 -0.89842,-22.68541 0,-7.86128 0.22461,-15.94717 0.44921,-8.31049 2.24607,-15.27334 2.02147,-6.96285 6.51362,-11.2304 4.71678,-4.49216 13.25187,-4.49216 6.06443,0 11.00582,2.9199 4.94136,2.6953 6.28901,8.3105 5.16599,-4.71677 13.02727,-6.73824 8.08587,-2.24608 16.62099,-2.24608 7.18746,0 14.59952,3.59373 7.41207,3.36912 12.57803,9.43353 5.16599,6.06442 5.16599,13.70109 0,6.51363 -4.94136,12.35344 -4.71678,5.83981 -13.4765,5.83981 -3.81831,0 -6.28901,-0.89843 -2.47068,-1.12304 -4.71676,-2.02147 -2.2461,-0.89844 -5.39059,-0.89844 -8.31051,0 -15.27337,6.73824 -6.73822,6.51364 -6.73822,17.74404 0,5.8398 -0.44921,12.80265 -0.22463,6.73824 -2.02147,13.02727 -1.57226,6.28902 -5.83983,10.33196 -4.26754,3.81834 -12.35342,3.81834 z"
+         id="path21" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath21">
+      <path
+         style="font-size:224.608px;line-height:393.415px;font-family:'Cherry Bomb One';-inkscape-font-specification:'Cherry Bomb One';letter-spacing:0px;fill:#259eb4;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 573.177,224.36663 q -7.63667,0 -12.57805,-4.94138 -4.71678,-5.16598 -7.18746,-13.70108 -2.47068,-8.53511 -3.36913,-19.5409 -0.89842,-11.00579 -0.89842,-22.68541 0,-7.86128 0.22461,-15.94717 0.44921,-8.31049 2.24607,-15.27334 2.02147,-6.96285 6.51362,-11.2304 4.71678,-4.49216 13.25187,-4.49216 6.06443,0 11.00582,2.9199 4.94136,2.6953 6.28901,8.3105 5.16599,-4.71677 13.02727,-6.73824 8.08587,-2.24608 16.62099,-2.24608 7.18746,0 14.59952,3.59373 7.41207,3.36912 12.57803,9.43353 5.16599,6.06442 5.16599,13.70109 0,6.51363 -4.94136,12.35344 -4.71678,5.83981 -13.4765,5.83981 -3.81831,0 -6.28901,-0.89843 -2.47068,-1.12304 -4.71676,-2.02147 -2.2461,-0.89844 -5.39059,-0.89844 -8.31051,0 -15.27337,6.73824 -6.73822,6.51364 -6.73822,17.74404 0,5.8398 -0.44921,12.80265 -0.22463,6.73824 -2.02147,13.02727 -1.57226,6.28902 -5.83983,10.33196 -4.26754,3.81834 -12.35342,3.81834 z"
+         id="path22" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath23">
+      <path
+         style="font-size:224.608px;line-height:393.415px;font-family:'Cherry Bomb One';-inkscape-font-specification:'Cherry Bomb One';letter-spacing:0px;fill:#259eb4;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 681.43807,224.36663 q -8.98432,0 -13.47647,-5.16598 -4.26757,-5.16599 -5.83983,-15.72256 -1.34763,-10.78119 -1.57226,-27.62679 0,-16.8456 1.34765,-27.62678 1.57226,-10.78119 6.06444,-15.72256 4.49215,-5.16599 13.47647,-5.16599 8.98432,0 13.25187,5.16599 4.49215,4.94137 6.06441,15.72256 1.57226,10.78118 1.57226,27.62678 0.2246,16.8456 -1.34766,27.62679 -1.57223,10.55657 -6.06441,15.72256 -4.49215,5.16598 -13.47647,5.16598 z"
+         id="path25" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath25">
+      <path
+         style="font-size:224.608px;line-height:393.415px;font-family:'Cherry Bomb One';-inkscape-font-specification:'Cherry Bomb One';letter-spacing:0px;fill:#259eb4;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 681.43807,224.36663 q -8.98432,0 -13.47647,-5.16598 -4.26757,-5.16599 -5.83983,-15.72256 -1.34763,-10.78119 -1.57226,-27.62679 0,-16.8456 1.34765,-27.62678 1.57226,-10.78119 6.06444,-15.72256 4.49215,-5.16599 13.47647,-5.16599 8.98432,0 13.25187,5.16599 4.49215,4.94137 6.06441,15.72256 1.57226,10.78118 1.57226,27.62678 0.2246,16.8456 -1.34766,27.62679 -1.57223,10.55657 -6.06441,15.72256 -4.49215,5.16598 -13.47647,5.16598 z"
+         id="path26" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath34">
+      <path
+         id="path35"
+         style="fill:#259eb4;fill-opacity:1;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 169.33334,220.13334 c 0,8.46667 -4.23334,16.93333 -33.86667,16.93333 -29.63333,0 -33.86667,-8.46666 -33.86667,-16.93333 0,-12.7 8.46667,-21.16667 33.86667,-21.16667 25.4,0 33.86667,8.46667 33.86667,21.16667 z" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath35">
+      <path
+         id="path36"
+         style="fill:#259eb4;fill-opacity:1;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+         d="m 715.91343,141.3418 c 0,8.46667 -4.23334,16.93332 -33.86667,16.93332 -29.63333,0 -33.86667,-8.46665 -33.86667,-16.93332 0,-12.7 8.46667,-21.16668 33.86667,-21.16668 25.4,0 33.86667,8.46668 33.86667,21.16668 z" />
+    </clipPath>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       id="filter61"
+       x="-0.43233622"
+       y="-0.31282974"
+       width="1.8646724"
+       height="1.6256595">
+      <feGaussianBlur
+         stdDeviation="18.492881"
+         id="feGaussianBlur61" />
+    </filter>
+  </defs>
+  <g
+     id="layer1"
+     transform="translate(255.60477,-19.034522)">
+    <g
+       id="g71"
+       transform="matrix(0.53845513,0,0,0.53845513,-260.51955,13.25883)"
+       inkscape:label="ICON">
+      <g
+         id="g4"
+         inkscape:label="OUTLINE">
+        <path
+           id="path1"
+           style="display:inline;fill:#2d2d2d;fill-opacity:1;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+           d="m 131.35535,193.41317 c -8.42529,0.21555 -17.07195,1.23898 -24.70899,5.03516 -6.56852,3.28887 -11.780948,9.56904 -13.037575,16.89416 -1.12503,5.50318 -0.847502,11.50687 1.819693,16.54193 2.619641,4.74577 7.282642,8.08459 12.343352,9.82958 7.20278,2.70364 14.97875,3.20323 22.59699,3.46523 7.89843,0.20478 15.85819,-0.17121 23.61105,-1.76836 5.63625,-1.25422 11.31076,-3.51115 15.35105,-7.77992 3.29144,-3.52234 5.05422,-8.32066 5.11255,-13.1185 0.31661,-6.70741 -1.69285,-13.72981 -6.39837,-18.65616 -4.18578,-4.5464 -10.04779,-7.11576 -15.95626,-8.569 -6.77112,-1.66654 -13.79057,-1.92415 -20.73349,-1.87412 z" />
+        <path
+           id="path4"
+           style="display:inline;mix-blend-mode:normal;fill:#2d2d2d;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;stroke-opacity:1;paint-order:stroke fill markers"
+           d="m 98.902224,36.772549 c -6.995893,0.126233 -13.62619,4.553849 -16.638172,10.834978 -3.470673,6.368967 -4.476788,13.68672 -5.225527,20.799337 -1.546324,15.903589 -0.51861,31.905986 -1.354082,47.842876 -0.544064,12.91133 -1.490643,25.96714 0.724426,38.77934 1.594594,9.15149 5.382372,18.1514 11.945332,24.8552 5.649973,5.83947 12.892719,10.17523 20.761639,12.23377 4.29395,0.94959 9.28733,-0.57303 11.73776,-4.36606 2.38164,-3.59662 2.34796,-8.32076 0.82613,-12.24486 -1.20789,-3.11502 -2.64307,-6.14315 -3.64842,-9.33584 -1.12185,-3.39459 -1.94228,-6.99797 -2.3869,-10.47882 -0.55748,-4.05967 -0.49766,-8.22945 -0.15435,-12.24032 0.58298,-6.27022 1.46357,-12.5645 3.39036,-18.57849 0.79153,-2.26867 1.52928,-4.64049 3.02766,-6.55814 5.54574,0.77098 10.63142,3.47347 15.10865,6.73077 1.80507,1.34294 3.49258,2.79574 5.00233,4.33482 4.14952,4.21383 7.69916,9.25861 9.14438,15.0671 1.23316,4.77068 1.46924,9.85005 0.41871,14.67703 -1.02032,4.50982 -3.25363,8.60065 -5.45452,12.62181 -1.87577,3.646 -3.05511,7.8744 -2.17051,11.96837 0.96209,4.20638 4.82507,7.5927 9.1658,7.8093 4.52117,0.38592 8.79301,-1.6188 12.64582,-3.75368 9.91038,-5.51624 17.57193,-14.7796 21.44242,-25.41236 3.56981,-9.82442 4.74142,-20.45137 3.89537,-30.84701 -1.23706,-11.29301 -6.03879,-21.87272 -12.00583,-31.42104 -8.7119,-13.884894 -20.08721,-25.908588 -32.38582,-36.666079 -9.92644,-8.582365 -20.62052,-16.394651 -32.3549,-22.32888 -4.66406,-2.261816 -9.65523,-4.278849 -14.913576,-4.33312 -0.18139,0.0033 -0.36279,0.0067 -0.54418,0.01 z" />
+      </g>
+      <g
+         id="g26"
+         clip-path="none"
+         style="display:inline"
+         inkscape:label="STUB">
+        <path
+           id="path2"
+           style="fill:#259eb4;fill-opacity:1;stroke-width:2.11667;stroke-linecap:square;paint-order:stroke fill markers"
+           d="m 169.33334,220.13334 c 0,8.46667 -4.23334,16.93333 -33.86667,16.93333 -29.63333,0 -33.86667,-8.46666 -33.86667,-16.93333 0,-12.7 8.46667,-21.16667 33.86667,-21.16667 25.4,0 33.86667,8.46667 33.86667,21.16667 z" />
+        <path
+           style="mix-blend-mode:normal;fill:#92cfda;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:1.292;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;filter:url(#filter27)"
+           d="m 649.45734,133.81724 c 0.30861,-0.52382 1.24567,-1.10943 2.25778,-1.9344 0.71834,-0.58551 1.60294,-1.1585 2.689,-1.71704 1.33566,-0.68692 2.82604,-1.27591 4.41873,-1.81477 0.91309,-0.30893 1.90318,-0.61043 2.97552,-0.89949 2.75909,-0.74374 5.93213,-1.36936 9.45117,-1.81993 3.4485,-0.44153 7.02191,-0.68799 10.54487,-0.74159 0.11888,-0.002 0.23758,-0.003 0.35611,-0.005 3.42087,-0.0395 6.87572,0.10105 10.20745,0.42751 3.52675,0.34557 6.72,0.8799 9.50577,1.55294 1.13268,0.27365 2.17777,0.56526 3.14025,0.86932 1.5536,0.49082 3.01719,1.0374 4.3387,1.68661 1.10269,0.54172 2.00605,1.10621 2.74422,1.69041 1.03948,0.82267 1.92442,1.4682 2.24848,1.99812 -0.19311,-0.57592 -0.56732,-1.6128 -1.44388,-2.71822 -0.62575,-0.78911 -1.46647,-2.06647 -2.53663,-2.85214 -1.27528,-0.93627 -2.69843,-2.19648 -4.28815,-2.8662 -0.98885,-0.41658 -2.24548,-1.23914 -3.41727,-1.59811 -2.87657,-0.88121 -5.61102,-1.58246 -9.24402,-2.0046 -3.43498,-0.39913 -7.78163,-0.93367 -11.29835,-0.89735 -0.12203,0.001 -0.24424,0.003 -0.36663,0.005 -3.62086,0.0519 -8.29298,0.61115 -11.8461,1.12441 -3.62258,0.5233 -6.54204,1.50557 -9.38537,2.45693 -1.10746,0.37055 -2.4353,1.22472 -3.37108,1.64065 -1.62494,0.72224 -2.75555,1.66679 -4.03455,2.65099 -1.04655,0.80534 -1.65707,2.24134 -2.25723,3.03279 -0.84139,1.10955 -1.24261,2.1654 -1.41747,2.7334 z"
+           id="path24"
+           transform="translate(-546.58009,78.791545)"
+           clip-path="url(#clipPath35)"
+           sodipodi:nodetypes="csssssccssssscsssssccssssscc" />
+        <path
+           style="mix-blend-mode:normal;fill:#134f5a;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:1.292;stroke-linecap:round;stroke-linejoin:round;filter:url(#filter60)"
+           d="m 102.62873,226.09888 c 0.21837,0.59119 0.61147,1.63901 1.62645,2.90953 0.71917,0.90024 1.67343,1.81283 2.88011,2.66136 0.63885,0.44924 1.326,0.86437 2.04583,1.23422 1.73607,0.89199 3.88794,1.6902 6.44451,2.35832 3.15978,0.82576 6.73316,1.3998 10.52375,1.74639 2.77174,0.25344 5.543,0.37487 8.21345,0.40382 1.03453,0.0112 2.07172,0.008 3.10774,-0.0105 3.80268,-0.0675 7.55355,-0.33754 11.05616,-0.82447 3.61058,-0.50195 6.89851,-1.22612 9.69476,-2.17075 0.18263,-0.0617 0.36305,-0.1243 0.54123,-0.1878 2.50252,-0.89183 4.82056,-2.11237 6.51802,-3.52561 0.94359,-0.78561 1.6151,-1.56242 2.06492,-2.2946 0.63371,-1.03151 0.74175,-1.832 0.76927,-2.29791 -0.27946,0.40619 -0.77594,0.89664 -1.67451,1.38662 -0.63117,0.34418 -1.42595,0.67135 -2.41953,0.98728 -1.84319,0.58607 -3.98976,1.02107 -6.42445,1.47239 -0.16947,0.0314 -0.34092,0.0627 -0.51435,0.094 -2.66528,0.48001 -5.74678,0.9266 -9.18723,1.27047 -3.33185,0.33301 -6.89061,0.55814 -10.52391,0.6262 -0.98784,0.0185 -1.97654,0.0253 -2.96263,0.0197 -2.54936,-0.0146 -5.17908,-0.11853 -7.80849,-0.31818 -3.6162,-0.27458 -6.92286,-0.70577 -9.89494,-1.23993 -2.40547,-0.43232 -4.36461,-0.8899 -6.04479,-1.31771 -0.70208,-0.17876 -1.35634,-0.34389 -2.02406,-0.52251 -1.24448,-0.33289 -2.31304,-0.65483 -3.26912,-1.01993 -1.3453,-0.51373 -2.22471,-1.029 -2.73819,-1.44035 z"
+           id="path59"
+           clip-path="url(#clipPath34)" />
+      </g>
+      <path
+         style="display:inline;mix-blend-mode:normal;fill:#3ba8bc;fill-opacity:1;stroke:none;stroke-width:2.11667;stroke-linecap:square;stroke-opacity:1;paint-order:stroke fill markers"
+         d="m 101.6,42.333334 c 16.93334,0 84.66667,50.800005 84.66667,93.133336 0,28.57209 -13.39181,41.07402 -25.11117,46.54433 -8.87807,4.14406 -11.33775,-1.382 -6.3999,-9.88879 3.31767,-5.71559 6.11107,-12.63293 6.11107,-19.72221 0,-12.7 -4.23333,-21.16666 -12.7,-29.63333 -8.46667,-8.46667 -19.34216,-12.70001 -25.4,-12.7 -8.46666,1e-5 -12.7,24.8856 -12.7,38.1 0,10.52973 3.14292,20.01182 6.30176,26.88277 2.97912,6.48004 0.48516,10.93086 -6.19604,8.47352 -7.29956,-2.68477 -16.052373,-7.98293 -21.272388,-18.42296 -8.466666,-16.93333 -4.233333,-41.3022 -4.233333,-63.5 0,-33.866665 -7e-6,-59.266666 16.933331,-59.266666 z"
+         id="path3"
+         inkscape:label="FLAME" />
+      <path
+         style="display:inline;mix-blend-mode:normal;fill:#3ba8bc;fill-opacity:0.151125;stroke:none;stroke-width:2.11667;stroke-linecap:square;stroke-opacity:1;paint-order:stroke fill markers;filter:url(#filter70)"
+         d="m 101.6,42.333334 c 16.93334,0 84.66667,50.800005 84.66667,93.133336 0,28.57209 -13.39181,41.07402 -25.11117,46.54433 -8.87807,4.14406 -11.33775,-1.382 -6.3999,-9.88879 3.31767,-5.71559 6.11107,-12.63293 6.11107,-19.72221 0,-12.7 -4.23333,-21.16666 -12.7,-29.63333 -8.46667,-8.46667 -19.34216,-12.70001 -25.4,-12.7 -8.46666,1e-5 -12.7,24.8856 -12.7,38.1 0,10.52973 3.14292,20.01182 6.30176,26.88277 2.97912,6.48004 0.48516,10.93086 -6.19604,8.47352 -7.29956,-2.68477 -16.052373,-7.98293 -21.272388,-18.42296 -8.466666,-16.93333 -4.233333,-41.3022 -4.233333,-63.5 0,-33.866665 -7e-6,-59.266666 16.933331,-59.266666 z"
+         id="path67"
+         inkscape:label="GLOW" />
+    </g>
+  </g>
+</svg>

docs/wiki/_assets/stylesheets/niri.css

@@ -0,0 +1,60 @@
+:root  > * {
+  --md-primary-fg-color: #1e97b5;
+  --md-primary-fg-color--dark: color-mix(in srgb, var(--md-primary-fg-color), black 20%);
+  --md-accent-fg-color: var(--md-primary-fg-color--dark);
+}
+
+.md-logo > img {
+  background-color: white;
+  border-radius: 8px;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root  > * {
+    --md-primary-fg-color: #167188;
+    --md-accent-fg-color: #1e97b5;
+    --md-typeset-a-color: color-mix(in srgb, var(--md-accent-fg-color), white 30%);
+  }
+
+  .md-logo > img {
+    background-color: #eee;
+  }
+}
+
+.md-nav--primary .md-nav__title {
+  box-shadow: none;
+}
+
+@media screen and (min-width: 76.25em) {
+  .md-nav__title {
+    display: none;
+  }
+}
+
+@media screen and (min-width: 76.25em) {
+  .md-main {
+    min-height: 100vh;
+  }
+}
+
+.md-nav__link--active {
+  font-weight: bold;
+}
+
+.highlight .gp, .highlight .go {
+  user-select: none;
+}
+
+.md-source-file__fact {
+  visibility: hidden;
+}
+
+.badge {
+    font-size: 0.85em;
+    box-shadow: 0 0 0 1px inset var(--md-accent-fg-color--transparent);
+    padding: 0.2rem 0.3rem;
+}
+
+.md-typeset table:not([class]) td {
+    padding: .5em 1.25em;
+}

docs/wiki/examples/close_custom_shader.frag

@@ -0,0 +1,147 @@
+// Your shader must contain one function (see the bottom of this file).
+//
+// It should not contain any uniform definitions or anything else, as niri
+// provides them for you.
+//
+// All symbols defined by niri will have a niri_ prefix, so don't use it for
+// your own variables and functions.
+
+// The function that you must define looks like this:
+vec4 close_color(vec3 coords_geo, vec3 size_geo) {
+    vec4 color = /* ...compute the color... */;
+    return color;
+}
+
+// It takes as input:
+//
+// * coords_geo: coordinates of the current pixel relative to the window
+//   geometry.
+//
+// These are homogeneous (the Z component is equal to 1) and scaled in such a
+// way that the 0 to 1 coordinates lie within the window geometry. Pixels
+// outside the window geometry will have coordinates below 0 or above 1.
+//
+// The window geometry is its "visible bounds" from the user's perspective.
+//
+// The shader runs over the full screen area, so you must expect and handle
+// coordinates outside the [0, 1] range. If the window is scrolled off-screen,
+// all of the coordinates to the shader can fall outside the [0, 1] range.
+//
+// * size_geo: size of the window geometry in logical pixels.
+//
+// It is homogeneous (the Z component is equal to 1).
+//
+// The function must return the color of the pixel (with premultiplied alpha).
+// The pixel color will be further processed by niri (for example, to apply the
+// final opacity from window rules).
+
+// Now let's go over the uniforms that niri defines.
+//
+// You should only rely on the uniforms documented here. Any other uniforms can
+// change or be removed without notice.
+
+// The window texture.
+uniform sampler2D niri_tex;
+
+// Matrix that converts geometry coordinates into the window texture
+// coordinates.
+//
+// The window texture can and will go outside the geometry (for client-side
+// decoration shadows for example), which is why this matrix is necessary.
+uniform mat3 niri_geo_to_tex;
+
+
+// Unclamped progress of the animation.
+//
+// Goes from 0 to 1 but may overshoot and oscillate.
+uniform float niri_progress;
+
+// Clamped progress of the animation.
+//
+// Goes from 0 to 1, but will stop at 1 as soon as it first reaches 1. Will not
+// overshoot or oscillate.
+uniform float niri_clamped_progress;
+
+// Random float in [0; 1), consistent for the duration of the animation.
+uniform float niri_random_seed;
+
+// Now let's look at some examples. You can copy everything below this line
+// into your custom-shader to experiment.
+
+// Example: fill the current geometry with a solid vertical gradient and
+// gradually make transparent.
+vec4 solid_gradient(vec3 coords_geo, vec3 size_geo) {
+    vec4 color = vec4(0.0);
+
+    // Paint only the area inside the current geometry.
+    if (0.0 <= coords_geo.x && coords_geo.x <= 1.0
+            && 0.0 <= coords_geo.y && coords_geo.y <= 1.0)
+    {
+        vec4 from = vec4(1.0, 0.0, 0.0, 1.0);
+        vec4 to = vec4(0.0, 1.0, 0.0, 1.0);
+        color = mix(from, to, coords_geo.y);
+    }
+
+    // Make it transparent.
+    color *= (1.0 - niri_clamped_progress);
+
+    return color;
+}
+
+// Example: gradually scale down and make transparent, equivalent to the
+// default closing animation.
+vec4 default_close(vec3 coords_geo, vec3 size_geo) {
+    // Scale down the window.
+    float scale = max(0.0, ((1.0 - niri_clamped_progress) / 5.0 + 0.8));
+    coords_geo = vec3((coords_geo.xy - vec2(0.5)) / scale + vec2(0.5), 1.0);
+
+    // Get color from the window texture.
+    vec3 coords_tex = niri_geo_to_tex * coords_geo;
+    vec4 color = texture2D(niri_tex, coords_tex.st);
+
+    // Make the window transparent.
+    color *= (1.0 - niri_clamped_progress);
+
+    return color;
+}
+
+// Example: make the window 'fall down' with slight rotation.
+vec4 fall_and_rotate(vec3 coords_geo, vec3 size_geo) {
+    // For this shader, set animation curve to linear for best results.
+
+    // Simulate an accelerated fall: square the (linear) progress.
+    float progress = niri_clamped_progress * niri_clamped_progress;
+
+    // Get our rotation pivot point coordinates at the bottom center of the window.
+    vec2 coords = (coords_geo.xy - vec2(0.5, 1.0)) * size_geo.xy;
+
+    // Move the window down to simulate a fall.
+    coords.y -= progress * 200.0;
+
+    // Randomize rotation direction and maximum angle.
+    float random = (niri_random_seed - 0.5) / 2.0;
+    random = sign(random) - random;
+    float max_angle = 0.05 * random;
+
+    // Rotate the window around our pivot point.
+    float angle = progress * max_angle;
+    mat2 rotate = mat2(cos(angle), -sin(angle), sin(angle), cos(angle));
+    coords = rotate * coords;
+
+    // Transform the coordinates back.
+    coords_geo = vec3(coords / size_geo.xy + vec2(0.5, 1.0), 1.0);
+
+    // Sample the window texture.
+    vec3 coords_tex = niri_geo_to_tex * coords_geo;
+    vec4 color = texture2D(niri_tex, coords_tex.st);
+
+    // Multiply by alpha to fade out.
+    return color * (1.0 - niri_clamped_progress);
+}
+
+// This is the function that you must define.
+vec4 close_color(vec3 coords_geo, vec3 size_geo) {
+    // You can pick one of the example functions or write your own.
+    return fall_and_rotate(coords_geo, size_geo);
+}
+

docs/wiki/examples/open_custom_shader.frag

@@ -0,0 +1,128 @@
+// Your shader must contain one function (see the bottom of this file).
+//
+// It should not contain any uniform definitions or anything else, as niri
+// provides them for you.
+//
+// All symbols defined by niri will have a niri_ prefix, so don't use it for
+// your own variables and functions.
+
+// The function that you must define looks like this:
+vec4 open_color(vec3 coords_geo, vec3 size_geo) {
+    vec4 color = /* ...compute the color... */;
+    return color;
+}
+
+// It takes as input:
+//
+// * coords_geo: coordinates of the current pixel relative to the window
+//   geometry.
+//
+// These are homogeneous (the Z component is equal to 1) and scaled in such a
+// way that the 0 to 1 coordinates lie within the window geometry. Pixels
+// outside the window geometry will have coordinates below 0 or above 1.
+//
+// The window geometry is its "visible bounds" from the user's perspective.
+//
+// The shader runs over an area of unspecified size and location, so you must
+// expect and handle coordinates outside the [0, 1] range. The area will be
+// larger than the final window size to accommodate more varied effects.
+//
+// * size_geo: size of the window geometry in logical pixels.
+//
+// It is homogeneous (the Z component is equal to 1).
+//
+// The function must return the color of the pixel (with premultiplied alpha).
+// The pixel color will be further processed by niri (for example, to apply the
+// final opacity from window rules).
+
+// Now let's go over the uniforms that niri defines.
+//
+// You should only rely on the uniforms documented here. Any other uniforms can
+// change or be removed without notice.
+
+// The window texture.
+uniform sampler2D niri_tex;
+
+// Matrix that converts geometry coordinates into the window texture
+// coordinates.
+//
+// The window texture can and will go outside the geometry (for client-side
+// decoration shadows for example), which is why this matrix is necessary.
+uniform mat3 niri_geo_to_tex;
+
+
+// Unclamped progress of the animation.
+//
+// Goes from 0 to 1 but may overshoot and oscillate.
+uniform float niri_progress;
+
+// Clamped progress of the animation.
+//
+// Goes from 0 to 1, but will stop at 1 as soon as it first reaches 1. Will not
+// overshoot or oscillate.
+uniform float niri_clamped_progress;
+
+// Random float in [0; 1), consistent for the duration of the animation.
+uniform float niri_random_seed;
+
+// Now let's look at some examples. You can copy everything below this line
+// into your custom-shader to experiment.
+
+// Example: fill the current geometry with a solid vertical gradient and
+// gradually make opaque.
+vec4 solid_gradient(vec3 coords_geo, vec3 size_geo) {
+    vec4 color = vec4(0.0);
+
+    // Paint only the area inside the current geometry.
+    if (0.0 <= coords_geo.x && coords_geo.x <= 1.0
+            && 0.0 <= coords_geo.y && coords_geo.y <= 1.0)
+    {
+        vec4 from = vec4(1.0, 0.0, 0.0, 1.0);
+        vec4 to = vec4(0.0, 1.0, 0.0, 1.0);
+        color = mix(from, to, coords_geo.y);
+    }
+
+    // Make it opaque.
+    color *= niri_clamped_progress;
+
+    return color;
+}
+
+// Example: gradually scale up and make opaque, equivalent to the default
+// opening animation.
+vec4 default_open(vec3 coords_geo, vec3 size_geo) {
+    // Scale up the window.
+    float scale = max(0.0, (niri_progress / 2.0 + 0.5));
+    coords_geo = vec3((coords_geo.xy - vec2(0.5)) / scale + vec2(0.5), 1.0);
+
+    // Get color from the window texture.
+    vec3 coords_tex = niri_geo_to_tex * coords_geo;
+    vec4 color = texture2D(niri_tex, coords_tex.st);
+
+    // Make the window opaque.
+    color *= niri_clamped_progress;
+
+    return color;
+}
+
+// Example: show the window as an expanding circle.
+// Recommended setting: duration-ms 250
+vec4 expanding_circle(vec3 coords_geo, vec3 size_geo) {
+    vec3 coords_tex = niri_geo_to_tex * coords_geo;
+    vec4 color = texture2D(niri_tex, coords_tex.st);
+
+    vec2 coords = (coords_geo.xy - vec2(0.5, 0.5)) * size_geo.xy * 2.0;
+    coords = coords / length(size_geo.xy);
+    float p = niri_clamped_progress;
+    if (p * p <= dot(coords, coords))
+        color = vec4(0.0);
+
+    return color;
+}
+
+// This is the function that you must define.
+vec4 open_color(vec3 coords_geo, vec3 size_geo) {
+    // You can pick one of the example functions or write your own.
+    return expanding_circle(coords_geo, size_geo);
+}
+

docs/wiki/examples/resize_custom_shader.frag

@@ -0,0 +1,211 @@
+// Your shader must contain one function (see the bottom of this file).
+//
+// It should not contain any uniform definitions or anything else, as niri
+// provides them for you.
+//
+// All symbols defined by niri will have a niri_ prefix, so don't use it for
+// your own variables and functions.
+
+// The function that you must define looks like this:
+vec4 resize_color(vec3 coords_curr_geo, vec3 size_curr_geo) {
+    vec4 color = /* ...compute the color... */;
+    return color;
+}
+
+// It takes as input:
+//
+// * coords_curr_geo: coordinates of the current pixel relative to the current
+// window geometry.
+//
+// These are homogeneous (the Z component is equal to 1) and scaled in such a
+// way that the 0 to 1 coordinates lie within the current window geometry (in
+// the middle of a resize). Pixels outside the window geometry will have
+// coordinates below 0 or above 1.
+//
+// The window geometry is its "visible bounds" from the user's perspective.
+//
+// The shader runs over an area of unspecified size and location, so you must
+// expect and handle coordinates outside the [0, 1] range. The area will be
+// large enough to accommodate a crossfade effect.
+//
+// * size_curr_geo: size of the current window geometry in logical pixels.
+//
+// It is homogeneous (the Z component is equal to 1).
+//
+// The function must return the color of the pixel (with premultiplied alpha).
+// The pixel color will be further processed by niri (for example, to apply the
+// final opacity from window rules).
+
+// Now let's go over the uniforms that niri defines.
+//
+// You should only rely on the uniforms documented here. Any other uniforms can
+// change or be removed without notice.
+
+// Previous (before resize) window texture.
+uniform sampler2D niri_tex_prev;
+
+// Matrix that converts geometry coordinates into the previous window texture
+// coordinates.
+//
+// The window texture can and will go outside the geometry (for client-side
+// decoration shadows for example), which is why this matrix is necessary.
+uniform mat3 niri_geo_to_tex_prev;
+
+// Next (after resize) window texture.
+uniform sampler2D niri_tex_next;
+
+// Matrix that converts geometry coordinates into the next window texture
+// coordinates.
+uniform mat3 niri_geo_to_tex_next;
+
+
+// Matrix that converts coords_curr_geo into coordinates inside the previous
+// (before resize) window geometry.
+uniform mat3 niri_curr_geo_to_prev_geo;
+
+// Matrix that converts coords_curr_geo into coordinates inside the next
+// (after resize) window geometry.
+uniform mat3 niri_curr_geo_to_next_geo;
+
+
+// Unclamped progress of the animation.
+//
+// Goes from 0 to 1 but may overshoot and oscillate.
+uniform float niri_progress;
+
+// Clamped progress of the animation.
+//
+// Goes from 0 to 1, but will stop at 1 as soon as it first reaches 1. Will not
+// overshoot or oscillate.
+uniform float niri_clamped_progress;
+
+// Now let's look at some examples. You can copy everything below this line
+// into your custom-shader to experiment.
+
+// Example: fill the current geometry with a solid vertical gradient.
+vec4 solid_gradient(vec3 coords_curr_geo, vec3 size_curr_geo) {
+    vec3 coords = coords_curr_geo;
+    vec4 color = vec4(0.0);
+
+    // Paint only the area inside the current geometry.
+    if (0.0 <= coords.x && coords.x <= 1.0
+            && 0.0 <= coords.y && coords.y <= 1.0)
+    {
+        vec4 from = vec4(1.0, 0.0, 0.0, 1.0);
+        vec4 to = vec4(0.0, 1.0, 0.0, 1.0);
+        color = mix(from, to, coords.y);
+    }
+
+    return color;
+}
+
+// Example: crossfade between previous and next texture, stretched to the
+// current geometry.
+vec4 crossfade(vec3 coords_curr_geo, vec3 size_curr_geo) {
+    // Convert coordinates into the texture space for sampling.
+    vec3 coords_tex_prev = niri_geo_to_tex_prev * coords_curr_geo;
+    vec4 color_prev = texture2D(niri_tex_prev, coords_tex_prev.st);
+
+    // Convert coordinates into the texture space for sampling.
+    vec3 coords_tex_next = niri_geo_to_tex_next * coords_curr_geo;
+    vec4 color_next = texture2D(niri_tex_next, coords_tex_next.st);
+
+    vec4 color = mix(color_prev, color_next, niri_clamped_progress);
+    return color;
+}
+
+// Example: next texture, stretched to the current geometry.
+vec4 stretch_next(vec3 coords_curr_geo, vec3 size_curr_geo) {
+    vec3 coords_tex_next = niri_geo_to_tex_next * coords_curr_geo;
+    vec4 color = texture2D(niri_tex_next, coords_tex_next.st);
+    return color;
+}
+
+// Example: next texture, stretched to the current geometry if smaller, and
+// cropped if bigger.
+vec4 stretch_or_crop_next(vec3 coords_curr_geo, vec3 size_curr_geo) {
+    vec3 coords_next_geo = niri_curr_geo_to_next_geo * coords_curr_geo;
+
+    vec3 coords_stretch = niri_geo_to_tex_next * coords_curr_geo;
+    vec3 coords_crop = niri_geo_to_tex_next * coords_next_geo;
+
+    // We can crop if the current window size is smaller than the next window
+    // size. One way to tell is by comparing to 1.0 the X and Y scaling
+    // coefficients in the current-to-next transformation matrix.
+    bool can_crop_by_x = niri_curr_geo_to_next_geo[0][0] <= 1.0;
+    bool can_crop_by_y = niri_curr_geo_to_next_geo[1][1] <= 1.0;
+
+    vec3 coords = coords_stretch;
+    if (can_crop_by_x)
+        coords.x = coords_crop.x;
+    if (can_crop_by_y)
+        coords.y = coords_crop.y;
+
+    vec4 color = texture2D(niri_tex_next, coords.st);
+
+    // However, when we crop, we also want to crop out anything outside the
+    // current geometry. This is because the area of the shader is unspecified
+    // and usually bigger than the current geometry, so if we don't fill pixels
+    // outside with transparency, the texture will leak out.
+    //
+    // When stretching, this is not an issue because the area outside will
+    // correspond to client-side decoration shadows, which are already supposed
+    // to be outside.
+    if (can_crop_by_x && (coords_curr_geo.x < 0.0 || 1.0 < coords_curr_geo.x))
+        color = vec4(0.0);
+    if (can_crop_by_y && (coords_curr_geo.y < 0.0 || 1.0 < coords_curr_geo.y))
+        color = vec4(0.0);
+
+    return color;
+}
+
+// Example: cropped next texture if it's bigger than the current geometry, and
+// crossfade between previous and next texture otherwise.
+vec4 crossfade_or_crop_next(vec3 coords_curr_geo, vec3 size_curr_geo) {
+    vec3 coords_next_geo = niri_curr_geo_to_next_geo * coords_curr_geo;
+    vec3 coords_prev_geo = niri_curr_geo_to_prev_geo * coords_curr_geo;
+
+    vec3 coords_crop = niri_geo_to_tex_next * coords_next_geo;
+    vec3 coords_stretch = niri_geo_to_tex_next * coords_curr_geo;
+    vec3 coords_stretch_prev = niri_geo_to_tex_prev * coords_curr_geo;
+
+    // We can crop if the current window size is smaller than the next window
+    // size. One way to tell is by comparing to 1.0 the X and Y scaling
+    // coefficients in the current-to-next transformation matrix.
+    bool can_crop_by_x = niri_curr_geo_to_next_geo[0][0] <= 1.0;
+    bool can_crop_by_y = niri_curr_geo_to_next_geo[1][1] <= 1.0;
+    bool crop = can_crop_by_x && can_crop_by_y;
+
+    vec4 color;
+
+    if (crop) {
+        // However, when we crop, we also want to crop out anything outside the
+        // current geometry. This is because the area of the shader is unspecified
+        // and usually bigger than the current geometry, so if we don't fill pixels
+        // outside with transparency, the texture will leak out.
+        //
+        // When crossfading, this is not an issue because the area outside will
+        // correspond to client-side decoration shadows, which are already supposed
+        // to be outside.
+        if (coords_curr_geo.x < 0.0 || 1.0 < coords_curr_geo.x ||
+                coords_curr_geo.y < 0.0 || 1.0 < coords_curr_geo.y) {
+            color = vec4(0.0);
+        } else {
+            color = texture2D(niri_tex_next, coords_crop.st);
+        }
+    } else {
+        // If we can't crop, then crossfade.
+        color = texture2D(niri_tex_next, coords_stretch.st);
+        vec4 color_prev = texture2D(niri_tex_prev, coords_stretch_prev.st);
+        color = mix(color_prev, color, niri_clamped_progress);
+    }
+
+    return color;
+}
+
+// This is the function that you must define.
+vec4 resize_color(vec3 coords_curr_geo, vec3 size_curr_geo) {
+    // You can pick one of the example functions or write your own.
+    return stretch_or_crop_next(coords_curr_geo, size_curr_geo);
+}
+

docs/wiki/img/RedrawState-dark.drawio.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d6053eb3d7dbc07ae4b03403a28819788be50ce56f1d3c109b755e50de14ad62
+size 97565

docs/wiki/img/RedrawState-light.drawio.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:546c4a452f964f07a8d7e100eb6a007fec856c784857c67d214727b62b14a75d
+size 86906

docs/wiki/img/block-out-from-screencast.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:65b22b833dc0b05166b4b3403b1c6323315ca0885d4a75d2bbb68250a3855e96
+size 432355

docs/wiki/img/border-radius-clip.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6246413f95e5aa2d63db3fc8bc7726e45af3d20a95ea8f66614f4d62fa7a6624
+size 34239

docs/wiki/img/border.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bc0f46cdc5fc56a483f56a052b934b02f915f8b95cce3a9309e2ce7bf02478d4
+size 2623

docs/wiki/img/clip-to-geometry.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:88ca1517153755ee64b3fae4e67eced1f83873026ad1ad35c44b85f31fa8171d
+size 33591

docs/wiki/img/different-corner-radius.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:66eb4b989604a229c9413138f8de53d1038d9a2c6b2f40018e823b5589bdc941
+size 11266

docs/wiki/img/focus-ring.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ee21b6ed445f069270a6b0023a0c15659ac62cf7c92721792a3e3781148f2394
+size 4608

docs/wiki/img/geometry-corner-radius.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3ed3d553cae8948726ab03db3bf4ad9ef2dc9cf4593e24a96fad9d8820af949d
+size 25777

docs/wiki/img/gradients-default.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:164e445914282dc0e6e345f0b76ae59b617dfb8db6cf0c8b05cae51ed7d51b97
+size 31700

docs/wiki/img/gradients-oklch.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a3e4db583ac849ec3bd6c2312a84a16eaad810ebb7599cad3762a7dfc66e865b
+size 23180

docs/wiki/img/gradients-relative-to-workspace-view.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bb4e3e64bb0402b402b945b778c39b083512f7453d1503b789b63c8d6ff69330
+size 29540

docs/wiki/img/layer-block-out-from-screencast.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1dcaa6ece8e8287081332604270fa17a66561e0d81fd190d665005b6359c0eac
+size 559823

docs/wiki/img/opacity-popup.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d1e456ff87be58fcda542473dcbb5c5d63bef4f95b7e71bc1790de5e012f640d
+size 15837

docs/wiki/img/simple-egl-border-with-background.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:db034a4d42c382df3ff8aab1178f1978e1d7a20ff2318145c28a7f87e710eeaa
+size 4999

docs/wiki/img/simple-egl-border-without-background.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2623c4f1b11d82b0588893c87908b14337f42bd2ee328d17d1db74acf9c7bd17
+size 15729

docs/wiki/img/struts.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:32e84ae4c14683d07da42bea96a66fbb3427b11ba7619a98d3dc73d77c9f999c
+size 20959

docs/wiki/img/workspaces-dark.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e387b2551923ebcf9a21e2e485c55195c817d64a3198bc8d38ee0808046b7a44
+size 16825

docs/wiki/img/workspaces-light.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bf088a6b2a4ba2f38b711a5057251a702f55d6c8fcbc8310d39ad4c75a2a0d38
+size 17357

flake.lock

@@ -0,0 +1,48 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1752077645,
+        "narHash": "sha256-HM791ZQtXV93xtCY+ZxG1REzhQenSQO020cu6rHtAPk=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "be9e214982e20b8310878ac2baa063a961c1bdf6",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs",
+        "rust-overlay": "rust-overlay"
+      }
+    },
+    "rust-overlay": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1752374969,
+        "narHash": "sha256-Ky3ynEkJXih7mvWyt9DWoiSiZGqPeHLU1tlBU4b0mcc=",
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "rev": "75fb000638e6d0f57cb1e8b7a4550cbdd8c76f1d",
+        "type": "github"
+      },
+      "original": {
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,265 @@
+# This flake file is community maintained
+{
+  description = "Niri: A scrollable-tiling Wayland compositor.";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+
+    # NOTE: This is not necessary for end users
+    # You can omit it with `inputs.rust-overlay.follows = ""`
+    rust-overlay = {
+      url = "github:oxalica/rust-overlay";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs =
+    {
+      self,
+      nixpkgs,
+      rust-overlay,
+    }:
+    let
+      niri-package =
+        {
+          lib,
+          cairo,
+          dbus,
+          libGL,
+          libdisplay-info,
+          libinput,
+          seatd,
+          libxkbcommon,
+          libgbm,
+          pango,
+          pipewire,
+          pkg-config,
+          rustPlatform,
+          systemd,
+          wayland,
+          installShellFiles,
+          withDbus ? true,
+          withSystemd ? true,
+          withScreencastSupport ? true,
+          withDinit ? false,
+        }:
+
+        rustPlatform.buildRustPackage {
+          pname = "niri";
+          version = self.shortRev or self.dirtyShortRev or "unknown";
+
+          src = lib.fileset.toSource {
+            root = ./.;
+            fileset = lib.fileset.unions [
+              ./niri-config
+              ./niri-ipc
+              ./niri-visual-tests
+              ./resources
+              ./src
+              ./Cargo.toml
+              ./Cargo.lock
+            ];
+          };
+
+          postPatch = ''
+            patchShebangs resources/niri-session
+            substituteInPlace resources/niri.service \
+              --replace-fail '/usr/bin' "$out/bin"
+          '';
+
+          cargoLock = {
+            # NOTE: This is only used for Git dependencies
+            allowBuiltinFetchGit = true;
+            lockFile = ./Cargo.lock;
+          };
+
+          strictDeps = true;
+
+          nativeBuildInputs = [
+            rustPlatform.bindgenHook
+            pkg-config
+            installShellFiles
+          ];
+
+          buildInputs =
+            [
+              cairo
+              dbus
+              libGL
+              libdisplay-info
+              libinput
+              seatd
+              libxkbcommon
+              libgbm
+              pango
+              wayland
+            ]
+            ++ lib.optional (withDbus || withScreencastSupport || withSystemd) dbus
+            ++ lib.optional withScreencastSupport pipewire
+            # Also includes libudev
+            ++ lib.optional withSystemd systemd;
+
+          buildFeatures =
+            lib.optional withDbus "dbus"
+            ++ lib.optional withDinit "dinit"
+            ++ lib.optional withScreencastSupport "xdp-gnome-screencast"
+            ++ lib.optional withSystemd "systemd";
+          buildNoDefaultFeatures = true;
+
+          # ever since this commit:
+          # https://github.com/YaLTeR/niri/commit/771ea1e81557ffe7af9cbdbec161601575b64d81
+          # niri now runs an actual instance of the real compositor (with a mock backend) during tests
+          # and thus creates a real socket file in the runtime dir.
+          # this is fine for our build, we just need to make sure it has a directory to write to.
+          preCheck = ''
+            export XDG_RUNTIME_DIR="$(mktemp -d)"
+          '';
+
+          checkFlags = [
+            # These tests require the ability to access a "valid EGL Display", but that won't work
+            # inside the Nix sandbox
+            "--skip=tests::animations"
+          ];
+
+          postInstall =
+            ''
+              installShellCompletion --cmd niri \
+                --bash <($out/bin/niri completions bash) \
+                --fish <($out/bin/niri completions fish) \
+                --zsh <($out/bin/niri completions zsh)
+
+              install -Dm644 resources/niri.desktop -t $out/share/wayland-sessions
+              install -Dm644 resources/niri-portals.conf -t $out/share/xdg-desktop-portal
+            ''
+            + lib.optionalString withSystemd ''
+              install -Dm755 resources/niri-session $out/bin/niri-session
+              install -Dm644 resources/niri{.service,-shutdown.target} -t $out/share/systemd/user
+            '';
+
+          env = {
+            # Force linking with libEGL and libwayland-client
+            # so they can be discovered by `dlopen()`
+            RUSTFLAGS = toString (
+              map (arg: "-C link-arg=" + arg) [
+                "-Wl,--push-state,--no-as-needed"
+                "-lEGL"
+                "-lwayland-client"
+                "-Wl,--pop-state"
+              ]
+            );
+          };
+
+          passthru = {
+            providedSessions = [ "niri" ];
+          };
+
+          meta = {
+            description = "Scrollable-tiling Wayland compositor";
+            homepage = "https://github.com/YaLTeR/niri";
+            license = lib.licenses.gpl3Only;
+            mainProgram = "niri";
+            platforms = lib.platforms.linux;
+          };
+        };
+
+      inherit (nixpkgs) lib;
+      # Support all Linux systems that the nixpkgs flake exposes
+      systems = lib.intersectLists lib.systems.flakeExposed lib.platforms.linux;
+
+      forAllSystems = lib.genAttrs systems;
+      nixpkgsFor = forAllSystems (system: nixpkgs.legacyPackages.${system});
+    in
+    {
+      checks = forAllSystems (system: {
+        # We use the debug build here to save a bit of time
+        inherit (self.packages.${system}) niri-debug;
+      });
+
+      devShells = forAllSystems (
+        system:
+        let
+          pkgs = nixpkgsFor.${system};
+          rust-bin = rust-overlay.lib.mkRustBin { } pkgs;
+          inherit (self.packages.${system}) niri;
+        in
+        {
+          default = pkgs.mkShell {
+            packages = [
+              # We don't use the toolchain from nixpkgs
+              # because we prefer a nightly toolchain
+              # and we *require* a nightly rustfmt
+              (rust-bin.selectLatestNightlyWith (
+                toolchain:
+                toolchain.default.override {
+                  extensions = [
+                    # includes already:
+                    # rustc
+                    # cargo
+                    # rust-std
+                    # rust-docs
+                    # rustfmt-preview
+                    # clippy-preview
+                    "rust-analyzer"
+                    "rust-src"
+                  ];
+                }
+              ))
+            ];
+
+            nativeBuildInputs = [
+              pkgs.rustPlatform.bindgenHook
+              pkgs.pkg-config
+              pkgs.wrapGAppsHook4 # For `niri-visual-tests`
+            ];
+
+            buildInputs = niri.buildInputs ++ [
+              pkgs.libadwaita # For `niri-visual-tests`
+            ];
+
+            env = {
+              # WARN: Do not overwrite this variable in your shell!
+              # It is required for `dlopen()` to work on some libraries; see the comment
+              # in the package expression
+              #
+              # This should only be set with `CARGO_BUILD_RUSTFLAGS="$CARGO_BUILD_RUSTFLAGS -C your-flags"`
+              CARGO_BUILD_RUSTFLAGS = niri.RUSTFLAGS;
+            };
+          };
+        }
+      );
+
+      formatter = forAllSystems (system: nixpkgsFor.${system}.nixfmt-rfc-style);
+
+      packages = forAllSystems (
+        system:
+        let
+          niri = nixpkgsFor.${system}.callPackage niri-package { };
+        in
+        {
+          inherit niri;
+
+          # NOTE: This is for development purposes only
+          #
+          # It is primarily to help with quickly iterating on
+          # changes made to the above expression - though it is
+          # also not stripped in order to better debug niri itself
+          niri-debug = niri.overrideAttrs (
+            newAttrs: oldAttrs: {
+              pname = oldAttrs.pname + "-debug";
+
+              cargoBuildType = "debug";
+              cargoCheckType = newAttrs.cargoBuildType;
+
+              dontStrip = true;
+            }
+          );
+
+          default = niri;
+        }
+      );
+
+      overlays.default = final: _: {
+        niri = final.callPackage niri-package { };
+      };
+    };
+}

niri-config/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "niri-config"
+version.workspace = true
+description.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+
+[dependencies]
+bitflags.workspace = true
+csscolorparser = "0.7.2"
+knuffel = "3.2.0"
+miette = { version = "5.10.0", features = ["fancy-no-backtrace"] }
+niri-ipc = { version = "25.5.1", path = "../niri-ipc" }
+regex = "1.11.1"
+smithay = { workspace = true, features = ["backend_libinput"] }
+tracing.workspace = true
+tracy-client.workspace = true
+
+[dev-dependencies]
+insta.workspace = true
+pretty_assertions = "1.4.1"

niri-config/src/layer_rule.rs

@@ -0,0 +1,30 @@
+use crate::{BlockOutFrom, CornerRadius, RegexEq, ShadowRule};
+
+#[derive(knuffel::Decode, Debug, Default, Clone, PartialEq)]
+pub struct LayerRule {
+    #[knuffel(children(name = "match"))]
+    pub matches: Vec<Match>,
+    #[knuffel(children(name = "exclude"))]
+    pub excludes: Vec<Match>,
+
+    #[knuffel(child, unwrap(argument))]
+    pub opacity: Option<f32>,
+    #[knuffel(child, unwrap(argument))]
+    pub block_out_from: Option<BlockOutFrom>,
+    #[knuffel(child, default)]
+    pub shadow: ShadowRule,
+    #[knuffel(child)]
+    pub geometry_corner_radius: Option<CornerRadius>,
+    #[knuffel(child, unwrap(argument))]
+    pub place_within_backdrop: Option<bool>,
+    #[knuffel(child, unwrap(argument))]
+    pub baba_is_float: Option<bool>,
+}
+
+#[derive(knuffel::Decode, Debug, Default, Clone, PartialEq)]
+pub struct Match {
+    #[knuffel(property, str)]
+    pub namespace: Option<RegexEq>,
+    #[knuffel(property)]
+    pub at_startup: Option<bool>,
+}

niri-config/src/utils.rs

@@ -0,0 +1,23 @@
+use std::str::FromStr;
+
+use regex::Regex;
+
+/// `Regex` that implements `PartialEq` by its string form.
+#[derive(Debug, Clone)]
+pub struct RegexEq(pub Regex);
+
+impl PartialEq for RegexEq {
+    fn eq(&self, other: &Self) -> bool {
+        self.0.as_str() == other.0.as_str()
+    }
+}
+
+impl Eq for RegexEq {}
+
+impl FromStr for RegexEq {
+    type Err = <Regex as FromStr>::Err;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Regex::from_str(s).map(Self)
+    }
+}

niri-config/tests/wiki-parses.rs

@@ -0,0 +1,110 @@
+use std::fs;
+use std::path::PathBuf;
+
+struct KdlCodeBlock {
+    filename: String,
+    code: String,
+    line_number: usize,
+    must_fail: bool,
+}
+
+fn extract_kdl_from_file(file_contents: &str, filename: &str) -> Vec<KdlCodeBlock> {
+    let mut lines = file_contents
+        .lines()
+        .map(|line| {
+            // Removes the > from callouts that might contain ```kdl```
+            let line = line.trim();
+            if line.starts_with('>') {
+                if line.len() == 1 {
+                    ""
+                } else {
+                    &line[2..]
+                }
+            } else {
+                line
+            }
+        })
+        .enumerate();
+
+    let mut kdl_code_blocks = vec![];
+
+    while let Some((line_number, line)) = lines.next() {
+        if !line.starts_with("```kdl") {
+            continue;
+        }
+
+        let mut snippet = String::new();
+
+        for (_, line) in lines
+            .by_ref()
+            .take_while(|(_, line)| !line.starts_with("```"))
+        {
+            snippet.push_str(line);
+            snippet.push('\n');
+        }
+
+        kdl_code_blocks.push(KdlCodeBlock {
+            code: snippet,
+            line_number,
+            filename: filename.to_string(),
+            must_fail: line.contains("must-fail"),
+        });
+    }
+
+    kdl_code_blocks
+}
+
+#[test]
+fn wiki_docs_parses() {
+    let wiki_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../docs/wiki");
+
+    let code_blocks = fs::read_dir(wiki_dir)
+        .unwrap()
+        .filter_map(|entry| entry.ok())
+        .filter(|entry| entry.file_type().is_ok_and(|ft| ft.is_file()))
+        .filter(|file| {
+            file.path()
+                .extension()
+                .map(|ext| ext == "md")
+                .unwrap_or(false)
+        })
+        .flat_map(|file| {
+            let file_contents = fs::read_to_string(file.path()).unwrap();
+            let file_path = file.path();
+            let filename = file_path.to_str().unwrap();
+            extract_kdl_from_file(&file_contents, filename)
+        });
+
+    let mut errors = vec![];
+
+    for KdlCodeBlock {
+        code,
+        line_number,
+        filename,
+        must_fail,
+    } in code_blocks
+    {
+        if let Err(error) = niri_config::Config::parse(&filename, &code) {
+            if !must_fail {
+                errors.push(format!(
+                    "Error parsing wiki KDL code block at {}:{}: {:?}",
+                    filename,
+                    line_number,
+                    miette::Report::new(error)
+                ));
+            }
+        } else if must_fail {
+            errors.push(format!(
+                "Expected error parsing wiki KDL code block at {filename}:{line_number}",
+            ));
+        }
+    }
+
+    if !errors.is_empty() {
+        panic!(
+            "Errors parsing {} wiki KDL code blocks:\n{}",
+            errors.len(),
+            errors.join("\n")
+        );
+    }
+}

niri-ipc/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "niri-ipc"
+version.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+
+description = "Types and helpers for interfacing with the niri Wayland compositor."
+keywords = ["wayland"]
+categories = ["api-bindings", "os"]
+readme = "README.md"
+
+[dependencies]
+clap = { workspace = true, optional = true }
+schemars = { version = "1.0.4", optional = true }
+serde.workspace = true
+serde_json.workspace = true
+
+[features]
+clap = ["dep:clap"]
+json-schema = ["dep:schemars"]

niri-ipc/README.md

@@ -0,0 +1,16 @@
+# niri-ipc
+
+Types and helpers for interfacing with the [niri](https://github.com/YaLTeR/niri) Wayland compositor.
+
+## Backwards compatibility
+
+This crate follows the niri version.
+It is **not** API-stable in terms of the Rust semver.
+In particular, expect new struct fields and enum variants to be added in patch version bumps.
+
+Use an exact version requirement to avoid breaking changes:
+
+```toml
+[dependencies]
+niri-ipc = "=25.5.1"
+```

niri-ipc/src/socket.rs

@@ -0,0 +1,101 @@
+//! Helper for blocking communication over the niri socket.
+
+use std::env;
+use std::io::{self, BufRead, BufReader, Write};
+use std::net::Shutdown;
+use std::os::unix::net::UnixStream;
+use std::path::Path;
+
+use crate::{Event, Reply, Request};
+
+/// Name of the environment variable containing the niri IPC socket path.
+pub const SOCKET_PATH_ENV: &str = "NIRI_SOCKET";
+
+/// Helper for blocking communication over the niri socket.
+///
+/// This struct is used to communicate with the niri IPC server. It handles the socket connection
+/// and serialization/deserialization of messages.
+pub struct Socket {
+    stream: BufReader<UnixStream>,
+}
+
+impl Socket {
+    /// Connects to the default niri IPC socket.
+    ///
+    /// This is equivalent to calling [`Self::connect_to`] with the path taken from the
+    /// [`SOCKET_PATH_ENV`] environment variable.
+    pub fn connect() -> io::Result<Self> {
+        let socket_path = env::var_os(SOCKET_PATH_ENV).ok_or_else(|| {
+            io::Error::new(
+                io::ErrorKind::NotFound,
+                format!("{SOCKET_PATH_ENV} is not set, are you running this within niri?"),
+            )
+        })?;
+        Self::connect_to(socket_path)
+    }
+
+    /// Connects to the niri IPC socket at the given path.
+    pub fn connect_to(path: impl AsRef<Path>) -> io::Result<Self> {
+        let stream = UnixStream::connect(path.as_ref())?;
+        let stream = BufReader::new(stream);
+        Ok(Self { stream })
+    }
+
+    /// Sends a request to niri and returns the response.
+    ///
+    /// Return values:
+    ///
+    /// * `Ok(Ok(response))`: successful [`Response`](crate::Response) from niri
+    /// * `Ok(Err(message))`: error message from niri
+    /// * `Err(error)`: error communicating with niri
+    pub fn send(&mut self, request: Request) -> io::Result<Reply> {
+        let mut buf = serde_json::to_string(&request).unwrap();
+        buf.push('\n');
+        self.stream.get_mut().write_all(buf.as_bytes())?;
+
+        buf.clear();
+        self.stream.read_line(&mut buf)?;
+
+        let reply = serde_json::from_str(&buf)?;
+        Ok(reply)
+    }
+
+    /// Starts reading event stream [`Event`]s from the socket.
+    ///
+    /// The returned function will block until the next [`Event`] arrives, then return it.
+    ///
+    /// Use this only after requesting an [`EventStream`][Request::EventStream].
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use niri_ipc::{Request, Response};
+    /// use niri_ipc::socket::Socket;
+    ///
+    /// fn main() -> std::io::Result<()> {
+    ///     let mut socket = Socket::connect()?;
+    ///
+    ///     let reply = socket.send(Request::EventStream)?;
+    ///     if matches!(reply, Ok(Response::Handled)) {
+    ///         let mut read_event = socket.read_events();
+    ///         while let Ok(event) = read_event() {
+    ///             println!("Received event: {event:?}");
+    ///         }
+    ///     }
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
+    pub fn read_events(self) -> impl FnMut() -> io::Result<Event> {
+        let Self { mut stream } = self;
+        let _ = stream.get_mut().shutdown(Shutdown::Write);
+
+        let mut buf = String::new();
+        move || {
+            buf.clear();
+            stream.read_line(&mut buf)?;
+            let event = serde_json::from_str(&buf)?;
+            Ok(event)
+        }
+    }
+}

niri-ipc/src/state.rs

@@ -0,0 +1,276 @@
+//! Helpers for keeping track of the event stream state.
+//!
+//! 1. Create an [`EventStreamState`] using `Default::default()`, or any individual state part if
+//!    you only care about part of the state.
+//! 2. Connect to the niri socket and request an event stream.
+//! 3. Pass every [`Event`] to [`EventStreamStatePart::apply`] on your state.
+//! 4. Read the fields of the state as needed.
+
+use std::collections::hash_map::Entry;
+use std::collections::HashMap;
+
+use crate::{Event, KeyboardLayouts, Window, Workspace};
+
+/// Part of the state communicated via the event stream.
+pub trait EventStreamStatePart {
+    /// Returns a sequence of events that replicates this state from default initialization.
+    fn replicate(&self) -> Vec<Event>;
+
+    /// Applies the event to this state.
+    ///
+    /// Returns `None` after applying the event, and `Some(event)` if the event is ignored by this
+    /// part of the state.
+    fn apply(&mut self, event: Event) -> Option<Event>;
+}
+
+/// The full state communicated over the event stream.
+///
+/// Different parts of the state are not guaranteed to be consistent across every single event
+/// sent by niri. For example, you may receive the first [`Event::WindowOpenedOrChanged`] for a
+/// just-opened window *after* an [`Event::WorkspaceActiveWindowChanged`] for that window. Between
+/// these two events, the workspace active window id refers to a window that does not yet exist in
+/// the windows state part.
+#[derive(Debug, Default)]
+pub struct EventStreamState {
+    /// State of workspaces.
+    pub workspaces: WorkspacesState,
+
+    /// State of workspaces.
+    pub windows: WindowsState,
+
+    /// State of the keyboard layouts.
+    pub keyboard_layouts: KeyboardLayoutsState,
+
+    /// State of the overview.
+    pub overview: OverviewState,
+
+    /// State of the config.
+    pub config: ConfigState,
+}
+
+/// The workspaces state communicated over the event stream.
+#[derive(Debug, Default)]
+pub struct WorkspacesState {
+    /// Map from a workspace id to the workspace.
+    pub workspaces: HashMap<u64, Workspace>,
+}
+
+/// The windows state communicated over the event stream.
+#[derive(Debug, Default)]
+pub struct WindowsState {
+    /// Map from a window id to the window.
+    pub windows: HashMap<u64, Window>,
+}
+
+/// The keyboard layout state communicated over the event stream.
+#[derive(Debug, Default)]
+pub struct KeyboardLayoutsState {
+    /// Configured keyboard layouts.
+    pub keyboard_layouts: Option<KeyboardLayouts>,
+}
+
+/// The overview state communicated over the event stream.
+#[derive(Debug, Default)]
+pub struct OverviewState {
+    /// Whether the overview is currently open.
+    pub is_open: bool,
+}
+
+/// The config state communicated over the event stream.
+#[derive(Debug, Default)]
+pub struct ConfigState {
+    /// Whether the last config load attempt had failed.
+    pub failed: bool,
+}
+
+impl EventStreamStatePart for EventStreamState {
+    fn replicate(&self) -> Vec<Event> {
+        let mut events = Vec::new();
+        events.extend(self.workspaces.replicate());
+        events.extend(self.windows.replicate());
+        events.extend(self.keyboard_layouts.replicate());
+        events.extend(self.overview.replicate());
+        events.extend(self.config.replicate());
+        events
+    }
+
+    fn apply(&mut self, event: Event) -> Option<Event> {
+        let event = self.workspaces.apply(event)?;
+        let event = self.windows.apply(event)?;
+        let event = self.keyboard_layouts.apply(event)?;
+        let event = self.overview.apply(event)?;
+        let event = self.config.apply(event)?;
+        Some(event)
+    }
+}
+
+impl EventStreamStatePart for WorkspacesState {
+    fn replicate(&self) -> Vec<Event> {
+        let workspaces = self.workspaces.values().cloned().collect();
+        vec![Event::WorkspacesChanged { workspaces }]
+    }
+
+    fn apply(&mut self, event: Event) -> Option<Event> {
+        match event {
+            Event::WorkspacesChanged { workspaces } => {
+                self.workspaces = workspaces.into_iter().map(|ws| (ws.id, ws)).collect();
+            }
+            Event::WorkspaceUrgencyChanged { id, urgent } => {
+                for ws in self.workspaces.values_mut() {
+                    if ws.id == id {
+                        ws.is_urgent = urgent;
+                    }
+                }
+            }
+            Event::WorkspaceActivated { id, focused } => {
+                let ws = self.workspaces.get(&id);
+                let ws = ws.expect("activated workspace was missing from the map");
+                let output = ws.output.clone();
+
+                for ws in self.workspaces.values_mut() {
+                    let got_activated = ws.id == id;
+                    if ws.output == output {
+                        ws.is_active = got_activated;
+                    }
+
+                    if focused {
+                        ws.is_focused = got_activated;
+                    }
+                }
+            }
+            Event::WorkspaceActiveWindowChanged {
+                workspace_id,
+                active_window_id,
+            } => {
+                let ws = self.workspaces.get_mut(&workspace_id);
+                let ws = ws.expect("changed workspace was missing from the map");
+                ws.active_window_id = active_window_id;
+            }
+            event => return Some(event),
+        }
+        None
+    }
+}
+
+impl EventStreamStatePart for WindowsState {
+    fn replicate(&self) -> Vec<Event> {
+        let windows = self.windows.values().cloned().collect();
+        vec![Event::WindowsChanged { windows }]
+    }
+
+    fn apply(&mut self, event: Event) -> Option<Event> {
+        match event {
+            Event::WindowsChanged { windows } => {
+                self.windows = windows.into_iter().map(|win| (win.id, win)).collect();
+            }
+            Event::WindowOpenedOrChanged { window } => {
+                let (id, is_focused) = match self.windows.entry(window.id) {
+                    Entry::Occupied(mut entry) => {
+                        let entry = entry.get_mut();
+                        *entry = window;
+                        (entry.id, entry.is_focused)
+                    }
+                    Entry::Vacant(entry) => {
+                        let entry = entry.insert(window);
+                        (entry.id, entry.is_focused)
+                    }
+                };
+
+                if is_focused {
+                    for win in self.windows.values_mut() {
+                        if win.id != id {
+                            win.is_focused = false;
+                        }
+                    }
+                }
+            }
+            Event::WindowClosed { id } => {
+                let win = self.windows.remove(&id);
+                win.expect("closed window was missing from the map");
+            }
+            Event::WindowFocusChanged { id } => {
+                for win in self.windows.values_mut() {
+                    win.is_focused = Some(win.id) == id;
+                }
+            }
+            Event::WindowUrgencyChanged { id, urgent } => {
+                for win in self.windows.values_mut() {
+                    if win.id == id {
+                        win.is_urgent = urgent;
+                        break;
+                    }
+                }
+            }
+            Event::WindowLayoutsChanged { changes } => {
+                for (id, update) in changes {
+                    let win = self.windows.get_mut(&id);
+                    let win = win.expect("changed window was missing from the map");
+                    win.layout = update;
+                }
+            }
+            event => return Some(event),
+        }
+        None
+    }
+}
+
+impl EventStreamStatePart for KeyboardLayoutsState {
+    fn replicate(&self) -> Vec<Event> {
+        if let Some(keyboard_layouts) = self.keyboard_layouts.clone() {
+            vec![Event::KeyboardLayoutsChanged { keyboard_layouts }]
+        } else {
+            vec![]
+        }
+    }
+
+    fn apply(&mut self, event: Event) -> Option<Event> {
+        match event {
+            Event::KeyboardLayoutsChanged { keyboard_layouts } => {
+                self.keyboard_layouts = Some(keyboard_layouts);
+            }
+            Event::KeyboardLayoutSwitched { idx } => {
+                let kb = self.keyboard_layouts.as_mut();
+                let kb = kb.expect("keyboard layouts must be set before a layout can be switched");
+                kb.current_idx = idx;
+            }
+            event => return Some(event),
+        }
+        None
+    }
+}
+
+impl EventStreamStatePart for OverviewState {
+    fn replicate(&self) -> Vec<Event> {
+        vec![Event::OverviewOpenedOrClosed {
+            is_open: self.is_open,
+        }]
+    }
+
+    fn apply(&mut self, event: Event) -> Option<Event> {
+        match event {
+            Event::OverviewOpenedOrClosed { is_open } => {
+                self.is_open = is_open;
+            }
+            event => return Some(event),
+        }
+        None
+    }
+}
+
+impl EventStreamStatePart for ConfigState {
+    fn replicate(&self) -> Vec<Event> {
+        vec![Event::ConfigLoaded {
+            failed: self.failed,
+        }]
+    }
+
+    fn apply(&mut self, event: Event) -> Option<Event> {
+        match event {
+            Event::ConfigLoaded { failed } => {
+                self.failed = failed;
+            }
+            event => return Some(event),
+        }
+        None
+    }
+}

niri-visual-tests/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "niri-visual-tests"
+version.workspace = true
+description.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+
+[dependencies]
+adw = { version = "0.7.2", package = "libadwaita", features = ["v1_4"] }
+anyhow.workspace = true
+gtk = { version = "0.9.7", package = "gtk4", features = ["v4_12"] }
+niri = { version = "25.5.1", path = ".." }
+niri-config = { version = "25.5.1", path = "../niri-config" }
+smithay.workspace = true
+tracing.workspace = true
+tracing-subscriber.workspace = true

niri-visual-tests/README.md

@@ -0,0 +1,14 @@
+# niri-visual-tests
+
+> [!NOTE]
+>
+> This is a development-only app, you shouldn't package it.
+
+This app contains a number of hard-coded test scenarios for visual inspection.
+It uses the real niri layout and rendering code, but with mock windows instead of Wayland clients.
+The idea is to go through the test scenarios and check that everything *looks* right.
+
+## Running
+
+You will need recent GTK and libadwaita.
+Then, `cargo run`.

niri-visual-tests/resources/style.css

@@ -0,0 +1,3 @@
+.anim-control-bar {
+    padding: 12px;
+}

niri-visual-tests/src/cases/gradient_angle.rs

@@ -0,0 +1,73 @@
+use std::f32::consts::{FRAC_PI_2, PI};
+use std::time::Duration;
+
+use niri::render_helpers::border::BorderRenderElement;
+use niri_config::{Color, CornerRadius, GradientInterpolation};
+use smithay::backend::renderer::element::RenderElement;
+use smithay::backend::renderer::gles::GlesRenderer;
+use smithay::utils::{Physical, Point, Rectangle, Size};
+
+use super::{Args, TestCase};
+
+pub struct GradientAngle {
+    angle: f32,
+    prev_time: Duration,
+}
+
+impl GradientAngle {
+    pub fn new(_args: Args) -> Self {
+        Self {
+            angle: 0.,
+            prev_time: Duration::ZERO,
+        }
+    }
+}
+
+impl TestCase for GradientAngle {
+    fn are_animations_ongoing(&self) -> bool {
+        true
+    }
+
+    fn advance_animations(&mut self, current_time: Duration) {
+        let delta = if self.prev_time.is_zero() {
+            Duration::ZERO
+        } else {
+            current_time.saturating_sub(self.prev_time)
+        };
+        self.prev_time = current_time;
+
+        self.angle += delta.as_secs_f32() * PI;
+
+        if self.angle >= PI * 2. {
+            self.angle -= PI * 2.
+        }
+    }
+
+    fn render(
+        &mut self,
+        _renderer: &mut GlesRenderer,
+        size: Size<i32, Physical>,
+    ) -> Vec<Box<dyn RenderElement<GlesRenderer>>> {
+        let (a, b) = (size.w / 4, size.h / 4);
+        let size = (size.w - a * 2, size.h - b * 2);
+        let area = Rectangle::new(Point::from((a, b)), Size::from(size)).to_f64();
+
+        [BorderRenderElement::new(
+            area.size,
+            Rectangle::from_size(area.size),
+            GradientInterpolation::default(),
+            Color::new_unpremul(1., 0., 0., 1.),
+            Color::new_unpremul(0., 1., 0., 1.),
+            self.angle - FRAC_PI_2,
+            Rectangle::from_size(area.size),
+            0.,
+            CornerRadius::default(),
+            1.,
+            1.,
+        )
+        .with_location(area.loc)]
+        .into_iter()
+        .map(|elem| Box::new(elem) as _)
+        .collect()
+    }
+}

niri-visual-tests/src/cases/gradient_area.rs

@@ -0,0 +1,119 @@
+use std::f32::consts::{FRAC_PI_4, PI};
+use std::time::Duration;
+
+use niri::layout::focus_ring::FocusRing;
+use niri::render_helpers::border::BorderRenderElement;
+use niri_config::{Color, CornerRadius, FloatOrInt, GradientInterpolation};
+use smithay::backend::renderer::element::RenderElement;
+use smithay::backend::renderer::gles::GlesRenderer;
+use smithay::utils::{Physical, Point, Rectangle, Size};
+
+use super::{Args, TestCase};
+
+pub struct GradientArea {
+    progress: f32,
+    border: FocusRing,
+    prev_time: Duration,
+}
+
+impl GradientArea {
+    pub fn new(_args: Args) -> Self {
+        let border = FocusRing::new(niri_config::FocusRing {
+            off: false,
+            width: FloatOrInt(1.),
+            active_color: Color::from_rgba8_unpremul(255, 255, 255, 128),
+            inactive_color: Color::default(),
+            urgent_color: Color::default(),
+            active_gradient: None,
+            inactive_gradient: None,
+            urgent_gradient: None,
+        });
+
+        Self {
+            progress: 0.,
+            border,
+            prev_time: Duration::ZERO,
+        }
+    }
+}
+
+impl TestCase for GradientArea {
+    fn are_animations_ongoing(&self) -> bool {
+        true
+    }
+
+    fn advance_animations(&mut self, current_time: Duration) {
+        let delta = if self.prev_time.is_zero() {
+            Duration::ZERO
+        } else {
+            current_time.saturating_sub(self.prev_time)
+        };
+        self.prev_time = current_time;
+
+        self.progress += delta.as_secs_f32() * PI;
+
+        if self.progress >= PI * 2. {
+            self.progress -= PI * 2.
+        }
+    }
+
+    fn render(
+        &mut self,
+        renderer: &mut GlesRenderer,
+        size: Size<i32, Physical>,
+    ) -> Vec<Box<dyn RenderElement<GlesRenderer>>> {
+        let mut rv = Vec::new();
+
+        let f = (self.progress.sin() + 1.) / 2.;
+
+        let (a, b) = (size.w / 4, size.h / 4);
+        let rect_size = Size::from((size.w - a * 2, size.h - b * 2));
+        let area = Rectangle::new(Point::from((a, b)), rect_size).to_f64();
+
+        let g_size = Size::from((
+            (size.w as f32 / 8. + size.w as f32 / 8. * 7. * f).round() as i32,
+            (size.h as f32 / 8. + size.h as f32 / 8. * 7. * f).round() as i32,
+        ));
+        let g_loc = Point::from(((size.w - g_size.w) / 2, (size.h - g_size.h) / 2)).to_f64();
+        let g_size = g_size.to_f64();
+        let mut g_area = Rectangle::new(g_loc, g_size);
+        g_area.loc -= area.loc;
+
+        self.border.update_render_elements(
+            g_size,
+            true,
+            true,
+            false,
+            Rectangle::default(),
+            CornerRadius::default(),
+            1.,
+            1.,
+        );
+        rv.extend(
+            self.border
+                .render(renderer, g_loc)
+                .map(|elem| Box::new(elem) as _),
+        );
+
+        rv.extend(
+            [BorderRenderElement::new(
+                area.size,
+                g_area,
+                GradientInterpolation::default(),
+                Color::new_unpremul(1., 0., 0., 1.),
+                Color::new_unpremul(0., 1., 0., 1.),
+                FRAC_PI_4,
+                Rectangle::from_size(rect_size).to_f64(),
+                0.,
+                CornerRadius::default(),
+                1.,
+                1.,
+            )
+            .with_location(area.loc)]
+            .into_iter()
+            .map(|elem| Box::new(elem) as _),
+        );
+
+        rv
+    }
+}

niri-visual-tests/src/cases/gradient_oklab.rs

@@ -0,0 +1,54 @@
+use niri::render_helpers::border::BorderRenderElement;
+use niri_config::{
+    Color, CornerRadius, GradientColorSpace, GradientInterpolation, HueInterpolation,
+};
+use smithay::backend::renderer::element::RenderElement;
+use smithay::backend::renderer::gles::GlesRenderer;
+use smithay::utils::{Physical, Point, Rectangle, Size};
+
+use super::{Args, TestCase};
+
+pub struct GradientOklab {
+    gradient_format: GradientInterpolation,
+}
+
+impl GradientOklab {
+    pub fn new(_args: Args) -> Self {
+        Self {
+            gradient_format: GradientInterpolation {
+                color_space: GradientColorSpace::Oklab,
+                hue_interpolation: HueInterpolation::Shorter,
+            },
+        }
+    }
+}
+
+impl TestCase for GradientOklab {
+    fn render(
+        &mut self,
+        _renderer: &mut GlesRenderer,
+        size: Size<i32, Physical>,
+    ) -> Vec<Box<dyn RenderElement<GlesRenderer>>> {
+        let (a, b) = (size.w / 6, size.h / 3);
+        let size = (size.w - a * 2, size.h - b * 2);
+        let area = Rectangle::new(Point::from((a, b)), Size::from(size)).to_f64();
+
+        [BorderRenderElement::new(
+            area.size,
+            Rectangle::from_size(area.size),
+            self.gradient_format,
+            Color::new_unpremul(1., 0., 0., 1.),
+            Color::new_unpremul(0., 1., 0., 1.),
+            0.,
+            Rectangle::from_size(area.size),
+            0.,
+            CornerRadius::default(),
+            1.,
+            1.,
+        )
+        .with_location(area.loc)]
+        .into_iter()
+        .map(|elem| Box::new(elem) as _)
+        .collect()
+    }
+}