Kitty graphics: Implement relative placements (P/Q/H/V keys)

[anthonykim1]

Context

The Kitty graphics protocol supports "relative placements" — positioning an image relative to another already-placed image rather than at the current cursor position. This uses four keys: P (parent image ID), Q (parent placement ID), H (horizontal offset from parent in pixels), and V (vertical offset from parent in pixels).

Currently none of these keys are parsed or handled anywhere in the codebase.

What needs to happen

1. Parse relative placement keys in KittyGraphicsTypes.ts:

   • P — parent image ID (the image to position relative to)
   • Q — parent placement ID (which placement of the parent image)
   • H — horizontal offset in pixels from parent's top-left corner
   • V — vertical offset in pixels from parent's top-left corner
   • Add these to the KittyKey enum and IKittyCommand interface

2. Implement relative positioning in KittyGraphicsHandler._decodeAndDisplay():

   • When P is specified, look up the parent image's placement position in the buffer
   • Calculate the target position as parent position + (H, V) pixel offsets
   • Convert pixel offsets to cell coordinates for placement
   • If the parent placement is not found, respond with an error

3. Track placement positions in KittyImageStorage:

   • Need to store the screen position of each placement so child images can reference it
   • This likely requires a placement registry mapping (imageId, placementId) → (row, col, pixelOffsetX, pixelOffsetY)

Spec reference

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

Key files

• addons/addon-image/src/kitty/KittyGraphicsTypes.ts — add P, Q, H, V key parsing
• addons/addon-image/src/kitty/KittyGraphicsHandler.ts — _decodeAndDisplay() needs relative positioning logic
• addons/addon-image/src/kitty/KittyImageStorage.ts — needs placement position tracking
• addons/addon-image/test/KittyGraphics.test.ts

Acceptance criteria

• a=T,i=2,P=1,H=50,V=30 places image 2 at 50px right and 30px down from image 1's top-left
• a=T,i=2,P=1,Q=3,H=0,V=0 places image 2 at the same position as placement 3 of image 1
• If parent image/placement not found, respond with appropriate error
• Negative H/V offsets work correctly (place to the left/above parent)
• Integration tests verify relative positioning accuracy

Discussion

See feature inventory §12 in #5683

[jerch]

This will get a bit tricky with the current storage backend, as it needs a true double saving of contents to be shown, or a neat thin abstraction to fetch and place partial contents in ImageStorage.render. I would prefer the latter for the sake of memory usage, but that is hard to get done right.

Rough idea - additionally to addImage maybe we need a addPlacement with coords and a ref to an IImageDef. something along these lines. I would need a similar function for image seralization later on (separating image data load from image placement).