Skip to content

fix(graphics): isolate oversized kitty images - #3035

Merged
ogulcancelik merged 2 commits into
masterfrom
akbash/3033-kitty-oversized-starvation
Aug 20, 2026
Merged

fix(graphics): isolate oversized kitty images#3035
ogulcancelik merged 2 commits into
masterfrom
akbash/3033-kitty-oversized-starvation

Conversation

@akbash-bot

@akbash-bot akbash-bot commented Aug 20, 2026

Copy link
Copy Markdown
Collaborator

Issue

Showing a large Kitty image leaves blank space. Smaller images shown later in the same pane also stay blank.

Problem

The decoded large image produced an upload larger than the client graphics frame limit. Terminal-only rendering bundled that upload with later images, dropped the whole frame, and retried it on every render.

How did we fix it?

Herdr now applies the existing per-image transaction budget to terminal-only attached clients. It quarantines an oversized upload and continues with later bounded images. The quarantine is bounded and avoids copying unchanged pixels again. Local rendering keeps its existing uncapped behavior.

Verification

Before the change, the large image produced a 41,267,682-byte dropped payload and the later small image produced a 41,379,271-byte dropped payload. Afterward, the same pane transmitted and placed the 158×132 image without retrying the 3456×2234 upload. Kitty graphics tests and render scaling passed. just check passed 3,490 of 3,491 tests; an unrelated live-handoff PID-discovery test still fails although its log shows the replacement server started.

refs #3033

@coderabbitai

coderabbitai Bot commented Aug 20, 2026

Copy link
Copy Markdown

Review Change Stack

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: 85a0c3d7-6f11-4f8b-87aa-a61f148c610a

📥 Commits

Reviewing files that changed from the base of the PR and between cd7c0d0 and e7815b7.

📒 Files selected for processing (1)
  • docs/next/CHANGELOG.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • docs/next/CHANGELOG.md

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


📝 Walkthrough

Walkthrough

Kitty graphics encoding now quarantines oversized image sources within a bounded cache. Budgeted terminal updates continue with smaller images, deduplicate data requests, preserve quarantine state during pane cleanup, and retain legacy behavior without a transaction budget. The changelog also records a Windows pane fix.

Changes

Kitty graphics rendering

Layer / File(s) Summary
Bounded quarantine and state lifecycle
src/kitty_graphics.rs
The graphics cache bounds oversized-source tracking, separates incremental progress resets from full resets, and preserves quarantine entries during pane cleanup.
Budgeted encoding and request handling
src/kitty_graphics.rs
Budgeted terminal updates quarantine oversized images, defer pane cleanup when required, encode later smaller images, deduplicate terminal data requests, and retain legacy encoding without a transaction budget.
Regression coverage and changelog
src/kitty_graphics.rs, docs/next/CHANGELOG.md
Tests cover budget starvation, cleanup ordering, dispatch, request deduplication, quarantine persistence, bounded eviction, and full clearing. The changelog records the Kitty rendering and Windows pane fixes.

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

Merge Risk: 🔵 Low · up to e7815

The change prevents oversized Kitty images from starving later images, but pane-source cleanup can still combine with a budget-sized terminal image transaction and exceed the graphics budget, potentially dropping an image batch. The PR is mergeable with explicit owner awareness or follow-up.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 21 functions across 1 files. (1 skipped: 1 unsupported.) Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly identifies the graphics fix for oversized Kitty images, which is the main change in the pull request.
Description check ✅ Passed The description explains the oversized Kitty image problem, the quarantine-based fix, affected clients, and verification results.
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 unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch akbash/3033-kitty-oversized-starvation

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

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

@kangal-bot kangal-bot added the ai-review Trigger automated AI reviews for pull requests admitted by the PR gate label Aug 20, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
src/kitty_graphics.rs (1)

227-255: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Keep pane-layer cleanup inside the transaction budget.

Line 227 can generate delete-image commands. Lines 251-253 prepend those commands to a terminal image update that can already consume HEADLESS_GRAPHICS_TRANSACTION_BUDGET. image_transaction_fits does not include the cleanup bytes.

Process pane-source deletes through the incremental budgeted path. Return incomplete before an upload when cleanup consumes the transaction. Add a regression test with cached pane sources and a terminal image at the budget boundary.

Proposed direction
- let mut bytes = cache.clear_pane_sources();
- let mut encoded =
-     encode_terminal_graphics_update(cache, &placements, view_changed, transaction_budget);
- bytes.extend(encoded.bytes);
+ if transaction_budget.is_some() {
+     cache.request_placement_replay();
+     return encode_graphics_update_incremental(
+         cache,
+         &placements,
+         &HashSet::new(),
+         transaction_budget,
+     );
+ }
+
+ let mut bytes = cache.clear_pane_sources();
+ let mut encoded =
+     encode_terminal_graphics_update(cache, &placements, view_changed, transaction_budget);
+ bytes.extend(encoded.bytes);

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7283773d-844d-48cd-9c42-2b18d934b0f6

📥 Commits

Reviewing files that changed from the base of the PR and between ffc4e26 and 766f3d8.

📒 Files selected for processing (2)
  • docs/next/CHANGELOG.md
  • src/kitty_graphics.rs

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

@akbash-bot

Copy link
Copy Markdown
Collaborator Author

agreed, fixed in cd7c0d0.

@greptile-apps

greptile-apps Bot commented Aug 20, 2026

Copy link
Copy Markdown

Greptile Summary

The PR applies the existing graphics transaction budget to terminal-only attached clients so oversized Kitty uploads are quarantined without blocking later images.

  • Routes terminal-only rendering through the incremental budgeted encoder.
  • Retains a bounded cache of oversized terminal image signatures to avoid repeated pixel extraction and upload attempts.
  • Adds coverage for quarantine persistence, bounded eviction, request deduplication, cleanup ordering, and rendering smaller images after oversized ones.
  • Documents the Kitty graphics fix in the upcoming changelog.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename Overview
src/kitty_graphics.rs Adds budget-aware terminal-only graphics encoding, bounded oversized-image quarantine, request deduplication, and focused regression tests.
docs/next/CHANGELOG.md Records that oversized Kitty images no longer prevent later smaller images from rendering.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Collect visible Kitty placements] --> B{Image already uploaded?}
  B -->|Yes| P[Emit or replay placement]
  B -->|No| C{Signature quarantined?}
  C -->|Yes| D[Skip oversized image data]
  C -->|No| E{Upload fits transaction budget?}
  E -->|Yes| F[Upload image]
  F --> P
  E -->|No| G[Quarantine source and signature]
  G --> H[Continue processing later bounded images]
Loading

Reviews (2): Last reviewed commit: "fix(graphics): budget pane image cleanup" | Re-trigger Greptile

@ogulcancelik
ogulcancelik force-pushed the akbash/3033-kitty-oversized-starvation branch from cd7c0d0 to e7815b7 Compare August 20, 2026 20:02
@ogulcancelik
ogulcancelik merged commit 624dfd4 into master Aug 20, 2026
7 checks passed
@kangal-bot kangal-bot removed the ai-review Trigger automated AI reviews for pull requests admitted by the PR gate label Aug 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants