01. Overview & Architecture

Profile: v1.2.1
Schema validatedSource pinned
Purpose
Auto-tiling KWin script, successor in spirit to Bismuth.
Compatibility
Any distro (Server: BOTH)
Desktop Part
DE extensions
Window Manager & Theme
KDE Plasma / Other

02. Installation & Deployment

Before you installThis changes your desktop configuration and installs packages. Run it as your normal user, never with sudo: it asks for sudo only where a step needs it (listed below).The guided installer shows its plan first. Files it would replace are kept unless you approve. Everything it copies, clones or appends to in your home folder is backed up and verified first, and --rollback restores it. Packages, sudo changes and the other commands listed under Impact are not undone.
IntegrityEach release from main builds the installers in GitHub Actions and signs them with a GitHub build attestation. Verify your download against the repository, not this website (Option B, step 2). If it does not verify, don't run it.
ImpactPackages: kwin-polonium (some from the Arch AUR)
RecoveryGuided: backups in ~/.local/state/0xtsoa/backups/, undo with bash install.sh --rollback.Manual: the steps below only write in the download folder or run listed commands.
Option A: manual installAdvanced
Read the source at the reviewed commit, back up, then run each step yourself.
$git clone https://github.com/zeroxoneafour/polonium ~/0xtsoa-review/zeroxoneafour-polonium# 1. clone to a review folder
$git -C ~/0xtsoa-review/zeroxoneafour-polonium checkout --detach 227967ed448205d42b5e63e4cc4b868d72606467# 2. the reviewed commit
Then the steps. Package commands are written for Arch; on other distros use your package manager.

Step-by-step deployment protocol

Step-by-step deployment
1Install kwin-polonium (AUR)
$yay -S kwin-polonium # AUR
$# Other distros: see the upstream README
2Enable it
$# System Settings > Window Management > KWin Scripts / Desktop Effects: enable it
$qdbus org.kde.KWin /KWin reconfigure
Option B: guided installerRecommended
The same steps as one script for any distro. It shows the plan first, keeps files you already have unless you approve replacing them, and backs up everything it changes in your home folder. Never pipe it into a shell.
$curl -fsSLo install.sh 'https://www.0xtsoa.dev/configs/zeroxoneafour/polonium/install.sh'# 1. download
$gh attestation verify install.sh --repo nyharena25/0xTsoa --signer-workflow nyharena25/0xTsoa/.github/workflows/attest-installers.yml# 2. verify (GitHub CLI 2.49+, signed in)
$less install.sh# 3. read it
$bash install.sh --dry-run# 4. preview: changes nothing
$bash install.sh# 5. install (asks first)
$bash install.sh --rollback# undo the file changes
View script in browserOther options: --force (replace conflicts, backed up first), --yes, --help

03. Documentation & Guide

Source: zeroxoneafour/poloniumRef: 227967ed44
readme.md|GitHub Flavored Markdown

features

  • Works in Wayland Plasma 6.4 and up (6.7 recommended)
  • Custom moddable tiling engine backend
  • Edit tile sizes with the integrated KWin GUI
  • Move and tile windows with your mouse and keyboard
  • Set layouts independently of desktop and screen
  • DBus integration to save layouts and configurations after logging out

x11

X11 is not supported. If you encounter an issue running the script on X11, make sure it is reproducible in Wayland before submitting a bug report.

building/installing

Requires npm and kpackagetool6

Commands -

  • Build/Install/Clean - make
  • Build - make build
  • Install/Reinstall - make install
  • Clean build - make clean
  • Clean build and target - make cleanall
  • Build and install DBus service - make dbus

getting logs

To get logs, do the following -

  • Set log level to "Log" in settings
  • Log out and log in again, and immediately reproduce the issue if possible after logging in
  • Run the below command. An explanation is provided if you are wary about running it. It only works if all of the required executables are installed.
  • journalctl --since="$(journalctl -g "Polonium LOG: controller initialized" -n 1 --output=short-iso | cut -d ' ' -f1)" -g "[Pp]olonium" | wl-copy
    1. Gets the timestamp of the first controller message
    2. Gets the journalctl log since that message
    3. Greps for Polonium-related output
    4. Copies the output into your clipboard
  • If you don't have wl-copy, remove that part from the end of the command and run it, and manually copy the output

Depending on the issue, more precise logs may be needed. For these logs, set log level to "Debug" instead.

license

Majority of this project is MIT licensed

name

Came from a comment on my old script, you can find the script and comment here

GitHub Flavored Markdown (github-markdown-css)README snapshot at 227967ed44