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]

Approved