Release v3.2.4

Use the DFTE async integration helper so portal HTML chunk callbacks handle
zero-length buffers and no-progress retries without terminating transfers
early on constrained hosts.

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: Build
+
+on:
+  push:
+    branches:
+      - device-framework
+    tags:
+      - "v*"
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  documentation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: bash -n scripts/*.sh tools/portal-hardware tools/lib/*.sh tools/tests/*.sh
+      - run: ./tools/tests/test-portal-hardware-cli.sh
+      - run: ./scripts/check-docs.sh
+
+  compile-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        environment: ["esp8266", "esp32"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: python -m pip install --upgrade platformio==6.1.19
+      - run: ./scripts/test.sh compile --platform ${{ matrix.environment }}
+      - run: ./scripts/test.sh examples --platform ${{ matrix.environment }}

.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Publish release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: python -m pip install --upgrade platformio==6.1.19
+      - run: ./scripts/test.sh compile --platform esp8266
+      - run: ./scripts/test.sh examples --platform esp8266
+      - run: ./scripts/test.sh compile --platform esp32
+      - run: ./scripts/test.sh examples --platform esp32
+      - run: ./scripts/check-docs.sh
+      - run: ./scripts/prepare-release.sh "$GITHUB_REF_NAME"
+      - run: ./scripts/release-notes.sh "$GITHUB_REF_NAME" > "$RUNNER_TEMP/release-notes.md"
+      - run: >-
+          gh release create "$GITHUB_REF_NAME"
+          --title "WiFiManager $GITHUB_REF_NAME"
+          --notes-file "$RUNNER_TEMP/release-notes.md"
+        env:
+          GH_TOKEN: ${{ github.token }}

.gitignore

@@ -0,0 +1,39 @@
+# PlatformIO
+.pio/
+.pioenvs/
+.piolibdeps/
+.vscode/
+.cache/
+*.pyc
+*.pyo
+*.pyd
+__pycache__/
+
+# IDE
+.idea/
+*.sublime-project
+*.sublime-workspace
+.vscode/
+!.vscode/extensions.json
+
+# PlatformIO project overrides
+/platformio_override.ini
+/build_output/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build artifacts
+*.o
+*.elf
+*.hex
+*.bin
+*.log
+
+# Misc
+node_modules/
+
+# Local portal station handoff credentials and optional direct test artifacts
+/test/portal-station.env
+/tests/portal-contract/artifacts/

CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## 3.2.4
+
+- Correct profile-backed Wi-Fi hand-off from the embedded web portal: the
+  station controller now owns attempts started through either portal surface,
+  preventing the legacy empty-SSID path from reporting success before a
+  station address is available.
+
+## 3.2.3
+
+- Clarify the public integration boundary, built-in browser protocol, and
+  portal presentation documentation without coupling the standalone library to
+  DeviceFramework.
+- Refresh the standalone test guidance and pin the packaged DFTE dependency to
+  the validated 1.2.1 release.
+
+## 3.2.2
+
+- Align the direct ESP8266 and ESP32 test environments with the packaged DFTE 1.2.0 dependency.
+
+## 3.2.1
+
+- Ensure externally supplied station profiles remain authoritative on ESP32 by clearing stale SDK-owned credentials before opening the portal for an empty or invalid external profile set.
+- Pin DFTE 1.2.0, the tested template-engine release used by the maintained portal.
+
+## 3.2.0
+
+- Refine the device-hosted portal with a startup Wi-Fi scan, stable loading overlays, clearer connection progress, and a resettable configuration timeout.
+- Keep a successful portal-to-station hand-off reachable until the browser acknowledges its redirect, with a bounded fallback for captive or headless clients.
+- Rename the presentation field `homeIntro` to `tagline` so portal identity and wording are clearer; update portal bootstrap contract to v3.
+- Add focused Basic Portal, Branded Portal, Custom Portal Content, and Station Profiles examples for ESP8266 and ESP32, with real-hardware README captures.
+- Strengthen release CI with documentation and clean-consumer/example compilation checks for both supported targets.
+
+## 3.1.0
+
+- Add an opt-in primary/fallback station-profile controller with bounded failover, reconnection, a durable consumer-supplied store, and profile-aware portal APIs. DeviceFramework uses this to persist verified WiFi profiles transactionally.
+- Add portable portal branding and presentation hooks, including theme-aware shell and template rendering, without requiring DeviceFramework.
+- Pin ESP32 tests to the Arduino 3-compatible pioarduino platform release and resolve DFTE 1.1.0.
+
+## 3.0.6
+
+- Correct async PlatformIO dependency owners to the registry's canonical lowercase identity, so a clean consumer builds WiFiManager and its ESP8266/ESP32 transport dependencies without duplicating them in `lib_deps`. Remove the superseded include-path bridge.
+
+## 3.0.5
+
+- Add a library-owned PlatformIO bridge for the asynchronous web/TCP include paths required when WiFiManager is nested beneath DeviceFramework.
+
+## 3.0.4
+
+- Set the package's deep PlatformIO dependency-discovery mode so WiFiManager's asynchronous web/TCP children remain available when it is consumed through DeviceFramework.
+
+## 3.0.3
+
+- Declare the ESP8266 and ESP32 async TCP libraries explicitly in the PlatformIO package manifest so clean consumers resolve the headers required by the asynchronous portal.
+
+## 3.0.2
+
+- Update the pinned DFTE dependency to the iterator-lifecycle and configuration-safe 1.0.2 release.
+
+## 3.0.1
+
+- Redact WiFi, AP, portal-form, and custom-parameter values from diagnostic logs.
+
+## 3.0.0
+
+- Establish `device-framework` as the independently maintained canonical branch.
+- Add safe default parameter construction and allocation-failure handling.
+- Pin the DFTE dependency used by PlatformIO builds.

LICENSE

@@ -20,3 +20,12 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+---
+
+This is a fork of tzapu/WiFiManager (https://github.com/tzapu/WiFiManager)
+Original work Copyright (c) 2015 tzapu
+
+This software has been modified and includes contributions Copyright (c) 2024
+Alex Hope-O'Connor (https://github.com/alexhopeoconnor). The original
+license and copyright notice above must be preserved in all copies as required
+by the MIT License.

README.md

@@ -1,136 +1,99 @@
 # WiFiManager
-ESP8266 WiFi Connection manager with fallback web configuration portal
 
-The configuration portal is of the captive variety, so on various devices it will present the configuration dialogue as soon as you connect to the created access point.
+WiFiManager gives ESP8266 and ESP32 firmware a polished, self-hosted Wi-Fi setup experience. It reconnects to saved networks and opens a temporary captive portal when it cannot, so users can configure the device from any phone or browser without a cloud service or companion app.
 
-First attempt at a library. Lots more changes and fixes to do. Contributions are welcome.
+## See it on real hardware
 
-#### This works with the ESP8266 Arduino platform with a recent stable release(2.0.0 or newer) https://github.com/esp8266/Arduino
+| Brand the built-in portal | Combine Wi-Fi and application setup |
+| --- | --- |
+| ![Branded WiFiManager portal overview on an ESP32.](docs/assets/portal-esp32-branded-overview.png) | ![WiFiManager network picker and custom MQTT broker field on an ESP8266.](docs/assets/portal-esp8266-custom-wifi.png) |
+| Give each product its own title, identity, icon, and color theme without copying portal HTML. | Show live nearby networks and collect application values, such as an MQTT broker, in the same setup flow. |
 
-## How It works
-- when your ESP starts up, it sets it up in Station mode and tries to connect to a previously saved Access Point
-- if this is unsuccessful (or no previous network saved) it moves the ESP into Access Point mode and spins up a DNS and WebServer (default ip 192.168.4.1)
-- using any wifi enabled device with a browser (computer, phone, tablet) connect to the newly created Access Point
-- because of the Captive Portal and the DNS server you will either get a 'Join to network' type of popup or get any domain you try to access redirected to the configuration portal
-- choose one of the access points scanned, enter password, click save
-- ESP will try to connect. If successful, it relinquishes control back to your app. If not, reconnect to AP and reconfigure.
+## Start with a working portal
 
-## Still left to do
-- ~~remove dependency on EEPROM library~~
-- move HTML Strings to PROGMEM
-- cleanup and streamline code
-- if timeout is set, extend it when a page is fetched in AP mode
-- add ability to configure more parameters than ssid/password
-- maybe allow setting ip of ESP after reboot
-
-## Releases
-#### v0.4 - user contributed changes - Thank you
- - added ability to password protect the configuration Access Point
- - callback for enter configuration mode
- - memory allocation improvements
-
-##### v0.3
- - removed the need for EEPROM and works with the 2.0.0 and above stable release of the ESP8266 for Arduino IDE package
- - removed restart on save of credentials
- - updated examples
-
-##### v0.2
-needs the latest staging version (or at least a recent release of the staging version) to work
-
-##### v0.1
-works with the staging release ver. 1.6.5-1044-g170995a, built on Aug 10, 2015 of the ESP8266 Arduino library.
-
-
-## Quick Start
-- Make sure you have a recent package of the ESP8266 for Arduino IDE
-
-- Checkout library to your Arduino libraries folder
-
-- Include in your sketch
 ```cpp
-#include <DNSServer.h>
-#include <ESP8266WebServer.h>
+#include <Arduino.h>
 #include <WiFiManager.h>
-```
 
-- Initialise library, in your setup function add
-```cpp
-WiFiManager wifiManager;
-```
+WiFiManager wifi;
 
-- Also in the setup function add
-```cpp
-//first parameter is name of access point, second is the password
-wifiManager.autoConnect("AP-NAME", "AP-PASSWORD");
-```
-if you just want an unsecured access point
-```cpp
-wifiManager.autoConnect("AP-NAME");
-```
-or if you want to use and auto generated name from 'ESP' and the esp's Chip ID use
-```cpp
-wifiManager.autoConnect();
-```
+void setup() {
+    Serial.begin(115200);
+    wifi.setConfigPortalTimeout(180);
+    wifi.autoConnect("Device Setup", "change-me");
+}
 
-After you write your sketch and start the ESP, it will try to connect to WiFi. If it fails it starts in Access Point mode.
-While in AP mode, connect to it then open a browser to the gateway IP, default 192.168.4.1, configure wifi, save and it should reboot and connect.
-
-Also see examples.
-
-### Password protect the configuration Access Point
-You can and should password protect the configuration access point.  Simply add the password as a second parameter to `autoConnect`.
-A short password seems to have unpredictable results so use one that's around 8 characters or more in length.
-```
-wifiManager.autoConnect("AutoConnectAP", "password")
-```
-
-### Callbacks
-##### Enter Config mode
-Use this if you need to do something when your device enters configuration mode on failed WiFi connection attempt.
-Before `autoConnect()`
-```cpp
-wifiManager.setAPCallback(configModeCallback);
-```
-`configModeCallback` declaration and example
-```cpp
-void configModeCallback () {
-  Serial.println("Entered config mode");
-  Serial.println(WiFi.softAPIP());
+void loop() {
+    wifi.process();
 }
 ```
 
-### Timeout
-If you need to set a timeout so the ESP doesn't hang waiting to be configured, for instance after a power failure, you can add
-```cpp
-wifiManager.setTimeout(180);
-```
-which will wait 3 minutes (180 seconds). When the time passes, the autoConnect function will return, no matter the outcome.
-Check for connection and if it's still not established do whatever is needed (on some modules I restart them to retry, on others I enter deep sleep)
+When saved Wi-Fi is unavailable, `autoConnect()` starts the portal asynchronously. Call `process()` from every `loop()` iteration while it may be open. Flash [Basic Portal](examples/BasicPortal/) to try this exact flow; its README gives the network name, password, portal address, and expected result after saving Wi-Fi.
+
+## Make it yours
 
-### Debug
-Debug is enabled by default on Serial. To disable add before autoConnect
 ```cpp
-wifiManager.setDebugOutput(false);
+const char kTitle[] PROGMEM = "Set up Temperature Monitor";
+const char kBrand[] PROGMEM = "Example Devices";
+const char kAccent[] PROGMEM = "#347a45";
+
+void setup() {
+    WiFiManagerPortalConfig portalUI;
+
+    // Leave fields unset to keep WiFiManager's built-in portal values.
+    portalUI.title = WiFiManagerPortalText::progmem(kTitle);
+    portalUI.identityText = WiFiManagerPortalText::progmem(kBrand);
+
+    // Theme values customise the built-in styles; they do not replace the portal.
+    portalUI.theme.accent = WiFiManagerPortalText::progmem(kAccent);
+    portalUI.theme.cornerRadiusPx = 10;
+
+    wifi.setPortalConfig(portalUI);  // Apply before the portal starts.
+    wifi.autoConnect("Device Setup");
+}
+
+void loop() {
+    wifi.process();
+}
 ```
 
-### Custom IP Configuration
-This will set your captive portal to a specific IP should you need/want such a feature. Add the following snippet before `autoConnect()`
-```cpp
-//set custom ip for portal
-wifiManager.setAPConfig(IPAddress(10,0,1,1), IPAddress(10,0,1,1), IPAddress(255,255,255,0));
+The [Branded Portal](examples/BrandedPortal/) example includes a static SVG, accessible identity text, and a small semantic theme. [Custom Portal Content](examples/CustomPortalContent/) shows the supported parameters, information sections, and home cards without replacing the portal shell.
+
+## What it provides
+
+- **Captive Wi-Fi setup:** starts an access point only when saved network credentials cannot connect.
+- **Responsive portal:** one small portal for Wi-Fi, application fields, information, actions, and firmware update flow.
+- **Structured APIs:** C++ configuration and a local JSON protocol for the built-in portal.
+- **Product presentation:** title, logo, tagline, and semantic colour tokens without copying the portal HTML.
+- **Primary and fallback networks:** an opt-in two-network controller backed by an application-provided store.
+- **ESP8266 and ESP32 support:** the package resolves its asynchronous web dependencies for the selected target.
+
+## Choose a guide
+
+| Goal | Guide |
+| --- | --- |
+| Understand library/application ownership and supported boundaries | [Architecture](docs/ARCHITECTURE.md) |
+| Get a device online or recover from missing Wi-Fi | [Provisioning lifecycle](docs/PROVISIONING_LIFECYCLE.md) |
+| Brand or constrain the built-in portal | [Portal UI and configuration](docs/PORTAL_UI.md) |
+| Add and persist application settings, status, or home cards | [Portal content](docs/PORTAL_CONTENT.md) |
+| Configure primary/fallback station profiles | [Station profiles](docs/STATION_PROFILES.md) |
+| Surface setup, offline, and connection state in firmware | [Observability](docs/OBSERVABILITY.md) |
+| Configure AP, station, scan, or reconnect behaviour | [Network configuration](docs/NETWORK_CONFIGURATION.md) |
+| Look up a supported C++ method and its timing | [API reference](docs/API_REFERENCE.md) |
+| Understand the built-in portal's local JSON protocol | [Portal API](docs/PORTAL_API.md) |
+| Follow deployment-oriented integration patterns | [Recipes](docs/recipes/README.md) |
+| Build or flash a complete example | [Examples](examples/README.md) |
+| Run documentation and board-free compile checks | [Testing](docs/TESTING.md) |
+| Contribute to this fork or prepare a release | [Development](docs/DEVELOPMENT.md) |
+
+## Install
+
+```ini
+[common]
+lib_deps =
+    WiFiManager=https://github.com/alexhopeoconnor/WiFiManager.git#v3.2.4
 ```
-### Contributions and thanks
-[alltheblinkythings](https://github.com/alltheblinkythings)
 
-[Niklas Wall](https://github.com/niklaswall)
+The suffix after `#` is a Git ref. PlatformIO clones the repository and checks out that release tag; GitHub Release assets are unrelated. Arduino IDE users can install this repository as a library checkout.
 
-[Jakub Piasecki](https://github.com/zaporylie)
-
-[Maximiliano Duarte](https://github.com/domonetic)
-
-[Peter Allan](https://github.com/alwynallan)
-
-[John Little](https://github.com/j0hnlittle)
-
-#### Inspiration
-- http://www.esp8266.com/viewtopic.php?f=29&t=2520
+See the [documentation index](docs/README.md), [examples](examples/README.md), [release history](CHANGELOG.md), and [licence](LICENSE).

WiFiManager.cpp

@@ -1,456 +0,0 @@
-/**************************************************************
- * WiFiManager is a library for the ESP8266/Arduino platform
- * (https://github.com/esp8266/Arduino) to enable easy
- * configuration and reconfiguration of WiFi credentials and
- * store them in EEPROM.
- * inspired by: 
- * http://www.esp8266.com/viewtopic.php?f=29&t=2520
- * https://github.com/chriscook8/esp-arduino-apboot
- * https://github.com/esp8266/Arduino/tree/esp8266/hardware/esp8266com/esp8266/libraries/DNSServer/examples/CaptivePortalAdvanced
- * Built by AlexT https://github.com/tzapu
- * Licensed under MIT license
- **************************************************************/
-
-#include "WiFiManager.h"
-
-WiFiManager::WiFiManager() {
-}
-
-void WiFiManager::begin() {
-  begin("NoNetESP");
-}
-
-void WiFiManager::begin(char const *apName) {
-  begin(apName,NULL);
-}
-
-void WiFiManager::begin(char const *apName, char const *apPasswd) {
-  dnsServer.reset(new DNSServer());
-  server.reset(new ESP8266WebServer(80));
-  
-  DEBUG_PRINT("");
-  _apName = apName;
-  _apPasswd = apPasswd;
-  start = millis();
-
-  DEBUG_PRINT("Configuring access point... ");
-  DEBUG_PRINT(_apName);
-  if (_apPasswd != NULL)
-    DEBUG_PRINT(_apPasswd);
-
-  //optional soft ip config
-  if (_ip) {
-    DEBUG_PRINT("Custom IP/GW/Subnet");
-    WiFi.softAPConfig(_ip, _gw, _sn);
-  }
-
-  if (_apPasswd != NULL)
-    WiFi.softAP(_apName, _apPasswd);//password option
-  else
-    WiFi.softAP(_apName);
-
-  delay(500); // Without delay I've seen the IP address blank
-  DEBUG_PRINT("AP IP address: ");
-  DEBUG_PRINT(WiFi.softAPIP());
-
-  /* Setup the DNS server redirecting all the domains to the apIP */  
-  dnsServer->setErrorReplyCode(DNSReplyCode::NoError);
-  dnsServer->start(DNS_PORT, "*", WiFi.softAPIP());
-
-  /* Setup web pages: root, wifi config pages, SO captive portal detectors and not found. */
-  server->on("/", std::bind(&WiFiManager::handleRoot, this));
-  server->on("/wifi", std::bind(&WiFiManager::handleWifi, this, true));
-  server->on("/0wifi", std::bind(&WiFiManager::handleWifi, this, false));
-  server->on("/wifisave", std::bind(&WiFiManager::handleWifiSave, this));
-  server->on("/generate_204", std::bind(&WiFiManager::handle204, this));  //Android/Chrome OS captive portal check.
-  server->on("/fwlink", std::bind(&WiFiManager::handleRoot, this));  //Microsoft captive portal. Maybe not needed. Might be handled by notFound handler.
-  server->onNotFound (std::bind(&WiFiManager::handleNotFound, this));
-  server->begin(); // Web server start
-  DEBUG_PRINT("HTTP server started");
-}
-
-boolean WiFiManager::autoConnect() {
-  String ssid = "ESP" + String(ESP.getChipId());
-  return autoConnect(ssid.c_str(),NULL);
-}
-
-boolean WiFiManager::autoConnect(char const *apName) {
-  return autoConnect(apName,NULL);
-}
-
-boolean WiFiManager::autoConnect(char const *apName, char const *apPasswd) {
-  DEBUG_PRINT("");
-  DEBUG_PRINT("AutoConnect");
-  
-  // read eeprom for ssid and pass
-  String ssid = getSSID();
-  String pass = getPassword();
-  //use SDK functions to get SSID and pass
-  //String ssid = WiFi.SSID();
-  //String pass = WiFi.psk();
-  
-  WiFi.mode(WIFI_STA);
-  connectWifi(ssid, pass);
-  int s = WiFi.status();
-  if (s == WL_CONNECTED) {
-    DEBUG_PRINT("IP Address:");
-    DEBUG_PRINT(WiFi.localIP());
-    //connected
-    return true;
-  }
- 
-  //not connected
-  //setup AP
-  WiFi.mode(WIFI_AP);
-  //notify we entered AP mode
-  if( _apcallback != NULL) {
-    _apcallback();
-  }
-  connect = false;
-  begin(apName,apPasswd);
-
-  bool looping = true;
-  while(timeout == 0 || millis() < start + timeout) {
-    //DNS
-    dnsServer->processNextRequest();
-    //HTTP
-    server->handleClient();
-
-    
-    if(connect) {
-      delay(2000);
-      DEBUG_PRINT("Connecting to new AP");
-      connect = false;
-      //ssid = getSSID();
-      //pass = getPassword();
-      connectWifi(_ssid, _pass);
-      int s = WiFi.status();
-      if (s != WL_CONNECTED) {
-        DEBUG_PRINT("Failed to connect.");
-        //not connected, should retry everything
-        //ESP.reset();
-        //delay(1000);
-        //return false;
-      } else {
-        //connected 
-        WiFi.mode(WIFI_STA);
-        break;
-      }
- 
-    }
-    yield();    
-  }
-
-  server.reset();
-  dnsServer.reset();
-  return  WiFi.status() == WL_CONNECTED;
-}
-
-
-void WiFiManager::connectWifi(String ssid, String pass) {
-  DEBUG_PRINT("Connecting as wifi client...");
-  //WiFi.disconnect();
-  WiFi.begin(ssid.c_str(), pass.c_str());
-  int connRes = WiFi.waitForConnectResult();
-  DEBUG_PRINT ("Connection result: ");
-  DEBUG_PRINT ( connRes );
-}
-
-
-String WiFiManager::getSSID() {
-  if (_ssid == "") {
-    DEBUG_PRINT("Reading EEPROM SSID");
-    _ssid = WiFi.SSID();//getEEPROMString(0, 32);
-    DEBUG_PRINT("SSID: ");
-    DEBUG_PRINT(_ssid);
-  }
-  return _ssid;
-}
-
-String WiFiManager::getPassword() {
-  if (_pass == "") {
-    DEBUG_PRINT("Reading EEPROM Password");
-    _pass = WiFi.psk();//getEEPROMString(32, 64);
-    DEBUG_PRINT("Password: " + _pass);
-    //DEBUG_PRINT(_pass);
-  }
-  return _pass;
-}
-
-/*
-String WiFiManager::getEEPROMString(int start, int len) {
-  EEPROM.begin(512);
-  delay(10);
-  String string = "";
-  for (int i = _eepromStart + start; i < _eepromStart + start + len; i++) {
-    //DEBUG_PRINT(i);
-    string += char(EEPROM.read(i));
-  }
-  EEPROM.end();
-  return string;
-}
-*/
-/*
-void WiFiManager::setEEPROMString(int start, int len, String string) {
-  EEPROM.begin(512);
-  delay(10);
-  int si = 0;
-  for (int i = _eepromStart + start; i < _eepromStart + start + len; i++) {
-    char c;
-    if (si < string.length()) {
-      c = string[si];
-      //DEBUG_PRINT("Wrote: ");
-      //DEBUG_PRINT(c);
-    } else {
-      c = 0;
-    }
-    EEPROM.write(i, c);
-    si++;
-  }
-  EEPROM.end();
-  DEBUG_PRINT("Wrote " + string);
-}*/
-
-String WiFiManager::urldecode(const char *src)
-{
-  String decoded = "";
-  char a, b;
-  while (*src) {
-    if ((*src == '%') &&
-        ((a = src[1]) && (b = src[2])) &&
-        (isxdigit(a) && isxdigit(b))) {
-      if (a >= 'a')
-        a -= 'a' - 'A';
-      if (a >= 'A')
-        a -= ('A' - 10);
-      else
-        a -= '0';
-      if (b >= 'a')
-        b -= 'a' - 'A';
-      if (b >= 'A')
-        b -= ('A' - 10);
-      else
-        b -= '0';
-
-      decoded += char(16 * a + b);
-      src += 3;
-    } else if (*src == '+') {
-      decoded += ' ';
-      *src++;
-    } else {
-      decoded += *src;
-      *src++;
-    }
-  }
-  decoded += '\0';
-
-  return decoded;
-}
-
-void WiFiManager::resetSettings() {
-  //need to call it only after lib has been started with autoConnect or begin
-  DEBUG_PRINT("settings invalidated");
-  WiFi.disconnect();
-  delay(200);
-}
-
-void WiFiManager::setTimeout(unsigned long seconds) {
-  timeout = seconds * 1000;
-}
-
-void WiFiManager::setDebugOutput(boolean debug) {
-  _debug = debug;
-}
-
-void WiFiManager::setAPConfig(IPAddress ip, IPAddress gw, IPAddress sn) {
-  _ip = ip;
-  _gw = gw;
-  _sn = sn;
-}
-
-
-/** Handle root or redirect to captive portal */
-void WiFiManager::handleRoot() {
-  DEBUG_PRINT("Handle root");
-  if (captivePortal()) { // If caprive portal redirect instead of displaying the page.
-    return;
-  }
-
-  server->sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
-  server->sendHeader("Pragma", "no-cache");
-  server->sendHeader("Expires", "-1");
-  server->send(200, "text/html", ""); // Empty content inhibits Content-length header so we have to close the socket ourselves.
-
-  String head = HTTP_HEAD;
-  head.replace("{v}", "Options");
-  server->sendContent(head);
-  server->sendContent(HTTP_SCRIPT);
-  server->sendContent(HTTP_STYLE);
-  server->sendContent(HTTP_HEAD_END);
-  
-  server->sendContent(
-    "<form action=\"/wifi\" method=\"get\"><button>Configure WiFi</button></form><br/>"
-  );
-  server->sendContent(
-    "<form action=\"/0wifi\" method=\"get\"><button>Configure WiFi (No Scan)</button></form>"
-  );
-  
-  server->sendContent(HTTP_END);
-
-  server->client().stop(); // Stop is needed because we sent no content length
-}
-
-/** Wifi config page handler */
-void WiFiManager::handleWifi(bool scan) {
-  server->sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
-  server->sendHeader("Pragma", "no-cache");
-  server->sendHeader("Expires", "-1");
-  server->send(200, "text/html", ""); // Empty content inhibits Content-length header so we have to close the socket ourselves.
-
-
-  String head = HTTP_HEAD;
-  head.replace("{v}", "Config ESP");
-  server->sendContent(head);
-  server->sendContent(HTTP_SCRIPT);
-  server->sendContent(HTTP_STYLE);
-  server->sendContent(HTTP_HEAD_END);
-
-  if (scan) {
-    int n = WiFi.scanNetworks();
-    DEBUG_PRINT("Scan done");
-    if (n == 0) {
-      DEBUG_PRINT("No networks found");
-      server->sendContent("<div>No networks found. Refresh to scan again.</div>");
-    }
-    else {
-      for (int i = 0; i < n; ++i)
-      {
-        DEBUG_PRINT(WiFi.SSID(i));
-        DEBUG_PRINT(WiFi.RSSI(i));
-        String item = HTTP_ITEM;
-        item.replace("{v}", WiFi.SSID(i));
-        server->sendContent(item);
-        yield();
-      }
-    }
-  }
-  
-  server->sendContent(HTTP_FORM);
-  server->sendContent(HTTP_END);
-  server->client().stop();
-  
-  DEBUG_PRINT("Sent config page");  
-}
-
-/** Handle the WLAN save form and redirect to WLAN config page again */
-void WiFiManager::handleWifiSave() {
-  DEBUG_PRINT("WiFi save");
-
-  //SAVE/connect here
-  _ssid = urldecode(server->arg("s").c_str());
-  _pass = urldecode(server->arg("p").c_str());
-
-  server->sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
-  server->sendHeader("Pragma", "no-cache");
-  server->sendHeader("Expires", "-1");
-  server->send(200, "text/html", ""); // Empty content inhibits Content-length header so we have to close the socket ourselves.
-
-  String head = HTTP_HEAD;
-  head.replace("{v}", "Credentials Saved");
-  server->sendContent(head);
-  server->sendContent(HTTP_SCRIPT);
-  server->sendContent(HTTP_STYLE);
-  server->sendContent(HTTP_HEAD_END);
-  
-  server->sendContent(HTTP_SAVED);
-
-  server->sendContent(HTTP_END);
-  server->client().stop();
-  
-  DEBUG_PRINT("Sent wifi save page");  
-  
-  connect = true; //signal ready to connect/reset
-}
-
-void WiFiManager::handle204() {
-  DEBUG_PRINT("204 No Response");  
-  server->sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
-  server->sendHeader("Pragma", "no-cache");
-  server->sendHeader("Expires", "-1");
-  server->send ( 204, "text/plain", "");
-}
-
-void WiFiManager::handleNotFound() {
-  if (captivePortal()) { // If captive portal redirect instead of displaying the error page.
-    return;
-  }
-  String message = "File Not Found\n\n";
-  message += "URI: ";
-  message += server->uri();
-  message += "\nMethod: ";
-  message += ( server->method() == HTTP_GET ) ? "GET" : "POST";
-  message += "\nArguments: ";
-  message += server->args();
-  message += "\n";
-
-  for ( uint8_t i = 0; i < server->args(); i++ ) {
-    message += " " + server->argName ( i ) + ": " + server->arg ( i ) + "\n";
-  }
-  server->sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
-  server->sendHeader("Pragma", "no-cache");
-  server->sendHeader("Expires", "-1");
-  server->send ( 404, "text/plain", message );
-}
-
-
-/** Redirect to captive portal if we got a request for another domain. Return true in that case so the page handler do not try to handle the request again. */
-boolean WiFiManager::captivePortal() {
-  if (!isIp(server->hostHeader()) ) {
-    DEBUG_PRINT("Request redirected to captive portal");
-    server->sendHeader("Location", String("http://") + toStringIp(server->client().localIP()), true);
-    server->send ( 302, "text/plain", ""); // Empty content inhibits Content-length header so we have to close the socket ourselves.
-    server->client().stop(); // Stop is needed because we sent no content length
-    return true;
-  }
-  return false;
-}
-
-//start up config portal callback
-void WiFiManager::setAPCallback( void (*func)(void) ) {
-  _apcallback = func;
-}
-
-
-template <typename Generic>
-void WiFiManager::DEBUG_PRINT(Generic text) {
-  if(_debug) {
-    Serial.print("*WM: ");
-    Serial.println(text);    
-  }
-}
-
-
-
-
-/** Is this an IP? */
-boolean WiFiManager::isIp(String str) {
-  for (int i = 0; i < str.length(); i++) {
-    int c = str.charAt(i);
-    if (c != '.' && (c < '0' || c > '9')) {
-      return false;
-    }
-  }
-  return true;
-}
-
-/** IP to String? */
-String WiFiManager::toStringIp(IPAddress ip) {
-  String res = "";
-  for (int i = 0; i < 3; i++) {
-    res += String((ip >> (8 * i)) & 0xFF) + ".";
-  }
-  res += String(((ip >> 8 * 3)) & 0xFF);
-  return res;
-}
-
-

WiFiManager.h

@@ -1,116 +0,0 @@
-/**************************************************************
- * WiFiManager is a library for the ESP8266/Arduino platform
- * (https://github.com/esp8266/Arduino) to enable easy 
- * configuration and reconfiguration of WiFi credentials and 
- * store them in EEPROM.
- * inspired by http://www.esp8266.com/viewtopic.php?f=29&t=2520
- * https://github.com/chriscook8/esp-arduino-apboot 
- * Built by AlexT https://github.com/tzapu
- * Licensed under MIT license
- **************************************************************/
-
-#ifndef WiFiManager_h
-#define WiFiManager_h
-
-#include <ESP8266WiFi.h>
-
-//#include <EEPROM.h>
-//#include <WiFiClient.h>
-#include <ESP8266WebServer.h>
-#include <DNSServer.h>
-#include <memory>
-
-class WiFiManager
-{
-public:
-    WiFiManager();
-        
-    boolean autoConnect();
-    boolean autoConnect(char const *apName);
-    boolean autoConnect(char const *apName, char const *apPasswd);
-
-    String  getSSID();
-    String  getPassword();
-
-    void    resetSettings();
-    //for convenience
-    String  urldecode(const char*);
-
-    //sets timeout before webserver loop ends and exits even if there has been no setup. 
-    //usefully for devices that failed to connect at some point and got stuck in a webserver loop
-    //in seconds
-    void    setTimeout(unsigned long seconds);
-    void    setDebugOutput(boolean debug);
-
-    //sets a custom ip /gateway /subnet configuration
-    void    setAPConfig(IPAddress ip, IPAddress gw, IPAddress sn);
-    void    setAPCallback( void (*func)(void) );    
- 
-private:
-    std::unique_ptr<DNSServer> dnsServer;
-    std::unique_ptr<ESP8266WebServer> server;
-
-    const int WM_DONE = 0;
-    const int WM_WAIT = 10;
-    
-    const String HTTP_404 = "HTTP/1.1 404 Not Found\r\n\r\n";
-    const String HTTP_200 = "HTTP/1.1 200 OK\r\nContent-Type: text/html\r\n\r\n";
-    const String HTTP_HEAD = "<!DOCTYPE html><html lang=\"en\"><head><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"/><title>{v}</title>";
-    const String HTTP_STYLE = "<style>div,input {margin-bottom: 5px;} body{width:200px;display:block;margin-left:auto;margin-right:auto;} button{padding:0.75rem 1rem;border:0;border-radius:0.317rem;background-color:#1fa3ec;color:#fff;line-height:1.5;cursor:pointer;}</style>";
-    const String HTTP_SCRIPT = "<script>function c(l){document.getElementById('s').value=l.innerText||l.textContent;document.getElementById('p').focus();}</script>";
-    const String HTTP_HEAD_END = "</head><body>";
-    const String HTTP_ITEM = "<div><a href='#' onclick='c(this)'>{v}</a></div>";
-    const String HTTP_FORM = "<form method='get' action='wifisave'><input id='s' name='s' length=32 placeholder='SSID'><input id='p' name='p' length=64 placeholder='password'><br/><button type='submit'>save</button></form>";
-    const String HTTP_SAVED = "<div>Credentials Saved<br />Trying to connect ESP to network.<br />If it fails reconnect to AP to try again</div>";
-    const String HTTP_END = "</body></html>";
-    //const char HTTP_END[] PROGMEM = R"=====(
-    //</body></html>
-    //)=====";
-
-    void    begin();
-    void    begin(char const *apName);
-    void    begin(char const *apName, char const *apPasswd);
-    
-    int _eepromStart;
-    const char* _apName = "no-net";
-    const char* _apPasswd = "no-net";
-    String _ssid = "";
-    String _pass = "";
-    unsigned long timeout = 0;
-    unsigned long start = 0;
-    IPAddress _ip;
-    IPAddress _gw;
-    IPAddress _sn;
-    
-    String getEEPROMString(int start, int len);
-    void setEEPROMString(int start, int len, String string);
-
-    bool keepLooping = true;
-    int status = WL_IDLE_STATUS;
-    void connectWifi(String ssid, String pass);
-
-    void handleRoot();
-    void handleWifi(bool scan);
-    void handleWifiSave();
-    void handleNotFound();
-    void handle204();
-    boolean captivePortal();
-    
-    // DNS server
-    const byte DNS_PORT = 53;
-    
-    boolean isIp(String str);
-    String toStringIp(IPAddress ip);
-
-    boolean connect;
-    boolean _debug = true;
-
-    void (*_apcallback)(void) = NULL;
-
-    template <typename Generic>
-    void DEBUG_PRINT(Generic text);
-};
-
-
-
-#endif

docs/API_REFERENCE.md

@@ -0,0 +1,133 @@
+# API reference
+
+This is a task-oriented reference for the supported WiFiManager firmware API. Configure an instance during boot, keep it alive for the application's lifetime, and call process() regularly while WiFiManager may have active work.
+
+For complete end-to-end patterns, use [Provisioning lifecycle](PROVISIONING_LIFECYCLE.md), [Portal content](PORTAL_CONTENT.md), and [Station profiles](STATION_PROFILES.md).
+
+## Lifecycle
+
+| API | Timing and meaning |
+| --- | --- |
+| autoConnect([apName, apPassword]) | Tries legacy saved station credentials. Returns true if it connected during the call; otherwise starts the enabled portal fallback and returns false. |
+| startConfigPortal([apName, apPassword]) | Immediately starts a configuration AP and captive portal. |
+| stopConfigPortal() | Immediately stops the configuration portal. |
+| startWebPortal() / stopWebPortal() | Starts/stops the portal web server without the configuration-AP flow. |
+| process() | Cooperatively services active portal, scan, station-profile, and connection state. Call from loop(); do not treat it as a hard real-time operation or rely on a fixed maximum duration. |
+| getConfigPortalSSID() | Returns the current configuration AP name. |
+| getConfigPortalActive() / getWebPortalActive() | Reports active configuration or web portal state. |
+| setHttpPort(port) | Chooses the portal server port before starting it. |
+
+The application owns any existing HTTP service and must release a shared port before WiFiManager starts its portal.
+
+## Station profiles
+
+| API | Timing and meaning |
+| --- | --- |
+| setStationProfileStore(store) | Supplies an application-owned durable store; WiFiManager does not own it. |
+| startStationConnection([apName, apPassword]) | Loads and begins the stored primary/fallback profile flow. |
+| startStationCandidate(candidate[, apName, apPassword]) | Attempts an in-memory profile set; when a store is attached, saves it only after a successful usable connection. |
+| saveStationProfiles(profiles) | Deliberately stores a complete profile set without a connection verification attempt. |
+| clearStationProfiles() | Clears the store and disconnects the station. |
+| setStationRecoveryInterval(milliseconds) | Sets delay before profile recovery attempts after a connection loss. |
+| isStationProfileMode(), getStationProfiles(), getStationStatus() | Inspects profile-controller state. |
+
+Profile mode has exactly primary slot 0 and optional fallback slot 1. See [Station profiles](STATION_PROFILES.md) for storage rules and portal fields.
+
+## Application settings and callbacks
+
+| API | Timing and meaning |
+| --- | --- |
+| portalAddParameter(parameter) | Registers an application-owned WiFiManagerParameter; it must outlive the portal. Returns false if registration fails. |
+| portalClearParameters() | Removes registered parameter pointers; it does not delete them. |
+| getParameters() / getParametersCount() | Inspects registered parameters. |
+| setPreSaveParamsCallback(callback) | Invoked before a parameter-only save. |
+| setSaveParamsCallback(callback) | Invoked when parameters save; receives WiFiManagerRequestArgs. |
+| setPreSaveConfigCallback(callback) | Invoked before a combined Wi-Fi/config save. |
+| setSaveConfigCallback(callback) | Invoked after changed Wi-Fi settings connect successfully, or when break-after-config is enabled. |
+| setConfigResetCallback(callback) | Invoked when Wi-Fi settings reset. |
+| setAPCallback(callback) / setWebServerCallback(callback) | Invoked after the AP/config portal or web server begins. |
+| setConfigPortalTimeoutCallback(callback) | Invoked when a configuration portal times out. |
+| setPreOtaUpdateCallback(callback) | Invoked immediately before OTA update handling. |
+
+WiFiManagerRequestArgs provides hasArg(), getArg(), getArgAsInt(), getArgAsFloat(), getArgAsBool(), and count(). It is a callback argument, not durable application configuration.
+
+WiFiManagerParameter constructors accept an ID, label, default value, maximum length, optional custom HTML, and optional label placement. IDs are request field names; keep them stable and simple.
+
+## Portal presentation and policy
+
+| API | Timing and meaning |
+| --- | --- |
+| setPortalConfig(config) | Applies title, identity text, tagline, SVG logo, and semantic theme. Returns false when a portal is active or the theme is invalid. |
+| portalSetPageInfoVisible(), portalSetPageUpdateVisible(), portalSetPageSetupVisible() | Controls built-in page visibility. |
+| portalSetActionEraseVisible(), portalSetActionRestartVisible(), portalSetActionExitVisible(), portalSetActionCloseCaptiveVisible(), portalSetActionBackVisible() | Controls built-in action visibility. |
+| portalSetLayoutParamsLocation(location) | Selects WiFiPage or SetupPage for custom parameters. |
+| portalSetBehaviorCaptivePortalEnabled(), portalSetBehaviorConnectOnSave(), portalSetBehaviorExitAllowed() | Sets portal availability, post-save connection, and exit policy. |
+| portalSetBehaviorConnectTimeoutSeconds(), portalSetBehaviorPortalTimeoutSeconds() | Sets connection and portal timeout behavior. |
+| portalSetBehaviorAutoReconnect(), portalSetBehaviorApClientCheck(), portalSetBehaviorWebClientCheck() | Sets reconnection and activity/timeout behavior. |
+| portalSetFieldPasswordPlaceholderMode(mode) | Selects Hidden, Masked, or Actual password placeholder behavior. |
+| portalSetFieldStaticIpVisibility(visibility), portalSetFieldStaticDnsVisibility(visibility) | Selects Hidden, Auto, or Always static-network fields. |
+| portalAddInfoSection(), portalClearInfoSections() | Adds/clears copied read-only information sections. |
+| portalAddHomeCard(), portalClearHomeCards() | Adds/clears copied overview cards. |
+
+Use [Portal UI and configuration](PORTAL_UI.md) for configuration examples and [Portal content](PORTAL_CONTENT.md) for ownership/persistence rules.
+
+## Connection and network policy
+
+| API | Timing and meaning |
+| --- | --- |
+| setConfigPortalTimeout(seconds) | Limits configuration portal lifetime; setTimeout() is deprecated alias. |
+| setConnectTimeout(seconds), setConnectRetries(count) | Bounds legacy automatic connection attempts. |
+| setSaveConnectTimeout(seconds), setSaveConnect(enabled) | Controls and bounds portal save-and-connect behavior. |
+| setBreakAfterConfig(enabled) | Exits after a configuration submission even when it did not connect. |
+| setEnableConfigPortal(enabled), setDisableConfigPortal(enabled) | Controls autoConnect() fallback/start-stop behavior. |
+| setAPClientCheck(enabled), setWebPortalClientCheck(enabled) | Controls portal timeout interaction with AP/web clients. |
+| setWiFiAutoReconnect(enabled), setCleanConnect(enabled) | Controls station reconnect and pre-connect disconnect behavior. |
+| setHostname(), getWiFiHostname() | Sets/reads the supported target hostname. |
+| setWiFiSSIDPrefix(), setWiFiAPChannel(), setWiFiAPHidden() | Configures the temporary setup AP. |
+| setAPStaticIPConfig(), setSTAStaticIPConfig() | Configures AP or station static addressing. |
+| setCountry(), setMinimumSignalQuality(), setRemoveDuplicateAPs(), setScanDispPerc() | Configures country and scan presentation/filter behavior. |
+| setRestorePersistent(enabled) | Controls restoration of the platform Wi-Fi persistence setting. |
+
+See [Network configuration](NETWORK_CONFIGURATION.md) for deployment constraints.
+
+## Scan, state, and diagnostics
+
+| API | Timing and meaning |
+| --- | --- |
+| requestAsyncScan(forceRefresh) | Requests a non-blocking scan. |
+| getScanSnapshot(), getScanRuntimeState(), getScanState() | Returns scan lifecycle state. |
+| isScanRunning(), hasValidScanResults() | Reads scan progress and cached-result validity. |
+| getScanResults() | Returns WiFiManager-owned cached visible results; do not retain references after a new scan or portal shutdown. |
+| getRSSIasQuality(rssi) | Converts RSSI to WiFiManager quality. |
+| getLastConxResult(), getWLStatusString(), getModeString() | Formats connection and mode diagnostics. |
+| hasEnteredConfigPortal(), getConfigPortalConnectState() | Reads portal-session history and last submission state. |
+| isConfigPortalConnectPending(), didConfigPortalConnectSucceed(), didConfigPortalConnectFail() | Reads concise portal connection status. |
+| getConfigPortalConnectStatus(), getConfigPortalConnectMessage() | Returns platform status and message for the last portal attempt. |
+| setEventCallback(callback) | Receives lifecycle notifications; use getters for detailed state. |
+| setLogEnabled(), setLogPrefix(), setLogOutput(), setLogSink(), getLogSink() | Configures log output and optional application-owned sink. |
+
+See [Observability](OBSERVABILITY.md) for event meanings and product feedback.
+
+## Reset and low-level helpers
+
+| API | Meaning |
+| --- | --- |
+| disconnect() | Disconnects without erasing saved configuration. |
+| resetSettings() | Clears legacy Wi-Fi settings. |
+| erase([optional]) | Erases Wi-Fi configuration. |
+| reboot() | Reboots the target. |
+| getWiFiIsSaved(), getWiFiSSID(), getWiFiPass() | Reads legacy saved/current station values; handle credentials carefully. |
+| getDefaultAPName() | Returns the default generated AP name. |
+| debugSoftAPConfig(), debugPlatformInfo() | Writes diagnostic information. |
+| htmlEntities(text[, whitespace]) | Escapes text for WiFiManager HTML rendering. |
+| preloadWiFi(ssid, password) | Intended for fixtures or controlled integrations that deliberately skip normal station configuration. |
+
+getServer() and getDNSServer() are exposed for testing/host integration. They are not a supported way for product firmware to add private portal routes or mutate the built-in server.
+
+## Continue
+
+- [Architecture and boundaries](ARCHITECTURE.md)
+- [Portal API](PORTAL_API.md)
+- [Examples](../examples/README.md)
+
+Back to [documentation](README.md) · [project overview](../README.md).

docs/ARCHITECTURE.md

@@ -0,0 +1,93 @@
+# Integrating WiFiManager
+
+WiFiManager runs device-local Wi-Fi setup. It tries station Wi-Fi, temporarily
+hosts an access point and portal when the device cannot connect, and then lets
+the firmware continue its normal work. It is not a cloud service,
+remote-management system, or companion-app framework.
+
+## What WiFiManager handles
+
+| WiFiManager handles | Your firmware handles |
+| --- | --- |
+| Temporary AP, captive DNS, portal routes, Wi-Fi connection attempts, portal session state | Durable application settings, schema migration, product services, LEDs/display, reboot policy, telemetry, and access-control decisions |
+| Wi-Fi credentials in the legacy flow, or profile-selection policy in station-profile mode | The durable station-profile store when profile mode is enabled |
+| Structured portal presentation and built-in Wi-Fi/settings forms | Product-specific validation and the persistence of product settings |
+| The local portal JSON protocol | Any separate product HTTP API or local web server |
+
+This lets a firmware decide what configuration it needs without copying the
+portal, captive-network behavior, or Wi-Fi connection flow.
+
+## Typical boot sequence
+
+~~~text
+Firmware boot
+  │
+  ├─ Load and migrate application settings
+  ├─ Register portal branding, policy, and application parameters
+  ├─ Start a WiFiManager connection flow
+  │    ├─ Connected: start normal application services
+  │    └─ Not connected: temporary AP + local portal
+  ├─ Service wifi.process() while a portal or profile controller is active
+  └─ Persist application data and decide when to restart or resume services
+~~~
+
+Register portal configuration before calling autoConnect(), startConfigPortal(), startWebPortal(), or a station-profile start method. The active portal uses an immutable response model so that asynchronous requests cannot see a partially changed UI.
+
+## Customise the built-in portal
+
+WiFiManager can set product identity, named theme values, page/action
+visibility, parameters, information sections, and home cards. Use its public
+C++ configuration and content APIs for those tasks:
+
+~~~cpp
+WiFiManagerPortalConfig portal;
+portal.title = WiFiManagerPortalText::progmem(PSTR("Set up sensor"));
+wifi.setPortalConfig(portal);
+~~~
+
+The built-in portal still owns its HTML shell, routes, forms, navigation, and
+captive behavior. It does not provide:
+
+- arbitrary portal HTML-shell replacement;
+- raw CSS or JavaScript injection;
+- route replacement or navigation injection;
+- a cloud API or supported mobile-companion integration surface.
+
+The `/api/*` routes are the built-in portal's browser protocol. They are useful
+for portal maintenance and tests, but are not a product firmware or
+companion-app integration API. If a product needs a reusable portal capability,
+add one focused public WiFiManager C++ API and test it on ESP8266 and ESP32.
+
+## Application-service handoff
+
+WiFiManager's portal server uses its configured HTTP port, 80 by default. A product already using that port must explicitly release it before WiFiManager starts a portal. Conversely, the application decides when its normal web service is safe to start after a successful connection.
+
+Release an application-owned server before starting the portal:
+
+~~~cpp
+void beginRecovery() {
+    stopApplicationWebServer();       // Releases port 80 owned by the product.
+    wifi.startConfigPortal("Device Setup", "setup-password");
+}
+~~~
+
+The application may instead use a different WiFiManager HTTP port through setHttpPort(); document that address for installers because the captive-portal redirect and station handoff will include the selected port.
+
+## Data lifetime and persistence
+
+WiFiManagerPortalConfig text and SVG values are non-owning. Keep RAM or PROGMEM source data alive for the entire firmware lifetime. WiFiManagerParameter instances are application-owned and must outlive the portal. Portal information sections and home cards are copied when registered.
+
+A station-profile store is also application-owned. Its load(), save(), and clear() methods are responsible for durable storage and error handling. The profile controller chooses and verifies networks; it does not own the store or an application's migration format.
+
+## Security and operator expectations
+
+The configuration portal is intended for local setup. Use a Wi-Fi-valid AP password in deployed products, do not put secrets in information cards or logs, and do not expose password placeholders unless there is an explicit local-installation requirement. The portal's JSON endpoints are the built-in UI's device-local protocol; they are not an authenticated remote-management API.
+
+## Continue
+
+- [Provisioning lifecycle](PROVISIONING_LIFECYCLE.md)
+- [Portal UI and configuration](PORTAL_UI.md)
+- [Portal content](PORTAL_CONTENT.md)
+- [Integration recipes](recipes/README.md)
+
+Back to [documentation](README.md) · [project overview](../README.md).

docs/DEVELOPMENT.md

@@ -0,0 +1,51 @@
+# Development and releases
+
+Released consumers use the public Git tag. While changing WiFiManager and a sibling dependency together, point an ignored local PlatformIO override at a `symlink://` or `file://` checkout rather than changing tracked application dependencies.
+
+```ini
+lib_deps =
+    WiFiManager=symlink:///path/to/WiFiManager
+```
+
+The ESP32 environments pin the PlatformIO-compatible pioarduino 51.03.05
+platform package, which packages official Arduino-ESP32 3.0.5. This avoids the
+known six-second asynchronous scan failure in the older 2.0.17 framework. Core
+3 also requires the `SOC_WIFI_SUPPORTED`, `Network/src`, and ESP8266-transport
+ignore settings shown in this repository `platformio.ini`; keep those settings
+when adding an ESP32 environment.
+
+Start a release with `bump-version.sh`. It updates package metadata and canonical installation snippets, then creates the changelog section. Replace its generated TODO with the release summary and update any behavioural documentation before running:
+
+```bash
+./scripts/bump-version.sh vMAJOR.MINOR.PATCH
+# Replace the generated CHANGELOG TODO with the release summary.
+./scripts/check-docs.sh
+./scripts/test.sh compile --platform esp8266
+./scripts/test.sh compile --platform esp32
+./scripts/prepare-release.sh vMAJOR.MINOR.PATCH --tag
+```
+
+When a physical ESP8266 and ESP32 are available, include their local lifecycle tests in the release gate. These tests remain opt-in because they flash the selected board and use its actual radio:
+
+~~~bash
+./scripts/test.sh hardware --platform esp8266 --port /dev/serial/by-id/usb-...
+./scripts/test.sh hardware --platform esp32 --port /dev/serial/by-id/usb-...
+~~~
+
+When a physical ESP8266 or ESP32 and a spare USB Wi-Fi adapter are available,
+run the Docker portal contract as an additional release-gate check. It is
+opt-in because it flashes the selected board and temporarily joins its AP, but
+it refuses the host default-route adapter and leaves Docker responsible only
+for browser/API testing:
+
+```bash
+./tools/portal-hardware run --platform esp8266 --port /dev/serial/by-id/usb-... \
+  --client-interface wlx74da385d4165
+```
+
+See [Testing](TESTING.md#docker-portal-contract) for cleanup, artifacts, and
+optional station handoff credentials.
+
+Push the branch and annotated tag. GitHub Actions repeats the board-free compile checks, validates the package, and creates a GitHub Release using that version’s changelog section. The workflow does not publish to the PlatformIO Registry.
+
+Back to [documentation](README.md) · [project overview](../README.md).

docs/GETTING_STARTED.md

@@ -0,0 +1,38 @@
+# Getting started
+
+WiFiManager owns station credential recovery and a temporary configuration portal. Keep one instance for the life of the application.
+
+```cpp
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+WiFiManager wifi;
+
+void setup() {
+    Serial.begin(115200);
+    wifi.setConfigPortalTimeout(180);  // Stop the portal after three minutes.
+    wifi.autoConnect("Example Setup", "change-me");
+}
+
+void loop() {
+    wifi.process();  // Keeps the portal responsive when setup is needed.
+    // Normal work begins after autoConnect succeeds.
+}
+```
+
+`autoConnect()` first tries stored station credentials. If that cannot connect, it starts the AP and portal with the supplied name and password, then returns `false`; call `process()` from `loop()` so that portal can run. `setConfigPortalTimeout(180)` limits that portal to three minutes; pass `0` (the default) to leave it open. Use a Wi-Fi-valid AP password.
+
+## PlatformIO dependency
+
+```ini
+lib_deps =
+    WiFiManager=https://github.com/alexhopeoconnor/WiFiManager.git#v3.2.4
+```
+
+The package includes the asynchronous web and TCP dependencies required by the selected ESP8266 or ESP32 target. Add WiFiManager as the application’s direct dependency; do not copy its internal dependency list into your project.
+
+Next: build [Basic Portal](../examples/BasicPortal/), then read [Provisioning lifecycle](PROVISIONING_LIFECYCLE.md) for return-state, timeout, and recovery rules.
+
+For product presentation and settings, continue with [Portal UI and configuration](PORTAL_UI.md) and [Portal content](PORTAL_CONTENT.md).
+
+Back to [documentation](README.md) · [project overview](../README.md).

docs/NETWORK_CONFIGURATION.md

@@ -0,0 +1,107 @@
+# Network configuration
+
+These APIs configure WiFiManager's AP, station, scan, and reconnection behavior. Set them during boot, before starting a connection or portal flow, so an installer sees one consistent configuration.
+
+The current ESP8266 and ESP32 implementations apply AP static addressing through WiFi.softAPConfig() and station static addressing through WiFi.config(). Station static configuration is used by legacy connections, portal save-and-connect attempts, and the station-profile controller.
+
+This page is an advanced deployment reference. Use these settings only when the local network and the product's operating policy require them; WiFiManager's defaults are appropriate for many devices.
+
+## Access-point setup network
+
+| API | Purpose |
+| --- | --- |
+| setWiFiSSIDPrefix(prefix) | Changes the prefix used by an automatically generated AP name. |
+| setWiFiAPChannel(channel) | Selects the setup AP Wi-Fi channel. |
+| setWiFiAPHidden(hidden) | Hides or advertises the setup AP SSID. |
+| setAPStaticIPConfig(ip, gateway, subnet) | Sets the AP-side portal address configuration. |
+| setHttpPort(port) | Uses a non-default portal HTTP port. |
+| setHostname(name) | Sets the station/AP hostname as supported by the target. |
+| getConfigPortalSSID() / getDefaultAPName() | Reports the actual/current setup AP name. |
+
+A hidden AP can make field setup harder because an installer must enter the SSID manually. Treat it as a deployment decision, not a general security control. If setHttpPort() changes the default, publish the full portal address in the product's installation procedure.
+
+## A fixed setup-portal address
+
+Give the setup AP a fixed address when an installer procedure needs a stable local portal address:
+
+~~~cpp
+wifi.setAPStaticIPConfig(
+    IPAddress(192, 168, 8, 1),
+    IPAddress(192, 168, 8, 1),
+    IPAddress(255, 255, 255, 0));
+wifi.setWiFiAPChannel(6);
+wifi.setWiFiAPHidden(false);
+~~~
+
+This is applied before WiFiManager starts its SoftAP. The usual portal address becomes http://192.168.8.1/. If setHttpPort() selects a non-default port, include that port in the installer instructions and expect the station handoff URL to include it too.
+
+## Station address and credential behavior
+
+Use a station static address only when the network owner has reserved and documented it:
+
+~~~cpp
+wifi.setSTAStaticIPConfig(
+    IPAddress(192, 168, 20, 50),
+    IPAddress(192, 168, 20, 1),
+    IPAddress(255, 255, 255, 0),
+    IPAddress(192, 168, 20, 1));
+~~~
+
+| API | Purpose |
+| --- | --- |
+| setSTAStaticIPConfig(ip, gateway, subnet[, dns]) | Supplies a station static address and optional DNS server. |
+| setCleanConnect(enabled) | Disconnects before connecting; use when the product requires a fresh association. |
+| setRestorePersistent(enabled) | Controls restoration of the platform Wi-Fi persistence preference. |
+| setWiFiAutoReconnect(enabled) | Enables Wi-Fi auto-reconnect behavior. |
+| setCountry(countryCode) | Applies the supported Wi-Fi country setting. |
+| disconnect() | Disconnects without erasing persistent settings. |
+| resetSettings() | Clears legacy saved Wi-Fi settings. |
+| erase([optional]) | Erases Wi-Fi configuration and schedules the configured reset behavior. |
+
+Static-IP entry fields can be configured independently of the network setting:
+
+~~~cpp
+wifi.portalSetFieldStaticIpVisibility(PortalFieldVisibility::Auto);
+wifi.portalSetFieldStaticDnsVisibility(PortalFieldVisibility::Hidden);
+~~~
+
+Auto shows these fields when a static station configuration is already in use; Always makes them visible; Hidden suppresses them. Do not expose static network controls in a general user portal unless the installer is expected to manage those values.
+
+## Scan behavior
+
+WiFiManager's portal schedules asynchronous scans. Firmware that needs its own nearby-network status can request and inspect the same cached scan state:
+
+~~~cpp
+wifi.requestAsyncScan();
+
+if (wifi.hasValidScanResults()) {
+    for (const auto& network : wifi.getScanResults()) {
+        Serial.printf("%s: %ld dBm\n", network.ssid.c_str(), network.rssi);
+    }
+}
+~~~
+
+| API | Purpose |
+| --- | --- |
+| requestAsyncScan(forceRefresh) | Queues a scan without blocking the application loop. |
+| getScanSnapshot() / getScanRuntimeState() | Returns the complete scan lifecycle snapshot. |
+| getScanState() / isScanRunning() / hasValidScanResults() | Provides concise status checks. |
+| getScanResults() | Returns the cached visible network list. |
+| setMinimumSignalQuality(quality) | Filters low-quality scan results. |
+| setRemoveDuplicateAPs(enabled) | Controls duplicate SSID removal. |
+| setScanDispPerc(enabled) | Uses percentage rather than quality icons in the portal. |
+| getRSSIasQuality(rssi) | Converts RSSI for display. |
+
+WiFiManager owns the scan cache. It keeps the cache and its allocation while a portal is active so nearby networks can be rendered without repeated allocation churn; it clears and releases that storage when the portal fully closes. Treat getScanResults() as a snapshot and do not retain references, iterators, or pointers across a new scan or portal shutdown.
+
+## Connection and timeout policy
+
+See [Provisioning lifecycle](PROVISIONING_LIFECYCLE.md) for setConfigPortalTimeout(), setConnectTimeout(), setConnectRetries(), setSaveConnectTimeout(), setSaveConnect(), and the portal-prefixed behavior equivalents. These settings define recovery behavior; they should reflect how long an on-site installer can reasonably work and how long the product can remain offline.
+
+## Continue
+
+- [Portal UI and configuration](PORTAL_UI.md)
+- [Provisioning lifecycle](PROVISIONING_LIFECYCLE.md)
+- [API reference](API_REFERENCE.md)
+
+Back to [documentation](README.md) · [project overview](../README.md).

docs/OBSERVABILITY.md

@@ -0,0 +1,89 @@
+# Observability
+
+WiFiManager exposes connection and portal state so product firmware can provide useful local feedback. Use getters as the source of truth and treat callbacks as notifications.
+
+A device framework consuming WiFiManager uses this pattern to distinguish normal operation, offline recovery, active setup, and a successful portal connection before it changes LED state or starts product services.
+
+## Portal state
+
+| API | Meaning |
+| --- | --- |
+| getConfigPortalActive() | A configuration AP/portal is currently active. |
+| getWebPortalActive() | A manually started portal web service is active. |
+| hasEnteredConfigPortal() | Setup has been entered at least once since boot. |
+| getConfigPortalConnectState() | Idle, queued, waiting, success, or failed for the most recent portal connection attempt. |
+| isConfigPortalConnectPending() | A concise check for queued or waiting connection work. |
+| didConfigPortalConnectSucceed() / didConfigPortalConnectFail() | Result checks for the most recent portal submission. |
+| getConfigPortalConnectStatus() | Platform Wi-Fi status for that attempt. |
+| getConfigPortalConnectMessage() | Human-readable status; suitable for logs or local display. |
+| getLastConxResult() / getWLStatusString() | Legacy and general Wi-Fi connection result helpers. |
+
+Use these values to drive product feedback. Do not derive state by scraping portal HTML or assuming that an autoConnect() false return means the portal session failed.
+
+## Events
+
+setEventCallback() installs an optional notification hook:
+
+~~~cpp
+wifi.setEventCallback([](WiFiManager::wm_event_t event) {
+    switch (event) {
+        case WiFiManager::WM_EVENT_PORTAL_STARTED:
+            setIndicator(IndicatorState::Setup);
+            break;
+        case WiFiManager::WM_EVENT_PORTAL_CONNECT_SUCCESS:
+            setIndicator(IndicatorState::ConnectingComplete);
+            break;
+        case WiFiManager::WM_EVENT_STATION_LINK_LOST:
+            setIndicator(IndicatorState::Offline);
+            break;
+        default:
+            break;
+    }
+});
+~~~
+
+| Event | Product use |
+| --- | --- |
+| WM_EVENT_PORTAL_STARTED / WM_EVENT_PORTAL_STOPPED | Begin or end setup feedback. |
+| WM_EVENT_PORTAL_CONNECT_QUEUED / START / SUCCESS / FAILED | Show progress and result for a portal-submitted network. |
+| WM_EVENT_STATION_PROFILE_ATTEMPT / CONNECTED / FAILED | Track profile-controller progress. |
+| WM_EVENT_STATION_LINK_LOST / BACKOFF | Show recovery behavior after an established connection drops. |
+| WM_EVENT_STATION_PROFILES_CLEARED | Reconcile product state after profiles are cleared. |
+
+Events are intentionally small and do not carry credentials or mutable request state. Read the relevant getter inside the callback when more detail is needed.
+
+## Station-profile status
+
+When using profile mode, getStationStatus() reports:
+
+- state: idle, loading, attempting, switching, connected, backoff, or portal;
+- activeSlot and attemptedSlot;
+- configuredProfiles;
+- wifiStatus and a human-readable message;
+- whether the last connection was a candidate;
+- whether the profile store could not save a successful candidate.
+
+A store-save failure is operationally important: the device may be connected now but will not necessarily reconnect after a restart. Preserve that distinction in an LED, display, or operator log.
+
+## Logging
+
+WiFiManager logs to its configured Print output unless a WiFiManagerLogSink is supplied.
+
+~~~cpp
+wifi.setLogPrefix("[network] ");
+wifi.setLogOutput(true, WiFiManagerLogLevel::Info);
+~~~
+
+WiFiManagerLogLevel ranges from Silent through Error, Warn, Info, Debug, and Trace. A custom WiFiManagerLogSink receives a WiFiManagerLogMessage instead of the Print output. Redact SSIDs and never log passwords, portal form values, or product secrets into a remotely collected log.
+
+## Scan status
+
+For nearby-network progress, use getScanState(), isScanRunning(), hasValidScanResults(), and getScanResults(); see [Network configuration](NETWORK_CONFIGURATION.md#scan-behavior). The portal API exposes a matching local scan-status representation for the built-in UI.
+
+## Continue
+
+- [Provisioning lifecycle](PROVISIONING_LIFECYCLE.md)
+- [Station profiles](STATION_PROFILES.md)
+- [API reference](API_REFERENCE.md)
+
+Back to [documentation](README.md) · [project overview](../README.md).

docs/PORTAL_API.md

@@ -0,0 +1,114 @@
+# Built-in portal browser protocol
+
+This device-local protocol is used by WiFiManager's built-in portal shell. It
+is useful when maintaining that UI or writing portal-focused tests. It is not a
+cloud API, remote-management interface, or supported companion-app integration
+surface.
+
+The portal is unauthenticated local setup infrastructure. Do not expose it as a product's general application API, and do not infer a security boundary from hiding an action in the UI.
+
+## Contract version and format
+
+GET /api/bootstrap returns contractVersion 3. The built-in portal uses that versioned response; tests that assert its shape should feature-detect fields rather than assume undocumented portal HTML or JSON properties.
+
+All documented API responses are JSON with no-cache headers. The server also sends permissive CORS headers for the built-in portal implementation; that does not change the local-only security boundary or make these routes a remote integration contract.
+
+## Route inventory
+
+| Method | Route | Built-in portal purpose |
+| --- | --- | --- |
+| GET | / | Serves the one portal HTML shell. |
+| GET | /api/bootstrap | Reads product brand, portal context, page/action visibility, layout, scan summary, and overview cards. |
+| GET | /api/wifi/scan-status | Reads async scan state and visible nearby networks. |
+| POST | /api/wifi/scan | Queues a forced asynchronous scan; returns 202. |
+| GET | /api/wifi/meta | Reads Wi-Fi form fields, static-IP fields, parameters on the Wi-Fi page, and profile metadata when enabled. |
+| POST | /api/wifi/save | Submits Wi-Fi fields, applicable parameters, and optionally a station-profile set. |
+| GET | /api/wifi/connect-status | Reads the result of the most recent portal save-and-connect attempt. |
+| POST | /api/wifi/connect-complete | Acknowledges that the built-in portal has received the successful station handoff address. |
+| POST | /api/portal/timeout-reset | Restarts an active configured portal timeout. |
+| GET | /api/params | Reads parameters for the separate Setup page. |
+| POST | /api/params/save | Saves Setup-page parameters. |
+| GET | /api/info | Reads device/Wi-Fi info, copied information sections, and visible actions. |
+| GET | /api/status | Reads a short plain-text status summary in JSON. |
+| POST | /api/device/restart | Schedules a target restart. |
+| POST | /api/device/erase | Erases Wi-Fi configuration and schedules restart when successful. |
+| POST | /api/portal/close | Disables captive-portal detection for the active session. |
+| POST | /api/portal/exit | Requests portal exit when portal exit is allowed. |
+| POST | /u | Receives multipart firmware upload and returns JSON completion status. |
+
+Unknown routes are redirected only while captive-portal handling is active; otherwise they return the normal not-found result.
+
+## Bootstrap and read models
+
+Bootstrap includes a brand object (title, tagline, logo SVG, and logo alt text), a context object (portal activity, timeout remaining, identity text, status summary, scan state), visible pages/actions, parameter layout, and copied home cards.
+
+Wi-Fi form metadata is intentionally separate:
+
+- Legacy mode returns SSID/password fields, configured static fields, and parameters when the layout places them on the Wi-Fi page.
+- Profile mode returns primary/fallback profile metadata, the active slot, controller state, static fields, and applicable parameters.
+- Password values are never returned. Legacy password placeholder behavior is controlled by portalSetFieldPasswordPlaceholderMode().
+
+GET /api/params exposes all registered parameters for the separate Setup page, plus whether the back action is visible. GET /api/info exposes device/Wi-Fi facts, copied information sections, and action visibility. GET /api/status returns a short human-readable text field.
+
+## Wi-Fi submit and connection handoff
+
+POST /api/wifi/save accepts form fields. In legacy mode:
+
+| Field | Meaning |
+| --- | --- |
+| s | Station SSID. |
+| p | Station password. A password without an SSID is treated as a password change for the stored SSID. |
+| ip, gw, sn, dns | Optional station static IP, gateway, subnet, and DNS values when those fields are visible. |
+| Registered parameter ID or param_N | Application parameter values when parameters are placed on the Wi-Fi page. |
+
+A normal accepted save returns 202 and directs the portal to poll /api/wifi/connect-status. The status response is:
+
+~~~json
+{
+  "state": "idle | waiting | success | failed",
+  "message": "human readable status",
+  "wifiStatus": "WL_CONNECTED",
+  "stationIp": "192.168.1.42",
+  "redirectUrl": "http://192.168.1.42/"
+}
+~~~
+
+stationIp and redirectUrl are present only after success. If WiFiManager uses a non-default HTTP port, redirectUrl includes it.
+
+After observing success, the built-in portal POSTs /api/wifi/connect-complete. A 409 response means successful handoff is not ready; otherwise WiFiManager keeps the portal alive briefly, receives the acknowledgement, and then closes after a grace delay. Browser captive redirects can still fail, so the portal keeps the station address visible.
+
+When portalSetBehaviorConnectOnSave(false) or setSaveConnect(false) is selected, a Wi-Fi save does not start this station connection/handoff flow.
+
+## Profile-mode submit
+
+In profile mode, POST /api/wifi/save accepts s0/p0 for primary and s1/p1 for fallback. Primary must be non-empty. A blank p0 or p1 preserves an existing password; clear0 or clear1 explicitly clears a password for an open network.
+
+By default, WiFiManager attempts the submitted candidate and returns 202 for status polling. With stationAction=save, it writes the submitted profile set for a later connection attempt and returns 200. See [Station profiles](STATION_PROFILES.md) for candidate verification and storage behavior.
+
+## Parameter submit
+
+POST /api/params/save sends registered application parameter fields and returns a successful acknowledgement after the registered save callbacks run. A parameter can be addressed by its stable ID or by param_N index. WiFiManager does not define application validation or durable-storage semantics; the consuming application owns both.
+
+## Actions and error states
+
+| Route | Success | Important non-success response |
+| --- | --- | --- |
+| POST /api/wifi/scan | 202 with accepted/queued state | Scan result arrives through scan-status. |
+| POST /api/wifi/save | 202 for queued connection, or 200 for profile save-for-later | 400 for invalid Wi-Fi/profile input; 500 when an explicit profile store save fails. |
+| POST /api/wifi/connect-complete | 200 after successful station handoff | 409 when success/address is not ready. |
+| POST /api/portal/timeout-reset | 200 with timeout seconds remaining | 409 when no active finite portal timeout exists. |
+| POST /api/device/restart | 200, restart scheduled | The target restarts shortly after the response. |
+| POST /api/device/erase | 200, erase/restart scheduled | 500 when erase fails. |
+| POST /api/portal/close | 200, captive detection disabled | The portal server itself remains subject to its normal lifecycle. |
+| POST /api/portal/exit | 200, exit scheduled | 403 when exit is not allowed. |
+| POST /u | 200, firmware update/restart scheduled | 500 with update failure detail. |
+
+## Using this protocol safely
+
+Use this document to understand and test WiFiManager's own portal behavior.
+Applications that need a product web API should host and secure that API after
+WiFiManager has completed its provisioning role. Do not scrape the portal shell,
+depend on undocumented JSON fields, or add routes through WiFiManager's testing
+server accessor.
+
+Back to [documentation](README.md) · [project overview](../README.md).

docs/PORTAL_CONTENT.md

@@ -0,0 +1,107 @@
+# Portal content and application settings
+
+Use the built-in portal to collect small product settings alongside Wi-Fi credentials. WiFiManager owns the form and its temporary values; the application validates and persists its own settings.
+
+This matches the product-firmware pattern used by real consumers: load configuration first, expose its current values through WiFiManagerParameter objects, then persist valid submitted values through the application's configuration layer.
+
+## End-to-end pattern
+
+~~~cpp
+#include <WiFiManager.h>
+
+constexpr int kBrokerHostLength = 64;
+
+WiFiManager wifi;
+WiFiManagerParameter brokerHost(
+    "broker_host", "MQTT broker", "", kBrokerHostLength);
+
+void setupPortal() {
+    // The application has already loaded settings before this point.
+    brokerHost.setValue(settings.mqttHost.c_str(), kBrokerHostLength);
+    wifi.portalAddParameter(&brokerHost);
+
+    wifi.setSaveParamsCallback([](WiFiManager::WiFiManagerRequestArgs) {
+        const String candidate = brokerHost.getValue();
+
+        if (!isValidHostname(candidate)) {
+            logInvalidBroker(candidate);
+            return;  // Keep the application's known-good stored value.
+        }
+
+        settings.mqttHost = candidate;
+        saveApplicationSettings(settings);
+    });
+}
+~~~
+
+Call setupPortal() after loading application settings and before a WiFiManager connection or portal start method. The callback receives a copy of the submitted request arguments; use getArg(), getArgAsInt(), getArgAsFloat(), or getArgAsBool() when the application needs request-level values.
+
+The save-parameters callback is a notification hook, not a validation-response API. Its return type cannot turn the built-in UI's success response into a form error. Validate before using the candidate, preserve known-good data when persistence fails, and provide product-specific feedback through the application's own UI/logging policy.
+
+## Parameter rules
+
+| Rule | Why it matters |
+| --- | --- |
+| Keep each WiFiManagerParameter alive while the portal can use it. | WiFiManager stores the parameter pointer; it does not take ownership. |
+| Use a stable ID without spaces or special characters. | The ID is used in portal requests. |
+| Choose a bounded value length. | It defines the editable buffer length. |
+| Register parameters before opening the portal. | Active portal responses use their established form model. |
+| Treat submitted text as untrusted application input. | Portal input is not application validation or durable storage. |
+
+Use portalClearParameters() only before opening a portal when rebuilding a complete form. It removes registered parameter pointers; it does not destroy application-owned parameter objects.
+
+## Where settings appear
+
+By default, custom parameters appear on the Wi-Fi page. To put them on the separate Setup page:
+
+~~~cpp
+wifi.portalSetLayoutParamsLocation(PortalParamsLocation::SetupPage);
+~~~
+
+Use the Wi-Fi page for a small setting that is naturally provisioned with network credentials. Use the Setup page when product configuration needs its own step. Page visibility and layout are part of the structured portal policy; see [Portal UI and configuration](PORTAL_UI.md).
+
+## Read-only product context
+
+Use information sections for labelled facts and home cards for a short overview or callout:
+
+~~~cpp
+PortalInfoSection deviceInfo;
+deviceInfo.id = "device";
+deviceInfo.title = "Device";
+deviceInfo.items = {
+    {"firmware", "Firmware", firmwareVersion},
+    {"sensor", "Sensor", sensorReady ? "Ready" : "Checking"},
+};
+wifi.portalAddInfoSection(deviceInfo);
+
+PortalHomeCard installerHint;
+installerHint.id = "installer-hint";
+installerHint.title = "Before you begin";
+installerHint.kind = PortalHomeCardKind::Callout;
+installerHint.text = "Connect the device to its final local network.";
+wifi.portalAddHomeCard(installerHint);
+~~~
+
+Information sections and cards are copied at registration. Do not place secrets, passwords, API tokens, or personally identifying values in them.
+
+## Save callbacks
+
+| Callback | Use |
+| --- | --- |
+| setPreSaveParamsCallback() | Observe a parameter-only save before the normal parameter callback. |
+| setSaveParamsCallback(args) | Read, validate, and persist application settings after a parameter save. |
+| setPreSaveConfigCallback() | Observe a combined Wi-Fi/config save before Wi-Fi connection processing. |
+| setSaveConfigCallback() | React after Wi-Fi settings changed and the connection succeeded, or when break-after-config is enabled. |
+| setConfigResetCallback() | Clear or reconcile application configuration when the portal resets Wi-Fi settings. |
+
+Do not use a Wi-Fi-success callback to persist unrelated product settings: parameters can be saved separately, and an application needs its own durable-data policy.
+
+The buildable [Custom Portal Content](../examples/CustomPortalContent/) example demonstrates parameters, information sections, and home cards. This guide supplies the missing persistence and validation boundary.
+
+## Continue
+
+- [Portal UI and configuration](PORTAL_UI.md)
+- [Product settings and Wi-Fi recipe](recipes/PRODUCT_SETTINGS_AND_WIFI.md)
+- [API reference](API_REFERENCE.md)
+
+Back to [documentation](README.md) · [project overview](../README.md).

docs/PORTAL_UI.md

@@ -0,0 +1,124 @@
+# Portal UI and configuration
+
+WiFiManagerPortalConfig is the supported presentation API for the built-in provisioning portal. It changes product identity and semantic visual tokens; the portal-policy methods below control the visibility and behavior of existing built-in features. WiFiManager continues to own portal routes, forms, navigation, captive behavior, reset, and OTA views.
+
+Apply presentation before autoConnect(), startConfigPortal(), or startWebPortal(). Configure portal policy during boot as well so each portal session begins consistently. Portal text and SVG assets are non-owning, so their RAM or PROGMEM data must have static firmware lifetime. WiFiManager locks presentation while a portal is active so asynchronous responses cannot observe partial configuration; setPortalConfig() returns false if it cannot accept the configuration.
+
+## Standalone branded portal
+
+~~~cpp
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+WiFiManager wifi;
+
+namespace {
+const char kTitle[] PROGMEM = "Set up Temperature Monitor";
+const char kIdentity[] PROGMEM = "Example Devices";
+const char kTagline[] PROGMEM = "Reliable setup for connected devices.";
+const char kLogoAlt[] PROGMEM = "Example Devices";
+const char kLogo[] PROGMEM =
+    R"svg(<svg viewBox="0 0 64 64"><circle cx="32" cy="32" r="28"/></svg>)svg";
+const char kPage[] PROGMEM = "#f4f7f3";
+const char kSurface[] PROGMEM = "#ffffff";
+const char kAccent[] PROGMEM = "#347a45";
+const char kAccentText[] PROGMEM = "#ffffff";
+
+WiFiManagerPortalConfig kPortalUI;
+}
+
+void setup() {
+    // Set only the identity values this product needs.
+    kPortalUI.title = WiFiManagerPortalText::progmem(kTitle);
+    kPortalUI.identityText = WiFiManagerPortalText::progmem(kIdentity);
+    kPortalUI.tagline = WiFiManagerPortalText::progmem(kTagline);
+    kPortalUI.logo = WiFiManagerPortalAsset::svgFromProgmem(kLogo);
+    kPortalUI.logoAltText = WiFiManagerPortalText::progmem(kLogoAlt);
+
+    // Unset theme values retain the built-in style.
+    kPortalUI.theme.pageBackground = WiFiManagerPortalText::progmem(kPage);
+    kPortalUI.theme.surface = WiFiManagerPortalText::progmem(kSurface);
+    kPortalUI.theme.accent = WiFiManagerPortalText::progmem(kAccent);
+    kPortalUI.theme.accentText = WiFiManagerPortalText::progmem(kAccentText);
+    kPortalUI.theme.cornerRadiusPx = 10;
+
+    if (!wifi.setPortalConfig(kPortalUI)) {
+        Serial.println("Portal UI configuration was rejected");
+    }
+    wifi.autoConnect("Temperature Monitor");
+}
+
+void loop() { wifi.process(); }
+~~~
+
+The complete buildable example is [Branded Portal](../examples/BrandedPortal/BrandedPortal.ino). The compile fixture exercises this API on ESP8266 and ESP32.
+
+## Presentation reference
+
+Leave a text or colour value empty, or a radius at 0, to retain the built-in stylesheet value.
+
+| Field | Used by |
+| --- | --- |
+| title | Document title and concise setup-page heading |
+| identityText | Company or product name in the header above navigation |
+| tagline | Short product context in the header above navigation |
+| logo.svg, logoAltText | Optional trusted inline SVG and its accessible label |
+| pageBackground, surface, text, mutedText, border | Portal surfaces and text |
+| accent, accentHover, accentText | Primary links and actions |
+| success, danger, dangerHover | Status and destructive actions |
+| cornerRadiusPx, smallCornerRadiusPx | Card and compact-control corners, limited to 64 px |
+
+Theme values accept simple named CSS values and are emitted once into a small
+portal theme block. Raw CSS and JavaScript are not supported. An SVG is a
+trusted compiled firmware asset, never form, MQTT, or network input.
+
+## Portal policy
+
+Use the portal-prefixed methods to choose which built-in pages and actions a
+product presents. Configure them during boot, before the portal starts, so a
+session begins with the intended behavior.
+
+~~~cpp
+// An installer portal that does not expose destructive reset or OTA actions.
+wifi.portalSetPageUpdateVisible(false);
+wifi.portalSetActionEraseVisible(false);
+wifi.portalSetActionRestartVisible(false);
+
+// Keep application settings on their own Setup page.
+wifi.portalSetLayoutParamsLocation(PortalParamsLocation::SetupPage);
+
+// Do not show saved passwords or static-IP fields unless the product needs them.
+wifi.portalSetFieldPasswordPlaceholderMode(PortalPasswordPlaceholderMode::Hidden);
+wifi.portalSetFieldStaticIpVisibility(PortalFieldVisibility::Hidden);
+wifi.portalSetFieldStaticDnsVisibility(PortalFieldVisibility::Hidden);
+~~~
+
+| Group | Methods | Use |
+| --- | --- | --- |
+| Pages | portalSetPageInfoVisible(), portalSetPageUpdateVisible(), portalSetPageSetupVisible() | Show only product-appropriate built-in pages. |
+| Actions | portalSetActionEraseVisible(), portalSetActionRestartVisible(), portalSetActionExitVisible(), portalSetActionCloseCaptiveVisible(), portalSetActionBackVisible() | Control existing action affordances; hiding an action is not a security boundary. |
+| Layout | portalSetLayoutParamsLocation() | Put registered parameters on the Wi-Fi page or separate Setup page. |
+| Connection/portal behavior | portalSetBehaviorCaptivePortalEnabled(), portalSetBehaviorConnectOnSave(), portalSetBehaviorExitAllowed(), portalSetBehaviorConnectTimeoutSeconds(), portalSetBehaviorPortalTimeoutSeconds(), portalSetBehaviorAutoReconnect(), portalSetBehaviorApClientCheck(), portalSetBehaviorWebClientCheck() | Set built-in portal behavior. |
+| Fields | portalSetFieldPasswordPlaceholderMode(), portalSetFieldStaticIpVisibility(), portalSetFieldStaticDnsVisibility() | Limit password disclosure and network-field visibility. |
+
+The older setConfigPortalTimeout(), setSaveConnect(), setShowStaticFields(), and related methods remain available. Prefer a single vocabulary within a product; the portal-prefixed methods make the policy visible in the portal's structured model.
+
+## Structured content
+
+Use portalAddParameter() for editable product settings, portalAddInfoSection() for labelled read-only values, and portalAddHomeCard() for overview text or key/value cards. Parameters remain application-owned; information sections and cards are copied when registered.
+
+See [Portal content](PORTAL_CONTENT.md) for the full persistence, validation, callback, and lifetime rules. The buildable [Custom Portal Content](../examples/CustomPortalContent/) example shows all three content types.
+
+## What stays built in
+
+Branding, policy, and structured content configure the supplied portal. The
+portal's HTML shell, routes, navigation, stylesheet, and scripts stay owned by
+WiFiManager. There is no custom shell, route replacement, navigation injection,
+raw stylesheet, or script hook.
+
+For a product-specific web application, start that application's own server
+after WiFiManager has completed provisioning. If the supplied portal needs a
+reusable capability, add one focused public WiFiManager C++ API and test it on
+ESP8266 and ESP32.
+
+Back to the [documentation index](README.md) or [project overview](../README.md).

docs/PROVISIONING_LIFECYCLE.md

@@ -0,0 +1,92 @@
+# Provisioning lifecycle
+
+Choose a connection flow that matches the device's operating policy, then call process() regularly for as long as WiFiManager is active. It is a cooperative service call, not a hard real-time guarantee: target Wi-Fi or DNS work can occasionally take longer than a typical loop iteration. The consuming firmware owns its product-service lifecycle and restart decision.
+
+## Choose a flow
+
+| Need | Preferred API | What it does |
+| --- | --- | --- |
+| One saved station network, with portal fallback | autoConnect() | Tries saved credentials and starts the configuration portal when the attempt cannot connect. |
+| Primary plus fallback network with application-owned storage | setStationProfileStore() + startStationConnection() | Loads, selects, retries, and recovers a fixed two-profile station set. |
+| Verify a received profile before retaining it | startStationCandidate() | Attempts a primary/fallback candidate in memory and saves it only after success. |
+| Start setup under application control | startConfigPortal() | Starts an AP and captive configuration portal immediately. |
+| Show the portal while station Wi-Fi is already available | startWebPortal() | Starts the portal web service without starting a configuration AP. |
+
+The first two are the normal deployed-device flows. StartConfigPortal() and startWebPortal() are supported control APIs, but should be used only when the application has a clear policy for entering and leaving them.
+
+## Basic recovery flow
+
+~~~cpp
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+WiFiManager wifi;
+
+void setup() {
+    Serial.begin(115200);
+    wifi.setConfigPortalTimeout(180);
+
+    if (wifi.autoConnect("Device Setup", "change-me")) {
+        startNormalApplication();
+    } else {
+        Serial.println("Wi-Fi setup portal is active");
+    }
+}
+
+void loop() {
+    wifi.process();
+
+    if (wifi.didConfigPortalConnectSucceed()) {
+        // The application decides whether to start services or reboot.
+        startNormalApplication();
+    }
+}
+~~~
+
+autoConnect() returns true when WiFiManager connected during that call. It returns false when it could not connect and has entered the portal path; false is not, by itself, an instruction to restart. Call process() every loop iteration while setup may be needed.
+
+A portal timeout is in seconds. setConfigPortalTimeout(0), the default, leaves the portal open. A field-installed product may deliberately use a longer bounded window, such as 15 minutes, so an installer has time to complete setup without leaving an unattended portal indefinitely.
+
+## Portal connection outcome
+
+For a portal save-and-connect attempt, use these getters instead of inferring state from the rendered page:
+
+| Getter | Meaning |
+| --- | --- |
+| getConfigPortalActive() | The configuration portal is currently running. |
+| hasEnteredConfigPortal() | The portal has been entered at least once this runtime session. |
+| isConfigPortalConnectPending() | A portal-submitted station connection is queued or waiting. |
+| didConfigPortalConnectSucceed() / didConfigPortalConnectFail() | Result of the last portal-submitted connection attempt. |
+| getConfigPortalConnectStatus() / getConfigPortalConnectMessage() | Platform Wi-Fi status and a human-readable result. |
+
+The local portal UI obtains the same state through its documented local API. Do not parse portal HTML to determine connection state.
+
+## Timing and policy
+
+Set these before the flow starts:
+
+| API | Use |
+| --- | --- |
+| setConfigPortalTimeout(seconds) | Limits a captive configuration session; setTimeout() is its deprecated alias. |
+| setConnectTimeout(seconds) and setConnectRetries(count) | Bounds legacy automatic connection attempts. |
+| setSaveConnectTimeout(seconds) | Bounds a portal save-and-connect attempt. |
+| setSaveConnect(enabled) | Controls whether a normal portal save attempts a station connection. |
+| setBreakAfterConfig(enabled) | Exits after a configuration submission even if the connection was unsuccessful. |
+| setEnableConfigPortal(enabled) / setDisableConfigPortal(enabled) | Controls autoConnect() portal fallback and its post-save shutdown behavior. |
+| setAPClientCheck(enabled) / setWebPortalClientCheck(enabled) | Controls whether AP/web-client activity affects the portal timeout. |
+
+The portal-prefixed behavior methods provide the same configuration through the structured portal contract; prefer one vocabulary consistently in a product.
+
+## Port ownership and clean handoff
+
+Before beginning a portal on port 80, stop any application server that already owns that port. After a portal connection succeeds, wait for the application's own readiness requirements before starting its server again. A successful station connection does not automatically make an application-level service ready.
+
+See [Local web-service handoff](recipes/LOCAL_WEB_SERVICE_HANDOFF.md) for the integration sequence.
+
+## Continue
+
+- [Station profiles](STATION_PROFILES.md)
+- [Observability](OBSERVABILITY.md)
+- [API reference](API_REFERENCE.md)
+
+Back to [documentation](README.md) · [project overview](../README.md).

docs/README.md

@@ -0,0 +1,20 @@
+# WiFiManager documentation
+
+| I want to… | Read |
+| --- | --- |
+| See what WiFiManager handles and what the firmware handles | [Integrating WiFiManager](ARCHITECTURE.md) |
+| Start a basic portal or install a released dependency | [Getting started](GETTING_STARTED.md) |
+| Choose and operate a provisioning flow | [Provisioning lifecycle](PROVISIONING_LIFECYCLE.md) |
+| Brand or constrain the built-in portal | [Portal UI and configuration](PORTAL_UI.md) |
+| Add and persist application settings, status, or home cards | [Portal content](PORTAL_CONTENT.md) |
+| Configure primary/fallback station profiles or their portal workflow | [Station profiles](STATION_PROFILES.md) |
+| Configure AP, station, scan, and reconnect settings | [Network configuration](NETWORK_CONFIGURATION.md) |
+| Surface portal and station state in product firmware | [Observability](OBSERVABILITY.md) |
+| Look up a supported C++ method and lifecycle rule | [API reference](API_REFERENCE.md) |
+| Maintain or test the built-in portal's browser protocol | [Portal browser protocol](PORTAL_API.md) |
+| Apply an existing device-integration pattern | [Recipes](recipes/README.md) |
+| Run documentation and board-free compile checks | [Testing](TESTING.md) |
+| Build or flash a complete example | [Examples](../examples/README.md) |
+| Work on this fork or make a release | [Development and releases](DEVELOPMENT.md) |
+
+Back to the [project overview](../README.md).

docs/STATION_PROFILES.md

@@ -0,0 +1,90 @@
+# Station profiles
+
+WiFiManager adds an opt-in station-profile controller for applications that need a primary Wi-Fi network and one fallback. It is independent of the legacy autoConnect() flow: existing WiFiManager consumers do not need to change.
+
+Profile mode is enabled only when the application supplies a WiFiManagerStationProfileStore. The store may be an in-memory implementation for a temporary session, but durable deployments should provide persistent storage.
+
+## Lifecycle
+
+A profile set has exactly two fixed slots:
+
+- **Primary** (slot 0) is required whenever the controller is enabled.
+- **Fallback** (slot 1) is optional.
+- The last successful slot is tried first on the next connection cycle, then the remaining enabled slot.
+
+The controller never treats the ESP SDK's saved single network as an additional source of truth. It begins one bounded connection attempt at a time, moves to the fallback after failure, and retries both profiles after a temporary loss of a previously working connection. If a new device has no valid profiles, it opens the normal configuration portal.
+
+A candidate submitted by the portal or another application subsystem is only committed after it connects and receives a usable IP address. A failed candidate leaves the last saved profile set intact.
+
+## Direct WiFiManager use
+
+Implement a small store appropriate to the application. WiFiManager neither allocates nor owns it:
+
+~~~cpp
+class MyProfileStore final : public WiFiManagerStationProfileStore {
+public:
+    bool load(WiFiManagerStationProfiles& profiles) override;
+    bool save(const WiFiManagerStationProfiles& profiles) override;
+    bool clear() override;
+};
+
+WiFiManager wifi;
+MyProfileStore profiles;
+
+void setup() {
+    wifi.setStationProfileStore(&profiles);
+    wifi.setStationRecoveryInterval(30000);
+    wifi.startStationConnection("Example Setup", "setup-password");
+}
+
+void loop() {
+    wifi.process();
+}
+~~~
+
+The store must return a complete WiFiManagerStationProfiles value. Each enabled profile has a NUL-terminated SSID of at most 32 characters and an optional NUL-terminated password of at most 64 characters. Keep slot 0 enabled; set hasPassword to false for an open network.
+
+When load() returns false, WiFiManager treats the profile set as unavailable and opens the normal configuration portal. When save() or clear() returns false, getStationStatus().storageSaveFailed is set and the status message explains the failure.
+
+## Verified candidate flow
+
+Use startStationCandidate(candidate) when another application subsystem supplies a complete primary/fallback proposal:
+
+~~~cpp
+wifi.setStationProfileStore(&profiles);
+
+if (!wifi.startStationCandidate(candidate, "Example Setup", "setup-password")) {
+    reportInvalidProfileCandidate();
+}
+~~~
+
+WiFiManager tries the candidate in memory, then calls the attached store only after the station connects and has a usable IP address. Inspect getStationStatus() after WM_EVENT_STATION_PROFILE_CONNECTED: lastConnectionWasCandidate tells the application that this was a candidate, and storageSaveFailed distinguishes a usable but non-durable connection.
+
+Use saveStationProfiles(profiles) only when deliberately saving without a connection check. clearStationProfiles() asks the supplied store to clear profiles and disconnects the station only after that clear succeeds.
+
+The [Primary and fallback Wi-Fi recipe](recipes/PRIMARY_AND_FALLBACK_WIFI.md) shows why candidate verification protects known-good data.
+
+## Portal contract
+
+In profile mode, the existing Wi-Fi page becomes a two-profile form. It remains driven by the same local portal endpoints:
+
+- GET /api/wifi/meta returns profiles, activeSlot, and controller state without passwords.
+- POST /api/wifi/save accepts s0/p0 for primary and s1/p1 for fallback. A blank submitted password preserves an existing password; send clear0 or clear1 for an intentional open network.
+- A normal save verifies the candidate by connecting. The built-in portal polls GET /api/wifi/connect-status for its result.
+- stationAction=save stores the submitted profiles for a later connection attempt.
+
+The portal requires a non-empty primary SSID. Its local protocol never returns a password. See [Portal API](PORTAL_API.md) for the shared connection-status response.
+
+## Recovery and troubleshooting
+
+| Symptom | Inspect | Meaning |
+| --- | --- | --- |
+| Portal starts immediately | getStationStatus().configuredProfiles and message | Store had no valid primary profile, so WiFiManager did not fall back to SDK-owned credentials. |
+| Repeated network recovery | state, attemptedSlot, activeSlot, and WM_EVENT_STATION_BACKOFF | The controller is trying configured profiles with the recovery interval. |
+| Candidate is connected but lost after reboot | lastConnectionWasCandidate and storageSaveFailed | The candidate connected, but the application store did not retain it. |
+| Portal form rejects a save | Local API response/message | Primary profile was missing or SSID/password bounds were invalid. |
+| Profiles do not clear | storageSaveFailed and message | The application store rejected clear(); fix its storage error before assuming Wi-Fi was removed. |
+
+The buildable [Station Profiles](../examples/StationProfiles/) example contains a compact EEPROM-backed store for both supported ESP targets.
+
+Back to [documentation](README.md) · [project overview](../README.md).

docs/TESTING.md

@@ -0,0 +1,105 @@
+# Testing
+
+WiFiManager separates repeatable package checks from opt-in tests that flash a
+real board or join a captive portal. The normal commands never need a board,
+local Wi-Fi credentials, browser binary, or sibling checkout.
+
+## Clean consumer and example builds
+
+The clean-consumer check builds a project that declares only WiFiManager. It
+proves the package manifest resolves DFTE, ESPAsyncWebServer, and the correct
+ESP8266 or ESP32 TCP dependency without a sibling checkout. The runner removes
+a prior local package link before each check, so dependency resolution uses the
+current manifest rather than a stale `.pio` copy.
+
+```bash
+./scripts/test.sh compile --platform esp8266
+./scripts/test.sh compile --platform esp32
+./scripts/test.sh examples --platform esp8266
+./scripts/test.sh examples --platform esp32
+```
+
+CI runs these board-free checks for pull requests and pushes to the maintained
+branch. It intentionally does not require attached hardware, a local network,
+or Docker.
+
+## Local hardware lifecycle tests
+
+The Unity suite runs portal-only firmware with no Wi-Fi credentials, MQTT,
+product application framework, or local profile. It verifies portal start/stop
+recovery, scan-cache release, and a real asynchronous Wi-Fi scan.
+
+Use a stable serial-by-id path rather than a changing `/dev/ttyUSB` number:
+
+```bash
+pio device list
+./scripts/test.sh hardware --platform esp8266 --port /dev/serial/by-id/usb-...
+./scripts/test.sh hardware --platform esp32 --port /dev/serial/by-id/usb-...
+```
+
+The runner flashes the selected board, captures normal-boot serial output with
+the repository Bash helper, requires Unity's `Tests 0 Failures` and `OK`
+summary, and prints lifecycle metrics. Hardware work shares a lock with the
+portal contract, so two invocations cannot flash or use the same board at once.
+
+## Docker portal contract
+
+`test/portal-harness` is deliberately tiny portal-only firmware, not an example
+or consuming application. `tools/portal-hardware` flashes it to one explicitly
+selected board, joins its AP through one explicitly selected **secondary**
+Wi-Fi adapter, then runs its HTTP and browser contract in a pinned Playwright
+Docker image. Docker uses host networking only to reach the already-routed
+portal; it never runs NetworkManager or changes host adapters.
+
+```bash
+./tools/portal-hardware doctor --client-interface wlx74da385d4165
+./tools/portal-hardware run \
+  --platform esp8266 \
+  --port /dev/serial/by-id/usb-... \
+  --client-interface wlx74da385d4165
+```
+
+The command refuses the host default-route adapter. If the chosen secondary
+adapter is already connected, require an explicit acknowledgement before it is
+replaced:
+
+```bash
+./tools/portal-hardware run ... --take-over-client-adapter
+```
+
+The fixture opens a 15-minute portal session, includes one harmless custom
+parameter, and verifies root/bootstrap/info/status API responses, concurrent
+low-priority requests, parameter persistence, timeout reset, an actual async
+scan, a missing-route response, and desktop/mobile portal rendering with no
+browser page errors. Screenshots, traces on failure, JSON results, and the HTML
+report are saved under the printed XDG state-directory artifact path.
+
+On ESP8266, an AP+STA scan can briefly move the radio off the AP channel. The
+client may reconnect during that interval; the contract deliberately retries
+that transport interruption and still requires a reachable portal with a
+complete, valid scan result.
+
+For interactive diagnosis, leave the temporary client connection up and remove
+only that managed connection when finished:
+
+```bash
+./tools/portal-hardware up --platform esp32 --port /dev/serial/by-id/usb-... \
+  --client-interface wlx74da385d4165
+./tools/portal-hardware down
+```
+
+An optional station handoff test is deliberately separate because it connects
+the fixture to a real LAN. Copy the ignored template below, add local
+credentials, and pass it explicitly; it is mounted read-only into the test
+container and is never logged by the runner.
+
+A retained session is deliberately never overwritten. If a previous `up` or an
+interrupted `run` left one behind, run `./tools/portal-hardware down` first;
+that removes only the named temporary connection recorded by the tool.
+
+```bash
+cp test/portal-station.env.example test/portal-station.env
+./tools/portal-hardware run ... --station-env test/portal-station.env
+```
+
+Back to [documentation](README.md) · [project overview](../README.md).

docs/recipes/FIELD_INSTALLER_PROVISIONING.md

@@ -0,0 +1,63 @@
+# Field installer provisioning
+
+A field-installed controller or sensor often needs more time for setup than a desk-bound demo, but should not host an unattended configuration portal forever. Existing consuming device sketches solve this by choosing a deliberate 15-minute configuration window and exposing clear local feedback while setup is active.
+
+## Flow
+
+1. Boot with the product's normal configuration.
+2. Try the stored primary/fallback profile set.
+3. If Wi-Fi is unavailable, start the local setup AP and portal.
+4. Keep the portal available for the installation window.
+5. On a successful connection, let the application start services or reboot according to its own policy.
+6. On timeout, return to the product's recovery policy rather than assuming the installer finished.
+
+~~~cpp
+constexpr unsigned long kInstallerWindowSeconds = 15 * 60;
+MyProfileStore profileStore;
+
+void setup() {
+    configureProductPortal();
+    wifi.setStationProfileStore(&profileStore);
+    wifi.setStationRecoveryInterval(30000);
+    wifi.setConfigPortalTimeout(kInstallerWindowSeconds);
+
+    wifi.setAPCallback([](WiFiManager*) {
+        setIndicator(IndicatorState::Setup);
+        showInstallerInstructions();
+    });
+
+    wifi.setConfigPortalTimeoutCallback([] {
+        setIndicator(IndicatorState::Offline);
+        recordSetupTimeout();
+    });
+
+    wifi.startStationConnection(deviceSetupName(), deviceSetupPassword());
+}
+
+void loop() {
+    wifi.process();
+    // Do not start or recreate an application server while the portal owns its port.
+}
+~~~
+
+The timeout is a product decision. A short interval is appropriate for a user-facing appliance; a longer maintenance window may be justified for a device installed in a cabinet or plant room. Set 0 only when an always-open setup portal is an explicit operational choice.
+
+## What to show an installer
+
+Keep feedback independent of a browser redirect:
+
+- the setup SSID and any required password;
+- the device's portal address and non-default port, if configured;
+- a distinct setup indicator while the portal is active;
+- a distinct failure/offline indication after timeout;
+- confirmation only after Wi-Fi has actually connected.
+
+Use getConfigPortalActive(), didConfigPortalConnectSucceed(), and getConfigPortalConnectMessage() for this state. See [Observability](../OBSERVABILITY.md).
+
+## Product boundary
+
+WiFiManager supplies the local portal and timer. The product decides what happens after timeout: keep retrying profiles, sleep, wait for a physical action, or operate in an offline mode. If startStationConnection() returns false because no usable stored profile exists, the portal may be the intended next state rather than a reason to reboot immediately.
+
+For a product that deliberately uses one platform-saved network rather than primary/fallback profiles, the smaller legacy equivalent is wifi.autoConnect(deviceSetupName(), deviceSetupPassword()). It has the same local portal fallback, but no application-owned profile store, candidate verification, or fallback network.
+
+Continue with [Provisioning lifecycle](../PROVISIONING_LIFECYCLE.md) or [Provisioning state feedback](PROVISIONING_STATE_FEEDBACK.md).

docs/recipes/LOCAL_WEB_SERVICE_HANDOFF.md

@@ -0,0 +1,40 @@
+# Local web-service handoff
+
+A product may already host its own local HTTP service when a later connection failure opens WiFiManager's provisioning portal. Because WiFiManager owns its portal server port while active, the product must release that port before WiFiManager registers its portal routes.
+
+A real consuming framework does this from the AP callback: it shuts down its normal web service after the setup AP has started but before WiFiManager registers portal routes.
+
+## Automatic recovery handoff
+
+~~~cpp
+MyProfileStore profileStore;
+
+void setup() {
+    wifi.setStationProfileStore(&profileStore);
+    wifi.setStationRecoveryInterval(30000);
+
+    wifi.setAPCallback([](WiFiManager*) {
+        stopApplicationWebServer();  // Releases port 80 for WiFiManager.
+        setIndicator(IndicatorState::Setup);
+    });
+
+    wifi.startStationConnection("Device Setup", "setup-password");
+}
+~~~
+
+The AP callback runs after AP mode begins and before the portal routes are registered. It is the appropriate hook for automatic portal fallback. This profile-controller form matches the consuming firmware's recovery flow. If a product deliberately uses one platform-saved network instead, replace startStationConnection(...) with wifi.autoConnect(...); the same AP callback ordering applies. If the application explicitly starts setup itself, release its server before calling startConfigPortal().
+
+## After a successful connection
+
+The portal's successful Wi-Fi connection means the station has an address. It does not guarantee that the product's own web application, MQTT connection, or sensors are ready. The product should:
+
+1. observe didConfigPortalConnectSucceed() or the matching event;
+2. persist any application settings required for normal operation;
+3. choose whether to restart or recreate its own server;
+4. only advertise the product service when it is ready.
+
+If the product uses a non-default WiFiManager HTTP port, it can avoid a port conflict but must treat the portal URL and its station-connect handoff URL as that non-default port.
+
+Do not add routes to WiFiManager's internal server through getServer(). That accessor is for testing/host integration, not a supported product-extension API.
+
+Continue with [Provisioning lifecycle](../PROVISIONING_LIFECYCLE.md) and [Observability](../OBSERVABILITY.md).

docs/recipes/PRIMARY_AND_FALLBACK_WIFI.md

@@ -0,0 +1,49 @@
+# Primary and fallback Wi-Fi
+
+Some deployed devices receive a primary Wi-Fi network and an optional fallback from a local provisioning source. The consuming framework uses WiFiManager's fixed two-profile controller so it can verify a candidate connection before replacing durable known-good profiles.
+
+## Flow
+
+1. The application obtains a complete candidate profile set.
+2. It gives the candidate to startStationCandidate().
+3. WiFiManager attempts the primary profile and then fallback when needed.
+4. On a usable station connection, WiFiManager saves the candidate through the application-owned store.
+5. If connection or storage fails, the application can report the result without silently replacing known-good data.
+
+~~~cpp
+WiFiManagerStationProfiles candidate = makeDeploymentProfiles();
+
+wifi.setStationProfileStore(&profileStore);
+wifi.setStationRecoveryInterval(30000);
+
+if (!wifi.startStationCandidate(candidate, "Device Setup", "setup-password")) {
+    reportRejectedProfileSet();
+}
+~~~
+
+A candidate needs a non-empty enabled primary slot. The fallback slot is optional. WiFiManager never exposes profile passwords through the portal metadata API.
+
+## Treat persistence result as part of success
+
+A candidate can connect successfully while the profile store fails to write. Read getStationStatus() when WM_EVENT_STATION_PROFILE_CONNECTED arrives:
+
+~~~cpp
+wifi.setEventCallback([](WiFiManager::wm_event_t event) {
+    if (event != WiFiManager::WM_EVENT_STATION_PROFILE_CONNECTED) {
+        return;
+    }
+
+    const auto& status = wifi.getStationStatus();
+    if (status.lastConnectionWasCandidate && status.storageSaveFailed) {
+        reportConnectedButNotRetained();
+    }
+});
+~~~
+
+This distinction matters in unattended devices: the device works now, but may fail to reconnect after a restart.
+
+## Bootstrap and reconcile are application decisions
+
+WiFiManager verifies and selects station profiles. It does not define whether a product should accept a supplied profile only on first boot, replace values after an explicit revision, or merge settings from another system. Keep that policy in the application, alongside its durable configuration and schema migration.
+
+See [Station profiles](../STATION_PROFILES.md) for store requirements, portal fields, and the complete controller lifecycle.

docs/recipes/PRODUCT_SETTINGS_AND_WIFI.md

@@ -0,0 +1,56 @@
+# Product settings and Wi-Fi
+
+A connected device often needs more than an SSID and password: a device name, broker host, endpoint, operating mode, or installer-selected option. The actual consuming framework pattern is to load those settings before WiFiManager begins, expose them as portal parameters, and persist them through the application's own storage layer.
+
+## Flow
+
+1. Load the application's durable settings and run its schema migration.
+2. Build WiFiManagerParameter objects from the loaded values.
+3. Register those parameters before a portal can start.
+4. Register the save-parameters callback.
+5. Validate and persist submitted application values through the application's storage layer.
+6. Separately observe a successful Wi-Fi configuration/save if product services need a connected station first.
+
+~~~cpp
+constexpr int kBrokerHostLength = 64;
+WiFiManagerParameter brokerHost(
+    "broker_host", "MQTT broker", "", kBrokerHostLength);
+
+void configurePortalFromSettings() {
+    brokerHost.setValue(settings.mqttHost.c_str(), kBrokerHostLength);
+    wifi.portalAddParameter(&brokerHost);
+
+    wifi.setSaveParamsCallback([](WiFiManager::WiFiManagerRequestArgs) {
+        const String requestedHost = brokerHost.getValue();
+
+        if (!isValidHostname(requestedHost)) {
+            logRejectedSetting("broker_host");
+            return;
+        }
+
+        settings.mqttHost = requestedHost;
+        if (!saveApplicationSettings(settings)) {
+            reportConfigurationStorageFailure();
+        }
+    });
+}
+~~~
+
+WiFiManager does not own settings, schema migration, or the storage transaction. In particular, an application should keep known-good settings if validation or storage fails.
+
+## Keep the two persistence paths separate
+
+| Data | Owner | Save trigger |
+| --- | --- | --- |
+| Wi-Fi credentials in legacy mode | WiFiManager/platform Wi-Fi | Portal Wi-Fi save and connection flow |
+| Primary/fallback station profiles | Application-provided profile store | Profile controller after verified candidate connection, or explicit save |
+| Product settings | Application | setSaveParamsCallback() and application validation |
+| Product schema/revision | Application | Application boot/migration policy |
+
+A profile provisioning revision is not the same thing as an application schema version. The application owns both migration and the decision to apply a configuration update.
+
+## Form placement
+
+Use portalSetLayoutParamsLocation(PortalParamsLocation::WiFiPage) for one or two values that naturally belong in initial connectivity setup. Use SetupPage for product configuration that deserves a separate step. Put read-only status in PortalInfoSection or PortalHomeCard rather than turning it into a parameter.
+
+For lifetime and callback details, see [Portal content](../PORTAL_CONTENT.md).

docs/recipes/PROVISIONING_STATE_FEEDBACK.md

@@ -0,0 +1,43 @@
+# Provisioning state feedback
+
+A physical device should give useful feedback without relying on a captive-browser redirect. Existing consuming firmware uses WiFiManager state to make setup, recovery, and connected states visible through an LED, display, or local log.
+
+## State model
+
+| Product state | WiFiManager signal | Typical feedback |
+| --- | --- | --- |
+| Normal connected operation | Station/profile controller connected, no configuration portal | Normal indicator and application services. |
+| Trying known networks | Profile status is attempting or switching | Short recovery indication; no claim that setup is active yet. |
+| Setup portal active | getConfigPortalActive() is true or WM_EVENT_PORTAL_STARTED | Installer-oriented setup indication and instructions. |
+| Portal submitted credentials | isConfigPortalConnectPending() is true | Progress indication. |
+| Portal connection succeeded | didConfigPortalConnectSucceed() or WM_EVENT_PORTAL_CONNECT_SUCCESS | Connected confirmation; application decides when services start. |
+| Portal connection failed | didConfigPortalConnectFail() or WM_EVENT_PORTAL_CONNECT_FAILED | Failure indication with retry/recovery policy. |
+| Candidate connected but not stored | Station event plus storageSaveFailed | Warning: active connection may not survive restart. |
+
+## Polling pattern
+
+~~~cpp
+void updateIndicator() {
+    if (wifi.getConfigPortalActive()) {
+        setIndicator(IndicatorState::Setup);
+    } else if (wifi.isConfigPortalConnectPending()) {
+        setIndicator(IndicatorState::Connecting);
+    } else if (wifi.didConfigPortalConnectFail()) {
+        setIndicator(IndicatorState::Offline);
+    } else {
+        setIndicator(IndicatorState::Normal);
+    }
+}
+~~~
+
+Call this from the application loop after wifi.process(). For profile mode, add getStationStatus() so the product can distinguish an active station recovery attempt from a portal session.
+
+## Event pattern
+
+Events reduce polling for transitions, but getters remain the authoritative state. Use setEventCallback() to record a transition or wake a product state machine, then read the relevant portal/profile status. Avoid performing long work in the callback; keep it suitable for the normal firmware loop.
+
+## Operator-facing messages
+
+Use getConfigPortalConnectMessage() and getWLStatusString() for concise local diagnostics. Never place Wi-Fi passwords, portal parameter values, or secrets in an operator display or remotely collected logs.
+
+See [Observability](../OBSERVABILITY.md) for the complete event list and [Field installer provisioning](FIELD_INSTALLER_PROVISIONING.md) for timeout policy.

docs/recipes/README.md

@@ -0,0 +1,15 @@
+# Integration recipes
+
+These patterns come from real firmware that consumes this WiFiManager fork. They describe the boundary between a product application and WiFiManager; they are not additional framework APIs and do not require a cloud service or companion app.
+
+| Scenario | Start here when… |
+| --- | --- |
+| [Field installer provisioning](FIELD_INSTALLER_PROVISIONING.md) | A physical device needs a deliberately bounded setup window on site. |
+| [Product settings and Wi-Fi](PRODUCT_SETTINGS_AND_WIFI.md) | The portal collects Wi-Fi and application-owned settings together. |
+| [Primary and fallback Wi-Fi](PRIMARY_AND_FALLBACK_WIFI.md) | A deployment supplies a candidate primary/fallback network that must be verified before storage. |
+| [Local web-service handoff](LOCAL_WEB_SERVICE_HANDOFF.md) | The application already owns port 80 when recovery provisioning may begin. |
+| [Provisioning state feedback](PROVISIONING_STATE_FEEDBACK.md) | LEDs, a display, or logs need to distinguish setup, recovery, and connected states. |
+
+The normal [Basic Portal](../../examples/BasicPortal/) example remains the shortest way to try the legacy saved-network-or-portal flow. These recipes explain the product concerns that a standalone example should not pretend to solve.
+
+Back to [documentation](../README.md) · [project overview](../../README.md).

examples/AutoConnect/AutoConnect.ino

@@ -1,38 +0,0 @@
-#include <ESP8266WiFi.h>          //https://github.com/esp8266/Arduino
-
-//needed for library
-#include <DNSServer.h>
-#include <ESP8266WebServer.h>
-#include <WiFiManager.h>         //https://github.com/tzapu/WiFiManager
-
-
-void setup() {
-    // put your setup code here, to run once:
-    Serial.begin(115200);
-
-    //WiFiManager
-    //Local intialization. Once its business is done, there is no need to keep it around
-    WiFiManager wifiManager;
-    //reset saved settings
-    //wifiManager.resetSettings();
-    
-    //set custom ip for portal
-    //wifiManager.setAPConfig(IPAddress(10,0,1,1), IPAddress(10,0,1,1), IPAddress(255,255,255,0));
-
-    //fetches ssid and pass from eeprom and tries to connect
-    //if it does not connect it starts an access point with the specified name
-    //here  "AutoConnectAP"
-    //and goes into a blocking loop awaiting configuration
-    wifiManager.autoConnect("AutoConnectAP");
-    //or use this for auto generated name ESP + ChipID
-    //wifiManager.autoConnect();
-
-    
-    //if you get here you have connected to the WiFi
-    Serial.println("connected...yeey :)");
-}
-
-void loop() {
-    // put your main code here, to run repeatedly:
-    
-}

examples/AutoConnectWithFeedback/AutoConnectWithFeedback.ino

@@ -1,44 +0,0 @@
-#include <ESP8266WiFi.h>          //https://github.com/esp8266/Arduino
-
-//needed for library
-#include <DNSServer.h>
-#include <ESP8266WebServer.h>
-#include <WiFiManager.h>          //https://github.com/tzapu/WiFiManager
-
-void configModeCallback () {
-  Serial.println("Entered config mode");
-  Serial.println(WiFi.softAPIP());
-}
-
-void setup() {
-  // put your setup code here, to run once:
-  Serial.begin(115200);
-  
-  //WiFiManager
-  //Local intialization. Once its business is done, there is no need to keep it around
-  WiFiManager wifiManager;
-  //reset settings - for testing
-  //wifiManager.resetSettings();
-
-  //set callback that gets called when connecting to previous WiFi fails, and enters Access Point mode
-  wifiManager.setAPCallback(configModeCallback);
-  //fetches ssid and pass and tries to connect
-  //if it does not connect it starts an access point with the specified name
-  //here  "AutoConnectAP"
-  //and goes into a blocking loop awaiting configuration
-  if(!wifiManager.autoConnect("AutoConnectAP")) {
-    Serial.println("failed to connect and hit timeout");
-    //reset and try again, or maybe put it to deep sleep
-    ESP.reset();
-    delay(1000);
-  } 
-
-  //if you get here you have connected to the WiFi
-  Serial.println("connected...yeey :)");
- 
-}
-
-void loop() {
-  // put your main code here, to run repeatedly:
-
-}

examples/AutoConnectWithTimeout/AutoConnectWithTimeout.ino

@@ -1,45 +0,0 @@
-#include <ESP8266WiFi.h>          //https://github.com/esp8266/Arduino
-
-//needed for library
-#include <DNSServer.h>
-#include <ESP8266WebServer.h>
-#include <WiFiManager.h>          //https://github.com/tzapu/WiFiManager
-
-
-
-void setup() {
-  // put your setup code here, to run once:
-  Serial.begin(115200);
-  
-  //WiFiManager
-  //Local intialization. Once its business is done, there is no need to keep it around
-  WiFiManager wifiManager;
-  //reset settings - for testing
-  //wifiManager.resetSettings();
-
-  //sets timeout until configuration portal gets turned off
-  //useful to make it all retry or go to sleep
-  //in seconds
-  wifiManager.setTimeout(180);
-  
-  //fetches ssid and pass and tries to connect
-  //if it does not connect it starts an access point with the specified name
-  //here  "AutoConnectAP"
-  //and goes into a blocking loop awaiting configuration
-  if(!wifiManager.autoConnect("AutoConnectAP")) {
-    Serial.println("failed to connect and hit timeout");
-    delay(3000);
-    //reset and try again, or maybe put it to deep sleep
-    ESP.reset();
-    delay(5000);
-  } 
-
-  //if you get here you have connected to the WiFi
-  Serial.println("connected...yeey :)");
- 
-}
-
-void loop() {
-  // put your main code here, to run repeatedly:
-
-}

examples/BasicPortal/BasicPortal.ino

@@ -0,0 +1,17 @@
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+WiFiManager portal;
+
+void setup() {
+    Serial.begin(115200);
+    portal.setConfigPortalTimeout(180);
+
+    if (portal.autoConnect("WiFiManager Basic", "example-pass")) {
+        Serial.println("Connected. Run your normal application here.");
+    } else {
+        Serial.println("Setup portal started at http://192.168.4.1/");
+    }
+}
+
+void loop() { portal.process(); }

examples/BasicPortal/README.md

@@ -0,0 +1,12 @@
+# Basic Portal
+
+This is the smallest useful WiFiManager application. It first tries the credentials the ESP platform already knows. If it cannot connect, it opens an access point named **WiFiManager Basic** with password **example-pass**.
+
+1. Build and flash the selected `esp8266` or `esp32` environment.
+2. Connect a phone or computer to **WiFiManager Basic**.
+3. Open `http://192.168.4.1/` if your captive-portal helper does not open it automatically.
+4. Select a network and save it. The board joins that network and the next reboot reconnects without opening the portal.
+
+The access-point password is only an example. Choose a unique, Wi-Fi-valid password for a real product.
+
+See the shared [example guide](../README.md), [getting started](../../docs/GETTING_STARTED.md), and [provisioning lifecycle](../../docs/PROVISIONING_LIFECYCLE.md).

examples/BasicPortal/platformio.ini

@@ -0,0 +1,26 @@
+[platformio]
+default_envs = esp8266
+src_dir = .
+
+[common]
+framework = arduino
+lib_ldf_mode = deep+
+lib_deps =
+    WiFiManager=symlink://../..
+
+[env:esp8266]
+extends = common
+platform = espressif8266
+board = d1_mini
+platform_packages =
+    platformio/framework-arduinoespressif8266 @ https://github.com/esp8266/Arduino.git#521ae60a89e64bb0d1eb7a0b7addf620ced5cad3
+
+[env:esp32]
+extends = common
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/51.03.05/platform-espressif32.zip
+board = esp32dev
+build_unflags = -std=gnu++11
+build_flags =
+    -std=gnu++14
+    -DSOC_WIFI_SUPPORTED=1
+    -I${platformio.packages_dir}/framework-arduinoespressif32/libraries/Network/src

examples/BrandedPortal/BrandedPortal.ino

@@ -0,0 +1,47 @@
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+WiFiManager wifi;
+
+namespace {
+const char kPortalTitle[] PROGMEM = "Set up Temperature Monitor";
+const char kPortalIdentity[] PROGMEM = "Example Devices";
+const char kPortalTagline[] PROGMEM = "Reliable setup for connected devices.";
+const char kPortalLogoAlt[] PROGMEM = "Example Devices";
+const char kExampleLogo[] PROGMEM = "<svg viewBox='0 0 64 64' aria-hidden='true'><circle cx='32' cy='32' r='28' fill='#347a45'/></svg>";
+const char kPage[] PROGMEM = "#f4f7f3";
+const char kSurface[] PROGMEM = "#ffffff";
+const char kText[] PROGMEM = "#1c251e";
+const char kAccent[] PROGMEM = "#347a45";
+const char kAccentText[] PROGMEM = "#ffffff";
+
+WiFiManagerPortalConfig kPortalUI;
+}
+
+void setup() {
+    Serial.begin(115200);
+
+    // Brand the built-in portal; unassigned fields retain their default values.
+    kPortalUI.title = WiFiManagerPortalText::progmem(kPortalTitle);
+    kPortalUI.identityText = WiFiManagerPortalText::progmem(kPortalIdentity);
+    kPortalUI.tagline = WiFiManagerPortalText::progmem(kPortalTagline);
+    kPortalUI.logo = WiFiManagerPortalAsset::svgFromProgmem(kExampleLogo);
+    kPortalUI.logoAltText = WiFiManagerPortalText::progmem(kPortalLogoAlt);
+
+    // Override only the theme tokens that define this product's appearance.
+    kPortalUI.theme.pageBackground = WiFiManagerPortalText::progmem(kPage);
+    kPortalUI.theme.surface = WiFiManagerPortalText::progmem(kSurface);
+    kPortalUI.theme.text = WiFiManagerPortalText::progmem(kText);
+    kPortalUI.theme.accent = WiFiManagerPortalText::progmem(kAccent);
+    kPortalUI.theme.accentText = WiFiManagerPortalText::progmem(kAccentText);
+    kPortalUI.theme.cornerRadiusPx = 10;
+    kPortalUI.theme.smallCornerRadiusPx = 6;
+
+    if (!wifi.setPortalConfig(kPortalUI)) {
+        Serial.println("Portal UI configuration was rejected");
+    }
+    wifi.setConfigPortalTimeout(180);
+    wifi.autoConnect("Temperature Monitor");
+}
+
+void loop() { wifi.process(); }

examples/BrandedPortal/README.md

@@ -0,0 +1,9 @@
+# Branded Portal
+
+This example uses the supported `WiFiManagerPortalConfig` presentation API to give the built-in portal a product name, company identity, tagline, inline SVG mark, and semantic colour tokens.
+
+Flash the `esp8266` or `esp32` environment, join **Temperature Monitor**, and open `http://192.168.4.1/`. The visual changes come from static firmware data; WiFiManager still owns the portal routes, forms, validation, and captive-network behaviour.
+
+Use only trusted compiled SVG data. Keep the backing strings static for the lifetime of the firmware, then call `setPortalConfig()` before opening a portal.
+
+See [Portal UI and configuration](../../docs/PORTAL_UI.md), [architecture boundaries](../../docs/ARCHITECTURE.md), and the shared [example guide](../README.md).

examples/BrandedPortal/platformio.ini

@@ -0,0 +1,26 @@
+[platformio]
+default_envs = esp8266
+src_dir = .
+
+[common]
+framework = arduino
+lib_ldf_mode = deep+
+lib_deps =
+    WiFiManager=symlink://../..
+
+[env:esp8266]
+extends = common
+platform = espressif8266
+board = d1_mini
+platform_packages =
+    platformio/framework-arduinoespressif8266 @ https://github.com/esp8266/Arduino.git#521ae60a89e64bb0d1eb7a0b7addf620ced5cad3
+
+[env:esp32]
+extends = common
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/51.03.05/platform-espressif32.zip
+board = esp32dev
+build_unflags = -std=gnu++11
+build_flags =
+    -std=gnu++14
+    -DSOC_WIFI_SUPPORTED=1
+    -I${platformio.packages_dir}/framework-arduinoespressif32/libraries/Network/src

examples/CustomPortalContent/CustomPortalContent.ino

@@ -0,0 +1,40 @@
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+WiFiManager portal;
+WiFiManagerParameter brokerHost("broker_host", "MQTT broker", "mqtt.local", 40);
+
+void setup() {
+    Serial.begin(115200);
+
+    portal.portalAddParameter(&brokerHost);
+
+    // WiFiManager copies this read-only status section when it is registered.
+    PortalInfoSection deviceInfo;
+    deviceInfo.id = "device";
+    deviceInfo.title = "Example device";
+    deviceInfo.items = {
+        {"firmware", "Firmware", "1.0.0"},
+        {"sensor", "Sensor", "Ready"},
+    };
+    portal.portalAddInfoSection(deviceInfo);
+
+    // This callout appears on the built-in portal overview.
+    PortalHomeCard hint;
+    hint.id = "hint";
+    hint.title = "What this example adds";
+    hint.kind = PortalHomeCardKind::Callout;
+    hint.text = "A normal text setting, a status section, and a home-page callout.";
+    portal.portalAddHomeCard(hint);
+
+    portal.setSaveParamsCallback([](WiFiManager::WiFiManagerRequestArgs) {
+        // A product validates and persists this value here; this demo only prints it.
+        Serial.print("MQTT broker selected: ");
+        Serial.println(brokerHost.getValue());
+    });
+    portal.setConfigPortalTimeout(180);
+
+    portal.autoConnect("WiFiManager Content", "example-pass");
+}
+
+void loop() { portal.process(); }

examples/CustomPortalContent/README.md

@@ -0,0 +1,13 @@
+# Custom Portal Content
+
+This example keeps WiFiManager’s portal navigation, validation, and captive behaviour, while adding three application-owned pieces of content:
+
+- an editable MQTT broker host field;
+- a compact device-information section;
+- a callout on the portal overview.
+
+It opens **WiFiManager Content** with password **example-pass** until it has working station credentials. Save the form, then inspect serial output to see the selected broker value.
+
+The parameter object is global because WiFiManager reads it for the lifetime of the portal. In a real application, copy the value into that application’s own validated persistent configuration inside the save callback.
+
+See [Portal content](../../docs/PORTAL_CONTENT.md), [product settings and Wi-Fi](../../docs/recipes/PRODUCT_SETTINGS_AND_WIFI.md), and the shared [example guide](../README.md).

examples/CustomPortalContent/platformio.ini

@@ -0,0 +1,26 @@
+[platformio]
+default_envs = esp8266
+src_dir = .
+
+[common]
+framework = arduino
+lib_ldf_mode = deep+
+lib_deps =
+    WiFiManager=symlink://../..
+
+[env:esp8266]
+extends = common
+platform = espressif8266
+board = d1_mini
+platform_packages =
+    platformio/framework-arduinoespressif8266 @ https://github.com/esp8266/Arduino.git#521ae60a89e64bb0d1eb7a0b7addf620ced5cad3
+
+[env:esp32]
+extends = common
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/51.03.05/platform-espressif32.zip
+board = esp32dev
+build_unflags = -std=gnu++11
+build_flags =
+    -std=gnu++14
+    -DSOC_WIFI_SUPPORTED=1
+    -I${platformio.packages_dir}/framework-arduinoespressif32/libraries/Network/src

examples/README.md

@@ -0,0 +1,29 @@
+# WiFiManager examples
+
+Every directory below is a standalone PlatformIO project. Build it from the repository root or the example directory:
+
+```bash
+pio run -d examples/BasicPortal -e esp8266
+pio run -d examples/BasicPortal -e esp8266 -t upload
+pio device monitor -d examples/BasicPortal -e esp8266
+```
+
+Choose `esp32` for an ESP32 development board. The examples use the checked-out WiFiManager source, so they are also useful while developing this fork.
+
+| Example | Start here when you want to… |
+| --- | --- |
+| [Basic Portal](BasicPortal/) | provision one board through the normal saved-network-or-portal flow |
+| [Custom Portal Content](CustomPortalContent/) | add application settings and useful status cards to the built-in portal |
+| [Branded Portal](BrandedPortal/) | change the portal’s identity, logo, and semantic visual theme |
+| [Station Profiles](StationProfiles/) | remember a primary Wi-Fi network and one fallback in application-owned EEPROM storage |
+
+The portal examples intentionally begin with no station credentials. On first boot, connect to the matching setup network and open `http://192.168.4.1/`.
+
+| Example | Setup network | Password |
+| --- | --- | --- |
+| Basic Portal | WiFiManager Basic | example-pass |
+| Custom Portal Content | WiFiManager Content | example-pass |
+| Branded Portal | Temperature Monitor | none |
+| Station Profiles | WiFiManager Profiles | example-pass |
+
+Back to the [project overview](../README.md).

examples/StationProfiles/README.md

@@ -0,0 +1,9 @@
+# Station Profiles
+
+This example gives WiFiManager a small application-owned EEPROM store. The portal accepts a required primary Wi-Fi network and an optional fallback, verifies a submitted network before saving it, then remembers the last successful choice across restarts.
+
+On a blank board, connect to **WiFiManager Profiles** with password **example-pass** and open `http://192.168.4.1/`. Enter a primary network and, if useful, one fallback. After a successful connection, restart the board to confirm that it tries the saved profiles before reopening the portal.
+
+`StoredProfiles` is intentionally simple so the ownership boundary is visible. A production application should add its own record versioning and integrity protection around the application’s complete configuration; WiFiManager only owns network-selection policy.
+
+See [Station profiles](../../docs/STATION_PROFILES.md), [primary and fallback Wi-Fi](../../docs/recipes/PRIMARY_AND_FALLBACK_WIFI.md), and the shared [example guide](../README.md).

examples/StationProfiles/StationProfiles.ino

@@ -0,0 +1,63 @@
+#include <Arduino.h>
+#include <EEPROM.h>
+#include <WiFiManager.h>
+
+namespace {
+constexpr uint32_t kStoreMagic = 0x574D5031;  // "WMP1"
+
+struct StoredProfiles {
+    uint32_t magic;
+    WiFiManagerStationProfiles profiles;
+};
+
+class EepromProfileStore final : public WiFiManagerStationProfileStore {
+public:
+    bool begin() {
+#if defined(ESP32)
+        return EEPROM.begin(sizeof(StoredProfiles));
+#else
+        EEPROM.begin(sizeof(StoredProfiles));
+        return true;
+#endif
+    }
+
+    bool load(WiFiManagerStationProfiles& profiles) override {
+        StoredProfiles stored{};
+        EEPROM.get(0, stored);
+        if (stored.magic != kStoreMagic) {
+            return false;
+        }
+        profiles = stored.profiles;
+        return true;
+    }
+
+    bool save(const WiFiManagerStationProfiles& profiles) override {
+        EEPROM.put(0, StoredProfiles{kStoreMagic, profiles});
+        return EEPROM.commit();
+    }
+
+    bool clear() override {
+        EEPROM.put(0, StoredProfiles{});
+        return EEPROM.commit();
+    }
+};
+
+EepromProfileStore profileStore;
+WiFiManager portal;
+}  // namespace
+
+void setup() {
+    Serial.begin(115200);
+    if (!profileStore.begin()) {
+        Serial.println("Could not initialise EEPROM profile storage");
+        return;
+    }
+
+    portal.setStationProfileStore(&profileStore);
+    portal.setStationRecoveryInterval(30000);
+    portal.startStationConnection("WiFiManager Profiles", "example-pass");
+}
+
+void loop() {
+    portal.process();
+}

examples/StationProfiles/platformio.ini

@@ -0,0 +1,26 @@
+[platformio]
+default_envs = esp8266
+src_dir = .
+
+[common]
+framework = arduino
+lib_ldf_mode = deep+
+lib_deps =
+    WiFiManager=symlink://../..
+
+[env:esp8266]
+extends = common
+platform = espressif8266
+board = d1_mini
+platform_packages =
+    platformio/framework-arduinoespressif8266 @ https://github.com/esp8266/Arduino.git#521ae60a89e64bb0d1eb7a0b7addf620ced5cad3
+
+[env:esp32]
+extends = common
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/51.03.05/platform-espressif32.zip
+board = esp32dev
+build_unflags = -std=gnu++11
+build_flags =
+    -std=gnu++14
+    -DSOC_WIFI_SUPPORTED=1
+    -I${platformio.packages_dir}/framework-arduinoespressif32/libraries/Network/src

lib/WiFiManager/include/WiFiManagerDfteLogger.h

@@ -0,0 +1,45 @@
+/**
+ * WiFiManagerDfteLogger.h
+ *
+ * @author alexhopeoconnor
+ * @license MIT
+ *
+ * Optional bridge from DFTE's logging hooks to WiFiManager::log.
+ * Enabled only when the sketch / library build defines WM_DFTE_LOGGING.
+ */
+
+#ifndef WiFiManagerDfteLogger_h
+#define WiFiManagerDfteLogger_h
+
+#if defined(ESP8266) || defined(ESP32)
+
+#include <DeviceFrameworkTemplateEngineDebug.h>
+#include "WiFiManager.h"
+
+/**
+ * Forwards DeviceFrameworkTemplateEngineLogger calls to WiFiManager logging
+ * with subsystem WM/DFTE.
+ */
+class WiFiManagerDfteLogger : public DeviceFrameworkTemplateEngineLogger {
+public:
+    explicit WiFiManagerDfteLogger(WiFiManager* wm) : _wm(wm) {}
+
+    void error(const String& msg) override { logLine(WiFiManagerLogLevel::Error, msg); }
+    void warn(const String& msg) override { logLine(WiFiManagerLogLevel::Warn, msg); }
+    void info(const String& msg) override { logLine(WiFiManagerLogLevel::Debug, msg); }
+    void debug(const String& msg) override { logLine(WiFiManagerLogLevel::Trace, msg); }
+
+private:
+    WiFiManager* _wm;
+
+    void logLine(WiFiManagerLogLevel level, const String& msg) {
+        if (!_wm) {
+            return;
+        }
+        _wm->log(level, "WM/DFTE", msg);
+    }
+};
+
+#endif // ESP8266 || ESP32
+
+#endif // WiFiManagerDfteLogger_h

lib/WiFiManager/include/WiFiManagerHandlers.h

@@ -0,0 +1,125 @@
+/**
+ * WiFiManagerHandlers.h
+ *
+ * HTTP request handlers for WiFiManager: single HTML shell + JSON APIs.
+ *
+ * @author alexhopeoconnor
+ * @license MIT
+ */
+
+#ifndef WiFiManagerHandlers_h
+#define WiFiManagerHandlers_h
+
+#if defined(ESP8266) || defined(ESP32)
+
+#include <ESPAsyncWebServer.h>
+#include <memory>
+#include "WiFiManager.h"
+
+#ifndef WM_TEMPLATE_REGISTRY_CAPACITY
+#define WM_TEMPLATE_REGISTRY_CAPACITY 16
+#endif
+
+// Portal UI customization is driven by WiFiManager `portal*` APIs and JSON (/api/...) — not by mutating template
+// placeholder registries.
+
+// -----------------------------------------------------------------------------------------------
+// FORM FIELD NAMES (for IP configuration forms)
+
+const char S_ip[]                 PROGMEM = "ip";
+const char S_gw[]                 PROGMEM = "gw";
+const char S_sn[]                 PROGMEM = "sn";
+const char S_dns[]                PROGMEM = "dns";
+
+// -----------------------------------------------------------------------------------------------
+// HTTP HEADERS
+
+const char HTTP_HEAD_CT[]         PROGMEM = "text/html";
+const char HTTP_HEAD_CT2[]        PROGMEM = "text/plain";
+const char HTTP_HEAD_CORS[]       PROGMEM = "Access-Control-Allow-Origin";
+const char HTTP_HEAD_CORS_ALLOW_ALL[]  PROGMEM = "*";
+
+class WiFiManagerHandlers {
+  public:
+    WiFiManagerHandlers(WiFiManager* wm);
+
+    void handleRoot(AsyncWebServerRequest *request);
+    void handleNotFound(AsyncWebServerRequest *request);
+    void handleRequest(AsyncWebServerRequest *request);
+    void handleUpdating(AsyncWebServerRequest *request, String filename, size_t index, uint8_t *data, size_t len, bool final);
+    void handleUpdateDone(AsyncWebServerRequest *request);
+
+    void handleApiBootstrap(AsyncWebServerRequest *request);
+    void handleApiWifiScanStatus(AsyncWebServerRequest *request);
+    void handleApiWifiScan(AsyncWebServerRequest *request);
+    void handleApiWifiMeta(AsyncWebServerRequest *request);
+    void handleApiWifiSave(AsyncWebServerRequest *request);
+    void handleApiWifiConnectStatus(AsyncWebServerRequest *request);
+    void handleApiWifiConnectComplete(AsyncWebServerRequest *request);
+    void handleApiPortalTimeoutReset(AsyncWebServerRequest *request);
+    void handleApiParamsGet(AsyncWebServerRequest *request);
+    void handleApiParamsSave(AsyncWebServerRequest *request);
+    void handleApiInfo(AsyncWebServerRequest *request);
+    void handleApiStatus(AsyncWebServerRequest *request);
+    void handleApiDeviceRestart(AsyncWebServerRequest *request);
+    void handleApiDeviceErase(AsyncWebServerRequest *request, boolean optionalErase = false);
+    void handleApiPortalClose(AsyncWebServerRequest *request);
+    void handleApiPortalExit(AsyncWebServerRequest *request);
+
+    boolean captivePortal(AsyncWebServerRequest *request);
+    void stopCaptivePortal();
+
+    /** True when the HTTP Host header does not match the portal’s canonical host:port (captive redirect needed). */
+    static bool shouldRedirectCaptiveForHost(const String& requestHost, const String& serverLocWithPort);
+
+    void doParamSave(WiFiManager::WiFiManagerRequestArgs requestArgs);
+
+    /** Portal bootstrap JSON (same payload as GET /api/bootstrap). Public for tests and host integration. */
+    String buildPortalBootstrapJson();
+    /** Same JSON body as GET /api/wifi/meta (tests + embedding). */
+    String buildApiWifiMetaJson();
+    /** Same JSON body as GET /api/info (tests + embedding). */
+    String buildApiInfoJson();
+    /** Same JSON body as GET /api/params (tests + embedding). */
+    String buildApiParamsGetJson();
+    /** Same JSON body as GET /api/status (tests + embedding). */
+    String buildApiStatusJson();
+    /** GET /api/wifi/connect-status (portal connect progress). */
+    String buildApiWifiConnectStatusJson();
+
+    /** Fixed JSON bodies for POST action endpoints (single source for handlers + tests). */
+    static String jsonApiWifiScanAccepted();
+    static String jsonApiDeviceRestartScheduled();
+    static String jsonApiParamsSaveOk();
+    static String jsonApiPortalCloseOk();
+    static String jsonApiPortalExitOk();
+    static String jsonApiPortalExitForbidden();
+    static String jsonApiOtaUpdateSuccess();
+    static String jsonApiEraseResponse(boolean success);
+
+  private:
+    WiFiManager* _wm;
+    void collectVisibleScanResults(std::vector<const WiFiManager::WiFiScanNetwork*>& networks);
+    void appendVisibleScanResultsJson(String& json, const std::vector<const WiFiManager::WiFiScanNetwork*>& networks);
+
+    void applyWifiAndParamsFromRequest(AsyncWebServerRequest *request);
+    bool buildStationProfilesFromRequest(AsyncWebServerRequest *request, WiFiManagerStationProfiles& profiles);
+    void buildPlainStatusSummary(String& out);
+    void appendPortalJsonStaticFields(String& json, bool& first);
+    void appendPortalJsonCustomParams(String& json, bool& first);
+
+    void appendPortalExtraInfoSectionsJson(String& json, bool& first);
+    void appendPortalExtraHomeCardsJson(String& json, bool& first);
+
+    void appendJsonKvItem(String& json, bool& first, const char* key, const String& label, const String& value);
+    void appendOneInfoItemForId(String& json, bool& first, const char* id);
+    void appendInfoSectionFromIds(String& json, const char* const* ids, size_t count, bool& first);
+
+    void appendApiInfoActionsJson(String& json);
+
+    static void sendApiJson(AsyncWebServerRequest *request, int code, const String& json);
+};
+
+#endif // defined(ESP8266) || defined(ESP32)
+
+#endif // WiFiManagerHandlers_h

lib/WiFiManager/include/WiFiManagerLogLevel.h

@@ -0,0 +1,35 @@
+/**
+ * WiFiManagerLogLevel.h
+ *
+ * @author alexhopeoconnor
+ * @license MIT
+ *
+ * Compile-time and runtime log levels for WiFiManager. Higher numeric values
+ * mean more verbose output. Matches the old 0..5 tier model for build flags.
+ */
+
+#ifndef WiFiManagerLogLevel_h
+#define WiFiManagerLogLevel_h
+
+#include <Arduino.h>
+
+/** Default subsystem tag for core WiFiManager messages (macro for C++11 embedded toolchains). */
+#define kWiFiMgrLogSubsystem "WM"
+
+enum class WiFiManagerLogLevel : uint8_t {
+    Silent = 0,
+    Error = 1,
+    Warn = 2,
+    Info = 3,
+    Debug = 4,
+    Trace = 5,
+};
+
+/** Full line delivered to Print or WiFiManagerLogSink (prefix and tags included). */
+struct WiFiManagerLogMessage {
+    WiFiManagerLogLevel level;
+    const char* subsystem;
+    String line;
+};
+
+#endif

lib/WiFiManager/include/WiFiManagerLogSink.h

@@ -0,0 +1,22 @@
+/**
+ * WiFiManagerLogSink.h
+ *
+ * @author alexhopeoconnor
+ * @license MIT
+ *
+ * Optional host-provided sink for WiFiManager log output. When set, logs are
+ * delivered here instead of the configured Print stream (usually Serial).
+ */
+
+#ifndef WiFiManagerLogSink_h
+#define WiFiManagerLogSink_h
+
+#include "WiFiManagerLogLevel.h"
+
+class WiFiManagerLogSink {
+public:
+    virtual void log(const WiFiManagerLogMessage& msg) = 0;
+    virtual ~WiFiManagerLogSink() = default;
+};
+
+#endif

lib/WiFiManager/include/WiFiManagerLogTemplates.h

@@ -0,0 +1,48 @@
+/**
+ * WiFiManagerLogTemplates.h
+ *
+ * @author alexhopeoconnor
+ * @license MIT
+ *
+ * Template implementations for WiFiManager::log(...). Included at the end of WiFiManager.h.
+ */
+
+#ifndef WiFiManagerLogTemplates_h
+#define WiFiManagerLogTemplates_h
+
+#include "WiFiManagerLogLevel.h"
+#include <IPAddress.h>
+#include <WString.h>
+
+#if defined(ESP8266) || defined(ESP32)
+
+inline String wmLogStringifyArg(const __FlashStringHelper* v) {
+    return String(v);
+}
+
+inline String wmLogStringifyArg(const IPAddress& v) {
+    return v.toString();
+}
+
+template<typename T>
+inline String wmLogStringifyArg(const T& v) {
+    return String(v);
+}
+
+template<typename T>
+inline void WiFiManager::log(WiFiManagerLogLevel level, const char* subsystem, T&& text) {
+#ifndef WM_NO_LOG
+    emitLogImpl(level, subsystem, wmLogStringifyArg(text), String());
+#endif
+}
+
+template<typename T, typename U>
+inline void WiFiManager::log(WiFiManagerLogLevel level, const char* subsystem, T&& a, U&& b) {
+#ifndef WM_NO_LOG
+    emitLogImpl(level, subsystem, wmLogStringifyArg(a), wmLogStringifyArg(b));
+#endif
+}
+
+#endif // ESP8266 || ESP32
+
+#endif // WiFiManagerLogTemplates_h

lib/WiFiManager/include/WiFiManagerParameter.h

@@ -0,0 +1,64 @@
+/**
+ * WiFiManagerParameter.h
+ *
+ * @author alexhopeoconnor
+ * @license MIT
+ */
+
+#ifndef WiFiManagerParameter_h
+#define WiFiManagerParameter_h
+
+#include <Arduino.h>
+
+class WiFiManager;
+
+#ifndef WIFI_MANAGER_MAX_PARAMS
+    #define WIFI_MANAGER_MAX_PARAMS 5 // params will autoincrement and realloc by this amount when max is reached
+#endif
+
+#define WFM_LABEL_BEFORE 1
+#define WFM_LABEL_AFTER 2
+#define WFM_NO_LABEL 0
+#define WFM_LABEL_DEFAULT 1
+
+class WiFiManagerParameter {
+  public:
+    /**
+        Create custom parameters that can be added to the WiFiManager setup web page
+        @id is used for HTTP queries and must not contain spaces nor other special characters
+    */
+    WiFiManagerParameter();
+    explicit WiFiManagerParameter(const char *custom);
+    WiFiManagerParameter(const char *id, const char *label);
+    WiFiManagerParameter(const char *id, const char *label, const char *defaultValue, int length);
+    WiFiManagerParameter(const char *id, const char *label, const char *defaultValue, int length, const char *custom);
+    WiFiManagerParameter(const char *id, const char *label, const char *defaultValue, int length, const char *custom, int labelPlacement);
+    virtual ~WiFiManagerParameter();
+
+    WiFiManagerParameter(const WiFiManagerParameter&) = delete;
+    WiFiManagerParameter& operator=(const WiFiManagerParameter&) = delete;
+
+    const char *getID() const;
+    const char *getValue() const;
+    const char *getLabel() const;
+    const char *getPlaceholder() const; // @deprecated, use getLabel
+    int         getValueLength() const;
+    int         getLabelPlacement() const;
+    virtual const char *getCustomHTML() const;
+    void        setValue(const char *defaultValue, int length);
+
+  protected:
+    void init(const char *id, const char *label, const char *defaultValue, int length, const char *custom, int labelPlacement);
+
+    const char *_id;
+    const char *_label;
+    char       *_value;
+    int         _length;
+    int         _labelPlacement;
+
+    const char *_customHTML;
+    friend class WiFiManager;
+};
+
+#endif // WiFiManagerParameter_h
+

lib/WiFiManager/include/WiFiManagerPortalUI.h

@@ -0,0 +1,93 @@
+/**
+ * WiFiManagerPortalUI.h
+ *
+ * Deliberate, portal-specific presentation configuration. This header does
+ * not depend on DeviceFramework: WiFiManager remains useful on its own.
+ */
+
+#ifndef WIFI_MANAGER_PORTAL_UI_H
+#define WIFI_MANAGER_PORTAL_UI_H
+
+#include <Arduino.h>
+
+enum class WiFiManagerPortalStorage : uint8_t {
+  Ram,
+  Progmem,
+};
+
+/** Non-owning static text. The caller retains the data for the firmware lifetime. */
+struct WiFiManagerPortalText {
+  const char* data = nullptr;
+  WiFiManagerPortalStorage storage = WiFiManagerPortalStorage::Ram;
+
+  static constexpr WiFiManagerPortalText ram(const char* value) {
+    return {value, WiFiManagerPortalStorage::Ram};
+  }
+  static constexpr WiFiManagerPortalText progmem(const char* value) {
+    return {value, WiFiManagerPortalStorage::Progmem};
+  }
+
+  bool empty() const { return data == nullptr || length() == 0; }
+  size_t length() const {
+    return data == nullptr ? 0 : (storage == WiFiManagerPortalStorage::Progmem ? strlen_P(data) : strlen(data));
+  }
+  char at(size_t index) const {
+    return storage == WiFiManagerPortalStorage::Progmem
+      ? static_cast<char>(pgm_read_byte(data + index))
+      : data[index];
+  }
+};
+
+/** Optional inline SVG branding asset. It is not a general HTML extension point. */
+struct WiFiManagerPortalAsset {
+  WiFiManagerPortalText svg;
+
+  static constexpr WiFiManagerPortalAsset svgFromRam(const char* value) {
+    return {WiFiManagerPortalText::ram(value)};
+  }
+  static constexpr WiFiManagerPortalAsset svgFromProgmem(const char* value) {
+    return {WiFiManagerPortalText::progmem(value)};
+  }
+
+  bool empty() const { return svg.empty(); }
+};
+
+/**
+ * Semantic colour and shape values for WiFiManager's built-in portal.
+ *
+ * Leave a value empty to retain the built-in stylesheet value. Values are
+ * validated before they are emitted into the portal stylesheet; they are not
+ * a general CSS injection mechanism.
+ */
+struct WiFiManagerPortalTheme {
+  WiFiManagerPortalText pageBackground;
+  WiFiManagerPortalText surface;
+  WiFiManagerPortalText text;
+  WiFiManagerPortalText mutedText;
+  WiFiManagerPortalText border;
+  WiFiManagerPortalText accent;
+  WiFiManagerPortalText accentHover;
+  WiFiManagerPortalText accentText;
+  WiFiManagerPortalText danger;
+  WiFiManagerPortalText dangerHover;
+  WiFiManagerPortalText success;
+  uint8_t cornerRadiusPx = 0;
+  uint8_t smallCornerRadiusPx = 0;
+};
+
+/**
+ * Complete setup-time presentation configuration for WiFiManager's portal.
+ *
+ * Text and SVG assets are non-owning static data in RAM or PROGMEM. Apply this
+ * before starting a portal; asynchronous portal responses use immutable state.
+ */
+struct WiFiManagerPortalConfig {
+  WiFiManagerPortalText title;
+  WiFiManagerPortalText identityText;
+  WiFiManagerPortalText tagline;
+  WiFiManagerPortalAsset logo;
+  WiFiManagerPortalText logoAltText;
+  WiFiManagerPortalTheme theme;
+};
+
+#endif  // WIFI_MANAGER_PORTAL_UI_H

lib/WiFiManager/include/WiFiManagerServer.h

@@ -0,0 +1,100 @@
+/**
+ * WiFiManagerServer.h
+ *
+ * @author alexhopeoconnor
+ * @license MIT
+ *
+ * HTTP server for the config portal: single HTML shell (GET /), JSON under /api/..., OTA POST /u,
+ * captive-portal redirects, and 404 handling. No legacy page routes.
+ *
+ * Supported surface (authoritative; registerRoutes mirrors this):
+ *   GET  /
+ *   GET  /api/bootstrap
+ *   GET  /api/wifi/scan-status
+ *   POST /api/wifi/scan
+ *   GET  /api/wifi/meta
+ *   POST /api/wifi/save
+ *   GET  /api/wifi/connect-status
+ *   POST /api/wifi/connect-complete
+ *   POST /api/portal/timeout-reset
+ *   GET  /api/params
+ *   POST /api/params/save
+ *   GET  /api/info
+ *   GET  /api/status
+ *   POST /api/device/restart
+ *   POST /api/device/erase
+ *   POST /api/portal/close
+ *   POST /api/portal/exit
+ *   POST /u                      (multipart firmware upload; JSON completion response)
+ *   notFound -> captive redirect or 404
+ */
+
+#ifndef WiFiManagerServer_h
+#define WiFiManagerServer_h
+
+#if defined(ESP8266) || defined(ESP32)
+
+#include <ESPAsyncWebServer.h>
+#include <DNSServer.h>
+#include <functional>
+#include <memory>
+
+class WiFiManager;
+class WiFiManagerHandlers;
+
+#ifdef WM_DFTE_LOGGING
+class WiFiManagerDfteLogger;
+#endif
+
+// -----------------------------------------------------------------------------------------------
+// HTTP routes (portal API only; no legacy /wifi, /info, … page URLs)
+
+const char R_root[]               PROGMEM = "/";
+
+const char R_api_bootstrap[]      PROGMEM = "/api/bootstrap";
+const char R_api_wifi_scan_status[] PROGMEM = "/api/wifi/scan-status";
+const char R_api_wifi_scan[]      PROGMEM = "/api/wifi/scan";
+const char R_api_wifi_meta[]      PROGMEM = "/api/wifi/meta";
+const char R_api_wifi_save[]      PROGMEM = "/api/wifi/save";
+const char R_api_wifi_connect_status[] PROGMEM = "/api/wifi/connect-status";
+const char R_api_wifi_connect_complete[] PROGMEM = "/api/wifi/connect-complete";
+const char R_api_portal_timeout_reset[] PROGMEM = "/api/portal/timeout-reset";
+const char R_api_params[]         PROGMEM = "/api/params";
+const char R_api_params_save[]    PROGMEM = "/api/params/save";
+const char R_api_info[]           PROGMEM = "/api/info";
+const char R_api_status[]         PROGMEM = "/api/status";
+const char R_api_device_restart[] PROGMEM = "/api/device/restart";
+const char R_api_device_erase[]   PROGMEM = "/api/device/erase";
+const char R_api_portal_close[]   PROGMEM = "/api/portal/close";
+const char R_api_portal_exit[]    PROGMEM = "/api/portal/exit";
+
+const char R_updatedone[]         PROGMEM = "/u";
+
+class WiFiManagerServer {
+  public:
+    WiFiManagerServer(WiFiManager* wm);
+    ~WiFiManagerServer();
+
+    void createServer(uint16_t port);
+    void registerRoutes();
+    void setupDNSD();
+    void processDNS();
+    void shutdownServer();
+    AsyncWebServer* getServer() { return server.get(); }
+    DNSServer* getDNSServer() { return dnsServer.get(); }
+
+  private:
+    WiFiManager* _wm;
+    std::unique_ptr<WiFiManagerHandlers> _handlers;
+    std::unique_ptr<AsyncWebServer> server;
+    std::unique_ptr<DNSServer> dnsServer;
+
+#ifdef WM_DFTE_LOGGING
+    std::unique_ptr<WiFiManagerDfteLogger> _dfteLogger;
+    bool _wmOwnsDfteLogSink = false;
+#endif
+};
+
+#endif // defined(ESP8266) || defined(ESP32)
+
+#endif // WiFiManagerServer_h

lib/WiFiManager/include/WiFiManagerUtils.h

@@ -0,0 +1,106 @@
+/**
+ * WiFiManagerUtils.h
+ * Pure utility functions for WiFiManager
+ * String conversions, HTML encoding, and helper calculations
+ * These functions have no dependency on WiFiManager instance state
+ *
+ * @author alexhopeoconnor
+ * @license MIT
+ */
+
+#ifndef _WIFI_MANAGER_UTILS_H_
+#define _WIFI_MANAGER_UTILS_H_
+
+#include <Arduino.h>
+
+// Forward declaration
+class IPAddress;
+
+namespace WiFiManagerUtils {
+
+// -----------------------------------------------------------------------------------------------
+// WIFI STATUS ARRAYS (for status string conversion)
+
+extern const char * const WIFI_STA_STATUS[] PROGMEM;
+extern const char * const WIFI_MODES[] PROGMEM;
+
+#ifdef ESP32
+extern const char * const AUTH_MODE_NAMES[] PROGMEM;
+#elif defined(ESP8266)
+extern const char * const AUTH_MODE_NAMES[] PROGMEM;
+#endif
+
+// -----------------------------------------------------------------------------------------------
+// STRING CONVERSION UTILITIES
+
+/**
+ * Convert WiFi status code to readable string
+ * @param status WiFi status code
+ * @return Status string or "Unknown" if invalid
+ */
+String getStatusString(uint8_t status);
+
+
+/**
+ * Convert WiFi mode code to readable string
+ * @param mode WiFi mode code
+ * @return Mode string or "Unknown" if invalid
+ */
+String getModeString(uint8_t mode);
+
+/**
+ * Convert encryption/auth mode to readable string
+ * @param authmode Encryption type code
+ * @return Encryption type string
+ */
+String getEncryptionString(uint8_t authmode);
+
+// -----------------------------------------------------------------------------------------------
+// HTML UTILITIES
+
+/**
+ * Encode HTML entities in a string
+ * @param str String to encode
+ * @param whitespace If true, also encode spaces as &#160;
+ * @return Encoded string
+ */
+String htmlEntities(const String& str, bool whitespace = false);
+
+// -----------------------------------------------------------------------------------------------
+// IP/STRING UTILITIES
+
+/**
+ * Check if string is a valid IP address
+ * @param str String to check
+ * @return true if valid IP address
+ */
+bool isValidIP(const String& str);
+
+/**
+ * Convert IPAddress to String
+ * @param ip IPAddress to convert
+ * @return IP address string
+ */
+String ipToString(IPAddress ip);
+
+/**
+ * Validate AP password format (8-63 characters)
+ * @param password Password to validate
+ * @return true if valid
+ */
+bool isValidAPPassword(const String& password);
+
+// -----------------------------------------------------------------------------------------------
+// HELPER CALCULATIONS
+
+/**
+ * Convert RSSI value to quality percentage (0-100)
+ * @param rssi RSSI value in dBm
+ * @return Quality percentage (0-100)
+ */
+int rssiToQuality(int rssi);
+
+} // namespace WiFiManagerUtils
+
+#endif // _WIFI_MANAGER_UTILS_H_
+

lib/WiFiManager/include/templates/CSS.h

@@ -0,0 +1,233 @@
+/**
+ * CSS.h
+ *
+ * @author alexhopeoconnor
+ * @license MIT
+ *
+ * CSS stylesheet for WiFiManager web interface.
+ * Embedded styles to avoid external file dependencies.
+ */
+
+#ifndef _CSS_TEMPLATES_H_
+#define _CSS_TEMPLATES_H_
+
+#include <Arduino.h>
+
+const char CSS_STYLE[] PROGMEM = "<style>"
+/* Design tokens */
+":root{"
+"--wm-bg:#f0f4f8;"
+"--wm-surface:#ffffff;"
+"--wm-text:#0f172a;"
+"--wm-muted:#64748b;"
+"--wm-border:#e2e8f0;"
+"--wm-brand:#0ea5e9;"
+"--wm-brand-hover:#0284c7;"
+"--wm-brand-text:#ffffff;"
+"--wm-danger:#dc2626;"
+"--wm-danger-hover:#b91c1c;"
+"--wm-success:#16a34a;"
+"--wm-radius:12px;"
+"--wm-radius-sm:8px;"
+"--wm-shadow:0 1px 3px rgba(15,23,42,.08),0 4px 16px rgba(15,23,42,.06);"
+"--wm-font:system-ui,-apple-system,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif;"
+"}"
+"body.invert{"
+"--wm-bg:#0c1222;"
+"--wm-surface:#151d2e;"
+"--wm-text:#f1f5f9;"
+"--wm-muted:#94a3b8;"
+"--wm-border:#334155;"
+"--wm-brand:#38bdf8;"
+"--wm-brand-hover:#7dd3fc;"
+"--wm-danger:#f87171;"
+"--wm-danger-hover:#fca5a5;"
+"--wm-success:#4ade80;"
+"--wm-shadow:0 4px 24px rgba(0,0,0,.45);"
+"}"
+/* Base */
+"*,*::before,*::after{box-sizing:border-box}"
+"body.portal{margin:0;min-height:100vh;background:var(--wm-bg);color:var(--wm-text);"
+"font-family:var(--wm-font);font-size:16px;line-height:1.5;-webkit-text-size-adjust:100%;text-align:left}"
+"a{color:var(--wm-brand);font-weight:600;text-decoration:none}"
+"a:hover{color:var(--wm-brand-hover);text-decoration:underline}"
+/* Layout shell */
+".wm-layout{width:100%;max-width:420px;margin:0 auto;padding:16px 18px 28px;}"
+"h1,h2,h3{margin:0 0 .35em;font-weight:700;letter-spacing:-.02em}"
+"h1{font-size:1.5rem}"
+"h2{font-size:1.15rem}"
+"h3{font-size:1rem}"
+"p{margin:.5em 0}"
+/* Top navigation — single row; overflow scrollable but scrollbar hidden (touch still pans) */
+".wm-nav{display:flex;flex-wrap:nowrap;align-items:stretch;gap:4px;margin:0 0 20px;padding:4px 6px;"
+"overflow-x:auto;-webkit-overflow-scrolling:touch;scrollbar-width:none;-ms-overflow-style:none;"
+"background:var(--wm-surface);border-radius:var(--wm-radius);box-shadow:var(--wm-shadow);border:1px solid var(--wm-border)}"
+".wm-nav::-webkit-scrollbar{display:none;width:0;height:0}"
+".wm-nav-link{display:inline-flex;align-items:center;justify-content:center;flex:0 0 auto;padding:6px 8px;border-radius:var(--wm-radius-sm);"
+"font-size:.8rem;font-weight:600;color:var(--wm-muted);text-decoration:none;border:1px solid transparent;white-space:nowrap}"
+".wm-nav-link:hover{color:var(--wm-brand);background:rgba(14,165,233,.08);text-decoration:none}"
+"body.invert .wm-nav-link:hover{background:rgba(56,189,248,.12)}"
+".wm-nav-link--active{color:var(--wm-text);background:rgba(14,165,233,.15);border-color:rgba(14,165,233,.35)}"
+"body.invert .wm-nav-link--active{background:rgba(56,189,248,.2);border-color:rgba(56,189,248,.4)}"
+".wm-nav .wm-icon-label{gap:4px}"
+".wm-nav .wm-icon{width:.95rem;height:.95rem;flex:0 0 .95rem}"
+".wm-icon-label{display:inline-flex;align-items:center;gap:8px;min-width:0}"
+".wm-icon{display:inline-flex;align-items:center;justify-content:center;width:1.1rem;height:1.1rem;flex:0 0 1.1rem;color:currentColor}"
+".wm-icon svg{display:block;width:100%;height:100%}"
+/* Header / page chrome */
+".wm-site-header{display:flex;align-items:center;gap:10px;min-height:40px;margin:0 0 12px}"
+".wm-site-logo{display:flex;align-items:center;justify-content:center;width:40px;height:40px;flex:0 0 40px;line-height:0}"
+".wm-site-logo svg{display:block;width:100%;height:100%}"
+".wm-site-brand-copy{min-width:0}"
+".wm-site-brand-name{margin:0;font-size:.78rem;font-weight:800;letter-spacing:.09em;text-transform:uppercase;color:var(--wm-text)}"
+".wm-site-tagline{margin:2px 0 0;font-size:.82rem;line-height:1.25;color:var(--wm-muted)}"
+".wm-page-head{margin-bottom:16px}"
+".wm-page-head h1{font-size:1.45rem}"
+".wm-page-desc{font-size:.95rem;color:var(--wm-muted);margin:.35em 0 0}"
+/* Cards */
+".wm-card{background:var(--wm-surface);border:1px solid var(--wm-border);border-radius:var(--wm-radius);"
+"box-shadow:var(--wm-shadow);padding:18px 16px;margin-bottom:16px;text-align:left}"
+".wm-scan-card,.wm-ota-card{position:relative;overflow:hidden}"
+".wm-scan-results{min-height:126px}"
+".wm-card-title{font-size:1rem;margin:0 0 12px;padding-bottom:10px;border-bottom:1px solid var(--wm-border);"
+"color:var(--wm-text)}"
+".wm-card-subtitle{margin:-4px 0 12px;font-size:.9rem;line-height:1.45;color:var(--wm-muted)}"
+".wm-lead{margin:0 0 8px;font-size:.95rem;color:var(--wm-muted);line-height:1.5}"
+".wm-home-summary{margin:0 0 14px;font-size:1rem;font-weight:600;line-height:1.45;color:var(--wm-text)}"
+/* Callout / status */
+".wm-callout{padding:12px 14px;border-radius:var(--wm-radius-sm);border:1px solid var(--wm-border);"
+"background:rgba(14,165,233,.06);margin-bottom:16px}"
+"body.invert .wm-callout{background:rgba(56,189,248,.08)}"
+".wm-callout--info{border-left:4px solid var(--wm-brand)}"
+".wm-info-summary{font-weight:600;color:var(--wm-text)}"
+".wm-status{margin:0 0 12px;padding:10px 12px;font-size:.92rem;font-weight:700;color:var(--wm-brand);"
+"text-align:center;border-radius:var(--wm-radius-sm);background:rgba(14,165,233,.08);border:1px solid rgba(14,165,233,.18)}"
+".wm-status--warning{color:#c2410c;background:rgba(249,115,22,.12);border-color:rgba(249,115,22,.28)}"
+".wm-status--caution{color:#a16207;background:rgba(234,179,8,.14);border-color:rgba(234,179,8,.3)}"
+".wm-status--danger{color:var(--wm-danger);background:rgba(220,38,38,.12);border-color:rgba(220,38,38,.28)}"
+"body.invert .wm-status{background:rgba(56,189,248,.12);border-color:rgba(56,189,248,.22)}"
+"body.invert .wm-status--warning{background:rgba(249,115,22,.18);border-color:rgba(249,115,22,.34)}"
+"body.invert .wm-status--caution{background:rgba(234,179,8,.18);border-color:rgba(234,179,8,.34)}"
+"body.invert .wm-status--danger{background:rgba(220,38,38,.18);border-color:rgba(220,38,38,.34)}"
+/* Form fields */
+".wm-field{margin-bottom:14px;text-align:left}"
+".wm-field:last-child{margin-bottom:0}"
+".wm-field label{display:block;font-size:.82rem;font-weight:600;color:var(--wm-muted);margin-bottom:6px}"
+"input[type=text],input[type=password],input[type=number],input[type=email],select{"
+"display:block;width:100%;padding:12px 14px;font-size:1rem;font-family:inherit;"
+"color:var(--wm-text);background:var(--wm-bg);border:1px solid var(--wm-border);border-radius:var(--wm-radius-sm);"
+"-webkit-appearance:none;appearance:none}"
+"input:focus,select:focus{outline:2px solid var(--wm-brand);outline-offset:0;border-color:var(--wm-brand)}"
+"input[type=radio],input[type=checkbox]{width:auto;margin-right:8px;accent-color:var(--wm-brand)}"
+".wm-checkbox-row{display:flex;align-items:center;gap:8px;margin:12px 0;font-size:.92rem}"
+".wm-checkbox-row label{display:inline;margin:0;font-weight:500;color:var(--wm-text)}"
+".wm-form-actions{margin-top:16px}"
+".wm-wifi-details-card{position:relative}"
+".wm-wifi-save-overlay{position:fixed;inset:0;z-index:10002;display:none;align-items:center;justify-content:center;padding:18px;"
+"box-sizing:border-box;background:rgba(15,23,42,.58)}"
+".wm-wifi-save-panel{display:flex;align-items:center;gap:14px;width:100%;max-width:340px;padding:18px;border:1px solid var(--wm-border);"
+"border-radius:var(--wm-radius-sm);background:var(--wm-surface);box-shadow:var(--wm-shadow);text-align:left}"
+".wm-wifi-save-panel strong{display:block;font-size:1rem;color:var(--wm-text)}"
+".wm-wifi-save-panel p{margin:4px 0 0;font-size:.9rem;line-height:1.45;color:var(--wm-muted)}"
+".wm-operation-overlay{position:absolute;inset:0;z-index:5;display:none;align-items:center;justify-content:center;padding:16px;background:rgba(15,23,42,.56)}"
+".wm-operation-panel{display:flex;align-items:center;gap:12px;width:100%;max-width:310px;padding:16px;border:1px solid var(--wm-border);border-radius:var(--wm-radius-sm);background:var(--wm-surface);box-shadow:var(--wm-shadow);text-align:left}"
+".wm-operation-panel strong{display:block;font-size:.98rem;color:var(--wm-text)}"
+".wm-operation-panel p{margin:3px 0 0;font-size:.88rem;line-height:1.4;color:var(--wm-muted)}"
+".wm-operation-progress{margin-top:10px}"
+".wm-operation-progress-track{height:7px;overflow:hidden;border-radius:999px;background:var(--wm-border)}"
+".wm-operation-progress-track span{display:block;width:0;height:100%;border-radius:inherit;background:var(--wm-brand);transition:width .15s ease}"
+".wm-operation-progress-label{display:block;margin-top:4px;font-size:.8rem;font-weight:700;color:var(--wm-muted);text-align:right}"
+".wm-portal-timeout-row{display:flex;align-items:stretch;gap:8px;margin:0 0 12px}"
+".wm-portal-timeout-row .wm-status{flex:1;margin:0}"
+".wm-icon-button{display:inline-flex;align-items:center;justify-content:center;width:42px;min-height:42px;padding:0;border:1px solid var(--wm-border);border-radius:var(--wm-radius-sm);background:var(--wm-bg);color:var(--wm-text);cursor:pointer}"
+".wm-icon-button:hover{border-color:var(--wm-brand);color:var(--wm-brand)}"
+".wm-icon-button:disabled{opacity:.5;cursor:not-allowed}"
+".wm-icon-button .wm-icon{width:1.05rem;height:1.05rem}"
+".wm-inline-link{display:inline-block;margin-top:12px;font-size:.92rem}"
+".wm-spinner{width:24px;height:24px;flex:0 0 24px;border:3px solid var(--wm-border);border-top-color:var(--wm-brand);border-radius:50%;animation:wm-spin .8s linear infinite}"
+"@keyframes wm-spin{to{transform:rotate(360deg)}}"
+"@media (prefers-reduced-motion:reduce){.wm-spinner{animation:none;border-right-color:var(--wm-brand)}}"
+/* Buttons */
+".wm-btn{display:inline-flex;align-items:center;justify-content:center;min-height:44px;padding:0 18px;"
+"font-size:1rem;font-weight:600;font-family:inherit;border-radius:var(--wm-radius-sm);border:0;cursor:pointer;"
+"transition:background .15s,transform .1s,opacity .15s}"
+".wm-btn:disabled{opacity:.5;cursor:not-allowed}"
+".wm-btn:active{transform:scale(.98)}"
+"a.wm-btn{box-sizing:border-box;text-decoration:none}"
+".wm-btn .wm-icon-label{justify-content:center}"
+".wm-btn--block{width:100%}"
+".wm-btn--primary{background:var(--wm-brand);color:var(--wm-brand-text)}"
+".wm-btn--primary:hover{background:var(--wm-brand-hover)}"
+".wm-btn--secondary{background:var(--wm-bg);color:var(--wm-text);border:1px solid var(--wm-border)}"
+".wm-btn--secondary:hover{border-color:var(--wm-brand);color:var(--wm-brand)}"
+".wm-btn--danger{background:var(--wm-danger);color:var(--wm-brand-text)}"
+".wm-btn--danger:hover{background:var(--wm-danger-hover)}"
+"input[type=file]{width:100%;padding:10px;border:1px dashed var(--wm-border);border-radius:var(--wm-radius-sm);"
+"background:var(--wm-bg);font-size:.9rem}"
+/* Legacy: unclassed submit in forms */
+"button[type=submit],.wm-form-actions .wm-btn--primary{background:var(--wm-brand);color:var(--wm-brand-text)}"
+"button[type=submit]:hover{background:var(--wm-brand-hover)}"
+/* Device actions / button stack */
+".wm-actions-stack{display:flex;flex-direction:column;gap:10px;margin-top:4px}"
+".wm-btn-group{display:flex;flex-direction:column;gap:10px}"
+/* WiFi scan list */
+".wm-scan-list{margin:0 0 12px;border:1px solid var(--wm-border);border-radius:var(--wm-radius-sm);"
+"overflow:hidden;background:var(--wm-bg)}"
+".wm-scan-row{display:flex;align-items:center;gap:10px;min-height:48px;padding:10px 12px;"
+"border-bottom:1px solid var(--wm-border);text-decoration:none;color:inherit;cursor:pointer}"
+".wm-scan-row:last-child{border-bottom:0}"
+".wm-scan-row:hover{background:rgba(14,165,233,.1)}"
+"body.invert .wm-scan-row:hover{background:rgba(56,189,248,.12)}"
+".wm-scan-ssid{flex:1;min-width:0;font-weight:600;font-size:.95rem;text-align:left;word-break:break-word}"
+".wm-scan-meta{display:flex;align-items:center;justify-content:flex-end;gap:6px;flex-shrink:0;min-width:78px}"
+".wm-scan-signal{display:block;flex-shrink:0;font-size:.8rem;color:var(--wm-muted);font-weight:600;min-width:38px;text-align:right}"
+".wm-scan-lock,.wm-scan-bars{display:block;flex:0 0 16px}"
+// quality icons
+".q{position:relative;height:16px;width:16px;margin:0;padding:0;flex-shrink:0}.q.q-0:after{background-position-x:0}.q.q-1:after{background-position-x:-16px}.q.q-2:after{background-position-x:-32px}.q.q-3:after{background-position-x:-48px}.q.q-4:after{background-position-x:-64px}.q.l:before{background-position-x:-80px}.ql .q{float:left}.q:after,.q:before{content:'';position:absolute;left:0;top:0;width:16px;height:16px;display:block;background-repeat:no-repeat;background-position:16px 0;"
+"background-image:url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGAAAAAQCAMAAADeZIrLAAAAJFBMVEX///8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADHJj5lAAAAC3RSTlMAIjN3iJmqu8zd7vF8pzcAAABsSURBVHja7Y1BCsAwCASNSVo3/v+/BUEiXnIoXkoX5jAQMxTHzK9cVSnvDxwD8bFx8PhZ9q8FmghXBhqA1faxk92PsxvRc2CCCFdhQCbRkLoAQ3q/wWUBqG35ZxtVzW4Ed6LngPyBU2CobdIDQ5oPWI5nCUwAAAAASUVORK5CYII=');}"
+".wm-scan-lock:after,.wm-scan-bars:before{content:none}"
+"@media (-webkit-min-device-pixel-ratio: 2),(min-resolution: 192dpi){.q:before,.q:after {"
+"background-image:url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAALwAAAAgCAMAAACfM+KhAAAALVBMVEX///8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADAOrOgAAAADnRSTlMAESIzRGZ3iJmqu8zd7gKjCLQAAACmSURBVHgB7dDBCoMwEEXRmKlVY3L//3NLhyzqIqSUggy8uxnhCR5Mo8xLt+14aZ7wwgsvvPA/ofv9+44334UXXngvb6XsFhO/VoC2RsSv9J7x8BnYLW+AjT56ud/uePMdb7IP8Bsc/e7h8Cfk912ghsNXWPpDC4hvN+D1560A1QPORyh84VKLjjdvfPFm++i9EWq0348XXnjhhT+4dIbCW+WjZim9AKk4UZMnnCEuAAAAAElFTkSuQmCC');"
+"background-size: 95px 16px;}}"
+// messages from firmware / server
+".msg{padding:16px;margin:12px 0;border-radius:var(--wm-radius-sm);border:1px solid var(--wm-border);"
+"border-left-width:4px;border-left-color:var(--wm-muted);background:var(--wm-surface);text-align:left}"
+".msg h4{margin:0 0 8px;font-size:1rem}"
+".msg.P{border-left-color:var(--wm-brand)}.msg.P h4{color:var(--wm-brand)}"
+".msg.D{border-left-color:var(--wm-danger)}.msg.D h4{color:var(--wm-danger)}"
+".msg.S{border-left-color:var(--wm-success)}.msg.S h4{color:var(--wm-success)}"
+"dt{font-weight:700;font-size:.85rem;color:var(--wm-muted)}dd{margin:2px 0 12px 0;padding:0;font-size:.95rem}"
+"td{vertical-align:top}"
+".h{display:none}"
+/* Info page key-value grid */
+".wm-kv{margin:0;padding:0}"
+".wm-kv dt{padding-top:10px}"
+".wm-kv dt:first-of-type{padding-top:0}"
+".wm-kv dd{margin-left:0;padding-bottom:4px;border-bottom:1px solid var(--wm-border)}"
+".wm-kv dd:last-of-type{border-bottom:0}"
+/* Feedback areas */
+"#wm-wifi-msg,#wm-param-msg{font-size:.9rem;margin-top:12px;min-height:1.2em;color:var(--wm-muted)}"
+// invert legacy body
+"body.invert{background-color:var(--wm-bg)}"
+"body.invert .msg{border-color:var(--wm-border)}"
+"body.invert .q[role=img]{-webkit-filter:invert(1);filter:invert(1)}"
+":disabled{opacity:.55}"
+// toast + modal
+".wm-toast{position:fixed;left:50%;top:12px;transform:translateX(-50%);z-index:10001;max-width:92%;padding:12px 16px;border-radius:var(--wm-radius-sm);"
+"box-shadow:var(--wm-shadow);font-size:.95rem;text-align:center;font-weight:600}"
+".wm-toast.ok{background:rgba(22,163,74,.15);border:1px solid var(--wm-success);color:var(--wm-text)}"
+".wm-toast.err{background:rgba(220,38,38,.12);border:1px solid var(--wm-danger);color:var(--wm-text)}"
+".wm-dialog{position:fixed;inset:0;z-index:10000;display:none;align-items:center;justify-content:center;padding:16px;box-sizing:border-box}"
+".wm-dialog-backdrop{position:absolute;inset:0;background:rgba(15,23,42,.5)}"
+".wm-dialog-panel{position:relative;z-index:1;background:var(--wm-surface);border-radius:var(--wm-radius);padding:20px 18px;max-width:400px;width:100%;"
+"box-shadow:var(--wm-shadow);border:1px solid var(--wm-border);text-align:left}"
+".wm-dialog-msg{margin:0 0 16px;line-height:1.45;color:var(--wm-text)}"
+".wm-dialog-actions{display:flex;gap:10px;justify-content:flex-end;flex-wrap:wrap}"
+".wm-dialog-actions .wm-btn{min-width:108px}"
+".wm-dialog-ok,.wm-btn.wm-dialog-ok{background:var(--wm-brand)!important;color:var(--wm-brand-text)!important}"
+".wm-dialog-ok:hover{background:var(--wm-brand-hover)!important}"
+"body.invert .wm-toast.ok{background:rgba(22,163,74,.2)}"
+"body.invert .wm-toast.err{background:rgba(220,38,38,.2)}"
+"</style>";
+
+#endif // _CSS_TEMPLATES_H_

lib/WiFiManager/include/templates/RootShell.h

@@ -0,0 +1,48 @@
+/**
+ * RootShell.h
+ *
+ * @author alexhopeoconnor
+ * @license MIT
+ *
+ * Single-page portal shell: only HTML document served for GET /.
+ * Dynamic UI is driven by embedded JS + JSON APIs under /api/...
+ *
+ * Placeholder keys (%PAGE_TITLE%, %STYLES%, %PORTAL_THEME%, %BOOTSTRAP_JSON%, %PORTAL_APP_JS%) are filled
+ * per request in WiFiManagerHandlers::handleRoot; do not treat placeholders as a customization API.
+ */
+
+#ifndef _WM_ROOT_SHELL_TEMPLATE_H_
+#define _WM_ROOT_SHELL_TEMPLATE_H_
+
+#include <Arduino.h>
+
+const char WM_ROOT_SHELL_TEMPLATE[] PROGMEM =
+    "<!DOCTYPE html>"
+    "<html lang='en'>"
+    "<head>"
+    "<meta name='format-detection' content='telephone=no'>"
+    "<meta charset='UTF-8'/>"
+    "<meta name='viewport' content='width=device-width,initial-scale=1,user-scalable=no'/>"
+    "<title>%PAGE_TITLE%</title>"
+    "%STYLES%"
+    "%PORTAL_THEME%"
+    "</head>"
+    "<body class='portal'>"
+    "<div id='wm-toast' class='wm-toast' aria-live='polite' role='status' style='display:none'></div>"
+    "<div id='wm-dialog' class='wm-dialog' style='display:none' aria-hidden='true'>"
+    "<div class='wm-dialog-backdrop' id='wm-dialog-backdrop'></div>"
+    "<div class='wm-dialog-panel'>"
+    "<p class='wm-dialog-msg' id='wm-dialog-msg'></p>"
+    "<div class='wm-dialog-actions'>"
+    "<button type='button' id='wm-dialog-cancel' class='wm-btn wm-btn--secondary'>Cancel</button>"
+    "<button type='button' id='wm-dialog-ok' class='wm-btn wm-btn--primary wm-dialog-ok'>OK</button>"
+    "</div></div></div>"
+    "<div id='app'></div>"
+    "<script id='wm-bootstrap' type='application/json'>%BOOTSTRAP_JSON%</script>"
+    "<script>"
+    "%PORTAL_APP_JS%"
+    "</script>"
+    "</body>"
+    "</html>";
+
+#endif  // _WM_ROOT_SHELL_TEMPLATE_H_

lib/WiFiManager/src/WiFiManagerParameter.cpp

@@ -0,0 +1,111 @@
+/**
+ * WiFiManagerParameter.cpp
+ *
+ * @author alexhopeoconnor
+ * @license MIT
+ */
+
+#include "WiFiManagerParameter.h"
+
+#include <cstring>
+#include <new>
+
+WiFiManagerParameter::WiFiManagerParameter()
+  : WiFiManagerParameter("")
+{
+}
+
+WiFiManagerParameter::WiFiManagerParameter(const char *custom) {
+  _id             = NULL;
+  _label          = NULL;
+  _length         = 0;
+  _value          = nullptr;
+  _labelPlacement = WFM_LABEL_DEFAULT;
+  _customHTML     = custom;
+}
+
+WiFiManagerParameter::WiFiManagerParameter(const char *id, const char *label) {
+  init(id, label, "", 0, "", WFM_LABEL_DEFAULT);
+}
+
+WiFiManagerParameter::WiFiManagerParameter(const char *id, const char *label, const char *defaultValue, int length) {
+  init(id, label, defaultValue, length, "", WFM_LABEL_DEFAULT);
+}
+
+WiFiManagerParameter::WiFiManagerParameter(const char *id, const char *label, const char *defaultValue, int length, const char *custom) {
+  init(id, label, defaultValue, length, custom, WFM_LABEL_DEFAULT);
+}
+
+WiFiManagerParameter::WiFiManagerParameter(const char *id, const char *label, const char *defaultValue, int length, const char *custom, int labelPlacement) {
+  init(id, label, defaultValue, length, custom, labelPlacement);
+}
+
+void WiFiManagerParameter::init(const char *id, const char *label, const char *defaultValue, int length, const char *custom, int labelPlacement) {
+  _id             = id;
+  _label          = label;
+  _labelPlacement = labelPlacement;
+  _customHTML     = custom;
+  _length         = 0;
+  _value          = nullptr;
+  setValue(defaultValue,length);
+}
+
+WiFiManagerParameter::~WiFiManagerParameter() {
+  if (_value != NULL) {
+    delete[] _value;
+  }
+  _length=0; // setting length 0, ideally the entire parameter should be removed, or added to wifimanager scope so it follows
+}
+
+// WiFiManagerParameter& WiFiManagerParameter::operator=(const WiFiManagerParameter& rhs){
+//   Serial.println("copy assignment op called");
+//   (*this->_value) = (*rhs._value);
+//   return *this;
+// }
+
+// @note debug is not available in wmparameter class
+void WiFiManagerParameter::setValue(const char *defaultValue, int length) {
+  if (!_id || length < 0) {
+    return;
+  }
+
+  if (_length != length || _value == nullptr) {
+    char* replacement = new (std::nothrow) char[static_cast<size_t>(length) + 1];
+    if (!replacement) {
+      return;
+    }
+
+    delete[] _value;
+    _value = replacement;
+    _length = length;
+  }
+
+  memset(_value, 0, static_cast<size_t>(_length) + 1);
+
+  if (defaultValue != nullptr) {
+    strncpy(_value, defaultValue, _length);
+  }
+}
+const char* WiFiManagerParameter::getValue() const {
+  // Serial.println(printf("Address of _value is %p\n", (void *)_value));
+  return _value;
+}
+const char* WiFiManagerParameter::getID() const {
+  return _id;
+}
+const char* WiFiManagerParameter::getPlaceholder() const {
+  return _label;
+}
+const char* WiFiManagerParameter::getLabel() const {
+  return _label;
+}
+int WiFiManagerParameter::getValueLength() const {
+  return _length;
+}
+int WiFiManagerParameter::getLabelPlacement() const {
+  return _labelPlacement;
+}
+const char* WiFiManagerParameter::getCustomHTML() const {
+  return _customHTML;
+}
+

lib/WiFiManager/src/WiFiManagerServer.cpp

@@ -0,0 +1,184 @@
+/**
+ * WiFiManagerServer.cpp
+ *
+ * @author alexhopeoconnor
+ * @license MIT
+ *
+ * HTTP server lifecycle and route registration only. HTML shell rendering is request-scoped in
+ * WiFiManagerHandlers (WM_ROOT_SHELL_TEMPLATE + per-request placeholder registry).
+ * Route inventory matches WiFiManagerServer.h (GET /, /api/..., POST /u, onNotFound).
+ */
+
+#include "WiFiManagerServer.h"
+#include "WiFiManager.h"
+#include "WiFiManagerHandlers.h"
+#ifdef WM_DFTE_LOGGING
+#include "WiFiManagerDfteLogger.h"
+#include <DeviceFrameworkTemplateEngineDebug.h>
+#endif
+
+#if defined(ESP8266) || defined(ESP32)
+
+WiFiManagerServer::WiFiManagerServer(WiFiManager* wm)
+    : _wm(wm), _handlers(std::make_unique<WiFiManagerHandlers>(wm)) {}
+
+WiFiManagerServer::~WiFiManagerServer() = default;
+
+void WiFiManagerServer::createServer(uint16_t port) {
+  if (server) {
+#ifndef WM_NO_LOG
+    _wm->log(WiFiManagerLogLevel::Debug, kWiFiMgrLogSubsystem, F("Server already exists, shutting down first"));
+#endif
+    shutdownServer();
+  }
+
+#ifndef WM_NO_LOG
+  _wm->log(WiFiManagerLogLevel::Info, kWiFiMgrLogSubsystem, F("Starting Web Portal"));
+#endif
+
+  if (port != 80) {
+#ifndef WM_NO_LOG
+    _wm->log(WiFiManagerLogLevel::Debug, kWiFiMgrLogSubsystem, F("http server started with custom port: "), port);
+#endif
+  }
+
+  server.reset(new AsyncWebServer(port));
+
+#ifdef WM_DFTE_LOGGING
+  // DFTE logging is still owned by server lifecycle; it is intentionally independent of
+  // request-scoped shell rendering / placeholder registration.
+  if (!deviceFrameworkTemplateEngineIsLoggingEnabled()) {
+    if (!_dfteLogger) {
+      _dfteLogger = std::make_unique<WiFiManagerDfteLogger>(_wm);
+    }
+    deviceFrameworkTemplateEngineEnableLogging(_dfteLogger.get(), static_cast<const void*>(this));
+    _wmOwnsDfteLogSink = true;
+  }
+#endif
+}
+
+void WiFiManagerServer::registerRoutes() {
+  if (!server) {
+#ifndef WM_NO_LOG
+    _wm->log(WiFiManagerLogLevel::Error, kWiFiMgrLogSubsystem, F("[ERROR] Server not created, call createServer() first"));
+#endif
+    return;
+  }
+
+  if (_wm->_webservercallback != NULL) {
+#ifndef WM_NO_LOG
+    _wm->log(WiFiManagerLogLevel::Debug, kWiFiMgrLogSubsystem, F("[CB] _webservercallback calling"));
+#endif
+    _wm->_webservercallback();
+  }
+
+  // Shell: only HTML document. JSON + actions + OTA below (no legacy /wifi, /info, … routes).
+
+  server->on(WM_G(R_root), HTTP_GET, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleRoot(request);
+  });
+
+  server->on(WM_G(R_api_bootstrap), HTTP_GET, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiBootstrap(request);
+  });
+  server->on(WM_G(R_api_wifi_scan_status), HTTP_GET, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiWifiScanStatus(request);
+  });
+  server->on(WM_G(R_api_wifi_scan), HTTP_POST, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiWifiScan(request);
+  });
+  server->on(WM_G(R_api_wifi_meta), HTTP_GET, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiWifiMeta(request);
+  });
+  server->on(WM_G(R_api_wifi_save), HTTP_POST, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiWifiSave(request);
+  });
+  server->on(WM_G(R_api_wifi_connect_status), HTTP_GET, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiWifiConnectStatus(request);
+  });
+  server->on(WM_G(R_api_wifi_connect_complete), HTTP_POST, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiWifiConnectComplete(request);
+  });
+  server->on(WM_G(R_api_portal_timeout_reset), HTTP_POST, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiPortalTimeoutReset(request);
+  });
+  server->on(WM_G(R_api_params), HTTP_GET, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiParamsGet(request);
+  });
+  server->on(WM_G(R_api_params_save), HTTP_POST, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiParamsSave(request);
+  });
+  server->on(WM_G(R_api_info), HTTP_GET, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiInfo(request);
+  });
+  server->on(WM_G(R_api_status), HTTP_GET, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiStatus(request);
+  });
+  server->on(WM_G(R_api_device_restart), HTTP_POST, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiDeviceRestart(request);
+  });
+  server->on(WM_G(R_api_device_erase), HTTP_POST, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiDeviceErase(request);
+  });
+  server->on(WM_G(R_api_portal_close), HTTP_POST, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiPortalClose(request);
+  });
+  server->on(WM_G(R_api_portal_exit), HTTP_POST, [this](AsyncWebServerRequest *request) {
+    this->_handlers->handleApiPortalExit(request);
+  });
+
+  server->on(WM_G(R_updatedone), HTTP_POST,
+              [this](AsyncWebServerRequest *request) {
+                this->_handlers->handleUpdateDone(request);
+              },
+              [this](AsyncWebServerRequest *request, String filename, size_t index, uint8_t *data, size_t len,
+                     bool final) {
+                this->_handlers->handleUpdating(request, filename, index, data, len, final);
+              });
+
+  server->onNotFound([this](AsyncWebServerRequest *request) {
+    this->_handlers->handleNotFound(request);
+  });
+
+  server->begin();
+#ifndef WM_NO_LOG
+  _wm->log(WiFiManagerLogLevel::Debug, kWiFiMgrLogSubsystem, F("HTTP server started"));
+#endif
+}
+
+void WiFiManagerServer::setupDNSD() {
+  dnsServer.reset(new DNSServer());
+  dnsServer->setErrorReplyCode(DNSReplyCode::NoError);
+#ifndef WM_NO_LOG
+  _wm->log(WiFiManagerLogLevel::Trace, kWiFiMgrLogSubsystem, F("dns server started with ip: "), WiFi.softAPIP());
+#endif
+  const uint8_t DNS_PORT = 53;
+  dnsServer->start(DNS_PORT, F("*"), WiFi.softAPIP());
+}
+
+void WiFiManagerServer::processDNS() {
+  if (dnsServer) {
+    dnsServer->processNextRequest();
+  }
+}
+
+void WiFiManagerServer::shutdownServer() {
+#ifdef WM_DFTE_LOGGING
+  if (_wmOwnsDfteLogSink) {
+    deviceFrameworkTemplateEngineDisableLoggingForOwner(static_cast<const void*>(this));
+    _dfteLogger.reset();
+    _wmOwnsDfteLogSink = false;
+  }
+#endif
+
+  if (server) {
+    server.reset();
+  }
+
+  if (dnsServer) {
+    dnsServer->stop();
+    dnsServer.reset();
+  }
+}
+
+#endif

lib/WiFiManager/src/WiFiManagerUtils.cpp

@@ -0,0 +1,135 @@
+/**
+ * WiFiManagerUtils.cpp
+ * Implementation of pure utility functions for WiFiManager
+ *
+ * @author alexhopeoconnor
+ * @license MIT
+ */
+
+#include "WiFiManagerUtils.h"
+
+#if defined(ESP8266)
+#include <ESP8266WiFi.h>
+#elif defined(ESP32)
+#include <WiFi.h>
+#endif
+
+namespace WiFiManagerUtils {
+
+// -----------------------------------------------------------------------------------------------
+// WIFI STATUS ARRAYS
+
+const char * const WIFI_STA_STATUS[] PROGMEM = {
+  "WL_IDLE_STATUS",     // 0 STATION_IDLE
+  "WL_NO_SSID_AVAIL",   // 1 STATION_NO_AP_FOUND
+  "WL_SCAN_COMPLETED",  // 2
+  "WL_CONNECTED",       // 3 STATION_GOT_IP
+  "WL_CONNECT_FAILED",  // 4 STATION_CONNECT_FAIL, STATION_WRONG_PASSWORD(NI)
+  "WL_CONNECTION_LOST", // 5
+  "WL_DISCONNECTED",    // 6
+  "WL_STATION_WRONG_PASSWORD" // 7 KLUDGE
+};
+
+#ifdef ESP32
+const char * const AUTH_MODE_NAMES[] PROGMEM = {
+    "OPEN",
+    "WEP",
+    "WPA_PSK",
+    "WPA2_PSK",
+    "WPA_WPA2_PSK",
+    "WPA2_ENTERPRISE",
+    "MAX"
+};
+#elif defined(ESP8266)
+const char * const AUTH_MODE_NAMES[] PROGMEM = {
+    "",
+    "",
+    "WPA_PSK",      // 2 ENC_TYPE_TKIP
+    "",
+    "WPA2_PSK",     // 4 ENC_TYPE_CCMP
+    "WEP",          // 5 ENC_TYPE_WEP
+    "",
+    "OPEN",         //7 ENC_TYPE_NONE
+    "WPA_WPA2_PSK", // 8 ENC_TYPE_AUTO
+};
+#endif
+
+const char* const WIFI_MODES[] PROGMEM = { "NULL", "STA", "AP", "STA+AP" };
+
+// -----------------------------------------------------------------------------------------------
+// STRING CONVERSION UTILITIES
+
+String getStatusString(uint8_t status) {
+  if(status <= 7) return FPSTR(WIFI_STA_STATUS[status]);
+  return F("Unknown");
+}
+
+
+String getModeString(uint8_t mode) {
+  if(mode <= 3) return FPSTR(WIFI_MODES[mode]);
+  return F("Unknown");
+}
+
+String getEncryptionString(uint8_t authmode) {
+  return FPSTR(AUTH_MODE_NAMES[authmode]);
+}
+
+// -----------------------------------------------------------------------------------------------
+// HTML UTILITIES
+
+String htmlEntities(const String& str, bool whitespace) {
+  String result = str;
+  result.replace("&","&amp;");
+  result.replace("<","&lt;");
+  result.replace(">","&gt;");
+  result.replace("'","&#39;");
+  if(whitespace) result.replace(" ","&#160;");
+  return result;
+}
+
+// -----------------------------------------------------------------------------------------------
+// IP/STRING UTILITIES
+
+bool isValidIP(const String& str) {
+  for (size_t i = 0; i < str.length(); i++) {
+    int c = str.charAt(i);
+    if (c != '.' && (c < '0' || c > '9')) {
+      return false;
+    }
+  }
+  return true;
+}
+
+String ipToString(IPAddress ip) {
+  String res = "";
+  for (int i = 0; i < 3; i++) {
+    res += String((ip >> (8 * i)) & 0xFF) + ".";
+  }
+  res += String(((ip >> 8 * 3)) & 0xFF);
+  return res;
+}
+
+bool isValidAPPassword(const String& password) {
+  if (password.length() < 8 || password.length() > 63) {
+    return false;
+  }
+  return true;
+}
+
+// -----------------------------------------------------------------------------------------------
+// HELPER CALCULATIONS
+
+int rssiToQuality(int rssi) {
+  int quality = 0;
+  if (rssi <= -100) {
+    quality = 0;
+  } else if (rssi >= -50) {
+    quality = 100;
+  } else {
+    quality = 2 * (rssi + 100);
+  }
+  return quality;
+}
+
+} // namespace WiFiManagerUtils
+

library.json

@@ -0,0 +1,80 @@
+{
+  "name": "WiFiManager",
+  "version": "3.2.4",
+  "keywords": [
+    "wifi",
+    "wi-fi",
+    "esp",
+    "esp8266",
+    "esp32",
+    "espressif8266",
+    "espressif32",
+    "nodemcu",
+    "wemos",
+    "arduino"
+  ],
+  "description": "Maintained ESP8266/ESP32 WiFi configuration portal with asynchronous web support.",
+  "authors": [
+    {
+      "name": "tzapu",
+      "url": "https://github.com/tzapu"
+    },
+    {
+      "name": "tablatronix",
+      "url": "https://github.com/tablatronix",
+      "maintainer": true
+    },
+    {
+      "name": "Alex Hope-O'Connor",
+      "url": "https://github.com/alexhopeoconnor"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alexhopeoconnor/WiFiManager.git"
+  },
+  "frameworks": "arduino",
+  "platforms": [
+    "espressif8266",
+    "espressif32"
+  ],
+  "dependencies": [
+    {
+      "owner": "esp32async",
+      "name": "ESPAsyncWebServer",
+      "version": "3.9.1"
+    },
+    {
+      "owner": "esp32async",
+      "name": "ESPAsyncTCP",
+      "version": "^2.0.0",
+      "platforms": "espressif8266"
+    },
+    {
+      "owner": "esp32async",
+      "name": "AsyncTCP",
+      "version": "^3.4.9",
+      "platforms": "espressif32"
+    },
+    {
+      "name": "DeviceFrameworkTemplateEngine",
+      "version": "https://github.com/alexhopeoconnor/DFTE.git#v1.2.1"
+    }
+  ],
+  "build": {
+    "includeDir": "lib/WiFiManager/include",
+    "srcDir": "lib/WiFiManager/src"
+  },
+  "export": {
+    "include": [
+      "lib/WiFiManager/include",
+      "lib/WiFiManager/src",
+      "LICENSE",
+      "README.md",
+      "CHANGELOG.md",
+      "library.json"
+    ]
+  },
+  "$schema": "https://raw.githubusercontent.com/platformio/platformio-core/develop/platformio/assets/schema/library.json",
+  "homepage": "https://github.com/alexhopeoconnor/WiFiManager"
+}

platformio.ini

@@ -0,0 +1,48 @@
+; PlatformIO Project Configuration File for WiFiManager Library
+; This file is used for building tests
+
+[env:esp8266]
+platform = espressif8266
+board = d1_mini
+framework = arduino
+; Postmortem jump relocation fix for large binaries (see ESP8266-LINKER-WORKAROUND.md in arduino-home-assistant)
+platform_packages =
+    platformio/framework-arduinoespressif8266 @ https://github.com/esp8266/Arduino.git#521ae60a89e64bb0d1eb7a0b7addf620ced5cad3
+monitor_speed = 115200
+test_framework = unity
+test_build_src = no
+build_flags =
+    -DWM_LOG_LEVEL=5
+    -DUNIT_TEST
+lib_deps = 
+    ESP32Async/ESPAsyncWebServer@3.9.1
+    DeviceFrameworkTemplateEngine=https://github.com/alexhopeoconnor/DFTE.git#v1.2.0
+    ESP32Async/ESPAsyncTCP@2.0.0
+
+[env:esp32]
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/51.03.05/platform-espressif32.zip
+board = esp32dev
+framework = arduino
+monitor_speed = 115200
+test_framework = unity
+test_build_src = no
+build_unflags = 
+    -std=gnu++11
+build_flags = 
+    -std=gnu++14
+    -DSOC_WIFI_SUPPORTED=1
+    -I${platformio.packages_dir}/framework-arduinoespressif32/libraries/Network/src
+    -DWM_LOG_LEVEL=5
+    -DUNIT_TEST
+lib_deps = 
+    ESP32Async/ESPAsyncWebServer@3.9.1
+    DeviceFrameworkTemplateEngine=https://github.com/alexhopeoconnor/DFTE.git#v1.2.0
+    ESP32Async/AsyncTCP@^3.4.9
+
+; Optional: compile tests with DFTE logs bridged into WiFiManager::log (see README)
+[env:esp8266_dfte_log]
+extends = env:esp8266
+build_flags =
+    ${env:esp8266.build_flags}
+    -DWM_DFTE_LOGGING
+

scripts/bump-version.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+    echo "Usage: $0 vMAJOR.MINOR.PATCH" >&2
+    exit 2
+}
+
+tag="${1:-}"
+[[ "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || usage
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+version="${tag#v}"
+repo_url="https://github.com/alexhopeoconnor/WiFiManager.git"
+reference_files=(README.md docs/GETTING_STARTED.md)
+
+current_version="$(sed -n 's/.*"version": "\([^"]*\)".*/\1/p' "$root/library.json" | head -n 1)"
+[[ "$current_version" != "$version" ]] || {
+    echo "library.json already declares $version; choose a new version." >&2
+    exit 1
+}
+grep -q "^## $version$" "$root/CHANGELOG.md" && {
+    echo "CHANGELOG.md already has a $version section; choose a new version." >&2
+    exit 1
+}
+
+sed -i -E '0,/"version": "[0-9]+\.[0-9]+\.[0-9]+"/s//"version": "'"$version"'"/' "$root/library.json"
+for file in "${reference_files[@]}"; do
+    sed -i -E "s|${repo_url}#v[0-9]+\.[0-9]+\.[0-9]+|${repo_url}#v${version}|g" "$root/$file"
+done
+
+temp_file="$(mktemp)"
+trap 'rm -f "$temp_file"' EXIT
+{
+    IFS= read -r changelog_heading < "$root/CHANGELOG.md"
+    [[ "$changelog_heading" == "# Changelog" ]] || {
+        echo "CHANGELOG.md must begin with # Changelog" >&2
+        exit 1
+    }
+    printf '%s\n\n## %s\n\n- TODO: Describe this release.\n' "$changelog_heading" "$version"
+    tail -n +2 "$root/CHANGELOG.md"
+} > "$temp_file"
+mv "$temp_file" "$root/CHANGELOG.md"
+
+echo "Updated WiFiManager declarations and canonical install references to $tag."
+echo "Replace the generated changelog TODO with the release summary, then run scripts/check-docs.sh and scripts/prepare-release.sh $tag."

scripts/capture-unity-serial.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+    echo "Usage: $0 --port /dev/serial/by-id/... [--timeout seconds]" >&2
+    exit 2
+}
+
+port=""
+timeout_seconds=300
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --port) [[ $# -ge 2 ]] || usage; port="${2:-}"; shift 2 ;;
+        --timeout) [[ $# -ge 2 ]] || usage; timeout_seconds="${2:-}"; shift 2 ;;
+        *) usage ;;
+    esac
+done
+
+[[ -n "$port" && -e "$port" ]] || usage
+[[ "$timeout_seconds" =~ ^[1-9][0-9]*$ ]] || usage
+
+capture_file="$(mktemp -p /tmp wifimanager-unity.XXXXXX)"
+monitor_pid=""
+preserve_capture=false
+cleanup() {
+    if [[ -n "$monitor_pid" ]] && kill -0 "$monitor_pid" 2>/dev/null; then
+        kill "$monitor_pid" 2>/dev/null || true
+        wait "$monitor_pid" 2>/dev/null || true
+    fi
+    if [[ "$preserve_capture" == "false" ]]; then
+        rm -f "$capture_file"
+    fi
+}
+trap cleanup EXIT
+
+# Start immediately after upload. PlatformIO's interactive monitor cannot run
+# without a TTY; socat opens only this port and streams its configured 115200
+# baud output into the capture file without touching another board.
+timeout --foreground "$timeout_seconds" socat -u "FILE:$port,raw,echo=0,b115200" STDOUT \
+    >"$capture_file" 2>&1 &
+monitor_pid="$!"
+
+while kill -0 "$monitor_pid" 2>/dev/null; do
+    if grep -aqE '[0-9]+ Tests [0-9]+ Failures' "$capture_file"; then
+        kill "$monitor_pid" 2>/dev/null || true
+        wait "$monitor_pid" 2>/dev/null || true
+        monitor_pid=""
+
+        if grep -aq "Tests 0 Failures" "$capture_file" && grep -aq "^OK" "$capture_file"; then
+            grep -aE '\[METRIC\]|Tests [0-9]+ Failures|^OK$' "$capture_file" || true
+            exit 0
+        fi
+
+        echo "Unity reported a test failure:" >&2
+        grep -anE ':FAIL|FAIL$|\[METRIC\]|Tests [0-9]+ Failures' "$capture_file" >&2 || true
+        tail -n 80 "$capture_file" >&2 || true
+        preserve_capture=true
+        echo "Full serial capture retained at $capture_file" >&2
+        exit 1
+    fi
+    sleep 0.25
+done
+
+wait "$monitor_pid" || true
+monitor_pid=""
+preserve_capture=true
+echo "Serial monitoring ended before Unity produced a summary; capture retained at $capture_file" >&2
+exit 1

scripts/check-docs.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+failed=0
+
+link_pattern='\]\(([^ )]+)'
+while IFS= read -r file; do
+    in_fence=false
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        if [[ "$line" =~ ^[[:space:]]*(\`\`\`|~~~) ]]; then
+            [[ "$in_fence" == true ]] && in_fence=false || in_fence=true
+            continue
+        fi
+        [[ "$in_fence" == true ]] && continue
+        remainder="$line"
+        while [[ "$remainder" =~ $link_pattern ]]; do
+            target="${BASH_REMATCH[1]}"
+            remainder="${remainder#*]($target)}"
+            case "$target" in
+                \#*|http://*|https://*|mailto:*|tel:*) continue ;;
+            esac
+            target="${target%%#*}"
+            [[ -z "$target" ]] && continue
+            if [[ "$target" == /* ]]; then
+                candidate="$root/${target#/}"
+            else
+                candidate="$(dirname "$file")/$target"
+            fi
+            if [[ ! -e "$candidate" ]]; then
+                printf 'Broken local Markdown link: %s -> %s\n' "${file#$root/}" "$target" >&2
+                failed=1
+            fi
+        done
+    done < "$file"
+done < <(find "$root" -path "$root/.git" -prune -o -path '*/.pio' -prune -o -type f -name '*.md' -print)
+
+for required in README.md CHANGELOG.md docs/README.md docs/GETTING_STARTED.md docs/PORTAL_UI.md docs/PORTAL_API.md docs/TESTING.md docs/DEVELOPMENT.md; do
+    if [[ ! -f "$root/$required" ]]; then
+        printf 'Missing required documentation file: %s\n' "$required" >&2
+        failed=1
+    fi
+done
+
+while IFS= read -r example; do
+    for required in README.md platformio.ini; do
+        if [[ ! -f "$example/$required" ]]; then
+            printf 'Incomplete example: %s is missing %s\n' "${example#$root/}" "$required" >&2
+            failed=1
+        fi
+    done
+    if ! find "$example" -maxdepth 2 -type f \( -name '*.ino' -o -name '*.cpp' \) -print -quit | grep -q .; then
+        printf 'Incomplete example: %s has no sketch source\n' "${example#$root/}" >&2
+        failed=1
+    fi
+done < <(find "$root/examples" -mindepth 1 -maxdepth 1 -type d -print | sort)
+
+if [[ "$failed" -ne 0 ]]; then
+    exit 1
+fi
+
+echo "WiFiManager documentation checks passed"

scripts/prepare-release.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+    echo "Usage: $0 vMAJOR.MINOR.PATCH [--tag]"
+    exit 2
+}
+
+tag="${1:-}"
+[[ "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || usage
+[[ "${2:-}" == "" || "${2:-}" == "--tag" ]] || usage
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+version="${tag#v}"
+manifest_version="$(sed -n 's/.*"version": "\([^"]*\)".*/\1/p' "$root/library.json" | head -n 1)"
+
+if [[ "$manifest_version" != "$version" ]]; then
+    echo "library.json is $manifest_version; expected $version for $tag" >&2
+    exit 1
+fi
+
+grep -q "^## $version$" "$root/CHANGELOG.md" || {
+    echo "CHANGELOG.md has no $version heading" >&2
+    exit 1
+}
+
+if [[ -f "$root/library.properties" ]]; then
+    properties_version="$(sed -n 's/^version=//p' "$root/library.properties" | head -n 1)"
+    if [[ "$properties_version" != "$version" ]]; then
+        echo "library.properties is $properties_version; expected $version for $tag" >&2
+        exit 1
+    fi
+fi
+
+if awk -v heading="## $version" '
+    $0 == heading { found = 1; next }
+    found && /^## / { exit }
+    found { print }
+' "$root/CHANGELOG.md" | grep -Fq 'TODO: Describe this release.'; then
+    echo "CHANGELOG.md still has the generated TODO for $version" >&2
+    exit 1
+fi
+repo_url="https://github.com/alexhopeoconnor/WiFiManager.git"
+validate_reference() {
+    local file="$1"
+    local reference_count
+    reference_count="$(grep -F "$repo_url#v" "$root/$file" | wc -l)"
+    [[ "$reference_count" -eq 1 ]] || { echo "$file must contain exactly one canonical release reference" >&2; exit 1; }
+    grep -Fq "$repo_url#$tag" "$root/$file" || { echo "$file does not reference $tag" >&2; exit 1; }
+}
+validate_reference README.md
+validate_reference docs/GETTING_STARTED.md
+
+git -C "$root" diff --check
+package_dir="$(mktemp -d)"
+trap 'rm -rf "$package_dir"' EXIT
+pio pkg pack "$root" --output "$package_dir/package.tar.gz" >/dev/null
+echo "Validated release metadata and PlatformIO package for $tag"
+
+if [[ "${2:-}" == "--tag" ]]; then
+    git -C "$root" diff --quiet
+    git -C "$root" diff --cached --quiet
+    git -C "$root" tag -a "$tag" -m "Release $tag"
+    echo "Created $tag. Push the branch and tag; GitHub Actions will publish the release."
+fi

scripts/release-notes.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+tag="${1:-}"
+[[ "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || {
+    echo "Usage: $0 vMAJOR.MINOR.PATCH" >&2
+    exit 2
+}
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+version="${tag#v}"
+notes="$(mktemp)"
+trap 'rm -f "$notes"' EXIT
+awk -v heading="## ${version}" '
+    $0 == heading { found = 1; next }
+    found && /^## / { exit }
+    found { print }
+    END { if (!found) exit 1 }
+' "$root/CHANGELOG.md" > "$notes" || {
+    echo "CHANGELOG.md has no ${version} section" >&2
+    exit 1
+}
+if [[ ! -s "$notes" ]]; then
+    echo "No release notes found for $tag in CHANGELOG.md" >&2
+    exit 1
+fi
+printf '%s\n\n' "# WiFiManager $tag"
+cat "$notes"

scripts/test.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+    cat <<'USAGE' >&2
+Usage:
+  ./scripts/test.sh compile  --platform esp8266|esp32
+  ./scripts/test.sh examples --platform esp8266|esp32
+  ./scripts/test.sh hardware --platform esp8266|esp32 --port /dev/serial/by-id/...
+USAGE
+    exit 2
+}
+
+mode="${1:-}"
+[[ "$mode" == "compile" || "$mode" == "examples" || "$mode" == "hardware" ]] || usage
+shift
+
+platform=""
+port=""
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --platform) [[ $# -ge 2 ]] || usage; platform="${2:-}"; shift 2 ;;
+        --port) [[ $# -ge 2 ]] || usage; port="${2:-}"; shift 2 ;;
+        *) usage ;;
+    esac
+done
+
+[[ "$platform" == "esp8266" || "$platform" == "esp32" ]] || usage
+[[ "$mode" != "hardware" || -n "$port" ]] || usage
+[[ "$mode" != "hardware" || -e "$port" ]] || { echo "Serial port not found: $port" >&2; exit 1; }
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+if [[ "$mode" == "hardware" ]]; then
+    # Keep serial flashing and portal-adapter work mutually exclusive.
+    # shellcheck source=tools/lib/portal-hardware-session.sh
+    source "$root/tools/lib/portal-hardware-session.sh"
+    wm_acquire_hardware_lock
+fi
+
+if [[ "$mode" == "examples" ]]; then
+    mapfile -t examples < <(find "$root/examples" -mindepth 2 -maxdepth 2 -type f -name platformio.ini -printf '%h\n' | sort)
+    if (( ${#examples[@]} == 0 )); then
+        echo "No example projects found" >&2
+        exit 1
+    fi
+    for example in "${examples[@]}"; do
+        pio run -d "$example" -e "$platform" </dev/null
+    done
+    echo "WiFiManager examples compile check passed for $platform"
+    exit 0
+fi
+
+if [[ "$mode" == "hardware" ]]; then
+    # Upload first, then capture from the normal boot reset. The Unity sketch
+    # deliberately waits two seconds before it begins its test sequence.
+    pio test -d "$root" -e "$platform" --filter test_wifimanager \
+        --upload-port "$port" --without-testing
+    "$root/scripts/capture-unity-serial.sh" --port "$port" --timeout 300
+    echo "WiFiManager hardware test passed for $platform on $port"
+    exit 0
+fi
+
+cached_library="$root/test/compile-project/.pio/libdeps/${platform}/WiFiManager"
+# The fixture intentionally declares only this local package. Remove a prior
+# link so each check resolves the current manifest as a fresh consumer would.
+if [[ -d "$cached_library" || -e "${cached_library}.pio-link" ]]; then
+    pio pkg uninstall -d "$root/test/compile-project" -e "$platform" \
+        -l WiFiManager --no-save --skip-dependencies >/dev/null
+fi
+pio run -d "$root/test/compile-project" -e "$platform"
+
+echo "WiFiManager consumer compile check passed for $platform"

test/compile-project/platformio.ini

@@ -0,0 +1,32 @@
+[platformio]
+default_envs = esp8266
+
+[common]
+framework = arduino
+lib_ldf_mode = deep+
+lib_deps =
+    WiFiManager=symlink://../..
+
+[env:esp8266]
+extends = common
+platform = espressif8266
+board = d1_mini
+platform_packages =
+    platformio/framework-arduinoespressif8266 @ https://github.com/esp8266/Arduino.git#521ae60a89e64bb0d1eb7a0b7addf620ced5cad3
+build_flags =
+    -DWM_LOG_LEVEL=3
+lib_deps =
+    ${common.lib_deps}
+
+[env:esp32]
+extends = common
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/51.03.05/platform-espressif32.zip
+board = esp32dev
+build_unflags = -std=gnu++11
+build_flags =
+    -std=gnu++14
+    -DSOC_WIFI_SUPPORTED=1
+    -I${platformio.packages_dir}/framework-arduinoespressif32/libraries/Network/src
+    -DWM_LOG_LEVEL=3
+lib_deps =
+    ${common.lib_deps}

test/compile-project/src/main.cpp

@@ -0,0 +1,46 @@
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+namespace {
+const char kTitle[] PROGMEM = "Set up Compile Fixture";
+const char kIdentity[] PROGMEM = "WiFiManager";
+const char kTagline[] PROGMEM = "A branded portal compile check.";
+const char kLogoAlt[] PROGMEM = "WiFiManager";
+const char kLogo[] PROGMEM = "<svg viewBox='0 0 24 24'></svg>";
+const char kPage[] PROGMEM = "#f4f7f3";
+const char kSurface[] PROGMEM = "#ffffff";
+const char kText[] PROGMEM = "#1c251e";
+const char kMuted[] PROGMEM = "#607064";
+const char kBorder[] PROGMEM = "#d6e0d7";
+const char kAccent[] PROGMEM = "#347a45";
+const char kAccentHover[] PROGMEM = "#245a32";
+const char kAccentText[] PROGMEM = "#ffffff";
+
+const WiFiManagerPortalConfig kPortalConfig = {
+    WiFiManagerPortalText::progmem(kTitle),
+    WiFiManagerPortalText::progmem(kIdentity),
+    WiFiManagerPortalText::progmem(kTagline),
+    WiFiManagerPortalAsset::svgFromProgmem(kLogo),
+    WiFiManagerPortalText::progmem(kLogoAlt),
+    {
+        WiFiManagerPortalText::progmem(kPage),
+        WiFiManagerPortalText::progmem(kSurface),
+        WiFiManagerPortalText::progmem(kText),
+        WiFiManagerPortalText::progmem(kMuted),
+        WiFiManagerPortalText::progmem(kBorder),
+        WiFiManagerPortalText::progmem(kAccent),
+        WiFiManagerPortalText::progmem(kAccentHover),
+        WiFiManagerPortalText::progmem(kAccentText),
+        {}, {}, {}, 10, 6,
+    },
+};
+}  // namespace
+
+WiFiManager wifiManager;
+
+void setup() {
+    wifiManager.setPortalConfig(kPortalConfig);
+    wifiManager.setConfigPortalTimeout(1);
+}
+
+void loop() {}

test/portal-harness/README.md

@@ -0,0 +1,16 @@
+# Portal browser harness
+
+This test fixture starts only the WiFiManager captive portal. It intentionally has no station credentials, MQTT configuration, DeviceFramework dependency, or application logic.
+
+Use it through the repository runner so a secondary Wi-Fi adapter is explicitly selected and protected from becoming the host default route:
+
+```bash
+./tools/portal-hardware run \
+  --platform esp8266 \
+  --port /dev/serial/by-id/... \
+  --client-interface wlx...
+```
+
+The ESP8266 portal SSID is `WM Contract ESP8266`; the ESP32 SSID is `WM Contract ESP32`. Both use `default1` exclusively for local development tests.
+
+The runner cleans up only the temporary connection it creates on the named secondary interface. It refuses to run if that interface is the system default route.

test/portal-harness/platformio.ini

@@ -0,0 +1,28 @@
+[platformio]
+default_envs = esp8266
+
+[common]
+framework = arduino
+lib_ldf_mode = deep+
+lib_deps =
+    WiFiManager=symlink://../..
+
+[env:esp8266]
+extends = common
+platform = espressif8266
+board = d1_mini
+platform_packages =
+    platformio/framework-arduinoespressif8266 @ https://github.com/esp8266/Arduino.git#521ae60a89e64bb0d1eb7a0b7addf620ced5cad3
+build_flags =
+    -DWM_LOG_LEVEL=4
+
+[env:esp32]
+extends = common
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/51.03.05/platform-espressif32.zip
+board = esp32dev
+build_unflags = -std=gnu++11
+build_flags =
+    -std=gnu++14
+    -DSOC_WIFI_SUPPORTED=1
+    -I${platformio.packages_dir}/framework-arduinoespressif32/libraries/Network/src
+    -DWM_LOG_LEVEL=4

test/portal-harness/src/main.cpp

@@ -0,0 +1,36 @@
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+namespace {
+
+#if defined(ESP8266)
+constexpr char kPortalSsid[] = "WM Contract ESP8266";
+#else
+constexpr char kPortalSsid[] = "WM Contract ESP32";
+#endif
+constexpr char kPortalPassword[] = "default1";
+
+WiFiManager wifi;
+WiFiManagerParameter kInstallationLabel(
+    "installation_label", "Installation label", "Contract fixture", 32);
+
+}  // namespace
+
+void setup() {
+    Serial.begin(115200);
+    delay(300);
+
+    // The fixture intentionally has no station credentials. A finite window
+    // exercises timeout reset without leaving a board in a permanent portal.
+    wifi.setConfigPortalTimeout(15 * 60);
+    wifi.setAPStaticIPConfig(
+        IPAddress(192, 168, 4, 1),
+        IPAddress(192, 168, 4, 1),
+        IPAddress(255, 255, 255, 0));
+    wifi.portalAddParameter(&kInstallationLabel);
+    wifi.startConfigPortal(kPortalSsid, kPortalPassword);
+}
+
+void loop() {
+    wifi.process();
+}

test/portal-station.env.example

@@ -0,0 +1,4 @@
+# Ignored local credentials for the optional station handoff test.
+# These values are mounted read-only into the Docker test container.
+WIFI_SSID=replace-me
+WIFI_PASSWORD=replace-me

test/test_wifimanager/test_main.cpp

@@ -0,0 +1,186 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+#include "test_main.h"
+
+// Test case array
+TestCase tests[] = {
+    // Basic tests
+    TEST_ENTRY(test_basic_wifimanager_instantiation),
+    TEST_ENTRY(test_reset_settings),
+    // JSON API shape (buildApiInfoJson is large — run with fresh heap, before stress tests)
+    TEST_ENTRY(test_captive_redirect_host_rule),
+    TEST_ENTRY(test_api_wifi_meta_json_shape),
+    TEST_ENTRY(test_api_wifi_meta_password_field_type),
+    TEST_ENTRY(test_api_wifi_connect_status_success_redirect),
+    TEST_ENTRY(test_profile_portal_success_keeps_handoff_alive),
+    TEST_ENTRY(test_profile_portal_candidate_does_not_take_legacy_empty_ssid_path),
+    TEST_ENTRY(test_api_info_json_shape),
+    TEST_ENTRY(test_api_params_json_shape),
+    TEST_ENTRY(test_api_status_json_shape),
+    
+    // Configuration tests
+    TEST_ENTRY(test_set_and_get_hostname),
+    TEST_ENTRY(test_get_default_ap_name),
+    TEST_ENTRY(test_get_wifi_status_string),
+    TEST_ENTRY(test_get_mode_string),
+    TEST_ENTRY(test_get_rssi_as_quality),
+    
+    // Portal lifecycle tests
+    TEST_ENTRY(test_start_config_portal),
+    TEST_ENTRY(test_start_config_portal_with_password),
+    TEST_ENTRY(test_start_config_portal_auto_name),
+    TEST_ENTRY(test_stop_config_portal),
+    TEST_ENTRY(test_config_portal_infrastructure),
+    TEST_ENTRY(test_start_web_portal),
+    TEST_ENTRY(test_stop_web_portal),
+    TEST_ENTRY(test_config_portal_multiple_start_stop),
+    TEST_ENTRY(test_config_portal_already_active),
+    TEST_ENTRY(test_get_config_portal_ssid),
+    TEST_ENTRY(test_bootstrap_json_portal_feature_flags),
+    TEST_ENTRY(test_portal_default_presentation),
+    TEST_ENTRY(test_bootstrap_json_contract_v3),
+    TEST_ENTRY(test_bootstrap_json_snapshot_consistency),
+    TEST_ENTRY(test_root_render_interleaved_context_isolation),
+    TEST_ENTRY(test_portal_presentation_configuration),
+    
+    // Non-blocking tests
+    TEST_ENTRY(test_nonblocking_process),
+    TEST_ENTRY(test_client_check_setters),
+    TEST_ENTRY(test_process_required_for_timeout),
+    
+    // Callback tests
+    TEST_ENTRY(test_ap_callback),
+    TEST_ENTRY(test_web_server_callback),
+    TEST_ENTRY(test_multiple_callbacks),
+    
+    // Parameter tests
+    TEST_ENTRY(test_create_parameter),
+    TEST_ENTRY(test_add_parameter),
+    TEST_ENTRY(test_get_parameters),
+    TEST_ENTRY(test_parameter_with_custom_html),
+    TEST_ENTRY(test_parameter_value_length),
+    TEST_ENTRY(test_parameter_label_placement),
+    TEST_ENTRY(test_multiple_parameters),
+    TEST_ENTRY(test_parameter_placeholder),
+    
+    // Static IP tests
+    TEST_ENTRY(test_set_ap_static_ip_config),
+    TEST_ENTRY(test_ap_static_ip_application),
+    
+    // WiFi connection tests
+    TEST_ENTRY(test_autoconnect_fallback_to_portal),
+    TEST_ENTRY(test_connectwifi_ssid_not_found),
+    TEST_ENTRY(test_connection_state_transitions),
+    TEST_ENTRY(test_autoconnect_with_timeout),
+    
+    // Callback firing tests
+    TEST_ENTRY(test_timeout_callback_fires),
+    TEST_ENTRY(test_config_reset_callback_fires),
+    TEST_ENTRY(test_ap_callback_fires_improved),
+    TEST_ENTRY(test_web_server_callback_fires_improved),
+    
+    // DNS lifecycle tests
+    TEST_ENTRY(test_dns_server_created),
+    TEST_ENTRY(test_dns_server_cleanup),
+    TEST_ENTRY(test_dns_server_lifecycle_cycles),
+    
+    // Error condition tests
+    TEST_ENTRY(test_connection_failure_handling),
+    TEST_ENTRY(test_resource_cleanup_after_error),
+    TEST_ENTRY(test_multiple_rapid_start_stop),
+    
+    // Parameter value tests
+    TEST_ENTRY(test_parameter_value_set_directly),
+    TEST_ENTRY(test_parameter_value_length_validation),
+    TEST_ENTRY(test_parameter_value_persistence),
+    TEST_ENTRY(test_parameter_value_update),
+    TEST_ENTRY(test_multiple_parameters_different_values),
+    
+    // WiFi scanning tests
+    TEST_ENTRY(test_wifi_scan_initiates),
+    TEST_ENTRY(test_async_scan_behavior),
+    TEST_ENTRY(test_scan_status_checking),
+    TEST_ENTRY(test_scan_completion_wait),
+    TEST_ENTRY(test_scan_cancels_when_connect_pending),
+    TEST_ENTRY(test_scan_cancels_when_lifecycle_blocked),
+    TEST_ENTRY(test_scan_generation_invalidated_on_reset),
+
+    TEST_ENTRY(test_real_async_scan_completes),
+    // Template rendering tests
+    TEST_ENTRY(test_shell_template_renders_core_placeholders),
+    TEST_ENTRY(test_shell_template_renders_dynamic_theme_with_percent_values),
+
+    // State transition tests
+    TEST_ENTRY(test_portal_to_connected_transition),
+    TEST_ENTRY(test_concurrent_operations),
+    TEST_ENTRY(test_state_consistency_during_portal),
+    TEST_ENTRY(test_state_transitions_multiple_cycles),
+    
+    // Integration tests
+    TEST_ENTRY(test_autoconnect_fallback_flow),
+    TEST_ENTRY(test_portal_lifecycle_with_connection_attempt),
+    TEST_ENTRY(test_parameter_add_and_retrieve),
+    TEST_ENTRY(test_complete_flow_reset_autoconnect_portal),
+    TEST_ENTRY(test_portal_with_parameters_and_infrastructure),
+    
+    // Stress tests
+    TEST_ENTRY(test_many_start_stop_cycles),
+    TEST_ENTRY(test_long_running_portal),
+    TEST_ENTRY(test_rapid_portal_start_stop),
+    TEST_ENTRY(test_multiple_parameters_stress),
+    TEST_ENTRY(test_portal_with_timeout_stress),
+    TEST_ENTRY(test_portal_resource_recovery),
+    TEST_ENTRY(test_scan_result_storage_released_when_portal_closes),
+};
+
+const size_t TEST_COUNT = sizeof(tests) / sizeof(TestCase);
+
+// Test state variables
+size_t next_index = 0;
+bool begun = false;
+
+// Test setup and teardown
+void setUp(void) {
+    // No per-test setup needed
+}
+
+void tearDown(void) {
+    // No per-test teardown needed
+}
+
+// Arduino setup and loop functions (required by framework)
+void setup() {
+    Serial.begin(115200);
+    delay(2000); // Give time for serial to initialize
+    
+    Serial.println("\n[TEST] =============================================");
+    Serial.println("[TEST] === WiFiManager Test Setup ===");
+    Serial.println("[TEST] Starting WiFiManager tests...");
+    Serial.println("[TEST] =============================================");
+    
+    UNITY_BEGIN(); // Start Unity test framework
+    begun = true; // Start tests immediately
+}
+
+void loop() {
+    // Run one test and return immediately
+    if (begun && next_index < TEST_COUNT) {
+        TestCase& t = tests[next_index];
+        Serial.print("\n[TEST] ==== Running test: ");
+        Serial.print(t.name);
+        Serial.println(" ====");
+        UnityDefaultTestRun(t.fn, t.name, t.line);
+        next_index++;
+        return; // yield quickly
+    }
+    
+    // All tests completed
+    if (begun && next_index >= TEST_COUNT) {
+        Serial.println("\n[TEST] =============================================");
+        Serial.println("[TEST] === All tests completed ===");
+        Serial.println("[TEST] =============================================");
+        UNITY_END(); // prints Unity summary
+        begun = false; // avoid repeating
+    }
+}

test/test_wifimanager/test_main.h

@@ -0,0 +1,149 @@
+#ifndef TEST_MAIN_H
+#define TEST_MAIN_H
+
+#include <Arduino.h>
+
+// Test function type
+using TestFn = void(*)();
+
+// Test case structure
+struct TestCase {
+    const char* name;
+    TestFn fn;
+    uint16_t line;
+};
+
+#define TEST_ENTRY(fn) { #fn, fn, __LINE__ }
+
+// Basic tests
+void test_basic_wifimanager_instantiation();
+void test_reset_settings();
+
+// Configuration tests
+void test_set_and_get_hostname();
+void test_get_default_ap_name();
+void test_get_wifi_status_string();
+void test_get_mode_string();
+void test_get_rssi_as_quality();
+
+// Portal lifecycle tests
+void test_start_config_portal();
+void test_start_config_portal_with_password();
+void test_start_config_portal_auto_name();
+void test_stop_config_portal();
+void test_config_portal_infrastructure();
+void test_start_web_portal();
+void test_stop_web_portal();
+void test_config_portal_multiple_start_stop();
+void test_config_portal_already_active();
+void test_get_config_portal_ssid();
+void test_bootstrap_json_portal_feature_flags();
+void test_portal_default_presentation();
+void test_bootstrap_json_contract_v3();
+void test_bootstrap_json_snapshot_consistency();
+void test_root_render_interleaved_context_isolation();
+void test_portal_presentation_configuration();
+
+// Non-blocking tests
+void test_nonblocking_process();
+void test_client_check_setters();
+void test_process_required_for_timeout();
+
+// Callback tests
+void test_ap_callback();
+void test_web_server_callback();
+void test_multiple_callbacks();
+
+// Parameter tests
+void test_create_parameter();
+void test_add_parameter();
+void test_get_parameters();
+void test_parameter_with_custom_html();
+void test_parameter_value_length();
+void test_parameter_label_placement();
+void test_multiple_parameters();
+void test_parameter_placeholder();
+
+// Static IP tests
+void test_set_ap_static_ip_config();
+void test_ap_static_ip_application();
+
+// Advanced options tests
+
+// WiFi connection tests
+void test_autoconnect_fallback_to_portal();
+void test_connectwifi_ssid_not_found();
+void test_connection_state_transitions();
+void test_autoconnect_with_timeout();
+
+// Callback firing tests
+void test_timeout_callback_fires();
+void test_config_reset_callback_fires();
+void test_ap_callback_fires_improved();
+void test_web_server_callback_fires_improved();
+
+// DNS lifecycle tests
+void test_dns_server_created();
+void test_dns_server_cleanup();
+void test_dns_server_lifecycle_cycles();
+
+// Error condition tests
+void test_connection_failure_handling();
+void test_resource_cleanup_after_error();
+void test_multiple_rapid_start_stop();
+
+// Parameter value tests
+void test_parameter_value_set_directly();
+void test_parameter_value_length_validation();
+void test_parameter_value_persistence();
+void test_parameter_value_update();
+void test_multiple_parameters_different_values();
+
+// WiFi scanning tests
+void test_wifi_scan_initiates();
+void test_async_scan_behavior();
+void test_scan_status_checking();
+void test_scan_completion_wait();
+void test_scan_cancels_when_connect_pending();
+void test_scan_cancels_when_lifecycle_blocked();
+void test_scan_generation_invalidated_on_reset();
+void test_real_async_scan_completes();
+
+// Template rendering tests
+void test_shell_template_renders_core_placeholders();
+void test_shell_template_renders_dynamic_theme_with_percent_values();
+
+// API JSON + captive helper tests
+void test_captive_redirect_host_rule();
+void test_api_wifi_meta_json_shape();
+void test_api_wifi_meta_password_field_type();
+void test_api_wifi_connect_status_success_redirect();
+void test_profile_portal_success_keeps_handoff_alive();
+void test_profile_portal_candidate_does_not_take_legacy_empty_ssid_path();
+void test_api_info_json_shape();
+void test_api_params_json_shape();
+void test_api_status_json_shape();
+
+// State transition tests
+void test_portal_to_connected_transition();
+void test_concurrent_operations();
+void test_state_consistency_during_portal();
+void test_state_transitions_multiple_cycles();
+
+// Integration tests
+void test_autoconnect_fallback_flow();
+void test_portal_lifecycle_with_connection_attempt();
+void test_parameter_add_and_retrieve();
+void test_complete_flow_reset_autoconnect_portal();
+void test_portal_with_parameters_and_infrastructure();
+
+// Stress tests
+void test_many_start_stop_cycles();
+void test_long_running_portal();
+void test_rapid_portal_start_stop();
+void test_multiple_parameters_stress();
+void test_portal_with_timeout_stress();
+void test_portal_resource_recovery();
+void test_scan_result_storage_released_when_portal_closes();
+
+#endif // TEST_MAIN_H

test/test_wifimanager/tests/test_advanced_options.cpp

@@ -0,0 +1,134 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+// Test advanced configuration options - consolidated into logical groups
+
+// Test connection behavior options
+void test_connection_behavior_options() {
+    Serial.println("[TEST]   Testing connection behavior options...");
+    
+    WiFiManager wm;
+    
+    // Test connection options
+    wm.setBreakAfterConfig(true);
+    wm.setBreakAfterConfig(false);
+    wm.setSaveConnect(true);
+    wm.setSaveConnect(false);
+    wm.setRestorePersistent(true);
+    wm.setRestorePersistent(false);
+    wm.setConnectRetries(1);
+    wm.setConnectRetries(3);
+    wm.setConnectRetries(5);
+    wm.setSaveConnectTimeout(0);
+    wm.setSaveConnectTimeout(10);
+    wm.setSaveConnectTimeout(30);
+    wm.setEnableConfigPortal(true);
+    wm.setEnableConfigPortal(false);
+    wm.setDisableConfigPortal(true);
+    wm.setDisableConfigPortal(false);
+    wm.portalSetBehaviorConnectOnSave(true);
+    wm.portalSetBehaviorConnectOnSave(false);
+    wm.portalSetBehaviorExitAllowed(true);
+    wm.portalSetBehaviorExitAllowed(false);
+    wm.portalSetBehaviorConnectTimeoutSeconds(15);
+    wm.portalSetBehaviorPortalTimeoutSeconds(20);
+    wm.portalSetBehaviorAutoReconnect(true);
+    wm.portalSetBehaviorAutoReconnect(false);
+    wm.portalSetBehaviorApClientCheck(true);
+    wm.portalSetBehaviorApClientCheck(false);
+    wm.portalSetBehaviorWebClientCheck(true);
+    wm.portalSetBehaviorWebClientCheck(false);
+    wm.preloadWiFi("TestSSID", "TestPassword");
+    
+    // All setters executed without crash
+    TEST_ASSERT_TRUE_MESSAGE(true, "Connection behavior options executed without crash");
+    
+    Serial.println("[TEST]   Connection behavior options test completed successfully");
+}
+
+// Test UI display options
+void test_ui_display_options() {
+    Serial.println("[TEST]   Testing UI display options...");
+    
+    WiFiManager wm;
+    
+    // Test display toggles
+    wm.portalSetFieldPasswordPlaceholderMode(PortalPasswordPlaceholderMode::Actual);
+    wm.portalSetFieldPasswordPlaceholderMode(PortalPasswordPlaceholderMode::Masked);
+    wm.portalSetFieldPasswordPlaceholderMode(PortalPasswordPlaceholderMode::Hidden);
+    wm.setScanDispPerc(true);
+    wm.setScanDispPerc(false);
+    wm.portalSetActionEraseVisible(true);
+    wm.portalSetActionEraseVisible(false);
+    wm.portalSetActionRestartVisible(true);
+    wm.portalSetActionRestartVisible(false);
+    wm.portalSetActionExitVisible(true);
+    wm.portalSetActionExitVisible(false);
+    wm.portalSetActionCloseCaptiveVisible(true);
+    wm.portalSetActionCloseCaptiveVisible(false);
+    wm.portalSetPageUpdateVisible(true);
+    wm.portalSetPageUpdateVisible(false);
+    wm.portalSetPageSetupVisible(true);
+    wm.portalSetPageSetupVisible(false);
+    wm.portalSetLayoutParamsLocation(PortalParamsLocation::WiFiPage);
+    wm.portalSetLayoutParamsLocation(PortalParamsLocation::SetupPage);
+    wm.portalSetActionBackVisible(true);
+    wm.portalSetActionBackVisible(false);
+    
+    // All setters executed without crash
+    TEST_ASSERT_TRUE_MESSAGE(true, "UI display options executed without crash");
+    
+    Serial.println("[TEST]   UI display options test completed successfully");
+}
+
+// Test custom HTML/UI customization
+void test_ui_customization() {
+    Serial.println("[TEST]   Testing UI customization...");
+    
+    WiFiManager wm;
+    
+    // Minimal customization uses the complete static portal configuration.
+    WiFiManagerPortalConfig portal;
+    portal.title = WiFiManagerPortalText::ram("MyDevice");
+    TEST_ASSERT_TRUE(wm.setPortalConfig(portal));
+    
+    // All setters executed without crash
+    TEST_ASSERT_TRUE_MESSAGE(true, "UI customization options executed without crash");
+    
+    Serial.println("[TEST]   UI customization test completed successfully");
+}
+
+void test_debug_soft_ap_config() {
+    Serial.println("[TEST]   Testing debugSoftAPConfig()...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(5);
+    
+    wm.startConfigPortal("TestAP");
+    
+    // Call process() to simulate real usage
+    wm.process();
+    delay(100);
+    
+    // Debug output should not crash
+    wm.debugSoftAPConfig();
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   debugSoftAPConfig() test completed successfully");
+}
+
+void test_debug_platform_info() {
+    Serial.println("[TEST]   Testing debugPlatformInfo()...");
+    
+    WiFiManager wm;
+    
+    // Debug output should not crash
+    wm.debugPlatformInfo();
+    
+    TEST_ASSERT_TRUE_MESSAGE(true, "debugPlatformInfo() executed without crash");
+    
+    Serial.println("[TEST]   debugPlatformInfo() test completed successfully");
+}
+

test/test_wifimanager/tests/test_api_json_and_captive.cpp

@@ -0,0 +1,182 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <string.h>
+#include <WiFiManager.h>
+#include <WiFiManagerHandlers.h>
+#include "../test_main.h"
+
+void test_captive_redirect_host_rule() {
+    Serial.println("[TEST]   Testing captive redirect host comparison...");
+
+    TEST_ASSERT_TRUE(WiFiManagerHandlers::shouldRedirectCaptiveForHost("captive.apple.com", "192.168.4.1"));
+    TEST_ASSERT_TRUE(WiFiManagerHandlers::shouldRedirectCaptiveForHost("192.168.4.2", "192.168.4.1"));
+    TEST_ASSERT_FALSE(WiFiManagerHandlers::shouldRedirectCaptiveForHost("192.168.4.1", "192.168.4.1"));
+    TEST_ASSERT_FALSE(WiFiManagerHandlers::shouldRedirectCaptiveForHost("example.com", ""));
+
+    Serial.println("[TEST]   Captive redirect host rule test completed successfully");
+}
+
+void test_api_wifi_meta_json_shape() {
+    Serial.println("[TEST]   Testing /api/wifi/meta JSON shape...");
+
+    WiFiManager wm;
+    WiFiManagerHandlers handlers(&wm);
+    String j = handlers.buildApiWifiMetaJson();
+
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"wifiFields\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"staticFields\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"params\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"actions\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"canRefreshScan\":true")));
+
+    WiFiManagerParameter fieldParam("mqtt_host", "MQTT host", "broker.local", 64, "placeholder='broker.local'");
+    WiFiManagerParameter htmlParam("<div class='wm-callout wm-callout--info'><p>GPS settings...</p></div>");
+    wm.portalAddParameter(&fieldParam);
+    wm.portalAddParameter(&htmlParam);
+    j = handlers.buildApiWifiMetaJson();
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"kind\":\"field\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"kind\":\"html\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"html\":\"<div class='wm-callout wm-callout--info'><p>GPS settings...</p></div>\"}")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"wifiFields\":[{\"id\":\"s\"")));
+
+    Serial.println("[TEST]   WiFi meta JSON shape test completed successfully");
+}
+
+void test_api_wifi_meta_password_field_type() {
+    Serial.println("[TEST]   Testing /api/wifi/meta password field type from custom attrs...");
+
+    WiFiManager wm;
+    WiFiManagerHandlers handlers(&wm);
+    WiFiManagerParameter pwd("mqttpass", "MQTT password", "secret", 24, " type='password' autocorrect='off'");
+    wm.portalAddParameter(&pwd);
+
+    String j = handlers.buildApiWifiMetaJson();
+    const char* p = j.c_str();
+    const char* chunk = strstr(p, "\"id\":\"mqttpass\"");
+    TEST_ASSERT_NOT_NULL_MESSAGE(chunk, "mqttpass param missing from meta JSON");
+    TEST_ASSERT_NOT_NULL_MESSAGE(strstr(chunk, "\"type\":\"password\""),
+                                 "customAttrs type=password must map to JSON type password");
+
+    Serial.println("[TEST]   WiFi meta password field type test completed successfully");
+}
+
+void test_api_wifi_connect_status_success_redirect() {
+    Serial.println("[TEST]   Testing /api/wifi/connect-status success redirect payload...");
+
+    WiFiManager wm;
+    WiFiManagerHandlers handlers(&wm);
+#ifdef UNIT_TEST
+    wm.wmTestSetPortalConnectSuccess("WiFi connected. Redirecting to 192.168.1.42", "192.168.1.42");
+#endif
+    String j = handlers.buildApiWifiConnectStatusJson();
+    const char* p = j.c_str();
+
+    TEST_ASSERT_NOT_NULL(strstr(p, "\"state\":\"success\""));
+    TEST_ASSERT_NOT_NULL(strstr(p, "\"stationIp\":\"192.168.1.42\""));
+    TEST_ASSERT_NOT_NULL(strstr(p, "\"redirectUrl\":\"http://192.168.1.42/\""));
+
+    Serial.println("[TEST]   WiFi connect-status success redirect payload test completed successfully");
+}
+
+void test_profile_portal_success_keeps_handoff_alive() {
+    Serial.println("[TEST]   Testing profile portal success hand-off delay...");
+
+    WiFiManager wm;
+#ifdef UNIT_TEST
+    wm.wmTestCompleteProfilePortalConnectionSuccess();
+    TEST_ASSERT_EQUAL(WiFiManager::WM_CP_CONNECT_SUCCESS, wm.getConfigPortalConnectState());
+    TEST_ASSERT_TRUE_MESSAGE(
+        wm.isConfigPortalConnectPending(),
+        "Profile-backed portal success must remain pending while the client reads the redirect response"
+    );
+#else
+    TEST_IGNORE_MESSAGE("UNIT_TEST helpers unavailable");
+#endif
+
+    Serial.println("[TEST]   Profile portal success hand-off delay test completed successfully");
+}
+
+void test_profile_portal_candidate_does_not_take_legacy_empty_ssid_path() {
+    Serial.println("[TEST]   Testing profile portal candidate state ownership...");
+
+    WiFiManager wm;
+#ifdef UNIT_TEST
+    WiFiManagerStationProfiles candidate;
+    candidate.slots[0].enabled = true;
+    snprintf(candidate.slots[0].ssid, sizeof(candidate.slots[0].ssid), "%s", "candidate-network");
+    wm.wmTestSetWebPortalActive(true);
+    TEST_ASSERT_TRUE(wm.startStationCandidate(candidate));
+    wm.process();
+    TEST_ASSERT_EQUAL_MESSAGE(
+        WiFiManager::WM_CP_CONNECT_WAITING,
+        wm.getConfigPortalConnectState(),
+        "A web-portal profile candidate must not be treated as the legacy empty-SSID save path"
+    );
+#else
+    TEST_IGNORE_MESSAGE("UNIT_TEST helpers unavailable");
+#endif
+
+    Serial.println("[TEST]   Profile portal candidate state ownership test completed successfully");
+}
+
+void test_api_info_json_shape() {
+    Serial.println("[TEST]   Testing /api/info JSON shape...");
+
+    WiFiManager wm;
+    WiFiManagerHandlers handlers(&wm);
+    PortalInfoSection battery;
+    battery.id = "battery";
+    battery.title = "Battery";
+    battery.items.push_back({"soc", "State of charge", "84%"});
+    battery.items.push_back({"voltage", "Voltage", "13.2V"});
+    wm.portalAddInfoSection(battery);
+    String j = handlers.buildApiInfoJson();
+    const char* p = j.c_str();
+    // Shape checks only: "status" is a nested object (},\n"device" not ],"device"); require
+    // a tail marker so we know the full String was built (heap is OK). Middle sections
+    // (wifi / about) are not asserted — long runs fragment heap and can truncate long JSONs.
+    TEST_ASSERT_NOT_NULL(p);
+    TEST_ASSERT_GREATER_THAN_INT_MESSAGE(200, (int)j.length(),
+                                         "api/info body unexpectedly short; likely heap/fragmentation");
+    TEST_ASSERT_NOT_NULL(strstr(p, "\"status\":"));
+    TEST_ASSERT_NOT_NULL(strstr(p, "\"connected\":"));
+    TEST_ASSERT_NOT_NULL(strstr(p, "},\"device\":["));
+    TEST_ASSERT_NOT_NULL(strstr(p, "\"extraSections\":"));
+    TEST_ASSERT_NOT_NULL(strstr(p, "\"id\":\"battery\""));
+    TEST_ASSERT_NOT_NULL(strstr(p, "\"title\":\"Battery\""));
+    TEST_ASSERT_NOT_NULL(strstr(p, "\"label\":\"State of charge\""));
+    TEST_ASSERT_NOT_NULL(strstr(p, "\"showUpdate\":"));
+    TEST_ASSERT_NOT_NULL(strstr(p, "\"key\":\"aboutver\",\"label\":\"WiFiManager\",\"value\":\""));
+    TEST_ASSERT_NOT_NULL(strstr(p, "\"},{\"key\":\"aboutarduinover\""));
+
+    Serial.println("[TEST]   API info JSON shape test completed successfully");
+}
+
+void test_api_params_json_shape() {
+    Serial.println("[TEST]   Testing /api/params JSON shape...");
+
+    WiFiManager wm;
+    WiFiManagerHandlers handlers(&wm);
+    String j = handlers.buildApiParamsGetJson();
+
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"params\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"actions\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"showBack\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"params\":[")));
+
+    Serial.println("[TEST]   API params JSON shape test completed successfully");
+}
+
+void test_api_status_json_shape() {
+    Serial.println("[TEST]   Testing /api/status JSON shape...");
+
+    WiFiManager wm;
+    WiFiManagerHandlers handlers(&wm);
+    String j = handlers.buildApiStatusJson();
+
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"text\"")));
+    TEST_ASSERT_EQUAL('{', j.charAt(0));
+    TEST_ASSERT_EQUAL('}', j.charAt(j.length() - 1));
+
+    Serial.println("[TEST]   API status JSON shape test completed successfully");
+}

test/test_wifimanager/tests/test_basic.cpp

@@ -0,0 +1,71 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+#include "../test_main.h"
+
+// Test basic WiFiManager instantiation
+void test_basic_wifimanager_instantiation() {
+    Serial.println("[TEST]   Testing basic WiFiManager instantiation...");
+    
+    // Test default constructor
+    WiFiManager wm;
+
+    // Test that we can call basic methods without crashing
+    String defaultName = wm.getDefaultAPName();
+    TEST_ASSERT_GREATER_THAN(0, defaultName.length());
+    
+    // Test default state - portal should not be active
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    TEST_ASSERT_FALSE(wm.getWebPortalActive());
+    
+    Serial.println("[TEST]   Basic WiFiManager instantiation test completed successfully");
+}
+
+// Test resetSettings clears credentials
+void test_reset_settings() {
+    Serial.println("[TEST]   Testing resetSettings()...");
+    
+    WiFiManager wm;
+    
+    // Ensure WiFi is in a stable state before resetting
+    delay(100);
+    
+    // Reset settings (should not crash)
+    wm.resetSettings();
+    
+    // Small delay to allow WiFi operations to complete
+    delay(100);
+    
+    // Verify WiFi is not saved after reset
+    // Note: ESP32 uses NVS for WiFi credentials which behaves differently than ESP8266's EEPROM
+    // On ESP32, getWiFiIsSaved() may still return TRUE due to NVS persistence differences
+    #ifdef ESP32
+        // ESP32: Due to NVS behavior, getWiFiIsSaved() may return TRUE even after resetSettings()
+        // This is a known platform difference - the reset is still effective, just detected differently
+        bool wifiIsSaved = wm.getWiFiIsSaved();
+        TEST_ASSERT_TRUE_MESSAGE(true, "resetSettings() executed on ESP32 (NVS behavior differs from ESP8266)");
+        Serial.print("[TEST]   ESP32: getWiFiIsSaved() = ");
+        Serial.println(wifiIsSaved ? "TRUE" : "FALSE");
+    #else
+        // ESP8266: Should return FALSE after resetSettings()
+        TEST_ASSERT_FALSE(wm.getWiFiIsSaved());
+    #endif
+    
+    Serial.println("[TEST]   resetSettings() test completed successfully");
+}
+
+// Test disconnect - verify it doesn't crash and can be called multiple times
+void test_disconnect() {
+    Serial.println("[TEST]   Testing disconnect()...");
+    
+    WiFiManager wm;
+    
+    // Disconnect should not crash even if not connected
+    (void)wm.disconnect();
+    
+    // Can be called multiple times safely
+    (void)wm.disconnect();
+    
+    Serial.println("[TEST]   disconnect() test completed successfully");
+}
+

test/test_wifimanager/tests/test_callback_firing.cpp

@@ -0,0 +1,129 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+#include "../test_main.h"
+
+// Callback flags (static to avoid duplicate definitions)
+static bool timeout_callback_fired = false;
+static bool config_reset_callback_fired = false;
+
+// Callback functions (static to avoid duplicate definitions)
+static void timeout_callback() {
+    timeout_callback_fired = true;
+}
+
+static void config_reset_callback() {
+    config_reset_callback_fired = true;
+}
+
+// Reset callback flags (static to avoid duplicate definitions)
+static void reset_callback_flags() {
+    timeout_callback_fired = false;
+    config_reset_callback_fired = false;
+}
+
+// Test timeout callback fires
+void test_timeout_callback_fires() {
+    Serial.println("[TEST]   Testing timeout callback firing...");
+    
+    reset_callback_flags();
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeoutCallback(timeout_callback);
+    
+    wm.setConfigPortalTimeout(2); // 2 second timeout
+    wm.startConfigPortal("TestAP");
+    
+    // Process until timeout
+    unsigned long start = millis();
+    while (wm.getConfigPortalActive() && (millis() - start < 5000)) {
+        wm.process();
+        delay(50);
+    }
+    
+    // Callback should have fired when timeout occurred
+    TEST_ASSERT_TRUE(timeout_callback_fired);
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Timeout callback firing test completed successfully");
+}
+
+// Test config reset callback fires
+void test_config_reset_callback_fires() {
+    Serial.println("[TEST]   Testing config reset callback firing...");
+    
+    reset_callback_flags();
+    
+    WiFiManager wm;
+    wm.setConfigResetCallback(config_reset_callback);
+    
+    // Ensure WiFi is in a stable state before resetting
+    delay(100);
+    
+    // Call resetSettings which should trigger callback
+    wm.resetSettings();
+    
+    // Allow WiFi operations to complete
+    delay(100);
+    
+    // Callback should have fired
+    TEST_ASSERT_TRUE(config_reset_callback_fired);
+    
+    Serial.println("[TEST]   Config reset callback firing test completed successfully");
+}
+
+// Test AP callback fires (improve existing test)
+void test_ap_callback_fires_improved() {
+    Serial.println("[TEST]   Testing AP callback firing (improved)...");
+    
+    bool ap_callback_fired = false;
+    
+    WiFiManager wm;
+    wm.setAPCallback([&](WiFiManager* wm) {
+        ap_callback_fired = true;
+        (void)wm; // Suppress unused parameter warning
+    });
+    
+    wm.setConfigPortalTimeout(5);
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    
+    // Callback should have fired when AP starts
+    TEST_ASSERT_TRUE(ap_callback_fired);
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   AP callback firing (improved) test completed successfully");
+}
+
+// Test web server callback fires (improve existing test)
+void test_web_server_callback_fires_improved() {
+    Serial.println("[TEST]   Testing web server callback firing (improved)...");
+    
+    bool web_server_callback_fired = false;
+    
+    WiFiManager wm;
+    wm.setWebServerCallback([&]() {
+        web_server_callback_fired = true;
+    });
+    
+    wm.setConfigPortalTimeout(5);
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    
+    // Wait for server to initialize
+    unsigned long start = millis();
+    while (!web_server_callback_fired && (millis() - start < 1000)) {
+        wm.process();
+        delay(10);
+    }
+    
+    // Callback should have fired when server starts
+    TEST_ASSERT_TRUE(web_server_callback_fired);
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Web server callback firing (improved) test completed successfully");
+}
+

test/test_wifimanager/tests/test_callbacks.cpp

@@ -0,0 +1,165 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+// Callback flags
+bool ap_callback_fired = false;
+bool web_server_callback_fired = false;
+bool save_config_callback_fired = false;
+bool pre_save_config_callback_fired = false;
+bool save_params_callback_fired = false;
+bool pre_save_params_callback_fired = false;
+bool config_reset_callback_fired = false;
+bool config_portal_timeout_callback_fired = false;
+
+// Callback functions
+void ap_callback(WiFiManager* wm) {
+    ap_callback_fired = true;
+}
+
+void web_server_callback() {
+    web_server_callback_fired = true;
+}
+
+void save_config_callback() {
+    save_config_callback_fired = true;
+}
+
+void pre_save_config_callback() {
+    pre_save_config_callback_fired = true;
+}
+
+void save_params_callback(WiFiManager::WiFiManagerRequestArgs requestArgs) {
+    save_params_callback_fired = true;
+    // Test that we can access request args
+    (void)requestArgs; // Suppress unused variable warning
+}
+
+void pre_save_params_callback() {
+    pre_save_params_callback_fired = true;
+}
+
+void config_reset_callback() {
+    config_reset_callback_fired = true;
+}
+
+void config_portal_timeout_callback() {
+    config_portal_timeout_callback_fired = true;
+}
+
+// Reset all callback flags
+void reset_callback_flags() {
+    ap_callback_fired = false;
+    web_server_callback_fired = false;
+    save_config_callback_fired = false;
+    pre_save_config_callback_fired = false;
+    save_params_callback_fired = false;
+    pre_save_params_callback_fired = false;
+    config_reset_callback_fired = false;
+    config_portal_timeout_callback_fired = false;
+}
+
+void test_ap_callback() {
+    Serial.println("[TEST]   Testing AP callback...");
+    
+    reset_callback_flags();
+    
+    WiFiManager wm;
+    wm.setAPCallback(ap_callback);
+    wm.setConfigPortalTimeout(5);
+    
+    wm.startConfigPortal("TestAP");
+    
+    // Call process() to ensure portal is fully initialized
+    wm.process();
+    
+    // Callback should have fired when AP starts
+    TEST_ASSERT_TRUE(ap_callback_fired);
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   AP callback test completed successfully");
+}
+
+void test_web_server_callback() {
+    Serial.println("[TEST]   Testing web server callback...");
+    
+    reset_callback_flags();
+    
+    WiFiManager wm;
+    wm.setWebServerCallback(web_server_callback);
+    wm.setConfigPortalTimeout(5);
+    
+    wm.startConfigPortal("TestAP");
+    
+    // Call process() to ensure server is initialized
+    wm.process();
+    delay(100); // Give time for server to start
+    
+    // Callback should have fired when server starts
+    TEST_ASSERT_TRUE(web_server_callback_fired);
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Web server callback test completed successfully");
+}
+
+// Test callback registration - verify all callbacks can be registered without crash
+void test_callback_registration() {
+    Serial.println("[TEST]   Testing callback registration...");
+    
+    reset_callback_flags();
+    
+    WiFiManager wm;
+    
+    // Register all callbacks - verify registration doesn't crash
+    wm.setConfigResetCallback(config_reset_callback);
+    wm.setSaveConfigCallback(save_config_callback);
+    wm.setPreSaveConfigCallback(pre_save_config_callback);
+    wm.setSaveParamsCallback(save_params_callback);
+    wm.setPreSaveParamsCallback(pre_save_params_callback);
+    wm.setConfigPortalTimeoutCallback(config_portal_timeout_callback);
+    
+    // Call resetSettings to verify callback registration doesn't interfere
+    wm.resetSettings();
+    
+    // Verify registration doesn't crash
+    TEST_ASSERT_TRUE_MESSAGE(true, "All callbacks registered without crash");
+    
+    Serial.println("[TEST]   Callback registration test completed successfully");
+}
+
+void test_multiple_callbacks() {
+    Serial.println("[TEST]   Testing multiple callbacks together...");
+    
+    reset_callback_flags();
+    
+    WiFiManager wm;
+    
+    // Register all callbacks
+    wm.setAPCallback(ap_callback);
+    wm.setWebServerCallback(web_server_callback);
+    wm.setSaveConfigCallback(save_config_callback);
+    wm.setPreSaveConfigCallback(pre_save_config_callback);
+    wm.setSaveParamsCallback(save_params_callback);
+    wm.setPreSaveParamsCallback(pre_save_params_callback);
+    wm.setConfigResetCallback(config_reset_callback);
+    wm.setConfigPortalTimeoutCallback(config_portal_timeout_callback);
+    
+    // Start portal - should fire AP and web server callbacks
+    wm.setConfigPortalTimeout(5);
+    wm.startConfigPortal("TestAP");
+    
+    // Call process() to ensure portal is fully initialized
+    wm.process();
+    delay(100);
+    
+    // Verify AP callback fired
+    TEST_ASSERT_TRUE(ap_callback_fired);
+    TEST_ASSERT_TRUE(web_server_callback_fired);
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Multiple callbacks test completed successfully");
+}
+

test/test_wifimanager/tests/test_configuration.cpp

@@ -0,0 +1,182 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+// Test configuration API methods
+// Consolidated setter tests - verify setters don't crash and can be called multiple times
+void test_configuration_setters() {
+    Serial.println("[TEST]   Testing configuration setters...");
+    
+    WiFiManager wm;
+    
+    // Test timeout setters
+    wm.setConfigPortalTimeout(0);
+    wm.setConfigPortalTimeout(30);
+    wm.setConfigPortalTimeout(300);
+    wm.setConnectTimeout(0);
+    wm.setConnectTimeout(20);
+    wm.setConnectTimeout(60);
+    
+    // Test HTTP port
+    wm.setHttpPort(80);
+    wm.setHttpPort(8080);
+    
+    // Test WiFi quality and filtering
+    wm.setMinimumSignalQuality(-1); // Disable filter
+    wm.setMinimumSignalQuality(0);
+    wm.setMinimumSignalQuality(50);
+    wm.setMinimumSignalQuality(100);
+    wm.setRemoveDuplicateAPs(true);
+    wm.setRemoveDuplicateAPs(false);
+    
+    // Test display options
+    wm.setShowStaticFields(true);
+    wm.setShowStaticFields(false);
+    wm.setShowDnsFields(true);
+    wm.setShowDnsFields(false);
+    
+    // Test portal behavior
+    wm.portalSetBehaviorCaptivePortalEnabled(true);
+    wm.portalSetBehaviorCaptivePortalEnabled(false);
+    
+    // Test the typed portal presentation path.
+    WiFiManagerPortalConfig portal;
+    portal.title = WiFiManagerPortalText::ram("TestTitle");
+    TEST_ASSERT_TRUE(wm.setPortalConfig(portal));
+
+    // Call setters multiple times with different values.
+    wm.setConfigPortalTimeout(60);
+    wm.setConnectTimeout(30);
+    wm.setHttpPort(8080);
+    wm.setMinimumSignalQuality(50);
+    
+    Serial.println("[TEST]   Configuration setters test completed successfully");
+}
+
+// Test hostname setter/getter - can verify behavior
+void test_set_and_get_hostname() {
+    Serial.println("[TEST]   Testing setHostname() and getWiFiHostname()...");
+    
+    WiFiManager wm;
+    
+    TEST_ASSERT_TRUE_MESSAGE(wm.setHostname("test-hostname"), "Valid char* hostname should be accepted");
+    TEST_ASSERT_TRUE_MESSAGE(wm.setHostname(String("  trimmed-hostname  ")), "Valid String hostname should be trimmed and accepted");
+    TEST_ASSERT_TRUE_MESSAGE(wm.setHostname(""), "Empty hostname should clear the configured hostname");
+
+    String tooLongHostname = "123456789012345678901234567890123";
+    TEST_ASSERT_FALSE_MESSAGE(wm.setHostname(tooLongHostname), "Hostnames longer than 32 chars should be rejected");
+    TEST_ASSERT_FALSE_MESSAGE(wm.setHostname("bad host"), "Hostnames with spaces should be rejected");
+    TEST_ASSERT_FALSE_MESSAGE(wm.setHostname("-leading"), "Hostnames cannot start with a hyphen");
+    TEST_ASSERT_FALSE_MESSAGE(wm.setHostname("trailing-"), "Hostnames cannot end with a hyphen");
+
+    (void)wm.getWiFiHostname();
+    
+    Serial.println("[TEST]   setHostname() and getWiFiHostname() test completed successfully");
+}
+
+// Test WiFi AP configuration setters - consolidated
+void test_wifi_ap_configuration_setters() {
+    Serial.println("[TEST]   Testing WiFi AP configuration setters...");
+    
+    WiFiManager wm;
+    
+    // Test AP channel
+    wm.setWiFiAPChannel(0);  // Auto
+    wm.setWiFiAPChannel(1);
+    wm.setWiFiAPChannel(11);
+    
+    // Test AP hidden
+    wm.setWiFiAPHidden(true);
+    wm.setWiFiAPHidden(false);
+    
+    // Test country code
+    wm.setCountry("US");
+    wm.setCountry("CN");
+    
+    // Test clean connect
+    wm.setCleanConnect(true);
+    wm.setCleanConnect(false);
+    
+    // Test auto reconnect
+    wm.setWiFiAutoReconnect(true);
+    wm.setWiFiAutoReconnect(false);
+    
+    Serial.println("[TEST]   WiFi AP configuration setters test completed successfully");
+}
+
+void test_get_default_ap_name() {
+    Serial.println("[TEST]   Testing getDefaultAPName()...");
+    
+    WiFiManager wm;
+    
+    String apName = wm.getDefaultAPName();
+    
+    // Should return a non-empty string (chip ID based)
+    TEST_ASSERT_GREATER_THAN(0, apName.length());
+    
+    Serial.println("[TEST]   getDefaultAPName() test completed successfully");
+}
+
+void test_get_wifi_status_string() {
+    Serial.println("[TEST]   Testing getWLStatusString()...");
+    
+    WiFiManager wm;
+    
+    // Test with status code
+    String status1 = wm.getWLStatusString(WL_IDLE_STATUS);
+    String status2 = wm.getWLStatusString(WL_CONNECTED);
+    String status3 = wm.getWLStatusString(WL_DISCONNECTED);
+    
+    // All should return non-empty strings
+    TEST_ASSERT_GREATER_THAN(0, status1.length());
+    TEST_ASSERT_GREATER_THAN(0, status2.length());
+    TEST_ASSERT_GREATER_THAN(0, status3.length());
+    
+    // Test without parameter (uses current WiFi.status())
+    String status4 = wm.getWLStatusString();
+    TEST_ASSERT_GREATER_THAN(0, status4.length());
+    
+    Serial.println("[TEST]   getWLStatusString() test completed successfully");
+}
+
+void test_get_mode_string() {
+    Serial.println("[TEST]   Testing getModeString()...");
+    
+    WiFiManager wm;
+    
+    String mode1 = wm.getModeString(WIFI_OFF);
+    String mode2 = wm.getModeString(WIFI_STA);
+    String mode3 = wm.getModeString(WIFI_AP);
+    String mode4 = wm.getModeString(WIFI_AP_STA);
+    
+    // All should return non-empty strings
+    TEST_ASSERT_GREATER_THAN(0, mode1.length());
+    TEST_ASSERT_GREATER_THAN(0, mode2.length());
+    TEST_ASSERT_GREATER_THAN(0, mode3.length());
+    TEST_ASSERT_GREATER_THAN(0, mode4.length());
+    
+    Serial.println("[TEST]   getModeString() test completed successfully");
+}
+
+void test_get_rssi_as_quality() {
+    Serial.println("[TEST]   Testing getRSSIasQuality()...");
+    
+    WiFiManager wm;
+    
+    // Test various RSSI values
+    int quality1 = wm.getRSSIasQuality(-30);  // Very strong
+    int quality2 = wm.getRSSIasQuality(-70);  // Good
+    int quality3 = wm.getRSSIasQuality(-90);  // Weak
+    
+    // Quality should be 0-100
+    TEST_ASSERT_GREATER_OR_EQUAL(0, quality1);
+    TEST_ASSERT_LESS_OR_EQUAL(100, quality1);
+    TEST_ASSERT_GREATER_OR_EQUAL(0, quality2);
+    TEST_ASSERT_LESS_OR_EQUAL(100, quality2);
+    
+    // Stronger signal should have higher quality
+    TEST_ASSERT_GREATER_THAN(quality3, quality1);
+    
+    Serial.println("[TEST]   getRSSIasQuality() test completed successfully");
+}
+

test/test_wifimanager/tests/test_dns_lifecycle.cpp

@@ -0,0 +1,101 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+#include "../test_main.h"
+
+// Test DNS server is created when portal starts
+void test_dns_server_created() {
+    Serial.println("[TEST]   Testing DNS server creation...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(10);
+    
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    
+    // Wait for DNS server to be created
+    unsigned long start = millis();
+    while (!wm.getDNSServer() && (millis() - start < 1000)) {
+        wm.process();
+        delay(10);
+    }
+    
+    // DNS server should be created when portal starts
+    TEST_ASSERT_NOT_NULL(wm.getDNSServer());
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   DNS server creation test completed successfully");
+}
+
+// Test DNS server cleanup when portal stops
+void test_dns_server_cleanup() {
+    Serial.println("[TEST]   Testing DNS server cleanup...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(10);
+    
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    
+    // Wait for DNS server to be created
+    unsigned long start = millis();
+    while (!wm.getDNSServer() && (millis() - start < 1000)) {
+        wm.process();
+        delay(10);
+    }
+    
+    // Verify DNS server exists
+    TEST_ASSERT_NOT_NULL(wm.getDNSServer());
+    
+    // Stop portal
+    wm.stopConfigPortal();
+    wm.process();
+    
+    // DNS server should be cleaned up (set to nullptr or deleted)
+    // Note: Actual cleanup verification depends on implementation
+    // For now, verify portal is stopped
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    Serial.println("[TEST]   DNS server cleanup test completed successfully");
+}
+
+// Test DNS server lifecycle with multiple start/stop cycles
+void test_dns_server_lifecycle_cycles() {
+    Serial.println("[TEST]   Testing DNS server lifecycle with multiple cycles...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(10);
+    
+    // Cycle 1
+    wm.startConfigPortal("TestAP1");
+    wm.process();
+    
+    unsigned long start = millis();
+    while (!wm.getDNSServer() && (millis() - start < 1000)) {
+        wm.process();
+        delay(10);
+    }
+    TEST_ASSERT_NOT_NULL(wm.getDNSServer());
+    
+    wm.stopConfigPortal();
+    wm.process();
+    delay(200);
+    
+    // Cycle 2
+    wm.startConfigPortal("TestAP2");
+    wm.process();
+    
+    start = millis();
+    while (!wm.getDNSServer() && (millis() - start < 1000)) {
+        wm.process();
+        delay(10);
+    }
+    TEST_ASSERT_NOT_NULL(wm.getDNSServer());
+    
+    wm.stopConfigPortal();
+    wm.process();
+    
+    Serial.println("[TEST]   DNS server lifecycle cycles test completed successfully");
+}
+

test/test_wifimanager/tests/test_error_conditions.cpp

@@ -0,0 +1,181 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+#include "../test_main.h"
+
+// Test invalid AP password (too short)
+void test_invalid_ap_password_too_short() {
+    Serial.println("[TEST]   Testing invalid AP password (too short)...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(5);
+    
+    // Password < 8 chars - should handle gracefully
+    wm.startConfigPortal("TestAP", "short"); // < 8 chars
+    
+    // Portal should either not start or use default behavior
+    // Verify it doesn't crash
+    wm.process();
+    
+    // Portal may or may not be active (implementation dependent)
+    // Just verify no crash
+    if (wm.getConfigPortalActive()) {
+        wm.stopConfigPortal();
+    }
+    
+    TEST_ASSERT_TRUE_MESSAGE(true, "Invalid AP password (too short) handled without crash");
+    
+    Serial.println("[TEST]   Invalid AP password (too short) test completed successfully");
+}
+
+// Test invalid AP password (too long)
+void test_invalid_ap_password_too_long() {
+    Serial.println("[TEST]   Testing invalid AP password (too long)...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(5);
+    
+    // Password > 63 chars - should handle gracefully
+    String longPassword = String('a', 64); // 64 chars
+    wm.startConfigPortal("TestAP", longPassword.c_str());
+    
+    // Portal should handle gracefully
+    wm.process();
+    
+    // Portal may or may not be active (implementation dependent)
+    // Just verify no crash
+    if (wm.getConfigPortalActive()) {
+        wm.stopConfigPortal();
+    }
+    
+    TEST_ASSERT_TRUE_MESSAGE(true, "Invalid AP password (too long) handled without crash");
+    
+    Serial.println("[TEST]   Invalid AP password (too long) test completed successfully");
+}
+
+// Test empty SSID
+void test_empty_ssid() {
+    Serial.println("[TEST]   Testing empty SSID...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(5);
+    
+    // Empty SSID - should use default AP name
+    wm.startConfigPortal(""); // Empty SSID
+    
+    wm.process();
+    
+    // Portal should start with default name or handle gracefully
+    if (wm.getConfigPortalActive()) {
+        String ssid = wm.getConfigPortalSSID();
+        // Should have a valid SSID (either default or empty handled)
+        TEST_ASSERT_TRUE_MESSAGE(true, "Empty SSID handled gracefully");
+        wm.stopConfigPortal();
+    } else {
+        TEST_ASSERT_TRUE_MESSAGE(true, "Empty SSID handled gracefully (portal not started)");
+    }
+    
+    Serial.println("[TEST]   Empty SSID test completed successfully");
+}
+
+// Test very long SSID
+void test_very_long_ssid() {
+    Serial.println("[TEST]   Testing very long SSID...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(5);
+    
+    // Very long SSID (> 32 chars) - should handle gracefully
+    String longSSID = String('A', 64); // 64 chars
+    wm.startConfigPortal(longSSID.c_str());
+    
+    wm.process();
+    
+    // Portal should handle gracefully (may truncate or reject)
+    if (wm.getConfigPortalActive()) {
+        wm.stopConfigPortal();
+    }
+    
+    TEST_ASSERT_TRUE_MESSAGE(true, "Very long SSID handled without crash");
+    
+    Serial.println("[TEST]   Very long SSID test completed successfully");
+}
+
+// Test connection failure handling
+void test_connection_failure_handling() {
+    Serial.println("[TEST]   Testing connection failure handling...");
+    
+    WiFiManager wm;
+    delay(100); // Ensure WiFi is in a stable state
+    wm.resetSettings(); // Clear saved credentials
+    delay(100); // Allow WiFi operations to complete
+    
+    // Attempt connection via autoConnect (will fail)
+    wm.setConfigPortalTimeout(5);
+    bool result = wm.autoConnect("TestAP");
+    
+    // Should handle failure gracefully
+    TEST_ASSERT_FALSE(result);
+    
+    // Verify WiFi state is consistent
+    wl_status_t status = WiFi.status();
+    TEST_ASSERT_NOT_EQUAL(WL_CONNECTED, status);
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Connection failure handling test completed successfully");
+}
+
+// Test resource cleanup after error
+void test_resource_cleanup_after_error() {
+    Serial.println("[TEST]   Testing resource cleanup after error...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(5);
+    
+    // Start portal
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Stop portal (simulating cleanup after potential error)
+    wm.stopConfigPortal();
+    wm.process();
+    
+    // Verify portal is stopped
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    // Verify we can start again (resources cleaned up)
+    wm.startConfigPortal("TestAP2");
+    wm.process();
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Resource cleanup after error test completed successfully");
+}
+
+// Test multiple rapid start/stop calls
+void test_multiple_rapid_start_stop() {
+    Serial.println("[TEST]   Testing multiple rapid start/stop calls...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(5);
+    
+    // Rapid start/stop cycles
+    for (int i = 0; i < 5; i++) {
+        wm.startConfigPortal("TestAP");
+        wm.process();
+        delay(10);
+        wm.stopConfigPortal();
+        wm.process();
+        delay(10);
+    }
+
+    // Final state should be stopped
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    Serial.println("[TEST]   Multiple rapid start/stop calls test completed successfully");
+}
+

test/test_wifimanager/tests/test_integration.cpp

@@ -0,0 +1,167 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+#include <WiFiManagerParameter.h>
+#include "../test_main.h"
+
+// Test autoConnect fallback flow
+void test_autoconnect_fallback_flow() {
+    Serial.println("[TEST]   Testing autoConnect fallback flow...");
+    
+    WiFiManager wm;
+    delay(100); // Ensure WiFi is in a stable state
+    wm.resetSettings(); // Clear saved credentials
+    delay(100); // Allow WiFi operations to complete
+    
+    wm.setConfigPortalTimeout(5);
+    
+    // 1. Device starts
+    // 2. autoConnect() called with no saved credentials
+    bool result = wm.autoConnect("TestAP");
+    
+    // 3. Should fail to connect (no saved credentials)
+    TEST_ASSERT_FALSE(result);
+    
+    // 4. Portal should start automatically as fallback
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   autoConnect fallback flow test completed successfully");
+}
+
+// Test portal lifecycle with connection attempt
+void test_portal_lifecycle_with_connection_attempt() {
+    Serial.println("[TEST]   Testing portal lifecycle with connection attempt...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(10);
+    
+    // 1. Start portal
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // 2. Attempt connection (while portal active) via preloadWiFi
+    wm.preloadWiFi("NonExistentSSID_12345", "password");
+    
+    // 3. Verify state handling - portal should still be active
+    wm.process();
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Connection should fail (verify WiFi is not connected)
+    wl_status_t status = WiFi.status();
+    TEST_ASSERT_NOT_EQUAL(WL_CONNECTED, status);
+    
+    // 4. Stop portal
+    wm.stopConfigPortal();
+    wm.process();
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    Serial.println("[TEST]   Portal lifecycle with connection attempt test completed successfully");
+}
+
+// Test parameter add and retrieve in portal
+void test_parameter_add_and_retrieve() {
+    Serial.println("[TEST]   Testing parameter add and retrieve in portal...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(10);
+    
+    // 1. Add parameters
+    WiFiManagerParameter param("server", "Server", "default", 40);
+    wm.portalAddParameter(&param);
+    
+    TEST_ASSERT_EQUAL(1, wm.getParametersCount());
+    
+    // 2. Start portal
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // 3. Verify parameters are accessible
+    TEST_ASSERT_EQUAL(1, wm.getParametersCount());
+    
+    WiFiManagerParameter** params = wm.getParameters();
+    TEST_ASSERT_NOT_NULL(params);
+    TEST_ASSERT_EQUAL_STRING("server", params[0]->getID());
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Parameter add and retrieve in portal test completed successfully");
+}
+
+// Test complete flow: reset -> autoConnect -> portal
+void test_complete_flow_reset_autoconnect_portal() {
+    Serial.println("[TEST]   Testing complete flow: reset -> autoConnect -> portal...");
+    
+    WiFiManager wm;
+    
+    // 1. Reset settings
+    delay(100); // Ensure WiFi is in a stable state
+    wm.resetSettings();
+    delay(100); // Allow WiFi operations to complete
+    
+    // 2. autoConnect (should fail and start portal)
+    wm.setConfigPortalTimeout(5);
+    bool result = wm.autoConnect("TestAP");
+    
+    // 3. Verify portal started
+    TEST_ASSERT_FALSE(result); // Connection failed
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive()); // Portal started
+    
+    // 4. Process portal
+    wm.process();
+    delay(100);
+    
+    // 5. Verify portal is still active
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // 6. Stop portal
+    wm.stopConfigPortal();
+    wm.process();
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    Serial.println("[TEST]   Complete flow: reset -> autoConnect -> portal test completed successfully");
+}
+
+// Test portal with parameters and infrastructure
+void test_portal_with_parameters_and_infrastructure() {
+    Serial.println("[TEST]   Testing portal with parameters and infrastructure...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(10);
+    
+    // Add parameters
+    WiFiManagerParameter p1("server", "Server", "192.168.1.1", 40);
+    WiFiManagerParameter p2("port", "Port", "1883", 6);
+    wm.portalAddParameter(&p1);
+    wm.portalAddParameter(&p2);
+    
+    // Start portal
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    
+    // Verify portal is active
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Verify infrastructure
+    TEST_ASSERT_NOT_NULL(wm.getServer());
+    TEST_ASSERT_NOT_NULL(wm.getDNSServer());
+    
+    // Verify parameters
+    TEST_ASSERT_EQUAL(2, wm.getParametersCount());
+    
+    // Verify WiFi mode
+    WiFiMode_t mode = WiFi.getMode();
+    TEST_ASSERT_TRUE((mode & WIFI_AP) != 0);
+    
+    // Verify AP IP
+    IPAddress apIP = WiFi.softAPIP();
+    TEST_ASSERT_NOT_EQUAL(IPAddress(0,0,0,0), apIP);
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Portal with parameters and infrastructure test completed successfully");
+}
+

test/test_wifimanager/tests/test_nonblocking.cpp

@@ -0,0 +1,158 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+// Test process() doesn't block - verify it must be called periodically
+void test_nonblocking_process() {
+    constexpr unsigned long kMaximumProcessDurationMs = 250;
+    unsigned long maximumObservedDurationMs = 0;
+    
+    WiFiManager wm;
+    
+    wm.setConfigPortalTimeout(10);
+    wm.startConfigPortal("TestAP");
+    
+    // Verify portal is active
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Call process multiple times - should not block
+    for (int i = 0; i < 10; i++) {
+        unsigned long start = millis();
+        wm.process();
+        const unsigned long elapsed = millis() - start;
+        maximumObservedDurationMs = max(maximumObservedDurationMs, elapsed);
+        
+        // A normal cooperative call is quick, but DNS and Wi-Fi service may
+        // briefly run on ESP8266. This still catches a truly blocking portal.
+        TEST_ASSERT_LESS_THAN_MESSAGE(kMaximumProcessDurationMs, elapsed,
+                                      "process() exceeded its bounded service time");
+        
+        delay(10);
+    }
+    
+    // Portal should still be active after multiple process() calls
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    wm.stopConfigPortal();
+    
+    Serial.printf("[METRIC] WM_PROCESS max_elapsed_ms=%lu\n", maximumObservedDurationMs);
+    Serial.println("[TEST]   Non-blocking process() test completed successfully");
+}
+
+// Test client check setters - verify they don't interfere with portal operation
+void test_client_check_setters() {
+    Serial.println("[TEST]   Testing client check setters...");
+    
+    WiFiManager wm;
+    
+    // Test AP client check
+    wm.setAPClientCheck(true);
+    wm.setAPClientCheck(false);
+    
+    wm.setConfigPortalTimeout(10);
+    
+    // Start portal and verify it works with client check settings
+    wm.startConfigPortal("TestAP");
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    wm.process();
+    delay(100);
+    wm.stopConfigPortal();
+    
+    // Test web portal client check
+    wm.setWebPortalClientCheck(true);
+    wm.setWebPortalClientCheck(false);
+    
+    // Start web portal and verify it works
+    wm.setConfigPortalTimeout(5);
+    wm.startWebPortal();
+    TEST_ASSERT_TRUE(wm.getWebPortalActive());
+    wm.process();
+    wm.stopWebPortal();
+    
+    Serial.println("[TEST]   Client check setters test completed successfully");
+}
+
+void test_nonblocking_timeout_behavior() {
+    Serial.println("[TEST]   Testing timeout behavior (requires process() calls)...");
+    
+    WiFiManager wm;
+    
+    wm.setConfigPortalTimeout(2); // 2 second timeout
+    wm.startConfigPortal("TestAP");
+    
+    unsigned long start = millis();
+    bool stillActive = true;
+    
+    // Process until timeout or max wait
+    while (stillActive && (millis() - start < 5000)) {
+        wm.process();
+        
+        // Check if portal is still active (may become inactive after timeout)
+        if (!wm.getConfigPortalActive()) {
+            stillActive = false;
+            break; // Exit loop if portal has closed
+        }
+        
+        delay(50);
+    }
+    
+    // After timeout, portal should be inactive (may have auto-closed)
+    // Just verify we can check the state without crashing
+    bool portalState = wm.getConfigPortalActive();
+    
+    // Only call stopConfigPortal if portal is still active
+    // If it auto-closed on timeout, calling stopConfigPortal may crash
+    if (portalState) {
+        wm.stopConfigPortal();
+    }
+    
+    // Test completed without crash
+    TEST_ASSERT_TRUE_MESSAGE(true, "Timeout test completed without crash");
+    
+    Serial.println("[TEST]   Timeout behavior test completed successfully");
+}
+
+// Test that process() is required for timeouts to work
+void test_process_required_for_timeout() {
+    Serial.println("[TEST]   Testing that process() is required for timeouts...");
+    
+    WiFiManager wm;
+    
+    wm.setConfigPortalTimeout(1); // 1 second timeout
+    wm.startConfigPortal("TestAP");
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Wait 2 seconds WITHOUT calling process()
+    delay(2000);
+    
+    // Portal should still be active because process() wasn't called
+    // (timeout checking only happens in process())
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Now call process() - timeout should be checked
+    unsigned long start = millis();
+    bool stillActive = true;
+    
+    // Process until timeout or max wait
+    while (stillActive && (millis() - start < 3000)) {
+        wm.process();
+        
+        if (!wm.getConfigPortalActive()) {
+            stillActive = false;
+            break;
+        }
+        
+        delay(50);
+    }
+    
+    // Portal should have timed out after process() was called
+    // (may have auto-closed, but at least we verified process() is needed)
+    bool portalState = wm.getConfigPortalActive();
+    
+    if (portalState) {
+        wm.stopConfigPortal();
+    }
+    
+    Serial.println("[TEST]   process() required for timeout test completed successfully");
+}
+

test/test_wifimanager/tests/test_parameter_values.cpp

@@ -0,0 +1,112 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+#include <WiFiManagerParameter.h>
+#include "../test_main.h"
+
+// Test parameter value set directly
+void test_parameter_value_set_directly() {
+    Serial.println("[TEST]   Testing parameter value set directly...");
+    
+    WiFiManagerParameter param("server", "Server", "default", 40);
+    
+    // Set value directly
+    param.setValue("newvalue", 40);
+    
+    // Verify value was set
+    TEST_ASSERT_EQUAL_STRING("newvalue", param.getValue());
+    
+    Serial.println("[TEST]   Parameter value set directly test completed successfully");
+}
+
+// Test parameter value length validation
+void test_parameter_value_length_validation() {
+    Serial.println("[TEST]   Testing parameter value length validation...");
+    
+    WiFiManagerParameter param("server", "Server", "", 10);
+    
+    // Set value within length
+    param.setValue("short", 10);
+    TEST_ASSERT_EQUAL_STRING("short", param.getValue());
+    
+    // Set value at length limit
+    param.setValue("1234567890", 10); // Exactly 10 chars
+    String value = param.getValue();
+    TEST_ASSERT_LESS_OR_EQUAL(10, value.length());
+    
+    Serial.println("[TEST]   Parameter value length validation test completed successfully");
+}
+
+// Test parameter value persistence
+void test_parameter_value_persistence() {
+    Serial.println("[TEST]   Testing parameter value persistence...");
+    
+    WiFiManager wm;
+    
+    WiFiManagerParameter param("server", "Server", "default", 40);
+    wm.portalAddParameter(&param);
+    
+    // Set value
+    param.setValue("persisted_value", 40);
+    TEST_ASSERT_EQUAL_STRING("persisted_value", param.getValue());
+    
+    // Verify parameter is still accessible through WiFiManager
+    TEST_ASSERT_EQUAL(1, wm.getParametersCount());
+    
+    WiFiManagerParameter** params = wm.getParameters();
+    TEST_ASSERT_NOT_NULL(params);
+    TEST_ASSERT_EQUAL_STRING("persisted_value", params[0]->getValue());
+    
+    Serial.println("[TEST]   Parameter value persistence test completed successfully");
+}
+
+// Test parameter value update
+void test_parameter_value_update() {
+    Serial.println("[TEST]   Testing parameter value update...");
+    
+    WiFiManagerParameter param("server", "Server", "default", 40);
+    
+    // Set initial value
+    param.setValue("initial", 40);
+    TEST_ASSERT_EQUAL_STRING("initial", param.getValue());
+    
+    // Update value
+    param.setValue("updated", 40);
+    TEST_ASSERT_EQUAL_STRING("updated", param.getValue());
+    
+    Serial.println("[TEST]   Parameter value update test completed successfully");
+}
+
+// Test multiple parameters with different values
+void test_multiple_parameters_different_values() {
+    Serial.println("[TEST]   Testing multiple parameters with different values...");
+    
+    WiFiManager wm;
+    
+    WiFiManagerParameter p1("server", "Server", "192.168.1.1", 40);
+    WiFiManagerParameter p2("port", "Port", "1883", 6);
+    WiFiManagerParameter p3("key", "Key", "default_key", 32);
+    
+    wm.portalAddParameter(&p1);
+    wm.portalAddParameter(&p2);
+    wm.portalAddParameter(&p3);
+    
+    // Set different values
+    p1.setValue("10.0.0.1", 40);
+    p2.setValue("8883", 6);
+    p3.setValue("new_key", 32);
+    
+    // Verify all values are correct
+    TEST_ASSERT_EQUAL_STRING("10.0.0.1", p1.getValue());
+    TEST_ASSERT_EQUAL_STRING("8883", p2.getValue());
+    TEST_ASSERT_EQUAL_STRING("new_key", p3.getValue());
+    
+    // Verify through WiFiManager
+    WiFiManagerParameter** params = wm.getParameters();
+    TEST_ASSERT_EQUAL_STRING("10.0.0.1", params[0]->getValue());
+    TEST_ASSERT_EQUAL_STRING("8883", params[1]->getValue());
+    TEST_ASSERT_EQUAL_STRING("new_key", params[2]->getValue());
+    
+    Serial.println("[TEST]   Multiple parameters with different values test completed successfully");
+}
+

test/test_wifimanager/tests/test_parameters.cpp

@@ -0,0 +1,154 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+#include <WiFiManagerParameter.h>
+
+// Test custom parameters
+void test_create_parameter() {
+    Serial.println("[TEST]   Testing WiFiManagerParameter creation...");
+    
+    // Create parameter with basic constructor
+    WiFiManagerParameter param("test_id", "Test Label", "default_value", 40);
+    
+    // Verify basic getters work
+    TEST_ASSERT_EQUAL_STRING("test_id", param.getID());
+    TEST_ASSERT_EQUAL_STRING("Test Label", param.getLabel());
+    TEST_ASSERT_EQUAL_STRING("default_value", param.getValue());
+    TEST_ASSERT_EQUAL(40, param.getValueLength());
+    
+    Serial.println("[TEST]   WiFiManagerParameter creation test completed successfully");
+}
+
+void test_add_parameter() {
+    Serial.println("[TEST]   Testing portalAddParameter()...");
+    
+    WiFiManager wm;
+    
+    WiFiManagerParameter param1("param1", "Parameter 1", "value1", 40);
+    WiFiManagerParameter param2("param2", "Parameter 2", "value2", 40);
+    
+    // Add parameters
+    bool result1 = wm.portalAddParameter(&param1);
+    bool result2 = wm.portalAddParameter(&param2);
+    
+    TEST_ASSERT_TRUE(result1);
+    TEST_ASSERT_TRUE(result2);
+    
+    // Verify parameters are stored
+    TEST_ASSERT_EQUAL(2, wm.getParametersCount());
+    wm.portalClearParameters();
+    TEST_ASSERT_EQUAL(0, wm.getParametersCount());
+    
+    Serial.println("[TEST]   portalAddParameter() test completed successfully");
+}
+
+void test_get_parameters() {
+    Serial.println("[TEST]   Testing getParameters() and getParametersCount()...");
+    
+    WiFiManager wm;
+    
+    WiFiManagerParameter param1("param1", "Parameter 1", "value1", 40);
+    WiFiManagerParameter param2("param2", "Parameter 2", "value2", 40);
+    WiFiManagerParameter param3("param3", "Parameter 3", "value3", 40);
+    
+    wm.portalAddParameter(&param1);
+    wm.portalAddParameter(&param2);
+    wm.portalAddParameter(&param3);
+    
+    // Get count
+    int count = wm.getParametersCount();
+    TEST_ASSERT_EQUAL(3, count);
+    
+    // Get parameters array
+    WiFiManagerParameter** params = wm.getParameters();
+    TEST_ASSERT_NOT_NULL(params);
+    
+    // Verify we can access parameters
+    TEST_ASSERT_EQUAL_STRING("param1", params[0]->getID());
+    TEST_ASSERT_EQUAL_STRING("param2", params[1]->getID());
+    TEST_ASSERT_EQUAL_STRING("param3", params[2]->getID());
+    
+    Serial.println("[TEST]   getParameters() test completed successfully");
+}
+
+void test_parameter_with_custom_html() {
+    Serial.println("[TEST]   Testing WiFiManagerParameter with custom HTML...");
+    
+    // Create parameter with custom HTML
+    const char* custom_html = "<input type='text' name='custom' value='test'>";
+    WiFiManagerParameter param(custom_html);
+    
+    // Verify custom HTML is accessible
+    const char* html = param.getCustomHTML();
+    TEST_ASSERT_NOT_NULL(html);
+    
+    Serial.println("[TEST]   Parameter with custom HTML test completed successfully");
+}
+
+void test_parameter_value_length() {
+    Serial.println("[TEST]   Testing WiFiManagerParameter value length...");
+    
+    WiFiManagerParameter param("test_id", "Test Label", "default", 10);
+    
+    TEST_ASSERT_EQUAL(10, param.getValueLength());
+    
+    // Try to set value within length
+    param.setValue("short", 10);
+    TEST_ASSERT_EQUAL_STRING("short", param.getValue());
+    
+    Serial.println("[TEST]   Parameter value length test completed successfully");
+}
+
+void test_parameter_label_placement() {
+    Serial.println("[TEST]   Testing WiFiManagerParameter label placement...");
+    
+    WiFiManagerParameter param("test_id", "Test Label", "default", 40, "", WFM_LABEL_BEFORE);
+    
+    TEST_ASSERT_EQUAL(WFM_LABEL_BEFORE, param.getLabelPlacement());
+    
+    WiFiManagerParameter param2("test_id2", "Test Label 2", "default", 40, "", WFM_LABEL_AFTER);
+    
+    TEST_ASSERT_EQUAL(WFM_LABEL_AFTER, param2.getLabelPlacement());
+    
+    Serial.println("[TEST]   Parameter label placement test completed successfully");
+}
+
+void test_multiple_parameters() {
+    Serial.println("[TEST]   Testing multiple parameters...");
+    
+    WiFiManager wm;
+    
+    // Add several parameters
+    WiFiManagerParameter p1("mqtt_server", "MQTT Server", "192.168.1.1", 40);
+    WiFiManagerParameter p2("mqtt_port", "MQTT Port", "1883", 6);
+    WiFiManagerParameter p3("api_key", "API Key", "default_key", 32);
+    
+    wm.portalAddParameter(&p1);
+    wm.portalAddParameter(&p2);
+    wm.portalAddParameter(&p3);
+    
+    TEST_ASSERT_EQUAL(3, wm.getParametersCount());
+    
+    WiFiManagerParameter** params = wm.getParameters();
+    
+    // Verify all parameters are accessible
+    TEST_ASSERT_EQUAL_STRING("mqtt_server", params[0]->getID());
+    TEST_ASSERT_EQUAL_STRING("mqtt_port", params[1]->getID());
+    TEST_ASSERT_EQUAL_STRING("api_key", params[2]->getID());
+    
+    Serial.println("[TEST]   Multiple parameters test completed successfully");
+}
+
+void test_parameter_placeholder() {
+    Serial.println("[TEST]   Testing WiFiManagerParameter placeholder (deprecated)...");
+    
+    WiFiManagerParameter param("test_id", "Test Label", "default", 40);
+    
+    // getPlaceholder() is deprecated but should still work
+    const char* placeholder = param.getPlaceholder();
+    // May return label or empty, just verify no crash
+    TEST_ASSERT_NOT_NULL(placeholder);
+    
+    Serial.println("[TEST]   Parameter placeholder test completed successfully");
+}
+

test/test_wifimanager/tests/test_portal_lifecycle.cpp

@@ -0,0 +1,257 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+// Test config portal lifecycle
+void test_start_config_portal() {
+    Serial.println("[TEST]   Testing startConfigPortal()...");
+    
+    WiFiManager wm;
+    
+    wm.setConfigPortalTimeout(10);
+    
+    // Start portal with SSID only
+    wm.startConfigPortal("TestAP");
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Call process() to simulate real usage
+    wm.process();
+    delay(100);
+    
+    wm.stopConfigPortal();
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    Serial.println("[TEST]   startConfigPortal() test completed successfully");
+}
+
+void test_start_config_portal_with_password() {
+    Serial.println("[TEST]   Testing startConfigPortal() with password...");
+    
+    WiFiManager wm;
+    
+    wm.setConfigPortalTimeout(10);
+    
+    // Start portal with SSID and password
+    wm.startConfigPortal("TestAP2", "password123");
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Call process() to simulate real usage
+    wm.process();
+    delay(100);
+    
+    wm.stopConfigPortal();
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    Serial.println("[TEST]   startConfigPortal() with password test completed successfully");
+}
+
+void test_start_config_portal_auto_name() {
+    Serial.println("[TEST]   Testing startConfigPortal() with auto-generated name...");
+    
+    WiFiManager wm;
+    
+    wm.setConfigPortalTimeout(10);
+    
+    // Start portal without SSID (uses chip ID)
+    wm.startConfigPortal();
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Call process() to simulate real usage
+    wm.process();
+    delay(100); // Give it time to initialize
+    
+    // Verify we can get the SSID
+    String ssid = wm.getConfigPortalSSID();
+    TEST_ASSERT_GREATER_THAN(0, ssid.length());
+    
+    wm.stopConfigPortal();
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    Serial.println("[TEST]   startConfigPortal() auto-name test completed successfully");
+}
+
+void test_stop_config_portal() {
+    Serial.println("[TEST]   Testing stopConfigPortal()...");
+    
+    WiFiManager wm;
+    
+    wm.setConfigPortalTimeout(10);
+    
+    // Start portal
+    wm.startConfigPortal("TestAP");
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Call process() to simulate real usage
+    wm.process();
+    delay(100);
+    
+    // Stop portal
+    wm.stopConfigPortal();
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    Serial.println("[TEST]   stopConfigPortal() test completed successfully");
+}
+
+void test_config_portal_infrastructure() {
+    Serial.println("[TEST]   Testing config portal infrastructure...");
+    
+    WiFiManager wm;
+    
+    wm.setConfigPortalTimeout(10);
+    
+    wm.startConfigPortal("TestAP");
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Call process() to simulate real usage
+    wm.process();
+    delay(200); // Give time for initialization
+    
+    // Verify server object exists (must check while portal is active)
+    TEST_ASSERT_NOT_NULL_MESSAGE(wm.getServer(), "Server object should exist when portal is active");
+    
+    // Verify DNS server exists
+    TEST_ASSERT_NOT_NULL_MESSAGE(wm.getDNSServer(), "DNS server object should exist when portal is active");
+    
+    // Verify WiFi is in AP mode
+    WiFiMode_t mode = WiFi.getMode();
+    TEST_ASSERT_TRUE_MESSAGE((mode & WIFI_AP) != 0, "WiFi should be in AP mode");
+    
+    // Verify AP has an IP
+    IPAddress apIP = WiFi.softAPIP();
+    TEST_ASSERT_NOT_EQUAL(IPAddress(0,0,0,0), apIP);
+    
+    // Verify AP SSID matches
+    String apSSID = WiFi.softAPSSID();
+    TEST_ASSERT_EQUAL_STRING("TestAP", apSSID.c_str());
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Config portal infrastructure test completed successfully");
+}
+
+void test_start_web_portal() {
+    Serial.println("[TEST]   Testing startWebPortal()...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(5);
+    
+    // Note: Web portal requires STA mode, but for testing we can just verify it starts
+    // In real usage, WiFi would need to be connected first
+    wm.startWebPortal();
+    
+    TEST_ASSERT_TRUE(wm.getWebPortalActive());
+    
+    // Call process() to simulate real usage
+    wm.process();
+    
+    // Verify server object exists
+    TEST_ASSERT_NOT_NULL(wm.getServer());
+    
+    wm.stopWebPortal();
+    
+    Serial.println("[TEST]   startWebPortal() test completed successfully");
+}
+
+void test_stop_web_portal() {
+    Serial.println("[TEST]   Testing stopWebPortal()...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(5);
+    
+    wm.startWebPortal();
+    TEST_ASSERT_TRUE(wm.getWebPortalActive());
+    
+    // Call process() to simulate real usage
+    wm.process();
+    delay(100);
+    
+    wm.stopWebPortal();
+    TEST_ASSERT_FALSE(wm.getWebPortalActive());
+    
+    Serial.println("[TEST]   stopWebPortal() test completed successfully");
+}
+
+void test_config_portal_multiple_start_stop() {
+    Serial.println("[TEST]   Testing multiple config portal start/stop cycles...");
+    
+    WiFiManager wm;
+    
+    wm.setConfigPortalTimeout(10);
+    
+    // First cycle
+    wm.startConfigPortal("TestAP1");
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    wm.process();
+    delay(100);
+    wm.stopConfigPortal();
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    delay(200);
+    
+    // Second cycle
+    wm.startConfigPortal("TestAP2");
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    wm.process();
+    delay(100);
+    wm.stopConfigPortal();
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    delay(200);
+    
+    // Third cycle
+    wm.startConfigPortal("TestAP3");
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    wm.process();
+    delay(100);
+    wm.stopConfigPortal();
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    Serial.println("[TEST]   Multiple config portal cycles test completed successfully");
+}
+
+void test_config_portal_already_active() {
+    Serial.println("[TEST]   Testing startConfigPortal() when already active...");
+    
+    WiFiManager wm;
+    
+    wm.setConfigPortalTimeout(10);
+    
+    // Start portal
+    wm.startConfigPortal("TestAP");
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Call process() to simulate real usage
+    wm.process();
+    delay(100);
+    
+    // Try to start again (should silently fail when already active)
+    wm.startConfigPortal("TestAP2");
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive()); // Still active with original AP name
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Config portal already active test completed successfully");
+}
+
+void test_get_config_portal_ssid() {
+    Serial.println("[TEST]   Testing getConfigPortalSSID()...");
+    
+    WiFiManager wm;
+    
+    wm.setConfigPortalTimeout(10);
+    
+    // Start with known SSID
+    wm.startConfigPortal("MyTestAP");
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Call process() to simulate real usage
+    wm.process();
+    delay(100);
+    
+    // Verify SSID matches what we set
+    String ssid = wm.getConfigPortalSSID();
+    TEST_ASSERT_EQUAL_STRING("MyTestAP", ssid.c_str());
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   getConfigPortalSSID() test completed successfully");
+}
+

test/test_wifimanager/tests/test_resource_lifecycle.cpp

@@ -0,0 +1,186 @@
+#include <Arduino.h>
+#include <WiFiManager.h>
+#include <unity.h>
+#include <vector>
+
+#include "../test_main.h"
+
+namespace {
+
+struct HeapSnapshot {
+    uint32_t freeHeap;
+    uint32_t largestBlock;
+    uint8_t fragmentation;
+};
+
+HeapSnapshot captureHeap(const char* label) {
+    HeapSnapshot snapshot{
+        ESP.getFreeHeap(),
+#if defined(ESP8266)
+        ESP.getMaxFreeBlockSize(),
+        ESP.getHeapFragmentation(),
+#else
+        ESP.getMaxAllocHeap(),
+        0,
+#endif
+    };
+
+    Serial.printf("[METRIC] WM_HEAP label=%s free=%lu largest=%lu fragmentation=%u\n",
+                  label,
+                  static_cast<unsigned long>(snapshot.freeHeap),
+                  static_cast<unsigned long>(snapshot.largestBlock),
+                  snapshot.fragmentation);
+    return snapshot;
+}
+
+uint32_t allowedHeapDrift() {
+#if defined(ESP8266)
+    return 1024;
+#else
+    return 4096;
+#endif
+}
+
+uint32_t allowedLargestBlockDrift() {
+#if defined(ESP8266)
+    return 1024;
+#else
+    return 4096;
+#endif
+}
+
+void assertRecovered(const HeapSnapshot& settled, const HeapSnapshot& final) {
+    const uint32_t freeFloor = settled.freeHeap > allowedHeapDrift()
+        ? settled.freeHeap - allowedHeapDrift()
+        : 0;
+    const uint32_t blockFloor = settled.largestBlock > allowedLargestBlockDrift()
+        ? settled.largestBlock - allowedLargestBlockDrift()
+        : 0;
+
+    TEST_ASSERT_GREATER_OR_EQUAL_UINT32_MESSAGE(
+        freeFloor, final.freeHeap,
+        "Portal start/stop cycles retained too much heap after warm-up");
+    TEST_ASSERT_GREATER_OR_EQUAL_UINT32_MESSAGE(
+        blockFloor, final.largestBlock,
+        "Portal start/stop cycles degraded the largest contiguous allocation");
+}
+
+void startAndStopPortal(WiFiManager& wm, const char* ssid) {
+    wm.startConfigPortal(ssid);
+    wm.process();
+    TEST_ASSERT_TRUE_MESSAGE(wm.getConfigPortalActive(), "Portal should start");
+    TEST_ASSERT_NOT_NULL_MESSAGE(wm.getServer(), "Portal server should exist");
+    TEST_ASSERT_NOT_NULL_MESSAGE(wm.getDNSServer(), "Portal DNS server should exist");
+
+    wm.stopConfigPortal();
+    wm.process();
+    TEST_ASSERT_FALSE_MESSAGE(wm.getConfigPortalActive(), "Portal should stop");
+    TEST_ASSERT_NULL_MESSAGE(wm.getServer(), "Portal server should be released");
+    TEST_ASSERT_NULL_MESSAGE(wm.getDNSServer(), "Portal DNS server should be released");
+}
+
+}  // namespace
+
+void test_portal_resource_recovery() {
+    Serial.println("[TEST]   Measuring portal resource recovery...");
+
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(20);
+
+    // Warm the Wi-Fi core once before establishing the comparison point. The
+    // SDK is allowed to retain its own one-time allocations; the test detects
+    // repeated decline after that settled point instead.
+    startAndStopPortal(wm, "WM-Memory-Warmup");
+    delay(200);
+    const HeapSnapshot settled = captureHeap("settled");
+
+    for (uint8_t cycle = 0; cycle < 20; ++cycle) {
+        const String ssid = String("WM-Memory-") + String(cycle);
+        wm.startConfigPortal(ssid.c_str());
+        wm.process();
+        TEST_ASSERT_TRUE_MESSAGE(wm.getConfigPortalActive(), "Portal should start during cycle");
+        TEST_ASSERT_NOT_NULL_MESSAGE(wm.getServer(), "Server should exist during cycle");
+        TEST_ASSERT_NOT_NULL_MESSAGE(wm.getDNSServer(), "DNS should exist during cycle");
+        if (cycle == 0) {
+            captureHeap("portal-active");
+        }
+
+        wm.stopConfigPortal();
+        wm.process();
+        TEST_ASSERT_FALSE_MESSAGE(wm.getConfigPortalActive(), "Portal should stop during cycle");
+        TEST_ASSERT_NULL_MESSAGE(wm.getServer(), "Server should be released during cycle");
+        TEST_ASSERT_NULL_MESSAGE(wm.getDNSServer(), "DNS should be released during cycle");
+        captureHeap("cycle-stopped");
+    }
+
+    delay(200);
+    const HeapSnapshot final = captureHeap("final");
+    assertRecovered(settled, final);
+
+    Serial.println("[TEST]   Portal resource recovery test completed successfully");
+}
+
+void test_scan_result_storage_released_when_portal_closes() {
+    Serial.println("[TEST]   Testing scan-result storage release on portal close...");
+
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(20);
+    wm.startConfigPortal("WM-Scan-Storage");
+    wm.process();
+
+#ifdef UNIT_TEST
+    std::vector<WiFiManager::WiFiScanNetwork> results;
+    for (uint8_t i = 0; i < 24; ++i) {
+        results.push_back({String("Network-") + String(i), -30 - i, static_cast<uint8_t>(i % 2)});
+    }
+    wm.wmTestInjectScanResults(results);
+    captureHeap("scan-cache-held");
+    TEST_ASSERT_GREATER_THAN_UINT32(0, wm.getScanResults().capacity());
+#endif
+
+    wm.stopConfigPortal();
+    wm.process();
+    TEST_ASSERT_EQUAL_UINT32(0, wm.getScanResults().size());
+    TEST_ASSERT_EQUAL_UINT32(0, wm.getScanResults().capacity());
+    captureHeap("scan-storage-cleared");
+
+    Serial.println("[TEST]   Scan-result storage release test completed successfully");
+}
+
+void test_real_async_scan_completes() {
+    Serial.println("[TEST]   Testing real asynchronous Wi-Fi scan completion...");
+
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(30);
+    wm.startConfigPortal("WM-Real-Scan");
+    wm.process();
+    TEST_ASSERT_TRUE_MESSAGE(wm.getConfigPortalActive(), "Portal should be active for scanning");
+    captureHeap("scan-portal-active");
+
+    wm.requestAsyncScan(true);
+    captureHeap("scan-requested");
+    const uint32_t deadline = millis() + 25000UL;
+    while (wm.isScanRunning() && millis() < deadline) {
+        wm.process();
+        delay(20);
+    }
+
+    const WiFiManager::WiFiScanRuntimeState scan = wm.getScanSnapshot();
+    Serial.printf("[METRIC] WM_SCAN state=%u result=%d count=%d elapsed=%lu\n",
+                  static_cast<unsigned>(scan.state),
+                  scan.lastScanResult,
+                  static_cast<int>(wm.getScanResults().size()),
+                  static_cast<unsigned long>(millis() - scan.startedAt));
+    captureHeap("scan-complete-cache");
+
+    const bool stillRunning = wm.isScanRunning();
+    const WiFiManager::wm_scan_state_t state = wm.getScanState();
+    wm.stopConfigPortal();
+
+    captureHeap("scan-storage-cleared");
+    TEST_ASSERT_FALSE_MESSAGE(stillRunning, "Async scan exceeded its completion deadline");
+    TEST_ASSERT_EQUAL_MESSAGE(WiFiManager::WM_SCAN_COMPLETE, state,
+                              "Real scan must complete rather than enter failed/timeout state");
+
+    Serial.println("[TEST]   Real asynchronous Wi-Fi scan test completed successfully");
+}

test/test_wifimanager/tests/test_root_render_lifecycle.cpp

@@ -0,0 +1,280 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+#include <WiFiManagerHandlers.h>
+#include <TemplateEngine.h>
+#include "templates/RootShell.h"
+
+namespace {
+
+const char kEmptyTemplateChunk[] PROGMEM = "";
+const char kTestTitle[] PROGMEM = "WiFiManager";
+
+const char* dynamicStringGetter(void* userData) {
+    const auto* value = static_cast<const String*>(userData);
+    return value ? value->c_str() : "";
+}
+
+size_t dynamicStringLengthGetter(const char* data, void* /*userData*/) {
+    return data ? strlen(data) : 0;
+}
+
+void configureDescriptor(DynamicDataDescriptor& descriptor, String& value) {
+    descriptor.getter = &dynamicStringGetter;
+    descriptor.getLength = &dynamicStringLengthGetter;
+    descriptor.userData = &value;
+}
+
+void renderContextsInterleaved(TemplateContext& first, String& firstOutput,
+                               TemplateContext& second, String& secondOutput) {
+    uint8_t firstBuffer[31];
+    uint8_t secondBuffer[31];
+    bool firstDone = false;
+    bool secondDone = false;
+
+    while (!firstDone || !secondDone) {
+        if (!firstDone) {
+            size_t written = TemplateRenderer::renderNextChunk(first, firstBuffer, sizeof(firstBuffer));
+            if (written == 0) {
+                firstDone = true;
+            } else {
+                firstOutput.concat(reinterpret_cast<const char*>(firstBuffer), written);
+            }
+        }
+
+        if (!secondDone) {
+            size_t written = TemplateRenderer::renderNextChunk(second, secondBuffer, sizeof(secondBuffer));
+            if (written == 0) {
+                secondDone = true;
+            } else {
+                secondOutput.concat(reinterpret_cast<const char*>(secondBuffer), written);
+            }
+        }
+    }
+}
+
+} // namespace
+
+void test_bootstrap_json_portal_feature_flags() {
+    Serial.println("[TEST]   Testing bootstrap JSON portal feature flags...");
+
+    WiFiManager wm;
+    WiFiManagerHandlers handlers(&wm);
+
+    String idleBootstrap = handlers.buildPortalBootstrapJson();
+    TEST_ASSERT_EQUAL(-1, idleBootstrap.indexOf(F("\"closeCaptive\":{\"visible\":true")));
+
+    wm.wmTestSetPortalActive(true);
+    wm.portalSetBehaviorCaptivePortalEnabled(true);
+
+    String apBootstrap = handlers.buildPortalBootstrapJson();
+    TEST_ASSERT_NOT_EQUAL(-1, apBootstrap.indexOf(F("\"closeCaptive\":{\"visible\":true")));
+    TEST_ASSERT_NOT_EQUAL(-1, apBootstrap.indexOf(F("\"exitPortal\":{\"visible\":true")));
+
+    wm.wmTestSetPortalActive(false);
+
+    Serial.println("[TEST]   Bootstrap portal feature flags test completed successfully");
+}
+
+void test_portal_default_presentation() {
+    WiFiManager wm;
+    WiFiManagerHandlers handlers(&wm);
+
+    const String bootstrap = handlers.buildPortalBootstrapJson();
+    TEST_ASSERT_NOT_EQUAL(-1, bootstrap.indexOf(F("\"title\":\"WiFiManager\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, bootstrap.indexOf(F("\"tagline\":\"\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, bootstrap.indexOf(F("\"logoSvg\":\"\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, bootstrap.indexOf(F("\"logoAltText\":\"\"")));
+}
+
+void test_bootstrap_json_contract_v3() {
+    Serial.println("[TEST]   Testing bootstrap JSON v3 contract...");
+
+    WiFiManager wm;
+    WiFiManagerHandlers handlers(&wm);
+
+    WiFiManagerPortalConfig portal;
+    portal.title = WiFiManagerPortalText::ram("Solar Battery Monitor Setup");
+    portal.identityText = WiFiManagerPortalText::ram("Solar Battery Monitor");
+    portal.tagline = WiFiManagerPortalText::ram("Connect this device to WiFi and finish setup.");
+    portal.logo = WiFiManagerPortalAsset::svgFromRam("<svg viewBox='0 0 24 24'></svg>");
+    TEST_ASSERT_TRUE(wm.setPortalConfig(portal));
+    wm.portalSetPageInfoVisible(true);
+    wm.portalSetPageUpdateVisible(false);
+    wm.portalSetPageSetupVisible(true);
+    wm.portalSetActionEraseVisible(false);
+    wm.portalSetActionBackVisible(true);
+    wm.portalSetLayoutParamsLocation(PortalParamsLocation::SetupPage);
+    wm.setConfigPortalTimeout(90);
+
+    PortalHomeCard card;
+    card.id = "solar";
+    card.title = "Solar summary";
+    card.kind = PortalHomeCardKind::KeyValue;
+    card.items.push_back({"pv", "PV input", "420W"});
+    wm.portalAddHomeCard(card);
+
+    String j = handlers.buildPortalBootstrapJson();
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"contractVersion\":3")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"brand\":{")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"title\":\"Solar Battery Monitor Setup\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"tagline\":\"Connect this device to WiFi and finish setup.\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"logoSvg\":\"<svg viewBox='0 0 24 24'></svg>\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"context\":{")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"identityText\":\"Solar Battery Monitor\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"pages\":{")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"setup\":{\"visible\":true}")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"actions\":{")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"erase\":{\"visible\":false}")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"back\":{\"visible\":true}")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"layout\":{\"paramsLocation\":\"setup\"}")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"extraHomeCards\":[")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"id\":\"solar\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"kind\":\"kv\"")));
+
+    wm.startWebPortal();
+    j = handlers.buildPortalBootstrapJson();
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"portalActive\":true")));
+    wm.stopWebPortal();
+
+    wm.wmTestSetPortalActive(true);
+    j = handlers.buildPortalBootstrapJson();
+    TEST_ASSERT_NOT_EQUAL(-1, j.indexOf(F("\"portalTimeoutSecondsRemaining\":")));
+    TEST_ASSERT_EQUAL(-1, j.indexOf(F("\"portalTimeoutSecondsRemaining\":0")));
+    wm.wmTestSetPortalActive(false);
+
+    Serial.println("[TEST]   Bootstrap JSON v2 contract test completed successfully");
+}
+
+void test_bootstrap_json_snapshot_consistency() {
+    Serial.println("[TEST]   Testing bootstrap JSON snapshot consistency...");
+
+    WiFiManager wm;
+    WiFiManagerHandlers handlers(&wm);
+
+    wm.setConfigPortalTimeout(5);
+    wm.startConfigPortal("RootSnapshotAP");
+    wm.process();
+    delay(100);
+
+    String snap1 = handlers.buildPortalBootstrapJson();
+    String snap2 = handlers.buildPortalBootstrapJson();
+
+    TEST_ASSERT_GREATER_THAN(32, snap1.length());
+    TEST_ASSERT_EQUAL_STRING(snap1.c_str(), snap2.c_str());
+
+    wm.stopConfigPortal();
+
+    Serial.println("[TEST]   Bootstrap JSON snapshot consistency test completed successfully");
+}
+
+void test_root_render_interleaved_context_isolation() {
+    Serial.println("[TEST]   Testing root render interleaved context isolation...");
+
+    PlaceholderRegistry registryA(8);
+    PlaceholderRegistry registryB(8);
+
+    registryA.registerProgmemData("%STYLES%", kEmptyTemplateChunk);
+    registryA.registerProgmemData("%PAGE_TITLE%", kTestTitle);
+    registryA.registerProgmemData("%PORTAL_THEME%", kEmptyTemplateChunk);
+
+    registryB.registerProgmemData("%STYLES%", kEmptyTemplateChunk);
+    registryB.registerProgmemData("%PAGE_TITLE%", kTestTitle);
+    registryB.registerProgmemData("%PORTAL_THEME%", kEmptyTemplateChunk);
+
+    String bootstrapA = F("{\"ctx\":\"A\"}");
+    String appJsA = F("// shell A");
+    String bootstrapB = F("{\"ctx\":\"B\"}");
+    String appJsB = F("// shell B");
+
+    DynamicDataDescriptor bootstrapDescriptorA{};
+    DynamicDataDescriptor appJsDescriptorA{};
+    DynamicDataDescriptor bootstrapDescriptorB{};
+    DynamicDataDescriptor appJsDescriptorB{};
+
+    configureDescriptor(bootstrapDescriptorA, bootstrapA);
+    configureDescriptor(appJsDescriptorA, appJsA);
+    configureDescriptor(bootstrapDescriptorB, bootstrapB);
+    configureDescriptor(appJsDescriptorB, appJsB);
+
+    TEST_ASSERT_TRUE_MESSAGE(registryA.registerDynamicData("%BOOTSTRAP_JSON%", &bootstrapDescriptorA),
+                             "Registry A bootstrap placeholder should register");
+    TEST_ASSERT_TRUE_MESSAGE(registryA.registerDynamicData("%PORTAL_APP_JS%", &appJsDescriptorA),
+                             "Registry A app JS placeholder should register");
+    TEST_ASSERT_TRUE_MESSAGE(registryB.registerDynamicData("%BOOTSTRAP_JSON%", &bootstrapDescriptorB),
+                             "Registry B bootstrap placeholder should register");
+    TEST_ASSERT_TRUE_MESSAGE(registryB.registerDynamicData("%PORTAL_APP_JS%", &appJsDescriptorB),
+                             "Registry B app JS placeholder should register");
+
+    TemplateContext contextA;
+    TemplateContext contextB;
+    contextA.setRegistry(&registryA);
+    contextB.setRegistry(&registryB);
+
+    TemplateRenderer::initializeContext(contextA, WM_ROOT_SHELL_TEMPLATE);
+    TemplateRenderer::initializeContext(contextB, WM_ROOT_SHELL_TEMPLATE);
+
+    String outputA;
+    String outputB;
+    renderContextsInterleaved(contextA, outputA, contextB, outputB);
+
+    TEST_ASSERT_NOT_EQUAL(-1, outputA.indexOf("{\"ctx\":\"A\"}"));
+    TEST_ASSERT_NOT_EQUAL(-1, outputA.indexOf("// shell A"));
+    TEST_ASSERT_EQUAL(-1, outputA.indexOf("{\"ctx\":\"B\"}"));
+    TEST_ASSERT_EQUAL(-1, outputA.indexOf("// shell B"));
+
+    TEST_ASSERT_NOT_EQUAL(-1, outputB.indexOf("{\"ctx\":\"B\"}"));
+    TEST_ASSERT_NOT_EQUAL(-1, outputB.indexOf("// shell B"));
+    TEST_ASSERT_EQUAL(-1, outputB.indexOf("{\"ctx\":\"A\"}"));
+    TEST_ASSERT_EQUAL(-1, outputB.indexOf("// shell A"));
+
+    Serial.println("[TEST]   Root render interleaved context isolation test completed successfully");
+}
+
+void test_portal_presentation_configuration() {
+    Serial.println("[TEST]   Testing portal presentation configuration...");
+
+    WiFiManager wm;
+    WiFiManagerHandlers handlers(&wm);
+    WiFiManagerPortalConfig config;
+    config.title = WiFiManagerPortalText::ram("Set up Temperature Monitor");
+    config.identityText = WiFiManagerPortalText::ram("Example Devices");
+    config.tagline = WiFiManagerPortalText::ram("Connect this device to WiFi.");
+    config.logo = WiFiManagerPortalAsset::svgFromRam("<svg viewBox='0 0 24 24'></svg>");
+    config.logoAltText = WiFiManagerPortalText::ram("Example Devices logo");
+    config.theme.pageBackground = WiFiManagerPortalText::ram("#f4f7f3");
+    config.theme.surface = WiFiManagerPortalText::ram("#ffffff");
+    config.theme.text = WiFiManagerPortalText::ram("#1c251e");
+    config.theme.mutedText = WiFiManagerPortalText::ram("#607064");
+    config.theme.border = WiFiManagerPortalText::ram("#d6e0d7");
+    config.theme.accent = WiFiManagerPortalText::ram("#347a45");
+    config.theme.accentHover = WiFiManagerPortalText::ram("#245a32");
+    config.theme.accentText = WiFiManagerPortalText::ram("#ffffff");
+    config.theme.success = WiFiManagerPortalText::ram("#2f855a");
+    config.theme.danger = WiFiManagerPortalText::ram("#c53030");
+    config.theme.dangerHover = WiFiManagerPortalText::ram("#9b2c2c");
+    config.theme.cornerRadiusPx = 10;
+    config.theme.smallCornerRadiusPx = 6;
+
+    TEST_ASSERT_TRUE_MESSAGE(wm.setPortalConfig(config),
+        "A complete setup-time portal configuration should be accepted");
+
+    String bootstrap = handlers.buildPortalBootstrapJson();
+    TEST_ASSERT_NOT_EQUAL(-1, bootstrap.indexOf(F("\"title\":\"Set up Temperature Monitor\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, bootstrap.indexOf(F("\"identityText\":\"Example Devices\"")));
+    TEST_ASSERT_NOT_EQUAL(-1, bootstrap.indexOf(F("\"logoAltText\":\"Example Devices logo\"")));
+
+    WiFiManagerPortalConfig unsafeConfig = config;
+    unsafeConfig.theme.accent = WiFiManagerPortalText::ram("#347a45;body{display:none}");
+    TEST_ASSERT_FALSE_MESSAGE(wm.setPortalConfig(unsafeConfig),
+        "Semantic theme values must reject stylesheet injection characters");
+
+    wm.startWebPortal();
+    TEST_ASSERT_FALSE_MESSAGE(wm.setPortalConfig(config),
+        "Portal presentation must remain immutable while async routes are active");
+    wm.stopWebPortal();
+    TEST_ASSERT_TRUE_MESSAGE(wm.setPortalConfig(config),
+        "Presentation can be applied after the portal stops");
+
+    Serial.println("[TEST]   Portal presentation configuration test completed successfully");
+}

test/test_wifimanager/tests/test_state_transitions.cpp

@@ -0,0 +1,131 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+#include "../test_main.h"
+
+// Test portal to connected transition (state consistency)
+void test_portal_to_connected_transition() {
+    Serial.println("[TEST]   Testing portal to connected transition...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(10);
+    
+    // Start portal
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    
+    // Verify portal is active
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    TEST_ASSERT_FALSE(wm.getWebPortalActive());
+    
+    // Portal state should be consistent
+    // While portal is active, WiFi should be in AP mode
+    WiFiMode_t mode = WiFi.getMode();
+    TEST_ASSERT_TRUE((mode & WIFI_AP) != 0);
+    
+    // Stop portal
+    wm.stopConfigPortal();
+    wm.process();
+    
+    // Verify portal is stopped
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    Serial.println("[TEST]   Portal to connected transition test completed successfully");
+}
+
+// Test concurrent operations (portal + connection attempt)
+void test_concurrent_operations() {
+    Serial.println("[TEST]   Testing concurrent operations...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(10);
+    
+    // Start portal
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Attempt connection while portal is active (via preloadWiFi)
+    // This should either be ignored or handled gracefully
+    wm.preloadWiFi("NonExistentSSID_12345", "password");
+    
+    // Portal should still be active (connection attempt shouldn't stop it)
+    wm.process();
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Verify WiFi is not connected (SSID doesn't exist)
+    wl_status_t status = WiFi.status();
+    TEST_ASSERT_NOT_EQUAL(WL_CONNECTED, status);
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Concurrent operations test completed successfully");
+}
+
+// Test state consistency during portal operation
+void test_state_consistency_during_portal() {
+    Serial.println("[TEST]   Testing state consistency during portal operation...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(10);
+    
+    // Start portal
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    
+    // Verify state consistency
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    TEST_ASSERT_NOT_NULL(wm.getServer());
+    TEST_ASSERT_NOT_NULL(wm.getDNSServer());
+    
+    // Process multiple times
+    for (int i = 0; i < 10; i++) {
+        wm.process();
+        delay(10);
+        
+        // State should remain consistent
+        TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    }
+    
+    wm.stopConfigPortal();
+    wm.process();
+    
+    // After stop, portal should be inactive
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    Serial.println("[TEST]   State consistency during portal operation test completed successfully");
+}
+
+// Test state transitions with multiple start/stop cycles
+void test_state_transitions_multiple_cycles() {
+    Serial.println("[TEST]   Testing state transitions with multiple cycles...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(10);
+    
+    for (int cycle = 0; cycle < 3; cycle++) {
+        // Start state
+        TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+        
+        // Start portal
+        wm.startConfigPortal("TestAP");
+        wm.process();
+        TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+        
+        // Active state
+        wm.process();
+        delay(100);
+        TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+        
+        // Stop portal
+        wm.stopConfigPortal();
+        wm.process();
+        TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+        
+        delay(100);
+    }
+    
+    Serial.println("[TEST]   State transitions with multiple cycles test completed successfully");
+}
+

test/test_wifimanager/tests/test_static_ip.cpp

@@ -0,0 +1,93 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+// Test static IP configuration
+// Test AP static IP configuration - verifies IP is actually applied
+void test_set_ap_static_ip_config() {
+    Serial.println("[TEST]   Testing setAPStaticIPConfig()...");
+    
+    WiFiManager wm;
+    
+    IPAddress ip(192, 168, 4, 1);
+    IPAddress gw(192, 168, 4, 1);
+    IPAddress sn(255, 255, 255, 0);
+    
+    // Set AP static IP
+    wm.setAPStaticIPConfig(ip, gw, sn);
+    
+    wm.setConfigPortalTimeout(10);
+    
+    // Start portal and verify IP is actually set
+    wm.startConfigPortal("TestAP");
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Call process() to simulate real usage
+    wm.process();
+    delay(200); // Give time for IP to be configured
+    
+    // Verify AP IP matches what we configured
+    IPAddress apIP = WiFi.softAPIP();
+    TEST_ASSERT_EQUAL(ip, apIP);
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   setAPStaticIPConfig() test completed successfully");
+}
+
+// Test STA static IP configuration - consolidated
+void test_sta_static_ip_configuration() {
+    Serial.println("[TEST]   Testing STA static IP configuration...");
+    
+    WiFiManager wm;
+    
+    IPAddress ip(192, 168, 1, 100);
+    IPAddress gw(192, 168, 1, 1);
+    IPAddress sn(255, 255, 255, 0);
+    IPAddress dns(8, 8, 8, 8);
+    
+    // Test setSTAStaticIPConfig without DNS
+    wm.setSTAStaticIPConfig(ip, gw, sn);
+    
+    // Test setSTAStaticIPConfig with DNS
+    wm.setSTAStaticIPConfig(ip, gw, sn, dns);
+    
+    // Verify no crash
+    TEST_ASSERT_TRUE_MESSAGE(true, "STA static IP configuration setters executed without crash");
+    
+    Serial.println("[TEST]   STA static IP configuration test completed successfully");
+}
+
+// Note: test_show_static_fields and test_show_dns_fields removed - 
+// already covered in test_configuration_setters() in test_configuration.cpp
+
+void test_ap_static_ip_application() {
+    Serial.println("[TEST]   Testing AP static IP application...");
+    
+    WiFiManager wm;
+    
+    IPAddress customIP(10, 0, 1, 1);
+    IPAddress customGW(10, 0, 1, 1);
+    IPAddress customSN(255, 255, 255, 0);
+    
+    wm.setAPStaticIPConfig(customIP, customGW, customSN);
+    
+    wm.setConfigPortalTimeout(10);
+    
+    wm.startConfigPortal("TestAP");
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Call process() to simulate real usage
+    wm.process();
+    delay(200); // Give time for AP to configure
+    
+    IPAddress apIP = WiFi.softAPIP();
+    
+    // AP should have the configured IP
+    TEST_ASSERT_EQUAL(customIP, apIP);
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   AP static IP application test completed successfully");
+}
+

test/test_wifimanager/tests/test_stress.cpp

@@ -0,0 +1,176 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+#include <WiFiManagerParameter.h>
+#include "../test_main.h"
+
+// Test many start/stop cycles for memory leaks
+void test_many_start_stop_cycles() {
+    Serial.println("[TEST]   Testing many start/stop cycles for memory leaks...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(10);
+    
+    // Test 10 start/stop cycles (enough to verify memory leaks and resource cleanup)
+    for (int i = 0; i < 10; i++) {
+        wm.startConfigPortal("TestAP");
+        wm.process();
+        
+        // Verify portal started
+        TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+        
+        wm.stopConfigPortal();
+        wm.process();
+        
+        // Verify portal stopped
+        TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+        
+        delay(10); // Small delay between cycles
+    }
+    
+    // Verify no crashes or memory leaks (by checking we can still start/stop)
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Many start/stop cycles test completed successfully");
+}
+
+// Test long running portal
+void test_long_running_portal() {
+    Serial.println("[TEST]   Testing long running portal...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(30); // Longer timeout for long running test
+    
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Process for extended period (enough to verify stability)
+    for (int i = 0; i < 50; i++) {
+        wm.process();
+        
+        // Verify portal remains active
+        TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+        
+        // Verify infrastructure remains
+        TEST_ASSERT_NOT_NULL(wm.getServer());
+        TEST_ASSERT_NOT_NULL(wm.getDNSServer());
+        
+        delay(10);
+    }
+    
+    wm.stopConfigPortal();
+    wm.process();
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    Serial.println("[TEST]   Long running portal test completed successfully");
+}
+
+// Test rapid portal start/stop
+void test_rapid_portal_start_stop() {
+    Serial.println("[TEST]   Testing rapid portal start/stop...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(10);
+    
+    // Rapid start/stop cycles (reduced for faster execution)
+    for (int i = 0; i < 5; i++) {
+        wm.startConfigPortal("TestAP");
+        wm.process();
+        wm.stopConfigPortal();
+        wm.process();
+    }
+    
+    // Verify final state
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    // Verify we can still start portal
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Rapid portal start/stop test completed successfully");
+}
+
+// Test multiple parameters stress
+void test_multiple_parameters_stress() {
+    Serial.println("[TEST]   Testing multiple parameters stress...");
+    
+    WiFiManager wm;
+    wm.setConfigPortalTimeout(10);
+    
+    // Add many parameters
+    WiFiManagerParameter* params[20];
+    for (int i = 0; i < 20; i++) {
+        char id[20];
+        char label[30];
+        sprintf(id, "param%d", i);
+        sprintf(label, "Parameter %d", i);
+        params[i] = new WiFiManagerParameter(id, label, "default", 40);
+        wm.portalAddParameter(params[i]);
+    }
+    
+    TEST_ASSERT_EQUAL(20, wm.getParametersCount());
+    
+    // Start portal
+    wm.startConfigPortal("TestAP");
+    wm.process();
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    // Verify all parameters accessible
+    WiFiManagerParameter** paramArray = wm.getParameters();
+    for (int i = 0; i < 20; i++) {
+        TEST_ASSERT_NOT_NULL(paramArray[i]);
+    }
+    
+    wm.stopConfigPortal();
+    
+    // Cleanup - Parameters are managed by WiFiManager, but we allocated with new
+    // Note: WiFiManagerParameter doesn't have virtual destructor, but this is just cleanup
+    for (int i = 0; i < 20; i++) {
+        delete params[i];
+    }
+    
+    Serial.println("[TEST]   Multiple parameters stress test completed successfully");
+}
+
+// Test portal with timeout stress
+void test_portal_with_timeout_stress() {
+    Serial.println("[TEST]   Testing portal with timeout stress...");
+    
+    WiFiManager wm;
+    
+    // Multiple cycles with different timeouts
+    for (int timeout = 1; timeout <= 5; timeout++) {
+        wm.setConfigPortalTimeout(timeout);
+        wm.startConfigPortal("TestAP");
+        wm.process();
+        
+        // Process until timeout or max wait
+        unsigned long start = millis();
+        unsigned long maxWait = (timeout + 1) * 1000UL;
+        while (wm.getConfigPortalActive() && (millis() - start < maxWait)) {
+            wm.process();
+            delay(50);
+        }
+        
+        // Portal may have timed out or still be active
+        if (wm.getConfigPortalActive()) {
+            wm.stopConfigPortal();
+        }
+        wm.process();
+        
+        delay(100);
+    }
+    
+    // Verify final state
+    TEST_ASSERT_FALSE(wm.getConfigPortalActive());
+    
+    Serial.println("[TEST]   Portal with timeout stress test completed successfully");
+}
+

test/test_wifimanager/tests/test_template_rendering.cpp

@@ -0,0 +1,101 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <TemplateEngine.h>
+#include "templates/RootShell.h"
+#include "templates/PortalAppJS.h"
+#include "../test_main.h"
+
+namespace {
+
+String renderTemplate(const char* templateData, PlaceholderRegistry& registry) {
+    TemplateContext context;
+    context.setRegistry(&registry);
+    TemplateRenderer::initializeContext(context, templateData);
+
+    uint8_t buffer[128];
+    String output;
+    while (true) {
+        size_t written = TemplateRenderer::renderNextChunk(context, buffer, sizeof(buffer));
+        if (written == 0) {
+            break;
+        }
+        output.concat(reinterpret_cast<const char*>(buffer), written);
+    }
+    return output;
+}
+
+const char kEmpty[] PROGMEM = "";
+const char kDocTitle[] PROGMEM = "Config ESP";
+const char kBootstrapJson[] PROGMEM = "{\"title\":\"Test\"}";
+const char kPortalAppJs[] PROGMEM = "console.log('portal');";
+const char kPortalTheme[] PROGMEM = "";
+
+const char* dynamicStringGetter(void* userData) {
+    const auto* value = static_cast<const String*>(userData);
+    return value ? value->c_str() : "";
+}
+
+size_t dynamicStringLengthGetter(const char* data, void* /*userData*/) {
+    return data ? strlen(data) : 0;
+}
+
+void configureDescriptor(DynamicDataDescriptor& descriptor, String& value) {
+    descriptor.getter = &dynamicStringGetter;
+    descriptor.getLength = &dynamicStringLengthGetter;
+    descriptor.userData = &value;
+}
+
+} // namespace
+
+void test_shell_template_renders_core_placeholders() {
+    Serial.println("[TEST]   Testing portal shell template rendering...");
+
+    PlaceholderRegistry registry(8);
+    registry.registerProgmemData("%STYLES%", kEmpty);
+    registry.registerProgmemData("%PAGE_TITLE%", kDocTitle);
+    registry.registerProgmemData("%BOOTSTRAP_JSON%", kBootstrapJson);
+    registry.registerProgmemData("%PORTAL_APP_JS%", kPortalAppJs);
+    registry.registerProgmemData("%PORTAL_THEME%", kPortalTheme);
+
+    String output = renderTemplate(WM_ROOT_SHELL_TEMPLATE, registry);
+
+    TEST_ASSERT_NOT_EQUAL(-1, output.indexOf("<title>Config ESP</title>"));
+    TEST_ASSERT_NOT_EQUAL(-1, output.indexOf("<div id='app'></div>"));
+    TEST_ASSERT_NOT_EQUAL(-1, output.indexOf("id='wm-toast'"));
+    TEST_ASSERT_NOT_EQUAL(-1, output.indexOf("id='wm-dialog'"));
+    TEST_ASSERT_NOT_EQUAL(-1, output.indexOf("id='wm-bootstrap'"));
+    TEST_ASSERT_NOT_EQUAL(-1, output.indexOf("{\"title\":\"Test\"}"));
+    TEST_ASSERT_NOT_EQUAL(-1, output.indexOf("console.log('portal')"));
+
+    Serial.println("[TEST]   Portal shell template rendering test completed successfully");
+}
+
+void test_shell_template_renders_dynamic_theme_with_percent_values() {
+    Serial.println("[TEST]   Testing portal shell dynamic theme placeholder with percent values...");
+
+    PlaceholderRegistry registry(8);
+    String theme = F("<style>:root{--wm-bg:rgb(20,50,30);--wm-width:100%}</style>");
+    String title = F("Config ESP");
+    String bootstrap = F("{\"title\":\"Test\"}");
+    DynamicDataDescriptor themeDescriptor{};
+    DynamicDataDescriptor titleDescriptor{};
+    DynamicDataDescriptor bootstrapDescriptor{};
+
+    configureDescriptor(themeDescriptor, theme);
+    configureDescriptor(titleDescriptor, title);
+    configureDescriptor(bootstrapDescriptor, bootstrap);
+
+    TEST_ASSERT_TRUE(registry.registerProgmemData("%STYLES%", kEmpty));
+    TEST_ASSERT_TRUE(registry.registerDynamicData("%PORTAL_THEME%", &themeDescriptor));
+    TEST_ASSERT_TRUE(registry.registerDynamicData("%PAGE_TITLE%", &titleDescriptor));
+    TEST_ASSERT_TRUE(registry.registerDynamicData("%BOOTSTRAP_JSON%", &bootstrapDescriptor));
+    TEST_ASSERT_TRUE(registry.registerProgmemData("%PORTAL_APP_JS%", kPortalAppJs));
+
+    String output = renderTemplate(WM_ROOT_SHELL_TEMPLATE, registry);
+
+    TEST_ASSERT_NOT_EQUAL(-1, output.indexOf("<style>:root{--wm-bg:rgb(20,50,30);--wm-width:100%}</style>"));
+    TEST_ASSERT_NOT_EQUAL(-1, output.indexOf("<title>Config ESP</title>"));
+    TEST_ASSERT_NOT_EQUAL(-1, output.indexOf("{\"title\":\"Test\"}"));
+
+    Serial.println("[TEST]   Dynamic theme placeholder percent rendering test completed successfully");
+}

test/test_wifimanager/tests/test_wifi_connection.cpp

@@ -0,0 +1,164 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+#include "../test_main.h"
+
+// Test autoConnect fallback to portal when no saved credentials
+void test_autoconnect_fallback_to_portal() {
+    Serial.println("[TEST]   Testing autoConnect fallback to portal...");
+    
+    WiFiManager wm;
+    delay(100); // Ensure WiFi is in a stable state
+    wm.resetSettings(); // Clear saved credentials
+    delay(100); // Allow WiFi operations to complete
+    
+    wm.setConfigPortalTimeout(5);
+    bool result = wm.autoConnect("TestAP");
+    
+    // Should fail to connect (no saved credentials)
+    TEST_ASSERT_FALSE(result);
+    
+    // Should start portal as fallback
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   autoConnect fallback to portal test completed successfully");
+}
+
+// Test connectWifi with non-existent SSID (using autoConnect instead)
+void test_connectwifi_ssid_not_found() {
+    Serial.println("[TEST]   Testing connection with non-existent SSID...");
+    
+    WiFiManager wm;
+    delay(100); // Ensure WiFi is in a stable state
+    wm.resetSettings(); // Clear saved credentials
+    delay(100); // Allow WiFi operations to complete
+    
+    // Use autoConnect with non-existent SSID (will fail to connect)
+    wm.setConfigPortalTimeout(5);
+    bool result = wm.autoConnect("TestAP");
+    
+    // Should fail to connect (no saved credentials or SSID not found)
+    TEST_ASSERT_FALSE(result);
+    
+    // Verify WiFi is not connected
+    wl_status_t status = WiFi.status();
+    TEST_ASSERT_NOT_EQUAL(WL_CONNECTED, status);
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Connection with non-existent SSID test completed successfully");
+}
+
+// Test connect retry count setting
+void test_connectwifi_retry_count() {
+    Serial.println("[TEST]   Testing connect retry count setting...");
+    
+    WiFiManager wm;
+    delay(100); // Ensure WiFi is in a stable state
+    wm.resetSettings(); // Clear saved credentials
+    delay(100); // Allow WiFi operations to complete
+    
+    // Set retry count
+    wm.setConnectRetries(3);
+    
+    // Verify setting is stored (by attempting connection via autoConnect)
+    // The retry logic should be called internally
+    wm.setConfigPortalTimeout(5);
+    bool result = wm.autoConnect("TestAP");
+    
+    // Should fail (not connected)
+    TEST_ASSERT_FALSE(result);
+    
+    // Verify no crash with retry setting
+    TEST_ASSERT_TRUE_MESSAGE(true, "autoConnect with retry count executed without crash");
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Connect retry count test completed successfully");
+}
+
+// Test connect timeout setting
+void test_connectwifi_timeout_setting() {
+    Serial.println("[TEST]   Testing connect timeout setting...");
+    
+    WiFiManager wm;
+    
+    // Ensure WiFi is in a stable state before resetting
+    delay(100);
+    wm.resetSettings(); // Clear saved credentials
+    
+    // Allow WiFi operations to complete
+    delay(100);
+    
+    // Set timeout
+    wm.setConnectTimeout(5);
+    
+    // Verify timeout setting is used (by attempting connection via autoConnect)
+    wm.setConfigPortalTimeout(5);
+    bool result = wm.autoConnect("TestAP");
+    
+    // Should fail (not connected)
+    TEST_ASSERT_FALSE(result);
+    
+    // Verify no crash with timeout setting
+    TEST_ASSERT_TRUE_MESSAGE(true, "autoConnect with timeout setting executed without crash");
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Connect timeout setting test completed successfully");
+}
+
+// Test connection state transitions
+void test_connection_state_transitions() {
+    Serial.println("[TEST]   Testing connection state transitions...");
+    
+    WiFiManager wm;
+    delay(100); // Ensure WiFi is in a stable state
+    wm.resetSettings(); // Clear saved credentials
+    delay(100); // Allow WiFi operations to complete
+    
+    // Attempt connection via autoConnect (will fail)
+    wm.setConfigPortalTimeout(5);
+    wm.autoConnect("TestAP");
+    
+    // Wait a bit for state to potentially change
+    delay(100);
+    
+    // Verify state transition (may be IDLE, DISCONNECTED, or NO_SSID_AVAIL)
+    wl_status_t finalStatus = WiFi.status();
+    
+    // Should not be CONNECTED (since no saved credentials)
+    TEST_ASSERT_NOT_EQUAL(WL_CONNECTED, finalStatus);
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   Connection state transitions test completed successfully");
+}
+
+// Test autoConnect with timeout
+void test_autoconnect_with_timeout() {
+    Serial.println("[TEST]   Testing autoConnect with timeout...");
+    
+    WiFiManager wm;
+    delay(100); // Ensure WiFi is in a stable state
+    wm.resetSettings(); // Clear saved credentials
+    delay(100); // Allow WiFi operations to complete
+    
+    wm.setConfigPortalTimeout(5);
+    wm.setConnectTimeout(3);
+    
+    bool result = wm.autoConnect("TestAP");
+    
+    // Should fail to connect (no saved credentials)
+    TEST_ASSERT_FALSE(result);
+    
+    // Should start portal as fallback
+    TEST_ASSERT_TRUE(wm.getConfigPortalActive());
+    
+    wm.stopConfigPortal();
+    
+    Serial.println("[TEST]   autoConnect with timeout test completed successfully");
+}
+

test/test_wifimanager/tests/test_wifi_scanning.cpp

@@ -0,0 +1,152 @@
+#include <unity.h>
+#include <Arduino.h>
+#include <WiFiManager.h>
+#include "../test_main.h"
+
+void test_wifi_scan_initiates() {
+    Serial.println("[TEST]   Testing async scan request queues...");
+
+    WiFiManager wm;
+    wm.requestAsyncScan(true);
+
+    TEST_ASSERT_EQUAL(WiFiManager::WM_SCAN_QUEUED, wm.getScanState());
+    TEST_ASSERT_TRUE_MESSAGE(wm.getScanSnapshot().schedulePending,
+                             "Explicit refresh should mark scan scheduling as pending");
+    TEST_ASSERT_EQUAL(WiFiManager::WM_SCAN_SCHEDULE_USER_REFRESH,
+                      wm.getScanSnapshot().scheduledReason);
+    TEST_ASSERT_FALSE_MESSAGE(wm.hasValidScanResults(),
+                              "Queueing a scan should invalidate previous cached results");
+
+    Serial.println("[TEST]   Async scan request queues test completed successfully");
+}
+
+void test_async_scan_behavior() {
+    Serial.println("[TEST]   Testing repeated scan requests coalesce...");
+
+    WiFiManager wm;
+    wm.requestAsyncScan(true);
+    wm.requestAsyncScan(true);
+    wm.requestAsyncScan(true);
+
+    TEST_ASSERT_EQUAL(WiFiManager::WM_SCAN_QUEUED, wm.getScanState());
+    TEST_ASSERT_TRUE_MESSAGE(wm.getScanSnapshot().schedulePending,
+                             "Repeated refresh clicks should still leave one pending schedule");
+    TEST_ASSERT_EQUAL(WiFiManager::WM_SCAN_SCHEDULE_USER_REFRESH,
+                      wm.getScanSnapshot().scheduledReason);
+    TEST_ASSERT_FALSE_MESSAGE(wm.hasValidScanResults(),
+                              "Repeated refresh requests should keep a single queued scan lifecycle");
+
+    Serial.println("[TEST]   Repeated scan requests coalesce test completed successfully");
+}
+
+void test_scan_status_checking() {
+    Serial.println("[TEST]   Testing cached scan snapshot state...");
+
+    WiFiManager wm;
+
+#ifdef UNIT_TEST
+    std::vector<WiFiManager::WiFiScanNetwork> results = {
+        { "Office", -48, 1 },
+        { "Guest", -70, 0 }
+    };
+    wm.wmTestInjectScanResults(results);
+
+    TEST_ASSERT_TRUE_MESSAGE(wm.hasValidScanResults(),
+                             "Injected scan snapshot should be marked valid");
+    TEST_ASSERT_EQUAL(WiFiManager::WM_SCAN_COMPLETE, wm.getScanState());
+    TEST_ASSERT_EQUAL(static_cast<size_t>(2), wm.getScanResults().size());
+    TEST_ASSERT_EQUAL_STRING("Office", wm.getScanResults()[0].ssid.c_str());
+#else
+    TEST_IGNORE_MESSAGE("UNIT_TEST helpers unavailable");
+#endif
+
+    Serial.println("[TEST]   Cached scan snapshot state test completed successfully");
+}
+
+void test_scan_completion_wait() {
+    Serial.println("[TEST]   Testing scan timeout transition...");
+
+    WiFiManager wm;
+
+#ifdef UNIT_TEST
+    wm.wmTestSetPortalActive(true);
+    wm.wmTestForceScanState(WiFiManager::WM_SCAN_RUNNING);
+    wm.wmTestSetScanStartedAt(millis() - 20000);
+    wm.wmTestSetScanTimeoutMs(1000);
+    wm.process();
+
+    TEST_ASSERT_EQUAL(WiFiManager::WM_SCAN_TIMEOUT, wm.getScanState());
+    TEST_ASSERT_FALSE_MESSAGE(wm.hasValidScanResults(),
+                              "Timed out scans should not leave cached results marked valid");
+#else
+    TEST_IGNORE_MESSAGE("UNIT_TEST helpers unavailable");
+#endif
+
+    Serial.println("[TEST]   Scan timeout transition test completed successfully");
+}
+
+void test_scan_cancels_when_connect_pending() {
+    Serial.println("[TEST]   Testing scan cancellation during connect...");
+
+    WiFiManager wm;
+
+#ifdef UNIT_TEST
+    wm.wmTestSetPortalActive(true);
+    wm.wmTestForceScanState(WiFiManager::WM_SCAN_RUNNING);
+    wm.wmTestSetScanStartedAt(millis());
+    wm.wmTestSetConnectPending(true);
+    wm.process();
+
+    TEST_ASSERT_EQUAL(WiFiManager::WM_SCAN_IDLE, wm.getScanState());
+    TEST_ASSERT_FALSE_MESSAGE(wm.getScanSnapshot().schedulePending,
+                              "Connect flow should cancel any in-flight async scan");
+#else
+    TEST_IGNORE_MESSAGE("UNIT_TEST helpers unavailable");
+#endif
+
+    Serial.println("[TEST]   Scan cancellation during connect test completed successfully");
+}
+
+void test_scan_cancels_when_lifecycle_blocked() {
+    Serial.println("[TEST]   Testing scan cancellation during lifecycle block...");
+
+    WiFiManager wm;
+
+#ifdef UNIT_TEST
+    wm.wmTestSetPortalActive(true);
+    wm.requestAsyncScan(true);
+    wm.wmTestSetScanLifecycleBlocked(true);
+    wm.process();
+
+    TEST_ASSERT_EQUAL(WiFiManager::WM_SCAN_IDLE, wm.getScanState());
+    TEST_ASSERT_FALSE_MESSAGE(wm.getScanSnapshot().schedulePending,
+                              "Lifecycle blocking should leave scan engine idle");
+#else
+    TEST_IGNORE_MESSAGE("UNIT_TEST helpers unavailable");
+#endif
+
+    Serial.println("[TEST]   Scan cancellation during lifecycle block test completed successfully");
+}
+
+void test_scan_generation_invalidated_on_reset() {
+    Serial.println("[TEST]   Testing scan generation invalidation on reset...");
+
+    WiFiManager wm;
+
+#ifdef UNIT_TEST
+    wm.wmTestSetScanGenerations(4, 4, 4);
+    wm.wmTestSetScanCompletionPending(3);
+    wm.wmTestClearScanResults();
+
+    TEST_ASSERT_EQUAL(WiFiManager::WM_SCAN_IDLE, wm.getScanState());
+    TEST_ASSERT_TRUE_MESSAGE(wm.getScanSnapshot().generation > 4,
+                             "Resetting scan state should invalidate older completion generations");
+    TEST_ASSERT_FALSE_MESSAGE(wm.getScanSnapshot().completionPending,
+                              "Resetting scan state should clear pending completion callbacks");
+#else
+    TEST_IGNORE_MESSAGE("UNIT_TEST helpers unavailable");
+#endif
+
+    Serial.println("[TEST]   Scan generation invalidation on reset test completed successfully");
+}
+