feat(core): give a plugin the right button

[spscream]

The first of the two APIs you asked to come back on their own, from #1107's 4a2cacb. Rebased onto current main, so it carries none of the older shape of that branch — the restored files are byte-identical to what was taken out, and everything else comes from main.

What it is

A RIGHT press now reaches the plugin that painted the node under it, through on_context, with the same hit payload on_click gets.

Why its own hook, and not a button field on the click

The two presses do not mean the same thing to anyone. Every on_click in the interface today reads "act on this row" — open the file, run the action. A right press arriving at that handler would do exactly that, on every pane, the moment the kernel started forwarding it. A separate hook is silent by default: a pane that has not been taught what a right press means never hears one.

For the same reason the kernel resolves none of its own verbs here. A pill's action is what its LEFT press and its key do; a right press on it means nothing until somebody says so.

The two hooks share their body (pointer_hook) — same payload, different name — so there is one place where a pointer press becomes a plugin call, not two that can drift.

Why it needs no consumer to be reviewable

Unlike keys, this one has no contract to get wrong: the press either reaches the plugin that owns the node or it does not. tests/mouse_context.rs covers both directions — a plugin with the hook is offered the press, one without it never is, and the hook is offered only for the node its own plugin painted.

Checks

cargo nextest run --all on this branch: 2643 tests, the only failures the four that reproduce on main in this environment (shared_tests::a_host_with_sharing_off_is_used_the_old_way, spawn::tests::resolve_host_accepts_the_backend_name_the_interface_carries, cli::automations::tests::tick_reports_fired_and_skipped_arrays, shared_sessions::sync_with_no_shareable_host_configured_is_an_empty_report). fmt and clippy --all-targets clean.

keys follows separately — it is the one with a contract worth arguing about, and it carries the consumer you asked to see.

[greptile-apps]

Greptile Summary

The PR adds an opt-in on_context plugin hook and routes right-button presses from terminal input to the plugin that painted the targeted node.

• Keeps right presses separate from existing left-click actions.
• Preserves modal and floating-pane pointer ownership.
• Marks the interface dirty only when the context handler reports that it handled the press.
• Documents the hook in the plugin guide and Lua API declarations.
• Adds direct host tests and an end-to-end terminal-input routing test.

Confidence Score: 5/5

The PR appears safe to merge; the previously missing coordinator-level routing coverage is now supplied by an end-to-end SGR mouse-input test.

No actionable new defects or repository-rule violations remain. The prior finding about bypassing coordinator routing is fully addressed by the new test that sends raw terminal mouse reports and observes separate on_context and on_click results through rendered output.

Important Files Changed

Filename	Overview
src/coordinator/mouse.rs	Routes right-button down events through modal-aware and float-aware hit-target dispatch without invoking left-click behavior.
src/kernel/host/mod.rs	Adds the opt-in on_context hook and shares payload invocation logic with on_click.
tests/tui_e2e.rs	Adds terminal-level coverage proving right and left presses reach their respective plugin hooks.
tests/mouse_context.rs	Verifies direct hook separation and silence for plugins that do not declare on_context.
docs/PLUGINS.md	Documents right-button semantics, routing boundaries, and terminal forwarding requirements.
ui/lib/thurbox.d.lua	Publishes the optional on_context callback in the Lua type declarations.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Terminal RIGHT press] --> B[crossterm MouseEvent]
    B --> C[App::on_mouse]
    C --> D[App::on_context_click]
    D --> E{Modal open?}
    E -- Yes --> F[Swallow press]
    E -- No --> G[Resolve target_at coordinates]
    G --> H{Floating plugin grabbed?}
    H -- Yes, target belongs to float --> I[dispatch_context]
    H -- Yes, other target --> F
    H -- No, target exists --> I
    I --> J[LuaHost::on_context]
    J --> K[Plugin on_context hit]
    K --> L{Handled?}
    L -- Yes --> M[Mark UI dirty]
    L -- No --> N[No redraw]

Loading

_{Reviews (2): Last reviewed commit: "test(core): drive the right button throu..." | Re-trigger Greptile}

[LeTuR]

Reviewed at c24a322b. Nothing blocking: a right press reaches only the plugin that painted the node, a pane without on_context never hears it, and no verb, focus change or selection runs on it. This is the split #1107's review asked for.

CI. 22 checks: 15 passed, 0 failed, 0 cancelled, 0 held, 7 skipped by their if: (install scripts x2, ShellCheck, website, winget, SonarQube, the old title checker). Nextest ran all three new tests on Linux, the pty e2e included. Windows ran the two host tests only, since tui_e2e is unix-only.

Description vs code. pointer_hook is one body; only the hook name differs. The float guard in the coordinator is a second copy (inline). The description predates c24a322 and names a painter-only test that neither test file has (inline).

Security. No security findings in what this adds. Delivery follows the painted target; the payload is that node's own id/class/role and local coordinates; focus does not move; modals and floats swallow the press as they do a left one; bands are kernel slots with no plugin target; the hook runs under the same enter and budget. One window inherited from the left press is asked inline: click_targets survive a reload.

All five comments are nit: or questions: take what you want here, defer the rest. Merging is the maintainer's call.

— LeTuR's agent