Merge pull request #16760 from esphome/bump-2026.5.2

2026.5.2

Doxyfile

@@ -48,7 +48,7 @@ PROJECT_NAME           = ESPHome
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2026.5.0
+PROJECT_NUMBER         = 2026.5.2
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

esphome/__main__.py

@@ -2449,7 +2449,10 @@ def run_esphome(argv):
     # Skipped when -s overrides are passed, since the cache was written
     # against the previous substitution set.
     config: ConfigType | None = None
-    if args.command in ("upload", "logs") and not command_line_substitutions:
+    cache_eligible = (
+        args.command in ("upload", "logs") and not command_line_substitutions
+    )
+    if cache_eligible:
         from esphome.compiled_config import load_compiled_config
 
         config = load_compiled_config(conf_path)
@@ -2464,6 +2467,16 @@ def run_esphome(argv):
             command_line_substitutions,
             skip_external_update=skip_external,
         )
+        # Refresh the cache so the next upload/logs hits the fast path
+        # instead of re-running read_config. Skip when the storage
+        # sidecar is absent (no compile has run): the cache would
+        # never be loaded back, so writing secrets to disk is wasted.
+        if cache_eligible and config is not None:
+            from esphome.compiled_config import save_compiled_config
+            from esphome.storage_json import ext_storage_path
+
+            if ext_storage_path(conf_path.name).exists():
+                save_compiled_config(config)
     if config is None:
         return 2
     CORE.config = config

esphome/components/api/api_connection.cpp

@@ -1,5 +1,6 @@
 #include "api_connection.h"
 #ifdef USE_API
+#include "api_connection_buffer.h"  // for encode_to_buffer / get_batch_delay_ms_ inlines
 #ifdef USE_API_NOISE
 #include "api_frame_helper_noise.h"
 #endif
@@ -1305,6 +1306,9 @@ void APIConnection::on_voice_assistant_announce_request(const VoiceAssistantAnno
 bool APIConnection::send_voice_assistant_get_configuration_response_(const VoiceAssistantConfigurationRequest &msg) {
   VoiceAssistantConfigurationResponse resp;
   if (!this->check_voice_assistant_api_connection_()) {
+    // send_message encodes synchronously, so this stack local outlives the encode
+    const std::vector<std::string> empty_wake_words;
+    resp.active_wake_words = &empty_wake_words;
     return this->send_message(resp);
   }
 

esphome/components/api/api_connection.h

@@ -11,7 +11,8 @@
 #endif
 #include "api_pb2.h"
 #include "api_pb2_service.h"
-#include "api_server.h"
+#include "list_entities.h"
+#include "subscribe_state.h"
 #include "esphome/core/application.h"
 #include "esphome/core/component.h"
 #ifdef USE_ESP32_CRASH_HANDLER
@@ -36,6 +37,9 @@ class ComponentIterator;
 
 namespace esphome::api {
 
+// Forward-declared to break the api_server.h cycle; full-type inlines are in api_connection_buffer.h.
+class APIServer;
+
 // Keepalive timeout in milliseconds
 static constexpr uint32_t KEEPALIVE_TIMEOUT_MS = 60000;
 // Maximum number of entities to process in a single batch during initial state/info sending
@@ -411,44 +415,10 @@ class APIConnection final : public APIServerConnectionBase {
   // Non-template buffer management for send_message
   bool send_message_(uint32_t payload_size, uint8_t message_type, MessageEncodeFn encode_fn, const void *msg);
 
-  // Core batch encoding logic. Computes header size, checks fit, resizes buffer, encodes.
-  // ALWAYS_INLINE so the compiler can devirtualize encode_fn at hot call sites.
-  static inline uint16_t ESPHOME_ALWAYS_INLINE encode_to_buffer(uint32_t calculated_size, MessageEncodeFn encode_fn,
-                                                                const void *msg, APIConnection *conn,
-                                                                uint32_t remaining_size) {
-#ifdef HAS_PROTO_MESSAGE_DUMP
-    if (conn->flags_.log_only_mode) {
-      auto *proto_msg = static_cast<const ProtoMessage *>(msg);
-      DumpBuffer dump_buf;
-      conn->log_send_message_(proto_msg->message_name(), proto_msg->dump_to(dump_buf));
-      return 1;
-    }
-#endif
-    const uint8_t footer_size = conn->helper_->frame_footer_size();
-
-    // First message uses max padding (already in buffer), subsequent use exact header size
-    size_t to_add;
-    if (conn->flags_.batch_first_message) {
-      conn->flags_.batch_first_message = false;
-      conn->batch_header_size_ = conn->helper_->frame_header_padding();
-      to_add = calculated_size;
-    } else {
-      conn->batch_header_size_ = conn->helper_->frame_header_size(calculated_size, conn->batch_message_type_);
-      to_add = calculated_size + conn->batch_header_size_ + footer_size;
-    }
-
-    // Check if it fits (using actual header size, not max padding)
-    uint16_t total_calculated_size = calculated_size + conn->batch_header_size_ + footer_size;
-    if (total_calculated_size > remaining_size)
-      return 0;
-
-    auto &shared_buf = conn->parent_->get_shared_buffer_ref();
-    shared_buf.resize(shared_buf.size() + to_add);
-    ProtoWriteBuffer buffer{&shared_buf, shared_buf.size() - calculated_size};
-    encode_fn(msg, buffer PROTO_ENCODE_DEBUG_INIT(&shared_buf));
-
-    return total_calculated_size;
-  }
+  // Core batch encoding logic. ALWAYS_INLINE so encode_fn devirtualizes at hot call sites.
+  // Defined in api_connection_buffer.h (needs APIServer complete).
+  static uint16_t ESPHOME_ALWAYS_INLINE encode_to_buffer(uint32_t calculated_size, MessageEncodeFn encode_fn,
+                                                         const void *msg, APIConnection *conn, uint32_t remaining_size);
 
   // Noinline version of encode_to_buffer for cold paths (entity info, zero-payload messages).
   // All cold callers share this single copy instead of each getting an ALWAYS_INLINE expansion.
@@ -792,7 +762,8 @@ class APIConnection final : public APIServerConnectionBase {
   // Read by process_batch_multi_ to pass into MessageInfo.
   uint8_t batch_header_size_{0};
 
-  uint32_t get_batch_delay_ms_() const { return this->parent_->get_batch_delay(); }
+  // Defined in api_connection_buffer.h (needs APIServer complete).
+  uint32_t get_batch_delay_ms_() const;
   // Message will use 8 more bytes than the minimum size, and typical
   // MTU is 1500. Sometimes users will see as low as 1460 MTU.
   // If its IPv6 the header is 40 bytes, and if its IPv4

esphome/components/api/api_connection_buffer.h

@@ -0,0 +1,54 @@
+#pragma once
+
+#include "esphome/core/defines.h"
+#ifdef USE_API
+
+// Inline APIConnection methods that need APIServer complete. Include this
+// instead of api_connection.h when calling encode_to_buffer or get_batch_delay_ms_.
+
+#include "api_connection.h"
+#include "api_server.h"
+
+namespace esphome::api {
+
+inline uint16_t ESPHOME_ALWAYS_INLINE APIConnection::encode_to_buffer(uint32_t calculated_size,
+                                                                      MessageEncodeFn encode_fn, const void *msg,
+                                                                      APIConnection *conn, uint32_t remaining_size) {
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  if (conn->flags_.log_only_mode) {
+    auto *proto_msg = static_cast<const ProtoMessage *>(msg);
+    DumpBuffer dump_buf;
+    conn->log_send_message_(proto_msg->message_name(), proto_msg->dump_to(dump_buf));
+    return 1;
+  }
+#endif
+  const uint8_t footer_size = conn->helper_->frame_footer_size();
+
+  // First message uses max padding (already in buffer), subsequent use exact header size
+  size_t to_add;
+  if (conn->flags_.batch_first_message) {
+    conn->flags_.batch_first_message = false;
+    conn->batch_header_size_ = conn->helper_->frame_header_padding();
+    to_add = calculated_size;
+  } else {
+    conn->batch_header_size_ = conn->helper_->frame_header_size(calculated_size, conn->batch_message_type_);
+    to_add = calculated_size + conn->batch_header_size_ + footer_size;
+  }
+
+  // Check if it fits (using actual header size, not max padding)
+  uint16_t total_calculated_size = calculated_size + conn->batch_header_size_ + footer_size;
+  if (total_calculated_size > remaining_size)
+    return 0;
+
+  auto &shared_buf = conn->parent_->get_shared_buffer_ref();
+  shared_buf.resize(shared_buf.size() + to_add);
+  ProtoWriteBuffer buffer{&shared_buf, shared_buf.size() - calculated_size};
+  encode_fn(msg, buffer PROTO_ENCODE_DEBUG_INIT(&shared_buf));
+
+  return total_calculated_size;
+}
+
+inline uint32_t APIConnection::get_batch_delay_ms_() const { return this->parent_->get_batch_delay(); }
+
+}  // namespace esphome::api
+#endif

esphome/components/api/api_server.cpp

@@ -30,11 +30,6 @@ APIServer *global_api_server = nullptr;  // NOLINT(cppcoreguidelines-avoid-non-c
 
 APIServer::APIServer() { global_api_server = this; }
 
-// Custom deleter defined here so `delete` sees the complete APIConnection type.
-// This prevents libc++ from emitting an "incomplete type" error when other
-// translation units only have the forward declaration of APIConnection.
-void APIServer::APIConnectionDeleter::operator()(APIConnection *p) const { delete p; }
-
 void APIServer::socket_failed_(const LogString *msg) {
   ESP_LOGW(TAG, "Socket %s: errno %d", LOG_STR_ARG(msg), errno);
   this->destroy_socket_();

esphome/components/api/api_server.h

@@ -3,6 +3,8 @@
 #include "esphome/core/defines.h"
 #ifdef USE_API
 #include "api_buffer.h"
+// Must precede clients_ so APIConnection is complete for default_delete (libc++).
+#include "api_connection.h"
 #include "api_noise_context.h"
 #include "api_pb2.h"
 #include "api_pb2_service.h"
@@ -12,8 +14,6 @@
 #include "esphome/core/controller.h"
 #include "esphome/core/log.h"
 #include "esphome/core/string_ref.h"
-#include "list_entities.h"
-#include "subscribe_state.h"
 #ifdef USE_LOGGER
 #include "esphome/components/logger/logger.h"
 #endif
@@ -191,15 +191,9 @@ class APIServer final : public Component,
   bool is_connected_with_state_subscription() const;
 
   // Range-for view over the populated slice [0, api_connection_count_). Read-only with respect
-  // to ownership — callers get `const unique_ptr&` so they can invoke non-const methods on the
+  // to ownership; callers get `const unique_ptr&` so they can invoke non-const methods on the
   // APIConnection but cannot reset/move the slot and break the count invariant.
-  // Custom deleter is defined out-of-line in api_server.cpp so libc++ does not
-  // eagerly instantiate `delete static_cast<APIConnection *>(p)` here, where
-  // only the forward declaration of APIConnection is visible (incomplete type).
-  struct APIConnectionDeleter {
-    void operator()(APIConnection *p) const;
-  };
-  using APIConnectionPtr = std::unique_ptr<APIConnection, APIConnectionDeleter>;
+  using APIConnectionPtr = std::unique_ptr<APIConnection>;
   class ActiveClientsView {
     const APIConnectionPtr *begin_;
     const APIConnectionPtr *end_;

esphome/components/bluetooth_proxy/bluetooth_connection.cpp

@@ -135,12 +135,26 @@ void BluetoothConnection::loop() {
   // - For V3_WITH_CACHE: Services are never sent, disable after INIT state
   // - For V3_WITHOUT_CACHE: Disable only after service discovery is complete
   //   (send_service_ == DONE_SENDING_SERVICES, which is only set after services are sent)
-  if (this->state() != espbt::ClientState::INIT && (this->connection_type_ == espbt::ConnectionType::V3_WITH_CACHE ||
-                                                    this->send_service_ == DONE_SENDING_SERVICES)) {
+  // Never disable while DISCONNECTING — BLEClientBase::loop() needs to keep running so the
+  // 10s safety timeout can force IDLE if CLOSE_EVT is never delivered.
+  if (this->state() != espbt::ClientState::INIT && this->state() != espbt::ClientState::DISCONNECTING &&
+      (this->connection_type_ == espbt::ConnectionType::V3_WITH_CACHE ||
+       this->send_service_ == DONE_SENDING_SERVICES)) {
     this->disable_loop();
   }
 }
 
+void BluetoothConnection::on_disconnect_complete(esp_err_t reason) {
+  // Called from both the CLOSE_EVT handler and the DISCONNECTING safety timeout in the
+  // base class. Free the proxy slot, notify the API client, and reset send_service_.
+  // address_ may already be 0 if reset_connection_ ran earlier on this teardown.
+  if (this->address_ == 0) {
+    return;
+  }
+  ESP_LOGD(TAG, "[%d] [%s] Close, reason=0x%02x, freeing slot", this->connection_index_, this->address_str_, reason);
+  this->reset_connection_(reason);
+}
+
 void BluetoothConnection::reset_connection_(esp_err_t reason) {
   // Send disconnection notification
   this->proxy_->send_device_connection(this->address_, false, 0, reason);
@@ -372,14 +386,6 @@ bool BluetoothConnection::gattc_event_handler(esp_gattc_cb_event_t event, esp_ga
       this->proxy_->send_device_connection(this->address_, false, 0, param->disconnect.reason);
       break;
     }
-    case ESP_GATTC_CLOSE_EVT: {
-      ESP_LOGD(TAG, "[%d] [%s] Close, reason=0x%02x, freeing slot", this->connection_index_, this->address_str_,
-               param->close.reason);
-      // Now the GATT connection is fully closed and controller resources are freed
-      // Safe to mark the connection slot as available
-      this->reset_connection_(param->close.reason);
-      break;
-    }
     case ESP_GATTC_OPEN_EVT: {
       if (param->open.status != ESP_GATT_OK && param->open.status != ESP_GATT_ALREADY_OPEN) {
         this->reset_connection_(param->open.status);

esphome/components/bluetooth_proxy/bluetooth_connection.h

@@ -33,6 +33,8 @@ class BluetoothConnection final : public esp32_ble_client::BLEClientBase {
  protected:
   friend class BluetoothProxy;
 
+  void on_disconnect_complete(esp_err_t reason) override;
+
   bool supports_efficient_uuids_() const;
   void send_service_for_discovery_();
   void reset_connection_(esp_err_t reason);

esphome/components/bluetooth_proxy/bluetooth_proxy.cpp

@@ -1,5 +1,6 @@
 #include "bluetooth_proxy.h"
 
+#include "esphome/components/api/api_server.h"
 #include "esphome/core/log.h"
 #include "esphome/core/macros.h"
 #include "esphome/core/application.h"

esphome/components/esp32/__init__.py

@@ -46,7 +46,7 @@ from esphome.const import (
     Toolchain,
     __version__,
 )
-from esphome.core import CORE, HexInt, Library
+from esphome.core import CORE, EsphomeError, HexInt, Library
 from esphome.core.config import BOARD_MAX_LENGTH
 from esphome.coroutine import CoroPriority, coroutine_with_priority
 from esphome.espidf.component import generate_idf_component
@@ -113,6 +113,7 @@ ARDUINO_FRAMEWORK_NAME = "framework-arduinoespressif32"
 ARDUINO_FRAMEWORK_PKG = f"pioarduino/{ARDUINO_FRAMEWORK_NAME}"
 ARDUINO_LIBS_NAME = f"{ARDUINO_FRAMEWORK_NAME}-libs"
 ARDUINO_LIBS_PKG = f"pioarduino/{ARDUINO_LIBS_NAME}"
+ARDUINO_ESP32_COMPONENT_NAME = "espressif/arduino-esp32"
 
 LOG_LEVELS_IDF = [
     "NONE",
@@ -1743,6 +1744,31 @@ async def _add_yaml_idf_components(components: list[ConfigType]):
         )
 
 
+@coroutine_with_priority(CoroPriority.FINAL - 1)
+async def _finalize_arduino_aware_flags():
+    """Build flags that depend on whether arduino-esp32 is linked in.
+
+    Scheduler runs lower priority values later, so ``FINAL - 1`` fires
+    after every ``FINAL`` job (incl. ``_add_yaml_idf_components``) --
+    by then ``KEY_COMPONENTS`` is fully populated.
+
+    - Skip our esp_panic_handler wrap when Arduino is linked; Arduino
+      wraps the same symbol and the linker errors on the duplicate.
+    - Define USE_ARDUINO in the hybrid esp-idf+arduino-esp32-component
+      case so ESPHome's ``#ifdef USE_ARDUINO`` paths light up. The
+      framework=arduino branch already adds it inline in to_code.
+    """
+    arduino_linked = (
+        CORE.using_arduino
+        or ARDUINO_ESP32_COMPONENT_NAME in CORE.data[KEY_ESP32][KEY_COMPONENTS]
+    )
+    if not arduino_linked:
+        cg.add_build_flag("-Wl,--wrap=esp_panic_handler")
+        cg.add_define("USE_ESP32_CRASH_HANDLER")
+    elif not CORE.using_arduino:
+        cg.add_build_flag("-DUSE_ARDUINO")
+
+
 async def to_code(config):
     framework_ver: cv.Version = CORE.data[KEY_CORE][KEY_FRAMEWORK_VERSION]
     conf = config[CONF_FRAMEWORK]
@@ -1790,11 +1816,12 @@ async def to_code(config):
                 Path(__file__).parent / "iram_fix.py.script",
             )
     else:
-        cg.add_build_flag("-Wno-error=format")
-        cg.add_build_flag("-Wno-error=maybe-uninitialized")
-        cg.add_build_flag("-Wno-error=overloaded-virtual")
-        cg.add_build_flag("-Wno-error=reorder")
-        cg.add_build_flag("-Wno-error=volatile")
+        # Demote IDF's blanket -Werror to warnings so third-party libs
+        # and user lambdas don't need a -Wno-error=<class> per warning.
+        # The sdkconfig knob disables IDF's rewrite to -Werror=all (which
+        # can't be globally undone); -Wno-error then handles the demotion.
+        add_idf_sdkconfig_option("CONFIG_COMPILER_DISABLE_DEFAULT_ERRORS", False)
+        cg.add_build_flag("-Wno-error")
         # -Wno- (not -Wno-error=): suppress entirely, too noisy on C++ aggregates
         cg.add_build_flag("-Wno-missing-field-initializers")
 
@@ -1802,11 +1829,8 @@ async def to_code(config):
     cg.add_build_flag("-DUSE_ESP32")
     cg.add_define("USE_NATIVE_64BIT_TIME")
     cg.add_build_flag("-Wl,-z,noexecstack")
-    # Arduino already wraps esp_panic_handler for its own backtrace handler,
-    # so only add our wrap when using ESP-IDF framework to avoid linker conflicts.
-    if conf[CONF_TYPE] == FRAMEWORK_ESP_IDF:
-        cg.add_build_flag("-Wl,--wrap=esp_panic_handler")
-        cg.add_define("USE_ESP32_CRASH_HANDLER")
+    # Deferred so KEY_COMPONENTS is fully populated -- see the coroutine.
+    CORE.add_job(_finalize_arduino_aware_flags)
     cg.add_define("ESPHOME_BOARD", config[CONF_BOARD])
     variant = config[CONF_VARIANT]
     cg.add_build_flag(f"-DUSE_ESP32_VARIANT_{variant}")
@@ -2566,7 +2590,7 @@ def _write_idf_component_yml():
 
         if CORE.using_toolchain_esp_idf:
             add_idf_component(
-                name="espressif/arduino-esp32",
+                name=ARDUINO_ESP32_COMPONENT_NAME,
                 ref=str(CORE.data[KEY_CORE][KEY_FRAMEWORK_VERSION]),
             )
 
@@ -2633,13 +2657,29 @@ def copy_files():
 
 
 def _decode_pc(config, addr):
-    from esphome.platformio import toolchain
+    # _decode_pc runs from the api log processor's asyncio callback, which
+    # only catches EsphomeError. Any other exception escaping here tears down
+    # the protocol and triggers an infinite reconnect/replay loop. Convert
+    # toolchain-resolution errors (e.g. missing build dir / cmake cache) into
+    # EsphomeError so the caller can disable decoding cleanly.
+    if CORE.using_toolchain_esp_idf:
+        from esphome.espidf import toolchain as idf_toolchain
 
-    idedata = toolchain.get_idedata(config)
-    if not idedata.addr2line_path or not idedata.firmware_elf_path:
+        try:
+            addr2line_path = idf_toolchain.get_addr2line_path()
+            firmware_elf_path = idf_toolchain.get_elf_path()
+        except RuntimeError as err:
+            raise EsphomeError(f"ESP-IDF toolchain not available: {err}") from err
+    else:
+        from esphome.platformio import toolchain
+
+        idedata = toolchain.get_idedata(config)
+        addr2line_path = idedata.addr2line_path
+        firmware_elf_path = idedata.firmware_elf_path
+    if not addr2line_path or not firmware_elf_path:
         _LOGGER.debug("decode_pc no addr2line")
         return
-    command = [idedata.addr2line_path, "-pfiaC", "-e", idedata.firmware_elf_path, addr]
+    command = [str(addr2line_path), "-pfiaC", "-e", str(firmware_elf_path), addr]
     try:
         translation = subprocess.check_output(command, close_fds=False).decode().strip()
     except Exception:  # pylint: disable=broad-except

esphome/components/esp32_ble_client/ble_client_base.cpp

@@ -72,6 +72,7 @@ void BLEClientBase::loop() {
     // never delivered CLOSE_EVT/DISCONNECT_EVT, services would leak without this call.
     this->release_services();
     this->set_idle_();
+    this->on_disconnect_complete(ESP_GATT_CONN_TIMEOUT);
   }
 }
 
@@ -418,6 +419,7 @@ bool BLEClientBase::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_
       this->log_gattc_lifecycle_event_("CLOSE");
       this->release_services();
       this->set_idle_();
+      this->on_disconnect_complete(param->close.reason);
       break;
     }
     case ESP_GATTC_SEARCH_RES_EVT: {

esphome/components/esp32_ble_client/ble_client_base.h

@@ -140,6 +140,12 @@ class BLEClientBase : public espbt::ESPBTClient, public Component {
   void log_gattc_warning_(const char *operation, esp_err_t err);
   void log_connection_params_(const char *param_type);
   void handle_connection_result_(esp_err_t ret);
+  /// Hook called once a connection has been fully torn down (after release_services() and
+  /// set_idle_()), from both the CLOSE_EVT handler and the DISCONNECTING safety timeout.
+  /// Subclasses with extra per-connection accounting (e.g. bluetooth_proxy slot state)
+  /// override this to release that state. `reason` is the controller reason code, or
+  /// ESP_GATT_CONN_TIMEOUT for the safety-timeout path.
+  virtual void on_disconnect_complete(esp_err_t reason) {}
   /// Transition to IDLE and reset conn_id — call when the connection is fully dead.
   void set_idle_() {
     this->set_state(espbt::ClientState::IDLE);
@@ -149,6 +155,10 @@ class BLEClientBase : public espbt::ESPBTClient, public Component {
   void set_disconnecting_() {
     this->disconnecting_started_ = millis();
     this->set_state(espbt::ClientState::DISCONNECTING);
+    // BluetoothConnection::loop() disables the component loop after service discovery
+    // completes, so the DISCONNECTING timeout check in loop() would never run if CLOSE_EVT
+    // gets lost. Re-enable the loop so the 10s safety timeout can force IDLE.
+    this->enable_loop();
   }
   // Compact error logging helpers to reduce flash usage
   void log_error_(const char *message);

esphome/components/esp8266/hal.cpp

@@ -5,6 +5,7 @@
 
 #include <Arduino.h>
 #include <core_esp8266_features.h>
+#include <coredecls.h>
 
 extern "C" {
 #include <user_interface.h>
@@ -71,23 +72,22 @@ uint32_t IRAM_ATTR HOT millis() {
   return result;
 }
 
-// Poll-based delay that avoids ::delay() — Arduino's __delay has an intra-object
-// call to the original millis() that --wrap can't intercept, so calling ::delay()
-// would keep the slow Arduino millis body alive in IRAM. optimistic_yield still
-// enters esp_schedule()/esp_suspend_within_cont() via yield(), so SDK tasks and
-// WiFi run correctly. Theoretically less power-efficient than Arduino's
-// os_timer-based delay() for long waits, but nearly all ESPHome delays are short
-// (sensor/I²C/SPI settling in the 1–100 ms range) where the difference is
-// negligible.
+// Delegate to Arduino's 1-arg esp_delay(), which uses os_timer + esp_suspend to
+// suspend the cont task for `ms` milliseconds without polling millis(). This
+// matches pre-2026.5.0 behavior (when esphome::delay() forwarded to ::delay())
+// and lets the SDK run freely while we wait, which timing-sensitive
+// interrupt-driven code (e.g. ESP8266 software-serial RX in components like
+// fingerprint_grow) depends on. The poll-based busy-wait that this replaced
+// rarely yielded inside short waits like delay(1), starving WiFi/SDK tasks and
+// extending interrupt latency. Unlike ::delay(), esp_delay()'s 1-arg form does
+// not call millis(), so the slow Arduino millis() body is not pulled into IRAM
+// by this path (the --wrap=millis goal of #15662 is preserved).
 void HOT delay(uint32_t ms) {
   if (ms == 0) {
     optimistic_yield(1000);
     return;
   }
-  uint32_t start = millis();
-  while (millis() - start < ms) {
-    optimistic_yield(1000);
-  }
+  esp_delay(ms);
 }
 
 void arch_restart() {

esphome/components/libretiny/hal.h

@@ -11,11 +11,19 @@
 #include "esphome/core/time_64.h"
 
 // IRAM_ATTR places a function in executable RAM so it is callable from an
-// ISR even while flash is busy (XIP stall, OTA, logger flash write).
-// Each family uses a section its stock linker already routes to RAM:
-// RTL8710B → .image2.ram.text, RTL8720C → .sram.text. LN882H is the
-// exception: its stock linker has no matching glob, so patch_linker.py
-// injects KEEP(*(.sram.text*)) into .flash_copysection at pre-link.
+// ISR even while flash is busy (XIP stall, OTA, logger flash write). All
+// LibreTiny families that need it share the same .sram.text input section
+// name; how that section is routed into RAM differs per family:
+//   RTL8720C: stock linker consumes *(.sram.text*) into .ram.code_text.
+//   RTL8710B: patch_linker.py.script injects KEEP(*(.sram.text*)) at the
+//             top of .ram_image2.data (which IS in ltchiptool's
+//             sections_ram). The stock linker has KEEP(*(.image2.ram.text*))
+//             in .ram_image2.text but that output section is NOT in
+//             ltchiptool's AmebaZ elf2bin sections_ram list, so code routed
+//             there is dropped from the flashed binary.
+//   LN882H:   patch_linker.py.script injects KEEP(*(.sram.text*)) into
+//             .flash_copysection (> RAM0 AT> FLASH), after KEEP(*(.vectors))
+//             so the Cortex-M4 vector table stays 512-byte-aligned for VTOR.
 //
 // BK72xx (all variants) are left as a no-op: their SDK wraps flash
 // operations in GLOBAL_INT_DISABLE() which masks FIQ + IRQ at the CPU for
@@ -26,13 +34,7 @@
 // layer.
 #if defined(USE_BK72XX)
 #define IRAM_ATTR
-#elif defined(USE_LIBRETINY_VARIANT_RTL8710B)
-// Stock linker consumes *(.image2.ram.text*) into .ram_image2.text (> BD_RAM).
-#define IRAM_ATTR __attribute__((noinline, section(".image2.ram.text")))
 #else
-// RTL8720C: stock linker consumes *(.sram.text*) into .ram.code_text.
-// LN882H: patch_linker.py.script injects *(.sram.text*) into
-// .flash_copysection (> RAM0 AT> FLASH).
 #define IRAM_ATTR __attribute__((noinline, section(".sram.text")))
 #endif
 #define PROGMEM

esphome/components/libretiny/patch_linker.py.script

@@ -6,14 +6,22 @@ import re
 import subprocess
 
 # ESPHome marks ISR code IRAM_ATTR, which on LibreTiny maps to a per-family
-# section routed into RAM-executable memory (see esphome/core/hal.h).
+# section routed into RAM-executable memory (see esphome/core/hal.h). The
+# input section name is always .sram.text; only the output section it lands
+# in differs per family.
 #
 # This script is NOT loaded on BK72xx (IRAM_ATTR is a no-op there; the SDK
 # masks FIQ+IRQ around flash writes). On the remaining families:
-# - RTL8710B: hal.h uses section(".image2.ram.text"); stock linker consumes it.
-# - RTL8720C: hal.h uses section(".sram.text"); stock linker consumes it.
+# - RTL8720C: stock linker consumes *(.sram.text*) into .ram.code_text.
+# - RTL8710B: stock linker has KEEP(*(.image2.ram.text*)) in .ram_image2.text,
+#   but ltchiptool's AmebaZ elf2bin (soc/ambz/binary.py) does NOT list
+#   .ram_image2.text in sections_ram, so code there is silently dropped from
+#   the flashed image. Inject KEEP(*(.sram.text*)) at the top of
+#   .ram_image2.data (which IS extracted) instead.
 # - LN882H: stock linker has no glob for ".sram.text", so we inject
-#   KEEP(*(.sram.text*)) into ".flash_copysection" (> RAM0 AT> FLASH).
+#   KEEP(*(.sram.text*)) into ".flash_copysection" (> RAM0 AT> FLASH)
+#   immediately after KEEP(*(.vectors)), so the vector table stays at
+#   __copysection_ram0_start (0x20000000) for correct Cortex-M4 VTOR alignment.
 #
 # All families also get a post-link summary showing where IRAM_ATTR landed.
 
@@ -27,7 +35,25 @@ _KEEP_LINE = (
     "__esphome_sram_text_end = .; "
     + _MARKER + "\n"
 )
-_LN_COPY = re.compile(r"(\.flash_copysection\s*:\s*\{\s*\n)")
+# Inject after KEEP(*(.vectors)) so the vector table stays at
+# __copysection_ram0_start (0x20000000). Cortex-M4 VTOR requires a 512-byte-
+# aligned address; injecting before the vectors would push them to an
+# unaligned offset and mis-route every IRQ handler.
+_LN_COPY = re.compile(r"(KEEP\(\*\(\.vectors\)\)[^\n]*\n)")
+# Inject at the top of .ram_image2.data, before __data_start__ so our code
+# does not fall inside the data range markers. .ram_image2.data is one of the
+# sections ltchiptool's AmebaZ elf2bin extracts; BD_RAM is rwx so the code is
+# executable. AmbZ has no C runtime .data copy loop (the bootloader loads
+# image2 into BD_RAM whole) so the inline code is not clobbered after boot.
+#
+# The regex is intentionally strict (no attribute / ALIGN between the section
+# name and the opening brace, brace on its own line). If a future AmbZ SDK
+# linker template changes this format, _pre_link raises RuntimeError on the
+# unpatched .ld file(s), and the RTL8710B CI compile job in
+# tests/test_build_components fails on the PR, surfacing the mismatch loudly
+# rather than silently shipping a binary with IRAM_ATTR code dropped from
+# one or both OTA slots.
+_AMBZ_DATA = re.compile(r"(\.ram_image2\.data\s*:\s*\n?\s*\{\s*\n)")
 
 
 def _detect(env):
@@ -56,7 +82,7 @@ KNOWN_VARIANTS = frozenset({
 
 
 def _inject_keep(host_section):
-    """Return a patcher that injects _KEEP_LINE at the top of `host_section`."""
+    """Return a patcher that injects _KEEP_LINE after `host_section` match."""
     def patch(content):
         if _MARKER in content:
             return content
@@ -65,12 +91,11 @@ def _inject_keep(host_section):
 
 
 # Variants not listed here intentionally have no .ld patcher:
-# - RTL8710B: hal.h uses section(".image2.ram.text") which the stock linker
-#   already routes into .ram_image2.text (> BD_RAM).
-# - RTL8720C: stock linker already consumes *(.sram.text*).
+# - RTL8720C: stock linker already consumes *(.sram.text*) into .ram.code_text.
 # - BK72xx (all): SDK masks FIQ+IRQ around flash writes, IRAM_ATTR is no-op.
 _PATCHERS_BY_VARIANT = {
     "LN882H": (_inject_keep(_LN_COPY),),
+    "RTL8710B": (_inject_keep(_AMBZ_DATA),),
 }
 
 
@@ -81,13 +106,14 @@ def _patchers_for(variant):
 def _pre_link(target, source, env):
     build_dir = env.subst("$BUILD_DIR")
     ld_files = [f for f in os.listdir(build_dir) if f.endswith(".ld")]
-    patched = 0
+    patched = []
+    unpatched = []
     for name in ld_files:
         path = os.path.join(build_dir, name)
         with open(path, "r", encoding="utf-8") as fh:
             original = fh.read()
         if _MARKER in original:
-            patched += 1
+            patched.append(name)
             continue
         content = original
         for fn in _patchers:
@@ -96,7 +122,9 @@ def _pre_link(target, source, env):
             with open(path, "w", encoding="utf-8") as fh:
                 fh.write(content)
             print("ESPHome: patched {} for IRAM_ATTR placement".format(name))
-            patched += 1
+            patched.append(name)
+        else:
+            unpatched.append(name)
     if not patched:
         raise RuntimeError(
             "ESPHome: no .ld in {} was patched for IRAM_ATTR. Update the "
@@ -104,6 +132,20 @@ def _pre_link(target, source, env):
                 build_dir
             )
         )
+    # Every .ld in the build must be patched. RTL8710B generates one .ld per
+    # OTA slot (xip1, xip2); if only one matches, the unpatched slot would
+    # ship with IRAM_ATTR code dropped to zeros and brick the device on the
+    # boot after an OTA into that slot.
+    if unpatched:
+        raise RuntimeError(
+            "ESPHome: {} of {} .ld file(s) in {} were not patched for "
+            "IRAM_ATTR: {}. The regex in patch_linker.py.script "
+            "(_PATCHERS_BY_VARIANT[{!r}]) matched the others but not "
+            "these. Update the regex to cover all linker scripts.".format(
+                len(unpatched), len(ld_files), build_dir,
+                ", ".join(unpatched), _variant,
+            )
+        )
 
 
 # Substrings matched against demangled names as a fallback on RTL8720C,

esphome/components/packages/__init__.py

@@ -215,7 +215,7 @@ def _process_remote_package(config: dict[str, Any]) -> dict[str, Any]:
     If loading fails after cloning, attempts a revert and retry in case
     a prior cached checkout is stale.
     """
-    repo_dir, revert = git.clone_or_update(
+    repo_root, revert = git.clone_or_update(
         url=config[CONF_URL],
         ref=config.get(CONF_REF),
         refresh=config[CONF_REFRESH],
@@ -225,6 +225,10 @@ def _process_remote_package(config: dict[str, Any]) -> dict[str, Any]:
     )
     files: list[dict[str, Any]] = []
 
+    # ``repo_root`` is the directory containing ``.git`` and must be passed
+    # to git for symlink-stub resolution. ``repo_dir`` may be narrowed to a
+    # subdirectory via the user's CONF_PATH and is used for file lookups.
+    repo_dir = repo_root
     if base_path := config.get(CONF_PATH):
         repo_dir = repo_dir / base_path
 
@@ -236,13 +240,37 @@ def _process_remote_package(config: dict[str, Any]) -> dict[str, Any]:
 
     def _load_package_yaml(yaml_file: Path, filename: str) -> dict:
         """Load a YAML file from a remote package, validating min_version."""
-        try:
-            new_yaml = yaml_util.load_yaml(yaml_file)
-        except EsphomeError as e:
+
+        def _load(path: Path) -> dict | str | None:
+            try:
+                return yaml_util.load_yaml(path)
+            except EsphomeError as e:
+                raise cv.Invalid(
+                    f"{filename} is not a valid YAML file."
+                    f" Please check the file contents.\n{e}"
+                ) from e
+
+        new_yaml = _load(yaml_file)
+        if not isinstance(new_yaml, dict):
+            # On Windows, git defaults to core.symlinks=false unless the user
+            # has Developer Mode enabled or is running elevated. Files stored
+            # in the repo as symlinks (tree mode 120000) are then checked out
+            # as plain text files containing the symlink target path, so
+            # parsing them as YAML yields a bare scalar instead of a mapping.
+            # Best-effort: follow the symlink target ourselves and re-load.
+            target = git.resolve_symlink_stub(repo_root, yaml_file)
+            if target is not None:
+                new_yaml = _load(target)
+        if not isinstance(new_yaml, dict):
             raise cv.Invalid(
-                f"{filename} is not a valid YAML file."
-                f" Please check the file contents.\n{e}"
-            ) from e
+                f"{filename} does not contain a YAML mapping at the top level "
+                f"(got {type(new_yaml).__name__}). "
+                f"If this file is a git symlink in the source repository, it "
+                f"may not have been materialized correctly on your platform "
+                f"(this is a known issue with git on Windows without Developer "
+                f"Mode enabled). Try pointing your package at the real file "
+                f"path instead."
+            )
         esphome_config = new_yaml.get(CONF_ESPHOME) or {}
         min_version = esphome_config.get(CONF_MIN_VERSION)
         if min_version is not None and cv.Version.parse(min_version) > cv.Version.parse(

esphome/components/sendspin/__init__.py

@@ -206,7 +206,7 @@ async def to_code(config: ConfigType) -> None:
         )
 
     # sendspin-cpp library
-    esp32.add_idf_component(name="sendspin/sendspin-cpp", ref="0.6.0")
+    esp32.add_idf_component(name="sendspin/sendspin-cpp", ref="0.6.1")
 
     cg.add_define("USE_SENDSPIN", True)  # for MDNS
 

esphome/components/sx126x/sx126x.cpp

@@ -30,8 +30,8 @@ static constexpr uint8_t OCP_140MA = 0x38;  // 140 mA max current
 static constexpr float LOW_DATA_RATE_OPTIMIZE_THRESHOLD = 16.38f;  // 16.38 ms
 
 uint8_t SX126x::read_fifo_(uint8_t offset, std::vector<uint8_t> &packet) {
-  this->wait_busy_();
   this->enable();
+  this->wait_busy_();
   this->transfer_byte(RADIO_READ_BUFFER);
   this->transfer_byte(offset);
   uint8_t status = this->transfer_byte(0x00);
@@ -43,8 +43,8 @@ uint8_t SX126x::read_fifo_(uint8_t offset, std::vector<uint8_t> &packet) {
 }
 
 void SX126x::write_fifo_(uint8_t offset, const std::vector<uint8_t> &packet) {
-  this->wait_busy_();
   this->enable();
+  this->wait_busy_();
   this->transfer_byte(RADIO_WRITE_BUFFER);
   this->transfer_byte(offset);
   for (const uint8_t &byte : packet) {
@@ -55,8 +55,8 @@ void SX126x::write_fifo_(uint8_t offset, const std::vector<uint8_t> &packet) {
 }
 
 uint8_t SX126x::read_opcode_(uint8_t opcode, uint8_t *data, uint8_t size) {
-  this->wait_busy_();
   this->enable();
+  this->wait_busy_();
   this->transfer_byte(opcode);
   uint8_t status = this->transfer_byte(0x00);
   for (int32_t i = 0; i < size; i++) {
@@ -67,8 +67,8 @@ uint8_t SX126x::read_opcode_(uint8_t opcode, uint8_t *data, uint8_t size) {
 }
 
 void SX126x::write_opcode_(uint8_t opcode, uint8_t *data, uint8_t size) {
-  this->wait_busy_();
   this->enable();
+  this->wait_busy_();
   this->transfer_byte(opcode);
   for (int32_t i = 0; i < size; i++) {
     this->transfer_byte(data[i]);
@@ -78,8 +78,8 @@ void SX126x::write_opcode_(uint8_t opcode, uint8_t *data, uint8_t size) {
 }
 
 void SX126x::read_register_(uint16_t reg, uint8_t *data, uint8_t size) {
-  this->wait_busy_();
   this->enable();
+  this->wait_busy_();
   this->write_byte(RADIO_READ_REGISTER);
   this->write_byte((reg >> 8) & 0xFF);
   this->write_byte((reg >> 0) & 0xFF);
@@ -91,8 +91,8 @@ void SX126x::read_register_(uint16_t reg, uint8_t *data, uint8_t size) {
 }
 
 void SX126x::write_register_(uint16_t reg, uint8_t *data, uint8_t size) {
-  this->wait_busy_();
   this->enable();
+  this->wait_busy_();
   this->write_byte(RADIO_WRITE_REGISTER);
   this->write_byte((reg >> 8) & 0xFF);
   this->write_byte((reg >> 0) & 0xFF);
@@ -394,7 +394,7 @@ void SX126x::run_image_cal() {
     buf[1] = 0xE9;
   } else if (this->frequency_ > 850000000) {
     buf[0] = 0xD7;
-    buf[1] = 0xD8;
+    buf[1] = 0xDB;
   } else if (this->frequency_ > 770000000) {
     buf[0] = 0xC1;
     buf[1] = 0xC5;

esphome/components/tuya/tuya.cpp

@@ -206,15 +206,17 @@ void Tuya::handle_command_(uint8_t command, uint8_t version, const uint8_t *buff
         if (this->status_pin_reported_ != -1) {
           this->init_state_ = TuyaInitState::INIT_DATAPOINT;
           this->send_empty_command_(TuyaCommandType::DATAPOINT_QUERY);
-          bool is_pin_equals =
-              this->status_pin_ != nullptr && this->status_pin_->get_pin() == this->status_pin_reported_;
-          // Configure status pin toggling (if reported and configured) or WIFI_STATE periodic send
-          if (!is_pin_equals) {
-            ESP_LOGW(TAG, "Supplied status_pin does not equals the reported pin %i. Using supplied pin anyway.",
+          if (this->status_pin_ != nullptr) {
+            if (this->status_pin_->get_pin() != this->status_pin_reported_) {
+              ESP_LOGW(TAG, "Supplied status_pin does not equal the reported pin %i. Using supplied pin anyway.",
+                       this->status_pin_reported_);
+            }
+            ESP_LOGV(TAG, "Configured status pin %i", this->status_pin_->get_pin());
+            this->set_interval("wifi", 1000, [this] { this->set_status_pin_(); });
+          } else {
+            ESP_LOGW(TAG, "MCU reported status_pin %i but no status_pin was configured; running in limited mode.",
                      this->status_pin_reported_);
           }
-          ESP_LOGV(TAG, "Configured status pin %i", this->status_pin_->get_pin());
-          this->set_interval("wifi", 1000, [this] { this->set_status_pin_(); });
         } else {
           this->init_state_ = TuyaInitState::INIT_WIFI;
           ESP_LOGV(TAG, "Configured WIFI_STATE periodic send");

esphome/components/uart/__init__.py

@@ -513,10 +513,11 @@ async def uart_write_to_code(config, action_id, template_arg, args):
 @coroutine_with_priority(CoroPriority.FINAL)
 async def final_step():
     """Final code generation step to configure optional UART features."""
-    if CORE.is_esp32 and CORE.has_networking:
-        # Wake-on-RX is essentially free on ESP32 (just an ISR function pointer
-        # registration) — enable by default to reduce RX buffer overflow risk
-        # by waking the main loop immediately when data arrives.
+    if (CORE.is_esp32 or CORE.is_esp8266) and CORE.has_networking:
+        # Wake-on-RX is essentially free (just an ISR function pointer
+        # registration on ESP32, an inline flag set on ESP8266 software
+        # serial) — enable by default to reduce RX buffer overflow risk by
+        # waking the main loop immediately when data arrives.
         cg.add_define("USE_UART_WAKE_LOOP_ON_RX")
 
 

esphome/components/uart/uart_component_esp8266.cpp

@@ -4,6 +4,9 @@
 #include "esphome/core/defines.h"
 #include "esphome/core/helpers.h"
 #include "esphome/core/log.h"
+#ifdef USE_UART_WAKE_LOOP_ON_RX
+#include "esphome/core/wake.h"
+#endif
 
 #ifdef USE_LOGGER
 #include "esphome/components/logger/logger.h"
@@ -149,7 +152,11 @@ void ESP8266UartComponent::dump_config() {
   if (this->hw_serial_ != nullptr) {
     ESP_LOGCONFIG(TAG, "  Using hardware serial interface.");
   } else {
-    ESP_LOGCONFIG(TAG, "  Using software serial");
+    ESP_LOGCONFIG(TAG, "  Using software serial"
+#ifdef USE_UART_WAKE_LOOP_ON_RX
+                       "\n  Wake on data RX: ENABLED"
+#endif
+    );
   }
   this->check_logger_conflict();
 }
@@ -266,6 +273,12 @@ void IRAM_ATTR ESP8266SoftwareSerial::gpio_intr(ESP8266SoftwareSerial *arg) {
   arg->rx_in_pos_ = (arg->rx_in_pos_ + 1) % arg->rx_buffer_size_;
   // Clear RX pin so that the interrupt doesn't re-trigger right away again.
   arg->rx_pin_.clear_interrupt();
+#ifdef USE_UART_WAKE_LOOP_ON_RX
+  // Wake the main loop so the consuming component drains the byte promptly
+  // instead of waiting for the next loop_interval_ tick. Important for timing
+  // sensitive setups that poll read() in a tight loop (e.g. fingerprint_grow).
+  wake_loop_isrsafe();
+#endif
 }
 void IRAM_ATTR HOT ESP8266SoftwareSerial::write_byte(uint8_t data) {
   if (this->gpio_tx_pin_ == nullptr) {

esphome/const.py

@@ -4,7 +4,7 @@ from enum import Enum
 
 from esphome.enum import StrEnum
 
-__version__ = "2026.5.0"
+__version__ = "2026.5.2"
 
 ALLOWED_NAME_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789-_"
 VALID_SUBSTITUTIONS_CHARACTERS = (

esphome/core/config.py

@@ -711,6 +711,7 @@ async def to_code(config: ConfigType) -> None:
     # Process areas
     all_areas: list[dict[str, str | core.ID]] = []
     if CONF_AREA in config:
+        CORE.area = config[CONF_AREA][CONF_NAME]
         all_areas.append(config[CONF_AREA])
     all_areas.extend(config[CONF_AREAS])
 

esphome/espidf/component.py

@@ -93,7 +93,7 @@ class URLSource(Source):
 
 
 class GitSource(Source):
-    def __init__(self, url: str, ref: str):
+    def __init__(self, url: str, ref: str | None):
         self.url = url
         self.ref = ref
 
@@ -109,7 +109,7 @@ class GitSource(Source):
         return path
 
     def __str__(self):
-        return f"{self.url}#{self.ref}"
+        return f"{self.url}#{self.ref}" if self.ref else self.url
 
 
 class InvalidIDFComponent(Exception):
@@ -352,7 +352,6 @@ def _convert_library_to_component(library: Library) -> IDFComponent:
         IDFComponent: The resolved component with name, version, and URL
 
     Raises:
-        ValueError: If a repository URL is missing a reference (#)
         RuntimeError: If no artifact can be found for the library
     """
     name = None
@@ -362,10 +361,11 @@ def _convert_library_to_component(library: Library) -> IDFComponent:
     #  Repository is provided directly
     if library.repository:
         # Parse repository URL: path becomes the component name, fragment
-        # becomes the git ref stored on GitSource.
+        # (if any) becomes the git ref stored on GitSource. A missing
+        # fragment is fine -- clone_or_update leaves the depth-1 clone on
+        # the remote's default branch, matching PIO's lib_deps behavior
+        # and external_components handling.
         split_result = urlsplit(library.repository)
-        if not split_result.fragment.strip():
-            raise ValueError(f"Missing ref in URL {library.repository}")
 
         # Sanitize name
         name = str(split_result.path).strip("/")
@@ -377,7 +377,8 @@ def _convert_library_to_component(library: Library) -> IDFComponent:
         version = "*"
         repository = urlunsplit(split_result._replace(fragment=""))
 
-        source = GitSource(str(repository), split_result.fragment)
+        ref = split_result.fragment.strip() or None
+        source = GitSource(str(repository), ref)
 
     # Version is provided - resolve using PlatformIO registry
     elif library.version:
@@ -655,6 +656,26 @@ def _process_dependencies(component: IDFComponent):
     if not dependencies:
         return
 
+    # PIO's library.json accepts both the list-of-dicts form and the
+    # shorthand dict form ``{"owner/Name": "version_spec"}``. Normalize
+    # the dict form so the loop below sees a uniform list. Iterating a
+    # dict gives string keys, which would silently fail the
+    # ``"name" in dependency`` substring check and skip every entry.
+    if isinstance(dependencies, dict):
+        normalized = []
+        for raw_name, spec in dependencies.items():
+            if "/" in raw_name:
+                owner, pkgname = raw_name.split("/", 1)
+            else:
+                owner, pkgname = None, raw_name
+            entry = {"name": pkgname, "owner": owner}
+            if isinstance(spec, dict):
+                entry.update(spec)
+            else:
+                entry["version"] = spec
+            normalized.append(entry)
+        dependencies = normalized
+
     _LOGGER.info("Processing %s@%s component dependencies...", name, version)
     for dependency in dependencies:
         # Validate dependency structure

esphome/espidf/framework.py

@@ -7,6 +7,7 @@ import json
 import logging
 import os
 from pathlib import Path
+import platform
 import shutil
 import subprocess
 import sys
@@ -17,7 +18,7 @@ import requests
 
 from esphome.config_validation import Version
 from esphome.core import CORE
-from esphome.helpers import ProgressBar, get_str_env, rmtree
+from esphome.helpers import ProgressBar, get_str_env, rmtree, write_file_if_changed
 
 PathType = str | os.PathLike
 
@@ -546,11 +547,11 @@ def _tar_extract_all(
                     if not (mode & stat.S_IXUSR):
                         mode &= ~(stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
                     mode |= stat.S_IRUSR | stat.S_IWUSR
-                elif member.isdir() or member.issym():
-                    # Ignore mode for directories & symlinks
-                    mode = None
-                else:
-                    # Block special files
+                elif not (member.isdir() or member.issym()):
+                    # Block special files. Directories and symlinks keep
+                    # their masked-original mode — passing None here would
+                    # crash tarfile.extract on Python <3.12 (its chmod
+                    # path calls os.chmod unconditionally).
                     continue
 
                 member.mode = mode
@@ -780,6 +781,102 @@ def download_from_mirrors(
         return None
 
 
+def _write_idf_version_txt(framework_path: Path, version: str) -> None:
+    """Write <framework_path>/version.txt if missing.
+
+    IDF's build.cmake picks the version it embeds in the firmware (and
+    stamps onto the bootloader) in this order: ``${IDF_PATH}/version.txt``
+    if present, else ``git describe`` against IDF_PATH, else the
+    ``IDF_VERSION_MAJOR/MINOR/PATCH`` triplet from ``tools/cmake/version.cmake``.
+    On a clean esphome-libs tarball ``.git`` is fully stripped, so
+    git_describe returns ``HEAD-HASH-NOTFOUND`` (falsy) and the triplet
+    wins -- correct by luck. But a *partial* ``.git`` (e.g. a custom
+    framework.source pointed at a real git URL where build artifacts
+    mark the tree dirty) makes git_describe return ``<hash>-dirty``,
+    which is what then gets baked into the bootloader. Dropping
+    version.txt forces the right answer regardless.
+    """
+    version_txt = framework_path / "version.txt"
+    if version_txt.exists():
+        return
+    try:
+        version_txt.write_text(f"v{version}\n", encoding="utf-8")
+    except OSError as e:
+        _LOGGER.warning(
+            "Could not write %s (%s); bootloader version string may be incorrect.",
+            version_txt,
+            e,
+        )
+
+
+# Backport of espressif/esp-idf#18272: every ESPHome-supported IDF release
+# through v6.0 ships a tools.json whose ninja 1.12.1 entry has no
+# ``linux-arm64`` source. ``idf_tools.py`` then either fails to find a
+# matching binary or grabs the x86_64 one, which can't execute on
+# aarch64. cmake is already populated across the same release range; we
+# only need to inject ninja. Values lifted verbatim from the IDF v6.0.1
+# tools.json where the fix landed natively.
+_NINJA_ARM64_BACKPORT: dict[str, dict[str, str | int]] = {
+    "1.12.1": {
+        "rename_dist": "ninja-linux-arm64-v1.12.1.zip",
+        "sha256": "5c25c6570b0155e95fce5918cb95f1ad9870df5768653afe128db822301a05a1",
+        "size": 121787,
+        "url": "https://github.com/ninja-build/ninja/releases/download/v1.12.1/ninja-linux-aarch64.zip",
+    },
+}
+
+
+def _patch_tools_json_for_linux_arm64(framework_path: Path) -> None:
+    """Inject ninja linux-arm64 entries into the framework's tools.json on aarch64.
+
+    Idempotent: a tools.json that already has the entry, or a host that
+    isn't aarch64, is a no-op. Applied unconditionally on every install
+    check so a build dir extracted before the backport got fixed up
+    without forcing a clean.
+    """
+    if platform.machine() != "aarch64":
+        return
+
+    tools_json = framework_path / "tools" / "tools.json"
+    if not tools_json.is_file():
+        return
+
+    try:
+        with open(tools_json, encoding="utf-8") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError) as e:
+        _LOGGER.warning(
+            "Could not parse %s for linux-arm64 backport (%s); "
+            "skipping. A clean reinstall of the framework directory "
+            "may be needed.",
+            tools_json,
+            e,
+        )
+        return
+
+    changed = False
+    for tool in data.get("tools", []):
+        if tool.get("name") != "ninja":
+            continue
+        for ver in tool.get("versions", []):
+            entry = _NINJA_ARM64_BACKPORT.get(ver.get("name"))
+            if entry is None or ver.get("linux-arm64"):
+                continue
+            ver["linux-arm64"] = entry
+            changed = True
+
+    if changed:
+        # write_file_if_changed stages a tempfile in the destination dir
+        # and atomically replaces — safe against mid-write interruption
+        # and concurrent invocations.
+        write_file_if_changed(tools_json, json.dumps(data, indent=2) + "\n")
+        _LOGGER.info(
+            "Patched %s to add ninja linux-arm64 download "
+            "(espressif/esp-idf#18272 backport).",
+            tools_json,
+        )
+
+
 def _check_esphome_idf_framework_install(
     version: str,
     targets: list[str],
@@ -861,6 +958,16 @@ def _check_esphome_idf_framework_install(
             archive_extract_all(tmp.file, framework_path, progress_header="Extracting")
             extracted_marker.touch()
 
+    # Idempotent post-extract patch: written every invocation so a build
+    # dir extracted before this fix gets the file too, without forcing a
+    # clean. Skips when version.txt already exists.
+    _write_idf_version_txt(framework_path, version)
+
+    # Apply the ninja linux-arm64 backport on every invocation, not just on
+    # fresh extracts — idempotent and cheap, and lets a build dir carrying
+    # a pre-patch tools.json get fixed up without forcing a clean.
+    _patch_tools_json_for_linux_arm64(framework_path)
+
     # 3. Check if the framework tools are the same and correctly installed
     if not install:
         install = True

esphome/espidf/runner.py

@@ -66,6 +66,12 @@ FILTER_IDF_LINES: list[str] = [
     # Drop the blank line rich emits after the note so the build log
     # doesn't end with an orphan gap before ESPHome's own status lines.
     r"\s*$",
+    # ESP-IDF shells out to ``git rev-parse`` to embed a commit hash;
+    # esphome-libs strips ``.git`` from the tarball so those probes fail
+    # noisily without affecting the build.
+    r"-- git rev-parse returned ",
+    r"fatal: not a git repository",
+    r"Stopping at filesystem boundary",
 ]
 
 

esphome/git.py

@@ -6,6 +6,7 @@ import logging
 from pathlib import Path
 import re
 import subprocess
+import sys
 import urllib.parse
 
 import esphome.config_validation as cv
@@ -93,6 +94,92 @@ def _compute_destination_path(key: str, domain: str) -> Path:
     return base_dir / h.hexdigest()[:8]
 
 
+def resolve_symlink_stub(repo_dir: Path, file_path: Path) -> Path | None:
+    """Return the symlink target if ``file_path`` is a Windows-checked-out symlink stub.
+
+    On Windows, when ``core.symlinks=false`` (the default unless the user has
+    SeCreateSymbolicLinkPrivilege — i.e. Developer Mode or running elevated),
+    git materializes files with tree mode ``120000`` as plain text files
+    whose content is the literal symlink target path. Opening such a file
+    yields the target path string instead of the target's content.
+
+    If ``file_path`` is one of those stubs, return the resolved target Path
+    inside ``repo_dir``. Otherwise return ``None`` and the caller should use
+    ``file_path`` as-is.
+
+    Designed to be called *only* when normal access has already produced an
+    unexpected result (e.g. YAML parsed as a top-level scalar), so the
+    per-file ``git ls-files`` subprocess cost is paid only on the failure
+    path. Returns ``None`` on any error or check failure — it's purely a
+    best-effort recovery, never raises.
+    """
+    # On non-Windows, git creates real symlinks; ordinary file access already
+    # transparently follows them.
+    if sys.platform != "win32":
+        return None
+    if file_path.is_symlink():
+        return None
+    if not file_path.is_file():
+        return None
+
+    try:
+        rel = file_path.relative_to(repo_dir)
+    except ValueError:
+        return None
+
+    try:
+        # ``git ls-files -s <path>`` prints "<mode> <sha> <stage>\t<path>"
+        # for that single entry, or empty if untracked.
+        out = run_git_command(
+            ["git", "ls-files", "-s", "--", rel.as_posix()],
+            git_dir=repo_dir,
+        )
+    except GitException:
+        return None
+
+    parts = out.split()
+    if not parts or parts[0] != "120000":
+        return None
+
+    # Stubs are short ASCII relative paths. Decode defensively, and only
+    # strip the trailing newline git's checkout may append — preserving any
+    # whitespace that could be part of a valid target name.
+    try:
+        raw = file_path.read_bytes()
+    except OSError:
+        return None
+    try:
+        target_str = raw.decode("utf-8").rstrip("\r\n")
+    except UnicodeDecodeError:
+        return None
+
+    # ``Path()`` and ``Path.resolve()`` can raise on malformed inputs (e.g.
+    # embedded NUL bytes from a hostile symlink blob, paths too long for the
+    # OS, or temporary I/O errors). Catch broadly — this helper is purely a
+    # best-effort recovery and must never raise.
+    try:
+        target_path = (file_path.parent / target_str).resolve()
+        repo_root_resolved = repo_dir.resolve()
+    except (OSError, ValueError, RuntimeError):
+        return None
+
+    # ``Path.resolve()`` follows ``..``; re-verify containment afterwards.
+    try:
+        target_path.relative_to(repo_root_resolved)
+    except ValueError:
+        _LOGGER.warning(
+            "Refusing to follow symlink %s -> %s (escapes repository)",
+            file_path,
+            target_str,
+        )
+        return None
+
+    if not target_path.is_file():
+        return None
+
+    return target_path
+
+
 def clone_or_update(
     *,
     url: str,

esphome/idf_component.yml

@@ -100,6 +100,6 @@ dependencies:
   esp32async/asynctcp:
     version: 3.4.91
   sendspin/sendspin-cpp:
-    version: 0.6.0
+    version: 0.6.1
   lvgl/lvgl:
     version: 9.5.0

esphome/storage_json.py

@@ -14,6 +14,7 @@ from esphome.const import (
     KEY_CORE,
     KEY_TARGET_FRAMEWORK,
     KEY_TARGET_PLATFORM,
+    Toolchain,
 )
 from esphome.core import CORE
 from esphome.helpers import write_file_if_changed
@@ -98,6 +99,8 @@ class StorageJSON:
         no_mdns: bool,
         framework: str | None = None,
         core_platform: str | None = None,
+        toolchain: str | None = None,
+        area: str | None = None,
     ) -> None:
         # Version of the storage JSON schema
         assert storage_version is None or isinstance(storage_version, int)
@@ -134,6 +137,10 @@ class StorageJSON:
         self.framework = framework
         # The core platform of this firmware. Like "esp32", "rp2040", "host" etc.
         self.core_platform = core_platform
+        # The toolchain used for the build ("platformio" / "esp-idf")
+        self.toolchain = toolchain
+        # The area of the node
+        self.area = area
 
     def as_dict(self):
         return {
@@ -153,6 +160,8 @@ class StorageJSON:
             "no_mdns": self.no_mdns,
             "framework": self.framework,
             "core_platform": self.core_platform,
+            "toolchain": self.toolchain,
+            "area": self.area,
         }
 
     def to_json(self):
@@ -189,6 +198,8 @@ class StorageJSON:
             ),
             framework=esph.target_framework,
             core_platform=esph.target_platform,
+            toolchain=esph.toolchain.value if esph.toolchain is not None else None,
+            area=esph.area,
         )
 
     @staticmethod
@@ -236,6 +247,8 @@ class StorageJSON:
         no_mdns = storage.get("no_mdns", False)
         framework = storage.get("framework")
         core_platform = storage.get("core_platform")
+        toolchain = storage.get("toolchain")
+        area = storage.get("area")
         return StorageJSON(
             storage_version,
             name,
@@ -253,6 +266,8 @@ class StorageJSON:
             no_mdns,
             framework,
             core_platform,
+            toolchain,
+            area,
         )
 
     @staticmethod
@@ -273,6 +288,18 @@ class StorageJSON:
         """
         CORE.name = self.name
         CORE.build_path = self.build_path
+        # Restore toolchain so upload/logs picks the right firmware_bin path.
+        # An unknown value (corrupt sidecar, or written by a newer ESPHome)
+        # just leaves CORE.toolchain None — the fallback then picks PlatformIO.
+        if self.toolchain and CORE.toolchain is None:
+            try:
+                CORE.toolchain = Toolchain(self.toolchain)
+            except ValueError:
+                _LOGGER.debug(
+                    "Ignoring unknown toolchain %r from %s",
+                    self.toolchain,
+                    storage_path(),
+                )
         target_platform = self.core_platform or self.target_platform.lower()
         CORE.data[KEY_CORE] = {
             KEY_TARGET_PLATFORM: target_platform,

esphome/writer.py

@@ -87,6 +87,23 @@ def replace_file_content(text, pattern, repl):
 
 
 def storage_should_clean(old: StorageJSON | None, new: StorageJSON) -> bool:
+    """Return True when the build tree must be wiped before reuse.
+
+    Predicate is True when *old* is missing (first build),
+    ``src_version`` differs, ``build_path`` differs, the build
+    ``toolchain`` differs (e.g. switching between the PlatformIO and
+    native ESP-IDF toolchains, which produce incompatible build trees),
+    or a previously loaded integration was removed in *new*. Adding
+    integrations or changing unrelated fields (friendly name, esphome
+    version, etc.) does not trigger a clean.
+
+    Used by esphome-device-builder (esphome/device-builder) to gate
+    its remote-build artifact materialiser so a local → remote → local
+    cycle preserves PlatformIO's local object cache instead of wiping
+    it on every cycle. The signature, semantics, and ``None`` handling
+    for *old* are part of the public contract; keep them stable so the
+    offloader's wipe decision tracks core's.
+    """
     if old is None:
         return True
 
@@ -94,6 +111,8 @@ def storage_should_clean(old: StorageJSON | None, new: StorageJSON) -> bool:
         return True
     if old.build_path != new.build_path:
         return True
+    if old.toolchain != new.toolchain:
+        return True
     # Check if any components have been removed
     return bool(old.loaded_integrations - new.loaded_integrations)
 
@@ -490,6 +509,10 @@ def clean_build(clear_pio_cache: bool = True):
     if dependencies_lock.is_file():
         _LOGGER.info("Deleting %s", dependencies_lock)
         dependencies_lock.unlink()
+    idedata_cache = CORE.relative_internal_path("idedata", f"{CORE.name}.json")
+    if idedata_cache.is_file():
+        _LOGGER.info("Deleting %s", idedata_cache)
+        idedata_cache.unlink()
     # Native ESP-IDF toolchain artifacts: the IDF CMake/ninja build dir
     # and the Component Manager's fetched managed components live under
     # the project's build path, not under .pioenvs / .piolibdeps.

requirements.txt

@@ -13,7 +13,7 @@ esptool==5.2.0
 click==8.3.3
 esphome-dashboard==20260425.0
 aioesphomeapi==45.0.4
-zeroconf==0.149.12
+zeroconf==0.149.16
 puremagic==1.30
 ruamel.yaml==0.19.1 # dashboard_import
 ruamel.yaml.clib==0.2.15 # dashboard_import

tests/dashboard/test_web_server.py

@@ -1503,13 +1503,18 @@ async def test_websocket_refresh_command(
 ) -> None:
     """Test WebSocket refresh command triggers dashboard update."""
     with patch("esphome.dashboard.web_server.DASHBOARD_SUBSCRIBER") as mock_subscriber:
-        mock_subscriber.request_refresh = Mock()
+        # Signal an asyncio.Event when request_refresh is invoked so the
+        # test can deterministically wait for the server-side handler to run
+        # instead of relying on a fixed sleep (flaky on Windows CI under load).
+        called = asyncio.Event()
+        mock_subscriber.request_refresh = Mock(side_effect=called.set)
 
         # Send refresh command
         await websocket_client.write_message(json.dumps({"event": "refresh"}))
 
-        # Give it a moment to process
-        await asyncio.sleep(0.01)
+        # Wait for the server to process the message and invoke request_refresh
+        async with asyncio.timeout(5):
+            await called.wait()
 
         # Verify request_refresh was called
         mock_subscriber.request_refresh.assert_called_once()

tests/unit_tests/core/test_config.py

@@ -140,6 +140,33 @@ def test_multiple_areas_and_devices(yaml_file: Callable[[str], str]) -> None:
     }
 
 
+@pytest.mark.asyncio
+@pytest.mark.filterwarnings("ignore::RuntimeWarning")
+@pytest.mark.parametrize(
+    ("fixture", "expected_area"),
+    [
+        ("legacy_string_area.yaml", "Living Room"),
+        ("multiple_areas_devices.yaml", "Main Area"),
+    ],
+)
+async def test_to_code_records_core_area(
+    yaml_file: Callable[[str], Path],
+    fixture: str,
+    expected_area: str,
+) -> None:
+    """``to_code`` records the node's area name on CORE for StorageJSON."""
+    result = load_config_from_fixture(yaml_file, fixture, FIXTURES_DIR)
+    assert result is not None
+    assert CORE.area is None
+
+    with patch("esphome.core.config.cg") as mock_cg:
+        mock_cg.RawStatement.side_effect = lambda *args, **kwargs: MagicMock()
+        mock_cg.RawExpression.side_effect = lambda *args, **kwargs: MagicMock()
+        await config.to_code(result[CONF_ESPHOME])
+
+    assert CORE.area == expected_area
+
+
 def test_legacy_string_area(
     yaml_file: Callable[[str], str], caplog: pytest.LogCaptureFixture
 ) -> None:

tests/unit_tests/test_compiled_config.py

@@ -253,6 +253,106 @@ def test_run_esphome_upload_and_logs_fall_back_when_no_cache(
     mock_read.assert_called_once()
 
 
+def test_run_esphome_upload_does_not_refresh_cache_without_sidecar(
+    tmp_path: Path,
+) -> None:
+    """Without a StorageJSON sidecar (no compile has run), the fallback
+    skips the cache write -- load_compiled_config requires the sidecar,
+    so writing the rendered (secret-resolved) YAML would be inert and
+    leak secrets to disk for nothing."""
+    yaml_path = tmp_path / "lite_test.yaml"
+    yaml_path.write_text("esphome:\n  name: lite_test\n")
+    CORE.config_path = yaml_path
+
+    with (
+        patch(
+            "esphome.__main__.read_config",
+            return_value={"esphome": {"name": "lite_test"}},
+        ),
+        patch("esphome.compiled_config.save_compiled_config") as mock_save,
+        patch.dict(
+            "esphome.__main__.POST_CONFIG_ACTIONS",
+            {"upload": lambda args, config: 0},
+        ),
+    ):
+        run_esphome(["esphome", "upload", str(yaml_path)])
+
+    mock_save.assert_not_called()
+
+
+@pytest.mark.parametrize("command", ["upload", "logs"])
+def test_run_esphome_upload_and_logs_refresh_cache_on_fallback(
+    tmp_path: Path, command: str
+) -> None:
+    """A stale-cache fallback rewrites the cache so the next call hits
+    the fast path. Without this, every upload/logs after a YAML edit
+    pays for read_config() until the next compile rewrites the cache."""
+    yaml_path = tmp_path / "lite_test.yaml"
+    yaml_path.write_text("esphome:\n  name: lite_test\n")
+    CORE.config_path = yaml_path
+
+    storage_dir = tmp_path / ".esphome" / "storage"
+    _write_storage(storage_dir / "lite_test.yaml.json")
+    cache = _write_cache(storage_dir / "lite_test.yaml.validated.yaml")
+    _set_cache_mtime(cache, yaml_path, offset=-60)  # stale
+
+    fresh_config = {"esphome": {"name": "lite_test"}, "logger": {}}
+
+    with (
+        patch("esphome.__main__.read_config", return_value=fresh_config),
+        patch(
+            "esphome.compiled_config.save_compiled_config", wraps=save_compiled_config
+        ) as mock_save,
+        patch.dict(
+            "esphome.__main__.POST_CONFIG_ACTIONS",
+            {command: lambda args, config: 0},
+        ),
+    ):
+        assert run_esphome(["esphome", command, str(yaml_path)]) == 0
+
+    mock_save.assert_called_once_with(fresh_config)
+    # mtime is now newer than the source YAML, so a follow-up call hits
+    # the fast path instead of repeating read_config.
+    assert cache.stat().st_mtime >= yaml_path.stat().st_mtime
+
+
+def test_run_esphome_upload_with_substitution_does_not_refresh_cache(
+    fresh_cache_files: Path,
+) -> None:
+    """`-s` substitutions skip the cache on both read and write -- saving
+    here would clobber the cache with a substitution-specific config."""
+    with (
+        patch("esphome.__main__.read_config", return_value={"esphome": {}}),
+        patch("esphome.compiled_config.save_compiled_config") as mock_save,
+        patch.dict(
+            "esphome.__main__.POST_CONFIG_ACTIONS",
+            {"upload": lambda args, config: 0},
+        ),
+    ):
+        run_esphome(["esphome", "-s", "var", "val", "upload", str(fresh_cache_files)])
+
+    mock_save.assert_not_called()
+
+
+def test_run_esphome_compile_does_not_refresh_cache_via_fallback(
+    fresh_cache_files: Path,
+) -> None:
+    """Compile writes the cache through update_storage_json, not via the
+    upload/logs fallback path -- the fallback save would skip the
+    storage_should_clean check."""
+    with (
+        patch("esphome.__main__.read_config", return_value={"esphome": {}}),
+        patch("esphome.compiled_config.save_compiled_config") as mock_save,
+        patch.dict(
+            "esphome.__main__.POST_CONFIG_ACTIONS",
+            {"compile": lambda args, config: 0},
+        ),
+    ):
+        run_esphome(["esphome", "compile", str(fresh_cache_files)])
+
+    mock_save.assert_not_called()
+
+
 def test_run_esphome_upload_with_substitution_skips_cache(
     fresh_cache_files: Path,
 ) -> None:

tests/unit_tests/test_espidf_component.py

@@ -436,11 +436,21 @@ def test_convert_library_with_branch_ref():
     assert result.source.ref == "some-branch"
 
 
-def test_convert_library_missing_ref():
+def test_convert_library_missing_ref_uses_default_branch():
+    """A bare URL with no #ref clones the remote's default branch.
+
+    Matches PIO's lib_deps behavior and external_components handling --
+    git.clone_or_update with ref=None leaves the depth-1 clone on
+    whatever branch the remote HEAD points at.
+    """
     lib = Library("name", None, "https://github.com/foo/bar.git")
 
-    with pytest.raises(ValueError):
-        _convert_library_to_component(lib)
+    result = _convert_library_to_component(lib)
+
+    assert result.name == "foo/bar"
+    assert result.version == "*"
+    assert isinstance(result.source, GitSource)
+    assert result.source.ref is None
 
 
 def test_convert_library_registry(monkeypatch):
@@ -495,3 +505,113 @@ def test_process_dependencies_skips_invalid(tmp_component):
     _process_dependencies(tmp_component)
 
     assert tmp_component.dependencies == []
+
+
+def test_process_dependencies_dict_form(tmp_component, monkeypatch):
+    """PIO library.json shorthand ``{"owner/Name": "version"}`` is honored.
+
+    Iterating a dict gives string keys, which would silently fail the
+    ``"name" in dependency`` substring check. Normalize to list-of-dicts
+    first so the dict form (used by e.g. tesla-ble for its nanopb dep)
+    is treated the same as the verbose list form.
+    """
+    captured: list[Library] = []
+
+    def fake_generate(library):
+        captured.append(library)
+        return IDFComponent(
+            library.name, library.version, source=URLSource("http://dummy.com")
+        )
+
+    tmp_component.data = {
+        "dependencies": {
+            "nanopb/Nanopb": "^0.4.91",
+            "BareName": "1.2.3",
+        }
+    }
+    monkeypatch.setattr(
+        esphome.espidf.component, "_generate_idf_component", fake_generate
+    )
+    monkeypatch.setattr(esphome.espidf.component, "_check_library_data", lambda x: None)
+
+    _process_dependencies(tmp_component)
+
+    assert len(tmp_component.dependencies) == 2
+    names = sorted(lib.name for lib in captured)
+    versions = sorted(lib.version for lib in captured)
+    assert names == ["BareName", "nanopb/Nanopb"]
+    assert versions == ["1.2.3", "^0.4.91"]
+
+
+def test_process_dependencies_dict_form_with_url_value(tmp_component, monkeypatch):
+    """A dict-value that's a URL gets routed to ``repository`` like the list form."""
+    captured: list[Library] = []
+
+    def fake_generate(library):
+        captured.append(library)
+        return IDFComponent(library.name, "*", source=URLSource("http://dummy.com"))
+
+    tmp_component.data = {
+        "dependencies": {
+            "foo/Bar": "https://github.com/foo/bar.git#main",
+        }
+    }
+    monkeypatch.setattr(
+        esphome.espidf.component, "_generate_idf_component", fake_generate
+    )
+    monkeypatch.setattr(esphome.espidf.component, "_check_library_data", lambda x: None)
+
+    _process_dependencies(tmp_component)
+
+    assert len(captured) == 1
+    assert captured[0].name == "foo/Bar"
+    assert captured[0].version is None
+    assert captured[0].repository == "https://github.com/foo/bar.git#main"
+
+
+def test_process_dependencies_dict_form_with_nested_spec(tmp_component, monkeypatch):
+    """A dict-value that's itself a dict is merged into the entry.
+
+    PIO's library.json allows ``{"owner/Name": {"version": "...", ...}}``
+    for entries that need fields beyond just a version (platforms,
+    frameworks, etc.). The extra fields flow into _check_library_data
+    via the entry merge.
+    """
+    captured: list[Library] = []
+    checked: list[dict] = []
+
+    def fake_generate(library):
+        captured.append(library)
+        return IDFComponent(
+            library.name, library.version, source=URLSource("http://dummy.com")
+        )
+
+    tmp_component.data = {
+        "dependencies": {
+            "nanopb/Nanopb": {"version": "^0.4.91", "platforms": "espidf"},
+        }
+    }
+    monkeypatch.setattr(
+        esphome.espidf.component, "_generate_idf_component", fake_generate
+    )
+    monkeypatch.setattr(
+        esphome.espidf.component,
+        "_check_library_data",
+        checked.append,
+    )
+
+    _process_dependencies(tmp_component)
+
+    assert len(captured) == 1
+    assert captured[0].name == "nanopb/Nanopb"
+    assert captured[0].version == "^0.4.91"
+    # Extra spec fields reach _check_library_data so platform/framework
+    # gating still applies.
+    assert checked == [
+        {
+            "name": "Nanopb",
+            "owner": "nanopb",
+            "version": "^0.4.91",
+            "platforms": "espidf",
+        }
+    ]

tests/unit_tests/test_git.py

@@ -4,7 +4,7 @@ from datetime import datetime, timedelta
 import os
 from pathlib import Path
 from typing import Any
-from unittest.mock import Mock
+from unittest.mock import Mock, patch
 
 import pytest
 
@@ -1001,3 +1001,304 @@ def test_refresh_picks_up_new_remote_commits(
         "--hard",
         "old_sha",
     ]
+
+
+def test_resolve_symlink_stub_returns_none_on_non_windows(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """On non-Windows, resolve_symlink_stub returns None without calling git."""
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+    stub = repo_dir / "file.yaml"
+    stub.write_text("static/file.yaml")
+
+    with patch("esphome.git.sys.platform", "linux"):
+        result = git.resolve_symlink_stub(repo_dir, stub)
+
+    assert result is None
+    mock_run_git_command.assert_not_called()
+
+
+def test_resolve_symlink_stub_returns_target_for_mode_120000(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """A mode-120000 file is recognised as a stub; its target Path is returned."""
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+    (repo_dir / "static").mkdir()
+
+    target = repo_dir / "static" / "real.yaml"
+    target.write_text("esphome:\n  name: real\n")
+
+    stub = repo_dir / "real.yaml"
+    stub.write_text("static/real.yaml")
+
+    mock_run_git_command.return_value = "120000 abc123 0\treal.yaml"
+
+    with patch("esphome.git.sys.platform", "win32"):
+        result = git.resolve_symlink_stub(repo_dir, stub)
+
+    assert result == target.resolve()
+    # Stub file itself was not modified — only inspected.
+    assert stub.read_text() == "static/real.yaml"
+
+
+def test_resolve_symlink_stub_resolves_relative_parent_paths(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """Symlink targets with ``..`` segments resolve correctly within the repo."""
+    repo_dir = tmp_path / "repo"
+    (repo_dir / "subdir").mkdir(parents=True)
+    (repo_dir / "static").mkdir()
+
+    target = repo_dir / "static" / "shared.yaml"
+    target.write_text("shared content")
+
+    stub = repo_dir / "subdir" / "shared.yaml"
+    stub.write_text("../static/shared.yaml")
+
+    mock_run_git_command.return_value = "120000 abc123 0\tsubdir/shared.yaml"
+
+    with patch("esphome.git.sys.platform", "win32"):
+        result = git.resolve_symlink_stub(repo_dir, stub)
+
+    assert result == target.resolve()
+
+
+def test_resolve_symlink_stub_refuses_escape_outside_repo(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """A symlink pointing outside the repository is not followed."""
+    outside = tmp_path / "outside.yaml"
+    outside.write_text("sensitive")
+
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+
+    stub = repo_dir / "escape.yaml"
+    stub.write_text("../outside.yaml")
+
+    mock_run_git_command.return_value = "120000 abc123 0\tescape.yaml"
+
+    with patch("esphome.git.sys.platform", "win32"):
+        result = git.resolve_symlink_stub(repo_dir, stub)
+
+    assert result is None
+
+
+def test_resolve_symlink_stub_returns_none_for_real_symlink(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """A real symlink already opens transparently, so the helper short-circuits.
+
+    Skipped on Windows where symlink creation requires
+    SeCreateSymbolicLinkPrivilege.
+    """
+    if os.name == "nt":
+        pytest.skip("Requires symlink-creation privilege on Windows")
+
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+    target = repo_dir / "real.yaml"
+    target.write_text("real content")
+
+    real_link = repo_dir / "link.yaml"
+    real_link.symlink_to("real.yaml")
+
+    with patch("esphome.git.sys.platform", "win32"):
+        result = git.resolve_symlink_stub(repo_dir, real_link)
+
+    assert result is None
+    # No git call needed for real symlinks.
+    mock_run_git_command.assert_not_called()
+
+
+def test_resolve_symlink_stub_returns_none_for_regular_file(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """A regular file (mode 100644) whose content looks path-shaped is not
+    followed."""
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+
+    regular = repo_dir / "looks_like_path.txt"
+    regular.write_text("static/something.yaml")
+
+    mock_run_git_command.return_value = "100644 abc123 0\tlooks_like_path.txt"
+
+    with patch("esphome.git.sys.platform", "win32"):
+        result = git.resolve_symlink_stub(repo_dir, regular)
+
+    assert result is None
+
+
+def test_resolve_symlink_stub_returns_none_when_git_fails(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """If ``git ls-files`` fails (e.g. not a repo), the helper returns None."""
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+
+    stub = repo_dir / "real.yaml"
+    stub.write_text("static/real.yaml")
+
+    mock_run_git_command.side_effect = GitCommandError("ls-files exploded")
+
+    with patch("esphome.git.sys.platform", "win32"):
+        result = git.resolve_symlink_stub(repo_dir, stub)
+
+    assert result is None
+
+
+def test_resolve_symlink_stub_returns_none_for_non_utf8_content(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """A file whose bytes are not valid UTF-8 must not raise — return None."""
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+
+    stub = repo_dir / "binary.bin"
+    stub.write_bytes(b"\xff\xfe\x00\xff")
+
+    mock_run_git_command.return_value = "120000 abc123 0\tbinary.bin"
+
+    with patch("esphome.git.sys.platform", "win32"):
+        result = git.resolve_symlink_stub(repo_dir, stub)
+
+    assert result is None
+
+
+def test_resolve_symlink_stub_preserves_whitespace_in_target(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """Only trailing CR/LF is stripped — internal whitespace is preserved."""
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+    target_dir = repo_dir / "dir with spaces"
+    target_dir.mkdir()
+    target = target_dir / "real.yaml"
+    target.write_text("hello")
+
+    stub = repo_dir / "link.yaml"
+    # Trailing newline (as git's checkout may append) is stripped, but
+    # whitespace inside the target path itself must survive.
+    stub.write_bytes(b"dir with spaces/real.yaml\n")
+
+    mock_run_git_command.return_value = "120000 abc123 0\tlink.yaml"
+
+    with patch("esphome.git.sys.platform", "win32"):
+        result = git.resolve_symlink_stub(repo_dir, stub)
+
+    assert result == target.resolve()
+
+
+def test_resolve_symlink_stub_returns_none_for_directory_target(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """A symlink pointing at a directory has no file content to load."""
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+    (repo_dir / "dir_target").mkdir()
+
+    stub = repo_dir / "link_to_dir"
+    stub.write_text("dir_target")
+
+    mock_run_git_command.return_value = "120000 abc123 0\tlink_to_dir"
+
+    with patch("esphome.git.sys.platform", "win32"):
+        result = git.resolve_symlink_stub(repo_dir, stub)
+
+    assert result is None
+
+
+def test_resolve_symlink_stub_returns_none_when_resolve_raises(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """Path.resolve() raising (e.g. on a malformed target) must not propagate."""
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+
+    stub = repo_dir / "broken.yaml"
+    stub.write_text("ignored")
+
+    mock_run_git_command.return_value = "120000 abc123 0\tbroken.yaml"
+
+    with (
+        patch("esphome.git.sys.platform", "win32"),
+        patch.object(Path, "resolve", side_effect=OSError("bad path")),
+    ):
+        result = git.resolve_symlink_stub(repo_dir, stub)
+
+    assert result is None
+
+
+def test_resolve_symlink_stub_returns_none_when_file_missing(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """A file path that doesn't exist is rejected before git is consulted."""
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+
+    missing = repo_dir / "ghost.yaml"  # not created
+
+    with patch("esphome.git.sys.platform", "win32"):
+        result = git.resolve_symlink_stub(repo_dir, missing)
+
+    assert result is None
+    mock_run_git_command.assert_not_called()
+
+
+def test_resolve_symlink_stub_returns_none_when_path_outside_repo(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """A file path that isn't under repo_dir is rejected (ValueError from relative_to)."""
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+
+    outside = tmp_path / "stray.yaml"
+    outside.write_text("something")
+
+    with patch("esphome.git.sys.platform", "win32"):
+        result = git.resolve_symlink_stub(repo_dir, outside)
+
+    assert result is None
+    mock_run_git_command.assert_not_called()
+
+
+def test_resolve_symlink_stub_returns_none_when_untracked(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """Empty `git ls-files` output (untracked file) makes the helper return None."""
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+
+    stub = repo_dir / "untracked.yaml"
+    stub.write_text("static/foo.yaml")
+
+    mock_run_git_command.return_value = ""
+
+    with patch("esphome.git.sys.platform", "win32"):
+        result = git.resolve_symlink_stub(repo_dir, stub)
+
+    assert result is None
+
+
+def test_resolve_symlink_stub_returns_none_when_read_bytes_raises(
+    tmp_path: Path, mock_run_git_command: Mock
+) -> None:
+    """An OSError from read_bytes() (e.g. file vanished mid-call) must not propagate."""
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+
+    stub = repo_dir / "racy.yaml"
+    stub.write_text("static/racy.yaml")
+
+    mock_run_git_command.return_value = "120000 abc123 0\tracy.yaml"
+
+    with (
+        patch("esphome.git.sys.platform", "win32"),
+        patch.object(Path, "read_bytes", side_effect=OSError("vanished")),
+    ):
+        result = git.resolve_symlink_stub(repo_dir, stub)
+
+    assert result is None

tests/unit_tests/test_storage_json.py

@@ -9,7 +9,7 @@ from unittest.mock import MagicMock, Mock, patch
 import pytest
 
 from esphome import storage_json
-from esphome.const import CONF_DISABLED, CONF_MDNS
+from esphome.const import CONF_DISABLED, CONF_MDNS, Toolchain
 from esphome.core import CORE
 
 
@@ -205,6 +205,7 @@ def test_storage_json_as_dict() -> None:
         no_mdns=True,
         framework="arduino",
         core_platform="esp32",
+        area="Living Room",
     )
 
     result = storage.as_dict()
@@ -233,6 +234,7 @@ def test_storage_json_as_dict() -> None:
     assert result["no_mdns"] is True
     assert result["framework"] == "arduino"
     assert result["core_platform"] == "esp32"
+    assert result["area"] == "Living Room"
 
 
 def test_storage_json_to_json() -> None:
@@ -308,6 +310,8 @@ def test_storage_json_from_esphome_core(setup_core: Path) -> None:
     mock_core.loaded_platforms = {"sensor"}
     mock_core.config = {CONF_MDNS: {CONF_DISABLED: True}}
     mock_core.target_framework = "esp-idf"
+    mock_core.toolchain = Toolchain.ESP_IDF
+    mock_core.area = "Living Room"
 
     with patch("esphome.components.esp32.get_esp32_variant") as mock_variant:
         mock_variant.return_value = "ESP32-C3"
@@ -327,6 +331,8 @@ def test_storage_json_from_esphome_core(setup_core: Path) -> None:
     assert result.no_mdns is True
     assert result.framework == "esp-idf"
     assert result.core_platform == "esp32"
+    assert result.toolchain == "esp-idf"
+    assert result.area == "Living Room"
 
 
 def test_storage_json_from_esphome_core_mdns_enabled(setup_core: Path) -> None:
@@ -345,10 +351,12 @@ def test_storage_json_from_esphome_core_mdns_enabled(setup_core: Path) -> None:
     mock_core.loaded_platforms = set()
     mock_core.config = {}  # No MDNS config means enabled
     mock_core.target_framework = "arduino"
+    mock_core.toolchain = None
 
     result = storage_json.StorageJSON.from_esphome_core(mock_core, old=None)
 
     assert result.no_mdns is False
+    assert result.toolchain is None
 
 
 def test_storage_json_load_valid_file(tmp_path: Path) -> None:
@@ -470,6 +478,73 @@ def test_storage_json_equality() -> None:
     assert storage1 != "not a storage object"
 
 
+def _make_storage_with_toolchain(
+    toolchain: str | None,
+) -> storage_json.StorageJSON:
+    return storage_json.StorageJSON(
+        storage_version=1,
+        name="dev",
+        friendly_name=None,
+        comment=None,
+        esphome_version="2024.1.0",
+        src_version=1,
+        address="dev.local",
+        web_port=None,
+        target_platform="ESP32",
+        build_path=Path("/build"),
+        firmware_bin_path=Path("/build/firmware.bin"),
+        loaded_integrations=set(),
+        loaded_platforms=set(),
+        no_mdns=False,
+        framework="esp-idf",
+        core_platform="esp32",
+        toolchain=toolchain,
+    )
+
+
+def test_storage_json_toolchain_round_trip(setup_core: Path) -> None:
+    """Sidecar toolchain survives save -> load -> apply_to_core."""
+    storage = _make_storage_with_toolchain("esp-idf")
+    path = setup_core / "storage.json"
+    path.write_text(storage.to_json())
+
+    # Serialization key is stable -- device-builder relies on it.
+    assert json.loads(path.read_text())["toolchain"] == "esp-idf"
+
+    loaded = storage_json.StorageJSON.load(path)
+    assert loaded is not None
+    assert loaded.toolchain == "esp-idf"
+
+    CORE.toolchain = None
+    with patch("esphome.components.esp32.get_esp32_variant"):
+        loaded.apply_to_core()
+    assert CORE.toolchain == Toolchain.ESP_IDF
+
+
+def test_storage_json_apply_to_core_preserves_cli_toolchain(
+    setup_core: Path,
+) -> None:
+    """A CLI-set CORE.toolchain wins over the sidecar value."""
+    loaded = _make_storage_with_toolchain("esp-idf")
+
+    CORE.toolchain = Toolchain.PLATFORMIO
+    with patch("esphome.components.esp32.get_esp32_variant"):
+        loaded.apply_to_core()
+    assert CORE.toolchain == Toolchain.PLATFORMIO
+
+
+def test_storage_json_apply_to_core_ignores_unknown_toolchain(
+    setup_core: Path,
+) -> None:
+    """Unknown enum values (corrupt sidecar / newer ESPHome) fall through to None."""
+    loaded = _make_storage_with_toolchain("gcc")
+
+    CORE.toolchain = None
+    with patch("esphome.components.esp32.get_esp32_variant"):
+        loaded.apply_to_core()
+    assert CORE.toolchain is None
+
+
 def test_esphome_storage_json_as_dict() -> None:
     """Test EsphomeStorageJSON.as_dict returns correct dictionary."""
     storage = storage_json.EsphomeStorageJSON(
@@ -658,3 +733,37 @@ def test_storage_json_load_legacy_esphomeyaml_version(tmp_path: Path) -> None:
 
     assert result is not None
     assert result.esphome_version == "1.14.0"  # Should map to esphome_version
+
+
+def test_storage_json_load_area(tmp_path: Path) -> None:
+    """``area`` round-trips through load; absence loads as None."""
+    file_path = tmp_path / "with_area.json"
+    file_path.write_text(
+        json.dumps(
+            {
+                "storage_version": 1,
+                "name": "lamp",
+                "friendly_name": "Lamp",
+                "esp_platform": "ESP32",
+                "area": "Living Room",
+            }
+        )
+    )
+    result = storage_json.StorageJSON.load(file_path)
+    assert result is not None
+    assert result.area == "Living Room"
+
+    legacy_path = tmp_path / "no_area.json"
+    legacy_path.write_text(
+        json.dumps(
+            {
+                "storage_version": 1,
+                "name": "lamp",
+                "friendly_name": "Lamp",
+                "esp_platform": "ESP32",
+            }
+        )
+    )
+    legacy = storage_json.StorageJSON.load(legacy_path)
+    assert legacy is not None
+    assert legacy.area is None

tests/unit_tests/test_substitutions.py

@@ -838,3 +838,86 @@ def test_include_vars_applied_to_lambda_value(tmp_path: Path) -> None:
 
     assert isinstance(result["value"], Lambda)
     assert result["value"].value == 'return "bar";'
+
+
+@patch("esphome.git.resolve_symlink_stub")
+@patch("esphome.git.clone_or_update")
+def test_remote_package_symlink_stub_is_followed(
+    mock_clone_or_update: MagicMock,
+    mock_resolve_symlink_stub: MagicMock,
+    tmp_path: Path,
+) -> None:
+    """When a package YAML is a scalar (symlink stub) and resolve_symlink_stub
+    returns a target, the loader follows the target and uses its content."""
+    CORE.config_path = tmp_path / "test.yaml"
+
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+    (repo_dir / "static").mkdir()
+
+    # Stub file: content is the target path string (simulating Windows behavior).
+    stub = repo_dir / "file1.yaml"
+    stub.write_text("static/file1.yaml")
+
+    # Real target with valid YAML mapping.
+    target = repo_dir / "static" / "file1.yaml"
+    target.write_text("substitutions:\n  hello: world\n")
+
+    mock_clone_or_update.return_value = (repo_dir, None)
+    mock_resolve_symlink_stub.return_value = target
+
+    config: dict[str, Any] = {
+        "packages": {
+            "test_package": {
+                "url": "https://github.com/esphome/repo1",
+                "ref": "main",
+                "files": ["file1.yaml"],
+            }
+        }
+    }
+
+    # Must succeed (does not raise the helpful cv.Invalid) because the stub
+    # was followed and a valid mapping was loaded from the target.
+    do_packages_pass(config)
+    assert mock_resolve_symlink_stub.called
+
+
+@patch("esphome.git.clone_or_update")
+def test_remote_package_scalar_yaml_raises_helpful_error(
+    mock_clone_or_update: MagicMock, tmp_path: Path
+) -> None:
+    """A remote package YAML that is a top-level scalar (e.g. an unmaterialized
+    git symlink on Windows) raises a clear cv.Invalid, not AttributeError.
+
+    Regression test for the case where a repo containing a YAML symlink,
+    checked out on Windows without symlink privilege, lands as a short text
+    file containing the symlink target path. PyYAML parses that as a bare
+    string scalar; the package loader must reject it with a human-readable
+    error instead of dying inside ``.get()``.
+    """
+    CORE.config_path = tmp_path / "test.yaml"
+
+    repo_dir = tmp_path / "repo"
+    repo_dir.mkdir()
+    # Simulate the broken-symlink state: a YAML file whose entire content is
+    # the symlink target string. PyYAML parses this as a top-level scalar.
+    (repo_dir / "file1.yaml").write_text("static/file1.yaml")
+
+    mock_clone_or_update.return_value = (repo_dir, None)
+
+    config: dict[str, Any] = {
+        "packages": {
+            "test_package": {
+                "url": "https://github.com/esphome/repo1",
+                "ref": "main",
+                "files": ["file1.yaml"],
+            }
+        }
+    }
+
+    with pytest.raises(cv.Invalid) as exc_info:
+        do_packages_pass(config)
+
+    msg = str(exc_info.value)
+    assert "mapping at the top level" in msg
+    assert "file1.yaml" in msg

tests/unit_tests/test_writer.py

@@ -75,6 +75,7 @@ def create_storage() -> Callable[..., StorageJSON]:
             no_mdns=kwargs.get("no_mdns", False),
             framework=kwargs.get("framework", "arduino"),
             core_platform=kwargs.get("core_platform", "esp32"),
+            toolchain=kwargs.get("toolchain", "platformio"),
         )
 
     return _create
@@ -106,6 +107,20 @@ def test_storage_should_clean_when_build_path_changes(
     assert storage_should_clean(old, new) is True
 
 
+def test_storage_should_clean_when_toolchain_changes(
+    create_storage: Callable[..., StorageJSON],
+) -> None:
+    """Test that clean is triggered when the build toolchain changes.
+
+    Switching between the PlatformIO and native ESP-IDF toolchains produces
+    incompatible build trees (and toolchain-specific idedata), so the build
+    must be wiped.
+    """
+    old = create_storage(loaded_integrations=["api", "wifi"], toolchain="platformio")
+    new = create_storage(loaded_integrations=["api", "wifi"], toolchain="esp-idf")
+    assert storage_should_clean(old, new) is True
+
+
 def test_storage_should_clean_when_component_removed(
     create_storage: Callable[..., StorageJSON],
 ) -> None:
@@ -443,6 +458,11 @@ def test_clean_build(
     dependencies_lock = tmp_path / "dependencies.lock"
     dependencies_lock.write_text("lock file")
 
+    # idedata cache lives under the data dir, not the build path.
+    idedata_cache = tmp_path / "idedata" / "test.json"
+    idedata_cache.parent.mkdir()
+    idedata_cache.write_text("{}")
+
     # Native ESP-IDF toolchain artifacts.
     idf_build_dir = tmp_path / "build"
     idf_build_dir.mkdir()
@@ -463,11 +483,14 @@ def test_clean_build(
     mock_core.relative_pioenvs_path.return_value = pioenvs_dir
     mock_core.relative_piolibdeps_path.return_value = piolibdeps_dir
     mock_core.relative_build_path.side_effect = lambda name: tmp_path / name
+    mock_core.name = "test"
+    mock_core.relative_internal_path.side_effect = tmp_path.joinpath
 
     # Verify all exist before
     assert pioenvs_dir.exists()
     assert piolibdeps_dir.exists()
     assert dependencies_lock.exists()
+    assert idedata_cache.exists()
     assert idf_build_dir.exists()
     assert managed_components_dir.exists()
     assert platformio_cache_dir.exists()
@@ -492,6 +515,7 @@ def test_clean_build(
     assert not pioenvs_dir.exists()
     assert not piolibdeps_dir.exists()
     assert not dependencies_lock.exists()
+    assert not idedata_cache.exists()
     assert not idf_build_dir.exists()
     assert not managed_components_dir.exists()
     assert not platformio_cache_dir.exists()
@@ -501,6 +525,7 @@ def test_clean_build(
     assert ".pioenvs" in caplog.text
     assert ".piolibdeps" in caplog.text
     assert "dependencies.lock" in caplog.text
+    assert str(idedata_cache) in caplog.text
     assert str(idf_build_dir) in caplog.text
     assert str(managed_components_dir) in caplog.text
     assert "PlatformIO cache" in caplog.text