Proposal: v3 async portal migration path — translations and a defined compatibility boundary

The long-running async-webserver work has shown that this is not a small backend swap. The synchronous and asynchronous server APIs differ in request handling, response lifetimes, uploads, route setup, shutdown, and callback context. Keeping both implementations in one code path has made the work difficult to complete and maintain.

I have been maintaining a fork that took the other approach: an async-only, templated/chunked portal implementation for ESP8266 and ESP32:

https://github.com/alexhopeoconnor/WiFiManager/tree/device-framework

It uses ESPAsyncWebServer, ESPAsyncTCP on ESP8266, and AsyncTCP on ESP32. It also avoids building large complete portal pages in String objects, which is relevant to the ESP8266 rendering/memory issues discussed in #1787.

This is not a PR proposal in its current form. The fork is a substantial refactor with intentional breaking changes:

• the web server and handler model are asynchronous;
• the portal is rendered through templates and a local JSON browser protocol;
• portal lifecycle and application-server handoff have changed;
• some legacy portal customisation and raw route/HTML injection APIs are no longer supported;
• callers must cooperate with portal processing rather than assuming the former blocking flow.

Trying to merge it as a normal feature PR, while retaining every existing API and the synchronous server implementation, would create a very large and difficult-to-test compatibility layer.

Proposed direction

If there is interest in moving WiFiManager forward, I think this should be treated as a new major version rather than a backwards-compatible minor release.

A possible v3 scope would be:

1. Adopt one maintained asynchronous portal architecture for ESP8266 and ESP32, rather than indefinitely maintaining sync and async implementations in parallel.

2. Restore multi-language support in the templated portal model. The current fork does not retain upstream's legacy language resources, so this needs to be designed properly rather than copied mechanically.

3. Audit the public API and retain compatibility where it is inexpensive and meaningful:

   • keep core provisioning, parameter, timeout, and callback APIs where practical;
   • provide deprecated wrappers where they remain safe;
   • clearly document APIs that cannot retain equivalent behaviour under an async portal;
   • provide migration examples for common sketches.

4. Make breaking portal-customisation changes explicit. A supported configuration/presentation API is more maintainable than arbitrary server-route or raw page replacement hooks, but users need a clear migration path.

5. Require ESP8266 and ESP32 compile coverage, plus focused hardware checks for portal rendering, scan behaviour, save/connect, and port handoff.

The fork has passing clean-consumer and example compilation checks for both supported targets, but it should be viewed as a reference implementation and migration starting point—not something to merge unchanged.

The key question is whether maintainers and contributors would support a deliberately breaking major-version effort with a defined compatibility boundary. If so, I am happy to help turn the existing work into smaller, reviewable pieces, beginning with an API/feature compatibility matrix and a plan for restoring translations.