niri-ribbon 0.1.0: viewport position indicator for niri scrollable-tiling

[luochen1990]

Plugin

• Id: luochen1990/niri-ribbon
• New plugin
• Update to an existing plugin (version bumped in plugin.toml)

What it does

A bar widget for niri's scrollable-tiling layout: draws the focused workspace's whole scrolling ribbon as a slim strip and highlights the region currently inside the viewport, so you can see at a glance how many columns are hidden to the left and right. Scrolling over the widget moves the focused column (focus-column-left/right).

The highlight is estimated geometrically from the niri IPC state (the IPC exposes no live viewport offset yet — exact viewport offsets are being implemented in niri#4147); the estimation model and its limits are documented in detail at the top of ribbon.luau and in the README Notes.

External dependencies

• niri — declared in dependencies. The plugin shells out to: read-only niri msg -j windows/workspaces/outputs queries on structural changes, one persistent niri msg -j event-stream subscription (killed automatically on widget unmount), and niri msg action focus-column-left|right on scroll. No network access, no filesystem writes.

Testing

• Tested on Niri
• Tested on Hyprland
• Tested on Sway
• Tested on another compositor:
• Noctalia version tested against: development build pinned 2026-08-26 (after 5.0.0-beta.8; onScroll requires ≥ beta.4)
• Plugin API level: 3

Daily-driven on my own machine for weeks (originally as a locally packaged plugin; this is the same code prepared for upstreaming). noctalia plugins lint passes with 0 errors / 0 warnings.

Screenshots / Videos

The card below is the committed thumbnail.webp (generated with the official thumbnail generator from a live bar screenshot — the slim strip left of the workspace numbers is the ribbon; the purple segment is the current viewport).

Checklist

Ready-for-review requirement: Every box in this section must be checked. If any statement is not true, keep the
pull request as Draft. An explanation does not replace a required check.

• 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:
Ready-for-review requirement: Every attestation below must be checked.

• 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.

---

Draft note — why one box stays unchecked.

• Right to publish: the core idea (geometric viewport estimation from niri IPC state) originates from ews/noctalia-niri-ribbon by J Pablo Puerta. That repository ships no license, so I opened ews/noctalia-niri-ribbon#1 asking the author to add one. This plugin is a ground-up rewrite (Python+QML → Luau; zero shared code — only the algorithm idea carries over). I will check this box once the licensing question is settled.
• zh-Hans.json is self-authored; Chinese is my native language.

[luochen1990]

The remaining validate failure is only the pending thumbnail.webp (tracked in the checklist); I'll generate it with the official thumbnail generator from a live screenshot and push it before marking ready-for-review. Everything else passes (enforce ✓, manifest validation ✓, nested translation keys fixed in acb86c3).

[ItsLemmy]

Licensing: agreed, this is fine to merge. The upstream project is Python + QML
(niri_ribbon.py, BarWidget.qml, Main.qml, manifest.json) and this plugin is a single Luau
file written against the v5 plugin spec, so no code is shared verbatim, and what carries over
is the algorithm idea, which is not copyrightable expression. Attribution is already in
plugin.toml, the ribbon.luau header and README Notes, so no further licensing work is needed
on your side and the right-to-publish box can be checked.