fix(keymap): repair refreshing behavior (niri), options not working and key rendering

[MateusAquino]

Plugin

• Id: blackbartblues/keymap
• New plugin
• Update to an existing plugin (version bumped in plugin.toml)

What it does

Compatibility with other compositors had several major problems, notably: refreshing, loading indefinitely, inconsistent key names (eg.: XF86Calculator) and options which does not take any effect. This PR aims to fix these problems and add some improvements.

cc: @blackbartblues (maintainer)

Added

[Click to Expand] New merge_similar option: shortcuts that trigger the same action (eg. "Close Window" on Super+W and Alt+F4) collapses into a single read-only row listing every key combination.






Disabled	Enabled

Fixed

[Click to Expand] Fixed panel stuck on "Loading keybindings" (tested on niri) after closing and reopening the panel: refreshes were replaying the full request backlog and execution is also deferred from the 25 ms state-watch callback into the service's own update tick, so a parse can no longer be aborted by a shared callback budget mid-flight. Note refreshing with the UI open was also not working (tested on niri);


[Click to Expand] Fixed missing debugging logs/errors: Internal parser errors now surface their actual Lua error text on the error panel instead of an opaque "unknown error";


[Click to Expand] Fixed show_undescribed=true option, which was NOT hiding Niri binds whose hotkey-overlay-title is missing, empty (""), or null values;




Before	After

[Click to Expand] Fixed merge_sequential=true option, which was NOT merging sequential keybindings (tested on niri);




Before	After

[Click to Expand] Fixed long keybindings being replaced with a single merged keybind.




Before	After

Changed

[Click to Expand] Unified the key display-name tables across Hyprland, Niri, and MangoWC so the same key reads identically for every compositor (ie. missing `XF86Calculator`, `XF86Mail`, touchpad scrolls, and punctuations on Niri/Mango service which was only present in Hyprland service).




Before	After

External dependencies

Unchanged: hyprctl, niri, mango, mmsg, xdg-open (already declared in plugin.toml). No new external calls.

Testing

• 15 Lua test files pass, including three new ones: niri_settings_test.lua (sequential merging, undescribed-title filtering, similar-action merging, refresh-watcher echo suppression), merge_similar_test.lua (MangoWC + Hyprland similar-action merging), and niri_scanner_test.lua (rewritten scanners checked byte-for-byte against the original implementations over a corpus plus 3000 fuzzed inputs).
• 2 Python structural tests pass (command_library_test.py, i18n_test.py).
• Manually exercised against a live Niri session with a 70-bind config + 2 includes: boot load, refresh button, close/reopen panel, merge_sequential on/off, show_undescribed on/off, merge_similar on/off.

Compositors:

• Tested on Niri
• Tested on Hyprland
• Tested on Sway
• Tested on another compositor: MangoWC (parser-level tests only)
• Noctalia version tested against: v5.0.0-beta.7
• Plugin API level: 9

Screenshots / Videos

There are screenshots on all of the expandable entries above in the PR.

Here's also a video showing how it was before (1.4.0) and after (1.5.0) patches on Niri.

Before

before.mp4

After

after.mp4

Checklist

• The directory name matches the part of id after the / in plugin.toml exactly.
• It ships plugin.toml, README.md, thumbnail.webp, and translations/en.json.
• README.md follows the
  README template, documents
  every entry id and dependency, and includes exact panel IPC commands and launcher prefixes where applicable.
• I created thumbnail.webp with the thumbnail generator.
• version follows semver and is bumped in this PR; plugin_api is the oldest API level this plugin requires.
• Every non-English translation in this PR uses a locale supported by Noctalia core, and I can read, write, and
  understand that language well enough to review and maintain it (no unreviewed machine/LLM translations).
• I did not edit catalog.toml; CI generates it.
• This PR touches exactly one plugin directory.

Code review attestation

Plugins run as trusted, unsandboxed Luau in the user's session. Confirm:

• The code is readable and not obfuscated, minified, or generated.
• It does not download and execute remote code.
• Every network call, filesystem write, and spawned process is something the description above accounts for.
• I have the right to publish this code under the license declared in plugin.toml.

[github-actions]

CC @blackbartblues

[ItsLemmy]

waiting for @blackbartblues review

[blackbartblues]

I checked this again and found a few issues that I think should be fixed before merging.

The biggest problem is the parser time slicing. It waits 12 ms before yielding, but Noctalia gives update callbacks
the same 12 ms budget. Large configurations can therefore hit the limit before the parser yields. The timer check
also resets for every included file, so configurations split into many short files may still run in one callback. An
old Niri or MangoWC parse is also not cancelled after changing the compositor and can overwrite the new napshot.

merge_similar also has some correctness issues. Niri can merge different actions that use the same title. MangoWC can merge different sequential ranges because the merged ranges lose their action. Hyprland can merge unrelated undescribed Lua binds. The conflict checks also ignore bind.combos, which allows an existing shortcut to be added again.

There are a few smaller issues as well, such as merged release binds being reported as press binds and long key
combinations overflowing their column.

All current tests pass, but the CPU tests do not actually measure the coroutine parser and do not force the multi
tick yield and resume path. GitHub CI also does not run the Keymap tests.

I think the parser lifecycle, merged combo handling and related regression tests should be fixed before this is
merged.

[MateusAquino]

Thanks for reviewing @blackbartblues, if I understood everything correctly then 2aabbc6 should be it, yet I still have only tested it w/ Niri, would be nice if you could check for your Hyprland setup as well (specially the merge similar issue) :)

Also:

GitHub CI also does not run the Keymap tests.

Btw, I'm not sure if I'm able to edit .github/workflows for this matter on this PR, I thought plugin tests were only being run locally, or am I missing something?