Update and refactor ImageCarousel fill handling

Previously, the ImageCarousel needed to directly set a video size
binding to the video player view, in order to communicate and listen to
video size changes, and it used that to calculate the carousel image fill.

However, in the new video coordination architecture, the video size is
not owned by the ImageCarousel, but instead it is owned by the video
player itself, which in turn is owned by the video coordinator.
Therefore, this is incompatible with several logic elements of
ImageCarousel.

This commit updates the image carousel to integrate with the new video
coordinator architecture, and it also refactors the image fill logic
almost completely — with a focus on reducing stateful behavior by
carefully employing some state management patterns.

Furthermore, the new CarouselModel was heavily documented to explain its
design decisions and inner workings.

Note: There used to be some caching on the ImageFill calculations, but
after using this new refactored version without caching, I have not
noticed any noticeable performance regressions, so I have decided not to
add them back — applying Occam's razor

Changelog-Changed: Improved image carousel image fill behavior
Closes: https://github.com/damus-io/damus/issues/2458
Signed-off-by: Daniel D’Aquino <daniel@daquino.me>

damus/Util/Extensions/KFOptionSetter+.swift

@@ -58,6 +58,22 @@ extension KFOptionSetter {
         
         return self
     }
+    
+    /// This allows you to observe the size of the image, and get a callback when the size changes
+    /// This is useful for when you need to layout views based on the size of the image
+    /// - Parameter size_changed: A callback that will be called when the size of the image changes
+    /// - Returns: The same KFOptionSetter instance
+    func observe_image_size(size_changed: @escaping (CGSize) -> Void) -> Self {
+        let modifier = AnyImageModifier { image -> KFCrossPlatformImage in
+            let image_size = image.size
+            DispatchQueue.main.async { [size_changed, image_size] in
+                size_changed(image_size)
+            }
+            return image
+        }
+        options.imageModifier = modifier
+        return self
+    }
 }
 
 let MAX_FILE_SIZE = 20_971_520 // 20MiB