Focus highlight doesn't follow FocusNextPane, only FocusPreviousPane

[GeneralD]

Problem

Cycling pane focus in the two directions behaves asymmetrically in the minimap: switching backward (FocusPreviousPane) moves the focus highlight to the newly focused pane as expected, but switching forward (FocusNextPane) leaves the highlight where it was — no pane changes color at all.

Steps to Reproduce

1. Open a tab with 2+ tiled panes (highlight ring visible on the focused pane).
2. Trigger FocusNextPane (bound to e.g. ⌘ + ]) — actual focus moves (cursor lands in the next pane).
3. Trigger FocusPreviousPane (e.g. ⌘ + [) for comparison.

Expected Behavior

Both directions move the focus ring/highlight to the newly focused pane.

Actual Behavior

• FocusPreviousPane: highlight follows the focus. ✅
• FocusNextPane: focus moves in zellij, but no pane in the minimap changes color. ❌

Relevant Code

• src/projection.rs:44 — is_focused is passed straight through from zellij's PaneInfo; the plugin derives the highlight purely from this flag.
• src/lib.rs:144-147 — every PaneUpdate replaces self.panes and triggers a repaint; there is no plugin-side caching that could pin a stale highlight.

Given that pass-through structure, the prime suspect is the data delivered on PaneUpdate after FocusNextPane (stale or missing is_focused flip), rather than the render path — but that needs to be confirmed with a payload dump.

Diagnostics / Proposed Steps

1. Log the is_focused flags from each PaneUpdate while cycling both directions to confirm whether zellij delivers the flip for FocusNextPane.
2. If zellij does deliver it → bug is in tabmap; bisect the projection/render path.
3. If zellij does not → check zellij 0.44.x for known focus_next_pane event-emission issues; consider deriving the focused pane from a complementary signal (e.g. TabUpdate/ModeUpdate) or reporting upstream.

Environment

• zellij 0.44.3 (macOS)
• zellij-tabmap v0.2.x (observed on the current release line)

[GeneralD]

Root cause identified: missing log_and_report_session_state() in zellij's FocusNextPane handler

Full diagnostic run (plugin audit + zellij source analysis + instrumented live probe + upstream search, each conclusion adversarially cross-examined by three independent reviewers). Recording all evidence here so it doesn't evaporate.

TL;DR — this is an upstream zellij bug, not a tabmap bug. In zellij v0.44.3, the ScreenInstruction::FocusNextPane handler never re-publishes the pane manifest to plugins, while FocusPreviousPane does. Since Event::PaneUpdate is the only way a plugin learns about focus changes, the highlight freezes after focus-next and catches up only when some later action happens to report session state.

1. zellij v0.44.3 source asymmetry (primary evidence)

zellij-server/src/screen.rs L6092–L6124 @ v0.44.3:

ScreenInstruction::FocusNextPane(client_id, mut _completion_tx) => {
    // ...
    active_tab_and_connected_client_id!(screen, client_id, |tab, client_id|
        tab.focus_next_pane(client_id));
    screen.render(None)?;
    //  <-- screen.log_and_report_session_state() is MISSING here
},
ScreenInstruction::FocusPreviousPane(client_id, mut _completion_tx) => {
    // ...
    active_tab_and_connected_client_id!(screen, client_id, |tab, client_id|
        tab.focus_previous_pane(client_id));
    screen.render(None)?;
    screen.log_and_report_session_state()?;   // L6122 — present here
},

Why this is conclusive:

• log_and_report_session_state() (screen.rs L3329) → generate_and_report_pane_state() (L3244–3266) is the only emission site of Event::PaneUpdate in all of zellij-server (the one other caller, SaveSession @ L8572, only writes the resurrection layout to disk). No alternative delivery path exists, and there is no periodic re-broadcast — so the plugin-visible state stays frozen indefinitely, not just momentarily.
• Everything upstream and downstream of the handlers is symmetric: route.rs L357–372 routes Action::FocusNextPane / FocusPreviousPane identically, and tiled_panes/mod.rs L1816–1869 has mirror-image focus_next_pane / focus_previous_pane implementations. Focus itself does move in zellij core (confirmed live via dump-layout); only the plugin notification is dropped.
• The neighbouring SwitchFocus handler (L6079–6091) calls the same tab.focus_next_pane and does call log_and_report_session_state() (L6090) — strong evidence this is an accidental omission, not a design decision.
• The omission is old: it exists as far back as v0.38.2, so it's not a 0.44.x regression — FocusNextPane was apparently just forgotten when session-state reporting was introduced.
• Still unfixed on main as of 2026-06-10 (same handlers at L6170–L6202). v0.44.3 (2026-05-13) is the latest release.

2. Plugin-side audit: clean

A full audit of every tabmap module found no mechanism that could produce a direction-asymmetric stale highlight:

• The PaneUpdate arm in src/lib.rs:144-147 is unconditionally self.panes = panes; true — no equality check, no debounce, no early return. Every delivered manifest triggers a re-render.
• render() recomputes layout → projection → minimap from self.tabs/self.panes purely on every frame; there is no frame cache or output diffing anywhere (paint.rs recomposes every line unconditionally).
• Focus always changes the output bytes: accent fill (color.rs), focus ring (minimap.rs:177-187), and label emphasis.
• The only order-dependent quirk found (painter's-algorithm ring bleed when the zero-width bump px1 = px0 + 1 overlaps blocks) points in the opposite direction and only affects sub-pixel-width panes — it cannot produce "highlight doesn't move on focus-next."

Conclusion: if a focus-flipped PaneUpdate arrives, tabmap renders it. The event simply never arrives.

3. Instrumented live probe — and the repro trap that almost fooled us

We built an instrumented wasm that logs every received PaneUpdate as PROBE37 [(tab, pane, is_focused), ...] and drove a throwaway 3-pane session.

First-pass result (misleading): both focus-next-pane and focus-previous-pane delivered PaneUpdate bursts with correctly flipped is_focused — apparently refuting the root cause above.

The confound: the actions were injected via the zellij action ... CLI. Each CLI invocation attaches a temporary client, and client attach/detach itself triggers log_and_report_session_state() (RemoveClient handler @ screen.rs L7420–7423, AddClient @ L7402). So the transport, not the handler under test, was publishing the manifest — the CLI path masks the bug.

The fingerprint that exposed it: the burst counts. focus-next #2 produced 21 PaneUpdates; focus-prev produced 22 — exactly +1, matching the one extra report that only the FocusPreviousPane handler makes itself. The "symmetric, all normal" reading missed this difference; the adversarial reviewers caught it.

⚠️ For any upstream reproduction: do not use zellij action focus-next-pane to reproduce this — the temporary CLI client's attach/detach re-publishes the manifest and hides the bug. Reproduce via an attached client pressing the keybinding.

Raw PROBE37 log (selected lines)

--- initial load (sandbox session) ---
12:09:55.895 PROBE37 [(0, 0, true), (0, 1, false), (0, 2, false)]
12:09:55.904 PROBE37 [(0, 0, true), (0, 1, false), (0, 2, false)]
12:09:55.913 PROBE37 [(0, 0, true), (0, 1, false), (0, 2, false)]
--- A: focus-next-pane #1 (12 PaneUpdates in burst) ---
12:10:25.971 PROBE37 [(0, 0, true), (0, 1, false), (0, 2, false)]
12:10:25.977 PROBE37 [(0, 0, true), (0, 1, false), (0, 2, false)]
12:10:25.979 PROBE37 [(0, 0, true), (0, 1, false), (0, 2, false)]
12:10:25.980 PROBE37 [(0, 0, false), (0, 1, true), (0, 2, false)]
12:10:25.981 PROBE37 [(0, 0, false), (0, 1, true), (0, 2, false)]
12:10:25.985 PROBE37 [(0, 0, false), (0, 1, true), (0, 2, false)]
--- B: focus-next-pane #2 (21 PaneUpdates total; first/last shown) ---
12:10:42.521 PROBE37 [(0, 0, false), (0, 1, true), (0, 2, false)]
12:10:44.081 PROBE37 [(0, 0, false), (0, 1, false), (0, 2, true)]
--- C: focus-previous-pane (22 PaneUpdates total; first/last shown) ---
12:10:55.124 PROBE37 [(0, 0, false), (0, 1, false), (0, 2, true)]
12:10:56.703 PROBE37 [(0, 0, false), (0, 1, true), (0, 2, false)]

Note the early lines of each burst still carry the old focus state before flipping — racing the first PaneUpdate of a burst reads stale state.

A follow-up probe that sends real keybindings to an attached PTY (no zellij action at all during measurement windows) is running now; results will be appended here. Predictions: 0 new PaneUpdates after focus-next keystrokes, ≥1 after focus-prev, and a catch-up burst the moment any reporting action runs.

4. Upstream search: unreported

Searched zellij-org/zellij issues, PRs, discussions, and CHANGELOG (WebSearch + gh search + GraphQL). No prior report of this exact bug exists — this issue appears to be the first documentation anywhere. Negative results recorded so nobody repeats the trip:

Adjacent-but-different upstream reports examined

• zellij#4203 — tab rename emits Event::PaneUpdate unnecessarily; shows PaneUpdate emission conditions are ad-hoc, but doesn't mention the focus-next omission.
• zellij#4656 — stacked+floating focus state corruption (two panes is_focused=true); affects MoveFocus (Alt+hjkl), different mechanism.
• zellij#4136 — focus-previous-pane doesn't work inside a floating pane; focus itself fails to move, unrelated to plugin event delivery.
• CHANGELOG 0.44.1–0.44.3 + Unreleased: no relevant fix entries. No 0.45/0.46 release exists.

5. Adversarial verification: 3/3 lenses passed

Three independent reviewers each tried to refute the root cause; none succeeded. Rejected alternatives, and why:

Rejected hypothesis	Why it dies
Plugin-side caching / debounce / render diffing	Audit found none exists (§2); plugin can't even observe which action changed the manifest, so a direction-asymmetric plugin bug is structurally impossible
Permission freeze is the true cause (see §6)	A permission freeze blocks all events symmetrically (probe confirmed: zero events even on new-pane) — it cannot produce "prev works, next doesn't"
Probe's "delivery is symmetric and normal" reading	Measurement artifact: CLI client attach/detach re-publishes the manifest (§3); the +1 burst-count fingerprint actually confirms the asymmetry

6. Side finding: permission-cache key format trap (independent of this issue)

During probing, a session whose permissions.kdl granted the local wasm only under the file:-prefixed form ("file:/path/to/plugin.wasm") delivered zero events to the plugin — frozen even on new-pane. Re-granting under the bare path form ("/path/to/plugin.wasm") immediately unfroze it. zellij 0.44.3 appears to key file-plugin permission lookups on the bare path. This is symmetric (kills everything), so it's unrelated to this issue's asymmetry — but worth knowing for local plugin development.

Disposition

• No clean plugin-side workaround exists: the event never arrives, so there is nothing for tabmap to react to (no polling hook in zellij-tile for the pane manifest).
• The proper fix is one line upstream: add screen.log_and_report_session_state()?; to the FocusNextPane arm in zellij-server/src/screen.rs, mirroring FocusPreviousPane and SwitchFocus.
• Next steps under consideration: file an upstream issue at zellij-org/zellij with the evidence above (including the CLI-repro trap), optionally accompanied by the one-line fix PR. Keeping this issue open to track until the fix ships in a zellij release.

[GeneralD]

Follow-up: keybind-path probe closes the verification gap — root cause confirmed by direct observation

The remaining gap in the previous comment was that the first probe drove actions through the zellij action CLI, whose client attach/detach masks the bug. This follow-up run drove focus changes exclusively via keystrokes sent to an attached PTY (expect-held client, zero zellij action invocations during measurement windows), with session_serialization false to eliminate the 60-second periodic serialization report as a noise source.

Result: keybind-driven FocusNextPane delivers ZERO Event::PaneUpdate to the plugin; FocusPreviousPane delivers exactly one, every time. Reproduced with two independent bindings (Alt-modified and bare keys). This matches the source asymmetry (missing log_and_report_session_state() at screen.rs L6092–6107 vs. present at L6122) exactly.

Measurements (counter = cumulative PROBE37 lines in zellij's log)

Step	Key (action)	Counter	Delta
Baseline	(8 s after session launch)	154	—
Self-test	Alt+n (NewPane, default bind)	155	+1 — delivery path alive
Window b	Alt+y (FocusNextPane #1)	155	0
Window c	Alt+y (FocusNextPane #2)	155	0
Window d	Alt+u (FocusPreviousPane)	156	+1
Repro (bare bind)	n (FocusNextPane)	156	0
Repro (bare bind)	b (FocusPreviousPane)	157	+1

Key-send → log-line causality holds at millisecond precision (e.g. Alt+u sent 12:37:22.440 → PROBE37 line at 12:37:22.441).

The stale-highlight mechanism, caught in the act

# self-test: Alt+n (NewPane) — +1. New pane (pane=3) is focused
12:37:13.345 PROBE37 (pane=0,focused=false) (pane=1,focused=false) (pane=2,focused=false) (pane=3,focused=true)

# FocusNextPane sent twice here (12:37:16.383 / 12:37:19.410) — real focus moved 3 → 1 → 2.
# NOT A SINGLE PROBE37 LINE appears. The plugin still believes pane 3 is focused.

# Alt+u (FocusPreviousPane) — +1. The manifest "jumps" straight to pane=1
12:37:22.441 PROBE37 (pane=0,focused=false) (pane=1,focused=true) (pane=2,focused=false) (pane=3,focused=false)

Between those two lines the real focus moved twice with no notification — the plugin renders a frozen highlight the whole time, then snaps to the post-prev state. This is precisely the symptom reported in this issue.

Catch-up bursts: empirical proof of the CLI masking trap

After the measurement windows:

• Re-attaching a client: counter 157 → 162 (+5 burst), all lines carrying the up-to-date focus — client attach forces a pending session-state report.
• A single zellij action dump-layout: 162 → 174 (+12 burst) — directly demonstrating why any zellij action-based reproduction hides this bug (as predicted in the previous comment).
• Side finding: while the session had zero attached clients, not even the detach-forced report reached the plugin (counter frozen) — detached sessions deliver no plugin events at all, so reproduction also requires an attached client.

Verification status

All three evidence layers now agree end-to-end:

1. Source: FocusNextPane handler lacks the log_and_report_session_state() call that FocusPreviousPane and SwitchFocus have.
2. Live keybind observation: next = 0 PaneUpdates, prev = exactly +1, across two independent bindings.
3. Confound accounted for: CLI-driven probes mask the bug via attach/detach reports (+5/+12 catch-up bursts measured).

Nothing remains unverified. Ready to file upstream against zellij-org/zellij with this evidence, including the repro constraints: attached client + keybinding only, no zellij action, serialization off for a clean signal.

[GeneralD]

Filed upstream

• Issue: zellij-org/zellij#5244 — full report with the source asymmetry, keybind-path measurements, and both reproduction traps (CLI-client masking, session-serialization catch-up).
• Fix PR: zellij-org/zellij#5245 — the one-line fix adding screen.log_and_report_session_state()?; to the FocusNextPane arm (4e93f218).

Keeping this issue open until the fix lands in a zellij release. No plugin-side workaround is planned — the event never reaches the plugin, so there is nothing to react to.

[GeneralD]

Follow-up: is there a plugin-side way after all? — yes, but only a pull, not a push

A deeper pass over the zellij 0.44.3 sources (zellij-tile / zellij-server / zellij-utils, all read locally from the cargo registry) to answer one question raised against the earlier "no plugin-side workaround" disposition:

The official UI follows FocusNextPane just fine. Isn't there some signal we can use?

Short answer: the official UI updates for a reason that has nothing to do with a plugin event, there is no push event that carries the FocusNextPane focus flip, but the live focus is retrievable on demand via a pull API that bypasses the broken report path. So the precise refinement of the prior disposition is: no push workaround exists; a polling workaround does, at a cost.

1. Why the official UI updates but plugins don't

The FocusNextPane arm calls screen.render() but not log_and_report_session_state():

// zellij-server-0.44.3/src/screen.rs  (~L6092)
ScreenInstruction::FocusNextPane(client_id, _) => {
    ... tab.focus_next_pane(client_id) ...
    screen.render(None)?;                       // core repaints the pane frame
    // log_and_report_session_state() is ABSENT  (FocusPreviousPane/SwitchFocus have it)
}

The pane-focus frame the user sees is drawn core-side by render() from live state — it is not a plugin reacting to an event. The official tab-bar/compact-bar plugins (and zjstatus) would be just as stale; they simply don't visualize per-pane focus, so nobody ever noticed. "The official UI updates ⇒ there must be an event" is a false lead.

2. No push event carries the flip (every candidate ruled out)

Per-event evidence

Channel	Verdict
TabUpdate / PaneUpdate	Emitted only via log_and_report_session_state() → absent on FocusNextPane.
SessionUpdate	Emitted only by log_and_report_session_state() (screen.rs:3413) or by the pull get_session_list() (zellij_exports.rs:4198 → update_session_infos screen.rs:3446). Its source current_session_info is updated only by ReportSessionInfo (background_jobs.rs:277), itself sent from log_and_report_session_state() (screen.rs:3390). Same hole → stale. Dead end.
1 s SESSION_METADATA_WRITE_INTERVAL_MS ticker (background_jobs.rs:203)	Writes session metadata to disk only; does not push SessionUpdate to plugins and does not recompute focus. (Matches the empirically frozen counter in the keybind probe above.)
CwdChanged / CommandChanged (pty.rs)	Fire only when cwd / command actually change. Not on focus.
ActionComplete (zellij_exports.rs:1475)	Emitted on the plugin-issued action path only, not on keybind-driven FocusNextPane.
Key	Not delivered to a set_selectable(false) plugin (goes to the focused terminal pane).

3. The live focus is pullable — and it bypasses the bug

zellij-tile 0.44.3 exposes a synchronous pull (shim.rs:207):

pub fn get_focused_pane_info() -> Result<(usize, PaneId), String>
//                                         ^tab_index  ^focused pane

The server handler reads live screen state, not the stale report cache:

// zellij-server-0.44.3/src/screen.rs  (~L6446)
ScreenInstruction::GetFocusedPaneInfo { client_id, response_channel } => {
    match screen.get_active_pane_id(&client_id) {   // same live state focus_next_pane() mutates
        Some(focused_pane_id) => Ok { tab_index, pane_id: focused_pane_id.into() },
        ...
    }
}

• Permission: ReadApplicationState only (zellij_exports.rs:5443) — already held by tabmap. No new permission, no upstream dependency.
• PaneInfo carries id: u32 + is_plugin: bool, so the returned PaneId can be matched onto the existing (geometry-still-valid) manifest. Focus is the only stale field on FocusNextPane; geometry doesn't move.
• list_clients() → ClientInfo.pane_id is the same live source (get_layout_metadata at screen.rs:4939 reads tab.get_active_pane_id), but get_focused_pane_info() is already client-scoped and cleaner.

Sketch + tradeoff

// update():
Event::Timer(_) => {                          // re-arm with set_timeout
    if let Ok((tab, pane_id)) = get_focused_pane_info() {   // synchronous, ≤100ms
        if Some((tab, pane_id)) != self.focused {
            self.focused = Some((tab, pane_id));            // geometry from manifest, focus overridden
            should_render = true;
        }
    }
}
Event::PaneUpdate(..) => { /* keep self.focused in sync from is_focused too */ }

Cost: this is a pull, so it needs polling — a Timer raises idle cost from ~zero to a few screen round-trips per second, or InputReceived (a real app-wide broadcast — see §4) heals reactively but fires a blocking round-trip per keystroke during typing. For a status-bar-class plugin that is a real regression, which is why the clean fix is still the one-line upstream change. But "no workaround" was too strong — a guarded, opt-in (config-gated, default off) reconciler is viable and removable once the fix ships.

4. zjstatus is not a model to copy — it shares the same dependency

Checked dj95/zjstatus (the third-party bar in my own layout). It subscribes to Timer + SessionUpdate and re-renders on a ~1 s set_timeout, but:

• It stores self.state.panes = pane_info on PaneUpdate exactly like tabmap, and never calls get_focused_pane_info() / list_clients().
• Its tabs widget reads panes.iter().find(|p| p.is_focused) only to grab the focused pane's title — i.e. the same is_focused-via-PaneUpdate dependency. Configured to show that title, it would be stale on FocusNextPane too; it just isn't a colored highlight so nobody filed it.
• Its timer re-renders cached (stale) self.state.panes — it does not re-query. So "just add a timer like zjstatus" would not fix this; only an active re-query does.

5. Confirmed: every other focus-change path reports — FocusNextPane is the lone hole

Mouse-click focus follows because handle_mouse_event reports on state_changed:

// zellij-server-0.44.3/src/screen.rs  (~L4863)
if mouse_effect.state_changed {
    if !is_bare_motion { let _ = self.log_and_report_session_state(); }   // click reports
    ...
}

Path that moves the active pane	Reports PaneUpdate?
Mouse click focus	✅
FocusPreviousPane	✅
SwitchFocus	✅
MoveFocus{Left,Right,Up,Down}	✅
FocusNextPane	❌ — the only outlier

This sharpens the "omission, not design" argument behind #5245: every sibling path that lands focus on a different pane reports it; FocusNextPane alone forgot. (Side notes: the same mouse handler also explicitly broadcasts Event::InputReceived to subscribed plugins on non-bare-motion events — corroborating §3's InputReceived trigger as a real path — and gates reporting on !is_bare_motion, so plain hover doesn't spam reports.)

Disposition (refined)

• Upstream zellij#5244 / #5245 remain the correct, zero-idle-cost fix and the right primary path; keep tracking until released.
• Correction to the prior "no plugin-side workaround": there is no push workaround, but a pull-based polling reconciler (get_focused_pane_info(), already-held permission, bypasses the broken report path) is technically viable as an opt-in, default-off stopgap if we want the highlight to track FocusNextPane before the upstream fix lands.