[core] Add buf_append_printf helper and fix unsafe sprintf in remote_base

esphome/components/debug/debug_component.cpp

@@ -30,7 +30,7 @@ void DebugComponent::dump_config() {
 
   char device_info_buffer[DEVICE_INFO_BUFFER_SIZE];
   ESP_LOGD(TAG, "ESPHome version %s", ESPHOME_VERSION);
-  size_t pos = buf_append(device_info_buffer, DEVICE_INFO_BUFFER_SIZE, 0, "%s", ESPHOME_VERSION);
+  size_t pos = buf_append_printf(device_info_buffer, DEVICE_INFO_BUFFER_SIZE, 0, "%s", ESPHOME_VERSION);
 
   this->free_heap_ = get_free_heap_();
   ESP_LOGD(TAG, "Free Heap Size: %" PRIu32 " bytes", this->free_heap_);

esphome/components/debug/debug_component.h

@@ -5,12 +5,6 @@
 #include "esphome/core/helpers.h"
 #include "esphome/core/macros.h"
 #include <span>
-#include <cstdarg>
-#include <cstdio>
-#include <algorithm>
-#ifdef USE_ESP8266
-#include <pgmspace.h>
-#endif
 
 #ifdef USE_SENSOR
 #include "esphome/components/sensor/sensor.h"
@@ -25,40 +19,7 @@ namespace debug {
 static constexpr size_t DEVICE_INFO_BUFFER_SIZE = 256;
 static constexpr size_t RESET_REASON_BUFFER_SIZE = 128;
 
-#ifdef USE_ESP8266
-// ESP8266: Use vsnprintf_P to keep format strings in flash (PROGMEM)
-// Format strings must be wrapped with PSTR() macro
-inline size_t buf_append_p(char *buf, size_t size, size_t pos, PGM_P fmt, ...) {
-  if (pos >= size) {
-    return size;
-  }
-  va_list args;
-  va_start(args, fmt);
-  int written = vsnprintf_P(buf + pos, size - pos, fmt, args);
-  va_end(args);
-  if (written < 0) {
-    return pos;  // encoding error
-  }
-  return std::min(pos + static_cast<size_t>(written), size);
-}
-#define buf_append(buf, size, pos, fmt, ...) buf_append_p(buf, size, pos, PSTR(fmt), ##__VA_ARGS__)
-#else
-/// Safely append formatted string to buffer, returning new position (capped at size)
-__attribute__((format(printf, 4, 5))) inline size_t buf_append(char *buf, size_t size, size_t pos, const char *fmt,
-                                                               ...) {
-  if (pos >= size) {
-    return size;
-  }
-  va_list args;
-  va_start(args, fmt);
-  int written = vsnprintf(buf + pos, size - pos, fmt, args);
-  va_end(args);
-  if (written < 0) {
-    return pos;  // encoding error
-  }
-  return std::min(pos + static_cast<size_t>(written), size);
-}
-#endif
+// buf_append_printf is now provided by esphome/core/helpers.h
 
 class DebugComponent : public PollingComponent {
  public:

esphome/components/debug/debug_esp32.cpp

@@ -173,8 +173,8 @@ size_t DebugComponent::get_device_info_(std::span<char, DEVICE_INFO_BUFFER_SIZE>
   uint32_t flash_size = ESP.getFlashChipSize() / 1024;       // NOLINT
   uint32_t flash_speed = ESP.getFlashChipSpeed() / 1000000;  // NOLINT
   ESP_LOGD(TAG, "Flash Chip: Size=%" PRIu32 "kB Speed=%" PRIu32 "MHz Mode=%s", flash_size, flash_speed, flash_mode);
-  pos = buf_append(buf, size, pos, "|Flash: %" PRIu32 "kB Speed:%" PRIu32 "MHz Mode:%s", flash_size, flash_speed,
-                   flash_mode);
+  pos = buf_append_printf(buf, size, pos, "|Flash: %" PRIu32 "kB Speed:%" PRIu32 "MHz Mode:%s", flash_size, flash_speed,
+                          flash_mode);
 #endif
 
   esp_chip_info_t info;
@@ -182,52 +182,52 @@ size_t DebugComponent::get_device_info_(std::span<char, DEVICE_INFO_BUFFER_SIZE>
   const char *model = ESPHOME_VARIANT;
 
   // Build features string
-  pos = buf_append(buf, size, pos, "|Chip: %s Features:", model);
+  pos = buf_append_printf(buf, size, pos, "|Chip: %s Features:", model);
   bool first_feature = true;
   for (const auto &feature : CHIP_FEATURES) {
     if (info.features & feature.bit) {
-      pos = buf_append(buf, size, pos, "%s%s", first_feature ? "" : ", ", feature.name);
+      pos = buf_append_printf(buf, size, pos, "%s%s", first_feature ? "" : ", ", feature.name);
       first_feature = false;
       info.features &= ~feature.bit;
     }
   }
   if (info.features != 0) {
-    pos = buf_append(buf, size, pos, "%sOther:0x%" PRIx32, first_feature ? "" : ", ", info.features);
+    pos = buf_append_printf(buf, size, pos, "%sOther:0x%" PRIx32, first_feature ? "" : ", ", info.features);
   }
   ESP_LOGD(TAG, "Chip: Model=%s, Cores=%u, Revision=%u", model, info.cores, info.revision);
-  pos = buf_append(buf, size, pos, " Cores:%u Revision:%u", info.cores, info.revision);
+  pos = buf_append_printf(buf, size, pos, " Cores:%u Revision:%u", info.cores, info.revision);
 
   uint32_t cpu_freq_mhz = arch_get_cpu_freq_hz() / 1000000;
   ESP_LOGD(TAG, "CPU Frequency: %" PRIu32 " MHz", cpu_freq_mhz);
-  pos = buf_append(buf, size, pos, "|CPU Frequency: %" PRIu32 " MHz", cpu_freq_mhz);
+  pos = buf_append_printf(buf, size, pos, "|CPU Frequency: %" PRIu32 " MHz", cpu_freq_mhz);
 
   // Framework detection
 #ifdef USE_ARDUINO
   ESP_LOGD(TAG, "Framework: Arduino");
-  pos = buf_append(buf, size, pos, "|Framework: Arduino");
+  pos = buf_append_printf(buf, size, pos, "|Framework: Arduino");
 #elif defined(USE_ESP32)
   ESP_LOGD(TAG, "Framework: ESP-IDF");
-  pos = buf_append(buf, size, pos, "|Framework: ESP-IDF");
+  pos = buf_append_printf(buf, size, pos, "|Framework: ESP-IDF");
 #else
   ESP_LOGW(TAG, "Framework: UNKNOWN");
-  pos = buf_append(buf, size, pos, "|Framework: UNKNOWN");
+  pos = buf_append_printf(buf, size, pos, "|Framework: UNKNOWN");
 #endif
 
   ESP_LOGD(TAG, "ESP-IDF Version: %s", esp_get_idf_version());
-  pos = buf_append(buf, size, pos, "|ESP-IDF: %s", esp_get_idf_version());
+  pos = buf_append_printf(buf, size, pos, "|ESP-IDF: %s", esp_get_idf_version());
 
   uint8_t mac[6];
   get_mac_address_raw(mac);
   ESP_LOGD(TAG, "EFuse MAC: %02X:%02X:%02X:%02X:%02X:%02X", mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
-  pos = buf_append(buf, size, pos, "|EFuse MAC: %02X:%02X:%02X:%02X:%02X:%02X", mac[0], mac[1], mac[2], mac[3], mac[4],
-                   mac[5]);
+  pos = buf_append_printf(buf, size, pos, "|EFuse MAC: %02X:%02X:%02X:%02X:%02X:%02X", mac[0], mac[1], mac[2], mac[3],
+                          mac[4], mac[5]);
 
   char reason_buffer[RESET_REASON_BUFFER_SIZE];
   const char *reset_reason = get_reset_reason_(std::span<char, RESET_REASON_BUFFER_SIZE>(reason_buffer));
-  pos = buf_append(buf, size, pos, "|Reset: %s", reset_reason);
+  pos = buf_append_printf(buf, size, pos, "|Reset: %s", reset_reason);
 
   const char *wakeup_cause = get_wakeup_cause_(std::span<char, RESET_REASON_BUFFER_SIZE>(reason_buffer));
-  pos = buf_append(buf, size, pos, "|Wakeup: %s", wakeup_cause);
+  pos = buf_append_printf(buf, size, pos, "|Wakeup: %s", wakeup_cause);
 
   return pos;
 }

esphome/components/debug/debug_esp8266.cpp

@@ -53,8 +53,8 @@ size_t DebugComponent::get_device_info_(std::span<char, DEVICE_INFO_BUFFER_SIZE>
   uint32_t flash_size = ESP.getFlashChipSize() / 1024;       // NOLINT
   uint32_t flash_speed = ESP.getFlashChipSpeed() / 1000000;  // NOLINT
   ESP_LOGD(TAG, "Flash Chip: Size=%" PRIu32 "kB Speed=%" PRIu32 "MHz Mode=%s", flash_size, flash_speed, flash_mode);
-  pos = buf_append(buf, size, pos, "|Flash: %" PRIu32 "kB Speed:%" PRIu32 "MHz Mode:%s", flash_size, flash_speed,
-                   flash_mode);
+  pos = buf_append_printf(buf, size, pos, "|Flash: %" PRIu32 "kB Speed:%" PRIu32 "MHz Mode:%s", flash_size, flash_speed,
+                          flash_mode);
 
 #if !defined(CLANG_TIDY)
   char reason_buffer[RESET_REASON_BUFFER_SIZE];
@@ -77,15 +77,15 @@ size_t DebugComponent::get_device_info_(std::span<char, DEVICE_INFO_BUFFER_SIZE>
            chip_id, ESP.getSdkVersion(), ESP.getCoreVersion().c_str(), boot_version, boot_mode, cpu_freq, flash_chip_id,
            reset_reason, ESP.getResetInfo().c_str());
 
-  pos = buf_append(buf, size, pos, "|Chip: 0x%08" PRIX32, chip_id);
-  pos = buf_append(buf, size, pos, "|SDK: %s", ESP.getSdkVersion());
-  pos = buf_append(buf, size, pos, "|Core: %s", ESP.getCoreVersion().c_str());
-  pos = buf_append(buf, size, pos, "|Boot: %u", boot_version);
-  pos = buf_append(buf, size, pos, "|Mode: %u", boot_mode);
-  pos = buf_append(buf, size, pos, "|CPU: %u", cpu_freq);
-  pos = buf_append(buf, size, pos, "|Flash: 0x%08" PRIX32, flash_chip_id);
-  pos = buf_append(buf, size, pos, "|Reset: %s", reset_reason);
-  pos = buf_append(buf, size, pos, "|%s", ESP.getResetInfo().c_str());
+  pos = buf_append_printf(buf, size, pos, "|Chip: 0x%08" PRIX32, chip_id);
+  pos = buf_append_printf(buf, size, pos, "|SDK: %s", ESP.getSdkVersion());
+  pos = buf_append_printf(buf, size, pos, "|Core: %s", ESP.getCoreVersion().c_str());
+  pos = buf_append_printf(buf, size, pos, "|Boot: %u", boot_version);
+  pos = buf_append_printf(buf, size, pos, "|Mode: %u", boot_mode);
+  pos = buf_append_printf(buf, size, pos, "|CPU: %u", cpu_freq);
+  pos = buf_append_printf(buf, size, pos, "|Flash: 0x%08" PRIX32, flash_chip_id);
+  pos = buf_append_printf(buf, size, pos, "|Reset: %s", reset_reason);
+  pos = buf_append_printf(buf, size, pos, "|%s", ESP.getResetInfo().c_str());
 #endif
 
   return pos;

esphome/components/debug/debug_libretiny.cpp

@@ -36,12 +36,12 @@ size_t DebugComponent::get_device_info_(std::span<char, DEVICE_INFO_BUFFER_SIZE>
            lt_get_version(), lt_cpu_get_model_name(), lt_cpu_get_model(), lt_cpu_get_freq_mhz(), mac_id,
            lt_get_board_code(), flash_kib, ram_kib, reset_reason);
 
-  pos = buf_append(buf, size, pos, "|Version: %s", LT_BANNER_STR + 10);
-  pos = buf_append(buf, size, pos, "|Reset Reason: %s", reset_reason);
-  pos = buf_append(buf, size, pos, "|Chip Name: %s", lt_cpu_get_model_name());
-  pos = buf_append(buf, size, pos, "|Chip ID: 0x%06" PRIX32, mac_id);
-  pos = buf_append(buf, size, pos, "|Flash: %" PRIu32 " KiB", flash_kib);
-  pos = buf_append(buf, size, pos, "|RAM: %" PRIu32 " KiB", ram_kib);
+  pos = buf_append_printf(buf, size, pos, "|Version: %s", LT_BANNER_STR + 10);
+  pos = buf_append_printf(buf, size, pos, "|Reset Reason: %s", reset_reason);
+  pos = buf_append_printf(buf, size, pos, "|Chip Name: %s", lt_cpu_get_model_name());
+  pos = buf_append_printf(buf, size, pos, "|Chip ID: 0x%06" PRIX32, mac_id);
+  pos = buf_append_printf(buf, size, pos, "|Flash: %" PRIu32 " KiB", flash_kib);
+  pos = buf_append_printf(buf, size, pos, "|RAM: %" PRIu32 " KiB", ram_kib);
 
   return pos;
 }

esphome/components/debug/debug_rp2040.cpp

@@ -19,7 +19,7 @@ size_t DebugComponent::get_device_info_(std::span<char, DEVICE_INFO_BUFFER_SIZE>
 
   uint32_t cpu_freq = rp2040.f_cpu();
   ESP_LOGD(TAG, "CPU Frequency: %" PRIu32, cpu_freq);
-  pos = buf_append(buf, size, pos, "|CPU Frequency: %" PRIu32, cpu_freq);
+  pos = buf_append_printf(buf, size, pos, "|CPU Frequency: %" PRIu32, cpu_freq);
 
   return pos;
 }

esphome/components/debug/debug_zephyr.cpp

@@ -20,9 +20,9 @@ static size_t append_reset_reason(char *buf, size_t size, size_t pos, bool set,
     return pos;
   }
   if (pos > 0) {
-    pos = buf_append(buf, size, pos, ", ");
+    pos = buf_append_printf(buf, size, pos, ", ");
   }
-  return buf_append(buf, size, pos, "%s", reason);
+  return buf_append_printf(buf, size, pos, "%s", reason);
 }
 
 static inline uint32_t read_mem_u32(uintptr_t addr) {
@@ -140,7 +140,7 @@ size_t DebugComponent::get_device_info_(std::span<char, DEVICE_INFO_BUFFER_SIZE>
   const char *supply_status =
       (nrf_power_mainregstatus_get(NRF_POWER) == NRF_POWER_MAINREGSTATUS_NORMAL) ? "Normal voltage." : "High voltage.";
   ESP_LOGD(TAG, "Main supply status: %s", supply_status);
-  pos = buf_append(buf, size, pos, "|Main supply status: %s", supply_status);
+  pos = buf_append_printf(buf, size, pos, "|Main supply status: %s", supply_status);
 
   // Regulator stage 0
   if (nrf_power_mainregstatus_get(NRF_POWER) == NRF_POWER_MAINREGSTATUS_HIGH) {
@@ -172,16 +172,16 @@ size_t DebugComponent::get_device_info_(std::span<char, DEVICE_INFO_BUFFER_SIZE>
         reg0_voltage = "???V";
     }
     ESP_LOGD(TAG, "Regulator stage 0: %s, %s", reg0_type, reg0_voltage);
-    pos = buf_append(buf, size, pos, "|Regulator stage 0: %s, %s", reg0_type, reg0_voltage);
+    pos = buf_append_printf(buf, size, pos, "|Regulator stage 0: %s, %s", reg0_type, reg0_voltage);
   } else {
     ESP_LOGD(TAG, "Regulator stage 0: disabled");
-    pos = buf_append(buf, size, pos, "|Regulator stage 0: disabled");
+    pos = buf_append_printf(buf, size, pos, "|Regulator stage 0: disabled");
   }
 
   // Regulator stage 1
   const char *reg1_type = nrf_power_dcdcen_get(NRF_POWER) ? "DC/DC" : "LDO";
   ESP_LOGD(TAG, "Regulator stage 1: %s", reg1_type);
-  pos = buf_append(buf, size, pos, "|Regulator stage 1: %s", reg1_type);
+  pos = buf_append_printf(buf, size, pos, "|Regulator stage 1: %s", reg1_type);
 
   // USB power state
   const char *usb_state;
@@ -195,7 +195,7 @@ size_t DebugComponent::get_device_info_(std::span<char, DEVICE_INFO_BUFFER_SIZE>
     usb_state = "disconnected";
   }
   ESP_LOGD(TAG, "USB power state: %s", usb_state);
-  pos = buf_append(buf, size, pos, "|USB power state: %s", usb_state);
+  pos = buf_append_printf(buf, size, pos, "|USB power state: %s", usb_state);
 
   // Power-fail comparator
   bool enabled;
@@ -300,14 +300,14 @@ size_t DebugComponent::get_device_info_(std::span<char, DEVICE_INFO_BUFFER_SIZE>
           break;
       }
       ESP_LOGD(TAG, "Power-fail comparator: %s, VDDH: %s", pof_voltage, vddh_voltage);
-      pos = buf_append(buf, size, pos, "|Power-fail comparator: %s, VDDH: %s", pof_voltage, vddh_voltage);
+      pos = buf_append_printf(buf, size, pos, "|Power-fail comparator: %s, VDDH: %s", pof_voltage, vddh_voltage);
     } else {
       ESP_LOGD(TAG, "Power-fail comparator: %s", pof_voltage);
-      pos = buf_append(buf, size, pos, "|Power-fail comparator: %s", pof_voltage);
+      pos = buf_append_printf(buf, size, pos, "|Power-fail comparator: %s", pof_voltage);
     }
   } else {
     ESP_LOGD(TAG, "Power-fail comparator: disabled");
-    pos = buf_append(buf, size, pos, "|Power-fail comparator: disabled");
+    pos = buf_append_printf(buf, size, pos, "|Power-fail comparator: disabled");
   }
 
   auto package = [](uint32_t value) {

esphome/components/remote_base/aeha_protocol.cpp

@@ -85,8 +85,8 @@ optional<AEHAData> AEHAProtocol::decode(RemoteReceiveData src) {
 std::string AEHAProtocol::format_data_(const std::vector<uint8_t> &data) {
   std::string out;
   for (uint8_t byte : data) {
-    char buf[6];
-    sprintf(buf, "0x%02X,", byte);
+    char buf[8];  // "0x%02X," = 6 chars + null + margin
+    snprintf(buf, sizeof(buf), "0x%02X,", byte);
     out += buf;
   }
   out.pop_back();

esphome/components/remote_base/raw_protocol.cpp

@@ -1,4 +1,5 @@
 #include "raw_protocol.h"
+#include "esphome/core/helpers.h"
 #include "esphome/core/log.h"
 
 namespace esphome {
@@ -8,36 +9,30 @@ static const char *const TAG = "remote.raw";
 
 bool RawDumper::dump(RemoteReceiveData src) {
   char buffer[256];
-  uint32_t buffer_offset = 0;
-  buffer_offset += sprintf(buffer, "Received Raw: ");
+  size_t pos = buf_append_printf(buffer, sizeof(buffer), 0, "Received Raw: ");
 
   for (int32_t i = 0; i < src.size() - 1; i++) {
     const int32_t value = src[i];
-    const uint32_t remaining_length = sizeof(buffer) - buffer_offset;
-    int written;
+    size_t prev_pos = pos;
 
     if (i + 1 < src.size() - 1) {
-      written = snprintf(buffer + buffer_offset, remaining_length, "%" PRId32 ", ", value);
+      pos = buf_append_printf(buffer, sizeof(buffer), pos, "%" PRId32 ", ", value);
     } else {
-      written = snprintf(buffer + buffer_offset, remaining_length, "%" PRId32, value);
+      pos = buf_append_printf(buffer, sizeof(buffer), pos, "%" PRId32, value);
     }
 
-    if (written < 0 || written >= int(remaining_length)) {
-      // write failed, flush...
-      buffer[buffer_offset] = '\0';
+    if (pos >= sizeof(buffer) - 1) {
+      // buffer full, flush and continue
+      buffer[prev_pos] = '\0';
       ESP_LOGI(TAG, "%s", buffer);
-      buffer_offset = 0;
-      written = sprintf(buffer, "  ");
       if (i + 1 < src.size() - 1) {
-        written += sprintf(buffer + written, "%" PRId32 ", ", value);
+        pos = buf_append_printf(buffer, sizeof(buffer), 0, "  %" PRId32 ", ", value);
       } else {
-        written += sprintf(buffer + written, "%" PRId32, value);
+        pos = buf_append_printf(buffer, sizeof(buffer), 0, "  %" PRId32, value);
       }
     }
-
-    buffer_offset += written;
   }
-  if (buffer_offset != 0) {
+  if (pos != 0) {
     ESP_LOGI(TAG, "%s", buffer);
   }
   return true;

esphome/components/remote_base/remote_base.cpp

@@ -1,4 +1,5 @@
 #include "remote_base.h"
+#include "esphome/core/helpers.h"
 #include "esphome/core/log.h"
 
 #include <cinttypes>
@@ -165,36 +166,31 @@ void RemoteTransmitterBase::send_(uint32_t send_times, uint32_t send_wait) {
 #ifdef ESPHOME_LOG_HAS_VERY_VERBOSE
   const auto &vec = this->temp_.get_data();
   char buffer[256];
-  uint32_t buffer_offset = 0;
-  buffer_offset += sprintf(buffer, "Sending times=%" PRIu32 " wait=%" PRIu32 "ms: ", send_times, send_wait);
+  size_t pos = buf_append_printf(buffer, sizeof(buffer), 0,
+                                 "Sending times=%" PRIu32 " wait=%" PRIu32 "ms: ", send_times, send_wait);
 
   for (size_t i = 0; i < vec.size(); i++) {
     const int32_t value = vec[i];
-    const uint32_t remaining_length = sizeof(buffer) - buffer_offset;
-    int written;
+    size_t prev_pos = pos;
 
     if (i + 1 < vec.size()) {
-      written = snprintf(buffer + buffer_offset, remaining_length, "%" PRId32 ", ", value);
+      pos = buf_append_printf(buffer, sizeof(buffer), pos, "%" PRId32 ", ", value);
     } else {
-      written = snprintf(buffer + buffer_offset, remaining_length, "%" PRId32, value);
+      pos = buf_append_printf(buffer, sizeof(buffer), pos, "%" PRId32, value);
     }
 
-    if (written < 0 || written >= int(remaining_length)) {
-      // write failed, flush...
-      buffer[buffer_offset] = '\0';
+    if (pos >= sizeof(buffer) - 1) {
+      // buffer full, flush and continue
+      buffer[prev_pos] = '\0';
       ESP_LOGVV(TAG, "%s", buffer);
-      buffer_offset = 0;
-      written = sprintf(buffer, "  ");
       if (i + 1 < vec.size()) {
-        written += sprintf(buffer + written, "%" PRId32 ", ", value);
+        pos = buf_append_printf(buffer, sizeof(buffer), 0, "  %" PRId32 ", ", value);
       } else {
-        written += sprintf(buffer + written, "%" PRId32, value);
+        pos = buf_append_printf(buffer, sizeof(buffer), 0, "  %" PRId32, value);
       }
     }
-
-    buffer_offset += written;
   }
-  if (buffer_offset != 0) {
+  if (pos != 0) {
     ESP_LOGVV(TAG, "%s", buffer);
   }
 #endif

esphome/core/helpers.h

@@ -1,8 +1,11 @@
 #pragma once
 
+#include <algorithm>
 #include <array>
 #include <cmath>
+#include <cstdarg>
 #include <cstdint>
+#include <cstdio>
 #include <cstring>
 #include <functional>
 #include <iterator>
@@ -568,6 +571,53 @@ std::string __attribute__((format(printf, 1, 3))) str_snprintf(const char *fmt,
 /// sprintf-like function returning std::string.
 std::string __attribute__((format(printf, 1, 2))) str_sprintf(const char *fmt, ...);
 
+#ifdef USE_ESP8266
+// ESP8266: Use vsnprintf_P to keep format strings in flash (PROGMEM)
+// Format strings must be wrapped with PSTR() macro
+/// Safely append formatted string to buffer, returning new position (capped at size).
+/// @param buf Output buffer
+/// @param size Total buffer size
+/// @param pos Current position in buffer
+/// @param fmt Format string (must be in PROGMEM on ESP8266)
+/// @return New position after appending (capped at size on overflow)
+inline size_t buf_append_printf_p(char *buf, size_t size, size_t pos, PGM_P fmt, ...) {
+  if (pos >= size) {
+    return size;
+  }
+  va_list args;
+  va_start(args, fmt);
+  int written = vsnprintf_P(buf + pos, size - pos, fmt, args);
+  va_end(args);
+  if (written < 0) {
+    return pos;  // encoding error
+  }
+  return std::min(pos + static_cast<size_t>(written), size);
+}
+#define buf_append_printf(buf, size, pos, fmt, ...) buf_append_printf_p(buf, size, pos, PSTR(fmt), ##__VA_ARGS__)
+#else
+/// Safely append formatted string to buffer, returning new position (capped at size).
+/// Handles snprintf edge cases: negative returns (encoding errors) and truncation.
+/// @param buf Output buffer
+/// @param size Total buffer size
+/// @param pos Current position in buffer
+/// @param fmt printf-style format string
+/// @return New position after appending (capped at size on overflow)
+__attribute__((format(printf, 4, 5))) inline size_t buf_append_printf(char *buf, size_t size, size_t pos,
+                                                                      const char *fmt, ...) {
+  if (pos >= size) {
+    return size;
+  }
+  va_list args;
+  va_start(args, fmt);
+  int written = vsnprintf(buf + pos, size - pos, fmt, args);
+  va_end(args);
+  if (written < 0) {
+    return pos;  // encoding error
+  }
+  return std::min(pos + static_cast<size_t>(written), size);
+}
+#endif
+
 /// Concatenate a name with a separator and suffix using an efficient stack-based approach.
 /// This avoids multiple heap allocations during string construction.
 /// Maximum name length supported is 120 characters for friendly names.