fix(keybind-cheatsheet): stage the Hyprland Lua refresh across CPU budget windows

[sboo]

Plugin

• Id: kenn/keybind-cheatsheet
• New plugin
• Update to an existing plugin (version bumped in plugin.toml)

What it does

Fixes the panel never loading on mid-size Hyprland Lua configs (#663).

Root cause: the completion callback of noctalia.runAsync("hyprctl binds -j", ...) performed the entire refresh inside one callback — JSON-decoding the full payload (~40 KB / 88 bindings on a real-world config), building the binding list, running
the Lua category scan (scanHyprLua), categorizing, and writing the cache. Noctalia's Luau host enforces a hard ~25 ms CPU budget per callback; when the chain exceeds it, the callback is killed before finishRefresh publishes anything, so the panel stays on "Reading keybinds…" forever, no error is ever shown (the abort is only in the host
log), and bindings-cache.json is never written, every shell start re-fails.

Fix: stage the work across multiple state-watch callbacks, reusing the same state-ping pattern the Niri parser and the self-test already use. The refresh now runs decode → build bindings in slices (HYPR_BINDING_SLICE = 16) → Lua category
scan → categorize in slices → publish + cache write, each in its own budget window. Stale pings are dropped via generation/request/step guards; all existing error paths (hyprctl missing/failed, invalid JSON, failed-refresh retention) are preserved.

This is the same CPU-budget failure class as #606; v0.2.6 (PR #639) fixed it by deferring the work into the async completion callback, this PR stages that callback itself.

Authorship disclosure: I am a software developer, but I have no prior experience with Luau. The initial implementation of this patch was produced with AI assistance, then debugged and iterated against real hardware. I reviewed the final diff block by block.

External dependencies

None added. hyprctl remains the plugin's only dependency (already declared in plugin.toml), used only by the Hyprland Lua path. This PR adds no network calls, no new filesystem writes, and no new spawned processes, only additional noctalia.state keys used to stage the existing refresh.

Testing

• Tested on Niri

• Tested on Hyprland

• Tested on Sway

• Tested on another compositor:

• Noctalia version tested against: 5.0.1-1.1 (Arch/CachyOS package)

• Plugin API level: 9

• Reproduction machine: CachyOS, Hyprland 0.56.2-2.1, AMD Ryzen 5 5600, native Lua config (~/.config/hypr/hyprland.lua requiring config/*.lua, no hyprland.conf), 88 bindings, hyprctl binds -j = 40,072 bytes.

• Before this patch: panel stuck on "Reading keybinds…" forever; host log showed script callback 'async command callback' exceeded its CPU budget (and, with the scan stage alone, the same abort at the categorization loop); bindings-cache.json never written; IPC refresh returned ok: dispatched 1 but the snapshot never landed.

• After this patch: panel populates; refresh works via IPC, panel toggle, and after a full shell restart (startup path); no budget errors across repeated refreshes and hot reloads; bindings-cache.json written.

• noctalia msg plugin kenn/keybind-cheatsheet:data all self-test → hypr_conf 5/5, hypr_lua 4/4, mango 9/9, niri 5/5, passed: true.

• Two-machine differential from [keybind-cheatsheet][BUG] Panel stuck on "Reading keybinds…" — async hyprctl binds -j callback exceeds CPU budget on mid-size Hyprland Lua configs #663 (identical software, near-identical binds.lua): 88 binds / 40,072 B failed pre-patch on Ryzen 5 5600; 82 binds / 37,381 B worked on Ryzen 9 7900X3D.

Screenshots / Videos

Before/after captures: (1) panel stuck on "Reading keybinds…" pre-patch, (2) panel
populated post-patch.

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.
• thumbnail.webp is present and relevant; for a new plugin I created it with the thumbnail generator, and for an update I regenerated it with the generator if the visual identity or user-facing appearance changed.
  (Unchanged in this PR — no visual identity change, so not regenerated.)
• version follows semver and is bumped in this PR; plugin_api is the oldest
  API level this plugin requires. (0.2.6 → 0.2.7; plugin_api stays 9.)
• 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. (keybind-cheatsheet/:
  service.luau + plugin.toml version bump only.)

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. (MIT, unchanged.)

[Noctalia-CI]

The description now contains the required template structure.

[Noctalia-CI]

CC @cheerfulScumbag: this pull request was automatically moved to draft until you have had a chance to look at it. It will be marked ready for review automatically once you reply here.

[cheerfulScumbag]

looks good to me!