Merge remote-tracking branch 'origin/dev' into binary-sensor-lazy-integration-imports

# Conflicts: # esphome/core/entity_helpers.py
[cover] Pack the cover traits flags into one byte (#21339 )
2026-10-22 22:06:12 +00:00 · 2026-10-22 10:56:35 -10:00 · 2026-10-22 16:53:20 -04:00 · 2026-10-22 16:52:35 -04:00 · 2026-10-22 16:52:05 -04:00 · 2026-10-22 10:49:15 -10:00
60 changed files with 1291 additions and 1147 deletions
@@ -446,6 +446,8 @@ file does, and it is the authority when they disagree. The most useful starting
          switches = switch.sub_switches(config, parent=hub)
          await switches(CONF_BLUETOOTH, None, apply="set_bluetooth(state)", publish="after")
          ```
+          Restore an owned or standalone switch in `setup()` with `sw->restore()`, or `restore(default)`
+          to still drive a state when the restore mode is disabled.

        - **Other codegen helpers:** `uart.new_uart_component(config, *ctor_args)` (and `i2c.new_i2c_component`,
          `spi.new_spi_component`, `modbus.new_modbus_client_component`, `ble_client.new_ble_node_component`)
@@ -3,7 +3,6 @@ from logging import getLogger
 from esphome import automation, core
 from esphome.automation import maybe_simple_id
 import esphome.codegen as cg
-from esphome.components import mqtt, web_server, zigbee
 from esphome.components.const import CONF_ON_STATE_CHANGE
 from esphome.config_helpers import filter_source_files_from_defines
 import esphome.config_validation as cv
@@ -29,7 +28,6 @@ from esphome.const import (
    CONF_STATE,
    CONF_TIMING,
    CONF_TRIGGER_ID,
-    CONF_WEB_SERVER,
    DEVICE_CLASS_BATTERY,
    DEVICE_CLASS_BATTERY_CHARGING,
    DEVICE_CLASS_CARBON_MONOXIDE,
@@ -61,10 +59,12 @@ from esphome.const import (
    DEVICE_CLASS_VIBRATION,
    DEVICE_CLASS_WINDOW,
 )
-from esphome.core import CORE, ID, CoroPriority, coroutine_with_priority
+from esphome.core import CORE, ID, CoroPriority, coroutine_with_priority, entity_helpers
 from esphome.core.entity_helpers import (
    SubEntities,
    entity_duplicate_validator,
+    lazy_load_validator,
+    mqtt_component_class,
    queue_entity_register,
    setup_device_class,
    setup_entity,
@@ -433,14 +433,14 @@ def validate_publish_initial_state(value):


 _BINARY_SENSOR_SCHEMA = (
-    cv.ENTITY_BASE_SCHEMA.extend(web_server.WEBSERVER_SORTING_SCHEMA)
+    cv.ENTITY_BASE_SCHEMA.extend(entity_helpers.WEBSERVER_SORTING_SCHEMA)
    .extend(cv.MQTT_COMPONENT_SCHEMA)
-    .extend(zigbee.BINARY_SENSOR_SCHEMA)
+    .extend(entity_helpers.ZIGBEE_BINARY_SENSOR_SCHEMA)
    .extend(
        {
            cv.GenerateID(): cv.declare_id(BinarySensor),
            cv.OnlyWith(CONF_MQTT_ID, "mqtt"): cv.declare_id(
-                mqtt.MQTTBinarySensorComponent
+                mqtt_component_class("MQTTBinarySensorComponent")
            ),
            cv.Exclusive(
                CONF_PUBLISH_INITIAL_STATE, CONF_TRIGGER_ON_INITIAL_STATE
@@ -508,7 +508,7 @@ _BINARY_SENSOR_SCHEMA = (


 _BINARY_SENSOR_SCHEMA.add_extra(entity_duplicate_validator("binary_sensor"))
-_BINARY_SENSOR_SCHEMA.add_extra(zigbee.validate_binary_sensor)
+_BINARY_SENSOR_SCHEMA.add_extra(lazy_load_validator("zigbee", "validate_binary_sensor"))


 def binary_sensor_schema(
@@ -619,14 +619,12 @@ async def setup_binary_sensor_core_(var, config):

    CORE.add_job(_build_binary_sensor_automations, var, config)

-    if mqtt_id := config.get(CONF_MQTT_ID):
-        mqtt_ = cg.new_Pvariable(mqtt_id, var)
-        await mqtt.register_mqtt_component(mqtt_, config)
+    await entity_helpers.setup_entity_integrations(var, config)

-    if web_server_config := config.get(CONF_WEB_SERVER):
-        await web_server.add_entity_config(var, web_server_config)
+    if "zigbee" in CORE.loaded_integrations:
+        from esphome.components import zigbee

-    await zigbee.setup_binary_sensor(var, config)
+        await zigbee.setup_binary_sensor(var, config)


 async def register_binary_sensor(var, config):
@@ -8,10 +8,7 @@ ESPHOME_LOG_TAG(TAG, "copy.lock");
 void CopyLock::setup() {
  source_->add_on_state_callback([this](lock::LockState state) { this->publish_state(state); });

-  traits.set_assumed_state(source_->traits.get_assumed_state());
-  traits.set_requires_code(source_->traits.get_requires_code());
-  traits.set_supported_states_mask(source_->traits.get_supported_states_mask());
-  traits.set_supports_open(source_->traits.get_supports_open());
+  this->traits = this->source_->traits;

  this->publish_state(source_->state);
 }
@@ -1,31 +1,37 @@
 #pragma once

+#include <cstdint>
+
 namespace esphome::cover {

 class CoverTraits {
 public:
  CoverTraits() = default;

-  bool get_is_assumed_state() const { return this->is_assumed_state_; }
-  void set_is_assumed_state(bool is_assumed_state) { this->is_assumed_state_ = is_assumed_state; }
-  bool get_supports_position() const { return this->supports_position_; }
-  void set_supports_position(bool supports_position) { this->supports_position_ = supports_position; }
-  bool get_supports_tilt() const { return this->supports_tilt_; }
-  void set_supports_tilt(bool supports_tilt) { this->supports_tilt_ = supports_tilt; }
-  bool get_supports_toggle() const { return this->supports_toggle_; }
-  void set_supports_toggle(bool supports_toggle) { this->supports_toggle_ = supports_toggle; }
-  bool get_supports_stop() const { return this->supports_stop_; }
-  void set_supports_stop(bool supports_stop) { this->supports_stop_ = supports_stop; }
-  bool get_supports_stop_tilt() const { return this->supports_stop_tilt_; }
-  void set_supports_stop_tilt(bool supports_stop_tilt) { this->supports_stop_tilt_ = supports_stop_tilt; }
+  bool get_is_assumed_state() const { return this->flags_.is_assumed_state; }
+  void set_is_assumed_state(bool is_assumed_state) { this->flags_.is_assumed_state = is_assumed_state; }
+  bool get_supports_position() const { return this->flags_.supports_position; }
+  void set_supports_position(bool supports_position) { this->flags_.supports_position = supports_position; }
+  bool get_supports_tilt() const { return this->flags_.supports_tilt; }
+  void set_supports_tilt(bool supports_tilt) { this->flags_.supports_tilt = supports_tilt; }
+  bool get_supports_toggle() const { return this->flags_.supports_toggle; }
+  void set_supports_toggle(bool supports_toggle) { this->flags_.supports_toggle = supports_toggle; }
+  bool get_supports_stop() const { return this->flags_.supports_stop; }
+  void set_supports_stop(bool supports_stop) { this->flags_.supports_stop = supports_stop; }
+  bool get_supports_stop_tilt() const { return this->flags_.supports_stop_tilt; }
+  void set_supports_stop_tilt(bool supports_stop_tilt) { this->flags_.supports_stop_tilt = supports_stop_tilt; }

 protected:
-  bool is_assumed_state_{false};
-  bool supports_position_{false};
-  bool supports_tilt_{false};
-  bool supports_toggle_{false};
-  bool supports_stop_{false};
-  bool supports_stop_tilt_{false};
+  // Bit-packed flags to save memory (1 byte instead of 6)
+  struct CoverTraitFlags {
+    uint8_t is_assumed_state : 1;
+    uint8_t supports_position : 1;
+    uint8_t supports_tilt : 1;
+    uint8_t supports_toggle : 1;
+    uint8_t supports_stop : 1;
+    uint8_t supports_stop_tilt : 1;
+    uint8_t reserved : 2;
+  } flags_{};
 };

 }  // namespace esphome::cover
@@ -7,7 +7,6 @@ namespace esphome::deep_sleep {

 ESPHOME_LOG_TAG(TAG, "deep_sleep");

-#ifdef USE_DEEP_SLEEP_ON_WAKE
 WakeupCause get_wakeup_cause() {
  switch (lt_get_reboot_reason()) {
    case REBOOT_REASON_SLEEP_GPIO:
@@ -20,7 +19,6 @@ WakeupCause get_wakeup_cause() {
      return WAKEUP_CAUSE_NONE;
  }
 }
-#endif  // USE_DEEP_SLEEP_ON_WAKE

 optional<uint32_t> DeepSleepComponent::get_run_duration_() const { return this->run_duration_; }

@@ -60,8 +60,6 @@ struct WakeupCauseToRunDuration {

 #endif  // USE_ESP32

-#ifdef USE_DEEP_SLEEP_ON_WAKE
-
 /// Why the device woke from deep sleep. Passed to on_wake automations.
 enum WakeupCause : uint8_t {
  /// The device did not wake from deep sleep (for example a cold boot, reset or OTA restart).
@@ -79,6 +77,11 @@ enum WakeupCause : uint8_t {
 /// Return why the device woke from deep sleep. Implemented per platform.
 WakeupCause get_wakeup_cause();

+/// Return true when this boot is a wake from deep sleep.
+inline bool woke_from_deep_sleep() { return get_wakeup_cause() != WAKEUP_CAUSE_NONE; }
+
+#ifdef USE_DEEP_SLEEP_ON_WAKE
+
 /** Setup priority of on_wake triggers.
 *
 * Between restoring global variables (setup_priority::HARDWARE, 800) and on_boot automations at
@@ -30,7 +30,6 @@ namespace esphome::deep_sleep {

 ESPHOME_LOG_TAG(TAG, "deep_sleep");

-#ifdef USE_DEEP_SLEEP_ON_WAKE
 WakeupCause get_wakeup_cause() {
  switch (esp_sleep_get_wakeup_cause()) {
    case ESP_SLEEP_WAKEUP_EXT0:
@@ -47,7 +46,6 @@ WakeupCause get_wakeup_cause() {
      return WAKEUP_CAUSE_UNKNOWN;
  }
 }
-#endif  // USE_DEEP_SLEEP_ON_WAKE

 optional<uint32_t> DeepSleepComponent::get_run_duration_() const {
  if (this->wakeup_cause_to_run_duration_.has_value()) {
@@ -3,17 +3,14 @@

 #include <Esp.h>

-#ifdef USE_DEEP_SLEEP_ON_WAKE
 extern "C" {
 #include <user_interface.h>
 }
-#endif

 namespace esphome::deep_sleep {

 ESPHOME_LOG_TAG(TAG, "deep_sleep");

-#ifdef USE_DEEP_SLEEP_ON_WAKE
 WakeupCause get_wakeup_cause() {
  // The ESP8266 can only wake from deep sleep through the RTC timer (via GPIO16 -> RST).
  // NOLINTNEXTLINE(readability-static-accessed-through-instance)
@@ -22,7 +19,6 @@ WakeupCause get_wakeup_cause() {
  }
  return WAKEUP_CAUSE_NONE;
 }
-#endif  // USE_DEEP_SLEEP_ON_WAKE

 optional<uint32_t> DeepSleepComponent::get_run_duration_() const { return this->run_duration_; }

@@ -31,6 +31,9 @@ static bool wakeable_delay_feed_wdt(uint32_t ms) {
  return false;
 }

+// A wake from System OFF is not told apart from a reset yet.
+WakeupCause get_wakeup_cause() { return WAKEUP_CAUSE_NONE; }
+
 optional<uint32_t> DeepSleepComponent::get_run_duration_() const { return this->run_duration_; }

 void DeepSleepComponent::dump_config_platform_() {}
@@ -2213,6 +2213,22 @@ def idf_version() -> cv.Version:
    return CORE.data[KEY_ESP32][KEY_IDF_VERSION]


+def require_idf_version(
+    minimum: cv.Version, feature: str = "This feature"
+) -> Callable[[Any], Any]:
+    """Validator for an option that needs the underlying ESP-IDF at ``minimum`` or newer."""
+
+    def validator(value: Any) -> Any:
+        cv.only_on_esp32(value)
+        if (version := idf_version()) < minimum:
+            raise cv.Invalid(
+                f"{feature} requires ESP-IDF {minimum} or newer, got {version}"
+            )
+        return value
+
+    return validator
+
+
 def require_fatfs() -> None:
    """Mark that FATFS support is required by a component.

@@ -37,6 +37,7 @@ from esphome.const import (
 )
 from esphome.core import CORE, ID, CoroPriority, HexInt, coroutine_with_priority
 from esphome.core.entity_helpers import (
+    RESTORE_STATE_NONE,
    entity_duplicate_validator,
    queue_entity_register,
    setup_entity,
@@ -56,7 +57,6 @@ from .effects import (
 )
 from .restore_state import (
    LEGACY_RESTORE_MODES,
-    RESTORE_STATE_NONE,
    RESTORE_STATE_SCHEMA,
    _build_state_lambda,
    _initial_state_overridden_by_legacy_mode,
@@ -11,6 +11,14 @@ import esphome.codegen as cg
 import esphome.config_validation as cv
 from esphome.const import CONF_COLOR_MODE, CONF_STATE
 from esphome.core import Lambda
+from esphome.core.entity_helpers import (
+    RESTORE_STATE_INITIAL,
+    RESTORE_STATE_INVERT,
+    RESTORE_STATE_KEEP,
+    RESTORE_STATE_NONE,
+    restore_state_keyword,
+    restore_state_schema,
+)
 from esphome.cpp_generator import call_lambda
 from esphome.schema_extractors import SCHEMA_EXTRACT, schema_extractor
 from esphome.types import ConfigType
@@ -18,12 +26,6 @@ from esphome.types import ConfigType
 from .automation import LIGHT_STATE_FIELDS, validate_light_state
 from .types import ColorMode, LightStateRTCState

-RESTORE_STATE_KEEP = "KEEP"
-RESTORE_STATE_INVERT = "INVERT"
-RESTORE_STATE_INITIAL = "INITIAL"
-RESTORE_STATE_ALL = "ALL"
-RESTORE_STATE_NONE = "NONE"
-

@dataclass(frozen=True)
 class LegacyRestoreMode:
@@ -290,10 +292,12 @@ def _keep_or(validator: Callable[[Any], Any]) -> Callable[[Any], Any]:
            except cv.Invalid:
                inner = ()
            return (RESTORE_STATE_KEEP, RESTORE_STATE_INITIAL, *inner)
-        if isinstance(value, str):
-            upper = value.strip().upper()
-            if upper in (RESTORE_STATE_KEEP, RESTORE_STATE_INITIAL):
-                return upper
+        if (
+            keyword := restore_state_keyword(
+                value, (RESTORE_STATE_KEEP, RESTORE_STATE_INITIAL)
+            )
+        ) is not None:
+            return keyword
        return validator(value)

    return validate
@@ -308,10 +312,12 @@ def _validate_restore_state_state(value: Any) -> str | bool:
            RESTORE_STATE_INITIAL,
            *validate_light_state(SCHEMA_EXTRACT),
        )
-    if isinstance(value, str):
-        upper = value.strip().upper()
-        if upper in (RESTORE_STATE_KEEP, RESTORE_STATE_INVERT, RESTORE_STATE_INITIAL):
-            return upper
+    if (
+        keyword := restore_state_keyword(
+            value, (RESTORE_STATE_KEEP, RESTORE_STATE_INVERT, RESTORE_STATE_INITIAL)
+        )
+    ) is not None:
+        return keyword
    return validate_light_state(value)


@@ -327,19 +333,7 @@ _RESTORE_STATE_FIELDS_SCHEMA = cv.Schema(
 )


-@schema_extractor("schema")
-def RESTORE_STATE_SCHEMA(value: Any) -> ConfigType | str:
-    """
-    The restore_state: config key can be a mapping of per-field overrides, `all`, or `none`.
-    """
-    if value == SCHEMA_EXTRACT:
-        # The `all`/`none` string shorthands have no representation in the extracted
-        # docs schema; only the per-field mapping form is walked here.
-        return _RESTORE_STATE_FIELDS_SCHEMA
-    if isinstance(value, str):
-        upper = value.strip().upper()
-        if upper == RESTORE_STATE_ALL:
-            value = {}
-        elif upper == RESTORE_STATE_NONE:
-            return RESTORE_STATE_NONE
-    return _RESTORE_STATE_FIELDS_SCHEMA(value)
+# A mapping of per-field overrides, `all`, or `none`, which stays the keyword for to_code
+RESTORE_STATE_SCHEMA = restore_state_schema(
+    _RESTORE_STATE_FIELDS_SCHEMA, RESTORE_STATE_NONE
+)
@@ -35,12 +35,12 @@ class LockTraits {
 public:
  LockTraits() = default;

-  bool get_supports_open() const { return this->supports_open_; }
-  void set_supports_open(bool supports_open) { this->supports_open_ = supports_open; }
-  bool get_requires_code() const { return this->requires_code_; }
-  void set_requires_code(bool requires_code) { this->requires_code_ = requires_code; }
-  bool get_assumed_state() const { return this->assumed_state_; }
-  void set_assumed_state(bool assumed_state) { this->assumed_state_ = assumed_state; }
+  bool get_supports_open() const { return this->flags_.supports_open; }
+  void set_supports_open(bool supports_open) { this->flags_.supports_open = supports_open; }
+  bool get_requires_code() const { return this->flags_.requires_code; }
+  void set_requires_code(bool requires_code) { this->flags_.requires_code = requires_code; }
+  bool get_assumed_state() const { return this->flags_.assumed_state; }
+  void set_assumed_state(bool assumed_state) { this->flags_.assumed_state = assumed_state; }

  bool supports_state(LockState state) const { return supported_states_mask_ & (1 << state); }
  void set_supported_states(std::initializer_list<LockState> states) {
@@ -54,9 +54,13 @@ class LockTraits {
  void add_supported_state(LockState state) { supported_states_mask_ |= (1 << state); }

 protected:
-  bool supports_open_{false};
-  bool requires_code_{false};
-  bool assumed_state_{false};
+  // Bit-packed flags to save memory (1 byte instead of 3)
+  struct LockTraitFlags {
+    uint8_t supports_open : 1;
+    uint8_t requires_code : 1;
+    uint8_t assumed_state : 1;
+    uint8_t reserved : 5;
+  } flags_{};
  uint8_t supported_states_mask_{(1 << LOCK_STATE_NONE) | (1 << LOCK_STATE_LOCKED) | (1 << LOCK_STATE_UNLOCKED)};
 };

@@ -176,8 +180,8 @@ class Lock : public EntityBase {
   */
  virtual void control(const LockCall &call) = 0;

+  Deduplicator<LockState> publish_dedup_;  // packs with state and traits ahead of the pointer members
  LazyCallbackManager<void(LockState)> state_callback_{};
-  Deduplicator<LockState> publish_dedup_;
  ESPPreferenceObject rtc_;
 };

@@ -1,6 +1,5 @@
 #include "download_buffer.h"
 #include "esphome/core/log.h"
-#include <algorithm>
 #include <cstring>

 namespace esphome::online_image {
@@ -35,46 +34,6 @@ size_t DownloadBuffer::read(size_t len) {
  return this->unread_;
 }

-void DownloadSource::compact() {
-  if (this->keep_read_ || this->pos_ == this->start_)
-    return;
-  this->buffer_.read(this->pos_ - this->start_);
-  this->start_ = this->pos_;
-}
-
-int32_t DownloadSource::read(uint8_t *buf, uint32_t len) {
-  const size_t offset = this->pos_ - this->start_;
-  const size_t n = std::min<size_t>(len, this->buffer_.unread() - offset);
-  memcpy(buf, this->buffer_.data(offset), n);
-  this->pos_ += n;
-  return static_cast<int32_t>(n);
-}
-
-bool DownloadSource::seek(uint32_t position) {
-  // Only what is still in the buffer can be read again; a decoder never skips ahead of the download
-  if (position < this->start_ || position > this->start_ + this->buffer_.unread())
-    return false;
-  this->pos_ = position;
-  return true;
-}
-
-bool DownloadBuffer::grow(size_t size) {
-  if (this->size_ >= size)
-    return true;
-  RAMAllocator<uint8_t> allocator;
-  uint8_t *buffer = allocator.allocate(size);
-  if (buffer == nullptr) {
-    ESP_LOGE(TAG, "allocation of %zu bytes failed. Biggest block in heap: %zu Bytes", size,
-             allocator.get_max_free_block_size());
-    return false;
-  }
-  memcpy(buffer, this->buffer_, this->unread_);
-  allocator.deallocate(this->buffer_, this->size_);
-  this->buffer_ = buffer;
-  this->size_ = size;
-  return true;
-}
-
 size_t DownloadBuffer::resize(size_t size) {
  if (this->size_ >= size) {
    // Avoid useless reallocations; if the buffer is big enough, don't reallocate.
@@ -1,6 +1,5 @@
 #pragma once

-#include "esphome/components/runtime_image/image_decoder.h"
 #include "esphome/core/helpers.h"
 #include <cstddef>
 #include <cstdint>
@@ -36,8 +35,6 @@ class DownloadBuffer {

  void reset() { this->unread_ = 0; }
  size_t resize(size_t size);
-  /// Make the buffer at least size bytes, keeping the unread data. Returns false if the allocation failed.
-  bool grow(size_t size);

 protected:
  uint8_t *buffer_;
@@ -46,35 +43,4 @@ class DownloadBuffer {
  size_t unread_;
 };

-/**
- * @brief Lets a decoder read a download as it arrives, from the download buffer.
- *
- * The decoder reads at its own position in the buffer. Bytes it has read stay there until compact() drops
- * them, and compact() keeps everything while set_keep_read(true) is in effect, so the decoder can seek back
- * while it reads the headers.
- */
-class DownloadSource : public runtime_image::DecodeSource {
- public:
-  explicit DownloadSource(DownloadBuffer &buffer) : buffer_(buffer) {}
-
-  /// Start again at the beginning of a new download, keeping what is read
-  void reset() {
-    this->start_ = 0;
-    this->pos_ = 0;
-    this->keep_read_ = true;
-  }
-  void set_keep_read(bool keep) { this->keep_read_ = keep; }
-  /// Drop the bytes the decoder has read, to make room for more of the download
-  void compact();
-
-  int32_t read(uint8_t *buf, uint32_t len) override;
-  bool seek(uint32_t position) override;
-
- protected:
-  DownloadBuffer &buffer_;
-  size_t start_{0};  // Position in the download of the first byte in the buffer
-  size_t pos_{0};    // Position in the download the decoder reads next
-  bool keep_read_{true};
-};
-
 }  // namespace esphome::online_image
@@ -22,8 +22,6 @@ DEPENDENCIES = ["http_request"]
 CODEOWNERS = ["@guillempages", "@clydebarrow"]

 CONF_ON_DOWNLOAD_FINISHED = "on_download_finished"
-CONF_ON_DOWNLOAD_STARTED = "on_download_started"
-CONF_ON_DOWNLOAD_PROGRESS = "on_download_progress"
 CONF_UPDATE = "update"

 online_image_ns = cg.esphome_ns.namespace("online_image")
@@ -45,9 +43,7 @@ ONLINE_IMAGE_SCHEMA = (
            cv.Optional(CONF_REQUEST_HEADERS): cv.All(
                cv.Schema({cv.string: cv.templatable(cv.string)})
            ),
-            cv.Optional(CONF_ON_DOWNLOAD_STARTED): automation.validate_automation({}),
            cv.Optional(CONF_ON_DOWNLOAD_FINISHED): automation.validate_automation({}),
-            cv.Optional(CONF_ON_DOWNLOAD_PROGRESS): automation.validate_automation({}),
            cv.Optional(CONF_ON_ERROR): automation.validate_automation({}),
        }
    )
@@ -100,17 +96,9 @@ automation.register_apply_action(


 _CALLBACK_AUTOMATIONS = (
-    automation.CallbackAutomation(
-        CONF_ON_DOWNLOAD_STARTED, "add_on_download_started_callback"
-    ),
    automation.CallbackAutomation(
        CONF_ON_DOWNLOAD_FINISHED, "add_on_finished_callback", [(bool, "cached")]
    ),
-    automation.CallbackAutomation(
-        CONF_ON_DOWNLOAD_PROGRESS,
-        "add_on_progress_callback",
-        [(float, "progress"), (cg.size_t, "bytes_read")],
-    ),
    automation.CallbackAutomation(CONF_ON_ERROR, "add_on_error_callback"),
 )

@@ -4,7 +4,6 @@
 #include "esphome/core/helpers.h"
 #include "esphome/core/log.h"
 #include <algorithm>
-#include <cmath>
 #include <cstdio>

 ESPHOME_LOG_TAG(TAG, "online_image");
@@ -16,11 +15,6 @@ static const char *const IF_MODIFIED_SINCE_HEADER_NAME = "if-modified-since";

 namespace esphome::online_image {

-// Time one loop pass may spend reading, and decoding a JPEG as it downloads
-static constexpr uint32_t PASS_BUDGET_MS = 20;
-// Shortest time between two on_download_progress calls
-static constexpr uint32_t PROGRESS_INTERVAL_MS = 100;
-
 OnlineImage::OnlineImage(const std::string &url, int width, int height, runtime_image::ImageFormat format,
                         image::ImageType type, image::Transparency transparency, image::Image *placeholder,
                         uint32_t buffer_size, bool is_big_endian)
@@ -146,12 +140,8 @@ void OnlineImage::update() {
    return;
  }

-  // A JPEG of known size is decoded as it arrives, so the download buffer only has to hold its headers.
-  // Otherwise the decoder needs the complete image in the buffer.
-  this->streaming_ = total_size > 0 && total_size <= INT32_MAX && this->decoder_supports_source();
-  this->stream_started_ = false;
-  this->source_.reset();
-  if (!this->streaming_ && format == runtime_image::JPEG && total_size > this->download_buffer_.size() &&
+  // JPEG requires the complete image in the download buffer before decoding
+  if (format == runtime_image::JPEG && total_size > this->download_buffer_.size() &&
      this->download_buffer_.resize(total_size) == 0) {
    // resize() logged the failed allocation; the next update() allocates the configured buffer again
    this->end_connection_();
@@ -162,8 +152,6 @@ void OnlineImage::update() {
  ESP_LOGI(TAG, "Downloading image (Size: %zu)", total_size);
  this->start_time_ = millis();
  this->last_data_time_ = this->start_time_;
-  this->download_started_callback_.call();
-  this->report_progress_(true);
  this->enable_loop();
 }

@@ -181,11 +169,6 @@ void OnlineImage::loop() {
    return;
  }

-  if (this->streaming_) {
-    this->loop_stream_();
-    return;
-  }
-
  // Check if download is complete — use decoder's format-specific completion check
  // to handle both known content-length and chunked transfer encoding
  if (this->is_decode_finished() || (this->downloader_->content_length > 0 &&
@@ -196,22 +179,15 @@ void OnlineImage::loop() {
  }

  // Download and decode more data
-  if (this->download_buffer_.free_capacity() > 0) {
-    const uint32_t now = App.get_loop_component_start_time();
-    size_t received = 0;
-    int len;
-    do {
-      len = this->downloader_->read(this->download_buffer_.append(),
-                                    std::min(this->download_buffer_.free_capacity(), READ_CHUNK));
-      if (len <= 0)
-        break;
-      this->download_buffer_.write(len);
-      received += len;
-    } while (this->download_buffer_.free_capacity() != 0 && millis() - now < PASS_BUDGET_MS);
+  size_t available = this->download_buffer_.free_capacity();
+  if (available > 0) {
+    // Download in chunks to avoid blocking
+    available = std::min(available, this->download_buffer_initial_size_);
+    auto len = this->downloader_->read(this->download_buffer_.append(), available);

-    if (received > 0) {
-      this->last_data_time_ = now;
-      this->report_progress_(false);
+    if (len > 0) {
+      this->last_data_time_ = App.get_loop_component_start_time();
+      this->download_buffer_.write(len);

      // Feed data to decoder
      auto consumed = this->feed_data(this->download_buffer_.data(), this->download_buffer_.unread());
@@ -279,114 +255,6 @@ void OnlineImage::loop() {
  }
 }

-void OnlineImage::loop_stream_() {
-  const uint32_t now = App.get_loop_component_start_time();
-  const size_t total = this->downloader_->content_length;
-  if (this->stream_started_)
-    this->source_.compact();
-
-  if (this->downloader_->get_bytes_read() < total) {
-    if (this->download_buffer_.free_capacity() == 0) {
-      // compact() already ran, so a full buffer means the decoder read nothing in the last pass
-      if (now - this->last_data_time_ >= this->parent_->get_timeout()) {
-        ESP_LOGE(TAG, "Image does not fit in the %zu byte download buffer; increase buffer_size",
-                 this->download_buffer_.size());
-        this->fail_download_();
-        return;
-      }
-    } else {
-      int len;
-      do {
-        len = this->downloader_->read(this->download_buffer_.append(),
-                                      std::min(this->download_buffer_.free_capacity(), READ_CHUNK));
-        if (len <= 0)
-          break;
-        this->last_data_time_ = now;
-        this->download_buffer_.write(len);
-        this->report_progress_(false);
-      } while (this->downloader_->get_bytes_read() < total && this->download_buffer_.free_capacity() != 0 &&
-               millis() - now < PASS_BUDGET_MS);
-      if (len < 0) {
-        ESP_LOGE(TAG, "Error downloading image: %d", len);
-        this->fail_download_();
-        return;
-      } else if (now - this->last_data_time_ >= this->parent_->get_timeout()) {
-        ESP_LOGE(TAG, "No data received for %" PRIu32 " ms", this->parent_->get_timeout());
-        this->fail_download_();
-        return;
-      }
-    }
-  }
-  const bool arrived = this->downloader_->get_bytes_read() >= total;
-
-  if (!this->stream_started_) {
-    // The decoder reads the headers when it opens the image, so wait until they are in the buffer
-    if (!arrived && this->download_buffer_.free_capacity() != 0)
-      return;
-    const int err = this->begin_source(&this->source_);
-    if (err != 0) {
-      // Headers cut short by a full buffer fail to parse, or make the decoder seek past the buffer. Such an image
-      // still decodes once it is all in memory, as it did before JPEG images were decoded as they download.
-      if (!arrived && (err == runtime_image::DECODE_ERROR_INVALID_TYPE || err == runtime_image::DECODE_ERROR_READ)) {
-        ESP_LOGW(TAG,
-                 "The image headers do not fit the %zu byte download buffer, so the whole image is downloaded "
-                 "before it is decoded; increase buffer_size to decode it as it downloads",
-                 this->download_buffer_.size());
-        // grow() logs a failed allocation
-        if (this->download_buffer_.grow(total)) {
-          this->streaming_ = false;
-        } else {
-          this->fail_download_();
-        }
-        return;
-      }
-      ESP_LOGE(TAG, "Error decoding image: %s", runtime_image::decode_error_to_string(err));
-      this->fail_download_();
-      return;
-    }
-    this->source_.set_keep_read(false);
-    this->stream_started_ = true;
-    // Opening the image and allocating its buffer is enough for one pass
-    return;
-  }
-
-  do {
-    const int result = this->decode_step();
-    if (result == runtime_image::DECODE_STEP_MORE)
-      continue;
-    if (result == runtime_image::DECODE_STEP_DONE) {
-      this->finish_download_();
-    } else if (result == runtime_image::DECODE_STEP_NEED_DATA) {
-      if (!arrived)
-        return;
-      // JPEGDEC only waits for bytes short of the size it was given, so this guards against a hang
-      ESP_LOGE(TAG, "Download ended before the image was complete");
-      this->fail_download_();
-    } else {
-      ESP_LOGE(TAG, "Error decoding image: %s", runtime_image::decode_error_to_string(result));
-      this->fail_download_();
-    }
-    return;
-  } while (millis() - now < PASS_BUDGET_MS);
-}
-
-void OnlineImage::report_progress_(bool force) {
-  const uint32_t now = App.get_loop_component_start_time();
-  const size_t bytes = this->downloader_->get_bytes_read();
-  const size_t total = this->downloader_->content_length;
-  // The last bytes are always reported, so a progress bar reaches 100%
-  if (!force && now - this->last_progress_time_ < PROGRESS_INTERVAL_MS && (total == 0 || bytes < total))
-    return;
-  this->last_progress_time_ = now;
-  const float progress = total > 0 ? std::min(100.0f, bytes * 100.0f / total) : NAN;
-  this->download_progress_callback_.call(progress, bytes);
-}
-
-void OnlineImage::fail_download_() {
-  this->end_connection_();
-  this->download_error_callback_.call();
-}
-
 void OnlineImage::finish_download_() {
  // Must be read before end_decode() ends the decoding session
  bool decoder_finished = this->is_decode_finished();
@@ -420,8 +288,6 @@ void OnlineImage::end_connection_() {
    this->downloader_ = nullptr;
  }
  this->download_buffer_.reset();
-  this->streaming_ = false;
-  this->stream_started_ = false;
  this->disable_loop();
 }

@@ -16,10 +16,6 @@ using t_http_codes = enum {
  HTTP_CODE_NOT_FOUND = 404,
 };

-/// Largest download read(). A read() blocks until it has every byte it asked for, so this bounds how long one loop
-/// pass waits on a slow link.
-static constexpr size_t READ_CHUNK = 1460;
-
 /**
 * @brief Download an image from a given URL, and decode it using the specified decoder.
 * The image will then be stored in a buffer, so that it can be re-displayed without the
@@ -74,17 +70,9 @@ class OnlineImage final : public PollingComponent,
   */
  void release();

-  /// Called when the server has accepted the request and the image starts to download
-  template<typename F> void add_on_download_started_callback(F &&callback) {
-    this->download_started_callback_.add(std::forward<F>(callback));
-  }
  template<typename F> void add_on_finished_callback(F &&callback) {
    this->download_finished_callback_.add(std::forward<F>(callback));
  }
-  /// Called with the percentage downloaded (NAN when the server did not send the size) and the bytes read so far
-  template<typename F> void add_on_progress_callback(F &&callback) {
-    this->download_progress_callback_.add(std::forward<F>(callback));
-  }
  template<typename F> void add_on_error_callback(F &&callback) {
    this->download_error_callback_.add(std::forward<F>(callback));
  }
@@ -93,20 +81,12 @@ class OnlineImage final : public PollingComponent,
  bool validate_url_(const std::string &url);
  void end_connection_();
  void finish_download_();
-  /// loop() for a JPEG that is decoded as it downloads
-  void loop_stream_();
-  void fail_download_();
-  /// Reports download progress, at most every PROGRESS_INTERVAL_MS unless force is set
-  void report_progress_(bool force);

  CallbackManager<void(bool)> download_finished_callback_{};
  CallbackManager<void()> download_error_callback_{};
-  LazyCallbackManager<void()> download_started_callback_{};
-  LazyCallbackManager<void(float, size_t)> download_progress_callback_{};

  std::shared_ptr<http_request::HttpContainer> downloader_{nullptr};
  DownloadBuffer download_buffer_;
-  DownloadSource source_{download_buffer_};
  /**
   * This is the *initial* size of the download buffer, not the current size.
   * The download buffer can be resized at runtime; the download_buffer_initial_size_
@@ -129,9 +109,6 @@ class OnlineImage final : public PollingComponent,

  uint32_t start_time_{0};
  uint32_t last_data_time_{0};
-  uint32_t last_progress_time_{0};
-  bool streaming_{false};       // The decoder reads the download itself, as it arrives
-  bool stream_started_{false};  // The decoder has read the headers
 };

 }  // namespace esphome::online_image
@@ -2,6 +2,7 @@
 #include "runtime_image.h"
 #include "esphome/core/log.h"
 #include <algorithm>
+#include <cmath>

 namespace esphome::runtime_image {

@@ -10,48 +11,19 @@ ESPHOME_LOG_TAG(TAG, "image_decoder");
 bool ImageDecoder::set_size(int width, int height) {
  bool success = this->image_->resize(width, height) > 0;
  this->size_valid_ = success;
-  this->draw_width_ = width;
-  this->draw_height_ = height;
+  this->x_scale_ = static_cast<double>(this->image_->get_buffer_width()) / width;
+  this->y_scale_ = static_cast<double>(this->image_->get_buffer_height()) / height;
  return success;
 }

-int ImageDecoder::scaled_x_(int x) const {
-  if (this->draw_width_ <= 0)
-    return 0;
-  const uint32_t buffer_width = this->image_->get_buffer_width();
-  return static_cast<int>((static_cast<uint32_t>(x) * buffer_width + this->draw_width_ - 1) / this->draw_width_);
-}
-
-int ImageDecoder::scaled_y_(int y) const {
-  if (this->draw_height_ <= 0)
-    return 0;
-  const uint32_t buffer_height = this->image_->get_buffer_height();
-  return static_cast<int>((static_cast<uint32_t>(y) * buffer_height + this->draw_height_ - 1) / this->draw_height_);
-}
-
 void ImageDecoder::draw(int x, int y, int w, int h, const Color &color) {
  if (!this->size_valid_) {
    return;
  }
-  // A source pixel paints the target pixels from ceil(start * scale) up to ceil(end * scale). The spans of neighbouring
-  // pixels meet without overlapping, so when an image is shrunk each target pixel is painted once, by the first
-  // source pixel that reaches it, rather than by every pixel that lands on it. Integer maths: the S3 has no double FPU.
-  const int buffer_width = this->image_->get_buffer_width();
-  const int buffer_height = this->image_->get_buffer_height();
-  int x1 = x;
-  int y1 = y;
-  int x2 = x + w;
-  int y2 = y + h;
-  if (buffer_width != this->draw_width_ || buffer_height != this->draw_height_) {
-    x1 = this->scaled_x_(x);
-    y1 = this->scaled_y_(y);
-    x2 = this->scaled_x_(x + w);
-    y2 = this->scaled_y_(y + h);
-  }
-  x2 = std::min(buffer_width, x2);
-  y2 = std::min(buffer_height, y2);
-  for (int i = x1; i < x2; i++) {
-    for (int j = y1; j < y2; j++) {
+  auto width = std::min(this->image_->get_buffer_width(), static_cast<int>(std::ceil((x + w) * this->x_scale_)));
+  auto height = std::min(this->image_->get_buffer_height(), static_cast<int>(std::ceil((y + h) * this->y_scale_)));
+  for (int i = x * this->x_scale_; i < width; i++) {
+    for (int j = y * this->y_scale_; j < height; j++) {
      this->image_->draw_pixel(i, j, color);
    }
  }
@@ -83,8 +83,8 @@ class ImageDecoder {
    this->expected_size_ = 0;
    this->decoded_bytes_ = 0;
    this->size_valid_ = true;
-    this->draw_width_ = 0;
-    this->draw_height_ = 0;
+    this->x_scale_ = 1.0;
+    this->y_scale_ = 1.0;
  }

  /**
@@ -184,13 +184,8 @@ class ImageDecoder {
  uint8_t *image_buffer_() const;
  bool image_is_big_endian_() const;

-  /// The first buffer column, or row, that source column x, or row y, paints: ceil(x * buffer size / draw size)
-  int scaled_x_(int x) const;
-  int scaled_y_(int y) const;
-
-  // Size of the image as the decoder draws it, which draw() spreads over the buffer
-  int draw_width_ = 0;
-  int draw_height_ = 0;
+  double x_scale_ = 1.0;
+  double y_scale_ = 1.0;
  RuntimeImage *image_;
  size_t expected_size_ = 0;  // Expected data size (0 if unknown)
  size_t decoded_bytes_ = 0;  // Bytes processed so far
@@ -31,8 +31,8 @@ bool JpegDecoder::prepare_rgb565_scaling_(int width, int height) {
  const uint32_t target_width = this->image_->get_buffer_width();
  const uint32_t target_height = this->image_->get_buffer_height();
  // Boundary n is the first target pixel source pixel n covers, rounded up. When shrinking, the source
-  // pixel whose span lands on a target pixel paints it, so an 8 to 4 scale keeps columns 0, 2, 4 and 6,
-  // as the generic draw() path does
+  // pixel whose span lands on a target pixel paints it, so an 8 to 4 scale keeps columns 0, 2, 4 and 6;
+  // the generic draw() path rounds down and keeps the odd ones instead
  for (uint32_t x = 0; x <= static_cast<uint32_t>(width); x++) {
    this->x_boundaries_.push_back(static_cast<uint16_t>((x * target_width + width - 1) / width));
  }
@@ -138,7 +138,7 @@ int HOT JpegDecoder::decode(uint8_t *buffer, size_t size) {
  const int err = this->start_();
  if (err != 0)
    return err;
-  if (!this->jpeg_.decode(0, 0, this->scale_option_()))
+  if (!this->jpeg_.decode(0, 0, 0))
    return this->fail_();
  this->decoded_bytes_ = size;
  this->jpeg_.close();
@@ -165,28 +165,10 @@ int JpegDecoder::start_() {
  } else {
    this->jpeg_.setPixelType(RGB8888);
  }
-  const int width = this->jpeg_.getWidth();
-  const int height = this->jpeg_.getHeight();
-  if (!this->set_size(width, height)) {
+  if (!this->set_size(this->jpeg_.getWidth(), this->jpeg_.getHeight())) {
    return DECODE_ERROR_OUT_OF_MEMORY;
  }
-  // JPEGDEC can decode at 1/2, 1/4 or 1/8 size for much less work. Use the smallest size that still has at least as
-  // many pixels as the buffer, so a large image shown small is not decoded in full only to be thrown away.
-  const int buffer_width = this->image_->get_buffer_width();
-  const int buffer_height = this->image_->get_buffer_height();
-  this->scale_ = 1;
-  while (this->scale_ < JPEG_SCALE_EIGHTH && width / (this->scale_ * 2) >= buffer_width &&
-         height / (this->scale_ * 2) >= buffer_height) {
-    this->scale_ *= 2;
-  }
-  const int decoded_width = (width + this->scale_ - 1) / this->scale_;
-  const int decoded_height = (height + this->scale_ - 1) / this->scale_;
-  this->draw_width_ = decoded_width;
-  this->draw_height_ = decoded_height;
-  if (this->scale_ != 1) {
-    ESP_LOGD(TAG, "Decoding at 1/%d size, %d x %d", this->scale_, decoded_width, decoded_height);
-  }
-  if (this->direct_rgb565_ && !this->prepare_rgb565_scaling_(decoded_width, decoded_height)) {
+  if (this->direct_rgb565_ && !this->prepare_rgb565_scaling_(this->jpeg_.getWidth(), this->jpeg_.getHeight())) {
    return DECODE_ERROR_OUT_OF_MEMORY;
  }
  return 0;
@@ -270,7 +252,7 @@ int JpegDecoder::begin_source(DecodeSource *source) {
    this->source_ = nullptr;
    return err;
  }
-  if (!this->jpeg_.decodeBegin(0, 0, this->scale_option_()))
+  if (!this->jpeg_.decodeBegin(0, 0, 0))
    return this->fail_();
  return 0;
 }
@@ -31,16 +31,12 @@ class JpegDecoder : public ImageDecoder {
  int HOT decode_step() override;

  bool uses_direct_rgb565() const { return this->direct_rgb565_; }
-  /// JPEGDEC decodes the image at 1/get_scale() of its size: 1, 2, 4 or 8
-  int get_scale() const { return this->scale_; }
  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 JPEGDEC option for scale_: JPEG_SCALE_HALF, _QUARTER and _EIGHTH are the divisors themselves
-  int scale_option_() const { return this->scale_ == 1 ? 0 : this->scale_; }
  /// The DecodeError for a failed read of the source or JPEGDEC's last error, closing the image
  int fail_();

@@ -53,7 +49,6 @@ class JpegDecoder : public ImageDecoder {
  FixedVector<uint16_t> y_boundaries_{};
  int source_width_{0};
  int source_height_{0};
-  int scale_{1};                   // JPEGDEC decodes at 1/scale_ of the image size
  DecodeSource *source_{nullptr};  // Set while a begin_source() decode is in progress
  bool direct_rgb565_{false};
  bool source_failed_{false};
@@ -17,8 +17,8 @@ from esphome.components.esp32 import (
    VARIANT_ESP32S2,
    VARIANT_ESP32S3,
    VARIANT_ESP32S31,
-    idf_version,
    only_on_variant,
+    require_idf_version,
 )
 from esphome.components.psram import DOMAIN as PSRAM_DOMAIN
 from esphome.config_helpers import filter_source_files_from_platform
@@ -143,19 +143,12 @@ TYPE_CLASS = {
 }


-def _require_psram_dma_idf(value: Any) -> Any:
-    if idf_version() < cv.Version(5, 5, 3):
-        raise cv.Invalid("psram_dma requires ESP-IDF 5.5.3 or newer")
-    return value
-
-
 def _validate_psram_dma(value: Any) -> bool:
    value = cv.boolean(value)
    if not value:
        return value
    return cv.All(
-        cv.only_on_esp32,
-        _require_psram_dma_idf,
+        require_idf_version(cv.Version(5, 5, 3), "psram_dma"),
        only_on_variant(
            supported=[
                VARIANT_ESP32C5,
@@ -1,4 +1,6 @@
-from esphome import automation
+from collections.abc import Callable
+
+from esphome import automation, preferences
 from esphome.automation import maybe_simple_id
 import esphome.codegen as cg
 from esphome.components import mqtt, web_server, zigbee
@@ -8,13 +10,16 @@ from esphome.const import (
    CONF_ENTITY_CATEGORY,
    CONF_ICON,
    CONF_ID,
+    CONF_INITIAL_STATE,
    CONF_INVERTED,
    CONF_MQTT_ID,
    CONF_ON_STATE,
    CONF_ON_TURN_OFF,
    CONF_ON_TURN_ON,
    CONF_RESTORE_MODE,
+    CONF_RESTORE_STATE,
    CONF_STATE,
+    CONF_STORAGE,
    CONF_WEB_SERVER,
    DEVICE_CLASS_EMPTY,
    DEVICE_CLASS_OUTLET,
@@ -22,10 +27,14 @@ from esphome.const import (
 )
 from esphome.core import CORE, ID, CoroPriority, coroutine_with_priority
 from esphome.core.entity_helpers import (
+    RESTORE_STATE_INITIAL,
+    RESTORE_STATE_INVERT,
+    RESTORE_STATE_KEEP,
    ApplyEntity,
    SubEntities,
    entity_duplicate_validator,
    queue_entity_register,
+    restore_state_schema,
    setup_device_class,
    setup_entity,
 )
@@ -47,6 +56,8 @@ SwitchPtr = Switch.operator("ptr")
 ApplySwitch = switch_ns.class_("ApplySwitch", Switch)

 SwitchRestoreMode = switch_ns.enum("SwitchRestoreMode")
+RESTORE_MODE_STORAGE_FLASH_MASK = switch_ns.RESTORE_MODE_STORAGE_FLASH_MASK
+RESTORE_MODE_STORAGE_RTC_MASK = switch_ns.RESTORE_MODE_STORAGE_RTC_MASK

 RESTORE_MODES = {
    "RESTORE_DEFAULT_OFF": SwitchRestoreMode.SWITCH_RESTORE_DEFAULT_OFF,
@@ -60,6 +71,115 @@ RESTORE_MODES = {


 validate_device_class = cv.one_of(*DEVICE_CLASSES, lower=True)
+validate_restore_mode = cv.enum(RESTORE_MODES, upper=True, space="_")
+
+
+def _validate_restore_state_storage(config: ConfigType) -> ConfigType:
+    if CONF_STORAGE in config and config[CONF_STATE] == RESTORE_STATE_INITIAL:
+        raise cv.Invalid(
+            "'storage' only applies when a saved state is restored (KEEP or INVERT)",
+            path=[CONF_STORAGE],
+        )
+    return config
+
+
+def _validate_restore_state_state(value: object) -> str:
+    # light accepts ON/OFF here (restore, then force a state); a switch has no such mode, and
+    # YAML turns ON into True, so say what to use instead of asking for quotes
+    if isinstance(value, bool) or (
+        isinstance(value, str) and value.upper() in ("ON", "OFF")
+    ):
+        raise cv.Invalid(
+            "a switch can't restore and then force ON or OFF; to always start in a fixed state, "
+            "use 'initial_state: ON' (or OFF) with 'restore_state: none'"
+        )
+    return cv.one_of(
+        RESTORE_STATE_KEEP, RESTORE_STATE_INVERT, RESTORE_STATE_INITIAL, upper=True
+    )(value)
+
+
+_RESTORE_STATE_FIELDS_SCHEMA = cv.Schema(
+    {
+        cv.Optional(
+            CONF_STATE, default=RESTORE_STATE_KEEP
+        ): _validate_restore_state_state,
+        # No default: when unset, the existing restore_mode storage applies (on ESP8266,
+        # restore_from_flash decides), as with wifi
+        cv.Optional(CONF_STORAGE): preferences.validate_storage,
+    }
+)
+_RESTORE_STATE_FIELDS_SCHEMA.add_extra(_validate_restore_state_storage)
+
+
+# A mapping of `state` and `storage`, or the shorthands `all` (KEEP) and `none` (INITIAL)
+RESTORE_STATE_SCHEMA = restore_state_schema(
+    _RESTORE_STATE_FIELDS_SCHEMA, {CONF_STATE: RESTORE_STATE_INITIAL}
+)
+
+
+def _validate_initial_state(config: ConfigType) -> ConfigType:
+    if CONF_INITIAL_STATE in config and CONF_RESTORE_MODE in config:
+        raise cv.Invalid(
+            "'initial_state' can't be combined with 'restore_mode', which already sets "
+            "the boot state; use 'restore_state' instead",
+            path=[CONF_INITIAL_STATE],
+        )
+    return config
+
+
+# (restore_state state, initial_state) -> restore mode
+_RESTORE_MODE_FOR_STATE = {
+    (RESTORE_STATE_KEEP, False): "RESTORE_DEFAULT_OFF",
+    (RESTORE_STATE_KEEP, True): "RESTORE_DEFAULT_ON",
+    (RESTORE_STATE_INVERT, False): "RESTORE_INVERTED_DEFAULT_OFF",
+    (RESTORE_STATE_INVERT, True): "RESTORE_INVERTED_DEFAULT_ON",
+    (RESTORE_STATE_INITIAL, False): "ALWAYS_OFF",
+    (RESTORE_STATE_INITIAL, True): "ALWAYS_ON",
+}
+_STATE_FOR_RESTORE_MODE = {
+    mode: state for (state, _), mode in _RESTORE_MODE_FOR_STATE.items()
+}
+
+
+def _apply_default_restore_mode(
+    default_restore_mode: str,
+) -> Callable[[ConfigType], ConfigType]:
+    # cv.Exclusive has no default, so apply it here when no restore option is configured.
+    # With only initial_state set, a restoring default keeps restoring and initial_state
+    # supplies the state used when nothing is saved.
+    default = validate_restore_mode(default_restore_mode)
+    state = _STATE_FOR_RESTORE_MODE.get(str(default), RESTORE_STATE_INITIAL)
+
+    def validator(config: ConfigType) -> ConfigType:
+        if CONF_RESTORE_MODE in config or CONF_RESTORE_STATE in config:
+            return config
+        if CONF_INITIAL_STATE in config:
+            config[CONF_RESTORE_STATE] = {CONF_STATE: state}
+        else:
+            config[CONF_RESTORE_MODE] = default
+        return config
+
+    return validator
+
+
+def _resolve_restore_mode(config: ConfigType) -> MockObj | str:
+    """Translate `initial_state` / `restore_state` into one of the RESTORE_MODES, with the storage bit."""
+    if (restore_mode := config.get(CONF_RESTORE_MODE)) is not None:
+        return restore_mode
+    restore_state = config.get(CONF_RESTORE_STATE, {})
+    state = restore_state.get(CONF_STATE, RESTORE_STATE_INITIAL)
+    mode = RESTORE_MODES[
+        _RESTORE_MODE_FOR_STATE[state, config.get(CONF_INITIAL_STATE, False)]
+    ]
+    if (storage := restore_state.get(CONF_STORAGE)) is None:
+        return mode
+    cg.add_define("USE_SWITCH_STORAGE")
+    mask = (
+        RESTORE_MODE_STORAGE_FLASH_MASK
+        if preferences.is_in_flash(storage)
+        else RESTORE_MODE_STORAGE_RTC_MASK
+    )
+    return cg.RawExpression(f"static_cast<{SwitchRestoreMode}>({mode} | {mask})")


 _SWITCH_SCHEMA = (
@@ -70,9 +190,9 @@ _SWITCH_SCHEMA = (
        {
            cv.OnlyWith(CONF_MQTT_ID, "mqtt"): cv.declare_id(mqtt.MQTTSwitchComponent),
            cv.Optional(CONF_INVERTED): cv.boolean,
-            cv.Optional(CONF_RESTORE_MODE, default="ALWAYS_OFF"): cv.enum(
-                RESTORE_MODES, upper=True, space="_"
-            ),
+            cv.Exclusive(CONF_RESTORE_MODE, "restore"): validate_restore_mode,
+            cv.Exclusive(CONF_RESTORE_STATE, "restore"): RESTORE_STATE_SCHEMA,
+            cv.Optional(CONF_INITIAL_STATE): cv.boolean,
            cv.Optional(CONF_ON_STATE): automation.validate_automation({}),
            cv.Optional(CONF_ON_TURN_ON): automation.validate_automation({}),
            cv.Optional(CONF_ON_TURN_OFF): automation.validate_automation({}),
@@ -86,6 +206,7 @@ _SWITCH_SCHEMA = (

 _SWITCH_SCHEMA.add_extra(entity_duplicate_validator("switch"))
 _SWITCH_SCHEMA.add_extra(zigbee.validate_switch)
+_SWITCH_SCHEMA.add_extra(_validate_initial_state)


 def switch_schema(
@@ -103,13 +224,6 @@ def switch_schema(
        (CONF_DEVICE_CLASS, device_class, validate_device_class),
        (CONF_ENTITY_CATEGORY, entity_category, cv.entity_category),
        (CONF_ICON, icon, cv.icon),
-        (
-            CONF_RESTORE_MODE,
-            default_restore_mode,
-            cv.enum(RESTORE_MODES, upper=True, space="_")
-            if default_restore_mode is not cv.UNDEFINED
-            else cv.UNDEFINED,
-        ),
    ]:
        if default is not cv.UNDEFINED:
            schema[cv.Optional(key, default=default)] = validator
@@ -119,7 +233,15 @@ def switch_schema(
            "Inverted is not supported for this platform!"
        )

-    return _SWITCH_SCHEMA.extend(schema)
+    result = _SWITCH_SCHEMA.extend(schema)
+    result.add_extra(
+        _apply_default_restore_mode(
+            "ALWAYS_OFF"
+            if default_restore_mode is cv.UNDEFINED
+            else default_restore_mode
+        )
+    )
+    return result


 _CALLBACK_AUTOMATIONS = (
@@ -159,7 +281,7 @@ async def setup_switch_core_(var, config):

    setup_device_class(config)

-    cg.add(var.set_restore_mode(config[CONF_RESTORE_MODE]))
+    cg.add(var.set_restore_mode(_resolve_restore_mode(config)))
    await zigbee.setup_switch(var, config)


@@ -33,7 +33,14 @@ optional<bool> Switch::get_initial_state() {
  if (!(restore_mode & RESTORE_MODE_PERSISTENT_MASK))
    return {};

-  this->rtc_ = this->make_entity_preference<bool>();
+#ifdef USE_SWITCH_STORAGE
+  if (restore_mode & RESTORE_MODE_STORAGE_MASK) {
+    this->rtc_ = this->make_entity_preference<bool>(0, restore_mode & RESTORE_MODE_STORAGE_FLASH_MASK);
+  } else
+#endif
+  {
+    this->rtc_ = this->make_entity_preference<bool>();
+  }
  bool initial_state;
  if (!this->rtc_.load(&initial_state))
    return {};
@@ -53,6 +60,13 @@ optional<bool> Switch::get_initial_state_with_restore_mode() {
  }
  return initial_state;
 }
+void Switch::restore() {
+  if (auto initial = this->get_initial_state_with_restore_mode())
+    this->control(*initial);
+}
+void Switch::restore(bool when_disabled) {
+  this->control(this->get_initial_state_with_restore_mode().value_or(when_disabled));
+}
 void Switch::publish_state(bool state) {
  if (!this->publish_dedup_.next(state))
    return;
@@ -14,11 +14,16 @@ namespace esphome::switch_ {
 public: \
  void set_##name##_switch(switch_::Switch *s) { this->name##_switch_ = s; }

-// bit0: on/off. bit1: persistent. bit2: inverted. bit3: disabled
+// bit0: on/off. bit1: persistent. bit2: inverted. bit3: disabled.
+// bit4: restore from flash. bit5: restore from RTC memory (neither: platform default).
+// Code generation ors the storage bit into the restore mode passed to set_restore_mode().
 constexpr int RESTORE_MODE_ON_MASK = 0x01;
 constexpr int RESTORE_MODE_PERSISTENT_MASK = 0x02;
 constexpr int RESTORE_MODE_INVERTED_MASK = 0x04;
 constexpr int RESTORE_MODE_DISABLED_MASK = 0x08;
+constexpr int RESTORE_MODE_STORAGE_FLASH_MASK = 0x10;
+constexpr int RESTORE_MODE_STORAGE_RTC_MASK = 0x20;
+constexpr int RESTORE_MODE_STORAGE_MASK = RESTORE_MODE_STORAGE_FLASH_MASK | RESTORE_MODE_STORAGE_RTC_MASK;

 enum SwitchRestoreMode : uint8_t {
  SWITCH_ALWAYS_OFF = !RESTORE_MODE_ON_MASK,
@@ -110,6 +115,11 @@ class Switch : public EntityBase {
   */
  optional<bool> get_initial_state_with_restore_mode();

+  /// Drive the switch to the state its restore mode yields, through control(), so inversion and
+  /// write_state() apply; a disabled restore mode drives \p when_disabled, or nothing without one.
+  void restore();
+  void restore(bool when_disabled);
+
  /** Return whether this switch uses an assumed state - i.e. if both the ON/OFF actions should be displayed in Home
   * Assistant because the real state is unknown.
   *
@@ -139,9 +149,9 @@ class Switch : public EntityBase {
  LazyCallbackManager<void(bool)> state_callback_{};

  // Small types grouped together
-  Deduplicator<bool> publish_dedup_;  // 2 bytes (bool has_value_ + bool last_value_)
+  Deduplicator<bool> publish_dedup_;  // 3 bytes (bool has_value_ + bool value_unknown_ + bool last_value_)
  bool inverted_{false};              // 1 byte
-  // Total: 3 bytes, 1 byte padding
+  // Total: 4 bytes, no padding
 };

 #define LOG_SWITCH(prefix, type, obj) log_switch((TAG), (prefix), LOG_STR_LITERAL(type), (obj))
@@ -14,6 +14,7 @@ from esphome.components.esp32 import (
    get_esp32_variant,
    idf_version,
    only_on_variant,
+    require_idf_version,
 )
 import esphome.config_validation as cv
 from esphome.const import CONF_DEVICES, CONF_FRAMEWORK, CONF_ID
@@ -201,10 +202,9 @@ def fifo_split() -> tuple[int, int, int] | None:
 def _reconcile_fifo() -> None:
    if (split := fifo_split()) is None:
        return
-    if idf_version() < FIFO_CUSTOM_MIN_IDF:
-        raise cv.Invalid(
-            f"Sizing the USB FIFO on the {get_esp32_variant()} needs ESP-IDF {FIFO_CUSTOM_MIN_IDF} or later"
-        )
+    require_idf_version(
+        FIFO_CUSTOM_MIN_IDF, f"Sizing the USB FIFO on the {get_esp32_variant()}"
+    )(None)
    rx, nptx, ptx = split
    cg.add_define("USE_USB_HOST_FIFO_CONFIG")
    cg.add_define("USB_HOST_FIFO_RX_LINES", rx)
@@ -1,25 +1,31 @@
 #pragma once

+#include <cstdint>
+
 namespace esphome::valve {

 class ValveTraits {
 public:
  ValveTraits() = default;

-  bool get_is_assumed_state() const { return this->is_assumed_state_; }
-  void set_is_assumed_state(bool is_assumed_state) { this->is_assumed_state_ = is_assumed_state; }
-  bool get_supports_position() const { return this->supports_position_; }
-  void set_supports_position(bool supports_position) { this->supports_position_ = supports_position; }
-  bool get_supports_toggle() const { return this->supports_toggle_; }
-  void set_supports_toggle(bool supports_toggle) { this->supports_toggle_ = supports_toggle; }
-  bool get_supports_stop() const { return this->supports_stop_; }
-  void set_supports_stop(bool supports_stop) { this->supports_stop_ = supports_stop; }
+  bool get_is_assumed_state() const { return this->flags_.is_assumed_state; }
+  void set_is_assumed_state(bool is_assumed_state) { this->flags_.is_assumed_state = is_assumed_state; }
+  bool get_supports_position() const { return this->flags_.supports_position; }
+  void set_supports_position(bool supports_position) { this->flags_.supports_position = supports_position; }
+  bool get_supports_toggle() const { return this->flags_.supports_toggle; }
+  void set_supports_toggle(bool supports_toggle) { this->flags_.supports_toggle = supports_toggle; }
+  bool get_supports_stop() const { return this->flags_.supports_stop; }
+  void set_supports_stop(bool supports_stop) { this->flags_.supports_stop = supports_stop; }

 protected:
-  bool is_assumed_state_{false};
-  bool supports_position_{false};
-  bool supports_toggle_{false};
-  bool supports_stop_{false};
+  // Bit-packed flags to save memory (1 byte instead of 4)
+  struct ValveTraitFlags {
+    uint8_t is_assumed_state : 1;
+    uint8_t supports_position : 1;
+    uint8_t supports_toggle : 1;
+    uint8_t supports_stop : 1;
+    uint8_t reserved : 4;
+  } flags_{};
 };

 }  // namespace esphome::valve
@@ -12,7 +12,11 @@ from esphome.components.json import enable_arena
 from esphome.components.logger import request_log_listener
 from esphome.components.web_server_base import CONF_WEB_SERVER_BASE_ID
 import esphome.config_validation as cv
-from esphome.const import (
+
+# Re-exported so entity components and external components keep importing
+# these from web_server; defined outside this package so entity base
+# schemas do not need to import it.
+from esphome.const import (  # noqa: F401
    CONF_AP,
    CONF_AUTH,
    CONF_COMPRESSION,
@@ -31,6 +35,8 @@ from esphome.const import (
    CONF_OTA,
    CONF_PASSWORD,
    CONF_PORT,
+    CONF_SORTING_GROUP_ID,
+    CONF_SORTING_WEIGHT,
    CONF_STATIC_IP,
    CONF_TYPE,
    CONF_USERNAME,
@@ -46,6 +52,7 @@ from esphome.const import (
    PLATFORM_RTL87XX,
 )
 from esphome.core import CORE, CoroPriority, coroutine_with_priority
+from esphome.core.entity_helpers import WEBSERVER_SORTING_SCHEMA  # noqa: F401
 from esphome.cpp_generator import MockObj
 import esphome.final_validate as fv
 from esphome.types import ConfigType
@@ -72,9 +79,7 @@ DOMAIN = "web_server"
 AUTH_TYPE_BASIC = "basic"
 AUTH_TYPE_DIGEST = "digest"

-CONF_SORTING_GROUP_ID = "sorting_group_id"
 CONF_SORTING_GROUPS = "sorting_groups"
-CONF_SORTING_WEIGHT = "sorting_weight"
 CONF_ALLOWED_ORIGINS = "allowed_origins"

 # Schema default that also matches the C++ initializer in web_server_base.h; codegen
@@ -234,27 +239,6 @@ sorting_group = {
    cv.Optional(CONF_SORTING_WEIGHT): cv.float_,
 }

-WEBSERVER_SORTING_SCHEMA = cv.Schema(
-    {
-        # The per-entity web_server block is cosmetic dashboard ordering —
-        # mark the whole block advanced; the children inherit via the cascade.
-        cv.Optional(CONF_WEB_SERVER, visibility=cv.Visibility.ADVANCED): cv.Schema(
-            {
-                cv.OnlyWith(CONF_WEB_SERVER_ID, "web_server"): cv.use_id(WebServer),
-                cv.Optional(CONF_SORTING_WEIGHT): cv.All(
-                    cv.requires_component(DOMAIN),
-                    cv.float_,
-                ),
-                cv.Optional(CONF_SORTING_GROUP_ID): cv.All(
-                    cv.requires_component(DOMAIN),
-                    cv.use_id(cg.int_),
-                ),
-            }
-        )
-    }
-)
-
-
 CONFIG_SCHEMA = cv.All(
    cv.Schema(
        {
@@ -9,9 +9,9 @@ from esphome.components.esp32 import (
    add_idf_sdkconfig_option,
    const,
    get_esp32_variant,
-    idf_version,
    only_on_variant,
    request_wifi,
+    require_idf_version,
    require_mbedtls_tls,
    require_mbedtls_tls_extras,
 )
@@ -232,8 +232,8 @@ def _validate_ap_mode(value: str) -> str:
 def _validate_dns_servers(value: list) -> list:
    if any(ip.is_unspecified for ip in value):
        raise cv.Invalid("0.0.0.0 is not a DNS server the access point can offer")
-    if len(value) > 1 and CORE.is_esp32 and idf_version() < cv.Version(6, 0, 0):
-        raise cv.Invalid("The access point offers a second DNS server from ESP-IDF 6.0")
+    if len(value) > 1:
+        require_idf_version(cv.Version(6, 0, 0), "A second DNS server")(value)
    return value


@@ -26,11 +26,14 @@ from esphome.const import (
    CONF_VERSION,
    __version__ as ESPHOME_VERSION,
 )
-from esphome.core import CORE, CoroPriority, coroutine_with_priority
+from esphome.core import CORE, CoroPriority, coroutine_with_priority, entity_helpers
 import esphome.final_validate as fv
 from esphome.types import ConfigType

-from .const import (
+# CONF_CLUSTER, CONF_ENDPOINT, CONF_MAX_EP_NUMBER, CONF_REPORT,
+# CONF_USE_DEVICE_TYPE and REPORT are re-exported for existing consumers of
+# this package's namespace.
+from .const import (  # noqa: F401
    CONF_CLUSTER,
    CONF_ENDPOINT,
    CONF_MAX_EP_NUMBER,
@@ -62,12 +65,7 @@ from .zigbee_esp32 import (
    validate_switch_esp32,
    zigbee_require_vfs_select,
 )
-from .zigbee_zephyr import (
-    zephyr_binary_sensor,
-    zephyr_number,
-    zephyr_sensor,
-    zephyr_switch,
-)
+from .zigbee_zephyr import zephyr_number, zephyr_sensor, zephyr_switch

 _LOGGER = logging.getLogger(__name__)

@@ -77,68 +75,24 @@ DOMAIN = "zigbee"
 CONFLICTS_WITH = ["openthread"]


-def _check_report_deprecation(value: str) -> str:
-    if str(value).lower() == "coordinator":
-        _LOGGER.warning(
-            "Report option 'coordinator' is deprecated and will be removed in a future release. Use 'default' instead."
-        )
-    return value
-
-
-def _get_base_schema(cluster_options: list[str] | None = None) -> cv.Schema:
-    schema = cv.Schema(
-        {
-            cv.Optional(CONF_REPORT): cv.All(
-                cv.requires_component(DOMAIN),
-                cv.requires_component(ESP32_DOMAIN),
-                _check_report_deprecation,
-                cv.enum(REPORT, lower=True),
-            ),
-            cv.Optional(CONF_ENDPOINT): cv.All(
-                cv.requires_component(DOMAIN),
-                cv.requires_component(ESP32_DOMAIN),
-                cv.int_range(1, CONF_MAX_EP_NUMBER),
-            ),
-            cv.Optional(CONF_USE_DEVICE_TYPE): cv.All(
-                cv.requires_component(DOMAIN),
-                cv.requires_component(ESP32_DOMAIN),
-                cv.boolean,
-            ),
-        }
-    )
-    if cluster_options:
-        schema = cv.Schema(
-            {
-                cv.OnlyWith(
-                    CONF_CLUSTER, ["esp32", "zigbee"], default=cluster_options[0]
-                ): cv.All(
-                    cv.requires_component(DOMAIN),
-                    cv.requires_component(ESP32_DOMAIN),
-                    cv.one_of(*cluster_options, lower=True),
-                ),
-            }
-        ).extend(schema)
-    return schema
-
-
-# set BASE_SCHEMA for CI and backwards compatibility
-BASE_SCHEMA = _get_base_schema()
-
-BINARY_SENSOR_SCHEMA = (
-    cv.Schema({})
-    .extend(_get_base_schema(["generic", "device_class"]))
-    .extend(zephyr_binary_sensor)
-)
+# Defined in esphome.core.entity_helpers so entity base schemas can reference
+# them without importing this package; re-exported here for existing consumers.
+BASE_SCHEMA = entity_helpers.ZIGBEE_BASE_ENTITY_SCHEMA
+BINARY_SENSOR_SCHEMA = entity_helpers.ZIGBEE_BINARY_SENSOR_SCHEMA
 SENSOR_SCHEMA = (
    cv.Schema({})
-    .extend(_get_base_schema(["generic", "device_class"]))
+    .extend(entity_helpers.zigbee_base_entity_schema(["generic", "device_class"]))
    .extend(zephyr_sensor)
 )
 SWITCH_SCHEMA = (
-    cv.Schema({}).extend(_get_base_schema(["generic", "on_off"])).extend(zephyr_switch)
+    cv.Schema({})
+    .extend(entity_helpers.zigbee_base_entity_schema(["generic", "on_off"]))
+    .extend(zephyr_switch)
 )
 NUMBER_SCHEMA = (
-    cv.Schema({}).extend(_get_base_schema(["generic"])).extend(zephyr_number)
+    cv.Schema({})
+    .extend(entity_helpers.zigbee_base_entity_schema(["generic"]))
+    .extend(zephyr_number)
 )


@@ -1,7 +1,15 @@
 from enum import IntEnum

 import esphome.codegen as cg
-from esphome.const import (
+
+# The entity schema keys and report enum live outside this package so
+# entity base schemas can use them without importing it; re-imported here
+# so zigbee code keeps its existing import paths.
+from esphome.const import (  # noqa: F401  # pylint: disable=unused-import
+    CONF_CLUSTER,
+    CONF_ENDPOINT,
+    CONF_REPORT,
+    CONF_USE_DEVICE_TYPE,
    DEVICE_CLASS_CURRENT,
    DEVICE_CLASS_DURATION,
    DEVICE_CLASS_ENERGY,
@@ -48,6 +56,10 @@ from esphome.const import (
    UNIT_WATT,
    UNIT_WATT_HOURS,
 )
+from esphome.core.entity_helpers import (  # noqa: F401  # pylint: disable=unused-import
+    ZIGBEE_MAX_EP_NUMBER as CONF_MAX_EP_NUMBER,
+    ZIGBEE_REPORT as REPORT,
+)

 zigbee_ns = cg.esphome_ns.namespace("zigbee")
 ZigbeeComponent = zigbee_ns.class_("ZigbeeComponent", cg.Component)
@@ -56,21 +68,11 @@ BinaryAttrs = zigbee_ns.struct("BinaryAttrs")
 AnalogAttrs = zigbee_ns.struct("AnalogAttrs")
 AnalogAttrsOutput = zigbee_ns.struct("AnalogAttrsOutput")

-report = zigbee_ns.enum("ZigbeeReportT")
-REPORT = report.options(
-    "coordinator", "enable", "force", "default", prefix="ZIGBEE_REPORT_"
-)
-
-CONF_CLUSTER = "cluster"
-CONF_ENDPOINT = "endpoint"
-CONF_MAX_EP_NUMBER = 239
 CONF_ON_JOIN = "on_join"
 CONF_WIPE_ON_BOOT = "wipe_on_boot"
-CONF_REPORT = "report"
 CONF_ROUTER = "router"
 CONF_POWER_SOURCE = "power_source"
 CONF_SLEEPY = "sleepy"
-CONF_USE_DEVICE_TYPE = "use_device_type"
 POWER_SOURCE = {
    "UNKNOWN": 0x00,  # ZB_ZCL_BASIC_POWER_SOURCE_UNKNOWN
    "MAINS_SINGLE_PHASE": 0x01,  # ZB_ZCL_BASIC_POWER_SOURCE_MAINS_SINGLE_PHASE
@@ -1,6 +1,8 @@
+# These two schema keys live in esphome.const so entity base
+# schemas can use them without importing this package.
+from esphome.const import CONF_ZIGBEE_BINARY_SENSOR, CONF_ZIGBEE_ID  # noqa: F401  # pylint: disable=unused-import
+
 CONF_MAX_EP_NUMBER_ZEPHYR = 8
-CONF_ZIGBEE_ID = "zigbee_id"
-CONF_ZIGBEE_BINARY_SENSOR = "zigbee_binary_sensor"
 CONF_ZIGBEE_SENSOR = "zigbee_sensor"
 CONF_ZIGBEE_SWITCH = "zigbee_switch"
 CONF_ZIGBEE_NUMBER = "zigbee_number"
@@ -60,15 +60,6 @@ ZigbeeSensor = zigbee_ns.class_("ZigbeeSensor", cg.Component)
 ZigbeeSwitch = zigbee_ns.class_("ZigbeeSwitch", cg.Component)
 ZigbeeNumber = zigbee_ns.class_("ZigbeeNumber", cg.Component)

-zephyr_binary_sensor = cv.Schema(
-    {
-        cv.OnlyWith(CONF_ZIGBEE_ID, ["nrf52", "zigbee"]): cv.use_id(ZigbeeComponent),
-        cv.OnlyWith(CONF_ZIGBEE_BINARY_SENSOR, ["nrf52", "zigbee"]): cv.declare_id(
-            ZigbeeBinarySensor
-        ),
-    }
-)
-
 zephyr_sensor = cv.Schema(
    {
        cv.OnlyWith(CONF_ZIGBEE_ID, ["nrf52", "zigbee"]): cv.use_id(ZigbeeComponent),
@@ -267,6 +267,7 @@ CONF_CLOCK_RESOLUTION = "clock_resolution"
 CONF_CLOSE_ACTION = "close_action"
 CONF_CLOSE_DURATION = "close_duration"
 CONF_CLOSE_ENDSTOP = "close_endstop"
+CONF_CLUSTER = "cluster"
 CONF_CO2 = "co2"
 CONF_CODE = "code"
 CONF_COL = "col"
@@ -405,6 +406,7 @@ CONF_ENABLE_PRIVATE_NETWORK_ACCESS = "enable_private_network_access"
 CONF_ENABLE_RRM = "enable_rrm"
 CONF_ENABLE_TIME = "enable_time"
 CONF_ENCRYPTION = "encryption"
+CONF_ENDPOINT = "endpoint"
 CONF_ENERGY = "energy"
 CONF_ENTITY_CATEGORY = "entity_category"
 CONF_ENTITY_ID = "entity_id"
@@ -903,6 +905,7 @@ CONF_REFERENCE_VOLTAGE = "reference_voltage"
 CONF_REFRESH = "refresh"
 CONF_RELABEL = "relabel"
 CONF_REPEAT = "repeat"
+CONF_REPORT = "report"
 CONF_REPOSITORY = "repository"
 CONF_RESET = "reset"
 CONF_RESET_DURATION = "reset_duration"
@@ -980,6 +983,8 @@ CONF_SLEEP_DURATION = "sleep_duration"
 CONF_SLEEP_PIN = "sleep_pin"
 CONF_SLEEP_WHEN_DONE = "sleep_when_done"
 CONF_SONY = "sony"
+CONF_SORTING_GROUP_ID = "sorting_group_id"
+CONF_SORTING_WEIGHT = "sorting_weight"
 CONF_SOURCE = "source"
 CONF_SOURCE_ID = "source_id"
 CONF_SPEAKER = "speaker"
@@ -1111,6 +1116,7 @@ CONF_UPDATE_ON_BOOT = "update_on_boot"
 CONF_URL = "url"
 CONF_USE_ABBREVIATIONS = "use_abbreviations"
 CONF_USE_ADDRESS = "use_address"
+CONF_USE_DEVICE_TYPE = "use_device_type"
 CONF_USE_DMA = "use_dma"
 CONF_USE_FAHRENHEIT = "use_fahrenheit"
 CONF_USERNAME = "username"
@@ -1162,6 +1168,8 @@ CONF_Y = "y"
 CONF_Y_GRID = "y_grid"
 CONF_YEAR = "year"
 CONF_ZERO = "zero"
+CONF_ZIGBEE_BINARY_SENSOR = "zigbee_binary_sensor"
+CONF_ZIGBEE_ID = "zigbee_id"

 TYPE_GIT = "git"
 TYPE_LOCAL = "local"
@@ -297,6 +297,7 @@
 #define USE_STATUS_LED
 #define USE_STATUS_SENSOR
 #define USE_SWITCH
+#define USE_SWITCH_STORAGE
 #define USE_TEXT
 #define USE_TEXT_SENSOR
 #define USE_TEXT_SENSOR_FILTER
@@ -1,6 +1,8 @@
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 import functools
+from importlib import import_module
+from importlib.util import find_spec
 import logging
 import re
 from typing import Any, Literal
@@ -9,15 +11,26 @@ from esphome.automation import apply_static_function, parent_ref
 import esphome.codegen as cg
 import esphome.config_validation as cv
 from esphome.const import (
+    CONF_CLUSTER,
    CONF_DEVICE_CLASS,
    CONF_DEVICE_ID,
    CONF_DISABLED_BY_DEFAULT,
+    CONF_ENDPOINT,
    CONF_ENTITY_CATEGORY,
    CONF_ICON,
    CONF_ID,
    CONF_INTERNAL,
+    CONF_MQTT_ID,
    CONF_NAME,
+    CONF_REPORT,
+    CONF_SORTING_GROUP_ID,
+    CONF_SORTING_WEIGHT,
    CONF_UNIT_OF_MEASUREMENT,
+    CONF_USE_DEVICE_TYPE,
+    CONF_WEB_SERVER,
+    CONF_WEB_SERVER_ID,
+    CONF_ZIGBEE_BINARY_SENSOR,
+    CONF_ZIGBEE_ID,
 )
 from esphome.core import CORE, ID, CoroPriority, coroutine_with_priority
 from esphome.core.config import (
@@ -42,6 +55,7 @@ from esphome.helpers import (
    sanitize,
    snake_case,
 )
+from esphome.schema_extractors import SCHEMA_EXTRACT, schema_extractor
 from esphome.types import ConfigType, EntityMetadata, Expression, SafeExpType

 _LOGGER = logging.getLogger(__name__)
@@ -764,3 +778,219 @@ def entity_duplicate_validator(platform: str) -> Callable[[ConfigType], ConfigTy
        return config

    return validator
+
+
+# restore_state: keywords, shared by the entity domains that save their state
+RESTORE_STATE_KEEP = "KEEP"
+RESTORE_STATE_INVERT = "INVERT"
+RESTORE_STATE_INITIAL = "INITIAL"
+RESTORE_STATE_ALL = "ALL"
+RESTORE_STATE_NONE = "NONE"
+
+
+def restore_state_keyword(value: Any, keywords: tuple[str, ...]) -> str | None:
+    """The upper-cased keyword when `value` spells one of `keywords`, else None."""
+    if isinstance(value, str):
+        upper = value.strip().upper()
+        if upper in keywords:
+            return upper
+    return None
+
+
+def restore_state_schema(fields_schema: cv.Schema, none: Any) -> Callable[[Any], Any]:
+    """The validator for a domain's `restore_state:` key.
+
+    A mapping is validated with `fields_schema`. The shorthand `all` is the empty mapping,
+    so every field keeps its saved value, and `none` is returned as it is; a mapping goes through
+    `fields_schema` like one the user wrote, so each config gets its own copy.
+    """
+
+    @schema_extractor("schema")
+    def validate(value: Any) -> Any:
+        if value == SCHEMA_EXTRACT:
+            # The shorthands have no representation in the extracted schema
+            return fields_schema
+        keyword = restore_state_keyword(value, (RESTORE_STATE_ALL, RESTORE_STATE_NONE))
+        if keyword == RESTORE_STATE_ALL:
+            value = {}
+        elif keyword == RESTORE_STATE_NONE:
+            if not isinstance(none, dict):
+                return none
+            value = none
+        elif isinstance(value, str):
+            raise cv.Invalid(
+                f"Unknown restore_state '{value}'; expected 'all', 'none' or a mapping, "
+                "for example '{state: INVERT}'"
+            )
+        return fields_schema(value)
+
+    return validate
+
+
+# ---------------------------------------------------------------------------
+# Cross-integration entity schema fragments
+# ---------------------------------------------------------------------------
+#
+# Entity base schemas offer mqtt/web_server/zigbee options, but importing
+# those packages pulls their full dependency chains (mqtt and zigbee both
+# import the esp32 package) into every entity component import. The
+# fragments below are built from cheap primitives instead: MockObjClass
+# identity is string-based, so the class handles here are interchangeable
+# with the ones the integrations declare, and every key is guarded by
+# ``cv.requires_component``/``cv.OnlyWith``, which consult
+# ``CORE.loaded_integrations`` at validation time without importing. The
+# owning integrations re-export the shared schema names and key strings so
+# each stays defined once.
+
+_WebServer = cg.esphome_ns.namespace("web_server").class_("WebServer", cg.Component)
+
+WEBSERVER_SORTING_SCHEMA = cv.Schema(
+    {
+        # The per-entity web_server block is cosmetic dashboard ordering —
+        # mark the whole block advanced; the children inherit via the cascade.
+        cv.Optional(CONF_WEB_SERVER, visibility=cv.Visibility.ADVANCED): cv.Schema(
+            {
+                cv.OnlyWith(CONF_WEB_SERVER_ID, "web_server"): cv.use_id(_WebServer),
+                cv.Optional(CONF_SORTING_WEIGHT): cv.All(
+                    cv.requires_component("web_server"),
+                    cv.float_,
+                ),
+                cv.Optional(CONF_SORTING_GROUP_ID): cv.All(
+                    cv.requires_component("web_server"),
+                    cv.use_id(cg.int_),
+                ),
+            }
+        )
+    }
+)
+
+_mqtt_ns = cg.esphome_ns.namespace("mqtt")
+_MQTTComponent = _mqtt_ns.class_("MQTTComponent", cg.Component)
+
+
+def mqtt_component_class(name: str) -> MockObjClass:
+    """Handle for a per-entity mqtt::<name> companion class."""
+    return _mqtt_ns.class_(name, _MQTTComponent)
+
+
+ZIGBEE_MAX_EP_NUMBER = 239
+
+_zigbee_ns = cg.esphome_ns.namespace("zigbee")
+_ZigbeeComponent = _zigbee_ns.class_("ZigbeeComponent", cg.Component)
+ZIGBEE_REPORT = _zigbee_ns.enum("ZigbeeReportT").options(
+    "coordinator", "enable", "force", "default", prefix="ZIGBEE_REPORT_"
+)
+
+
+def _check_report_deprecation(value: str) -> str:
+    if str(value).lower() == "coordinator":
+        _LOGGER.warning(
+            "Report option 'coordinator' is deprecated and will be removed in a future release. Use 'default' instead."
+        )
+    return value
+
+
+def zigbee_base_entity_schema(cluster_options: list[str] | None = None) -> cv.Schema:
+    """Zigbee options every entity offers; ``cluster_options`` adds the esp32 cluster key."""
+    schema = cv.Schema(
+        {
+            cv.Optional(CONF_REPORT): cv.All(
+                cv.requires_component("zigbee"),
+                cv.requires_component("esp32"),
+                _check_report_deprecation,
+                cv.enum(ZIGBEE_REPORT, lower=True),
+            ),
+            cv.Optional(CONF_ENDPOINT): cv.All(
+                cv.requires_component("zigbee"),
+                cv.requires_component("esp32"),
+                cv.int_range(1, ZIGBEE_MAX_EP_NUMBER),
+            ),
+            cv.Optional(CONF_USE_DEVICE_TYPE): cv.All(
+                cv.requires_component("zigbee"),
+                cv.requires_component("esp32"),
+                cv.boolean,
+            ),
+        }
+    )
+    if cluster_options:
+        schema = cv.Schema(
+            {
+                cv.OnlyWith(
+                    CONF_CLUSTER, ["esp32", "zigbee"], default=cluster_options[0]
+                ): cv.All(
+                    cv.requires_component("zigbee"),
+                    cv.requires_component("esp32"),
+                    cv.one_of(*cluster_options, lower=True),
+                ),
+            }
+        ).extend(schema)
+    return schema
+
+
+ZIGBEE_BASE_ENTITY_SCHEMA = zigbee_base_entity_schema()
+
+# Entity platform -> (config key, zigbee C++ class, esp32 cluster options). A
+# unit test checks each class against the owning declaration in zigbee_zephyr.
+_ZIGBEE_ENTITY_CLASSES = {
+    "binary_sensor": (
+        CONF_ZIGBEE_BINARY_SENSOR,
+        "ZigbeeBinarySensor",
+        ["generic", "device_class"],
+    ),
+}
+
+
+def _zigbee_entity_schema(platform: str) -> cv.Schema:
+    conf_key, class_name, cluster_options = _ZIGBEE_ENTITY_CLASSES[platform]
+    return zigbee_base_entity_schema(cluster_options).extend(
+        {
+            cv.OnlyWith(CONF_ZIGBEE_ID, ["nrf52", "zigbee"]): cv.use_id(
+                _ZigbeeComponent
+            ),
+            cv.OnlyWith(conf_key, ["nrf52", "zigbee"]): cv.declare_id(
+                _zigbee_ns.class_(class_name, cg.Component)
+            ),
+        }
+    )
+
+
+ZIGBEE_BINARY_SENSOR_SCHEMA = _zigbee_entity_schema("binary_sensor")
+
+
+def lazy_load_validator(
+    component: str, name: str
+) -> Callable[[ConfigType], ConfigType]:
+    """Schema extra delegating to ``components.<component>.<name>`` when loaded."""
+    if find_spec(f"esphome.components.{component}") is None:
+        raise ValueError(f"No such component {component!r}")
+
+    def validator(config: ConfigType) -> ConfigType:
+        if component not in CORE.loaded_integrations:
+            return config
+        module = import_module(f"esphome.components.{component}")
+        if (delegate := getattr(module, name, None)) is None:
+            raise ValueError(f"{component} has no validator {name!r}")
+        return delegate(config)
+
+    return validator
+
+
+async def setup_entity_integrations(var: MockObj, config: ConfigType) -> MockObj | None:
+    """Register the mqtt companion and web_server entry for an entity.
+
+    Imports the integrations lazily; returns the mqtt companion (or None)
+    so callers can apply integration specific options to it.
+    """
+    mqtt_ = None
+    if (mqtt_id := config.get(CONF_MQTT_ID)) is not None:
+        from esphome.components import mqtt
+
+        mqtt_ = cg.new_Pvariable(mqtt_id, var)
+        await mqtt.register_mqtt_component(mqtt_, config)
+
+    if web_server_config := config.get(CONF_WEB_SERVER):
+        from esphome.components import web_server
+
+        await web_server.add_entity_config(var, web_server_config)
+
+    return mqtt_
@@ -792,7 +792,7 @@ def lint_unit_constants_usage():
 # Maximum allowed CONF_ constants in esphome/const.py.
 # This file is frozen — new constants go in esphome/components/const/__init__.py.
 # Decrease this number when constants are moved out of const.py.
-CONST_PY_MAX_CONF = 1016
+CONST_PY_MAX_CONF = 1024


@lint_content_check(include=["esphome/const.py"])
@@ -32,8 +32,10 @@ from esphome.components.esp32 import (
    _user_sdkconfig_wants_tls,
    allow_insecure_tls,
    idf_version,
+    require_idf_version,
 )
 from esphome.components.esp32.const import (
+    KEY_BOARD,
    KEY_ESP32,
    KEY_EXCLUDE_COMPONENTS,
    KEY_IDF_VERSION,
@@ -2442,3 +2444,44 @@ def test_allow_insecure_tls_only_switches_the_flags_on(
        "CONFIG_ESP_TLS_INSECURE": True,
        "CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY": True,
    }
+
+
+@pytest.mark.parametrize(
+    ("platform_framework", "idf", "ok"),
+    [
+        (PlatformFramework.ESP32_IDF, cv.Version(5, 5, 3), True),
+        (PlatformFramework.ESP32_IDF, cv.Version(5, 5, 2), False),
+        (PlatformFramework.ESP32_ARDUINO, cv.Version(5, 5, 3), True),
+        (PlatformFramework.ESP32_ARDUINO, cv.Version(5, 5, 2), False),
+    ],
+)
+def test_require_idf_version_compares_the_idf_underneath(
+    set_core_config: SetCoreConfigCallable,
+    platform_framework: PlatformFramework,
+    idf: cv.Version,
+    ok: bool,
+) -> None:
+    set_core_config(
+        platform_framework,
+        platform_data={
+            KEY_BOARD: "esp32dev",
+            KEY_VARIANT: VARIANT_ESP32,
+            KEY_IDF_VERSION: idf,
+        },
+    )
+    validator = require_idf_version(cv.Version(5, 5, 3), "The thing")
+    if ok:
+        assert validator("x") == "x"
+    else:
+        with pytest.raises(
+            cv.Invalid, match="The thing requires ESP-IDF 5.5.3 or newer, got 5.5.2"
+        ):
+            validator("x")
+
+
+def test_require_idf_version_rejects_other_platforms(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    set_core_config(PlatformFramework.ESP8266_ARDUINO)
+    with pytest.raises(cv.Invalid, match="only available on"):
+        require_idf_version(cv.Version(5, 5, 3))("x")
@@ -0,0 +1,12 @@
+---
+esphome:
+  name: test
+
+esp32:
+  board: esp32dev
+
+logger:
+
+switch:
+  - {platform: template, id: legacy, optimistic: true, restore_mode: RESTORE_DEFAULT_OFF}
+  - {platform: template, id: plain, optimistic: true}
@@ -0,0 +1,20 @@
+---
+esphome:
+  name: test
+
+esp32:
+  board: esp32dev
+
+logger:
+
+switch:
+  - {platform: template, id: keep_rtc, optimistic: true, initial_state: ON, restore_state: {state: KEEP, storage: rtc}}
+  - {platform: template, id: keep_flash, optimistic: true, restore_state: {state: KEEP, storage: flash}}
+  - {platform: template, id: keep_short, optimistic: true, restore_state: {state: KEEP}}
+  - {platform: template, id: all_short, optimistic: true, restore_state: ALL}
+  - {platform: template, id: invert_on, optimistic: true, initial_state: ON, restore_state: {state: INVERT}}
+  - {platform: template, id: initial_on, optimistic: true, initial_state: ON, restore_state: {state: INITIAL}}
+  - {platform: template, id: none_on, optimistic: true, initial_state: ON, restore_state: NONE}
+  - {platform: template, id: initial_only, optimistic: true, initial_state: ON}
+  - {platform: template, id: legacy, optimistic: true, restore_mode: RESTORE_DEFAULT_OFF}
+  - {platform: template, id: plain, optimistic: true}
@@ -0,0 +1,12 @@
+---
+esphome:
+  name: test
+
+esp8266:
+  board: esp12e
+  restore_from_flash: true
+
+logger:
+
+switch:
+  - {platform: template, id: keep_rtc, optimistic: true, initial_state: ON, restore_state: {state: KEEP, storage: rtc}}
@@ -0,0 +1,216 @@
+"""Tests for switch `initial_state` / `restore_state` (including `storage`)."""
+
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+
+from esphome.components import switch
+from esphome.components.libretiny.const import (
+    FAMILY_BK7231T,
+    FAMILY_BK7251,
+    FAMILY_LN882H,
+    FAMILY_RTL8720C,
+    KEY_FAMILY,
+    KEY_LIBRETINY,
+)
+import esphome.config_validation as cv
+from esphome.const import PlatformFramework
+from esphome.core import CORE
+from tests.component_tests.types import SetCoreConfigCallable
+
+GATE = "USE_SWITCH_STORAGE"
+ESP32_RTC = "USE_ESP32_RTC_PREFERENCES"
+
+
+def _defines() -> set[str]:
+    return {define.name for define in CORE.defines}
+
+
+@pytest.mark.parametrize(
+    ("switch_id", "mode"),
+    [
+        ("keep_short", "SWITCH_RESTORE_DEFAULT_OFF"),
+        ("all_short", "SWITCH_RESTORE_DEFAULT_OFF"),
+        ("invert_on", "SWITCH_RESTORE_INVERTED_DEFAULT_ON"),
+        ("initial_on", "SWITCH_ALWAYS_ON"),
+        ("none_on", "SWITCH_ALWAYS_ON"),
+        ("initial_only", "SWITCH_ALWAYS_ON"),
+        ("legacy", "SWITCH_RESTORE_DEFAULT_OFF"),
+        ("plain", "SWITCH_ALWAYS_OFF"),
+    ],
+)
+def test_restore_state_maps_to_a_restore_mode(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+    switch_id: str,
+    mode: str,
+) -> None:
+    """Every initial_state / restore_state combination becomes one existing restore mode."""
+    main_cpp = generate_main(component_config_path("restore_state_esp32.yaml"))
+
+    assert f"{switch_id}->set_restore_mode(switch_::{mode});" in main_cpp
+
+
+def test_storage_is_passed_only_when_set(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+) -> None:
+    main_cpp = generate_main(component_config_path("restore_state_esp32.yaml"))
+
+    assert (
+        "keep_rtc->set_restore_mode(static_cast<switch_::SwitchRestoreMode>("
+        "switch_::SWITCH_RESTORE_DEFAULT_ON | switch_::RESTORE_MODE_STORAGE_RTC_MASK));"
+    ) in main_cpp
+    assert (
+        "keep_flash->set_restore_mode(static_cast<switch_::SwitchRestoreMode>("
+        "switch_::SWITCH_RESTORE_DEFAULT_OFF | switch_::RESTORE_MODE_STORAGE_FLASH_MASK));"
+    ) in main_cpp
+    assert (
+        "keep_short->set_restore_mode(switch_::SWITCH_RESTORE_DEFAULT_OFF);" in main_cpp
+    )
+    assert GATE in _defines()
+    assert ESP32_RTC in _defines()
+
+
+def test_nothing_new_emitted_without_restore_state(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+) -> None:
+    """Configs using only restore_mode generate exactly what they did before."""
+    main_cpp = generate_main(component_config_path("restore_state_absent_esp32.yaml"))
+
+    assert "RESTORE_MODE_STORAGE_" not in main_cpp
+    assert GATE not in _defines()
+    assert ESP32_RTC not in _defines()
+
+
+def test_rtc_applies_per_switch_on_esp8266_with_restore_from_flash(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+) -> None:
+    main_cpp = generate_main(component_config_path("restore_state_esp8266.yaml"))
+
+    assert (
+        "keep_rtc->set_restore_mode(static_cast<switch_::SwitchRestoreMode>("
+        "switch_::SWITCH_RESTORE_DEFAULT_ON | switch_::RESTORE_MODE_STORAGE_RTC_MASK));"
+    ) in main_cpp
+    assert ESP32_RTC not in _defines()
+
+
+def _validate(config: dict, *, default_restore_mode: str = cv.UNDEFINED) -> dict:
+    schema = switch.switch_schema(
+        switch.Switch, default_restore_mode=default_restore_mode
+    )
+    return schema({"id": "test_switch", **config})
+
+
+@pytest.fixture
+def esp8266(set_core_config: SetCoreConfigCallable) -> None:
+    set_core_config(PlatformFramework.ESP8266_ARDUINO)
+
+
+@pytest.mark.usefixtures("esp8266")
+def test_restore_mode_and_restore_state_are_exclusive() -> None:
+    with pytest.raises(cv.Invalid, match="restore"):
+        _validate({"restore_mode": "RESTORE_DEFAULT_OFF", "restore_state": "all"})
+
+
+@pytest.mark.usefixtures("esp8266")
+def test_initial_state_rejected_with_restore_mode() -> None:
+    """restore_mode already decides the boot state, so initial_state would be ignored."""
+    with pytest.raises(cv.Invalid, match="initial_state"):
+        _validate({"restore_mode": "ALWAYS_OFF", "initial_state": True})
+
+
+@pytest.mark.usefixtures("esp8266")
+def test_storage_rejected_when_nothing_is_restored() -> None:
+    with pytest.raises(cv.Invalid, match="only applies"):
+        _validate({"restore_state": {"state": "INITIAL", "storage": "rtc"}})
+
+
+@pytest.mark.usefixtures("esp8266")
+@pytest.mark.parametrize("value", ["RESTORE", "ON", "OFF", "KEEP", "INVERT", "INITIAL"])
+def test_unsupported_restore_state_values_rejected(value: object) -> None:
+    # Only light's shorthands (all, none) are accepted as a string
+    with pytest.raises(cv.Invalid, match="expected 'all', 'none' or a mapping"):
+        _validate({"restore_state": value})
+
+
+@pytest.mark.usefixtures("esp8266")
+@pytest.mark.parametrize("state", [True, False, "ON", "off"])
+def test_restore_state_on_off_explains_what_to_use(state: object) -> None:
+    # Valid on light, so people will try it; YAML turns ON into True
+    with pytest.raises(
+        cv.Invalid, match="initial_state: ON' \\(or OFF\\) with 'restore_state: none'"
+    ):
+        _validate({"restore_state": {"state": state}})
+
+
+@pytest.mark.parametrize(
+    ("platform", "family"),
+    [
+        (PlatformFramework.BK72XX_ARDUINO, FAMILY_BK7251),
+        (PlatformFramework.RTL87XX_ARDUINO, FAMILY_RTL8720C),
+        (PlatformFramework.LN882X_ARDUINO, FAMILY_LN882H),
+        (PlatformFramework.RP2040_ARDUINO, None),
+        (PlatformFramework.NRF52_ZEPHYR, None),
+        (PlatformFramework.HOST_NATIVE, None),
+    ],
+)
+def test_rtc_rejected_without_an_rtc_backend(
+    set_core_config: SetCoreConfigCallable,
+    platform: PlatformFramework,
+    family: str | None,
+) -> None:
+    """These preferences backends ignore in_flash, so the state would silently stay in flash."""
+    set_core_config(platform)
+    if family is not None:
+        CORE.data[KEY_LIBRETINY] = {KEY_FAMILY: family}
+    with pytest.raises(cv.Invalid, match="'rtc' storage is not supported"):
+        _validate({"restore_state": {"state": "KEEP", "storage": "rtc"}})
+
+
+def test_rtc_accepted_on_a_beken_chip_with_the_emulation(
+    set_core_config: SetCoreConfigCallable,
+) -> None:
+    set_core_config(PlatformFramework.BK72XX_ARDUINO)
+    CORE.data[KEY_LIBRETINY] = {KEY_FAMILY: FAMILY_BK7231T}
+    _validate({"restore_state": {"state": "KEEP", "storage": "rtc"}})
+
+
+@pytest.mark.usefixtures("esp8266")
+def test_rtc_accepted_on_esp8266() -> None:
+    _validate({"restore_state": {"state": "KEEP", "storage": "rtc"}})
+
+
+@pytest.mark.usefixtures("esp8266")
+def test_platform_default_restore_mode_applies_only_when_nothing_is_set() -> None:
+    """Platforms such as haier default to DISABLED; restore_state must still be usable there."""
+    assert _validate({}, default_restore_mode="DISABLED")["restore_mode"] == "DISABLED"
+    configured = _validate({"restore_state": "all"}, default_restore_mode="DISABLED")
+    assert "restore_mode" not in configured
+
+
+@pytest.mark.usefixtures("esp8266")
+@pytest.mark.parametrize(
+    ("default_restore_mode", "initial_state", "expected"),
+    [
+        # A restoring default keeps restoring; initial_state only replaces its fallback
+        ("RESTORE_DEFAULT_ON", False, "RESTORE_DEFAULT_OFF"),
+        ("RESTORE_DEFAULT_OFF", True, "RESTORE_DEFAULT_ON"),
+        ("RESTORE_INVERTED_DEFAULT_OFF", True, "RESTORE_INVERTED_DEFAULT_ON"),
+        # A default that restores nothing starts in initial_state
+        ("ALWAYS_OFF", True, "ALWAYS_ON"),
+        ("DISABLED", True, "ALWAYS_ON"),
+    ],
+)
+def test_initial_state_alone_keeps_a_restoring_platform_default(
+    default_restore_mode: str, initial_state: bool, expected: str
+) -> None:
+    config = _validate(
+        {"initial_state": initial_state}, default_restore_mode=default_restore_mode
+    )
+    assert "restore_mode" not in config
+    assert "storage" not in config.get("restore_state", {})
+    assert switch._resolve_restore_mode(config) is switch.RESTORE_MODES[expected]
@@ -168,5 +168,5 @@ def test_final_validate_needs_idf_5_5(
 ) -> None:
    _set_variant(set_core_config, VARIANT_ESP32S3, idf=idf)
    usb_host.request_periodic_fifo(out_bytes=196)
-    with pytest.raises(cv.Invalid, match="needs ESP-IDF 5.5.0 or later"):
+    with pytest.raises(cv.Invalid, match="requires ESP-IDF 5.5.0 or newer"):
        usb_host.FINAL_VALIDATE_SCHEMA({})
@@ -14,3 +14,8 @@ esphome:
          then:
            - deep_sleep.enter:
                sleep_duration: 60min
+      - if:
+          condition:
+            lambda: 'return deep_sleep::woke_from_deep_sleep();'
+          then:
+            - logger.log: Woke from deep sleep
@@ -19,11 +19,6 @@ image:
        } else {
          ESP_LOGD("online_image", "Cache miss: fresh download");
        }
-    on_download_started:
-      - logger.log: Download started
-    on_download_progress:
-      lambda: |-
-        ESP_LOGD("online_image", "Downloaded %.0f%% (%zu bytes)", progress, bytes_read);
  - platform: online_image
    id: online_binary_transparent_image
    url: http://www.libpng.org/pub/png/img_png/pnglogo-blk-tiny.png
@@ -2,7 +2,6 @@

 #include <algorithm>
 #include <array>
-#include <cmath>
 #include <cstdint>
 #include <cstring>
 #include <memory>
@@ -28,9 +27,6 @@ class FakeContainer : public http_request::HttpContainer {
  }

  int read(uint8_t *buf, size_t max_len) override {
-    this->largest_read = std::max(this->largest_read, max_len);
-    if (this->read_error_)
-      return -1;
    size_t len = std::min(max_len, this->available_ - this->bytes_read_);
    std::memcpy(buf, this->body_.data() + this->bytes_read_, len);
    this->bytes_read_ += len;
@@ -46,21 +42,13 @@ class FakeContainer : public http_request::HttpContainer {
  }

  void set_content_length(size_t length) { this->content_length = length; }
-  /// Make every read from now on fail, like a dropped connection
-  void fail_reads() { this->read_error_ = true; }
-  /// Let len more bytes of the body arrive
-  void deliver(size_t len) { this->available_ = std::min(this->body_.size(), this->available_ + len); }
  void add_response_header(const std::string &name, const std::string &value) {
    this->response_headers_.push_back({name, value});
  }

-  /// The most bytes any one read() asked for
-  size_t largest_read{0};
-
 protected:
  std::vector<uint8_t> body_;
  size_t available_;
-  bool read_error_{false};
 };

 class FakeHttpRequest : public http_request::HttpRequestComponent {
@@ -135,173 +123,13 @@ static constexpr std::array<uint8_t, 69> PNG_1X1{
    0x0C, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9C, 0x63, 0xF8, 0xCF, 0xC0, 0x00, 0x00, 0x03, 0x01, 0x01, 0x00, 0xC9,
    0xFE, 0x92, 0xEF, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4E, 0x44, 0xAE, 0x42, 0x60, 0x82};

-// 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,
-};
-
-// 48x40 4:2:0 JPEG (quality 95), 2344 bytes: three rows of 16 pixel MCUs, with the scan starting at byte 609
-static const uint8_t JPEG_48X40[] = {
-    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,
-};
-
 static void set_loop_time(uint32_t now) { LoopBlockingGuard clock(nullptr, LOG_STR("test"), now); }

 class OnlineImageDownloadEnd : public ::testing::Test {
 protected:
-  std::unique_ptr<OnlineImage> make_image_(runtime_image::ImageFormat format, uint32_t buffer_size = 256) {
+  std::unique_ptr<OnlineImage> make_image_(runtime_image::ImageFormat format) {
    auto img = std::make_unique<OnlineImage>("http://example.com/image", 0, 0, format, image::IMAGE_TYPE_RGB,
-                                             image::TRANSPARENCY_OPAQUE, nullptr, buffer_size);
+                                             image::TRANSPARENCY_OPAQUE, nullptr, 256);
    img->set_parent(&this->http_);
    return img;
  }
@@ -458,294 +286,4 @@ TEST_F(OnlineImageDownloadEnd, JpegBufferAllocationFailureReportsError) {
  EXPECT_EQ(this->finished_, 0);
 }

-// The JPEG decoded with all of it in memory at once, to compare the downloaded images with
-static std::vector<uint8_t> reference_jpeg_pixels() {
-  runtime_image::RuntimeImage ref(runtime_image::JPEG, image::IMAGE_TYPE_RGB, image::TRANSPARENCY_OPAQUE);
-  std::vector<uint8_t> data(JPEG_48X40, JPEG_48X40 + sizeof(JPEG_48X40));
-  EXPECT_TRUE(ref.begin_decode(data.size()));
-  EXPECT_EQ(ref.feed_data(data.data(), data.size()), static_cast<int>(data.size()));
-  EXPECT_TRUE(ref.end_decode());
-  return std::vector<uint8_t>(ref.get_data_start(), ref.get_data_start() + ref.get_width_stride() * ref.get_height());
-}
-
-static std::vector<uint8_t> image_pixels(OnlineImage &image) {
-  return std::vector<uint8_t>(image.get_data_start(),
-                              image.get_data_start() + image.get_width_stride() * image.get_height());
-}
-
-// A JPEG of known size is decoded as it arrives, so a buffer smaller than the file only has to hold the headers
-TEST_F(OnlineImageDownloadEnd, JpegDecodesThroughASmallBuffer) {
-  auto image = this->make_image_(runtime_image::JPEG, 1024);
-  // Bytes after the image are never needed. Waiting for the whole file before decoding would read them all.
-  std::vector<uint8_t> body(JPEG_48X40, JPEG_48X40 + sizeof(JPEG_48X40));
-  body.resize(body.size() + 8192, 0);
-  auto container = std::make_shared<FakeContainer>(body, body.size(), false);
-  container->add_response_header("etag", "\"abc\"");
-  this->start_(*image, container);
-
-  for (int i = 0; i < 100 && this->finished_ + this->errors_ == 0; i++)
-    image->loop();
-
-  ASSERT_EQ(this->finished_, 1);
-  EXPECT_LT(container->get_bytes_read(), body.size()) << "the image was not decoded as it arrived";
-  EXPECT_EQ(this->errors_, 0);
-  ASSERT_EQ(image->get_width(), 48);
-  ASSERT_EQ(image->get_height(), 40);
-  EXPECT_EQ(image_pixels(*image), reference_jpeg_pixels());
-
-  // A complete image is cached
-  this->http_.next = std::make_shared<FakeContainer>(std::vector<uint8_t>{}, 0, false);
-  image->update();
-  EXPECT_TRUE(this->http_.sent_header("if-none-match"));
-}
-
-// A read() waits for every byte it asks for, so a large buffer is filled a little at a time rather than in one
-// read that blocks the loop until the whole buffer has arrived
-TEST_F(OnlineImageDownloadEnd, JpegReadsInSmallPiecesWithALargeBuffer) {
-  auto image = this->make_image_(runtime_image::JPEG, 65536);
-  auto container =
-      std::make_shared<FakeContainer>(std::vector<uint8_t>(JPEG_48X40, JPEG_48X40 + sizeof(JPEG_48X40)), 0, false);
-  this->start_(*image, container);
-
-  for (int i = 0; i < 100 && this->finished_ + this->errors_ == 0; i++) {
-    container->deliver(sizeof(JPEG_48X40));
-    image->loop();
-  }
-
-  ASSERT_EQ(this->finished_, 1);
-  EXPECT_EQ(this->errors_, 0);
-  EXPECT_LE(container->largest_read, READ_CHUNK);
-  EXPECT_EQ(image_pixels(*image), reference_jpeg_pixels());
-}
-
-// A downloaded PNG is read a little at a time too
-TEST_F(OnlineImageDownloadEnd, PngReadsInSmallPiecesWithALargeBuffer) {
-  auto image = this->make_image_(runtime_image::PNG, 65536);
-  std::vector<uint8_t> png(PNG_1X1.begin(), PNG_1X1.end());
-  auto container = std::make_shared<FakeContainer>(png, png.size(), false);
-  this->start_(*image, container);
-
-  for (int i = 0; i < 100 && this->finished_ + this->errors_ == 0; i++)
-    image->loop();
-
-  ASSERT_EQ(this->finished_, 1);
-  EXPECT_EQ(this->errors_, 0);
-  EXPECT_LE(container->largest_read, READ_CHUNK);
-}
-
-// A slow link: the decoder waits part way through the image for the rest to arrive
-TEST_F(OnlineImageDownloadEnd, JpegWaitsForASlowDownload) {
-  auto image = this->make_image_(runtime_image::JPEG, 1024);
-  auto container =
-      std::make_shared<FakeContainer>(std::vector<uint8_t>(JPEG_48X40, JPEG_48X40 + sizeof(JPEG_48X40)), 1024, false);
-  this->start_(*image, container);
-
-  int passes = 0;
-  for (; passes < 1000 && this->finished_ + this->errors_ == 0; passes++) {
-    image->loop();
-    if (passes == 5) {
-      EXPECT_EQ(this->finished_, 0) << "the image cannot be finished before the rest of it arrives";
-    }
-    container->deliver(40);
-  }
-
-  ASSERT_EQ(this->finished_, 1);
-  EXPECT_EQ(this->errors_, 0);
-  EXPECT_GT(passes, 10);
-  EXPECT_EQ(image_pixels(*image), reference_jpeg_pixels());
-}
-
-// A download that stops part way through times out rather than waiting for ever
-TEST_F(OnlineImageDownloadEnd, JpegDownloadThatStopsTimesOut) {
-  auto image = this->make_image_(runtime_image::JPEG, 1024);
-  auto container =
-      std::make_shared<FakeContainer>(std::vector<uint8_t>(JPEG_48X40, JPEG_48X40 + sizeof(JPEG_48X40)), 1500, false);
-  set_loop_time(1000);
-  this->start_(*image, container);
-
-  for (int i = 0; i < 10; i++)
-    image->loop();
-  EXPECT_EQ(this->errors_, 0) << "still within the timeout";
-
-  set_loop_time(1000 + this->http_.get_timeout());
-  image->loop();
-  EXPECT_EQ(this->errors_, 1);
-  EXPECT_EQ(this->finished_, 0);
-}
-
-// Headers that do not fit the download buffer cannot be read as the image arrives, so the whole image is
-// downloaded first, keeping the bytes already read
-TEST_F(OnlineImageDownloadEnd, JpegHeadersLargerThanTheBufferDownloadTheWholeImage) {
-  auto image = this->make_image_(runtime_image::JPEG, 256);
-  auto container = std::make_shared<FakeContainer>(std::vector<uint8_t>(JPEG_48X40, JPEG_48X40 + sizeof(JPEG_48X40)),
-                                                   sizeof(JPEG_48X40), false);
-  this->start_(*image, container);
-
-  for (int i = 0; i < 100 && this->finished_ + this->errors_ == 0; i++) {
-    image->loop();
-    container->deliver(256);
-  }
-
-  ASSERT_EQ(this->finished_, 1);
-  EXPECT_EQ(this->errors_, 0);
-  EXPECT_EQ(container->get_bytes_read(), sizeof(JPEG_48X40));
-  EXPECT_EQ(image_pixels(*image), reference_jpeg_pixels());
-}
-
-// The pass that opens the image does not decode any of it
-TEST_F(OnlineImageDownloadEnd, JpegOpensInAPassOfItsOwn) {
-  auto image = this->make_image_(runtime_image::JPEG, 1024);
-  auto container = std::make_shared<FakeContainer>(std::vector<uint8_t>(JPEG_48X40, JPEG_48X40 + sizeof(JPEG_48X40)),
-                                                   sizeof(JPEG_48X40), false);
-  this->start_(*image, container);
-
-  image->loop();
-  EXPECT_EQ(this->finished_ + this->errors_, 0);
-  for (int i = 0; i < 100 && this->finished_ + this->errors_ == 0; i++)
-    image->loop();
-  EXPECT_EQ(this->finished_, 1);
-}
-
-// A progressive JPEG is refused while it downloads, without blaming the buffer size
-TEST_F(OnlineImageDownloadEnd, JpegProgressiveReportsError) {
-  auto image = this->make_image_(runtime_image::JPEG, 256);
-  std::vector<uint8_t> body(JPEG_PROGRESSIVE, JPEG_PROGRESSIVE + sizeof(JPEG_PROGRESSIVE));
-  auto container = std::make_shared<FakeContainer>(body, 256, false);
-  this->start_(*image, container);
-
-  for (int i = 0; i < 10 && this->finished_ + this->errors_ == 0; i++)
-    image->loop();
-
-  EXPECT_EQ(this->errors_, 1);
-  EXPECT_EQ(this->finished_, 0);
-}
-
-// on_download_started fires once the server has accepted the request, before the first progress report, and not
-// for a response that has no image to download
-TEST_F(OnlineImageDownloadEnd, StartedFiresOnlyWhenTheDownloadBegins) {
-  auto image = this->make_image_(runtime_image::JPEG, 1024);
-  std::vector<std::string> events;
-  image->add_on_download_started_callback([&events]() { events.emplace_back("started"); });
-  image->add_on_progress_callback([&events](float, size_t) { events.emplace_back("progress"); });
-  this->start_(*image,
-               std::make_shared<FakeContainer>(std::vector<uint8_t>(JPEG_48X40, JPEG_48X40 + sizeof(JPEG_48X40)),
-                                               sizeof(JPEG_48X40), false));
-  ASSERT_GE(events.size(), 2u);
-  EXPECT_EQ(events[0], "started");
-  EXPECT_EQ(events[1], "progress");
-  for (int i = 0; i < 100 && this->finished_ + this->errors_ == 0; i++)
-    image->loop();
-  EXPECT_EQ(std::count(events.begin(), events.end(), std::string("started")), 1);
-
-  for (int status : {304, 404}) {
-    events.clear();
-    auto container = std::make_shared<FakeContainer>(std::vector<uint8_t>{}, 0, false);
-    container->status_code = status;
-    this->http_.next = container;
-    image->update();
-    EXPECT_TRUE(events.empty()) << "HTTP " << status;
-  }
-}
-
-// Progress starts at 0, is reported at most every 100 ms, and always reaches 100%
-TEST_F(OnlineImageDownloadEnd, ProgressIsReportedAsTheImageDownloads) {
-  auto image = this->make_image_(runtime_image::JPEG, 1024);
-  std::vector<float> reports;
-  image->add_on_progress_callback([&reports](float progress, size_t) { reports.push_back(progress); });
-  auto container =
-      std::make_shared<FakeContainer>(std::vector<uint8_t>(JPEG_48X40, JPEG_48X40 + sizeof(JPEG_48X40)), 100, false);
-  uint32_t now = 1000;
-  set_loop_time(now);
-  this->start_(*image, container);
-  ASSERT_EQ(reports.size(), 1u);
-  EXPECT_EQ(reports[0], 0.0f);
-
-  int passes = 0;
-  for (; passes < 1000 && this->finished_ + this->errors_ == 0; passes++) {
-    now += 50;
-    set_loop_time(now);
-    container->deliver(100);
-    image->loop();
-  }
-
-  ASSERT_EQ(this->finished_, 1);
-  EXPECT_EQ(reports.back(), 100.0f);
-  EXPECT_TRUE(std::is_sorted(reports.begin(), reports.end()));
-  // A report every 100 ms of a 50 ms loop, plus the start and the end
-  EXPECT_LE(reports.size(), static_cast<size_t>(passes / 2 + 2));
-  EXPECT_GT(reports.size(), 3u);
-}
-
-// Without a Content-Length the percentage is unknown, but the bytes read are still reported
-TEST_F(OnlineImageDownloadEnd, ProgressOfAChunkedDownloadHasNoPercentage) {
-  auto image = this->make_image_(runtime_image::PNG);
-  std::vector<std::pair<float, size_t>> reports;
-  image->add_on_progress_callback(
-      [&reports](float progress, size_t bytes_read) { reports.emplace_back(progress, bytes_read); });
-  auto container =
-      std::make_shared<FakeContainer>(std::vector<uint8_t>(PNG_1X1.begin(), PNG_1X1.end()), PNG_1X1.size(), true);
-  set_loop_time(1000);
-  this->start_(*image, container);
-  set_loop_time(2000);
-  for (int i = 0; i < 10 && this->finished_ + this->errors_ == 0; i++)
-    image->loop();
-
-  ASSERT_GE(reports.size(), 2u);
-  EXPECT_TRUE(std::isnan(reports.back().first));
-  EXPECT_EQ(reports.back().second, PNG_1X1.size());
-}
-
-// Scan data that cannot be decoded fails the download part way through
-TEST_F(OnlineImageDownloadEnd, JpegDecodeErrorFailsTheDownload) {
-  auto image = this->make_image_(runtime_image::JPEG, 1024);
-  std::vector<uint8_t> body(JPEG_48X40, JPEG_48X40 + sizeof(JPEG_48X40));
-  std::fill(body.begin() + 700, body.end() - 2, 0xFE);
-  auto container = std::make_shared<FakeContainer>(body, 1024, false);
-  this->start_(*image, container);
-
-  for (int i = 0; i < 100 && this->finished_ + this->errors_ == 0; i++) {
-    image->loop();
-    container->deliver(256);
-  }
-
-  EXPECT_EQ(this->errors_, 1);
-  EXPECT_EQ(this->finished_, 0);
-}
-
-// A read that fails part way through the download ends it with an error
-TEST_F(OnlineImageDownloadEnd, JpegReadErrorFailsTheDownload) {
-  auto image = this->make_image_(runtime_image::JPEG, 1024);
-  auto container =
-      std::make_shared<FakeContainer>(std::vector<uint8_t>(JPEG_48X40, JPEG_48X40 + sizeof(JPEG_48X40)), 1024, false);
-  this->start_(*image, container);
-  for (int i = 0; i < 5; i++)
-    image->loop();
-  ASSERT_EQ(this->errors_, 0);
-
-  container->fail_reads();
-  image->loop();
-  EXPECT_EQ(this->errors_, 1);
-  EXPECT_EQ(this->finished_, 0);
-}
-
-TEST(DownloadBufferGrow, KeepsTheUnreadData) {
-  DownloadBuffer buffer(16);
-  std::memcpy(buffer.append(), "abcdef", 6);
-  buffer.write(6);
-  buffer.read(2);
-
-  ASSERT_TRUE(buffer.grow(64));
-  EXPECT_EQ(buffer.size(), 64u);
-  ASSERT_EQ(buffer.unread(), 4u);
-  EXPECT_EQ(std::memcmp(buffer.data(), "cdef", 4), 0);
-
-  // A failed allocation leaves the buffer as it was
-  EXPECT_FALSE(buffer.grow(SIZE_MAX / 2));
-  EXPECT_EQ(buffer.size(), 64u);
-  EXPECT_EQ(std::memcmp(buffer.data(), "cdef", 4), 0);
-  // Growing to a smaller size changes nothing
-  EXPECT_TRUE(buffer.grow(8));
-  EXPECT_EQ(buffer.size(), 64u);
-}
-
 }  // namespace esphome::online_image::testing
@@ -4,11 +4,9 @@
 #include <algorithm>
 #include <array>
 #include <cstring>
-#include <utility>
 #include <vector>

 #include "esphome/components/runtime_image/image_decoder.h"
-#include "esphome/components/runtime_image/jpeg_decoder.h"
 #include "esphome/components/runtime_image/runtime_image.h"

 namespace esphome::runtime_image::testing {
@@ -364,23 +362,6 @@ static std::vector<uint8_t> pixel_bytes(TestableRuntimeImage &img) {
  return std::vector<uint8_t>(start, start + img.get_width_stride() * img.get_height());
 }

-// Shrinking a PNG keeps the first source pixel of each span, as the JPEG path does: the even rows and columns
-TEST(RuntimeImageDecoder, ShrunkPngKeepsTheFirstPixelOfEachSpan) {
-  TestableRuntimeImage img(PNG, image::IMAGE_TYPE_RGB, false, 2, 2);
-  ASSERT_TRUE(decode_all(img, PNG_RGB, sizeof(PNG_RGB), PNG));
-  ASSERT_EQ(img.get_width(), 2);
-  ASSERT_EQ(img.get_height(), 2);
-  for (int row = 0; row < 2; row++) {
-    for (int col = 0; col < 2; col++) {
-      const Color pixel = img.get_pixel(col, row);
-      const uint8_t *expected = PNG_RGB_EXPECTED[row * 2][col * 2];
-      EXPECT_EQ(pixel.r, expected[0]) << col << "," << row;
-      EXPECT_EQ(pixel.g, expected[1]) << col << "," << row;
-      EXPECT_EQ(pixel.b, expected[2]) << col << "," << row;
-    }
-  }
-}
-
 TEST(RuntimeImageDecoder, JpegDecoderStaysWarmAcrossDecodes) {
  TestableRuntimeImage img(JPEG);

@@ -396,12 +377,6 @@ TEST(RuntimeImageDecoder, JpegDecoderStaysWarmAcrossDecodes) {
  EXPECT_EQ(pixel_bytes(img), first_pixels) << "reused decoder must reproduce identical pixels";
 }

-// The RGB565 word at (x, y) of a decoded image, in its own byte order
-static uint16_t rgb565_word(const TestableRuntimeImage &img, int x, int y) {
-  const uint8_t *p = img.get_data_start() + (y * img.get_width() + x) * 2;
-  return p[0] | (p[1] << 8);
-}
-
 // JPEGDEC's colour conversion differs by one step between its SIMD and scalar builds, so each
 // channel is checked within one step; the byte order is still exact
 static void expect_rgb565_near(uint16_t actual, uint16_t expected, const char *order, size_t pixel) {
@@ -411,12 +386,16 @@ static void expect_rgb565_near(uint16_t actual, uint16_t expected, const char *o
 }

 TEST(RuntimeImageDecoder, JpegDecodesDirectlyToScaledRgb565WithBothByteOrders) {
-  // Halving the 8x8 gradient makes JPEGDEC decode it at half size, which averages each 2x2 block of pixels
-  TestableRuntimeImage full(JPEG, image::IMAGE_TYPE_RGB565, false, 8, 8);
+  // Halving the 8x8 gradient keeps its even rows and columns. The words are JPEGDEC's output for those
+  // pixels, red in the top five bits: a decode of the fixture with PIL gives (51, 7, 30) for source
+  // pixel (2, 0), which is word 0x3803 here.
+  static const uint16_t EXPECTED[4 * 4] = {
+      0x0000, 0x3803, 0x8008, 0xB80B, 0x0203, 0x3A07, 0x81EC, 0xBA0F,
+      0x03E7, 0x3C0B, 0x83F0, 0xBC13, 0x05EC, 0x3E0F, 0x85F4, 0xBE17,
+  };
  TestableRuntimeImage rgb565_little_endian(JPEG, image::IMAGE_TYPE_RGB565, false, 4, 4);
  TestableRuntimeImage rgb565_big_endian(JPEG, image::IMAGE_TYPE_RGB565, true, 4, 4);

-  ASSERT_TRUE(decode_all(full, JPEG_GRADIENT, sizeof(JPEG_GRADIENT)));
  ASSERT_TRUE(decode_all(rgb565_little_endian, JPEG_GRADIENT, sizeof(JPEG_GRADIENT)));
  ASSERT_TRUE(decode_all(rgb565_big_endian, JPEG_GRADIENT, sizeof(JPEG_GRADIENT)));
  ASSERT_EQ(rgb565_little_endian.get_width(), 4);
@@ -426,53 +405,9 @@ TEST(RuntimeImageDecoder, JpegDecodesDirectlyToScaledRgb565WithBothByteOrders) {

  const uint8_t *little = rgb565_little_endian.get_data_start();
  const uint8_t *big = rgb565_big_endian.get_data_start();
-  for (int row = 0; row < 4; row++) {
-    for (int col = 0; col < 4; col++) {
-      int red = 0;
-      int green = 0;
-      int blue = 0;
-      for (int dy = 0; dy < 2; dy++) {
-        for (int dx = 0; dx < 2; dx++) {
-          const uint16_t word = rgb565_word(full, col * 2 + dx, row * 2 + dy);
-          red += word >> 11;
-          green += (word >> 5) & 0x3F;
-          blue += word & 0x1F;
-        }
-      }
-      const uint16_t expected = ((red + 2) / 4) << 11 | ((green + 2) / 4) << 5 | (blue + 2) / 4;
-      const size_t i = row * 4 + col;
-      expect_rgb565_near(little[i * 2] | (little[i * 2 + 1] << 8), expected, "little-endian", i);
-      expect_rgb565_near((big[i * 2] << 8) | big[i * 2 + 1], expected, "big-endian", i);
-    }
-  }
-}
-
-// The generic draw() path gets JPEGDEC's half size RGB8888 output, so it too averages each 2x2 block of pixels
-TEST(RuntimeImageDecoder, JpegDecodesToScaledRgb) {
-  TestableRuntimeImage full(JPEG, image::IMAGE_TYPE_RGB, false, 8, 8);
-  TestableRuntimeImage half(JPEG, image::IMAGE_TYPE_RGB, false, 4, 4);
-  ASSERT_TRUE(decode_all(full, JPEG_GRADIENT, sizeof(JPEG_GRADIENT)));
-  ASSERT_TRUE(decode_all(half, JPEG_GRADIENT, sizeof(JPEG_GRADIENT)));
-  ASSERT_EQ(static_cast<JpegDecoder *>(half.decoder())->get_scale(), 2);
-
-  for (int row = 0; row < 4; row++) {
-    for (int col = 0; col < 4; col++) {
-      int red = 0;
-      int green = 0;
-      int blue = 0;
-      for (int dy = 0; dy < 2; dy++) {
-        for (int dx = 0; dx < 2; dx++) {
-          const Color pixel = full.get_pixel(col * 2 + dx, row * 2 + dy);
-          red += pixel.r;
-          green += pixel.g;
-          blue += pixel.b;
-        }
-      }
-      const Color pixel = half.get_pixel(col, row);
-      EXPECT_NEAR(pixel.r, (red + 2) / 4, 8) << "pixel " << col << "," << row << " red";
-      EXPECT_NEAR(pixel.g, (green + 2) / 4, 8) << "pixel " << col << "," << row << " green";
-      EXPECT_NEAR(pixel.b, (blue + 2) / 4, 8) << "pixel " << col << "," << row << " blue";
-    }
+  for (size_t i = 0; i < 4 * 4; i++) {
+    expect_rgb565_near(little[i * 2] | (little[i * 2 + 1] << 8), EXPECTED[i], "little-endian", i);
+    expect_rgb565_near((big[i * 2] << 8) | big[i * 2 + 1], EXPECTED[i], "big-endian", i);
  }
 }

@@ -480,15 +415,10 @@ TEST(RuntimeImageDecoder, JpegDecodesToScaledRgb) {
 // prepare_rgb565_scaling_ rounds: source n covers targets ceil(n * target / source) up to the next start
 static uint16_t scaled_boundary(int n, int source, int target) { return (n * target + source - 1) / source; }

-// JPEGDEC decodes at the smallest of full, 1/2, 1/4 and 1/8 size that still covers the buffer
-TEST(RuntimeImageDecoder, JpegDecodesAtTheSmallestSizeThatCoversTheBuffer) {
-  for (auto [size, scale] :
-       {std::pair{8, 1}, std::pair{5, 1}, std::pair{4, 2}, std::pair{3, 2}, std::pair{2, 4}, std::pair{1, 8}}) {
-    TestableRuntimeImage img(JPEG, image::IMAGE_TYPE_RGB565, false, size, size);
-    ASSERT_TRUE(decode_all(img, JPEG_GRADIENT, sizeof(JPEG_GRADIENT)));
-    EXPECT_EQ(img.get_width(), size);
-    EXPECT_EQ(static_cast<JpegDecoder *>(img.decoder())->get_scale(), scale) << size << "x" << size;
-  }
+// The RGB565 word at (x, y) of a decoded image, in its own byte order
+static uint16_t rgb565_word(const TestableRuntimeImage &img, int x, int y) {
+  const uint8_t *p = img.get_data_start() + (y * img.get_width() + x) * 2;
+  return p[0] | (p[1] << 8);
 }

 // Every scaled direct decode must equal the unscaled one sampled through the boundary table,
@@ -497,8 +427,7 @@ TEST(RuntimeImageDecoder, JpegDirectRgb565ScalesBySourcePixelSpans) {
  TestableRuntimeImage full(JPEG, image::IMAGE_TYPE_RGB565, false, 8, 8);
  ASSERT_TRUE(decode_all(full, JPEG_GRADIENT, sizeof(JPEG_GRADIENT)));

-  // Sizes JPEGDEC cannot reach by scaling, so the full size decode is spread over the buffer
-  for (int size : {5, 6, 16}) {
+  for (int size : {4, 6, 16}) {
    TestableRuntimeImage scaled(JPEG, image::IMAGE_TYPE_RGB565, false, size, size);
    ASSERT_TRUE(decode_all(scaled, JPEG_GRADIENT, sizeof(JPEG_GRADIENT)));
    ASSERT_EQ(scaled.get_width(), size);
@@ -5,7 +5,6 @@
 #include <vector>

 #include "esphome/components/runtime_image/image_decoder.h"
-#include "esphome/components/runtime_image/jpeg_decoder.h"
 #include "esphome/components/runtime_image/runtime_image.h"

 #ifdef USE_RUNTIME_IMAGE_JPEG
@@ -179,7 +178,6 @@ class SourceImage : public RuntimeImage {
  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_; }
-  int scale() const { return static_cast<const JpegDecoder *>(this->decoder_.get())->get_scale(); }
 };

 /// The file in memory; fails reads once fail_at bytes have been read
@@ -293,23 +291,6 @@ TEST(JpegSourceDecode, SteppedDirectRgb565MatchesFedDecode) {
  EXPECT_EQ(pixels(stepped), pixels(fed));
 }

-// decodeBegin() is given the same reduced scale as decode(), and decodeRows() keeps it for every step
-TEST(JpegSourceDecode, SteppedScaledDecodeMatchesFedDecode) {
-  for (auto type : {image::IMAGE_TYPE_RGB565, image::IMAGE_TYPE_RGB}) {
-    // 24x20 is half of 48x40, so JPEGDEC decodes at 1/2 size
-    SourceImage fed(type, 24, 20);
-    ASSERT_TRUE(decode_fed(fed));
-    ASSERT_EQ(fed.scale(), 2);
-
-    SourceImage stepped(type, 24, 20);
-    MemorySource source(JPEG_ROWS, sizeof(JPEG_ROWS));
-    int steps;
-    ASSERT_EQ(decode_stepped(stepped, source, steps), DECODE_STEP_DONE);
-    ASSERT_EQ(stepped.scale(), 2);
-    EXPECT_EQ(pixels(stepped), pixels(fed)) << "image type " << type;
-  }
-}
-
 TEST(JpegSourceDecode, WaitsForDataThatHasNotArrived) {
  SourceImage fed;
  ASSERT_TRUE(decode_fed(fed));
@@ -0,0 +1,11 @@
+import esphome.codegen as cg
+from esphome.types import ConfigType
+from tests.testing_helpers import ComponentManifestOverride
+
+
+def override_manifest(manifest: ComponentManifestOverride) -> None:
+    # The gtest binary has no YAML switch to emit USE_SWITCH_STORAGE, so define it here.
+    async def to_code_testing(config: ConfigType) -> None:
+        cg.add_define("USE_SWITCH_STORAGE")
+
+    manifest.to_code = to_code_testing
@@ -21,6 +21,13 @@ switch:
      - logger.log: "Switch is now ON"
    on_turn_off:
      - logger.log: "Switch is now OFF"
+  - platform: template
+    name: "Flash Storage Switch"
+    id: flash_storage_switch
+    optimistic: true
+    restore_state:
+      state: KEEP
+      storage: flash

 esphome:
  on_boot:
@@ -0,0 +1,66 @@
+#ifdef USE_HOST
+#include <gtest/gtest.h>
+#include <cstdlib>
+#include <cstring>
+#include <filesystem>
+#include "esphome/components/host/preferences.h"
+#include "esphome/components/switch/switch.h"
+#include "esphome/core/application.h"
+
+namespace esphome::switch_::testing {
+namespace fs = std::filesystem;
+
+/// Switch is abstract; this is the minimum needed to instantiate one.
+class TestSwitch : public Switch {
+ public:
+  void write_state(bool state) override {}
+  /// The preference key is derived from object_id_hash_; two instances with the same value share stored state.
+  void set_test_id(uint32_t hash) { this->object_id_hash_ = hash; }
+};
+
+class SwitchRestoreStorageTest : public ::testing::Test {
+ protected:
+  void SetUp() override {
+    this->temp_dir_ = fs::temp_directory_path() / "esphome_switch_storage_test";
+    fs::remove_all(this->temp_dir_);
+    fs::create_directories(this->temp_dir_);
+    setenv("ESPHOME_PREFDIR", this->temp_dir_.c_str(), 1);
+    App.pre_setup("test_switch_storage", strlen("test_switch_storage"), "", 0);
+    host::setup_preferences();
+    // Host preferences also keep an in-memory store, which would leak between tests and GTEST_REPEAT iterations.
+    host::host_preferences->reset();
+  }
+
+  void TearDown() override {
+    unsetenv("ESPHOME_PREFDIR");
+    fs::remove_all(this->temp_dir_);
+  }
+
+  fs::path temp_dir_;
+};
+
+// Host ignores flash vs RTC, so this checks that a switch with a storage bit in its restore mode still binds,
+// saves and restores its preference; which memory it lands in is checked by the ESP32/ESP8266 compile tests.
+TEST_F(SwitchRestoreStorageTest, SwitchWithAStorageChoiceStillRestoresItsState) {
+  static constexpr uint32_t ID = 0x5001;
+  const auto mode = static_cast<SwitchRestoreMode>(SWITCH_RESTORE_DEFAULT_OFF | RESTORE_MODE_STORAGE_RTC_MASK);
+  {
+    TestSwitch sw;
+    sw.set_test_id(ID);
+    sw.set_restore_mode(mode);
+    auto first = sw.get_initial_state_with_restore_mode();
+    ASSERT_TRUE(first.has_value());
+    EXPECT_FALSE(first.value()) << "nothing stored yet, so RESTORE_DEFAULT_OFF gives OFF";
+    sw.publish_state(true);
+    global_preferences->sync();
+  }
+  TestSwitch sw2;
+  sw2.set_test_id(ID);
+  sw2.set_restore_mode(mode);
+  auto restored = sw2.get_initial_state_with_restore_mode();
+  ASSERT_TRUE(restored.has_value());
+  EXPECT_TRUE(restored.value()) << "the saved state was not restored";
+}
+
+}  // namespace esphome::switch_::testing
+#endif  // USE_HOST
@@ -0,0 +1,49 @@
+#include <gtest/gtest.h>
+
+#include <vector>
+
+#include "esphome/components/switch/switch.h"
+
+namespace esphome::switch_::testing {
+
+class RecordingSwitch : public Switch {
+ public:
+  std::vector<bool> writes;
+
+ protected:
+  void write_state(bool state) override {
+    this->writes.push_back(state);
+    this->publish_state(state);
+  }
+};
+
+TEST(SwitchRestore, DrivesTheRestoreModeStateThroughInversion) {
+  RecordingSwitch on, off, inverted;
+  on.set_restore_mode(SWITCH_ALWAYS_ON);
+  off.set_restore_mode(SWITCH_ALWAYS_OFF);
+  inverted.set_restore_mode(SWITCH_ALWAYS_ON);
+  inverted.set_inverted(true);
+  on.restore();
+  off.restore();
+  inverted.restore();
+  EXPECT_EQ(on.writes, std::vector<bool>{true});
+  EXPECT_EQ(off.writes, std::vector<bool>{false});
+  EXPECT_EQ(inverted.writes, std::vector<bool>{false});  // the hardware level
+  EXPECT_TRUE(on.state);
+  EXPECT_FALSE(off.state);
+  EXPECT_TRUE(inverted.state);
+}
+
+TEST(SwitchRestore, DefaultAppliesOnlyWhenTheModeIsDisabled) {
+  RecordingSwitch disabled, on;
+  disabled.set_restore_mode(SWITCH_RESTORE_DISABLED);
+  on.set_restore_mode(SWITCH_ALWAYS_ON);
+  disabled.restore();
+  EXPECT_TRUE(disabled.writes.empty());
+  disabled.restore(true);
+  on.restore(false);
+  EXPECT_EQ(disabled.writes, std::vector<bool>{true});
+  EXPECT_EQ(on.writes, std::vector<bool>{true});
+}
+
+}  // namespace esphome::switch_::testing
@@ -0,0 +1,8 @@
+switch:
+  - platform: template
+    name: "RTC Storage Switch"
+    id: rtc_storage_switch
+    optimistic: true
+    initial_state: ON
+    restore_state:
+      storage: rtc
@@ -1,2 +1,3 @@
 packages:
  common: !include common.yaml
+  rtc_storage: !include rtc_storage.yaml
@@ -1,2 +1,3 @@
 packages:
  common: !include common.yaml
+  rtc_storage: !include rtc_storage.yaml
@@ -16,10 +16,6 @@ from esphome.components.light import (
 from esphome.components.light.restore_state import (
    _RESTORE_STATE_FIELDS_SCHEMA,
    LEGACY_RESTORE_MODES,
-    RESTORE_STATE_INITIAL,
-    RESTORE_STATE_INVERT,
-    RESTORE_STATE_KEEP,
-    RESTORE_STATE_NONE,
    RESTORE_STATE_SCHEMA,
    StateStatement,
    _initial_state_overridden_by_legacy_mode,
@@ -33,6 +29,12 @@ from esphome.components.light.types import ColorMode
 import esphome.config_validation as cv
 from esphome.const import CONF_STATE
 from esphome.core import Lambda
+from esphome.core.entity_helpers import (
+    RESTORE_STATE_INITIAL,
+    RESTORE_STATE_INVERT,
+    RESTORE_STATE_KEEP,
+    RESTORE_STATE_NONE,
+)
 from esphome.schema_extractors import SCHEMA_EXTRACT

 # (mode name, expected cold_boot_state, expected restore_action, expected save_enabled)
@@ -1,9 +1,11 @@
 """Test get_base_entity_object_id function matches C++ behavior."""

 from collections.abc import Callable, Generator
+import logging
 from pathlib import Path
 import re
 from typing import Any
+from unittest.mock import patch

 import pytest

@@ -11,8 +13,10 @@ from esphome import final_validate as fv
 import esphome.codegen as cg
 from esphome.components import button, number, select, switch
 from esphome.config import Config
+import esphome.config_validation as cv
 from esphome.config_validation import Invalid
 from esphome.const import (
+    CONF_CLUSTER,
    CONF_DEVICE_CLASS,
    CONF_DEVICE_ID,
    CONF_DISABLED_BY_DEFAULT,
@@ -20,22 +24,28 @@ from esphome.const import (
    CONF_ICON,
    CONF_ID,
    CONF_INTERNAL,
+    CONF_MQTT_ID,
    CONF_NAME,
    CONF_UNIT_OF_MEASUREMENT,
+    CONF_WEB_SERVER,
 )
 from esphome.core import CORE, ID, entity_helpers
 from esphome.core.entity_helpers import (
+    _check_report_deprecation,
    _register_string,
    _setup_entity_impl,
    entity_duplicate_validator,
    finalize_entity_strings,
    get_base_entity_object_id,
    inherit_property_from,
+    lazy_load_validator,
+    mqtt_component_class,
    register_device_class,
    register_icon,
    register_unit_of_measurement,
    setup_device_class,
    setup_entity,
+    setup_entity_integrations,
    setup_unit_of_measurement,
 )
 from esphome.cpp_generator import MockObj, MockObjClass, RawExpression
@@ -1242,6 +1252,111 @@ async def test_finalize_comment_sanitization(
    assert "INJECTED_CODE" in comment_line  # still visible but safe in comment


+@pytest.mark.parametrize(
+    ("value", "warns"),
+    [
+        ("coordinator", True),
+        ("enable", False),
+        ("force", False),
+        ("default", False),
+    ],
+)
+def test_check_report_deprecation(
+    value: str, warns: bool, caplog: pytest.LogCaptureFixture
+) -> None:
+    """Deprecated zigbee report options warn; the value always passes through."""
+    with caplog.at_level(logging.WARNING):
+        assert _check_report_deprecation(value) == value
+    assert ("deprecated" in caplog.text) is warns
+
+
+def test_lazy_load_validator_defers_import() -> None:
+    """The validator no-ops without importing unless the component is loaded."""
+    validator = lazy_load_validator("zigbee", "validate_binary_sensor")
+    config = {CONF_NAME: "test"}
+
+    with (
+        patch.object(CORE, "loaded_integrations", set()),
+        patch("esphome.core.entity_helpers.import_module") as import_mock,
+    ):
+        assert validator(config) is config
+        import_mock.assert_not_called()
+
+        CORE.loaded_integrations.add("zigbee")
+        delegate = import_mock.return_value.validate_binary_sensor
+        delegate.return_value = {CONF_NAME: "validated"}
+        assert validator(config) == {CONF_NAME: "validated"}
+        import_mock.assert_called_once_with("esphome.components.zigbee")
+        delegate.assert_called_once_with(config)
+
+
+def test_lazy_load_validator_rejects_unknown_component() -> None:
+    """A typo in the component name fails at schema construction."""
+    with pytest.raises(ValueError, match="no_such_component"):
+        lazy_load_validator("no_such_component", "validate_binary_sensor")
+
+
+def test_lazy_load_validator_names_missing_hook() -> None:
+    """A missing hook raises a clear error naming the component and hook."""
+    validator = lazy_load_validator("zigbee", "no_such_hook")
+
+    with (
+        patch.object(CORE, "loaded_integrations", {"zigbee"}),
+        patch("esphome.core.entity_helpers.import_module") as import_mock,
+        pytest.raises(ValueError, match="no_such_hook"),
+    ):
+        del import_mock.return_value.no_such_hook
+        validator({})
+
+
+def test_integration_class_handles_match_owning_definitions() -> None:
+    """The cheap class handles must stay string-equal to the integrations'
+    own declarations, or use_id/declare_id resolution silently drifts."""
+    from esphome.components import mqtt, web_server
+    from esphome.components.zigbee import zigbee_zephyr
+    from esphome.components.zigbee.const import ZigbeeComponent
+
+    mqtt_handle = mqtt_component_class("MQTTBinarySensorComponent")
+    assert str(mqtt_handle) == str(mqtt.MQTTBinarySensorComponent)
+    assert mqtt_handle.inherits_from(mqtt.MQTTComponent)
+    assert mqtt.MQTTBinarySensorComponent.inherits_from(entity_helpers._MQTTComponent)
+
+    assert str(entity_helpers._WebServer) == str(web_server.WebServer)
+    assert entity_helpers._WebServer.inherits_from(web_server.WebServer)
+    assert web_server.WebServer.inherits_from(entity_helpers._WebServer)
+
+    assert str(entity_helpers._ZigbeeComponent) == str(ZigbeeComponent)
+    for (
+        _conf_key,
+        class_name,
+        _cluster_options,
+    ) in entity_helpers._ZIGBEE_ENTITY_CLASSES.values():
+        owning = getattr(zigbee_zephyr, class_name)
+        assert str(owning) == f"zigbee::{class_name}"
+
+
+def test_zigbee_entity_schema_cluster_options() -> None:
+    """The cluster key only exists for esp32 + zigbee and is limited to the
+    platform's options, with the first option as its default."""
+    schema = entity_helpers.ZIGBEE_BINARY_SENSOR_SCHEMA
+
+    with patch.object(CORE, "loaded_integrations", set()):
+        assert schema({}) == {}
+        with pytest.raises(Invalid, match="requires component zigbee"):
+            schema({CONF_CLUSTER: "generic"})
+
+    with patch.object(CORE, "loaded_integrations", {"esp32", "zigbee"}):
+        assert schema({}) == {CONF_CLUSTER: "generic"}
+        assert schema({CONF_CLUSTER: "Device_Class"}) == {CONF_CLUSTER: "device_class"}
+        with pytest.raises(Invalid, match="Unknown value 'on_off'"):
+            schema({CONF_CLUSTER: "on_off"})
+
+    with patch.object(CORE, "loaded_integrations", {"nrf52", "zigbee"}):
+        assert CONF_CLUSTER not in schema({})
+        with pytest.raises(Invalid, match="requires component esp32"):
+            schema({CONF_CLUSTER: "generic"})
+
+
@pytest.mark.asyncio
 async def test_sub_entities_creates_and_sets(
    monkeypatch: pytest.MonkeyPatch, setup_test_environment: list[str]
@@ -1301,6 +1416,45 @@ async def test_sub_entities_without_parent(
    assert setup_test_environment == ["hub->set_child(child)"]


+@pytest.mark.asyncio
+async def test_setup_entity_integrations_registers_mqtt_and_web_server(
+    monkeypatch: pytest.MonkeyPatch, setup_test_environment: list[str]
+) -> None:
+    """Both integrations are wired up and the mqtt companion is returned."""
+    from esphome.components import mqtt, web_server
+
+    calls: list[tuple[str, Any]] = []
+
+    async def register_mqtt_component(var: MockObj, config: dict[str, Any]) -> None:
+        calls.append(("mqtt", var))
+
+    async def add_entity_config(var: MockObj, config: dict[str, Any]) -> None:
+        calls.append(("web_server", config))
+
+    monkeypatch.setattr(mqtt, "register_mqtt_component", register_mqtt_component)
+    monkeypatch.setattr(web_server, "add_entity_config", add_entity_config)
+    config = {
+        CONF_MQTT_ID: ID(
+            "mqtt_switch", is_declaration=True, type=MockObj("MQTTSwitch")
+        ),
+        CONF_WEB_SERVER: {"sorting_weight": 1.0},
+    }
+
+    mqtt_ = await setup_entity_integrations(MockObj("switch_1"), config)
+
+    assert mqtt_ is not None
+    assert calls == [("mqtt", mqtt_), ("web_server", {"sorting_weight": 1.0})]
+
+
+@pytest.mark.asyncio
+async def test_setup_entity_integrations_without_integrations(
+    setup_test_environment: list[str],
+) -> None:
+    """Without mqtt_id or web_server config nothing is registered."""
+    assert await setup_entity_integrations(MockObj("switch_1"), {}) is None
+    assert setup_test_environment == []
+
+
@pytest.fixture
 def apply_functions(monkeypatch: pytest.MonkeyPatch) -> list[tuple[str, str, str]]:
    """Record every generated apply function as (name, parameters, body)."""
@@ -1740,3 +1894,31 @@ def test_inherit_property_from_path_missing_is_ignored() -> None:
        fv.full_config.reset(token)

    assert "absent" not in config["sensor"][1]
+
+
+_RESTORE_FIELDS = cv.Schema({cv.Optional("state", default="KEEP"): cv.string})
+
+
+def test_restore_state_schema_shorthands() -> None:
+    validate = entity_helpers.restore_state_schema(
+        _RESTORE_FIELDS, {"state": "INITIAL"}
+    )
+    assert validate(" all ") == {"state": "KEEP"}
+    assert validate("None") == {"state": "INITIAL"}
+    assert validate({"state": "INVERT"}) == {"state": "INVERT"}
+    with pytest.raises(Invalid, match="expected 'all', 'none' or a mapping"):
+        validate("everything")
+
+
+def test_restore_state_schema_keeps_a_keyword_for_none() -> None:
+    validate = entity_helpers.restore_state_schema(
+        _RESTORE_FIELDS, entity_helpers.RESTORE_STATE_NONE
+    )
+    assert validate("none") == entity_helpers.RESTORE_STATE_NONE
+
+
+def test_restore_state_keyword() -> None:
+    keywords = (entity_helpers.RESTORE_STATE_KEEP, entity_helpers.RESTORE_STATE_INVERT)
+    assert entity_helpers.restore_state_keyword(" invert ", keywords) == "INVERT"
+    assert entity_helpers.restore_state_keyword("INITIAL", keywords) is None
+    assert entity_helpers.restore_state_keyword(True, keywords) is None
@@ -218,6 +218,40 @@ def test_api_client_does_not_import_heavy_modules() -> None:
    )


+def test_binary_sensor_does_not_import_integrations() -> None:
+    """An entity component must not drag in its optional integrations.
+
+    binary_sensor's mqtt/web_server/zigbee schema fragments live in
+    ``esphome.core.entity_helpers``; the integration packages (and the
+    esp32/logger chains mqtt and zigbee pull in) must only load when the
+    user's config actually uses them.
+    """
+    allowed = (
+        "esphome.components",
+        "esphome.components.binary_sensor",
+        "esphome.components.const",
+    )
+    check = (
+        "import sys; import esphome.components.binary_sensor; "
+        f"leaked = [m for m in sys.modules "
+        f"if m.startswith('esphome.components') and m not in {allowed!r}]; "
+        "print(','.join(leaked))"
+    )
+    result = subprocess.run(
+        [sys.executable, "-c", check],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    leaked = result.stdout.strip()
+    assert not leaked, (
+        f"esphome.components.binary_sensor imports integration packages at "
+        f"top level: {leaked}. Keep the shared schema fragments in "
+        "esphome.core.entity_helpers and import the integration inside "
+        "to_code instead."
+    )
+
+
 def test_stacktrace_does_not_import_heavy_modules() -> None:
    """``esphome.stacktrace`` guards its own docstring's contract.
Author	SHA1	Message	Date
J. Nick Koston	b5b3382505	Merge remote-tracking branch 'origin/dev' into binary-sensor-lazy-integration-imports # Conflicts: # esphome/core/entity_helpers.py	2026-10-22 10:56:35 -10:00
J. Nick Koston	dac6a9c8cc	[cover] Pack the cover traits flags into one byte (#21339 )	2026-10-22 16:53:20 -04:00
J. Nick Koston	a3a4144e4f	[valve] Pack the valve traits flags into one byte (#21343 )	2026-10-22 16:52:35 -04:00
J. Nick Koston	29e9ae008d	[lock] Pack the lock traits flags into one byte (#21344 )	2026-10-22 16:52:05 -04:00
Bonne Eggleston	c92c4d7f99	[deep_sleep] Add woke_from_deep_sleep() and build get_wakeup_cause() without on_wake (#21425 )	2026-10-22 10:49:15 -10:00
Michele Porelli J. Nick Koston J. Nick Koston	5bcc3f42e9	[switch] Add initial_state and restore_state, with flash or RTC storage (#20978 ) Co-authored-by: J. Nick Koston <nick@home-assistant.io> Co-authored-by: J. Nick Koston <nick@koston.org>	2026-10-22 10:35:23 -10:00
Jonathan Swoboda	d6aa5ba14c	[esp32] Share one validator for options that need a newer ESP-IDF (#21422 )	2026-10-22 10:20:22 -10:00
J. Nick Koston	f167ef6bf0	Merge remote-tracking branch 'origin/dev' into binary-sensor-lazy-integration-imports # Conflicts: # tests/unit_tests/core/test_entity_helpers.py	2026-10-21 16:39:59 -10:00
J. Nick Koston	dce39bf19f	Merge remote-tracking branch 'origin/dev' into binary-sensor-lazy-integration-imports	2026-10-21 08:45:19 -10:00
J. Nick Koston	36e4018764	Merge remote-tracking branch 'origin/dev' into binary-sensor-lazy-integration-imports # Conflicts: # tests/unit_tests/core/test_entity_helpers.py	2026-10-19 08:01:41 -10:00
J. Nick Koston	6364d2b6c3	Merge remote-tracking branch 'origin/dev' into HEAD # Conflicts: # esphome/components/zigbee/const.py	2026-10-16 15:46:46 -10:00
J. Nick Koston	2ea2ffb127	Cover setup_entity_integrations	2026-10-14 10:42:15 -10:00
J. Nick Koston	4dccc1ea89	Merge remote-tracking branch 'origin/dev' into binary-sensor-lazy-integration-imports	2026-10-14 10:39:26 -10:00
J. Nick Koston	3a8a83d9fb	Merge remote-tracking branch 'origin/dev' into binary-sensor-lazy-integration-imports # Conflicts: # tests/benchmarks/python/test_component_import_bench.py	2026-10-14 08:16:43 -10:00
J. Nick Koston	fa070bf340	Merge branch 'component-import-benchmarks' into binary-sensor-lazy-integration-imports	2026-10-13 11:23:16 -10:00
J. Nick Koston	a31ce9bd9e	Drop the components package too so the re-import is real	2026-10-13 11:23:13 -10:00
J. Nick Koston	fd7fcbad0f	Merge branch 'component-import-benchmarks' into binary-sensor-lazy-integration-imports	2026-10-13 11:19:26 -10:00
J. Nick Koston	5860a392bd	Merge remote-tracking branch 'origin/component-import-benchmarks' into component-import-benchmarks # Conflicts: # tests/benchmarks/python/test_component_import_bench.py	2026-10-13 11:19:23 -10:00
J. Nick Koston	55487971c3	Point the const_zephyr comment at esphome.const	2026-10-13 11:16:29 -10:00
J. Nick Koston	82c535e0a7	Merge branch 'component-import-benchmarks' into binary-sensor-lazy-integration-imports	2026-10-13 11:16:28 -10:00
J. Nick Koston	de6991144e	Time only the component import and put the original modules back afterwards	2026-10-13 11:16:05 -10:00
J. Nick Koston	af1285f006	Put the session's esphome modules back after each import benchmark	2026-10-13 11:08:28 -10:00
J. Nick Koston	2fa7775fe7	Merge branch 'component-import-benchmarks' into binary-sensor-lazy-integration-imports	2026-10-13 10:25:49 -10:00
J. Nick Koston	926f2561b4	[core] Add CodSpeed benchmarks for importing entity components	2026-10-13 10:24:07 -10:00
J. Nick Koston	f24dba9de8	Merge remote-tracking branch 'origin/dev' into binary-sensor-lazy-integration-imports # Conflicts: # esphome/components/binary_sensor/__init__.py # esphome/components/web_server/__init__.py # esphome/components/zigbee/__init__.py # esphome/components/zigbee/const.py # script/ci-custom.py # tests/unit_tests/core/test_entity_helpers.py	2026-10-13 10:14:13 -10:00
pre-commit-ci-lite[bot]	82c3e0db96	apply automatic formatting fixes	2026-09-14 15:57:18 +00:00
J. Nick Koston	e207138557	Merge remote-tracking branch 'origin/dev' into binary-sensor-lazy-integration-imports # Conflicts: # esphome/components/web_server/__init__.py	2026-09-14 10:54:52 -05:00
J. Nick Koston	edeaded161	Consolidate zigbee schema factory and shared integration setup	2026-08-13 21:21:17 -05:00
J. Nick Koston	09a3b1a3d1	Address review: stable schema anchors, const.py home, validator hardening	2026-08-13 21:21:17 -05:00
J. Nick Koston	10d232dc40	Cover the report deprecation warning and lazy validator paths	2026-08-13 21:21:17 -05:00
J. Nick Koston	663f462877	[binary_sensor] Defer integration imports out of module scope	2026-08-13 21:20:59 -05:00