Kitty graphics: Implement animation support (a=f, a=a, a=c)

[anthonykim1]

Context

The Kitty graphics protocol supports animated images through three actions: a=f (frame operations), a=a (animation control), and a=c (frame composition). None of these are implemented — they all return EINVAL:unsupported action. The related animation keys (frame number, gap, blend mode, etc.) are also not parsed.

What needs to happen

1. Parse animation keys in KittyGraphicsTypes.ts:

   • Add to KittyKey enum and IKittyCommand:
     • Frame-related: frame number, source frame for copy, gap (ms between frames), blend mode, composition mode, background frame
   • Reference: https://sw.kovidgoyal.net/kitty/graphics-protocol/#control-data-reference

2. Implement a=f (frame operations):

   • Load a new frame into an existing image
   • Edit an existing frame's data
   • Delete specific frames
   • Each frame has its own pixel data, gap timing, blend/composition mode

3. Implement a=a (animation control):

   • Start/stop animation playback
   • Set number of loops
   • Jump to a specific frame
   • Set default gap timing

4. Implement a=c (frame composition):

   • Compose/blend one frame onto another
   • Support composition modes: overwrite, alpha blend, etc.

5. Animation rendering loop:

   • Timer-based frame advancement using per-frame gap values
   • Re-render the image placement each time the active frame changes
   • Respect loop count

6. Wire up delete selector f/F (delete animation frames) — currently listed as unsupported in _handleDelete(), depends on this work

Spec reference

https://sw.kovidgoyal.net/kitty/graphics-protocol/#animation

Key files

• addons/addon-image/src/kitty/KittyGraphicsTypes.ts — add animation key parsing
• addons/addon-image/src/kitty/KittyGraphicsHandler.ts — TODOs at lines 329 and 363 for a=f, a=a, a=c
• addons/addon-image/src/kitty/KittyImageStorage.ts — needs per-image frame storage
• addons/addon-image/src/ImageRenderer.ts — needs timer-driven re-rendering for animation
• addons/addon-image/test/KittyGraphics.test.ts — TODO at line 108 for animation frame tests

Acceptance criteria

• a=f,i=3 loads a new animation frame into image 3
• a=a,i=3,s=1 starts animation playback for image 3
• a=a,i=3,s=3 stops animation playback
• Frame gap timing controls the speed of animation
• Blend modes (alpha blend, overwrite) work correctly between frames
• a=c,i=3 composes frames together
• d=f deletes animation frames
• Integration tests with animated image sequences

Discussion

See feature inventory §2.6–2.8, §13 in #5683

[jerch]

@anthonykim1 Animation support is also in the TODO list for the IIP protocol (gifs). The proper way forward prolly would be an extension of the storage to hold multiple frames plus a render hook implementing time based frame switches.