web_server.cpp

#include "web_server.h"
#include "config.h"
#include "espnow_comm.h"
#include "finish_gate.h"
#include "start_gate.h"
#include "wled_integration.h"
#include "audio_manager.h"
#include "lidar_sensor.h"
#include "html_index.h"
#include "html_config.h"
#include "html_console.h"
#include "html_start_status.h"
#include "html_chartjs.h"
#include "html_speedtrap_status.h"
#include <ArduinoJson.h>
#include <LittleFS.h>
#include <WiFi.h>
#include <HTTPClient.h>
#include <HTTPUpdate.h>
#include <NetworkClientSecure.h>
#include <Update.h>
#include <esp_mac.h>
#include <Wire.h>

WebServer server(80);
WebSocketsServer webSocket(81);
SerialTee serialTee;

// ============================================================================
// FIRMWARE UPDATE — Root CA certs for GitHub TLS verification
// ============================================================================
// Two root CAs covering GitHub's TLS chains (extracted Feb 2026):
// 1. Sectigo Public Server Authentication Root E46 (cross-signed by USERTrust ECC)
//    Covers: api.github.com, github.com — Expires: Jan 18 2038
// 2. USERTrust RSA Certification Authority (cross-signed by AAA Certificate Services)
//    Covers: objects.githubusercontent.com — Expires: Dec 31 2028
// If these expire or GitHub rotates CAs, the firmware falls back to setInsecure()
// and logs a warning. The next firmware update then delivers fresh certs.
static const char github_root_ca_pem[] PROGMEM = R"CERT(
-----BEGIN CERTIFICATE-----
MIIDRjCCAsugAwIBAgIQGp6v7G3o4ZtcGTFBto2Q3TAKBggqhkjOPQQDAzCBiDEL
MAkGA1UEBhMCVVMxEzARBgNVBAgTCk5ldyBKZXJzZXkxFDASBgNVBAcTC0plcnNl
eSBDaXR5MR4wHAYDVQQKExVUaGUgVVNFUlRSVVNUIE5ldHdvcmsxLjAsBgNVBAMT
JVVTRVJUcnVzdCBFQ0MgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkwHhcNMjEwMzIy
MDAwMDAwWhcNMzgwMTE4MjM1OTU5WjBfMQswCQYDVQQGEwJHQjEYMBYGA1UEChMP
U2VjdGlnbyBMaW1pdGVkMTYwNAYDVQQDEy1TZWN0aWdvIFB1YmxpYyBTZXJ2ZXIg
QXV0aGVudGljYXRpb24gUm9vdCBFNDYwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAAR2
+pmpbiDt+dd34wc7qNs9Xzjoq1WmVk/WSOrsfy2qw7LFeeyZYX8QeccCWvkEN/U0
NSt3zn8gj1KjAIns1aeibVvjS5KToID1AZTc8GgHHs3u/iVStSBDHBv+6xnOQ6Oj
ggEgMIIBHDAfBgNVHSMEGDAWgBQ64QmG1M8ZwpZ2dEl23OA1xmNjmjAdBgNVHQ4E
FgQU0SLaTFnxS18mOKqd1u7rDcP7qWEwDgYDVR0PAQH/BAQDAgGGMA8GA1UdEwEB
/wQFMAMBAf8wHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMBEGA1UdIAQK
MAgwBgYEVR0gADBQBgNVHR8ESTBHMEWgQ6BBhj9odHRwOi8vY3JsLnVzZXJ0cnVz
dC5jb20vVVNFUlRydXN0RUNDQ2VydGlmaWNhdGlvbkF1dGhvcml0eS5jcmwwNQYI
KwYBBQUHAQEEKTAnMCUGCCsGAQUFBzABhhlodHRwOi8vb2NzcC51c2VydHJ1c3Qu
Y29tMAoGCCqGSM49BAMDA2kAMGYCMQCMCyBit99vX2ba6xEkDe+YO7vC0twjbkv9
PKpqGGuZ61JZryjFsp+DFpEclCVy4noCMQCwvZDXD/m2Ko1HA5Bkmz7YQOFAiNDD
49IWa2wdT7R3DtODaSXH/BiXv8fwB9su4tU=
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIFgTCCBGmgAwIBAgIQOXJEOvkit1HX02wQ3TE1lTANBgkqhkiG9w0BAQwFADB7
MQswCQYDVQQGEwJHQjEbMBkGA1UECAwSR3JlYXRlciBNYW5jaGVzdGVyMRAwDgYD
VQQHDAdTYWxmb3JkMRowGAYDVQQKDBFDb21vZG8gQ0EgTGltaXRlZDEhMB8GA1UE
AwwYQUFBIENlcnRpZmljYXRlIFNlcnZpY2VzMB4XDTE5MDMxMjAwMDAwMFoXDTI4
MTIzMTIzNTk1OVowgYgxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpOZXcgSmVyc2V5
MRQwEgYDVQQHEwtKZXJzZXkgQ2l0eTEeMBwGA1UEChMVVGhlIFVTRVJUUlVTVCBO
ZXR3b3JrMS4wLAYDVQQDEyVVU0VSVHJ1c3QgUlNBIENlcnRpZmljYXRpb24gQXV0
aG9yaXR5MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAgBJlFzYOw9sI
s9CsVw127c0n00ytUINh4qogTQktZAnczomfzD2p7PbPwdzx07HWezcoEStH2jnG
vDoZtF+mvX2do2NCtnbyqTsrkfjib9DsFiCQCT7i6HTJGLSR1GJk23+jBvGIGGqQ
Ijy8/hPwhxR79uQfjtTkUcYRZ0YIUcuGFFQ/vDP+fmyc/xadGL1RjjWmp2bIcmfb
IWax1Jt4A8BQOujM8Ny8nkz+rwWWNR9XWrf/zvk9tyy29lTdyOcSOk2uTIq3XJq0
tyA9yn8iNK5+O2hmAUTnAU5GU5szYPeUvlM3kHND8zLDU+/bqv50TmnHa4xgk97E
xwzf4TKuzJM7UXiVZ4vuPVb+DNBpDxsP8yUmazNt925H+nND5X4OpWaxKXwyhGNV
icQNwZNUMBkTrNN9N6frXTpsNVzbQdcS2qlJC9/YgIoJk2KOtWbPJYjNhLixP6Q5
D9kCnusSTJV882sFqV4Wg8y4Z+LoE53MW4LTTLPtW//e5XOsIzstAL81VXQJSdhJ
WBp/kjbmUZIO8yZ9HE0XvMnsQybQv0FfQKlERPSZ51eHnlAfV1SoPv10Yy+xUGUJ
5lhCLkMaTLTwJUdZ+gQek9QmRkpQgbLevni3/GcV4clXhB4PY9bpYrrWX1Uu6lzG
KAgEJTm4Diup8kyXHAc/DVL17e8vgg8CAwEAAaOB8jCB7zAfBgNVHSMEGDAWgBSg
EQojPpbxB+zirynvgqV/0DCktDAdBgNVHQ4EFgQUU3m/WqorSs9UgOHYm8Cd8rID
ZsswDgYDVR0PAQH/BAQDAgGGMA8GA1UdEwEB/wQFMAMBAf8wEQYDVR0gBAowCDAG
BgRVHSAAMEMGA1UdHwQ8MDowOKA2oDSGMmh0dHA6Ly9jcmwuY29tb2RvY2EuY29t
L0FBQUNlcnRpZmljYXRlU2VydmljZXMuY3JsMDQGCCsGAQUFBwEBBCgwJjAkBggr
BgEFBQcwAYYYaHR0cDovL29jc3AuY29tb2RvY2EuY29tMA0GCSqGSIb3DQEBDAUA
A4IBAQAYh1HcdCE9nIrgJ7cz0C7M7PDmy14R3iJvm3WOnnL+5Nb+qh+cli3vA0p+
rvSNb3I8QzvAP+u431yqqcau8vzY7qN7Q/aGNnwU4M309z/+3ri0ivCRlv79Q2R+
/czSAaF9ffgZGclCKxO/WIu6pKJmBHaIkU4MiRTOok3JMrO66BQavHHxW/BBC5gA
CiIDEOUMsfnNkjcZ7Tvx5Dq2+UUTJnWvu6rvP3t3O9LEApE9GQDTF1w52z97GA1F
zZOFli9d31kWTz9RvdVFGD/tSo7oBmF0Ixa1DVBzJ0RHfxBdiSprhTEUxOipakyA
vGp4z7h/jnZymQyd/teRCBaho1+V
-----END CERTIFICATE-----
)CERT";

// Firmware update scheduling state (set by HTTP handler, consumed by loop)
static volatile bool firmwareUpdateScheduled = false;
static volatile bool firmwareUpdateInProgress = false;
static char firmwareUpdateUrl[384] = "";
static char firmwareExpectedMd5[33] = "";   // 32 hex chars + null
static char firmwareUpdateStatus[128] = ""; // Human-readable status message

// ============================================================================
// FILE SERVING HELPERS
// ============================================================================
static String getContentType(const String& path) {
  if (path.endsWith(".html")) return "text/html";
  if (path.endsWith(".css"))  return "text/css";
  if (path.endsWith(".js"))   return "application/javascript";
  if (path.endsWith(".json")) return "application/json";
  if (path.endsWith(".csv"))  return "text/csv";
  return "text/plain";
}

// ============================================================================
// API AUTHENTICATION
// Simple API key check for destructive endpoints.
// Reuses OTA password as the key. Returns true if authorized.
// ============================================================================
static bool requireAuth() {
  if (strlen(cfg.ota_password) == 0) return true; // No password set = open
  String key = server.header("X-API-Key");
  if (key == cfg.ota_password) return true;
  server.send(401, "application/json", "{\"error\":\"Unauthorized. Provide X-API-Key header.\"}");
  return false;
}

static void serveFile(const String& path, const String& contentType) {
  if (LittleFS.exists(path)) {
    File file = LittleFS.open(path, "r");
    server.streamFile(file, contentType);
    file.close();
  } else {
    server.send(404, "text/plain", "File not found: " + path);
  }
}

// ============================================================================
// WEBSOCKET HANDLER
// ============================================================================
static void webSocketEvent(uint8_t num, WStype_t type, uint8_t *payload, size_t length) {
  switch (type) {
    case WStype_CONNECTED:
      broadcastState();
      break;

    case WStype_TEXT: {
      StaticJsonDocument<512> doc;  // 512 to fit Google Sheets URLs
      DeserializationError error = deserializeJson(doc, payload);
      if (error) return;

      const char* cmd = doc["cmd"];
      if (!cmd) return;

      if (strcmp(cmd, "arm") == 0) {
        raceState = ARMED;
        portENTER_CRITICAL(&finishTimerMux);
        startTime_us = 0;
        finishTime_us = 0;
        portEXIT_CRITICAL(&finishTimerMux);
        // Aggressive clock sync before race — guarantees sub-50µs accuracy
        sendToPeer(MSG_SYNC_REQ, nowUs(), 0);
        // Tell start gate to arm too
        sendToPeer(MSG_ARM_CMD, nowUs(), 0);
        setWLEDState("armed");
        broadcastState();
      }
      else if (strcmp(cmd, "reset") == 0) {
        raceState = IDLE;
        portENTER_CRITICAL(&finishTimerMux);
        startTime_us = 0;
        finishTime_us = 0;
        portEXIT_CRITICAL(&finishTimerMux);
        // Tell start gate to disarm
        sendToPeer(MSG_DISARM_CMD, nowUs(), 0);
        setWLEDState("idle");
        broadcastState();
      }
      else if (strcmp(cmd, "setCar") == 0) {
        currentCar = doc["name"].as<String>();
        currentWeight = doc["weight"];
      }
      else if (strcmp(cmd, "setTrack") == 0) {
        cfg.track_length_m = doc["length"];
      }
      else if (strcmp(cmd, "syncClock") == 0) {
        sendToPeer(MSG_SYNC_REQ, nowUs(), 0);
      }
      else if (strcmp(cmd, "setDryRun") == 0) {
        dryRunMode = doc["enabled"] | false;
        LOG.printf("[WEB] Dry-run mode %s\n", dryRunMode ? "ENABLED" : "DISABLED");
        broadcastState();
      }
      else if (strcmp(cmd, "setSheetsUrl") == 0) {
        // Update Google Sheets URL in config and save (no reboot needed)
        const char* url = doc["url"];
        if (url) {
          strncpy(cfg.google_sheets_url, url, sizeof(cfg.google_sheets_url) - 1);
          cfg.google_sheets_url[sizeof(cfg.google_sheets_url) - 1] = '\0';
          saveConfig();
          LOG.printf("[WEB] Google Sheets URL updated: %s\n", cfg.google_sheets_url);
        }
      }
      break;
    }
    default:
      break;
  }
}

// ============================================================================
// BROADCAST STATE
// ============================================================================
void broadcastState() {
  StaticJsonDocument<1024> doc;

  const char* stateStr;
  switch (raceState) {
    case IDLE:     stateStr = "IDLE"; break;
    case ARMED:    stateStr = "ARMED"; break;
    case RACING:   stateStr = "RACING"; break;
    case FINISHED: stateStr = "FINISHED"; break;
    default:       stateStr = "UNKNOWN"; break;
  }

  doc["state"] = stateStr;
  doc["connected"] = peerConnected;
  doc["car"] = currentCar;
  doc["weight"] = currentWeight;
  doc["trackLength"] = cfg.track_length_m;
  doc["scaleFactor"] = cfg.scale_factor;
  doc["totalRuns"] = totalRuns;
  doc["role"] = cfg.role;
  doc["units"] = cfg.units;
  doc["google_sheets_url"] = cfg.google_sheets_url;
  doc["dryRun"] = dryRunMode;

  // Speed trap mid-track velocity (if available)
  if (midTrackSpeed_mps > 0) {
    doc["midTrack_mps"] = midTrackSpeed_mps;
    doc["midTrack_mph"] = midTrackSpeed_mps * MPS_TO_MPH;
    doc["midTrack_scale_mph"] = midTrackSpeed_mps * MPS_TO_MPH * (double)cfg.scale_factor;
  }

  // LiDAR sensor data (if enabled)
  if (cfg.lidar_enabled) {
    JsonObject lidar = doc.createNestedObject("lidar");
    LidarState ls = getLidarState();
    lidar["state"] = (ls == LIDAR_NO_CAR) ? "empty" :
                     (ls == LIDAR_CAR_STAGED) ? "staged" : "launched";
    lidar["distance_mm"] = getDistanceMM();
  }

  // Proximity arm sensor data (HW-870 on start gate)
  if (isProxArmEnabled()) {
    doc["proxArm"] = true;
    doc["proxCar"] = isProxCarPresent();
  }

  // Peer count for dashboard status indicators
  int onlinePeers = 0;
  for (int i = 0; i < peerCount; i++) {
    if (peers[i].paired && getPeerStatus(peers[i]) == PEER_ONLINE) onlinePeers++;
  }
  doc["peerCount"] = peerCount;
  doc["onlinePeers"] = onlinePeers;

  // Atomic snapshot of 64-bit timing vars (shared with ISR and ESP-NOW task)
  uint64_t bcastFinish, bcastStart;
  portENTER_CRITICAL(&finishTimerMux);
  bcastFinish = finishTime_us;
  bcastStart = startTime_us;
  portEXIT_CRITICAL(&finishTimerMux);

  if (raceState == FINISHED && bcastStart > 0 && bcastFinish > 0) {
    // Use SIGNED math to detect underflows instead of wrapping to huge values
    int64_t elapsed_us = (int64_t)bcastFinish - (int64_t)bcastStart;

    // Sanity check: must be positive and < 60 seconds
    if (elapsed_us > 0 && elapsed_us < MAX_RACE_DURATION_US) {
      double elapsed_s = elapsed_us / 1000000.0;
      double speed_ms = cfg.track_length_m / elapsed_s;

      doc["time"] = elapsed_s;
      doc["speed_mps"] = speed_ms;
      doc["speed_mph"] = speed_ms * MPS_TO_MPH;
      doc["scale_mph"] = speed_ms * MPS_TO_MPH * (double)cfg.scale_factor;

      double mass_kg = currentWeight / 1000.0;
      doc["momentum"] = mass_kg * speed_ms;
      doc["ke"] = 0.5 * mass_kg * speed_ms * speed_ms;
    } else {
      // Timing error - report zeros instead of garbage
      doc["time"] = 0;
      doc["speed_mph"] = 0;
      doc["scale_mph"] = 0;
      doc["momentum"] = 0;
      doc["ke"] = 0;
      doc["timing_error"] = true;
    }
  }

  String output;
  serializeJson(doc, output);
  webSocket.broadcastTXT(output);
}

// ============================================================================
// CONFIG API HANDLERS
// ============================================================================
static void handleApiConfig() {
  if (server.method() == HTTP_GET) {
    server.send(200, "application/json", configToJson());
  }
  else if (server.method() == HTTP_POST) {
    if (!requireAuth()) return;
    String body = server.arg("plain");
    if (body.length() == 0) {
      server.send(400, "application/json", "{\"error\":\"Empty body\"}");
      return;
    }

    DeviceConfig tempCfg;
    setDefaults(tempCfg);

    // Try parsing the JSON
    String testJson = body;
    if (!configFromJson(testJson)) {
      // configFromJson modifies global cfg, so restore defaults if parse fails
      loadConfig();
      server.send(400, "application/json", "{\"error\":\"Invalid config JSON\"}");
      return;
    }

    // configFromJson already loaded into global cfg
    cfg.configured = true;

    // Auto-generate role-based hostname if user left it blank or default
    if (strlen(cfg.hostname) == 0 || strcmp(cfg.hostname, "masstrap") == 0) {
      char suffix[5];
      getMacSuffix(suffix, sizeof(suffix));
      generateHostname(cfg.role, suffix, cfg.hostname, sizeof(cfg.hostname));
      LOG.printf("[CONFIG] Auto-generated hostname: %s\n", cfg.hostname);
    }

    if (!validateConfig(cfg)) {
      loadConfig(); // Restore previous
      server.send(400, "application/json", "{\"error\":\"Config validation failed\"}");
      return;
    }

    if (!saveConfig()) {
      server.send(500, "application/json", "{\"error\":\"Failed to save config\"}");
      return;
    }

    // Include hostname in response so client knows where to redirect
    String resp = "{\"status\":\"ok\",\"message\":\"Config saved. Rebooting...\",\"hostname\":\"";
    resp += cfg.hostname;
    resp += "\"}";
    server.send(200, "application/json", resp);
    server.client().flush();          // Force TCP send buffer drain
    delay(1000);
    WiFi.softAPdisconnect(true);      // Kick AP clients so CNA sheet closes
    delay(500);
    ESP.restart();
  }
}

static void handleApiScan() {
  // Use passive scan in AP mode to avoid disrupting the radio state
  // Active scans can cause "association refused" on next WiFi.begin()
  wifi_scan_config_t scanConfig = {};
  scanConfig.scan_type = WIFI_SCAN_TYPE_PASSIVE;
  scanConfig.scan_time.passive = 300;  // 300ms per channel

  int n = WiFi.scanNetworks(false, false, false, scanConfig.scan_time.passive);

  StaticJsonDocument<1024> doc;
  JsonArray arr = doc.to<JsonArray>();

  for (int i = 0; i < n && i < 20; i++) {
    JsonObject net = arr.createNestedObject();
    net["ssid"] = WiFi.SSID(i);
    net["rssi"] = WiFi.RSSI(i);
    net["secure"] = (WiFi.encryptionType(i) != WIFI_AUTH_OPEN);
  }

  WiFi.scanDelete();

  String output;
  serializeJson(doc, output);
  server.send(200, "application/json", output);
}

static void handleApiMac() {
  StaticJsonDocument<128> doc;

  // WiFi.macAddress() returns STA MAC which may be 00:00:00:00:00:00 in AP-only mode
  // Use esp_efuse_mac_get_default() to always get the base MAC burned into the chip
  uint8_t baseMac[6];
  esp_efuse_mac_get_default(baseMac);
  char macStr[18];
  snprintf(macStr, sizeof(macStr), "%02X:%02X:%02X:%02X:%02X:%02X",
           baseMac[0], baseMac[1], baseMac[2], baseMac[3], baseMac[4], baseMac[5]);
  doc["mac"] = macStr;

  String output;
  serializeJson(doc, output);
  server.send(200, "application/json", output);
}

static void handleApiBackup() {
  String json = configToJson();
  server.sendHeader("Content-Disposition", "attachment; filename=masstrap-config.json");
  server.send(200, "application/json", json);
}

// ============================================================================
// SYSTEM SNAPSHOT API - Full backup/restore of config + garage + history
// ============================================================================
static void handleApiSystemBackup() {
  // Read all three data files from LittleFS
  String configJson = configToJson();

  String garageJson = "[]";
  if (LittleFS.exists("/garage.json")) {
    File f = LittleFS.open("/garage.json", "r");
    garageJson = f.readString();
    f.close();
  }

  String historyJson = "[]";
  if (LittleFS.exists("/history.json")) {
    File f = LittleFS.open("/history.json", "r");
    historyJson = f.readString();
    f.close();
  }

  // Build the unified snapshot envelope
  DynamicJsonDocument doc(16384);
  doc["snapshot_version"] = 1;
  doc["firmware_version"] = FIRMWARE_VERSION;
  doc["hostname"] = cfg.hostname;
  doc["role"] = cfg.role;

  // Parse config into nested object
  DynamicJsonDocument configDoc(1536);
  deserializeJson(configDoc, configJson);
  doc["config"] = configDoc.as<JsonObject>();

  // Parse garage into nested array
  DynamicJsonDocument garageDoc(4096);
  deserializeJson(garageDoc, garageJson);
  doc["garage"] = garageDoc.as<JsonArray>();

  // Parse history into nested array
  DynamicJsonDocument historyDoc(8192);
  deserializeJson(historyDoc, historyJson);
  doc["history"] = historyDoc.as<JsonArray>();

  String output;
  serializeJsonPretty(doc, output);

  server.sendHeader("Content-Disposition", "attachment; filename=masstrap-system-backup.json");
  server.send(200, "application/json", output);
  LOG.printf("[WEB] System snapshot exported (%d bytes)\n", output.length());
}

static void handleApiSystemRestore() {
  if (!requireAuth()) return;

  String body = server.arg("plain");
  if (body.length() == 0) {
    server.send(400, "application/json", "{\"error\":\"Empty body\"}");
    return;
  }

  DynamicJsonDocument doc(16384);
  DeserializationError err = deserializeJson(doc, body);
  if (err) {
    server.send(400, "application/json", "{\"error\":\"Invalid JSON\"}");
    return;
  }

  if (!doc.containsKey("snapshot_version") || !doc.containsKey("config")) {
    server.send(400, "application/json", "{\"error\":\"Not a valid system snapshot\"}");
    return;
  }

  bool skipNetwork = server.hasArg("skip_network") && server.arg("skip_network") == "true";

  // 1. Restore config
  JsonObject configObj = doc["config"];
  if (!configObj.isNull()) {
    if (skipNetwork) {
      // Clone mode: keep this device's network identity
      configObj["network"]["wifi_ssid"] = cfg.wifi_ssid;
      configObj["network"]["wifi_pass"] = cfg.wifi_pass;
      configObj["network"]["hostname"] = cfg.hostname;
    }
    String configStr;
    serializeJson(configObj, configStr);
    File f = LittleFS.open(CONFIG_FILE, "w");
    if (f) { f.print(configStr); f.close(); }
  }

  // 2. Restore garage
  JsonArray garageArr = doc["garage"];
  if (!garageArr.isNull()) {
    String garageStr;
    serializeJson(garageArr, garageStr);
    File f = LittleFS.open("/garage.json", "w");
    if (f) { f.print(garageStr); f.close(); }
  }

  // 3. Restore history
  JsonArray historyArr = doc["history"];
  if (!historyArr.isNull()) {
    String historyStr;
    serializeJson(historyArr, historyStr);
    File f = LittleFS.open("/history.json", "w");
    if (f) { f.print(historyStr); f.close(); }
  }

  LOG.printf("[WEB] System snapshot restored (skip_network=%s). Rebooting...\n",
                skipNetwork ? "true" : "false");

  server.send(200, "application/json",
    "{\"status\":\"ok\",\"message\":\"System snapshot restored. Rebooting...\"}");
  server.client().flush();
  delay(1000);
  WiFi.softAPdisconnect(true);
  delay(500);
  ESP.restart();
}

static void handleApiRestore() {
  if (!requireAuth()) return;
  String body = server.arg("plain");
  if (body.length() == 0) {
    server.send(400, "application/json", "{\"error\":\"Empty body\"}");
    return;
  }

  // Validate JSON structure
  StaticJsonDocument<1024> doc;
  DeserializationError err = deserializeJson(doc, body);
  if (err) {
    server.send(400, "application/json", "{\"error\":\"Invalid JSON\"}");
    return;
  }

  if (!doc.containsKey("version") || !doc.containsKey("configured")) {
    server.send(400, "application/json", "{\"error\":\"Not a valid config file\"}");
    return;
  }

  // Write directly to config file
  File f = LittleFS.open(CONFIG_FILE, "w");
  if (!f) {
    server.send(500, "application/json", "{\"error\":\"Failed to write config\"}");
    return;
  }
  f.print(body);
  f.close();

  server.send(200, "application/json", "{\"status\":\"ok\",\"message\":\"Config restored. Rebooting...\"}");
  server.client().flush();
  delay(1000);
  WiFi.softAPdisconnect(true);
  delay(500);
  ESP.restart();
}

static void handleApiReset() {
  if (!requireAuth()) return;
  server.send(200, "application/json", "{\"status\":\"ok\",\"message\":\"Factory reset. Rebooting...\"}");
  server.client().flush();
  delay(1000);
  WiFi.softAPdisconnect(true);
  delay(500);
  resetConfig();
}

static void handleApiInfo() {
  StaticJsonDocument<512> doc;
  doc["project"] = PROJECT_NAME;
  doc["firmware"] = FIRMWARE_VERSION;
  doc["role"] = cfg.role;
  doc["hostname"] = cfg.hostname;
  doc["uptime_s"] = millis() / 1000;
  doc["free_heap"] = ESP.getFreeHeap();
  doc["wifi_rssi"] = WiFi.RSSI();
  doc["wifi_channel"] = WiFi.channel();
  doc["peer_connected"] = peerConnected;
  doc["peer_count"] = peerCount;
  doc["ip"] = WiFi.localIP().toString();
  doc["audio_enabled"] = cfg.audio_enabled;
  doc["lidar_enabled"] = cfg.lidar_enabled;
  doc["clock_offset_us"] = (double)clockOffset_us;

  String output;
  serializeJson(doc, output);
  server.send(200, "application/json", output);
}

// WiFi diagnostic status — extern from MASS_Trap.ino
extern bool wifiConnected;
extern char wifiFailReason[64];

static void handleApiWifiStatus() {
  StaticJsonDocument<256> doc;
  doc["connected"] = (WiFi.status() == WL_CONNECTED);
  doc["ssid"] = cfg.wifi_ssid;
  doc["ip"] = WiFi.localIP().toString();
  doc["rssi"] = WiFi.RSSI();
  doc["channel"] = WiFi.channel();
  doc["mode"] = (WiFi.getMode() == WIFI_AP) ? "AP" :
                (WiFi.getMode() == WIFI_STA) ? "STA" :
                (WiFi.getMode() == WIFI_AP_STA) ? "AP_STA" : "OFF";
  if (strlen(wifiFailReason) > 0) {
    doc["fail_reason"] = wifiFailReason;
  }

  String output;
  serializeJson(doc, output);
  server.send(200, "application/json", output);
}

static void handleApiVersion() {
  StaticJsonDocument<256> doc;
  doc["firmware"] = FIRMWARE_VERSION;
  doc["web_ui"] = WEB_UI_VERSION;
  doc["build_date"] = BUILD_DATE;
  doc["build_time"] = BUILD_TIME;
#if CONFIG_IDF_TARGET_ESP32S3
  doc["board"] = "ESP32-S3";
#elif CONFIG_IDF_TARGET_ESP32
  doc["board"] = "ESP32";
#else
  doc["board"] = "Unknown";
#endif

  String output;
  serializeJson(doc, output);
  server.send(200, "application/json", output);
}

// ============================================================================
// HARDWARE DIAGNOSTICS — Remote CODE 3 Troubleshooting
// ============================================================================
// Comprehensive system health check for remote support. Reports pin states,
// I2C bus scan, memory, radio, filesystem, and peripheral status.
// Available in BOTH normal mode and setup mode — helps builders verify wiring
// before and after configuration.
static void handleApiDiagnostics() {
  DynamicJsonDocument doc(4096);

  // ---- SYSTEM INFO ----
  JsonObject sys = doc.createNestedObject("system");
  sys["firmware"] = FIRMWARE_VERSION;
  sys["role"] = cfg.role;
  sys["hostname"] = cfg.hostname;
  sys["uptime_s"] = millis() / 1000;
  sys["uptime_str"] = String(millis() / 3600000) + "h " +
                      String((millis() / 60000) % 60) + "m " +
                      String((millis() / 1000) % 60) + "s";
#if CONFIG_IDF_TARGET_ESP32S3
  sys["board"] = "ESP32-S3";
#elif CONFIG_IDF_TARGET_ESP32
  sys["board"] = "ESP32";
#else
  sys["board"] = "Unknown";
#endif
  sys["cpu_freq_mhz"] = ESP.getCpuFreqMHz();
  sys["flash_size"] = ESP.getFlashChipSize();
  sys["flash_speed"] = ESP.getFlashChipSpeed();
  sys["sdk"] = ESP.getSdkVersion();

  // ---- MEMORY ----
  JsonObject mem = doc.createNestedObject("memory");
  mem["free_heap"] = ESP.getFreeHeap();
  mem["min_free_heap"] = ESP.getMinFreeHeap();
  mem["max_alloc_heap"] = ESP.getMaxAllocHeap();
  mem["total_heap"] = ESP.getHeapSize();
  mem["heap_pct_free"] = (ESP.getHeapSize() > 0)
    ? (int)(100.0 * ESP.getFreeHeap() / ESP.getHeapSize()) : 0;
#ifdef BOARD_HAS_PSRAM
  mem["psram_total"] = ESP.getPsramSize();
  mem["psram_free"] = ESP.getFreePsram();
  mem["psram_pct_free"] = (ESP.getPsramSize() > 0)
    ? (int)(100.0 * ESP.getFreePsram() / ESP.getPsramSize()) : 0;
#else
  mem["psram_total"] = 0;
  mem["psram_free"] = 0;
#endif

  // ---- FILESYSTEM ----
  JsonObject fs = doc.createNestedObject("filesystem");
  fs["total_bytes"] = LittleFS.totalBytes();
  fs["used_bytes"] = LittleFS.usedBytes();
  fs["free_bytes"] = LittleFS.totalBytes() - LittleFS.usedBytes();
  fs["pct_used"] = (LittleFS.totalBytes() > 0)
    ? (int)(100.0 * LittleFS.usedBytes() / LittleFS.totalBytes()) : 0;

  // ---- WIFI ----
  JsonObject wifi = doc.createNestedObject("wifi");
  wifi["mode"] = (WiFi.getMode() == WIFI_AP) ? "AP" :
                 (WiFi.getMode() == WIFI_STA) ? "STA" :
                 (WiFi.getMode() == WIFI_AP_STA) ? "AP_STA" : "OFF";
  wifi["sta_connected"] = (WiFi.status() == WL_CONNECTED);
  wifi["sta_ip"] = WiFi.localIP().toString();
  wifi["sta_ssid"] = cfg.wifi_ssid;
  wifi["rssi"] = WiFi.RSSI();
  wifi["signal_quality"] = constrain(2 * (WiFi.RSSI() + 100), 0, 100);  // -100=0%, -50=100%
  wifi["channel"] = WiFi.channel();
  wifi["mac_sta"] = WiFi.macAddress();
  wifi["ap_ip"] = WiFi.softAPIP().toString();
  wifi["ap_clients"] = WiFi.softAPgetStationNum();

  // ---- ESP-NOW / PEERS ----
  JsonObject radio = doc.createNestedObject("espnow");
  radio["peer_connected"] = peerConnected;
  radio["peer_count"] = peerCount;
  radio["clock_offset_us"] = (double)clockOffset_us;  // Cast for JSON precision
  JsonArray peerList = radio.createNestedArray("peers");
  for (int i = 0; i < peerCount && i < MAX_PEERS; i++) {
    JsonObject p = peerList.createNestedObject();
    p["role"] = peers[i].role;
    p["hostname"] = peers[i].hostname;
    p["mac"] = formatMac(peers[i].mac);
    p["paired"] = peers[i].paired;
    unsigned long ago = millis() - peers[i].lastSeen;
    p["last_seen_ms"] = ago;
    p["status"] = (ago < PEER_ONLINE_THRESH_MS) ? "ONLINE" :
                  (ago < PEER_STALE_THRESH_MS) ? "STALE" : "OFFLINE";
  }

  // ---- RACE STATE ----
  JsonObject race = doc.createNestedObject("race");
  const char* stateNames[] = {"IDLE", "ARMED", "RACING", "FINISHED"};
  race["state"] = stateNames[(int)raceState];
  race["dry_run"] = dryRunMode;
  race["total_runs"] = totalRuns;
  race["current_car"] = currentCar;
  race["current_weight"] = currentWeight;

  // ---- PIN CONFIGURATION ----
  JsonObject pins = doc.createNestedObject("pins");

  // IR Sensor (primary)
  JsonObject irPin = pins.createNestedObject("ir_sensor");
  irPin["gpio"] = cfg.sensor_pin;
  irPin["configured"] = (cfg.sensor_pin > 0);
  if (cfg.sensor_pin > 0) {
    pinMode(cfg.sensor_pin, INPUT);
    irPin["state"] = digitalRead(cfg.sensor_pin) ? "HIGH" : "LOW";
    irPin["expected_idle"] = "HIGH (beam unbroken)";
    irPin["ok"] = (digitalRead(cfg.sensor_pin) == HIGH);
  }

  // IR Sensor 2 (speed trap)
  if (cfg.sensor_pin_2 > 0) {
    JsonObject ir2Pin = pins.createNestedObject("ir_sensor_2");
    ir2Pin["gpio"] = cfg.sensor_pin_2;
    pinMode(cfg.sensor_pin_2, INPUT);
    ir2Pin["state"] = digitalRead(cfg.sensor_pin_2) ? "HIGH" : "LOW";
    ir2Pin["expected_idle"] = "HIGH (beam unbroken)";
    ir2Pin["ok"] = (digitalRead(cfg.sensor_pin_2) == HIGH);
  }

  // LED pin
  JsonObject ledPin = pins.createNestedObject("led");
  ledPin["gpio"] = cfg.led_pin;
  ledPin["configured"] = (cfg.led_pin > 0);

  // Audio pins
  if (cfg.audio_enabled) {
    JsonObject audio = pins.createNestedObject("audio");
    audio["enabled"] = true;
    audio["bclk_gpio"] = cfg.i2s_bclk_pin;
    audio["lrc_gpio"] = cfg.i2s_lrc_pin;
    audio["dout_gpio"] = cfg.i2s_dout_pin;
    audio["volume"] = cfg.audio_volume;
    audio["playing"] = isPlaying();
  }

  // LiDAR pins
  if (cfg.lidar_enabled) {
    JsonObject lidar = pins.createNestedObject("lidar");
    lidar["enabled"] = true;
    lidar["rx_gpio"] = cfg.lidar_rx_pin;
    lidar["tx_gpio"] = cfg.lidar_tx_pin;
    lidar["threshold_mm"] = cfg.lidar_threshold_mm;
    lidar["distance_mm"] = getDistanceMM();
    const char* lidarStates[] = {"NO_CAR", "CAR_STAGED", "CAR_LAUNCHED"};
    lidar["state"] = lidarStates[(int)getLidarState()];
    lidar["ok"] = (getDistanceMM() > 0);  // 0 = no reading = possible wiring issue
  }

  // ---- I2C BUS SCAN ----
  // Scans the default I2C bus (SDA/SCL from board defaults) for connected devices.
  // This catches BNO055, OLED displays, BME280, or any other I2C peripheral.
  JsonObject i2c = doc.createNestedObject("i2c");
  Wire.begin();  // Initialize with default SDA/SCL for the board
  JsonArray devices = i2c.createNestedArray("devices");
  int deviceCount = 0;
  for (uint8_t addr = 1; addr < 127; addr++) {
    Wire.beginTransmission(addr);
    uint8_t err = Wire.endTransmission();
    if (err == 0) {
      JsonObject dev = devices.createNestedObject();
      char addrHex[8];
      snprintf(addrHex, sizeof(addrHex), "0x%02X", addr);
      dev["address"] = addrHex;
      // Identify well-known addresses
      const char* name = "Unknown";
      if (addr == 0x28 || addr == 0x29) name = "BNO055 IMU";
      else if (addr == 0x3C || addr == 0x3D) name = "SSD1306 OLED";
      else if (addr == 0x76 || addr == 0x77) name = "BME280/BMP280";
      else if (addr == 0x68 || addr == 0x69) name = "MPU6050/DS3231";
      else if (addr == 0x48) name = "ADS1115 ADC";
      else if (addr == 0x50) name = "AT24C EEPROM";
      else if (addr == 0x27 || addr == 0x3F) name = "PCF8574 I/O Expander";
      else if (addr == 0x5A) name = "MLX90614 IR Temp";
      else if (addr == 0x20) name = "PCF8574A I/O Expander";
      dev["device"] = name;
      deviceCount++;
    }
  }
  Wire.end();  // Release I2C bus
  i2c["device_count"] = deviceCount;

  // ---- WLED INTEGRATION ----
  if (strlen(cfg.wled_host) > 0) {
    JsonObject wled = doc.createNestedObject("wled");
    wled["host"] = cfg.wled_host;
    // Quick reachability check (50ms timeout — don't block long)
    HTTPClient http;
    http.begin("http://" + String(cfg.wled_host) + "/json/info");
    http.setTimeout(500);
    int code = http.GET();
    wled["reachable"] = (code == 200);
    wled["http_code"] = code;
    http.end();
  }

  // ---- CONFIG SUMMARY ----
  JsonObject config = doc.createNestedObject("config");
  config["configured"] = cfg.configured;
  config["version"] = cfg.version;
  config["network_mode"] = cfg.network_mode;
  config["track_length_m"] = cfg.track_length_m;
  config["scale_factor"] = cfg.scale_factor;
  config["units"] = cfg.units;
  config["audio_enabled"] = cfg.audio_enabled;
  config["lidar_enabled"] = cfg.lidar_enabled;
  config["has_wled"] = (strlen(cfg.wled_host) > 0);
  config["has_viewer_auth"] = (strlen(cfg.viewer_password) > 0);

  // ---- VERDICT ----
  // Quick pass/fail summary for the wiring wizard "Verify Connection" button
  JsonObject verdict = doc.createNestedObject("verdict");
  int issues = 0;
  JsonArray problems = verdict.createNestedArray("issues");

  // Check IR sensor
  if (cfg.sensor_pin > 0) {
    pinMode(cfg.sensor_pin, INPUT);
    if (digitalRead(cfg.sensor_pin) == LOW) {
      problems.add("IR sensor (GPIO " + String(cfg.sensor_pin) + ") reads LOW — beam blocked or disconnected");
      issues++;
    }
  }

  // Check memory health
  if (ESP.getFreeHeap() < 50000) {
    problems.add("Low heap memory: " + String(ESP.getFreeHeap()) + " bytes free");
    issues++;
  }

  // Check filesystem
  if (LittleFS.totalBytes() - LittleFS.usedBytes() < 100000) {
    problems.add("Low filesystem space: " + String(LittleFS.totalBytes() - LittleFS.usedBytes()) + " bytes free");
    issues++;
  }

  // Check WiFi signal
  if (WiFi.status() == WL_CONNECTED && WiFi.RSSI() < -80) {
    problems.add("Weak WiFi signal: " + String(WiFi.RSSI()) + " dBm");
    issues++;
  }

  // Check LiDAR if enabled
  if (cfg.lidar_enabled && getDistanceMM() == 0) {
    problems.add("LiDAR enabled but no reading — check RX/TX wiring (GPIO " +
                 String(cfg.lidar_rx_pin) + "/" + String(cfg.lidar_tx_pin) + ")");
    issues++;
  }

  verdict["issue_count"] = issues;
  verdict["status"] = (issues == 0) ? "ALL CLEAR" : "ISSUES DETECTED";

  String output;
  serializeJson(doc, output);
  server.send(200, "application/json", output);
}

// ============================================================================
// PEER DISCOVERY API — Brother's Six Protocol
// ============================================================================
static void handleApiPeers() {
  server.send(200, "application/json", getPeersJson());
}

static void handleApiPeersForget() {
  if (!requireAuth()) return;

  String body = server.arg("plain");
  if (body.length() > 0) {
    // Forget a specific peer by MAC
    StaticJsonDocument<128> doc;
    deserializeJson(doc, body);
    const char* macStr = doc["mac"] | "";
    uint8_t mac[6];
    if (parseMacString(macStr, mac)) {
      forgetPeer(mac);
      server.send(200, "application/json", "{\"status\":\"ok\",\"action\":\"forgot_one\"}");
    } else {
      server.send(400, "application/json", "{\"error\":\"Invalid MAC\"}");
    }
  } else {
    // Forget all peers
    forgetAllPeers();
    server.send(200, "application/json", "{\"status\":\"ok\",\"action\":\"forgot_all\"}");
  }
}

// ============================================================================
// FLEET MANAGEMENT API — WiFi sharing and remote commands
// ============================================================================

// POST /api/peers/share-wifi
// Body (optional): {"mac":"AA:BB:CC:DD:EE:FF"} — omit for broadcast to all
static void handleApiShareWifi() {
  if (!requireAuth()) return;

  // Only the finish gate should push WiFi creds (it's the hub)
  if (strcmp(cfg.role, "finish") != 0) {
    server.send(403, "application/json", "{\"error\":\"Only finish gate can share WiFi credentials\"}");
    return;
  }

  String body = server.arg("plain");
  if (body.length() > 0) {
    StaticJsonDocument<128> doc;
    DeserializationError err = deserializeJson(doc, body);
    if (err) {
      server.send(400, "application/json", "{\"error\":\"Invalid JSON\"}");
      return;
    }
    const char* macStr = doc["mac"] | "";
    if (strlen(macStr) > 0) {
      uint8_t mac[6];
      if (parseMacString(macStr, mac)) {
        sendWiFiConfig(mac);
        server.send(200, "application/json", "{\"ok\":true,\"sent\":1}");
      } else {
        server.send(400, "application/json", "{\"error\":\"Invalid MAC address\"}");
      }
      return;
    }
  }

  // No MAC specified — broadcast to all paired peers
  sendWiFiConfigAll();
  int pairedCount = 0;
  for (int i = 0; i < peerCount; i++) {
    if (peers[i].paired) pairedCount++;
  }
  char resp[64];
  snprintf(resp, sizeof(resp), "{\"ok\":true,\"sent\":%d}", pairedCount);
  server.send(200, "application/json", resp);
}

// POST /api/peers/command
// Body: {"mac":"AA:BB:CC:DD:EE:FF","cmd":"reboot","param":0}
static void handleApiPeerCommand() {
  if (!requireAuth()) return;

  // Only the finish gate should send remote commands
  if (strcmp(cfg.role, "finish") != 0) {
    server.send(403, "application/json", "{\"error\":\"Only finish gate can send remote commands\"}");
    return;
  }

  String body = server.arg("plain");
  if (body.length() == 0) {
    server.send(400, "application/json", "{\"error\":\"Empty body\"}");
    return;
  }

  StaticJsonDocument<256> doc;
  DeserializationError err = deserializeJson(doc, body);
  if (err) {
    server.send(400, "application/json", "{\"error\":\"Invalid JSON\"}");
    return;
  }

  const char* macStr = doc["mac"] | "";
  const char* cmdStr = doc["cmd"] | "";
  uint32_t param = doc["param"] | 0;

  if (strlen(macStr) == 0 || strlen(cmdStr) == 0) {
    server.send(400, "application/json", "{\"error\":\"Missing mac or cmd\"}");
    return;
  }

  uint8_t mac[6];
  if (!parseMacString(macStr, mac)) {
    server.send(400, "application/json", "{\"error\":\"Invalid MAC address\"}");
    return;
  }

  // Map command string to CMD_* constant
  uint8_t cmd = 0;
  if (strcmp(cmdStr, "reboot") == 0)          cmd = CMD_REBOOT;
  else if (strcmp(cmdStr, "identify") == 0)    cmd = CMD_IDENTIFY;
  else if (strcmp(cmdStr, "diag") == 0)        cmd = CMD_DIAG_REPORT;
  else if (strcmp(cmdStr, "wifi-reconnect") == 0) cmd = CMD_WIFI_RECONNECT;
  else {
    server.send(400, "application/json", "{\"error\":\"Unknown command. Use: reboot, identify, diag, wifi-reconnect\"}");
    return;
  }

  sendRemoteCmd(mac, cmd, param);
  server.send(200, "application/json", "{\"ok\":true}");
}

// ============================================================================
// GARAGE API - Persistent car storage on ESP32 filesystem
// POST validation: must be JSON array of car objects with valid types
// ============================================================================
static void handleApiGarage() {
  if (server.method() == HTTP_GET) {
    if (LittleFS.exists("/garage.json")) {
      File f = LittleFS.open("/garage.json", "r");
      String content = f.readString();
      f.close();
      server.send(200, "application/json", content);
    } else {
      server.send(200, "application/json", "[]");
    }
  }
  else if (server.method() == HTTP_POST) {
    if (!requireAuth()) return;
    String body = server.arg("plain");
    if (body.length() == 0) {
      server.send(400, "application/json", "{\"error\":\"Empty body\"}");
      return;
    }

    // Validate JSON structure
    DynamicJsonDocument doc(8192);
    DeserializationError err = deserializeJson(doc, body);
    if (err) {
      server.send(400, "application/json", "{\"error\":\"Invalid JSON\"}");
      return;
    }
    if (!doc.is<JsonArray>()) {
      server.send(400, "application/json", "{\"error\":\"Must be array\"}");
      return;
    }
    JsonArray arr = doc.as<JsonArray>();
    if (arr.size() > 50) {
      server.send(400, "application/json", "{\"error\":\"Max 50 cars\"}");
      return;
    }

    // Validate each car object
    for (JsonVariant item : arr) {
      if (!item.is<JsonObject>()) {
        server.send(400, "application/json", "{\"error\":\"Array items must be objects\"}");
        return;
      }
      JsonObject car = item.as<JsonObject>();
      // name must be string
      if (car.containsKey("name") && !car["name"].is<const char*>()) {
        server.send(400, "application/json", "{\"error\":\"name must be string\"}");
        return;
      }
      // weight must be numeric if present
      if (car.containsKey("weight") && !car["weight"].is<float>() && !car["weight"].is<int>()) {
        server.send(400, "application/json", "{\"error\":\"weight must be numeric\"}");
        return;
      }
      // Validate stats sub-object if present
      if (car.containsKey("stats") && car["stats"].is<JsonObject>()) {
        JsonObject stats = car["stats"].as<JsonObject>();
        // bestTime: must be null or numeric
        if (stats.containsKey("bestTime") && !stats["bestTime"].isNull()
            && !stats["bestTime"].is<float>() && !stats["bestTime"].is<int>()) {
          server.send(400, "application/json", "{\"error\":\"bestTime must be numeric or null\"}");
          return;
        }
        // bestSpeed: must be numeric if present
        if (stats.containsKey("bestSpeed") && !stats["bestSpeed"].isNull()
            && !stats["bestSpeed"].is<float>() && !stats["bestSpeed"].is<int>()) {
          server.send(400, "application/json", "{\"error\":\"bestSpeed must be numeric\"}");
          return;
        }
      }
    }

    // Valid — write to filesystem
    File f = LittleFS.open("/garage.json", "w");
    if (!f) {
      server.send(500, "application/json", "{\"error\":\"Failed to write garage\"}");
      return;
    }
    serializeJson(doc, f);
    f.close();
    server.send(200, "application/json", "{\"status\":\"ok\"}");
  }
}

// ============================================================================
// HISTORY API - Persistent race history on ESP32 filesystem
// POST validation: must be JSON array with valid numeric timing fields
// ============================================================================
static void handleApiHistory() {
  if (server.method() == HTTP_GET) {
    if (LittleFS.exists("/history.json")) {
      File f = LittleFS.open("/history.json", "r");
      String content = f.readString();
      f.close();
      server.send(200, "application/json", content);
    } else {
      server.send(200, "application/json", "[]");
    }
  }
  else if (server.method() == HTTP_POST) {
    if (!requireAuth()) return;
    String body = server.arg("plain");
    if (body.length() == 0) {
      server.send(400, "application/json", "{\"error\":\"Empty body\"}");
      return;
    }

    // Validate JSON structure
    DynamicJsonDocument doc(8192);
    DeserializationError err = deserializeJson(doc, body);
    if (err) {
      server.send(400, "application/json", "{\"error\":\"Invalid JSON\"}");
      return;
    }
    if (!doc.is<JsonArray>()) {
      server.send(400, "application/json", "{\"error\":\"Must be array\"}");
      return;
    }
    JsonArray arr = doc.as<JsonArray>();
    if (arr.size() > 100) {
      server.send(400, "application/json", "{\"error\":\"Max 100 entries\"}");
      return;
    }

    // Validate each history entry
    for (JsonVariant item : arr) {
      if (!item.is<JsonObject>()) {
        server.send(400, "application/json", "{\"error\":\"Array items must be objects\"}");
        return;
      }
      JsonObject entry = item.as<JsonObject>();
      // time must be numeric and sane
      if (entry.containsKey("time")) {
        if (!entry["time"].is<float>() && !entry["time"].is<int>()) {
          server.send(400, "application/json", "{\"error\":\"time must be numeric\"}");
          return;
        }
        float t = entry["time"].as<float>();
        if (t <= 0 || t > 60.0) {
          server.send(400, "application/json", "{\"error\":\"time out of range (0-60s)\"}");
          return;
        }
      }
      // car must be string
      if (entry.containsKey("car") && !entry["car"].is<const char*>()) {
        server.send(400, "application/json", "{\"error\":\"car must be string\"}");
        return;
      }
      // Numeric fields: reject strings
      const char* numFields[] = {"speed_mph", "speed_mps", "scale_mph", "momentum", "ke", "weight"};
      for (int i = 0; i < 6; i++) {
        if (entry.containsKey(numFields[i]) && !entry[numFields[i]].isNull()
            && !entry[numFields[i]].is<float>() && !entry[numFields[i]].is<int>()) {
          String errMsg = "{\"error\":\"" + String(numFields[i]) + " must be numeric\"}";
          server.send(400, "application/json", errMsg);
          return;
        }
      }
    }

    // Valid — write to filesystem
    File f = LittleFS.open("/history.json", "w");
    if (!f) {
      server.send(500, "application/json", "{\"error\":\"Failed to write history\"}");
      return;
    }
    serializeJson(doc, f);
    f.close();
    server.send(200, "application/json", "{\"status\":\"ok\"}");
  }
}

// ============================================================================
// AUDIO API - List sounds, test playback, upload WAV files
// ============================================================================
static void handleApiAudioList() {
  if (!cfg.audio_enabled) {
    server.send(200, "application/json", "{\"enabled\":false,\"files\":[]}");
    return;
  }
  String json = "{\"enabled\":true,\"playing\":" + String(isPlaying() ? "true" : "false") +
                ",\"volume\":" + String(cfg.audio_volume) +
                ",\"files\":" + getAudioFileList() + "}";
  server.send(200, "application/json", json);
}

static void handleApiAudioTest() {
  if (!cfg.audio_enabled) {
    server.send(400, "application/json", "{\"error\":\"Audio not enabled\"}");
    return;
  }
  String body = server.arg("plain");
  StaticJsonDocument<128> doc;
  deserializeJson(doc, body);
  const char* file = doc["file"] | "finish.wav";
  playSound(file);
  server.send(200, "application/json", "{\"status\":\"ok\",\"playing\":\"" + String(file) + "\"}");
}

static void handleApiAudioStop() {
  stopSound();
  server.send(200, "application/json", "{\"status\":\"ok\"}");
}

static void handleApiAudioVolume() {
  String body = server.arg("plain");
  StaticJsonDocument<64> doc;
  deserializeJson(doc, body);
  uint8_t vol = doc["volume"] | cfg.audio_volume;
  if (vol > 21) vol = 21;
  cfg.audio_volume = vol;
  setVolume(vol);
  saveConfig();
  server.send(200, "application/json", "{\"status\":\"ok\",\"volume\":" + String(vol) + "}");
}

// ============================================================================
// LIDAR SENSOR API - Live readout for config page
// ============================================================================
static void handleApiLidarStatus() {
  StaticJsonDocument<128> doc;
  doc["enabled"] = cfg.lidar_enabled;
  if (cfg.lidar_enabled) {
    LidarState ls = getLidarState();
    doc["state"] = (ls == LIDAR_NO_CAR) ? "empty" :
                   (ls == LIDAR_CAR_STAGED) ? "staged" : "launched";
    doc["distance_mm"] = getDistanceMM();
    doc["threshold_mm"] = cfg.lidar_threshold_mm;
  }
  String output;
  serializeJson(doc, output);
  server.send(200, "application/json", output);
}

// ============================================================================
// SERIAL LOG API - Web-viewable serial monitor
// ============================================================================
static void handleApiLog() {
  if (server.method() == HTTP_GET) {
    server.send(200, "text/plain", serialTee.getLog());
  }
  else if (server.method() == HTTP_DELETE) {
    if (!requireAuth()) return;
    serialTee.clear();
    server.send(200, "application/json", "{\"status\":\"ok\"}");
  }
}

// ============================================================================
// FILESYSTEM API - Browse, read, and write LittleFS files from the web
// ============================================================================
static void handleApiFiles() {
  String path = server.arg("path");
  if (path.length() == 0) path = "/";

  if (server.method() == HTTP_GET) {
    // If path ends with / or is a directory, list files
    // Otherwise, return file contents
    if (path == "/" || path.endsWith("/")) {
      // List directory
      File root = LittleFS.open(path.length() > 0 ? path : "/");
      if (!root || !root.isDirectory()) {
        // Not a directory — try listing root
        root = LittleFS.open("/");
      }

      StaticJsonDocument<2048> doc;
      JsonArray arr = doc.to<JsonArray>();
      File f = root.openNextFile();
      while (f) {
        JsonObject entry = arr.createNestedObject();
        entry["name"] = String(f.name());
        entry["size"] = f.size();
        entry["isDir"] = f.isDirectory();
        f = root.openNextFile();
      }
      String output;
      serializeJson(doc, output);
      server.send(200, "application/json", output);
    } else {
      // Read specific file
      if (!LittleFS.exists(path)) {
        server.send(404, "application/json", "{\"error\":\"File not found\"}");
        return;
      }
      File f = LittleFS.open(path, "r");
      String content = f.readString();
      f.close();
      // Return as JSON with metadata
      // Use DynamicJsonDocument for potentially large file contents
      DynamicJsonDocument doc(content.length() + 256);
      doc["path"] = path;
      doc["size"] = content.length();
      doc["content"] = content;
      String output;
      serializeJson(doc, output);
      server.send(200, "application/json", output);
    }
  }
  else if (server.method() == HTTP_POST) {
    if (!requireAuth()) return;
    // Write file contents
    if (path.length() == 0 || path == "/") {
      server.send(400, "application/json", "{\"error\":\"No path specified\"}");
      return;
    }
    String body = server.arg("plain");
    File f = LittleFS.open(path, "w");
    if (!f) {
      server.send(500, "application/json", "{\"error\":\"Failed to open file for writing\"}");
      return;
    }
    f.print(body);
    f.close();
    server.send(200, "application/json", "{\"status\":\"ok\",\"size\":" + String(body.length()) + "}");
  }
  else if (server.method() == HTTP_DELETE) {
    if (!requireAuth()) return;
    // Delete file
    if (path.length() == 0 || path == "/") {
      server.send(400, "application/json", "{\"error\":\"Cannot delete root\"}");
      return;
    }
    // Protect critical files
    if (path == CONFIG_FILE) {
      server.send(400, "application/json", "{\"error\":\"Use factory reset to delete config\"}");
      return;
    }
    if (LittleFS.remove(path)) {
      server.send(200, "application/json", "{\"status\":\"ok\"}");
    } else {
      server.send(404, "application/json", "{\"error\":\"File not found or delete failed\"}");
    }
  }
}

// ============================================================================
// NORMAL MODE ROUTES
// ============================================================================
// AUTH API — Two-tier authentication (Badge Reader / Internal Affairs)
// ============================================================================
static void handleApiAuthInfo() {
  // No auth required — client uses this to decide which gates to show
  String json = "{\"hasViewerPassword\":";
  json += (strlen(cfg.viewer_password) > 0) ? "true" : "false";
  json += ",\"hasAdminPassword\":";
  json += (strlen(cfg.ota_password) > 0) ? "true" : "false";
  json += "}";
  server.send(200, "application/json", json);
}

static void handleApiAuthCheck() {
  String body = server.arg("plain");
  if (body.length() == 0) {
    server.send(400, "application/json", "{\"error\":\"Empty body\"}");
    return;
  }

  StaticJsonDocument<256> doc;
  DeserializationError err = deserializeJson(doc, body);
  if (err) {
    server.send(400, "application/json", "{\"error\":\"Invalid JSON\"}");
    return;
  }

  const char* password = doc["password"] | "";
  const char* tier = doc["tier"] | "viewer";

  if (strcmp(tier, "admin") == 0) {
    // Admin tier: check OTA password
    if (strlen(cfg.ota_password) == 0 || strcmp(password, cfg.ota_password) == 0) {
      server.send(200, "application/json", "{\"ok\":true,\"tier\":\"admin\"}");
    } else {
      server.send(200, "application/json", "{\"ok\":false}");
    }
  } else {
    // Viewer tier: check viewer password (blank = always ok)
    if (strlen(cfg.viewer_password) == 0 || strcmp(password, cfg.viewer_password) == 0) {
      server.send(200, "application/json", "{\"ok\":true,\"tier\":\"viewer\"}");
    } else {
      server.send(200, "application/json", "{\"ok\":false}");
    }
  }
}

// ============================================================================
// FIRMWARE UPDATE ENDPOINTS
// ============================================================================

// GET /api/firmware/status — Current update status
static void handleFirmwareStatus() {
  StaticJsonDocument<256> doc;
  doc["updating"] = (bool)firmwareUpdateInProgress;
  doc["scheduled"] = (bool)firmwareUpdateScheduled;
  doc["message"] = firmwareUpdateStatus;
  String json;
  serializeJson(doc, json);
  server.send(200, "application/json", json);
}

// POST /api/firmware/update-from-url — Schedule GitHub download (primary flow)
static void handleFirmwareUpdateFromUrl() {
  if (!requireAuth()) return;

  if (firmwareUpdateScheduled || firmwareUpdateInProgress) {
    server.send(409, "application/json", "{\"error\":\"Firmware update already in progress\"}");
    return;
  }

  String body = server.arg("plain");
  if (body.length() == 0) {
    server.send(400, "application/json", "{\"error\":\"Empty body\"}");
    return;
  }

  StaticJsonDocument<512> doc;
  DeserializationError err = deserializeJson(doc, body);
  if (err) {
    server.send(400, "application/json", "{\"error\":\"Invalid JSON\"}");
    return;
  }

  const char* url = doc["url"] | "";
  const char* md5 = doc["md5"] | "";

  if (strlen(url) == 0) {
    server.send(400, "application/json", "{\"error\":\"Missing url field\"}");
    return;
  }

  // URL allowlist — closed circuit: only GitHub domains allowed
  if (strncmp(url, GITHUB_ASSET_PREFIX_1, strlen(GITHUB_ASSET_PREFIX_1)) != 0 &&
      strncmp(url, GITHUB_ASSET_PREFIX_2, strlen(GITHUB_ASSET_PREFIX_2)) != 0) {
    LOG.printf("[FW-UPDATE] Rejected non-GitHub URL: %.40s...\n", url);
    server.send(403, "application/json", "{\"error\":\"URL not allowed. Only GitHub release assets accepted.\"}");
    return;
  }

  // Validate MD5 format if provided (must be exactly 32 hex chars)
  if (strlen(md5) > 0 && strlen(md5) != 32) {
    server.send(400, "application/json", "{\"error\":\"Invalid MD5 format (expected 32 hex chars)\"}");
    return;
  }

  // Store for deferred processing in loop()
  strncpy(firmwareUpdateUrl, url, sizeof(firmwareUpdateUrl) - 1);
  firmwareUpdateUrl[sizeof(firmwareUpdateUrl) - 1] = '\0';
  strncpy(firmwareExpectedMd5, md5, sizeof(firmwareExpectedMd5) - 1);
  firmwareExpectedMd5[sizeof(firmwareExpectedMd5) - 1] = '\0';
  snprintf(firmwareUpdateStatus, sizeof(firmwareUpdateStatus), "Scheduled — download will begin shortly");
  firmwareUpdateScheduled = true;

  LOG.printf("[FW-UPDATE] Scheduled download from GitHub\n");
  if (strlen(md5) > 0) {
    LOG.printf("[FW-UPDATE] Expected MD5: %s\n", firmwareExpectedMd5);
  }

  // Respond BEFORE the download starts (download happens in loop via processFirmwareUpdate)
  server.send(200, "application/json", "{\"ok\":true,\"message\":\"Firmware download scheduled. Device will reboot when complete.\"}");
}

// POST /api/firmware/upload — Manual .bin upload (fallback)
static bool _fwUploadStarted = false;
static bool _fwUploadError = false;

static void handleFirmwareUpload() {
  HTTPUpload& upload = server.upload();

  if (upload.status == UPLOAD_FILE_START) {
    LOG.printf("[FW-UPDATE] Manual upload started: %s\n", upload.filename.c_str());
    _fwUploadStarted = true;
    _fwUploadError = false;
    firmwareUpdateInProgress = true;
    snprintf(firmwareUpdateStatus, sizeof(firmwareUpdateStatus), "Receiving upload: %s", upload.filename.c_str());

    if (!Update.begin(MAX_FIRMWARE_SIZE)) {
      LOG.printf("[FW-UPDATE] Update.begin() failed: %s\n", Update.errorString());
      _fwUploadError = true;
    }
  } else if (upload.status == UPLOAD_FILE_WRITE) {
    if (!_fwUploadError) {
      if (Update.write(upload.buf, upload.currentSize) != upload.currentSize) {
        LOG.printf("[FW-UPDATE] Update.write() failed: %s\n", Update.errorString());
        _fwUploadError = true;
      }
    }
  } else if (upload.status == UPLOAD_FILE_END) {
    if (!_fwUploadError && Update.end(true)) {
      LOG.printf("[FW-UPDATE] Upload complete, %u bytes written\n", upload.totalSize);
      snprintf(firmwareUpdateStatus, sizeof(firmwareUpdateStatus), "Upload complete — rebooting");
    } else {
      LOG.printf("[FW-UPDATE] Upload failed: %s\n", Update.errorString());
      _fwUploadError = true;
      snprintf(firmwareUpdateStatus, sizeof(firmwareUpdateStatus), "Upload failed: %s", Update.errorString());
    }
  }
}

static void handleFirmwareUploadComplete() {
  if (!requireAuth()) return;

  firmwareUpdateInProgress = false;

  if (_fwUploadError || Update.hasError()) {
    _fwUploadStarted = false;
    server.send(500, "application/json", "{\"error\":\"Firmware upload failed. See serial console for details.\"}");
    return;
  }

  server.send(200, "application/json", "{\"ok\":true,\"message\":\"Firmware uploaded successfully. Rebooting...\"}");
  delay(500);
  ESP.restart();
}

// Called from loop() — executes the scheduled firmware download
void processFirmwareUpdate() {
  if (!firmwareUpdateScheduled) return;
  firmwareUpdateScheduled = false;
  firmwareUpdateInProgress = true;

  LOG.printf("[FW-UPDATE] Starting download from: %s\n", firmwareUpdateUrl);
  snprintf(firmwareUpdateStatus, sizeof(firmwareUpdateStatus), "Downloading firmware...");

  NetworkClientSecure secClient;
  secClient.setCACert(github_root_ca_pem);
  secClient.setTimeout(30);  // 30 second TLS handshake timeout

  // Configure HTTPUpdate
  httpUpdate.setFollowRedirects(HTTPC_FORCE_FOLLOW_REDIRECTS);
  httpUpdate.rebootOnUpdate(true);

  // Set MD5 verification if provided
  if (strlen(firmwareExpectedMd5) > 0) {
    LOG.printf("[FW-UPDATE] MD5 verification enabled: %s\n", firmwareExpectedMd5);
  }

  // Progress callbacks
  httpUpdate.onStart([]() {
    LOG.println("[FW-UPDATE] Download started — writing to inactive partition");
  });
  httpUpdate.onProgress([](int cur, int total) {
    static int lastPct = -1;
    int pct = (total > 0) ? (cur * 100 / total) : 0;
    if (pct != lastPct && pct % 10 == 0) {
      LOG.printf("[FW-UPDATE] Progress: %d%% (%d / %d bytes)\n", pct, cur, total);
      snprintf(firmwareUpdateStatus, sizeof(firmwareUpdateStatus), "Downloading: %d%%", pct);
      lastPct = pct;
    }
  });
  httpUpdate.onEnd([]() {
    LOG.println("[FW-UPDATE] Download complete — verifying and rebooting");
    snprintf(firmwareUpdateStatus, sizeof(firmwareUpdateStatus), "Download complete — rebooting");
  });
  httpUpdate.onError([](int err) {
    LOG.printf("[FW-UPDATE] Error (%d): %s\n", err, httpUpdate.getLastErrorString().c_str());
    snprintf(firmwareUpdateStatus, sizeof(firmwareUpdateStatus), "Error: %s", httpUpdate.getLastErrorString().c_str());
  });

  // Attempt #1: with proper TLS cert verification
  t_httpUpdate_return ret;
  if (strlen(firmwareExpectedMd5) > 0) {
    httpUpdate.setMD5sum(firmwareExpectedMd5);
  }
  ret = httpUpdate.update(secClient, firmwareUpdateUrl);

  // If update() returns, it failed (success = reboot, never returns)
  if (ret == HTTP_UPDATE_FAILED) {
    int errCode = httpUpdate.getLastError();
    String errStr = httpUpdate.getLastErrorString();
    LOG.printf("[FW-UPDATE] Attempt 1 failed (code %d): %s\n", errCode, errStr.c_str());

    // Check if it's a TLS/connection error — retry with insecure fallback
    // Error codes: -1 = connection failed, -11 = SSL error
    if (errCode == -1 || errCode == -11 || errCode == HTTP_UPDATE_FAILED) {
      LOG.println("[FW-UPDATE] TLS verification may have failed — retrying with insecure fallback");
      LOG.println("[FW-UPDATE] WARNING: Certificate verification disabled for this attempt");
      snprintf(firmwareUpdateStatus, sizeof(firmwareUpdateStatus), "Retrying without cert verification...");

      secClient.setInsecure();
      if (strlen(firmwareExpectedMd5) > 0) {
        httpUpdate.setMD5sum(firmwareExpectedMd5);
      }
      ret = httpUpdate.update(secClient, firmwareUpdateUrl);

      if (ret == HTTP_UPDATE_FAILED) {
        LOG.printf("[FW-UPDATE] Attempt 2 also failed: %s\n", httpUpdate.getLastErrorString().c_str());
      }
    }
  }

  // If we're still here, both attempts failed
  firmwareUpdateInProgress = false;
  snprintf(firmwareUpdateStatus, sizeof(firmwareUpdateStatus), "Update failed: %s",
           httpUpdate.getLastErrorString().c_str());
  LOG.printf("[FW-UPDATE] All attempts failed. Device stays on current firmware.\n");

  // Clear stored URL for safety
  firmwareUpdateUrl[0] = '\0';
  firmwareExpectedMd5[0] = '\0';
}

// ============================================================================
void initWebServer() {
  // Collect X-API-Key header for authentication on protected endpoints
  const char* headerKeys[] = {"X-API-Key"};
  server.collectHeaders(headerKeys, 1);

  // Main page: serve role-appropriate page
  // v2.5.0: Prefer LittleFS files, fall back to PROGMEM if missing
  // Finish gate gets the full dashboard (garage, history, physics)
  // Start gate gets a lightweight status page (no data recording)
  server.on("/", HTTP_GET, []() {
    server.sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
    if (strcmp(cfg.role, "start") == 0) {
      if (LittleFS.exists("/start_status.html")) {
        serveFile("/start_status.html", "text/html");
      } else {
        server.send_P(200, "text/html", START_STATUS_HTML);
      }
    } else if (strcmp(cfg.role, "speedtrap") == 0) {
      if (LittleFS.exists("/speedtrap_status.html")) {
        serveFile("/speedtrap_status.html", "text/html");
      } else {
        server.send_P(200, "text/html", SPEEDTRAP_STATUS_HTML);
      }
    } else {
      if (LittleFS.exists("/dashboard.html")) {
        serveFile("/dashboard.html", "text/html");
      } else {
        server.send_P(200, "text/html", INDEX_HTML);
      }
    }
  });

  // Dashboard alias (direct URL access)
  server.on("/dashboard.html", HTTP_GET, []() {
    server.sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
    if (LittleFS.exists("/dashboard.html")) {
      serveFile("/dashboard.html", "text/html");
    } else {
      server.send_P(200, "text/html", INDEX_HTML);
    }
  });

  // Chart.js library: prefer LittleFS, fall back to PROGMEM
  server.on("/chart.min.js", HTTP_GET, []() {
    server.sendHeader("Cache-Control", "public, max-age=86400"); // Cache 24h
    if (LittleFS.exists("/chart.min.js")) {
      serveFile("/chart.min.js", "application/javascript");
    } else {
      server.send_P(200, "application/javascript", CHARTJS_MIN);
    }
  });

  // Config page: prefer LittleFS system.html, fall back to PROGMEM
  server.on("/config", HTTP_GET, []() {
    server.sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
    if (LittleFS.exists("/system.html")) {
      serveFile("/system.html", "text/html");
    } else {
      server.send_P(200, "text/html", CONFIG_HTML);
    }
  });

  // Auth API
  server.on("/api/auth/info", HTTP_GET, handleApiAuthInfo);
  server.on("/api/auth/check", HTTP_POST, handleApiAuthCheck);

  // Config API
  server.on("/api/config", handleApiConfig);
  server.on("/api/scan", HTTP_GET, handleApiScan);
  server.on("/api/mac", HTTP_GET, handleApiMac);
  server.on("/api/backup", HTTP_GET, handleApiBackup);
  server.on("/api/restore", HTTP_POST, handleApiRestore);
  server.on("/api/system/backup", HTTP_GET, handleApiSystemBackup);
  server.on("/api/system/restore", HTTP_POST, handleApiSystemRestore);
  server.on("/api/reset", HTTP_POST, handleApiReset);
  server.on("/api/info", HTTP_GET, handleApiInfo);
  server.on("/api/wifi-status", HTTP_GET, handleApiWifiStatus);
  server.on("/api/version", HTTP_GET, handleApiVersion);
  server.on("/api/diagnostics", HTTP_GET, handleApiDiagnostics);
  server.on("/api/peers", HTTP_GET, handleApiPeers);
  server.on("/api/peers/forget", HTTP_POST, handleApiPeersForget);
  server.on("/api/peers/share-wifi", HTTP_POST, handleApiShareWifi);
  server.on("/api/peers/command", HTTP_POST, handleApiPeerCommand);
  server.on("/api/garage", HTTP_GET, handleApiGarage);
  server.on("/api/garage", HTTP_POST, handleApiGarage);
  server.on("/api/history", HTTP_GET, handleApiHistory);
  server.on("/api/history", HTTP_POST, handleApiHistory);

  // Audio API
  server.on("/api/audio/list", HTTP_GET, handleApiAudioList);
  server.on("/api/audio/test", HTTP_POST, handleApiAudioTest);
  server.on("/api/audio/stop", HTTP_POST, handleApiAudioStop);
  server.on("/api/audio/volume", HTTP_POST, handleApiAudioVolume);

  // LiDAR sensor API
  server.on("/api/lidar/status", HTTP_GET, handleApiLidarStatus);

  // Serial log & filesystem
  server.on("/api/log", HTTP_GET, handleApiLog);
  server.on("/api/log", HTTP_DELETE, handleApiLog);
  server.on("/api/files", HTTP_GET, handleApiFiles);
  server.on("/api/files", HTTP_POST, handleApiFiles);
  server.on("/api/files", HTTP_DELETE, handleApiFiles);

  // Firmware update endpoints
  server.on("/api/firmware/status", HTTP_GET, handleFirmwareStatus);
  server.on("/api/firmware/update-from-url", HTTP_POST, handleFirmwareUpdateFromUrl);
  server.on("/api/firmware/upload", HTTP_POST, handleFirmwareUploadComplete, handleFirmwareUpload);

  // Console page: prefer LittleFS, fall back to PROGMEM
  server.on("/console", HTTP_GET, []() {
    server.sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
    if (LittleFS.exists("/console.html")) {
      serveFile("/console.html", "text/html");
    } else {
      server.send_P(200, "text/html", CONSOLE_HTML);
    }
  });

  // WLED proxy endpoints (for config page to fetch WLED data without CORS issues)
  server.on("/api/wled/info", HTTP_GET, []() {
    if (strlen(cfg.wled_host) == 0) {
      server.send(400, "application/json", "{\"error\":\"WLED not configured\"}");
      return;
    }
    HTTPClient http;
    http.begin("http://" + String(cfg.wled_host) + "/json/info");
    http.setTimeout(1000); // 1s for user-facing config page
    int code = http.GET();
    if (code == 200) {
      server.send(200, "application/json", http.getString());
    } else {
      server.send(502, "application/json", "{\"error\":\"WLED unreachable\"}");
    }
    http.end();
  });

  server.on("/api/wled/effects", HTTP_GET, []() {
    if (strlen(cfg.wled_host) == 0) {
      server.send(400, "application/json", "{\"error\":\"WLED not configured\"}");
      return;
    }
    HTTPClient http;
    http.begin("http://" + String(cfg.wled_host) + "/json/effects");
    http.setTimeout(1000); // 1s for user-facing config page
    int code = http.GET();
    if (code == 200) {
      server.send(200, "application/json", http.getString());
    } else {
      server.send(502, "application/json", "{\"error\":\"WLED unreachable\"}");
    }
    http.end();
  });

  // --- Telemetry (XIAO ride-along IMU data) ---
  server.on("/api/telemetry", HTTP_GET, []() {
    if (!requireAuth()) return;
    if (LittleFS.exists("/telemetry_latest.csv")) {
      File f = LittleFS.open("/telemetry_latest.csv", "r");
      server.streamFile(f, "text/csv");
      f.close();
    } else {
      server.send(404, "application/json", "{\"error\":\"No telemetry data\"}");
    }
  });

  server.on("/api/telemetry/info", HTTP_GET, []() {
    if (!requireAuth()) return;
    server.send(200, "application/json", getTelemetryInfoJson());
  });

  // Static CSS/JS assets from LittleFS with cache headers
  server.on("/style.css", HTTP_GET, []() {
    server.sendHeader("Cache-Control", "public, max-age=3600"); // Cache 1h
    serveFile("/style.css", "text/css");
  });

  server.on("/main.js", HTTP_GET, []() {
    server.sendHeader("Cache-Control", "public, max-age=3600"); // Cache 1h
    serveFile("/main.js", "application/javascript");
  });

  // Evidence Log page (new v2.5.0 page)
  server.on("/history.html", HTTP_GET, []() {
    server.sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
    serveFile("/history.html", "text/html");
  });

  // Catch-all: try to serve from LittleFS
  server.onNotFound([]() {
    String path = server.uri();
    if (LittleFS.exists(path)) {
      serveFile(path, getContentType(path));
    } else {
      server.send(404, "text/plain", "Not found");
    }
  });
}

void startWebServer() {
  server.begin();
  webSocket.begin();
  webSocket.onEvent(webSocketEvent);
  LOG.println("[WEB] HTTP server started on port 80");
  LOG.println("[WEB] WebSocket server started on port 81");
}

// ============================================================================
// SETUP MODE SERVER (captive portal)
// ============================================================================
void initSetupServer() {
  // Collect X-API-Key header for authentication
  const char* headerKeys[] = {"X-API-Key"};
  server.collectHeaders(headerKeys, 1);

  // In setup mode, serve config page from PROGMEM at root
  server.on("/", HTTP_GET, []() {
    server.sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
    server.send_P(200, "text/html", CONFIG_HTML);
  });

  // Same config API endpoints
  server.on("/api/config", handleApiConfig);
  server.on("/api/scan", HTTP_GET, handleApiScan);
  server.on("/api/mac", HTTP_GET, handleApiMac);
  server.on("/api/info", HTTP_GET, handleApiInfo);
  server.on("/api/wifi-status", HTTP_GET, handleApiWifiStatus);
  server.on("/api/diagnostics", HTTP_GET, handleApiDiagnostics);

  // ---- Captive portal detection handlers ----
  // Explicit handlers for OS-level probe URLs ensure reliable detection.
  // Using full URL in Location header (not relative "/") and no-cache headers
  // prevents CNA caching issues that cause "forget network and try again."

  // Apple (iOS/macOS) probe
  server.on("/hotspot-detect.html", HTTP_GET, []() {
    server.sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
    server.sendHeader("Location", "http://192.168.4.1/", true);
    server.send(302, "text/html", "");
  });

  // Android probe
  server.on("/generate_204", HTTP_GET, []() {
    server.sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
    server.sendHeader("Location", "http://192.168.4.1/", true);
    server.send(302, "text/html", "");
  });

  // Windows probe
  server.on("/connecttest.txt", HTTP_GET, []() {
    server.sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
    server.sendHeader("Location", "http://192.168.4.1/", true);
    server.send(302, "text/html", "");
  });

  // Additional known probe paths
  server.on("/redirect", HTTP_GET, []() {
    server.sendHeader("Location", "http://192.168.4.1/", true);
    server.send(302, "text/html", "");
  });
  server.on("/success.txt", HTTP_GET, []() {
    server.send(200, "text/plain", "");  // Empty body != expected → triggers portal
  });
  server.on("/fwlink", HTTP_GET, []() {
    server.sendHeader("Location", "http://192.168.4.1/", true);
    server.send(302, "text/html", "");
  });

  // Catch-all: redirect any other request to the config page
  server.onNotFound([]() {
    String path = server.uri();
    if (LittleFS.exists(path)) {
      serveFile(path, getContentType(path));
    } else {
      server.sendHeader("Cache-Control", "no-cache, no-store, must-revalidate");
      server.sendHeader("Location", "http://192.168.4.1/", true);
      server.send(302, "text/html", "");
    }
  });

  server.begin();
  LOG.println("[WEB] Setup mode server started");
}