fix(graphics): batch kitty image row lifecycle

[ogulcancelik]

Summary

• keep every row of one Kitty placeholder image together when it is uploaded, redrawn, or removed
• keep unrelated images isolated so large updates cannot consume the client frame budget
• supersede fix(graphics): coalesce terminal kitty placements #3152 while preserving @kataokatsuki's two commits

Why

The recent graphics budget fix treated each placeholder row as a separate update. Yazi clears the old rows before its next preview arrives, so Herdr removed those rows across multiple frames and exposed black bands. The same split made cached redraws visibly slow in Snacks.

This restores image-level updates without removing the frame-size guard that motivated the original change.

Validation

• reproduced and traced the row-by-row cleanup in Yazi, then verified the transition is immediate with this branch
• added coverage for image upload, cached redraw, disappearance, replacement, transaction budgets, and unrelated-image isolation
• just check
• just bench-render-scale: 1 to 15 panes was 1.12x median for background workspaces and 1.19x for active panes

No changelog entry: this fixes an unreleased regression.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a70e2d47-b7c7-4d6f-935a-792af5f5ca10

📥 Commits

Reviewing files that changed from the base of the PR and between d6dae88 and 386a3ed.

📒 Files selected for processing (1)

• src/kitty_graphics.rs

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Incremental graphics encoding now accepts placement coalescing. Same-image deletions and redisplays can share budgeted transactions. Uploads, unrelated images, and superseded-image cleanup remain isolated. Tests cover transaction limits, replacements, ordering, and continuation.

Changes

Incremental graphics coalescing

Layer / File(s)	Summary
Encoding control and call-site wiring src/kitty_graphics.rs	The incremental encoder accepts a coalescing control. Terminal updates enable it for budgeted encoding, while pane rendering and existing tests select non-coalescing behavior.
Budgeted placement coalescing src/kitty_graphics.rs	The encoder groups compatible same-image placement deletions and redisplays when they fit the budget. Uploads, unrelated images, and superseded-image operations terminate the current transaction.
Coalescing behavior coverage src/kitty_graphics.rs	Tests cover multi-row uploads, deletion, replacement, redisplay, budget limits, upload ordering, continuation, and superseded-image cleanup.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 386a3

This change restores image-level Kitty row lifecycle updates while retaining the frame-size guard, with validation and performance checks reported in the PR. No actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant TerminalGraphicsUpdate
  participant IncrementalEncoder
  participant ImageCache
  TerminalGraphicsUpdate->>IncrementalEncoder: encode budgeted update with coalesce_placements
  IncrementalEncoder->>ImageCache: check image cache and source binding
  ImageCache-->>IncrementalEncoder: classify upload or redisplay
  IncrementalEncoder-->>TerminalGraphicsUpdate: return budgeted graphics transactions

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains the Kitty image row batching fix, its motivation, scope, and validation.
Title check	✅ Passed	The title clearly identifies the primary change: batching the Kitty image row lifecycle.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
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.

✨ 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 fix/kitty-image-row-lifecycle

---

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