feat(tui): dim backdrops behind modals and exposé previews

[TraderSamwise]

What

Adds background dimming to two TUI surfaces so the foreground layer reads clearly above its backdrop.

1. Dashboard modals — when a centered overlay is active, the dashboard base frame is receded (faint) into a backdrop; the modal box overdraws its rectangle at full brightness on top.
2. Exposé tile previews — each captured pane preview is flattened to gray so the tile chrome (border, title, status pill — which keep their live state colors) reads as foreground. The selected tile's preview stays the brightest; others recede further. Extends the existing selected/unselected border model to the preview body.

How

• New standardized recede(text, mode) primitive in src/tui/render/theme.ts:
  • "faint" — keeps colors but dims via SGR-2, re-injecting faint after embedded resets (for the dashboard backdrop, which is pre-styled).
  • "soft"/"deep" — strip color and flatten to a single 256-color gray (for exposé previews); fully portable, visible width preserved.
• Composited at existing seams only: writeFrame (dashboard-state-methods.ts) gates on an active overlay; drawTile (expose.ts) maps preview rows. The stored dashboard base stays raw, so dismissal redraws bright.

Notes

• Full-screen takeovers (help, subscreens) bypass the modal compositor, so they're correctly left un-dimmed.
• Terminal portability: faint (SGR-2) is widely but not universally honored and degrades to a no-op; the exposé flatten path uses explicit 256-color gray and is unaffected.

Tests

• recede unit tests (faint reinjection, flatten levels, width preservation, empty input).
• Updated dashboard writeFrame composite assertion.
• New exposé drawTile test: captured colors stripped → gray, selected (250) vs unselected (240), plain text preserved.
• Full suite: 1416 passing; yarn build clean.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added modal-style backdrop dimming for dashboard overlays, improving readability without hiding the underlying view.
  • Improved tile preview rendering: unselected tiles now use dimmed/flattened ANSI styling, while selected tiles remain brightest for clearer visual hierarchy.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jun 18, 2026 9:55am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6d878d88-8443-4e0c-a7ba-e185cfffda13

📥 Commits

Reviewing files that changed from the base of the PR and between cab9641 and fda0ef1.

📒 Files selected for processing (2)

• src/tui/render/theme.test.ts
• src/tui/render/theme.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• src/tui/render/theme.ts
• src/tui/render/theme.test.ts

---

📝 Walkthrough

Walkthrough

Adds a recede(text, mode) utility to the theme module supporting "faint", "soft", and "deep" ANSI-dimming modes. The function is then wired into tmux tile preview rendering (per-line dimming by selection state) and dashboard overlay compositing (faint-dimming the base frame before appending the overlay).

Changes

recede() ANSI dimming and rendering integration

Layer / File(s)	Summary
recede() implementation and tests src/tui/render/theme.ts, src/tui/render/theme.test.ts	Exports RecedeMode type and recede() function. Faint mode wraps text in SGR \x1b[2m and re-injects faint after embedded reset codes. Soft/deep modes strip ANSI and re-emit a single 256-color gray foreground (250 or 240 respectively). Tests cover all modes, embedded reset continuity, visible-width preservation on flattened strings, and empty-string no-op.
Tile preview dimming in drawTile src/tmux/expose.ts, src/tmux/expose-tile.test.ts	Adds recede import and maps each sliced preview line through recede(line, selected ? "soft" : "deep") in drawTile. Test helper renderTile gains a preview parameter, and a new test case asserts that ANSI color codes in preview content are flattened to gray-250 for selected tiles and gray-240 for unselected tiles.
Dashboard overlay base-frame faint dimming src/multiplexer/dashboard-state-methods.ts, src/multiplexer/dashboard-view-methods.test.ts	writeFrame now applies recede(output, "faint") to the stored base frame before concatenating overlay output when a dashboard overlay is active. Test assertions updated to expect ANSI-dim escape codes wrapping base-frame in the composited stdout write.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• TraderSamwise/aimux#133: Modifies src/tmux/expose.ts tile preview rendering logic and directly overlaps with this PR's per-line recede() application in drawTile.
• TraderSamwise/aimux#135: Introduces or refactors src/tui/render/theme.ts theme helpers that this PR extends with the new recede() utility.
• TraderSamwise/aimux#150: Modifies Exposé tile rendering in src/tmux/expose.ts/expose-tile.test.ts; the retrieved PR rewrites drawTile header/status pill layout, while this PR further adjusts drawTile to dim previews using recede.

Poem

🐇 Hop, hop, through the terminal glow,
Colors too bright? Let them softly go.
Faint the backdrop, gray the rest,
recede() knows which mode is best.
The overlay shines, the chrome dims low —
A rabbit's palette, arranged just so! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(tui): dim backdrops behind modals and exposé previews' directly and accurately summarizes the main changes—adding background dimming to dashboard modals and exposé tile previews for improved visual hierarchy.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 chore/tui-next-22

---

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

[TraderSamwise]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[TraderSamwise]

Concurrent sub-agent review note (orphan finding, not blocking this PR):

• sanitizeLine in src/tmux/expose.ts doesn't fully neutralize an unterminated OSC sequence (no BEL/ST terminator) — the \x1b] opener is stripped but the body can leak as visible text into a preview. This is pre-existing (not touched by this PR), low/cosmetic (a rogue pane could inject visible text but not escapes — recede flatten runs stripAnsi before re-emitting, and borders are drawn separately), so I'm leaving it out of scope here. Flagging for visibility; happy to fix in a follow-up if desired.

Everything else the sub-agent checked (perf gating, exposé width/alignment, tile-height overflow, selected-tile flatten consistency, consumers of recede) came back clean.