basalt-appkit 0.0.0-rc5 → 0.2.0

package/native/tests/test_appkit_fonts.mm

@@ -0,0 +1,203 @@
+// Fonts loaded while the app is running, which is the seam `expo-font` arrives
+// through.
+//
+// The half worth testing is not that Core Text can register a file. It is that
+// the name the app chose keeps working afterwards: a font file carries its own
+// family name inside it, usually not the one the app passed to `loadAsync`, so
+// `fontFamily: 'TheAppsName'` only renders in that font if the registry
+// remembers the mapping and the layout asks it. That mapping is the whole of
+// core/FontRegistry.h, and until now nothing on this host asked it anything.
+//
+// The file is a real one, found through Core Text rather than added to this
+// repository as a fixture. Registering a font the system already has, under a
+// second name of the app's choosing, exercises exactly the mapping this seam
+// exists for and does it on any Mac.
+//
+// A face the system does *not* have is the case `expo-font` really exists for,
+// and it gets its own test at the bottom of this file: tests/RenamedFontFile.h
+// renames the family inside a copy of that same file, which is the one change
+// that makes a font new to the machine.
+
+#include "TestHarness.h"
+
+#import "CoreTextLayout.h"
+#import "RnTextLayout.h"
+
+#include "FontRegistry.h"
+#include "RenamedFontFile.h"
+
+#import <AppKit/AppKit.h>
+#import <CoreText/CoreText.h>
+
+#include <react/renderer/attributedstring/AttributedString.h>
+#include <react/renderer/textlayoutmanager/TextLayoutManager.h>
+#include <react/utils/ContextContainer.h>
+
+#include <cmath>
+#include <filesystem>
+#include <string>
+
+namespace {
+
+// Monospaced on purpose. The assertions below compare against the proportional
+// system font, and two proportional faces can measure the same string to the
+// same width, which would make a passing test mean nothing.
+NSString *const kKnownFamily = @"Courier New";
+
+// Where the system keeps that family's file. `kCTFontURLAttribute` is the only
+// way to ask: a descriptor built from a family name answers with the name, and
+// `registerFont` needs a path.
+std::string pathOfKnownFamily() {
+  NSFontDescriptor *wanted = [NSFontDescriptor fontDescriptorWithFontAttributes:@{
+    NSFontFamilyAttribute : kKnownFamily,
+  }];
+  NSArray<NSFontDescriptor *> *matches = [wanted
+      matchingFontDescriptorsWithMandatoryKeys:[NSSet setWithObject:NSFontFamilyAttribute]];
+  for (NSFontDescriptor *descriptor in matches) {
+    NSURL *url = (__bridge_transfer NSURL *)CTFontDescriptorCopyAttribute(
+        (__bridge CTFontDescriptorRef)descriptor, kCTFontURLAttribute);
+    if (url.isFileURL && url.path.length > 0) {
+      return url.path.UTF8String;
+    }
+  }
+  return {};
+}
+
+facebook::react::AttributedString paragraphIn(const std::string &family, const char *text) {
+  facebook::react::TextAttributes attributes;
+  attributes.fontSize = 24.0F;
+  attributes.fontFamily = family;
+
+  facebook::react::AttributedString::Fragment fragment;
+  fragment.string = text;
+  fragment.textAttributes = attributes;
+
+  facebook::react::AttributedString string;
+  string.appendFragment(std::move(fragment));
+  return string;
+}
+
+// The font Core Text was actually handed for a paragraph asking for `family`,
+// which is the question the registry exists to answer. Through buildTextLayout
+// rather than through fontFor directly, because the path from a prop to a font
+// is what an app's `fontFamily` travels.
+NSString *familyLaidOutFor(const std::string &family) {
+  NSAttributedString *built =
+      basalt::buildTextLayout(paragraphIn(family, "Handgloves"),
+                              facebook::react::ParagraphAttributes{})
+          .attributedString;
+  NSFont *font = [built attribute:NSFontAttributeName atIndex:0 effectiveRange:nullptr];
+  return font.familyName;
+}
+
+} // namespace
+
+TEST(appkit_a_font_loaded_at_runtime_resolves_to_the_family_in_the_file) {
+  @autoreleasepool {
+    const std::string path = pathOfKnownFamily();
+    EXPECT(!path.empty());
+
+    const std::string alias = "BasaltResolvedAlias";
+    EXPECT(basalt::registerFont(alias, path));
+    EXPECT(basalt::isFontRegistered(alias));
+
+    // The point of the registry: what the app calls it maps to what the file
+    // calls itself, which is the name Core Text indexes by.
+    EXPECT_EQ(basalt::resolveFontFamily(alias), std::string(kKnownFamily.UTF8String));
+
+    // And a name nobody registered comes back unchanged, so a system family
+    // reaches Core Text as itself rather than being rewritten.
+    EXPECT_EQ(basalt::resolveFontFamily("Helvetica"), std::string("Helvetica"));
+    EXPECT(!basalt::isFontRegistered("BasaltNeverLoaded"));
+  }
+}
+
+TEST(appkit_text_asking_for_a_runtime_family_is_laid_out_in_it) {
+  @autoreleasepool {
+    const std::string path = pathOfKnownFamily();
+    EXPECT(!path.empty());
+
+    const std::string alias = "BasaltLaidOutAlias";
+    EXPECT(basalt::registerFont(alias, path));
+
+    EXPECT_EQ(std::string(familyLaidOutFor(alias).UTF8String),
+              std::string(kKnownFamily.UTF8String));
+
+    // The negative control, and the reason the assertion above is not vacuous:
+    // a family the system does not have falls back to the system font, so a
+    // registry that forgot the mapping would land here instead.
+    NSString *fallback = familyLaidOutFor("BasaltNeverLoaded");
+    EXPECT(![fallback isEqualToString:kKnownFamily]);
+    EXPECT_EQ(std::string(fallback.UTF8String),
+              std::string([NSFont systemFontOfSize:24].familyName.UTF8String));
+  }
+}
+
+TEST(appkit_a_font_registered_after_a_measurement_invalidates_it) {
+  @autoreleasepool {
+    const std::string path = pathOfKnownFamily();
+    EXPECT(!path.empty());
+
+    // This is how every loader works, `useFonts` included: the app renders
+    // first, in whatever the fallback is, and the font arrives afterwards. The
+    // measurement from before has to stop counting, or the paragraph keeps the
+    // fallback's size for the rest of the session and the font appears to have
+    // done nothing.
+    const std::string alias = "BasaltCacheAlias";
+    EXPECT(!basalt::isFontRegistered(alias));
+
+    const facebook::react::TextLayoutManager manager(
+        std::make_shared<const facebook::react::ContextContainer>());
+    const auto widthNow = [&] {
+      return manager
+          .measure(facebook::react::AttributedStringBox{paragraphIn(alias, "Handgloves")},
+                   facebook::react::ParagraphAttributes{},
+                   facebook::react::TextLayoutContext{},
+                   facebook::react::LayoutConstraints{})
+          .size.width;
+    };
+
+    const float fallbackWidth = widthNow();
+    EXPECT(fallbackWidth > 0.0F);
+    // Measured again with nothing changed, to show the cache is in the way: if
+    // the two differed here, the test below would prove nothing.
+    EXPECT(std::fabs(widthNow() - fallbackWidth) < 0.01F);
+
+    const unsigned long before = basalt::fontGeneration();
+    EXPECT(basalt::registerFont(alias, path));
+    EXPECT(basalt::fontGeneration() != before);
+
+    EXPECT(std::fabs(widthNow() - fallbackWidth) > 0.5F);
+  }
+}
+
+TEST(appkit_a_font_the_system_does_not_have_becomes_usable) {
+  @autoreleasepool {
+    const std::string path = pathOfKnownFamily();
+    EXPECT(!path.empty());
+
+    const std::filesystem::path copy =
+        std::filesystem::temp_directory_path() / "basalt-appkit-renamed-font.ttf";
+    const basalt::test::RenamedFont renamed = basalt::test::renameFontFile(
+        path, kKnownFamily.UTF8String, copy.string());
+    EXPECT(!renamed.path.empty());
+
+    // Before: nobody has this family, so a paragraph asking for it by its own
+    // name gets the system font. This is the assertion that makes the rest of
+    // the file more than a lookup table test -- everything above registers a
+    // face Core Text already had.
+    EXPECT_EQ(std::string(familyLaidOutFor(renamed.family).UTF8String),
+              std::string([NSFont systemFontOfSize:24].familyName.UTF8String));
+
+    const std::string alias = "BasaltBundledAlias";
+    EXPECT(basalt::registerFont(alias, renamed.path));
+    EXPECT_EQ(basalt::resolveFontFamily(alias), renamed.family);
+
+    // After: the app's name reaches it, and so does the family inside the file,
+    // which is what `CTFontManagerRegisterFontsForURL` was called for.
+    EXPECT_EQ(std::string(familyLaidOutFor(alias).UTF8String), renamed.family);
+    EXPECT_EQ(std::string(familyLaidOutFor(renamed.family).UTF8String), renamed.family);
+
+    std::filesystem::remove(copy);
+  }
+}

package/native/tests/test_appkit_image.mm

@@ -18,7 +18,9 @@
 
 #import "RnAppKitView.h"
 
+#include <cmath>
 #include <sstream>
+#include <vector>
 
 namespace {
 
@@ -36,18 +38,25 @@ CGImageRef makeImage(size_t width, size_t height) {
   return image;
 }
 
-struct Ink {
-  int left{-1};
-  int top{-1};
-  int right{-1};
-  int bottom{-1};
-  int width() const { return right < 0 ? 0 : right - left + 1; }
-  int height() const { return bottom < 0 ? 0 : bottom - top + 1; }
-};
+// Left half black, right half white, opaque. A step edge, which is the one
+// picture a blur is measurable against: how far the ramp spreads is the radius.
+CGImageRef makeSplitImage(size_t width, size_t height) {
+  CGColorSpaceRef space = CGColorSpaceCreateWithName(kCGColorSpaceSRGB);
+  CGContextRef context = CGBitmapContextCreate(nullptr, width, height, 8, 0, space,
+                                               kCGImageAlphaPremultipliedLast);
+  CGColorSpaceRelease(space);
+  CGContextSetRGBFillColor(context, 1, 1, 1, 1);
+  CGContextFillRect(context, CGRectMake(0, 0, (CGFloat)width, (CGFloat)height));
+  CGContextSetRGBFillColor(context, 0, 0, 0, 1);
+  CGContextFillRect(context, CGRectMake(0, 0, (CGFloat)width / 2, (CGFloat)height));
+  CGImageRef image = CGBitmapContextCreateImage(context);
+  CGContextRelease(context);
+  return image;
+}
 
-// Draws the view into a white bitmap and returns the bounding box of anything
-// darker than white.
-Ink inkOf(RnAppKitView *view, CGSize size) {
+// The red channel of the view drawn onto white, row-major. Red rather than
+// luminance because everything here is grey or black: the three channels agree.
+std::vector<unsigned char> drawnPixels(RnAppKitView *view, CGSize size) {
   CGColorSpaceRef space = CGColorSpaceCreateWithName(kCGColorSpaceSRGB);
   CGContextRef context = CGBitmapContextCreate(nullptr, (size_t)size.width, (size_t)size.height,
                                                8, 0, space, kCGImageAlphaPremultipliedLast);
@@ -56,9 +65,7 @@ Ink inkOf(RnAppKitView *view, CGSize size) {
   CGContextFillRect(context, CGRectMake(0, 0, size.width, size.height));
   // A CGBitmapContext counts y from the bottom and this view counts it from the
   // top, and `graphicsContextWithCGContext:flipped:` only *declares* which way
-  // up a context is -- it applies no transform. Every case here happens to be
-  // vertically symmetric, so this changes no result; without it the next case
-  // that is not symmetric would be read upside down.
+  // up a context is -- it applies no transform.
   CGContextTranslateCTM(context, 0, size.height);
   CGContextScaleCTM(context, 1, -1);
 
@@ -68,12 +75,60 @@ Ink inkOf(RnAppKitView *view, CGSize size) {
   [view drawRect:NSMakeRect(0, 0, size.width, size.height)];
   NSGraphicsContext.currentContext = previous;
 
-  auto *pixels = static_cast<unsigned char *>(CGBitmapContextGetData(context));
+  auto *bytes = static_cast<unsigned char *>(CGBitmapContextGetData(context));
   const size_t stride = CGBitmapContextGetBytesPerRow(context);
+  std::vector<unsigned char> red((size_t)size.width * (size_t)size.height);
+  for (size_t y = 0; y < (size_t)size.height; y++) {
+    for (size_t x = 0; x < (size_t)size.width; x++) {
+      red[y * (size_t)size.width + x] = bytes[y * stride + x * 4];
+    }
+  }
+  CGContextRelease(context);
+  return red;
+}
+
+// How wide the black-to-white ramp is along the middle row, from 10% to 90%.
+//
+// For a gaussian of standard deviation sigma that width is 2.563 * sigma, which
+// is how a measured number here becomes a statement about the radius: an
+// unblurred edge is one or two pixels and nothing else needs to be known about
+// the filter.
+double rampWidth(RnAppKitView *view, CGSize size) {
+  const std::vector<unsigned char> pixels = drawnPixels(view, size);
+  const int width = (int)size.width;
+  const int row = (int)size.height / 2;
+  int low = -1;
+  int high = -1;
+  for (int x = 0; x < width; x++) {
+    const unsigned char value = pixels[(size_t)row * (size_t)width + (size_t)x];
+    if (low < 0 && value > 25) {
+      low = x;
+    }
+    if (value > 229) {
+      high = x;
+      break;
+    }
+  }
+  return (high > low && low >= 0) ? (double)(high - low) : 0.0;
+}
+
+struct Ink {
+  int left{-1};
+  int top{-1};
+  int right{-1};
+  int bottom{-1};
+  int width() const { return right < 0 ? 0 : right - left + 1; }
+  int height() const { return bottom < 0 ? 0 : bottom - top + 1; }
+};
+
+// Draws the view into a white bitmap and returns the bounding box of anything
+// darker than white.
+Ink inkOf(RnAppKitView *view, CGSize size) {
+  const std::vector<unsigned char> pixels = drawnPixels(view, size);
   Ink ink;
   for (int y = 0; y < (int)size.height; y++) {
     for (int x = 0; x < (int)size.width; x++) {
-      if (pixels[(size_t)y * stride + (size_t)x * 4] < 128) {
+      if (pixels[(size_t)y * (size_t)size.width + (size_t)x] < 128) {
         if (ink.left < 0 || x < ink.left) ink.left = x;
         if (ink.right < 0 || x > ink.right) ink.right = x;
         if (ink.top < 0 || y < ink.top) ink.top = y;
@@ -81,7 +136,6 @@ Ink inkOf(RnAppKitView *view, CGSize size) {
       }
     }
   }
-  CGContextRelease(context);
   return ink;
 }
 
@@ -235,3 +289,324 @@ TEST(image_repeat_keeps_the_tile_at_its_natural_size) {
     CGImageRelease(image);
   }
 }
+
+// `blurRadius` blurs the image, and by the right amount.
+//
+// The amount is the whole point of the test. A blur that is applied in the
+// source image's pixels rather than in the view's coordinates still looks
+// blurred, and still passes a test that only asks whether the edge is soft, but
+// it is a different picture from the GTK side's for every image that is not
+// drawn at its natural size. Here a 40-pixel-wide image is stretched to 200, so
+// a blur in the wrong space would be five times too narrow.
+TEST(image_blur_radius_softens_the_edge_in_view_coordinates) {
+  @autoreleasepool {
+    CGImageRef image = makeSplitImage(40, 8);
+    const CGSize size = CGSizeMake(200, 40);
+
+    RnAppKitView *sharp = imageView(image, RnAppKitImageFitStretch, size);
+    const double unblurred = rampWidth(sharp, size);
+    // Four pixels, which is what "no blur" looks like here: one source pixel is
+    // five destination pixels wide after the stretch, and the interpolation
+    // between them is the whole ramp.
+    EXPECT(unblurred <= 5);
+
+    RnAppKitView *view = imageView(image, RnAppKitImageFitStretch, size);
+    [view setRnImageBlur:20];
+    // sigma is half the radius and a 10-90 ramp is 2.563 sigma, so a radius of
+    // 20 is a ramp near 26 pixels, which is what it measures. The tolerance is
+    // wide enough for Core Image to round its kernel differently on a future
+    // macOS and narrow enough to fail on a blur applied in the source's own
+    // pixels: that one is magnified by the stretch along with the picture and
+    // measures 130, which is checked by sabotage rather than guessed at.
+    EXPECT_NEAR((int)rampWidth(view, size), 26, 5);
+
+    CGImageRelease(image);
+  }
+}
+
+// Zero is no blur, and so is a negative radius: an app can send either and
+// neither is a crash or a filter with a nonsense kernel.
+TEST(image_blur_radius_of_zero_or_less_draws_the_image_itself) {
+  @autoreleasepool {
+    CGImageRef image = makeSplitImage(40, 8);
+    const CGSize size = CGSizeMake(200, 40);
+
+    RnAppKitView *view = imageView(image, RnAppKitImageFitStretch, size);
+    [view setRnImageBlur:20];
+    [view setRnImageBlur:0];
+    EXPECT((int)rampWidth(view, size) <= 5);
+
+    [view setRnImageBlur:-20];
+    EXPECT((int)rampWidth(view, size) <= 5);
+
+    CGImageRelease(image);
+  }
+}
+
+// A tinted image is a silhouette filled with one colour, and a blurred tinted
+// image is that silhouette with soft edges. The mask is what gets blurred here,
+// which is the same picture as blurring the fill because the colour is
+// constant, and it is what the GTK side does by pushing its blur around the
+// tint rather than inside it.
+TEST(image_blur_radius_applies_to_a_tinted_image_too) {
+  @autoreleasepool {
+    // Opaque black on the left, transparent on the right: with a tint it is the
+    // alpha that decides where the colour lands.
+    CGColorSpaceRef space = CGColorSpaceCreateWithName(kCGColorSpaceSRGB);
+    CGContextRef bitmap = CGBitmapContextCreate(nullptr, 40, 8, 8, 0, space,
+                                                kCGImageAlphaPremultipliedLast);
+    CGColorSpaceRelease(space);
+    CGContextSetRGBFillColor(bitmap, 0, 0, 0, 1);
+    CGContextFillRect(bitmap, CGRectMake(0, 0, 20, 8));
+    CGImageRef image = CGBitmapContextCreateImage(bitmap);
+    CGContextRelease(bitmap);
+
+    const CGSize size = CGSizeMake(200, 40);
+    RnAppKitView *view = imageView(image, RnAppKitImageFitStretch, size);
+    [view setRnImageTint:[NSColor colorWithSRGBRed:0 green:0 blue:0 alpha:1]];
+    EXPECT((int)rampWidth(view, size) <= 5);
+
+    [view setRnImageBlur:20];
+    EXPECT_NEAR((int)rampWidth(view, size), 26, 5);
+
+    CGImageRelease(image);
+  }
+}
+
+// Clearing the image must not leave the blurred copy of it behind to be drawn
+// against the next one, and a blur with no image at all is nothing rather than a
+// crash.
+TEST(image_blur_survives_the_image_being_replaced) {
+  @autoreleasepool {
+    const CGSize size = CGSizeMake(200, 40);
+    RnAppKitView *view = [RnAppKitView viewWithTag:1];
+    [view setRnFrameX:0 y:0 width:size.width height:size.height];
+    [view setRnImageBlur:20];
+    EXPECT_EQ(inkOf(view, size).width(), 0);
+
+    CGImageRef image = makeSplitImage(40, 8);
+    [view setRnImage:image fit:RnAppKitImageFitStretch];
+    EXPECT_NEAR((int)rampWidth(view, size), 26, 5);
+
+    [view setRnImage:nullptr fit:RnAppKitImageFitStretch];
+    EXPECT_EQ(inkOf(view, size).width(), 0);
+    CGImageRelease(image);
+  }
+}
+
+// And the radius is in the tree dump, spelled as GTK spells it.
+//
+// Which is what makes the wiring testable rather than only the drawing: the
+// prop is read in a branch of AppKitMountingManager that knows ImageProps, and
+// every test above sets the blur on the view by hand, so all of them pass while
+// the mounting manager drops it on the floor. The GTK side did exactly that.
+TEST(image_blur_is_reported_in_the_tree) {
+  @autoreleasepool {
+    CGImageRef image = makeImage(4, 2);
+    RnAppKitView *view = imageView(image, RnAppKitImageFitStretch, CGSizeMake(50, 50));
+    CGImageRelease(image);
+
+    EXPECT(![[view describeTree] containsString:@"blur="]);
+    [view setRnImageBlur:8];
+    EXPECT([[view describeTree] containsString:@"blur=8"]);
+    [view setRnImageBlur:0];
+    EXPECT(![[view describeTree] containsString:@"blur="]);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Animated images.
+//
+// The frames come out of a real GIF rather than from bitmaps built here: the
+// delays and the loop count are in the file's own bytes, and reading them is
+// half of what this platform had to learn. The file is four pixels square,
+// ninety-five bytes, and inline for the same reason the still fixtures above
+// are -- it needs no asset pipeline and no fixture to keep in step.
+//
+// Written with ImageMagick:
+//
+//   magick -loop 0 -delay 8 -size 4x4 xc:'#ff0000' \
+//                 -delay 4 -size 4x4 xc:'#0000ff' anim.gif
+//
+// so frame one is red for 80ms and frame two is blue for 40ms, forever. The
+// delays differ on purpose: equal ones hide an engine that uses the first
+// frame's delay for all of them.
+// ---------------------------------------------------------------------------
+namespace {
+
+const char *const kAnimatedGifBase64 =
+    "R0lGODlhBAAEAPAAAP8AAAAAACH/C05FVFNDQVBFMi4wAwEAAAAh+QQACAAAACwAAAAABAAEAAAC"
+    "BISPCQUAIfkEAAQAAAAsAAAAAAQABACAAAD/AAAAAgSEjwkFADs=";
+
+CGImageSourceRef animatedGifSource() {
+  NSData *bytes = [[NSData alloc] initWithBase64EncodedString:@(kAnimatedGifBase64) options:0];
+  return CGImageSourceCreateWithData((__bridge CFDataRef)bytes, nullptr);
+}
+
+// The frames of that GIF, as the view takes them.
+NSArray *animatedGifFrames() {
+  CGImageSourceRef source = animatedGifSource();
+  NSMutableArray *frames = [NSMutableArray array];
+  for (size_t index = 0; index < CGImageSourceGetCount(source); index++) {
+    CGImageRef frame = CGImageSourceCreateImageAtIndex(source, index, nullptr);
+    if (frame != nullptr) {
+      [frames addObject:(__bridge_transfer id)frame];
+    }
+  }
+  CFRelease(source);
+  return frames;
+}
+
+// The colour at the centre of the view, drawn onto white. All three channels,
+// unlike `drawnPixels` above: red and blue differ in two of them and agree in
+// the green, so one channel cannot tell these frames apart.
+struct Rgb {
+  unsigned char red{0};
+  unsigned char green{0};
+  unsigned char blue{0};
+};
+
+Rgb centreColour(RnAppKitView *view, CGSize size) {
+  CGColorSpaceRef space = CGColorSpaceCreateWithName(kCGColorSpaceSRGB);
+  CGContextRef context = CGBitmapContextCreate(nullptr, (size_t)size.width, (size_t)size.height,
+                                               8, 0, space, kCGImageAlphaPremultipliedLast);
+  CGColorSpaceRelease(space);
+  CGContextSetRGBFillColor(context, 1, 1, 1, 1);
+  CGContextFillRect(context, CGRectMake(0, 0, size.width, size.height));
+  CGContextTranslateCTM(context, 0, size.height);
+  CGContextScaleCTM(context, 1, -1);
+
+  NSGraphicsContext *previous = NSGraphicsContext.currentContext;
+  NSGraphicsContext.currentContext = [NSGraphicsContext graphicsContextWithCGContext:context
+                                                                             flipped:YES];
+  [view drawRect:NSMakeRect(0, 0, size.width, size.height)];
+  NSGraphicsContext.currentContext = previous;
+
+  auto *bytes = static_cast<unsigned char *>(CGBitmapContextGetData(context));
+  const size_t stride = CGBitmapContextGetBytesPerRow(context);
+  const size_t row = (size_t)size.height / 2;
+  const size_t column = (size_t)size.width / 2;
+  const Rgb colour{bytes[row * stride + column * 4], bytes[row * stride + column * 4 + 1],
+                   bytes[row * stride + column * 4 + 2]};
+  CGContextRelease(context);
+  return colour;
+}
+
+RnAppKitView *animatedView(NSArray *frames, NSArray<NSNumber *> *delays, NSUInteger loops) {
+  RnAppKitView *view = [RnAppKitView viewWithTag:1];
+  [view setRnFrameX:0 y:0 width:20 height:20];
+  [view setRnImage:(__bridge CGImageRef)frames.firstObject fit:RnAppKitImageFitStretch];
+  [view setRnImageFrames:frames delaysMs:delays loopCount:loops];
+  return view;
+}
+
+} // namespace
+
+TEST(animated_image_the_frame_follows_the_time_it_is_advanced_by) {
+  @autoreleasepool {
+    NSArray *frames = animatedGifFrames();
+    EXPECT_EQ((int)frames.count, 2);
+
+    RnAppKitView *view = animatedView(frames, @[@80, @40], 0);
+    const CGSize size = CGSizeMake(20, 20);
+
+    // Frame one, red, which is also what a still <Image> of this file draws.
+    EXPECT(centreColour(view, size).red > 200);
+    EXPECT(centreColour(view, size).blue < 60);
+    EXPECT_EQ((int)view.rnImageFrameIndex, 0);
+
+    // Still frame one at 79ms: the delay is the file's and not a guess.
+    [view rnAdvanceImageAnimationBy:79];
+    EXPECT_EQ((int)view.rnImageFrameIndex, 0);
+
+    // Frame two, blue, one millisecond later.
+    [view rnAdvanceImageAnimationBy:1];
+    EXPECT_EQ((int)view.rnImageFrameIndex, 1);
+    EXPECT(centreColour(view, size).blue > 200);
+    EXPECT(centreColour(view, size).red < 60);
+
+    // And round again after the second frame's own, shorter delay: 40ms, not
+    // another 80.
+    [view rnAdvanceImageAnimationBy:40];
+    EXPECT_EQ((int)view.rnImageFrameIndex, 0);
+    EXPECT(centreColour(view, size).red > 200);
+  }
+}
+
+TEST(animated_image_says_how_long_until_the_next_frame) {
+  @autoreleasepool {
+    RnAppKitView *view = animatedView(animatedGifFrames(), @[@80, @40], 0);
+
+    // What the host's timer is set to, which is why this is answered rather
+    // than kept private: at the start of frame one, the whole 80ms.
+    EXPECT_NEAR([view rnAdvanceImageAnimationBy:0], 80.0, 0.01);
+    EXPECT_NEAR([view rnAdvanceImageAnimationBy:30], 50.0, 0.01);
+    // Into frame two, which is 40ms long.
+    EXPECT_NEAR([view rnAdvanceImageAnimationBy:50], 40.0 - 0.0, 0.01);
+  }
+}
+
+TEST(animated_image_a_loop_count_stops_on_the_last_frame) {
+  @autoreleasepool {
+    RnAppKitView *view = animatedView(animatedGifFrames(), @[@80, @40], 1);
+    const CGSize size = CGSizeMake(20, 20);
+
+    // One pass is 120ms. After it the animation stops, on frame two, and says
+    // nothing more is due -- which is what stops the timer.
+    EXPECT_NEAR([view rnAdvanceImageAnimationBy:120], 0.0, 0.01);
+    EXPECT_EQ((int)view.rnImageFrameIndex, 1);
+    EXPECT(centreColour(view, size).blue > 200);
+
+    [view rnAdvanceImageAnimationBy:1000];
+    EXPECT_EQ((int)view.rnImageFrameIndex, 1);
+  }
+}
+
+TEST(animated_image_a_single_frame_is_a_still_image) {
+  @autoreleasepool {
+    NSArray *frames = animatedGifFrames();
+    RnAppKitView *view = animatedView(@[frames.firstObject], @[@80], 0);
+
+    EXPECT_NEAR([view rnAdvanceImageAnimationBy:500], 0.0, 0.01);
+    EXPECT_EQ((int)view.rnImageFrameIndex, 0);
+    EXPECT(![[view describeTree] containsString:@"animated=1"]);
+  }
+}
+
+// A re-mount must not restart the animation, which is the bug this shape of
+// mounting manager invites: every mutation that touches an <Image> re-applies
+// the first frame, a layout-only one included, so a spinner would stutter back
+// to the top on every resize.
+TEST(animated_image_survives_the_props_being_reapplied) {
+  @autoreleasepool {
+    NSArray *frames = animatedGifFrames();
+    RnAppKitView *view = animatedView(frames, @[@80, @40], 0);
+
+    [view rnAdvanceImageAnimationBy:100];
+    EXPECT_EQ((int)view.rnImageFrameIndex, 1);
+
+    // What the mounting manager does on a mutation: the first frame again, and
+    // the same arrays the loader cached.
+    [view setRnImage:(__bridge CGImageRef)frames.firstObject fit:RnAppKitImageFitStretch];
+    [view setRnImageFrames:frames delaysMs:@[@80, @40] loopCount:0];
+    EXPECT_EQ((int)view.rnImageFrameIndex, 1);
+    EXPECT(centreColour(view, CGSizeMake(20, 20)).blue > 200);
+
+    // A different animation does start over, which is the same check from the
+    // other side: the frames array is what tells them apart.
+    [view setRnImageFrames:animatedGifFrames() delaysMs:@[@80, @40] loopCount:0];
+    EXPECT_EQ((int)view.rnImageFrameIndex, 0);
+  }
+}
+
+TEST(animated_image_is_reported_in_the_tree) {
+  @autoreleasepool {
+    RnAppKitView *view = animatedView(animatedGifFrames(), @[@80, @40], 0);
+    EXPECT([[view describeTree] containsString:@"animated=1"]);
+
+    // Cleared with the frames, so an <Image> whose source becomes a still one
+    // does not keep claiming to move.
+    [view setRnImageFrames:nil delaysMs:nil loopCount:0];
+    EXPECT(![[view describeTree] containsString:@"animated=1"]);
+  }
+}