niri-notch-rs

Animated Dynamic Island-style companion notch for the Niri Wayland compositor.

niri-notch-rs is a companion daemon, not an in-process compositor plugin. It owns a GTK3 + gtk-layer-shell overlay surface and integrates with Niri, Waybar, mako, and playerctl through narrow, testable effect boundaries.

Features

• Top-center animated layer-shell notch.
• Compact and expanded states with damped spring sizing.
• Niri workspace and focused-window context.
• mako notification interception:
  • auto-open on new notification,
  • cache notification text/chip,
  • dismiss duplicate mako card after a short delay.
• playerctl media fallback.
• Mouse interactions:
  • hover opens,
  • left click clears notification or toggles media,
  • right click opens the user's Niri control center,
  • wheel up/down switches Niri workspaces.
• Waybar companion styling pattern: Waybar as left/right secondary rails, notch as primary center surface.
• Testable internals:
  • src/core.rs: pure reducer, no I/O,
  • src/install.rs: pure Niri config managed-block transforms,
  • src/main.rs: GTK UI, snapshot collection, filesystem/process effects.

CLI

niri-notch-rs doctor
niri-notch-rs doctor --json
niri-notch-rs install --user --dry-run
niri-notch-rs install --user
niri-notch-rs uninstall --user --dry-run
niri-notch-rs uninstall --user
niri-notch-rs preview

doctor checks:

• niri
• gtk-layer-shell-0 via pkg-config
• waybar
• makoctl
• playerctl
• Niri config validity
• Niri layer query availability

install --user writes an idempotent managed block to ~/.config/niri/config.kdl and creates a timestamped backup before modifying the file.

Build

Arch/CachyOS dependencies:

sudo pacman -S --needed rust gtk3 gtk-layer-shell pkgconf waybar mako playerctl

Build and install locally:

cargo build --release --locked
install -Dm755 target/release/niri-notch-rs ~/.local/bin/niri-notch-rs
~/.local/bin/niri-notch-rs doctor

Niri integration

Manual config example:

spawn-sh-at-startup "waybar"
spawn-sh-at-startup "~/.local/bin/niri-notch-rs"

Or let the CLI manage the niri-notch-rs block:

niri-notch-rs install --user --dry-run
niri-notch-rs install --user
niri validate -c ~/.config/niri/config.kdl

Recommended Waybar setup:

"modules-center": []

Then style Waybar as companion rails rather than another strong center island.

Quality gates

CI and release candidates run:

cargo fmt -- --check
cargo test --locked
cargo clippy --locked --all-targets --all-features -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --locked --no-deps
cargo build --release --locked

Architecture

Event / snapshot / pointer input
  -> AppEvent
  -> reduce(AppState, AppEvent) -> (AppState, Vec<Effect>)
  -> render AppState
  -> run Effect through a narrow effect runner

Install/config changes follow the same rule:

Niri config text + InstallPlan
  -> pure transform
  -> backup + write in the effect layer

This keeps desktop behavior testable without GTK, Niri, mako, playerctl, or a live Wayland session.

Video

A Remotion showcase video lives in:

video/

Render it with:

cd video
npm install --include=dev
npm run typecheck
npm run still
npm run render

The composition uses real GitHub and Niri desktop screenshots from the project smoke-test pass.

Packaging

An Arch packaging draft lives in:

packaging/arch/PKGBUILD
packaging/arch/.SRCINFO

Status

Pre-1.0 daily-driver prototype. Verified locally on CachyOS + Niri + Waybar at 1920x1080@180Hz.