From 78c27851bbe0348363e6ef1dc85bc65ea29dd131 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Sat, 7 Mar 2026 20:07:34 -1000
Subject: [PATCH] [api] APIBuffer: add explicit include, fix stale comment,
 clarify docs

- Add explicit #include "api_buffer.h" in api_server.h
- Remove stale "swap trick" comment in api_frame_helper.h
- Document that exact-size allocation is intentional (no growth factor)
- Clarify debug_check_bounds_ scope to protobuf write path only
---
 esphome/components/api/api_buffer.h       | 7 ++++++-
 esphome/components/api/api_frame_helper.h | 1 -
 esphome/components/api/api_server.h       | 1 +
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/esphome/components/api/api_buffer.h b/esphome/components/api/api_buffer.h
index 13dd4e5610..8feaad5183 100644
--- a/esphome/components/api/api_buffer.h
+++ b/esphome/components/api/api_buffer.h
@@ -26,8 +26,13 @@ inline std::unique_ptr<uint8_t[]> make_buffer(size_t n) {
 /// making the zero-fill pure waste. For the receive buffer, bytes are
 /// overwritten by socket reads.
 ///
+/// Designed for bulk clear/resize/overwrite patterns. grow_() allocates
+/// exactly the requested size (no growth factor) since callers resize to
+/// known sizes rather than appending incrementally.
+///
 /// Safe because: callers always write exactly the number of bytes they
-/// resize for, and debug_check_bounds_ validates writes in debug builds.
+/// resize for. In the protobuf write path, debug_check_bounds_ validates
+/// writes in debug builds.
 class APIBuffer {
  public:
   void clear() { this->size_ = 0; }
diff --git a/esphome/components/api/api_frame_helper.h b/esphome/components/api/api_frame_helper.h
index 2ec2b72c93..f0666debee 100644
--- a/esphome/components/api/api_frame_helper.h
+++ b/esphome/components/api/api_frame_helper.h
@@ -178,7 +178,6 @@ class APIFrameHelper {
     // rx_buf_len_ tracks bytes read so far; if non-zero, we're mid-frame
     // and clearing would lose partially received data.
     if (this->rx_buf_len_ == 0) {
-      // Use swap trick since shrink_to_fit() is non-binding and may be ignored
       this->rx_buf_.release();
     }
   }
diff --git a/esphome/components/api/api_server.h b/esphome/components/api/api_server.h
index aabea3485f..69fc26cc00 100644
--- a/esphome/components/api/api_server.h
+++ b/esphome/components/api/api_server.h
@@ -2,6 +2,7 @@
 
 #include "esphome/core/defines.h"
 #ifdef USE_API
+#include "api_buffer.h"
 #include "api_noise_context.h"
 #include "api_pb2.h"
 #include "api_pb2_service.h"