[runtime_image] Log a failed open from a source at debug level, as the caller may recover

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

esphome/components/runtime_image/__init__.py

@@ -92,7 +92,15 @@ class JPEGFormat(Format):
 
     def actions(self) -> None:
         cg.add_define("USE_RUNTIME_IMAGE_JPEG")
-        cg.add_library("JPEGDEC", "1.8.4", "https://github.com/bitbank2/JPEGDEC#1.8.4")
+        # 1.8.4 plus decodeBegin()/decodeRows(), so an image can be decoded a few rows at a time and
+        # can wait for input that has not arrived yet, and fixes for: input that arrives in short
+        # reads, garbled RGB8888 output of grayscale images, and two ARM NEON faults seen on arm64 hosts
+        # (swapped red and blue in the 4:2:0 RGB8888 path, writes past the row on clipped MCUs)
+        cg.add_library(
+            "JPEGDEC",
+            "1.8.4",
+            "https://github.com/esphome-libs/JPEGDEC#1.8.4-esphome.1",
+        )
         if CORE.is_host:
             # JPEGDEC's host detection checks __MACH__/__LINUX__, but gcc only
             # predefines the lowercase __linux__; without this a Linux host

esphome/components/runtime_image/image_decoder.h

@@ -1,4 +1,6 @@
 #pragma once
+#include <cstdint>
+
 #include "esphome/core/color.h"
 #include "image_format.h"
 
@@ -9,6 +11,14 @@ enum DecodeError : int {
   DECODE_ERROR_UNSUPPORTED_FORMAT = -2,
   DECODE_ERROR_OUT_OF_MEMORY = -3,
   DECODE_ERROR_INTERNAL_DECODER_ERROR = -4,
+  DECODE_ERROR_READ = -5,
+};
+
+/// Results of ImageDecoder::decode_step() other than a DecodeError
+enum DecodeStep : int {
+  DECODE_STEP_DONE = 0,
+  DECODE_STEP_MORE = 1,
+  DECODE_STEP_NEED_DATA = 2,  // The source has nothing more yet; call again once more has arrived
 };
 
 constexpr const char *decode_error_to_string(int error) {
@@ -21,6 +31,8 @@ constexpr const char *decode_error_to_string(int error) {
       return "Out of memory";
     case DECODE_ERROR_INTERNAL_DECODER_ERROR:
       return "Internal decoder error";
+    case DECODE_ERROR_READ:
+      return "Read error";
     default:
       return "Unknown error";
   }
@@ -28,6 +40,19 @@ constexpr const char *decode_error_to_string(int error) {
 
 class RuntimeImage;
 
+/// Input that a decoder reads itself as it goes, so the whole image never has to be in memory at once
+class DecodeSource {
+ public:
+  virtual ~DecodeSource() = default;
+  /**
+   * Read up to len bytes at the current position. Returns the number read, which is less than len, even 0, when
+   * no more has arrived yet or at the end of the input, or negative on error.
+   */
+  virtual int32_t read(uint8_t *buf, uint32_t len) = 0;
+  /// Move to a position counted from the start. Returns false on error.
+  virtual bool seek(uint32_t position) = 0;
+};
+
 /**
  * @brief Class to abstract decoding different image formats.
  */
@@ -88,6 +113,28 @@ class ImageDecoder {
    */
   virtual int decode(uint8_t *buffer, size_t size) = 0;
 
+  /// Whether this decoder can read a DecodeSource itself, a step at a time, instead of being fed data.
+  virtual bool supports_source() const { return false; }
+
+  /**
+   * @brief Start decoding from a source the decoder reads itself. Call after prepare(), in place of decode().
+   *
+   * The image headers (everything before the image data) must be readable from the source when this is called;
+   * only decode_step() can wait for more to arrive. The source must hold expected_size bytes in the end, and stay
+   * valid until the session ends.
+   * @return int 0 on success, or a {@see DecodeError} value.
+   */
+  virtual int begin_source(DecodeSource *source) { return DECODE_ERROR_UNSUPPORTED_FORMAT; }
+
+  /**
+   * @brief Decode a little more of an image started with begin_source(), keeping each call short.
+   *
+   * @return int DECODE_STEP_MORE while there is more to do, DECODE_STEP_NEED_DATA when the source has not
+   *             delivered enough to go on, DECODE_STEP_DONE when the image is complete, or a {@see DecodeError}
+   *             value.
+   */
+  virtual int decode_step() { return DECODE_ERROR_UNSUPPORTED_FORMAT; }
+
   /**
    * @brief Request the image to be resized once the actual dimensions are known.
    * Called by the callback functions, to be able to access the parent Image class.
@@ -118,6 +165,9 @@ class ImageDecoder {
    * This should be overridden by decoders that can detect completion
    * based on format-specific markers rather than byte counts.
    */
+  /// Bytes of the image the decoder has used so far
+  size_t get_decoded_bytes() const { return this->decoded_bytes_; }
+
   virtual bool is_finished() const {
     if (this->expected_size_ > 0) {
       return this->decoded_bytes_ >= this->expected_size_;

esphome/components/runtime_image/jpeg_decoder.cpp

@@ -135,13 +135,24 @@ int HOT JpegDecoder::decode(uint8_t *buffer, size_t size) {
     ESP_LOGE(TAG, "Could not open image for decoding: %d", this->jpeg_.getLastError());
     return DECODE_ERROR_INVALID_TYPE;
   }
+  const int err = this->start_();
+  if (err != 0)
+    return err;
+  if (!this->jpeg_.decode(0, 0, 0))
+    return this->fail_();
+  this->decoded_bytes_ = size;
+  this->jpeg_.close();
+  return size;
+}
+
+int JpegDecoder::start_() {
   auto jpeg_type = this->jpeg_.getJPEGType();
   if (jpeg_type == JPEG_MODE_INVALID) {
     ESP_LOGE(TAG, "Unsupported JPEG image");
     return DECODE_ERROR_INVALID_TYPE;
   } else if (jpeg_type == JPEG_MODE_PROGRESSIVE) {
     ESP_LOGE(TAG, "Progressive JPEG images not supported");
-    return DECODE_ERROR_INVALID_TYPE;
+    return DECODE_ERROR_UNSUPPORTED_FORMAT;
   }
   ESP_LOGD(TAG, "Image size: %d x %d, bpp: %d", this->jpeg_.getWidth(), this->jpeg_.getHeight(), this->jpeg_.getBpp());
 
@@ -160,26 +171,109 @@ int HOT JpegDecoder::decode(uint8_t *buffer, size_t size) {
   if (this->direct_rgb565_ && !this->prepare_rgb565_scaling_(this->jpeg_.getWidth(), this->jpeg_.getHeight())) {
     return DECODE_ERROR_OUT_OF_MEMORY;
   }
-  if (!this->jpeg_.decode(0, 0, 0)) {
-    auto error = this->jpeg_.getLastError();
-    ESP_LOGE(TAG, "Error while decoding: %d", error);
-    this->jpeg_.close();
-    switch (error) {
-      case JPEG_ERROR_MEMORY:
-        return DECODE_ERROR_OUT_OF_MEMORY;
-      case JPEG_UNSUPPORTED_FEATURE:
-        return DECODE_ERROR_UNSUPPORTED_FORMAT;
-      case JPEG_INVALID_FILE:
-      case JPEG_INVALID_PARAMETER:
-        return DECODE_ERROR_INVALID_TYPE;
-      case JPEG_DECODE_ERROR:
-      default:
-        return DECODE_ERROR_INTERNAL_DECODER_ERROR;
-    }
-  }
-  this->decoded_bytes_ = size;
+  return 0;
+}
+
+int JpegDecoder::fail_() {
+  const bool read_failed = this->source_ != nullptr && this->source_failed_;
+  const int error = this->jpeg_.getLastError();
   this->jpeg_.close();
-  return size;
+  this->source_ = nullptr;
+  if (read_failed) {
+    ESP_LOGE(TAG, "Reading the image failed");
+    return DECODE_ERROR_READ;
+  }
+  ESP_LOGE(TAG, "Error while decoding: %d", error);
+  switch (error) {
+    case JPEG_ERROR_MEMORY:
+      return DECODE_ERROR_OUT_OF_MEMORY;
+    case JPEG_UNSUPPORTED_FEATURE:
+      return DECODE_ERROR_UNSUPPORTED_FORMAT;
+    case JPEG_INVALID_FILE:
+    case JPEG_INVALID_PARAMETER:
+      return DECODE_ERROR_INVALID_TYPE;
+    case JPEG_DECODE_ERROR:
+    default:
+      return DECODE_ERROR_INTERNAL_DECODER_ERROR;
+  }
+}
+
+void JpegDecoder::reset() {
+  // A decode from a source that was given up part way still has the image open
+  if (this->source_ != nullptr) {
+    this->jpeg_.close();
+    this->source_ = nullptr;
+  }
+  ImageDecoder::reset();
+}
+
+int32_t JpegDecoder::source_read(JPEGFILE *file, uint8_t *buf, int32_t len) {
+  auto *decoder = static_cast<JpegDecoder *>(file->fHandle);
+  const int32_t n = decoder->source_->read(buf, len);
+  if (n < 0) {
+    // JPEGDEC has no way to report a failed read, so remember it and give it no data
+    decoder->source_failed_ = true;
+    return 0;
+  }
+  file->iPos += n;
+  return n;
+}
+
+int32_t JpegDecoder::source_seek(JPEGFILE *file, int32_t position) {
+  auto *decoder = static_cast<JpegDecoder *>(file->fHandle);
+  if (position < 0 || !decoder->source_->seek(position)) {
+    decoder->source_failed_ = true;
+    return file->iPos;
+  }
+  file->iPos = position;
+  return position;
+}
+
+int JpegDecoder::begin_source(DecodeSource *source) {
+  if (this->expected_size_ == 0 || this->expected_size_ > INT32_MAX) {
+    ESP_LOGE(TAG, "Image size %zu cannot be read from a source", this->expected_size_);
+    return DECODE_ERROR_INVALID_TYPE;
+  }
+  if (!source->seek(0)) {
+    ESP_LOGE(TAG, "Could not read the image");
+    return DECODE_ERROR_READ;
+  }
+  this->source_ = source;
+  this->source_failed_ = false;
+  if (!this->jpeg_.open(this, this->expected_size_, source_close, source_read, source_seek, draw_callback)) {
+    // The caller may recover, for example by reading the whole image first, so it reports the failure
+    ESP_LOGD(TAG, "Could not open image for decoding: %d", this->jpeg_.getLastError());
+    this->source_ = nullptr;
+    return this->source_failed_ ? DECODE_ERROR_READ : DECODE_ERROR_INVALID_TYPE;
+  }
+  const int err = this->start_();
+  if (err != 0) {
+    this->jpeg_.close();
+    this->source_ = nullptr;
+    return err;
+  }
+  if (!this->jpeg_.decodeBegin(0, 0, 0))
+    return this->fail_();
+  return 0;
+}
+
+int HOT JpegDecoder::decode_step() {
+  if (this->source_ == nullptr)
+    return DECODE_ERROR_INVALID_TYPE;
+  const int result = this->jpeg_.decodeRows(1);
+  // JPEGDEC may decode on with the missing data, so check the read before its result
+  if (this->source_failed_)
+    return this->fail_();
+  if (result == JPEG_DECODE_MORE)
+    return DECODE_STEP_MORE;
+  if (result == JPEG_DECODE_NEED_DATA)
+    return DECODE_STEP_NEED_DATA;
+  if (result == 0)
+    return this->fail_();
+  this->decoded_bytes_ = this->expected_size_;
+  this->jpeg_.close();
+  this->source_ = nullptr;
+  return DECODE_STEP_DONE;
 }
 
 }  // namespace esphome::runtime_image

esphome/components/runtime_image/jpeg_decoder.h

@@ -22,19 +22,36 @@ class JpegDecoder : public ImageDecoder {
   ~JpegDecoder() override {}
 
   int HOT decode(uint8_t *buffer, size_t size) override;
+  void reset() override;
+
+  /// The source is read as the decode needs it, through JPEGDEC's own 2 KB buffer
+  bool supports_source() const override { return true; }
+  int begin_source(DecodeSource *source) override;
+  /// Decodes one row of MCUs (8 or 16 pixel rows), or waits part way through one for more of the source
+  int HOT decode_step() override;
 
   bool uses_direct_rgb565() const { return this->direct_rgb565_; }
   void draw_rgb565(int x, int y, int w, int h, const uint8_t *pixels);
 
  protected:
   bool prepare_rgb565_scaling_(int width, int height);
+  /// Set up an opened image for decoding. Returns 0, or a DecodeError.
+  int start_();
+  /// The DecodeError for a failed read of the source or JPEGDEC's last error, closing the image
+  int fail_();
+
+  static int32_t source_read(JPEGFILE *file, uint8_t *buf, int32_t len);
+  static int32_t source_seek(JPEGFILE *file, int32_t position);
+  static void source_close(void *handle) {}
 
   JPEGDEC jpeg_{};
   FixedVector<uint16_t> x_boundaries_{};
   FixedVector<uint16_t> y_boundaries_{};
   int source_width_{0};
   int source_height_{0};
+  DecodeSource *source_{nullptr};  // Set while a begin_source() decode is in progress
   bool direct_rgb565_{false};
+  bool source_failed_{false};
 };
 
 }  // namespace esphome::runtime_image

esphome/components/runtime_image/runtime_image.cpp

@@ -239,6 +239,25 @@ int RuntimeImage::feed_data(uint8_t *data, size_t len) {
   return consumed;
 }
 
+int RuntimeImage::begin_source(DecodeSource *source) {
+  if (!this->decoder_supports_source()) {
+    ESP_LOGE(TAG, "Decoder cannot read a source");
+    return DECODE_ERROR_UNSUPPORTED_FORMAT;
+  }
+  return this->decoder_->begin_source(source);
+}
+
+int RuntimeImage::decode_step() {
+  if (!this->is_decoding()) {
+    ESP_LOGE(TAG, "No decoder initialized");
+    return DECODE_ERROR_INVALID_TYPE;
+  }
+  const int result = this->decoder_->decode_step();
+  if (result == DECODE_STEP_DONE)
+    this->decoded_bytes_ = this->decoder_->get_decoded_bytes();
+  return result;
+}
+
 bool RuntimeImage::end_decode() {
   if (!this->is_decoding()) {
     return false;

esphome/components/runtime_image/runtime_image.h

@@ -76,6 +76,22 @@ class RuntimeImage : public image::Image {
    */
   int feed_data(uint8_t *data, size_t len);
 
+  /// Whether the active decoder can read a DecodeSource itself (see begin_source()).
+  bool decoder_supports_source() const { return this->is_decoding() && this->decoder_->supports_source(); }
+
+  /**
+   * @brief Decode from a source the decoder reads itself, in place of feed_data().
+   *
+   * Call after begin_decode() when decoder_supports_source() is true, once the image headers can be read from the
+   * source, then call decode_step() until it
+   * returns DECODE_STEP_DONE, and finish with end_decode().
+   * @return 0 on success, or a DecodeError value.
+   */
+  int begin_source(DecodeSource *source);
+
+  /// Decode a little more from the source; see ImageDecoder::decode_step().
+  int decode_step();
+
   /**
    * @brief Complete the decoding process.
    *

platformio.ini

@@ -48,7 +48,7 @@ lib_deps =
     improv/Improv@1.2.7                    ; improv_serial / improv_ble
     kikuchan98/pngle@1.1.0                 ; runtime_image
     ; Using the repository directly, otherwise ESP-IDF can't use the library
-    https://github.com/bitbank2/JPEGDEC.git#1.8.4    ; runtime_image
+    https://github.com/esphome-libs/JPEGDEC.git#1.8.4-esphome.1    ; runtime_image
     ; This dependency is used only in unit tests.
     ; Must coincide with PLATFORMIO_GOOGLE_TEST_LIB in scripts/cpp_unit_test.py
     ; See scripts/cpp_unit_test.py and tests/components/README.md
@@ -253,7 +253,7 @@ lib_deps =
     heman/AsyncMqttClient-esphome@2.0.0   ; mqtt
     improv/Improv@1.2.7                   ; improv_serial
     kikuchan98/pngle@1.1.0                ; runtime_image
-    https://github.com/bitbank2/JPEGDEC.git#1.8.4    ; runtime_image
+    https://github.com/esphome-libs/JPEGDEC.git#1.8.4-esphome.1    ; runtime_image
 build_flags =
     ${common:arduino.build_flags}
     -DUSE_LIBRETINY

tests/components/runtime_image/test_jpeg_grayscale.cpp

@@ -0,0 +1,83 @@
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <vector>
+
+#include "esphome/components/runtime_image/runtime_image.h"
+
+#ifdef USE_RUNTIME_IMAGE_JPEG
+
+namespace esphome::runtime_image::testing {
+
+// 16x8 grayscale JPEG (quality 95) of a smooth gradient, from 60 at the top left to 185 at the bottom right
+static const uint8_t JPEG_GRAY[] = {
+    0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 0x4A, 0x46, 0x49, 0x46, 0x00, 0x01, 0x01, 0x00, 0x00, 0x01, 0x00, 0x01, 0x00,
+    0x00, 0xFF, 0xDB, 0x00, 0x43, 0x00, 0x02, 0x01, 0x01, 0x01, 0x01, 0x01, 0x02, 0x01, 0x01, 0x01, 0x02, 0x02, 0x02,
+    0x02, 0x02, 0x04, 0x03, 0x02, 0x02, 0x02, 0x02, 0x05, 0x04, 0x04, 0x03, 0x04, 0x06, 0x05, 0x06, 0x06, 0x06, 0x05,
+    0x06, 0x06, 0x06, 0x07, 0x09, 0x08, 0x06, 0x07, 0x09, 0x07, 0x06, 0x06, 0x08, 0x0B, 0x08, 0x09, 0x0A, 0x0A, 0x0A,
+    0x0A, 0x0A, 0x06, 0x08, 0x0B, 0x0C, 0x0B, 0x0A, 0x0C, 0x09, 0x0A, 0x0A, 0x0A, 0xFF, 0xC0, 0x00, 0x0B, 0x08, 0x00,
+    0x08, 0x00, 0x10, 0x01, 0x01, 0x11, 0x00, 0xFF, 0xC4, 0x00, 0x1F, 0x00, 0x00, 0x01, 0x05, 0x01, 0x01, 0x01, 0x01,
+    0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09,
+    0x0A, 0x0B, 0xFF, 0xC4, 0x00, 0xB5, 0x10, 0x00, 0x02, 0x01, 0x03, 0x03, 0x02, 0x04, 0x03, 0x05, 0x05, 0x04, 0x04,
+    0x00, 0x00, 0x01, 0x7D, 0x01, 0x02, 0x03, 0x00, 0x04, 0x11, 0x05, 0x12, 0x21, 0x31, 0x41, 0x06, 0x13, 0x51, 0x61,
+    0x07, 0x22, 0x71, 0x14, 0x32, 0x81, 0x91, 0xA1, 0x08, 0x23, 0x42, 0xB1, 0xC1, 0x15, 0x52, 0xD1, 0xF0, 0x24, 0x33,
+    0x62, 0x72, 0x82, 0x09, 0x0A, 0x16, 0x17, 0x18, 0x19, 0x1A, 0x25, 0x26, 0x27, 0x28, 0x29, 0x2A, 0x34, 0x35, 0x36,
+    0x37, 0x38, 0x39, 0x3A, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48, 0x49, 0x4A, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59,
+    0x5A, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68, 0x69, 0x6A, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78, 0x79, 0x7A, 0x83, 0x84,
+    0x85, 0x86, 0x87, 0x88, 0x89, 0x8A, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9A, 0xA2, 0xA3, 0xA4, 0xA5,
+    0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xB2, 0xB3, 0xB4, 0xB5, 0xB6, 0xB7, 0xB8, 0xB9, 0xBA, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6,
+    0xC7, 0xC8, 0xC9, 0xCA, 0xD2, 0xD3, 0xD4, 0xD5, 0xD6, 0xD7, 0xD8, 0xD9, 0xDA, 0xE1, 0xE2, 0xE3, 0xE4, 0xE5, 0xE6,
+    0xE7, 0xE8, 0xE9, 0xEA, 0xF1, 0xF2, 0xF3, 0xF4, 0xF5, 0xF6, 0xF7, 0xF8, 0xF9, 0xFA, 0xFF, 0xDA, 0x00, 0x08, 0x01,
+    0x01, 0x00, 0x00, 0x3F, 0x00, 0xF0, 0x9F, 0x82, 0x5F, 0x09, 0x3F, 0xD4, 0xFF, 0x00, 0xA2, 0xFA, 0x76, 0xAF, 0xB0,
+    0x3E, 0x09, 0x7C, 0x24, 0xFF, 0x00, 0x53, 0xFE, 0x8B, 0xE9, 0xDA, 0xBF, 0xFF, 0xD9,
+};
+
+// The pixels Pillow decodes from it
+static const uint8_t JPEG_GRAY_PIXELS[8 * 16] = {
+    60,  66,  72,  78,  84,  90,  96,  102, 108, 114, 120, 126, 132, 138, 144, 150, 65,  71,  77,  83,  89,  95,
+    101, 107, 113, 119, 125, 131, 137, 143, 149, 155, 70,  76,  82,  88,  94,  100, 106, 112, 118, 124, 130, 136,
+    142, 148, 154, 160, 75,  81,  87,  93,  99,  105, 111, 117, 123, 129, 135, 141, 147, 153, 159, 165, 80,  86,
+    92,  98,  104, 110, 116, 122, 128, 134, 140, 146, 152, 158, 164, 170, 85,  91,  97,  103, 109, 115, 121, 127,
+    133, 139, 145, 151, 157, 163, 169, 175, 90,  96,  102, 108, 114, 120, 126, 132, 138, 144, 150, 156, 162, 168,
+    174, 180, 95,  101, 107, 113, 119, 125, 131, 137, 143, 149, 155, 161, 167, 173, 179, 185,
+};
+
+// JPEGDEC's faster inverse DCT is up to 4 steps from Pillow's on this image; the garbled output was off by hundreds
+static constexpr int TOLERANCE = 5;
+
+static bool decode(RuntimeImage &img) {
+  std::vector<uint8_t> data(JPEG_GRAY, JPEG_GRAY + sizeof(JPEG_GRAY));
+  if (!img.begin_decode(data.size()))
+    return false;
+  if (img.feed_data(data.data(), data.size()) != static_cast<int>(data.size()))
+    return false;
+  return img.end_decode();
+}
+
+// A grayscale JPEG decoded for a colour image goes through JPEGDEC's RGB8888 output, which used to be garbled
+TEST(JpegGrayscale, DecodesToRgb) {
+  RuntimeImage img(JPEG, image::IMAGE_TYPE_RGB, image::TRANSPARENCY_ALPHA_CHANNEL);
+  ASSERT_TRUE(decode(img));
+  ASSERT_EQ(img.get_width(), 16);
+  ASSERT_EQ(img.get_height(), 8);
+  const uint8_t *data = img.get_data_start();
+  for (int i = 0; i < 16 * 8; i++) {
+    const uint8_t *pixel = data + i * 4;  // blue, green, red, alpha
+    EXPECT_NEAR(pixel[0], JPEG_GRAY_PIXELS[i], TOLERANCE) << "blue of pixel " << i;
+    EXPECT_NEAR(pixel[1], JPEG_GRAY_PIXELS[i], TOLERANCE) << "green of pixel " << i;
+    EXPECT_NEAR(pixel[2], JPEG_GRAY_PIXELS[i], TOLERANCE) << "red of pixel " << i;
+    EXPECT_EQ(pixel[3], 255) << "alpha of pixel " << i;
+  }
+}
+
+TEST(JpegGrayscale, DecodesToGrayscale) {
+  RuntimeImage img(JPEG, image::IMAGE_TYPE_GRAYSCALE, image::TRANSPARENCY_OPAQUE);
+  ASSERT_TRUE(decode(img));
+  const uint8_t *data = img.get_data_start();
+  for (int i = 0; i < 16 * 8; i++)
+    EXPECT_NEAR(data[i], JPEG_GRAY_PIXELS[i], TOLERANCE) << "pixel " << i;
+}
+
+}  // namespace esphome::runtime_image::testing
+
+#endif  // USE_RUNTIME_IMAGE_JPEG

tests/components/runtime_image/test_jpeg_source.cpp

@@ -0,0 +1,434 @@
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <cstring>
+#include <vector>
+
+#include "esphome/components/runtime_image/image_decoder.h"
+#include "esphome/components/runtime_image/runtime_image.h"
+
+#ifdef USE_RUNTIME_IMAGE_JPEG
+
+namespace esphome::runtime_image::testing {
+
+// 48x40 4:2:0 JPEG of a noisy gradient (quality 95): three rows of 16 pixel MCUs, so a stepped decode takes
+// three steps. At 2344 bytes it is larger than JPEGDEC's 2048 byte read buffer, so the source is read again
+// part way through the image.
+static const uint8_t JPEG_ROWS[] = {
+    0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 0x4A, 0x46, 0x49, 0x46, 0x00, 0x01, 0x01, 0x00, 0x00, 0x01, 0x00, 0x01, 0x00,
+    0x00, 0xFF, 0xDB, 0x00, 0x43, 0x00, 0x02, 0x01, 0x01, 0x01, 0x01, 0x01, 0x02, 0x01, 0x01, 0x01, 0x02, 0x02, 0x02,
+    0x02, 0x02, 0x04, 0x03, 0x02, 0x02, 0x02, 0x02, 0x05, 0x04, 0x04, 0x03, 0x04, 0x06, 0x05, 0x06, 0x06, 0x06, 0x05,
+    0x06, 0x06, 0x06, 0x07, 0x09, 0x08, 0x06, 0x07, 0x09, 0x07, 0x06, 0x06, 0x08, 0x0B, 0x08, 0x09, 0x0A, 0x0A, 0x0A,
+    0x0A, 0x0A, 0x06, 0x08, 0x0B, 0x0C, 0x0B, 0x0A, 0x0C, 0x09, 0x0A, 0x0A, 0x0A, 0xFF, 0xDB, 0x00, 0x43, 0x01, 0x02,
+    0x02, 0x02, 0x02, 0x02, 0x02, 0x05, 0x03, 0x03, 0x05, 0x0A, 0x07, 0x06, 0x07, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A,
+    0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A,
+    0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A,
+    0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0x0A, 0xFF, 0xC0, 0x00, 0x11, 0x08, 0x00, 0x28, 0x00, 0x30, 0x03, 0x01, 0x22, 0x00,
+    0x02, 0x11, 0x01, 0x03, 0x11, 0x01, 0xFF, 0xC4, 0x00, 0x1F, 0x00, 0x00, 0x01, 0x05, 0x01, 0x01, 0x01, 0x01, 0x01,
+    0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A,
+    0x0B, 0xFF, 0xC4, 0x00, 0xB5, 0x10, 0x00, 0x02, 0x01, 0x03, 0x03, 0x02, 0x04, 0x03, 0x05, 0x05, 0x04, 0x04, 0x00,
+    0x00, 0x01, 0x7D, 0x01, 0x02, 0x03, 0x00, 0x04, 0x11, 0x05, 0x12, 0x21, 0x31, 0x41, 0x06, 0x13, 0x51, 0x61, 0x07,
+    0x22, 0x71, 0x14, 0x32, 0x81, 0x91, 0xA1, 0x08, 0x23, 0x42, 0xB1, 0xC1, 0x15, 0x52, 0xD1, 0xF0, 0x24, 0x33, 0x62,
+    0x72, 0x82, 0x09, 0x0A, 0x16, 0x17, 0x18, 0x19, 0x1A, 0x25, 0x26, 0x27, 0x28, 0x29, 0x2A, 0x34, 0x35, 0x36, 0x37,
+    0x38, 0x39, 0x3A, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48, 0x49, 0x4A, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, 0x5A,
+    0x63, 0x64, 0x65, 0x66, 0x67, 0x68, 0x69, 0x6A, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78, 0x79, 0x7A, 0x83, 0x84, 0x85,
+    0x86, 0x87, 0x88, 0x89, 0x8A, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9A, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6,
+    0xA7, 0xA8, 0xA9, 0xAA, 0xB2, 0xB3, 0xB4, 0xB5, 0xB6, 0xB7, 0xB8, 0xB9, 0xBA, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7,
+    0xC8, 0xC9, 0xCA, 0xD2, 0xD3, 0xD4, 0xD5, 0xD6, 0xD7, 0xD8, 0xD9, 0xDA, 0xE1, 0xE2, 0xE3, 0xE4, 0xE5, 0xE6, 0xE7,
+    0xE8, 0xE9, 0xEA, 0xF1, 0xF2, 0xF3, 0xF4, 0xF5, 0xF6, 0xF7, 0xF8, 0xF9, 0xFA, 0xFF, 0xC4, 0x00, 0x1F, 0x01, 0x00,
+    0x03, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03,
+    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0xFF, 0xC4, 0x00, 0xB5, 0x11, 0x00, 0x02, 0x01, 0x02, 0x04, 0x04,
+    0x03, 0x04, 0x07, 0x05, 0x04, 0x04, 0x00, 0x01, 0x02, 0x77, 0x00, 0x01, 0x02, 0x03, 0x11, 0x04, 0x05, 0x21, 0x31,
+    0x06, 0x12, 0x41, 0x51, 0x07, 0x61, 0x71, 0x13, 0x22, 0x32, 0x81, 0x08, 0x14, 0x42, 0x91, 0xA1, 0xB1, 0xC1, 0x09,
+    0x23, 0x33, 0x52, 0xF0, 0x15, 0x62, 0x72, 0xD1, 0x0A, 0x16, 0x24, 0x34, 0xE1, 0x25, 0xF1, 0x17, 0x18, 0x19, 0x1A,
+    0x26, 0x27, 0x28, 0x29, 0x2A, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3A, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48, 0x49, 0x4A,
+    0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, 0x5A, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68, 0x69, 0x6A, 0x73, 0x74, 0x75,
+    0x76, 0x77, 0x78, 0x79, 0x7A, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8A, 0x92, 0x93, 0x94, 0x95, 0x96,
+    0x97, 0x98, 0x99, 0x9A, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xB2, 0xB3, 0xB4, 0xB5, 0xB6, 0xB7,
+    0xB8, 0xB9, 0xBA, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, 0xCA, 0xD2, 0xD3, 0xD4, 0xD5, 0xD6, 0xD7, 0xD8,
+    0xD9, 0xDA, 0xE2, 0xE3, 0xE4, 0xE5, 0xE6, 0xE7, 0xE8, 0xE9, 0xEA, 0xF2, 0xF3, 0xF4, 0xF5, 0xF6, 0xF7, 0xF8, 0xF9,
+    0xFA, 0xFF, 0xDA, 0x00, 0x0C, 0x03, 0x01, 0x00, 0x02, 0x11, 0x03, 0x11, 0x00, 0x3F, 0x00, 0xFC, 0xAA, 0xB8, 0xB7,
+    0xD3, 0xB5, 0xD8, 0x1E, 0xD6, 0xD1, 0xA5, 0x5B, 0x4B, 0x46, 0x10, 0xC1, 0x06, 0xA1, 0x29, 0x69, 0x25, 0xB7, 0xC2,
+    0xC6, 0x0C, 0x71, 0x26, 0x5E, 0x50, 0x15, 0x5D, 0xB6, 0x9C, 0x9E, 0x00, 0xC1, 0x67, 0x67, 0x4D, 0xCF, 0x84, 0xF7,
+    0x57, 0xA6, 0xDA, 0x08, 0x52, 0xF5, 0xE5, 0xBA, 0xB8, 0x7B, 0x5B, 0x68, 0xEE, 0x2F, 0x66, 0x89, 0xB7, 0xB7, 0x9B,
+    0xE5, 0x9C, 0x23, 0xAA, 0xFE, 0xF7, 0x68, 0x11, 0x9E, 0x5D, 0x18, 0x12, 0x48, 0x56, 0x5C, 0x9F, 0x57, 0xB6, 0xF8,
+    0x33, 0xF0, 0xE2, 0x5B, 0xFB, 0xCF, 0xF4, 0x51, 0x0C, 0xC6, 0x64, 0x30, 0x49, 0x71, 0x7C, 0xE2, 0x16, 0x90, 0x2E,
+    0xF4, 0x72, 0xEA, 0xE0, 0x34, 0x81, 0x77, 0x93, 0x9C, 0x07, 0xC2, 0x93, 0xB9, 0x61, 0xC0, 0xD3, 0xF0, 0x17, 0xC1,
+    0xBF, 0x03, 0xCD, 0xE1, 0xAD, 0x42, 0x3F, 0x0A, 0xD8, 0xC7, 0x2D, 0xAC, 0x36, 0xCB, 0xF6, 0x79, 0x22, 0x69, 0x84,
+    0xC4, 0x93, 0x29, 0x2A, 0x89, 0xB9, 0x00, 0x50, 0x62, 0x7C, 0xFF, 0x00, 0x16, 0xD9, 0x65, 0x00, 0x16, 0x65, 0x07,
+    0xFA, 0x5B, 0x36, 0xE2, 0xAC, 0xBF, 0x2D, 0x55, 0x79, 0x29, 0xB5, 0x26, 0x9B, 0xA9, 0x18, 0xB5, 0x15, 0x36, 0x9B,
+    0x53, 0xD1, 0xCA, 0x10, 0x93, 0x69, 0xB6, 0x94, 0x27, 0x16, 0xAF, 0x19, 0x29, 0xB8, 0xBB, 0x3F, 0x9A, 0xE1, 0x1E,
+    0x2A, 0xCB, 0x9E, 0x79, 0x4A, 0x92, 0x84, 0xDA, 0xD6, 0xED, 0xA4, 0xED, 0x7A, 0x72, 0xB5, 0xAC, 0xF6, 0xEB, 0xAD,
+    0xD5, 0x97, 0x91, 0xC9, 0x4D, 0xA4, 0xE9, 0xD7, 0x56, 0x45, 0x66, 0xD3, 0x9D, 0x85, 0xB1, 0x86, 0x59, 0x7E, 0xD9,
+    0x7E, 0xA0, 0xE0, 0xA8, 0x02, 0x17, 0x02, 0x3C, 0x36, 0x59, 0x18, 0xE2, 0x42, 0x1D, 0x40, 0x56, 0x0A, 0x77, 0x30,
+    0xAE, 0xFA, 0x56, 0xD4, 0xA4, 0x8A, 0xD9, 0xAD, 0xD6, 0x38, 0x1D, 0x7F, 0x77, 0x77, 0x1C, 0xB2, 0x4C, 0x22, 0x8C,
+    0x2B, 0xF3, 0x14, 0x64, 0x45, 0x85, 0x52, 0x47, 0x92, 0x7E, 0xF2, 0x0F, 0x34, 0x1D, 0xBC, 0x56, 0xDE, 0x85, 0xF0,
+    0x4B, 0xE1, 0x0A, 0xE9, 0xB0, 0xDB, 0x2D, 0x8C, 0x4C, 0xCD, 0x74, 0xF1, 0x42, 0x96, 0x93, 0xCF, 0xF6, 0x54, 0x0C,
+    0xB3, 0x44, 0x03, 0xAA, 0x6C, 0x49, 0x10, 0x87, 0x00, 0x88, 0xC2, 0xEE, 0x66, 0x6F, 0x9B, 0xAB, 0x57, 0xA4, 0x68,
+    0xDF, 0x0A, 0x3E, 0x1B, 0xDA, 0xE9, 0xDF, 0xD9, 0x96, 0xFE, 0x03, 0xB2, 0x8E, 0xD9, 0x8A, 0xDD, 0xC1, 0x77, 0x14,
+    0x97, 0x50, 0x2E, 0xE3, 0x20, 0x62, 0xA0, 0x33, 0x0C, 0xC6, 0x58, 0x48, 0x36, 0x6D, 0xC1, 0x20, 0xA2, 0x2B, 0x00,
+    0xB5, 0xF1, 0x99, 0xCF, 0x19, 0x65, 0x79, 0xAD, 0x0C, 0x3C, 0x2B, 0x61, 0xF9, 0x28, 0xD6, 0x52, 0x97, 0x35, 0x95,
+    0xD4, 0x61, 0x28, 0x5B, 0x99, 0xB8, 0xA9, 0xA9, 0x47, 0xD9, 0x3A, 0x69, 0xA9, 0xC6, 0x51, 0x52, 0x6A, 0x0D, 0x4A,
+    0x74, 0xA9, 0xC3, 0xFA, 0x7F, 0xC3, 0xFE, 0x25, 0xC1, 0x4E, 0xAE, 0x26, 0x2E, 0x13, 0x71, 0x5C, 0x8D, 0xFB, 0xB1,
+    0xD6, 0xEA, 0x6F, 0xF9, 0xAF, 0xBE, 0xB7, 0x4B, 0x55, 0x1D, 0x75, 0x4C, 0xF3, 0xDF, 0x05, 0xD9, 0xF8, 0x7B, 0xC3,
+    0xBA, 0xB5, 0xF1, 0xBC, 0x8D, 0x63, 0xDF, 0x1C, 0x32, 0x88, 0x1A, 0xF3, 0x74, 0x73, 0x89, 0x15, 0xC4, 0x8A, 0x25,
+    0x66, 0xDC, 0xAA, 0x98, 0x60, 0x06, 0x7F, 0xBD, 0xF2, 0x81, 0xF3, 0x36, 0xFE, 0x9D, 0xAF, 0x78, 0x8F, 0x54, 0xD3,
+    0xAD, 0xA6, 0x9E, 0xC5, 0xE5, 0x9C, 0x96, 0xDC, 0xB7, 0xE8, 0x84, 0x47, 0xFB, 0xB4, 0x54, 0x42, 0x0F, 0x03, 0xF8,
+    0xD7, 0xE5, 0x39, 0x60, 0xF8, 0x04, 0x79, 0x7B, 0xE3, 0xF4, 0x9F, 0x85, 0x5F, 0x08, 0xBE, 0x0D, 0x2C, 0x57, 0xCE,
+    0x6C, 0xA5, 0x2B, 0xA8, 0x08, 0x20, 0x82, 0x04, 0xB9, 0xB8, 0x82, 0x43, 0x28, 0x72, 0x55, 0xD5, 0x83, 0xB9, 0x05,
+    0xC2, 0x44, 0x55, 0x77, 0x8C, 0xFC, 0xEC, 0xD8, 0xCB, 0xE7, 0xBE, 0x9B, 0xE0, 0x5F, 0xC3, 0x9D, 0x32, 0xD4, 0x45,
+    0x26, 0x8B, 0x2C, 0x93, 0xC0, 0xF3, 0x95, 0x49, 0xEE, 0x2E, 0x0C, 0x26, 0x26, 0x31, 0xC9, 0xF3, 0xED, 0x95, 0x96,
+    0x32, 0xEC, 0x10, 0xE1, 0xB8, 0x60, 0x3A, 0x90, 0x1B, 0x3F, 0x9E, 0x66, 0x58, 0xFC, 0x14, 0x31, 0x15, 0xFD, 0x9C,
+    0x79, 0x57, 0x3A, 0x92, 0x84, 0x1C, 0x3D, 0xC9, 0xCD, 0x27, 0x6D, 0x12, 0xE5, 0xE7, 0xA6, 0xD5, 0x4D, 0x64, 0x93,
+    0xD1, 0x45, 0xC6, 0xAD, 0xE7, 0x2F, 0xE9, 0xEE, 0x17, 0xE3, 0x0C, 0x0A, 0xE1, 0x9C, 0x37, 0x34, 0x67, 0x2B, 0x73,
+    0x2B, 0xB4, 0xBA, 0x49, 0xF4, 0x72, 0x57, 0x51, 0xDD, 0x24, 0x9B, 0x5A, 0x36, 0x9A, 0x49, 0x1E, 0x15, 0xA7, 0x7E,
+    0xCE, 0xF6, 0x89, 0x6A, 0x96, 0x43, 0x55, 0xB5, 0xB3, 0xB6, 0xB8, 0x96, 0x2B, 0x9B, 0x78, 0xA0, 0xB4, 0x9E, 0xE5,
+    0x61, 0x90, 0xE0, 0xC2, 0xEC, 0x61, 0x91, 0x47, 0xCC, 0xDB, 0xF1, 0x80, 0xC0, 0x98, 0xD4, 0xE5, 0xDC, 0x64, 0xEC,
+    0x7C, 0x29, 0xFD, 0x98, 0x6C, 0xAF, 0xEC, 0xF5, 0x76, 0xB7, 0xF1, 0x36, 0x9A, 0x5D, 0x6F, 0x96, 0xE1, 0x74, 0xB5,
+    0xD3, 0x44, 0x91, 0xA8, 0x45, 0x0C, 0xE2, 0x3D, 0xAC, 0x85, 0xF9, 0x3B, 0x5B, 0x19, 0x8A, 0x43, 0x1F, 0xCA, 0x50,
+    0x9D, 0x87, 0xD2, 0x0F, 0xC2, 0x1F, 0x89, 0x4F, 0x6D, 0x04, 0x0F, 0xE1, 0x61, 0xAA, 0xEE, 0xB4, 0x8E, 0x56, 0xFB,
+    0x06, 0xAF, 0x04, 0xF3, 0x40, 0x9B, 0x55, 0x4E, 0xCB, 0x66, 0x91, 0xCB, 0x18, 0xC2, 0x88, 0xB6, 0xB1, 0x65, 0x60,
+    0xA4, 0x6E, 0xDC, 0xA4, 0x9E, 0xAF, 0xE1, 0xBF, 0xC2, 0x2F, 0x89, 0xA9, 0xE1, 0xFB, 0x8D, 0x6E, 0xC2, 0x3B, 0x4B,
+    0x30, 0xD7, 0x60, 0xDA, 0x41, 0x2D, 0xCC, 0x6C, 0x2E, 0x49, 0xF3, 0x1E, 0x42, 0x19, 0x5D, 0x58, 0x3C, 0x8A, 0x81,
+    0x82, 0xB8, 0x0C, 0xC9, 0xF2, 0xE5, 0x8F, 0x03, 0x8F, 0x36, 0xE3, 0x8A, 0x98, 0xCC, 0x14, 0xAB, 0x62, 0x2B, 0xC2,
+    0x34, 0xA2, 0xA5, 0x78, 0x37, 0x42, 0x12, 0x70, 0x8C, 0x62, 0xD2, 0x6D, 0x72, 0x7B, 0xAF, 0x9B, 0xDD, 0xFD, 0xE5,
+    0x4E, 0x79, 0x49, 0x45, 0x73, 0xA9, 0x72, 0x2F, 0xF0, 0x73, 0x83, 0xF8, 0xCE, 0xB4, 0x33, 0xE8, 0x3F, 0xAE, 0x42,
+    0xF7, 0x76, 0xB3, 0x83, 0x57, 0xE5, 0x95, 0xBE, 0xCE, 0x8F, 0x7B, 0xDE, 0xD7, 0x4B, 0x6B, 0x9C, 0x1E, 0x8D, 0xF0,
+    0x56, 0x7B, 0xDD, 0x26, 0x34, 0x5F, 0x1F, 0xDB, 0x9D, 0x37, 0x53, 0xB8, 0x96, 0xED, 0xA0, 0x16, 0xB1, 0xC9, 0x2C,
+    0x8B, 0xF2, 0x26, 0x58, 0x89, 0x37, 0xEE, 0x04, 0xB2, 0x97, 0x54, 0x2D, 0x88, 0xC0, 0x60, 0x0B, 0x03, 0x5E, 0x9B,
+    0x67, 0xFB, 0x36, 0xE9, 0x31, 0x2D, 0x9C, 0x37, 0x9E, 0x32, 0x84, 0x5D, 0x2C, 0x4A, 0xD6, 0xAD, 0x73, 0x63, 0x28,
+    0x36, 0xAA, 0x53, 0xF7, 0x90, 0x29, 0x8E, 0x5C, 0x92, 0xBE, 0x41, 0xDC, 0xC0, 0xB3, 0x2B, 0x46, 0x32, 0x4B, 0x96,
+    0x35, 0xAD, 0x1F, 0xC2, 0xDF, 0x89, 0x17, 0xF6, 0xB6, 0xFA, 0xB5, 0xED, 0xB8, 0xB7, 0x8E, 0x78, 0x66, 0x96, 0x09,
+    0x6C, 0x6E, 0x23, 0x32, 0x28, 0x08, 0xE8, 0xF2, 0xBA, 0xF9, 0x86, 0x48, 0xC0, 0x68, 0xFE, 0x63, 0xC8, 0x23, 0x82,
+    0xCC, 0xA5, 0x4A, 0xFA, 0x66, 0x8F, 0xF0, 0x37, 0xE2, 0x6D, 0xE5, 0xC9, 0x3A, 0x87, 0x86, 0xB4, 0xFB, 0x28, 0xAE,
+    0x61, 0x0F, 0x0B, 0x59, 0xDF, 0xC0, 0xD1, 0xAC, 0xE0, 0x24, 0x41, 0x42, 0xC4, 0x49, 0x1B, 0x10, 0x21, 0x50, 0xC0,
+    0x09, 0x11, 0x8B, 0xEE, 0x6E, 0x71, 0xE2, 0xE2, 0x78, 0xBB, 0x33, 0xFA, 0xC5, 0x1A, 0xB4, 0xEA, 0xC6, 0x74, 0xD2,
+    0x8C, 0x24, 0xA5, 0x2A, 0x3C, 0xB5, 0x2E, 0xB9, 0x9B, 0x71, 0x97, 0x34, 0xE0, 0xAA, 0x54, 0x93, 0x71, 0x56, 0x49,
+    0xB9, 0xC6, 0x4E, 0x9A, 0x9B, 0xD3, 0xFA, 0x7F, 0x81, 0xB8, 0xD6, 0xAC, 0xDD, 0x6F, 0x65, 0x8D, 0x82, 0x77, 0x85,
+    0x95, 0xE1, 0x7D, 0x1C, 0xD2, 0x8B, 0x7A, 0x27, 0xA2, 0xF4, 0xED, 0xEE, 0x9E, 0x67, 0xE0, 0x8F, 0x81, 0x37, 0xBA,
+    0xEF, 0x87, 0x67, 0xBF, 0x8F, 0xC4, 0xD2, 0xDD, 0x4F, 0x05, 0xA8, 0x61, 0x7B, 0x1E, 0x9E, 0xE1, 0x8C, 0xEA, 0xF3,
+    0x18, 0x99, 0xA3, 0xDE, 0x76, 0x66, 0x36, 0x2A, 0x30, 0xFB, 0x9B, 0x0F, 0xC3, 0x1C, 0xA3, 0x76, 0x4B, 0xFB, 0x3B,
+    0xE8, 0xBA, 0x66, 0xBF, 0x0E, 0x93, 0xFD, 0xAB, 0x23, 0xD9, 0xA5, 0xCE, 0x62, 0xF3, 0x34, 0xEB, 0x7F, 0x29, 0x0A,
+    0xA7, 0x04, 0x48, 0xF2, 0x79, 0x82, 0x42, 0x1D, 0x46, 0x4B, 0xA9, 0x1B, 0xD1, 0xBE, 0x52, 0x54, 0xD7, 0xA8, 0xF8,
+    0x33, 0xE1, 0xAF, 0xC4, 0xA8, 0x24, 0xD6, 0x6D, 0xED, 0xBC, 0x0A, 0xD3, 0x5A, 0x5C, 0xC4, 0xDF, 0x64, 0x17, 0x97,
+    0x36, 0xF0, 0x65, 0x52, 0x39, 0xD4, 0x23, 0x22, 0x9D, 0xD8, 0x64, 0x83, 0x04, 0x85, 0x38, 0xEF, 0xB8, 0x49, 0x91,
+    0xBB, 0xFF, 0x00, 0x0A, 0xDF, 0xE3, 0x77, 0x84, 0xAC, 0xD3, 0x4A, 0xBC, 0xF0, 0x3A, 0x5A, 0x5B, 0x4F, 0x72, 0x5E,
+    0xD7, 0x53, 0x8E, 0xE2, 0x12, 0x6D, 0xC6, 0x40, 0x20, 0x47, 0xE6, 0x3E, 0x71, 0x26, 0x70, 0x24, 0xE4, 0xB4, 0x63,
+    0x2A, 0xC0, 0xE0, 0x7E, 0x71, 0x98, 0x71, 0x35, 0x5C, 0x4E, 0x69, 0x5A, 0xBD, 0x7C, 0x7A, 0x9C, 0xE3, 0xC9, 0xCF,
+    0x38, 0x46, 0x8D, 0xA4, 0xDC, 0x63, 0x38, 0x4A, 0xE9, 0xED, 0x5A, 0x4E, 0x4A, 0x6D, 0xF3, 0xCA, 0x2D, 0xB9, 0x4D,
+    0xD3, 0x77, 0x8C, 0x7F, 0xA8, 0xF8, 0x53, 0x8D, 0x31, 0x32, 0xC8, 0xA9, 0xDB, 0x15, 0x04, 0x9F, 0xB4, 0xD2, 0xF4,
+    0xD3, 0xF8, 0xA5, 0x77, 0xCD, 0xB3, 0x49, 0x6C, 0xB4, 0xEA, 0x97, 0x46, 0x78, 0x45, 0xC4, 0x16, 0x5A, 0xDD, 0xA5,
+    0xA6, 0x8D, 0xA7, 0xEA, 0x77, 0x4A, 0x54, 0x47, 0x3C, 0x31, 0x41, 0x20, 0x06, 0x68, 0x00, 0x9A, 0x4F, 0x2A, 0x40,
+    0x5D, 0x5F, 0x69, 0xF3, 0x15, 0xCB, 0x32, 0x96, 0xDC, 0xC0, 0x90, 0xA5, 0xF0, 0xBD, 0xAF, 0xC3, 0x96, 0x83, 0x51,
+    0xB8, 0xD6, 0xA7, 0x48, 0xD2, 0xE8, 0x2B, 0x2C, 0x2D, 0x6B, 0xF6, 0xA4, 0x55, 0x8E, 0x45, 0x5F, 0xBA, 0x54, 0x2A,
+    0x36, 0x77, 0x12, 0x72, 0xE5, 0x9C, 0x14, 0x3B, 0x63, 0x6C, 0x62, 0x8A, 0x2B, 0xDE, 0xCD, 0x70, 0x74, 0xA7, 0x92,
+    0xE2, 0x31, 0x35, 0x2D, 0x29, 0x54, 0xBB, 0x97, 0xBB, 0x18, 0xF3, 0x38, 0x52, 0xA5, 0x38, 0xDF, 0x92, 0x31, 0x7E,
+    0xEB, 0x9B, 0x6A, 0xCD, 0x6B, 0xEF, 0x7C, 0x6E, 0x52, 0x7F, 0xE1, 0xF7, 0x0E, 0x54, 0x96, 0x1B, 0x3D, 0x52, 0x86,
+    0xF0, 0x73, 0x4B, 0xEE, 0x92, 0xD6, 0xD6, 0xBF, 0xC2, 0x8D, 0x9F, 0x0B, 0xDE, 0xEB, 0xF3, 0x69, 0x6B, 0x06, 0x9B,
+    0xA9, 0x5B, 0xE9, 0xF6, 0x6F, 0x76, 0x1E, 0x45, 0x8E, 0xE1, 0x54, 0xC8, 0xCD, 0xF3, 0x28, 0x8B, 0x1C, 0x9E, 0x25,
+    0x55, 0xDA, 0xA5, 0x58, 0x80, 0xCA, 0x46, 0x42, 0xA8, 0xF4, 0x1B, 0xEB, 0xBB, 0xBB, 0x8B, 0x69, 0xAF, 0xA5, 0x8E,
+    0xD0, 0x49, 0x25, 0x9C, 0x37, 0x73, 0xE9, 0xD7, 0xF2, 0x14, 0x8E, 0x55, 0x91, 0x64, 0x90, 0x46, 0xA8, 0xF9, 0x50,
+    0x57, 0x73, 0x2E, 0xE0, 0x55, 0xF6, 0x87, 0x45, 0x20, 0x2E, 0xC7, 0x28, 0xAF, 0xCD, 0x78, 0xA6, 0xA5, 0x5C, 0x26,
+    0x33, 0x01, 0x35, 0x2E, 0x67, 0x52, 0x35, 0xA0, 0xEE, 0x93, 0x56, 0x70, 0x4F, 0x48, 0xDB, 0x95, 0x6B, 0x76, 0xF4,
+    0xB4, 0xA5, 0x27, 0x29, 0x29, 0x35, 0x16, 0xBF, 0xA8, 0x7C, 0x3E, 0x92, 0xF6, 0x98, 0xA8, 0x5B, 0x4B, 0xC5, 0xDB,
+    0x5E, 0x8E, 0x4F, 0x7D, 0xFA, 0xDB, 0x57, 0xB2, 0x56, 0xD6, 0xED, 0xF7, 0x3E, 0x10, 0xB2, 0x82, 0xF6, 0xC2, 0xF2,
+    0xF3, 0x4E, 0xD4, 0xAF, 0xEE, 0x5A, 0xCA, 0xCE, 0xD2, 0xF1, 0xA7, 0xB8, 0x9D, 0xD4, 0x42, 0x8C, 0xF2, 0x3C, 0x8E,
+    0x42, 0x02, 0x24, 0xFD, 0xDA, 0x96, 0x60, 0xAD, 0xB0, 0xC9, 0x0E, 0x00, 0xC8, 0xC8, 0xEA, 0xEE, 0x12, 0x7B, 0x09,
+    0x6C, 0x6E, 0xCE, 0xA2, 0x0B, 0xAA, 0x32, 0xD9, 0xB9, 0x49, 0x66, 0xDF, 0x74, 0xCC, 0x31, 0x1B, 0xE4, 0xE6, 0x63,
+    0xF2, 0x91, 0x95, 0x42, 0x15, 0x8B, 0x7D, 0xE0, 0xAC, 0xB4, 0x51, 0x5F, 0x33, 0x3A, 0xD8, 0x8C, 0x46, 0x7A, 0x9C,
+    0xA6, 0xD7, 0x2C, 0x13, 0x49, 0x25, 0x6E, 0x6A, 0x73, 0xE4, 0x84, 0x9E, 0x9A, 0xC9, 0x29, 0x24, 0x9E, 0xE9, 0x42,
+    0x11, 0x8D, 0xA2, 0x9C, 0x5F, 0xF5, 0x37, 0x0D, 0x36, 0xF8, 0x7E, 0x9A, 0xEC, 0xE5, 0xE5, 0x7E, 0x67, 0x77, 0x7B,
+    0x7A, 0xBF, 0x5E, 0xB7, 0x3F, 0xFF, 0xD9,
+};
+
+// 8x8 progressive JPEG, 521 bytes
+static const uint8_t JPEG_PROGRESSIVE[] = {
+    0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 0x4A, 0x46, 0x49, 0x46, 0x00, 0x01, 0x01, 0x00, 0x00, 0x01, 0x00, 0x01, 0x00,
+    0x00, 0xFF, 0xDB, 0x00, 0x43, 0x00, 0x10, 0x0B, 0x0C, 0x0E, 0x0C, 0x0A, 0x10, 0x0E, 0x0D, 0x0E, 0x12, 0x11, 0x10,
+    0x13, 0x18, 0x28, 0x1A, 0x18, 0x16, 0x16, 0x18, 0x31, 0x23, 0x25, 0x1D, 0x28, 0x3A, 0x33, 0x3D, 0x3C, 0x39, 0x33,
+    0x38, 0x37, 0x40, 0x48, 0x5C, 0x4E, 0x40, 0x44, 0x57, 0x45, 0x37, 0x38, 0x50, 0x6D, 0x51, 0x57, 0x5F, 0x62, 0x67,
+    0x68, 0x67, 0x3E, 0x4D, 0x71, 0x79, 0x70, 0x64, 0x78, 0x5C, 0x65, 0x67, 0x63, 0xFF, 0xDB, 0x00, 0x43, 0x01, 0x11,
+    0x12, 0x12, 0x18, 0x15, 0x18, 0x2F, 0x1A, 0x1A, 0x2F, 0x63, 0x42, 0x38, 0x42, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63,
+    0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63,
+    0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0x63,
+    0x63, 0x63, 0x63, 0x63, 0x63, 0x63, 0xFF, 0xC2, 0x00, 0x11, 0x08, 0x00, 0x08, 0x00, 0x08, 0x03, 0x01, 0x22, 0x00,
+    0x02, 0x11, 0x01, 0x03, 0x11, 0x01, 0xFF, 0xC4, 0x00, 0x15, 0x00, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x04, 0xFF, 0xC4, 0x00, 0x15, 0x01, 0x01, 0x01, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03, 0x05, 0xFF, 0xDA, 0x00, 0x0C, 0x03,
+    0x01, 0x00, 0x02, 0x10, 0x03, 0x10, 0x00, 0x00, 0x01, 0x94, 0x05, 0x3F, 0xFF, 0xC4, 0x00, 0x14, 0x10, 0x01, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xDA, 0x00, 0x08,
+    0x01, 0x01, 0x00, 0x01, 0x05, 0x02, 0x7F, 0xFF, 0xC4, 0x00, 0x14, 0x11, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xDA, 0x00, 0x08, 0x01, 0x03, 0x01, 0x01, 0x3F,
+    0x01, 0x7F, 0xFF, 0xC4, 0x00, 0x14, 0x11, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xDA, 0x00, 0x08, 0x01, 0x02, 0x01, 0x01, 0x3F, 0x01, 0x7F, 0xFF, 0xC4, 0x00,
+    0x14, 0x10, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0xFF, 0xDA, 0x00, 0x08, 0x01, 0x01, 0x00, 0x06, 0x3F, 0x02, 0x7F, 0xFF, 0xC4, 0x00, 0x14, 0x10, 0x01, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xDA, 0x00, 0x08, 0x01,
+    0x01, 0x00, 0x01, 0x3F, 0x21, 0x7F, 0xFF, 0xDA, 0x00, 0x0C, 0x03, 0x01, 0x00, 0x02, 0x00, 0x03, 0x00, 0x00, 0x00,
+    0x10, 0x0B, 0xFF, 0xC4, 0x00, 0x14, 0x11, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xDA, 0x00, 0x08, 0x01, 0x03, 0x01, 0x01, 0x3F, 0x10, 0x7F, 0xFF, 0xC4, 0x00,
+    0x14, 0x11, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0xFF, 0xDA, 0x00, 0x08, 0x01, 0x02, 0x01, 0x01, 0x3F, 0x10, 0x7F, 0xFF, 0xC4, 0x00, 0x14, 0x10, 0x01, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xDA, 0x00, 0x08, 0x01,
+    0x01, 0x00, 0x01, 0x3F, 0x10, 0x7F, 0xFF, 0xD9,
+};
+
+class SourceImage : public RuntimeImage {
+ public:
+  explicit SourceImage(image::ImageType type = image::IMAGE_TYPE_RGB, int width = 0, int height = 0)
+      : RuntimeImage(JPEG, type, image::TRANSPARENCY_OPAQUE, nullptr, false, width, height) {}
+  size_t decoded_bytes() const { return this->decoded_bytes_; }
+};
+
+/// The file in memory; fails reads once fail_at bytes have been read
+class MemorySource : public DecodeSource {
+ public:
+  MemorySource(const uint8_t *data, size_t size, size_t fail_at = SIZE_MAX)
+      : data_(data), size_(size), fail_at_(fail_at) {}
+  int32_t read(uint8_t *buf, uint32_t len) override {
+    if (this->pos_ >= this->fail_at_)
+      return -1;
+    const size_t n = std::min<size_t>(len, this->size_ - this->pos_);
+    memcpy(buf, this->data_ + this->pos_, n);
+    this->pos_ += n;
+    this->reads++;
+    return static_cast<int32_t>(n);
+  }
+  bool seek(uint32_t position) override {
+    if (position > this->size_)
+      return false;
+    this->pos_ = position;
+    return true;
+  }
+  int reads{0};
+
+ protected:
+  const uint8_t *data_;
+  size_t size_;
+  size_t pos_{0};
+  size_t fail_at_;
+};
+
+/// Hands out only the bytes delivered so far, like a download that is still arriving
+class TrickleSource : public DecodeSource {
+ public:
+  TrickleSource(const uint8_t *data, size_t size, size_t delivered) : data_(data), size_(size), delivered_(delivered) {}
+  int32_t read(uint8_t *buf, uint32_t len) override {
+    const size_t n = std::min<size_t>(len, this->delivered_ - this->pos_);
+    memcpy(buf, this->data_ + this->pos_, n);
+    this->pos_ += n;
+    return static_cast<int32_t>(n);
+  }
+  bool seek(uint32_t position) override {
+    if (position > this->delivered_)
+      return false;
+    this->pos_ = position;
+    return true;
+  }
+  void deliver(size_t len) { this->delivered_ = std::min(this->size_, this->delivered_ + len); }
+
+ protected:
+  const uint8_t *data_;
+  size_t size_;
+  size_t delivered_;
+  size_t pos_{0};
+};
+
+static bool decode_fed(RuntimeImage &img) {
+  std::vector<uint8_t> buffer(JPEG_ROWS, JPEG_ROWS + sizeof(JPEG_ROWS));
+  if (!img.begin_decode(buffer.size()))
+    return false;
+  if (img.feed_data(buffer.data(), buffer.size()) != static_cast<int>(buffer.size()))
+    return false;
+  return img.end_decode();
+}
+
+/// Decodes from a source a step at a time; returns the last result and counts the steps
+static int decode_stepped(RuntimeImage &img, DecodeSource &source, int &steps) {
+  steps = 0;
+  if (!img.begin_decode(sizeof(JPEG_ROWS)) || !img.decoder_supports_source())
+    return DECODE_ERROR_UNSUPPORTED_FORMAT;
+  int result = img.begin_source(&source);
+  if (result != 0)
+    return result;
+  do {
+    result = img.decode_step();
+    steps++;
+  } while (result == DECODE_STEP_MORE);
+  if (result == DECODE_STEP_DONE && !img.end_decode())
+    return DECODE_ERROR_INTERNAL_DECODER_ERROR;
+  return result;
+}
+
+static std::vector<uint8_t> pixels(const RuntimeImage &img) {
+  const uint8_t *start = img.get_data_start();
+  return std::vector<uint8_t>(start, start + img.get_width_stride() * img.get_height());
+}
+
+TEST(JpegSourceDecode, SteppedDecodeMatchesFedDecode) {
+  SourceImage fed;
+  ASSERT_TRUE(decode_fed(fed));
+
+  SourceImage stepped;
+  MemorySource source(JPEG_ROWS, sizeof(JPEG_ROWS));
+  int steps;
+  ASSERT_EQ(decode_stepped(stepped, source, steps), DECODE_STEP_DONE);
+  EXPECT_EQ(steps, 3);
+  ASSERT_EQ(stepped.get_width(), 48);
+  ASSERT_EQ(stepped.get_height(), 40);
+  EXPECT_EQ(pixels(stepped), pixels(fed));
+}
+
+TEST(JpegSourceDecode, SteppedDirectRgb565MatchesFedDecode) {
+  // A fixed size that is not a whole multiple of the source exercises the scaling tables across steps
+  SourceImage fed(image::IMAGE_TYPE_RGB565, 30, 25);
+  ASSERT_TRUE(decode_fed(fed));
+
+  SourceImage stepped(image::IMAGE_TYPE_RGB565, 30, 25);
+  MemorySource source(JPEG_ROWS, sizeof(JPEG_ROWS));
+  int steps;
+  ASSERT_EQ(decode_stepped(stepped, source, steps), DECODE_STEP_DONE);
+  EXPECT_EQ(pixels(stepped), pixels(fed));
+}
+
+TEST(JpegSourceDecode, WaitsForDataThatHasNotArrived) {
+  SourceImage fed;
+  ASSERT_TRUE(decode_fed(fed));
+
+  // Enough for the headers (the scan starts at byte 609), then 50 bytes between steps
+  SourceImage img;
+  TrickleSource source(JPEG_ROWS, sizeof(JPEG_ROWS), 700);
+  ASSERT_TRUE(img.begin_decode(sizeof(JPEG_ROWS)));
+  ASSERT_EQ(img.begin_source(&source), 0);
+  int waits = 0;
+  int result;
+  while ((result = img.decode_step()) == DECODE_STEP_MORE || result == DECODE_STEP_NEED_DATA) {
+    if (result == DECODE_STEP_NEED_DATA)
+      waits++;
+    source.deliver(50);
+    ASSERT_LT(waits, 1000);
+  }
+  ASSERT_EQ(result, DECODE_STEP_DONE);
+  ASSERT_TRUE(img.end_decode());
+  EXPECT_GT(waits, 0);
+  EXPECT_EQ(pixels(img), pixels(fed));
+}
+
+TEST(JpegSourceDecode, ImageIsHiddenUntilTheLastStep) {
+  SourceImage img;
+  MemorySource source(JPEG_ROWS, sizeof(JPEG_ROWS));
+  ASSERT_TRUE(img.begin_decode(sizeof(JPEG_ROWS)));
+  ASSERT_EQ(img.begin_source(&source), 0);
+  EXPECT_EQ(img.decode_step(), DECODE_STEP_MORE);
+  EXPECT_EQ(img.get_width(), 0);
+  EXPECT_EQ(img.get_data_start(), nullptr);
+}
+
+TEST(JpegSourceDecode, ReadFailureIsReportedAndTheDecoderRecovers) {
+  SourceImage img;
+  // The first read fills JPEGDEC's buffer, so the failure comes part way through the image data
+  MemorySource failing(JPEG_ROWS, sizeof(JPEG_ROWS), 2048);
+  int steps;
+  EXPECT_EQ(decode_stepped(img, failing, steps), DECODE_ERROR_READ);
+  EXPECT_GE(steps, 1);
+  img.release();
+
+  MemorySource source(JPEG_ROWS, sizeof(JPEG_ROWS));
+  EXPECT_EQ(decode_stepped(img, source, steps), DECODE_STEP_DONE);
+}
+
+TEST(JpegSourceDecode, ReleasePartWayThroughLetsTheNextDecodeStart) {
+  SourceImage img;
+  MemorySource first(JPEG_ROWS, sizeof(JPEG_ROWS));
+  ASSERT_TRUE(img.begin_decode(sizeof(JPEG_ROWS)));
+  ASSERT_EQ(img.begin_source(&first), 0);
+  ASSERT_EQ(img.decode_step(), DECODE_STEP_MORE);
+  img.release();
+  EXPECT_FALSE(img.is_decoding());
+
+  MemorySource second(JPEG_ROWS, sizeof(JPEG_ROWS));
+  int steps;
+  EXPECT_EQ(decode_stepped(img, second, steps), DECODE_STEP_DONE);
+  EXPECT_EQ(steps, 3);
+}
+
+TEST(JpegSourceDecode, FailedFirstReadIsAReadError) {
+  SourceImage img;
+  MemorySource failing(JPEG_ROWS, sizeof(JPEG_ROWS), 0);
+  ASSERT_TRUE(img.begin_decode(sizeof(JPEG_ROWS)));
+  EXPECT_EQ(img.begin_source(&failing), DECODE_ERROR_READ);
+}
+
+TEST(JpegSourceDecode, FailedSeekToTheStartIsAReadError) {
+  class NoSeekSource : public MemorySource {
+   public:
+    using MemorySource::MemorySource;
+    bool seek(uint32_t position) override { return false; }
+  };
+  SourceImage img;
+  NoSeekSource source(JPEG_ROWS, sizeof(JPEG_ROWS));
+  ASSERT_TRUE(img.begin_decode(sizeof(JPEG_ROWS)));
+  EXPECT_EQ(img.begin_source(&source), DECODE_ERROR_READ);
+  EXPECT_EQ(img.decode_step(), DECODE_ERROR_INVALID_TYPE);
+}
+
+TEST(JpegSourceDecode, ProgressiveImageIsUnsupported) {
+  SourceImage img;
+  MemorySource source(JPEG_PROGRESSIVE, sizeof(JPEG_PROGRESSIVE));
+  ASSERT_TRUE(img.begin_decode(sizeof(JPEG_PROGRESSIVE)));
+  EXPECT_EQ(img.begin_source(&source), DECODE_ERROR_UNSUPPORTED_FORMAT);
+  EXPECT_EQ(img.decode_step(), DECODE_ERROR_INVALID_TYPE);
+}
+
+TEST(JpegSourceDecode, CompletedDecodeCountsTheWholeImage) {
+  SourceImage img;
+  MemorySource source(JPEG_ROWS, sizeof(JPEG_ROWS));
+  ASSERT_TRUE(img.begin_decode(sizeof(JPEG_ROWS)));
+  ASSERT_EQ(img.begin_source(&source), 0);
+  int result;
+  while ((result = img.decode_step()) == DECODE_STEP_MORE) {
+    EXPECT_EQ(img.decoded_bytes(), 0u);
+  }
+  ASSERT_EQ(result, DECODE_STEP_DONE);
+  EXPECT_EQ(img.decoded_bytes(), sizeof(JPEG_ROWS));
+}
+
+TEST(JpegSourceDecode, SourceIsReadAsTheDecodeNeedsIt) {
+  SourceImage img;
+  MemorySource source(JPEG_ROWS, sizeof(JPEG_ROWS));
+  int steps;
+  ASSERT_EQ(decode_stepped(img, source, steps), DECODE_STEP_DONE);
+  EXPECT_GE(source.reads, 2);
+}
+
+TEST(JpegSourceDecode, DecodersThatCannotReadASourceSaySo) {
+  RuntimeImage img(BMP, image::IMAGE_TYPE_RGB, image::TRANSPARENCY_OPAQUE);
+  ASSERT_TRUE(img.begin_decode(100));
+  EXPECT_FALSE(img.decoder_supports_source());
+  MemorySource source(JPEG_ROWS, sizeof(JPEG_ROWS));
+  EXPECT_EQ(img.begin_source(&source), DECODE_ERROR_UNSUPPORTED_FORMAT);
+  EXPECT_EQ(img.decode_step(), DECODE_ERROR_UNSUPPORTED_FORMAT);
+}
+
+TEST(JpegSourceDecode, SourceNeedsTheImageSize) {
+  SourceImage img;
+  MemorySource source(JPEG_ROWS, sizeof(JPEG_ROWS));
+  // JPEGDEC needs the file size up front, and holds it in an int
+  ASSERT_TRUE(img.begin_decode(0));
+  EXPECT_EQ(img.begin_source(&source), DECODE_ERROR_INVALID_TYPE);
+  img.release();
+  ASSERT_TRUE(img.begin_decode(static_cast<size_t>(INT32_MAX) + 1));
+  EXPECT_EQ(img.begin_source(&source), DECODE_ERROR_INVALID_TYPE);
+}
+
+TEST(JpegSourceDecode, StepWithoutADecodeIsRefused) {
+  SourceImage img;
+  EXPECT_EQ(img.decode_step(), DECODE_ERROR_INVALID_TYPE);
+  ASSERT_TRUE(img.begin_decode(sizeof(JPEG_ROWS)));
+  // begin_source() was never called
+  EXPECT_EQ(img.decode_step(), DECODE_ERROR_INVALID_TYPE);
+}
+
+}  // namespace esphome::runtime_image::testing
+
+#endif  // USE_RUNTIME_IMAGE_JPEG