feat: label floats inside the overlay when space allows (#120)

[GeneralD]

Closes #120.

Label a visible floating pane with its summarized title inside its overlay,
mirroring the tiled-pane label treatment — but only when the overlay box is big
enough to hold a legible label. Small floats stay color + ring only, exactly as
before.

In the demo above, the active tab (⌘2) overlays two floats: the focused htop
is tall enough to clear the size gate, so it shows its title white and bold
inside the overlay; the shorter logs stays under the gate and renders
unlabeled — a side-by-side contrast between a labeled and an unlabeled float.

What changed

• src/minimap.rs (render) — a dedicated float_overlay reuses the tiled
  label vocabulary (title::summarize + display-width scan + OverlayCell) in
  its own index space, gated by:
  • the existing LabelMode (the L0–L4 degradation ladder): All labels
    every fitting float, Focused only the focused one, None none;
  • a conservative size gate — interior width ≥ 4 cols (fw − 2 ≥ 4) and
    height ≥ 6 px (3 text rows), the smallest box with a fully-interior row.
  • A new draw branch paints the label over the float's own fill on a
    centered interior row, foreground ACTIVE_FG on the active tab and receded
    via mixed(…, INACTIVE_LABEL_BLEND) on inactive tabs, bold only when
    active && focused — identical to the tiled-label styling.
  • A per-cell ownership check against float_grid means only the topmost
    float's label shows where floats overlap; a wide/CJK glyph's Continuation
    cells emit nothing, so the row width never breaks.
• New constants FLOAT_LABEL_MIN_INNER_WIDTH, FLOAT_LABEL_MIN_HEIGHT_PX.
• examples/render_floating.rs — the focused htop float is enlarged to
  clear the gate so the demo shows a labeled float next to an unlabeled one.

Testing

• CARGO_BUILD_TARGET=aarch64-apple-darwin cargo test --lib → 324 passed,
  including 8 new f_* regression tests: large-float labeled, small-float
  unlabeled, focused-bold, inactive-tab muting (never bold / never pure
  white), LabelMode gating (Focused/None), wide-glyph row-width
  preservation, and overlap (only the topmost float labeled — verified
  load-bearing against the ownership check).
• cargo clippy --target wasm32-wasip1 --all-features --lib → clean.
• cargo build --target wasm32-wasip1 and cargo build --examples → build.

Notes

• No new zellij permission and no new config key — pure rendering within the
  existing grant, so no feat(title): pane-title summarization module (icon table + width-aware truncation) #15 permission-freeze risk for existing users.
• Float overlays already render on non-active tabs (a feat: show floating panes in the minimap, selectable when hidden #110-era behavior), so
  the label foreground follows the active flag like tiled labels; the spec doc
  is corrected to match this shipped behavior.

Spec: docs/superpowers/specs/2026-07-16-float-labels-design.md ·
Plan: docs/superpowers/plans/2026-07-16-float-labels.md

Summary by CodeRabbit

• New Features
  • Added centered title labels to sufficiently large floating panes in the minimap.
  • Labels respect label visibility settings, focused-pane emphasis, and overlapping-pane ownership.
  • Added support for wide-character titles without disrupting minimap layout.
• Documentation
  • Added design and implementation documentation for minimap float labels.
  • Updated the floating-pane rendering example to demonstrate labeled panes.
• Tests
  • Added coverage for size thresholds, focus states, label modes, wide glyphs, and overlapping panes.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Float label rendering

Layer / File(s)	Summary
Float-label contract and validation plan docs/superpowers/plans/..., docs/superpowers/specs/...	Documents size thresholds, centered summarized titles, LabelMode behavior, overlap ownership, styling, and validation requirements.
Float overlay construction and painting src/minimap.rs	Renders eligible float titles above float fills, handles focused and inactive styling, preserves wide-glyph row widths, prevents overlap bleed-through, and adds coverage tests.
Visible float demonstration examples/render_floating.rs	Resizes the focused htop float to display its title while keeping the smaller logs float unlabeled.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant render
  participant float_grid
  participant float_overlay
  participant paint_loop
  render->>float_grid: check float ownership for covered cells
  render->>float_overlay: place centered summarized title glyphs
  render->>paint_loop: provide overlay glyph or continuation cells
  paint_loop->>paint_loop: paint glyph styling above float fill

Loading

Possibly related PRs

• GeneralD/zellij-tabmap#112: Provides the floating-pane minimap rendering extended by this change.
• GeneralD/zellij-tabmap#17: Introduces the LabelMode ladder used by float labels.
• GeneralD/zellij-tabmap#58: Establishes OverlayCell and continuation handling for width-safe label rendering.

Suggested reviewers: copilot

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR matches #120 by labeling only sufficiently large floats, reusing label logic, preserving small unlabeled floats, and adding tests.
Out of Scope Changes check	✅ Passed	The docs, design spec, example update, and tests all support the float-label feature and do not introduce unrelated scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding float labels inside overlays when there is enough space.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/120-float-labels

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Adds size-gated pane-title labels to visible floating-pane overlays in the minimap renderer, reusing the existing tiled-label vocabulary and respecting the existing LabelMode degradation ladder—so large floats can be identified from the bar without cluttering small overlays.

Changes:

• Introduces a dedicated float_overlay in minimap::render() to place centered, width-aware summarized titles inside sufficiently large visible float overlays.
• Paints float labels as the topmost layer over the float’s own fill, with inactive-tab muting and bold only for (active && focused) to match tiled label styling.
• Updates the floating render example and adds regression tests covering gating, overlap ownership, inactive-tab styling, and wide-glyph width preservation.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
src/minimap.rs	Implements float-label placement + paint path (size-gated, LabelMode-gated, overlap-safe) and adds focused regression tests.
examples/render_floating.rs	Adjusts the demo float geometry and documentation so the example reliably shows one labeled and one unlabeled float.
docs/superpowers/specs/2026-07-16-float-labels-design.md	Adds the design spec describing gating, placement, styling, and overlap/ownership rules.
docs/superpowers/plans/2026-07-16-float-labels.md	Adds an implementation plan detailing steps, invariants, and verification checklist.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.