Add Kitty frame renderer and shared random pool

Author: luccahuguet

README.md

@@ -8,11 +8,13 @@ The user-facing command is `yzs`
 nix run github:luccahuguet/yazelix-screen#yzs
 nix run github:luccahuguet/yazelix-screen#yzs -- mandelbrot
 nix run github:luccahuguet/yazelix-screen#yzs -- game_of_life_bloom --cell-style dotted
+nix run github:luccahuguet/yazelix-screen#yzs -- magician --kitty-frame-dir /path/to/frames --kitty-frame-count 198
 ```
 
 ## What It Contains
 
 - Animation engines for Boids, Mandelbrot, and Game of Life
+- File-backed Kitty PNG frame sequence rendering
 - Frame production through `ScreenFrameProducer`
 - Terminal sizing helpers and alternate-screen rendering helpers
 - A standalone `yzs` binary
@@ -27,6 +29,7 @@ yzs --help
 yzs
 yzs mandelbrot
 yzs game_of_life_bloom --cell-style dotted
+yzs magician --kitty-frame-dir /path/to/frames --kitty-frame-count 198
 ```
 
 Yazelix users get the integrated screen surface through the main command:
@@ -44,6 +47,7 @@ From this repository:
 cargo run --bin yzs -- --help
 cargo run --bin yzs -- mandelbrot
 cargo run --bin yzs -- game_of_life_bloom --cell-style dotted
+cargo run --bin yzs -- magician --kitty-frame-dir /path/to/frames --kitty-frame-count 198
 ```
 
 With Nix:
@@ -60,13 +64,18 @@ Supported styles:
 - `boids_predator`
 - `boids_schools`
 - `mandelbrot`
+- `magician`
 - `game_of_life_gliders`
 - `game_of_life_oscillators`
 - `game_of_life_bloom`
 - `random`
 
 No style means `random`
 
+`magician` requires a directory of PNG frame assets. With `--kitty-frame-count N`, `yzs` expects `frame_0.png` through `frame_N-1.png`; without a count, it uses every PNG in the directory
+
+`random` uses the same four-family pool as Yazelix and can resolve to `magician`, so pass the Kitty frame arguments when standalone random playback should support that branch
+
 ## Library Examples
 
 Render one frame without alternate-screen mode: