fix(ink): harden terminal image transport

[Nagi-ovo]

Depends on #688.
Closes #686.

Summary

• preserve source aspect ratio from terminal-reported cell pixels, with bounded transparent letterboxing and premultiplied-alpha downsampling;
• compress direct RGBA with zlib, share immutable content uploads across nodes and remounts, and keep image resources separate from node-owned placements;
• refresh geometry across resize and font/DPI changes while coalescing bursts and rejecting stale reports;
• suspend, drain, quarantine, and resume terminal queries around external-editor handoff so late CSI/DA1 replies cannot poison a new batch;
• retain text fallback behavior for unsupported, inline, accessibility, and multiplexer sessions.

The public plugin/Image contract is unchanged. Attachment decoding, transcript projection, source cropping, and temporal payload caching stay out of this renderer-focused PR.

Validation

• env TMPDIR=/tmp pnpm build
• pnpm smoke
• node --import tsx/esm scripts/verify-terminal-queries.tsx
• node --import tsx/esm scripts/verify-resize-reflow.tsx
• node --import tsx/esm scripts/repro-toolcards.tsx
• pnpm verify:package
• pnpm verify:bun-package
• git diff --check

Stack note

Base branch is nagi/kitty-graphics-image-base (#688). Once #688 merges, this PR retargets to main without changing its commits.

Summary by CodeRabbit

• New Features

  • Improved Kitty terminal image rendering with centered, aspect-preserving images, transparent letterboxing, and higher-quality resizing.
  • Reuses shared image data efficiently and supports configurable terminal cell dimensions.
  • Added support for detecting terminal cell and window pixel sizes for more accurate image geometry.

• Bug Fixes

  • Improved terminal-query handling during screen transitions, interruptions, resizing, and shutdown.
  • Prevented stale or delayed terminal responses from affecting rendering.

• Documentation

  • Updated image rendering documentation to describe aspect-ratio preservation, centering, downsampling, and fallback behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 43737420-674c-4cfa-9716-3a5a72be2d39

📥 Commits

Reviewing files that changed from the base of the PR and between b31dc9d and 14eefdc.

📒 Files selected for processing (1)

• src/ink/parse-keypress.ts

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

---

📝 Walkthrough

Walkthrough

The PR adds terminal pixel-size queries, suspended query handling, aspect-preserving Kitty image fitting, compressed shared uploads, placement lifecycle management, resize refreshes, stale-reply protection, and regression coverage.

Changes

Kitty image pipeline

Layer / File(s)	Summary
Terminal query contracts and suspension src/ink/parse-keypress.ts, src/ink/terminal-querier.ts, scripts/verify-terminal-queries.tsx	Terminal pixel-size responses and query builders are added. TerminalQuerier now suspends, drains, resumes, and ignores responses while suspended.
Image fitting and shared Kitty storage src/ink/terminal-image.ts, src/ink/kitty-graphics.ts, docs/interaction*.md, scripts/verify-terminal-images.tsx	Images use terminal cell geometry, bounded aspect-preserving RGBA fitting, transparent padding, zlib compression, shared immutable uploads, and independent placements.
Probe, resize, and handoff orchestration src/ink/components/App.tsx, src/ink/ink.tsx, scripts/verify-terminal-images.tsx	XTVERSION probes and pixel-metric refreshes are deferred, coalesced, quarantined, and retried around pauses, resizes, external TUI handoffs, and shutdown.

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

Merge Risk: ⚪ Minimal · up to 14eef

This change adds parsing for terminal pixel-size responses used by image geometry handling. No current merge-blocking behavior or compatibility risk remains identified.

Sequence Diagram(s)

sequenceDiagram
  participant App
  participant Ink
  participant TerminalQuerier
  participant Terminal
  App->>TerminalQuerier: Schedule XTVERSION probe
  Ink->>TerminalQuerier: Request Kitty and terminal pixel metrics
  TerminalQuerier->>Terminal: Send queries
  Terminal-->>TerminalQuerier: Return capability and geometry replies
  Ink->>TerminalQuerier: Suspend during external TUI handoff
  Ink->>TerminalQuerier: Resume after reply quarantine

Loading

Suggested reviewers: ccch1mneyyy, cikeseven

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 59.09% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 8 files.	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 clearly and concisely describes the main change: hardening terminal image transport and rendering behavior.
Linked Issues check	✅ Passed	The changes satisfy the coding objectives in [#686]. They add aspect-ratio-preserving geometry with fallback sizing, transparent letterboxing, bounded downsampling, zlib-compressed RGBA uploads, share…
Out of Scope Changes check	✅ Passed	The documentation and regression tests directly support the terminal image transport, geometry, and handoff changes in [#686]. No attachment, message-domain, transcript, cropping, or temporal payload …

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/terminal-image-hardening

---

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