pi-simocracy · kitty-graphics-render

Animated codex pets via the Kitty graphics protocol

@daviddao

Replace pi-simocracy's ANSI half-block sprite render with true-pixel inline graphics in Kitty / Ghostty / WezTerm / iTerm2, including a 6-frame idle animation that ticks via pi-tui's existing render loop — typing during animation continues to work, the same way it does during a spinner.

Date: 2026-05-03 · Version: pi-simocracy 0.5.1 · pass

---

Headline result

Walkthrough

Hero render — actual Ghostty screenshot

Both sims loaded via the production message-renderer path. Each sprite is the native 192×208 idle cell from the codex-pet atlas, transmitted with Kitty's a=T action and a stable image ID so frame swaps replace in place. Display is pinned to SIMOCRACY_SPRITE_WIDTH cells wide (default 10) with aspect-ratio-preserved height; the terminal does the on-screen scaling.

ANSI half-block fallback

Same script invoked with SIMOCRACY_INLINE_GRAPHICS=ansi simulates a terminal that doesn't advertise Kitty / iTerm2 inline-image support. Pi-simocracy detects the lack of capability and falls back to its existing ▀ / ▄ 24-bit colour half-block render. Same source RGBA, same sims, same display target — visibly more pixelated because each cell paints two pixels via Unicode block characters instead of a real bitmap.

Wire-level evidence

vhs tape (rendered in xterm.js, which can't display inline images) showing the underlying mechanism: terminal capability detection, the actual Kitty graphics escape sequence emitted to stdout, and the env-var-driven switch to the ANSI fallback path.

In-tape highlights: { images: 'kitty', trueColor: true, hyperlinks: true } from detectCapabilities() in Ghostty; the on-the-wire Kitty escape \x1b_Ga=T,f=100,q=2,c=10,r=6,m=1;iVBORw0KG…; the same call with SIMOCRACY_INLINE_GRAPHICS=ansi producing 24-bit colour half-block escapes (\x1b[38;2;…m▄) instead.

Animation mechanism — headless verification

The animation is impossible to capture in vhs (xterm.js can't render the bitmaps), so we verify the *mechanism* instead. This vhs tape runs a test harness that mocks pi-tui, mounts an AnimatedImage with Duo's 6 idle frames at 5 fps, and dumps a verification matrix showing every emission carries the same Kitty image ID (= in-place bitmap swap) but a different payload hash (= frames actually cycle). The 0.5.0 release shipped a regression where this didn't fire — pi-tui's Image component caches its render output and the base64Data is private, so frame swaps couldn't propagate through. 0.5.1 ships a tiny custom AnimatedImage component that owns its frames + timer and emits a fresh escape on every render() call.

In-tape result: 7 ticks captured in 1.5 s (≈4.6 fps measured against 5 fps target) · 1 distinct image ID (4001028631) across all ticks · 6 distinct sha256 payload hashes (= 6 idle frames cycling) · ✅ PASS.

How it works

Findings

Reproducing