feat: A web editor for settings (#667)

## Summary

This is an updated version of @itsthisjustin's #346 that builds on
current master and also deduplicates the settings list so we don't have
two copies of the settings. In the Web UI, it should organize the
settings a little closer to what you see on device.

## Additional Context

I tested this live on device and it seems to play nicely for me. It's
re-based on master since master's settings stuff has moved somewhat
since the original PR and addresses the sole review comment #346 - it
also means that I don't need to manually key in the URL for my OPDS
server. :)

---

### AI Usage

My changes were implemented with Claude Opus 4.5 and Claude Code 2.1.25.
I don't know if @itsthisjustin's original work used AI assistance.

Co-authored-by: Dave Allie <dave@daveallie.com>

src/network/CrossPointWebServer.cpp

@@ -9,8 +9,11 @@
 
 #include <algorithm>
 
+#include "CrossPointSettings.h"
+#include "SettingsList.h"
 #include "html/FilesPageHtml.generated.h"
 #include "html/HomePageHtml.generated.h"
+#include "html/SettingsPageHtml.generated.h"
 #include "util/StringUtils.h"
 
 namespace {
@@ -148,6 +151,11 @@ void CrossPointWebServer::begin() {
   // Delete file/folder endpoint
   server->on("/delete", HTTP_POST, [this] { handleDelete(); });
 
+  // Settings endpoints
+  server->on("/settings", HTTP_GET, [this] { handleSettingsPage(); });
+  server->on("/api/settings", HTTP_GET, [this] { handleGetSettings(); });
+  server->on("/api/settings", HTTP_POST, [this] { handlePostSettings(); });
+
   server->onNotFound([this] { handleNotFound(); });
   Serial.printf("[%lu] [WEB] [MEM] Free heap after route setup: %d bytes\n", millis(), ESP.getFreeHeap());
 
@@ -983,6 +991,168 @@ void CrossPointWebServer::handleDelete() const {
   }
 }
 
+void CrossPointWebServer::handleSettingsPage() const {
+  server->send(200, "text/html", SettingsPageHtml);
+  Serial.printf("[%lu] [WEB] Served settings page\n", millis());
+}
+
+void CrossPointWebServer::handleGetSettings() const {
+  auto settings = getSettingsList();
+
+  server->setContentLength(CONTENT_LENGTH_UNKNOWN);
+  server->send(200, "application/json", "");
+  server->sendContent("[");
+
+  char output[512];
+  constexpr size_t outputSize = sizeof(output);
+  bool seenFirst = false;
+  JsonDocument doc;
+
+  for (const auto& s : settings) {
+    if (!s.key) continue;  // Skip ACTION-only entries
+
+    doc.clear();
+    doc["key"] = s.key;
+    doc["name"] = s.name;
+    doc["category"] = s.category;
+
+    switch (s.type) {
+      case SettingType::TOGGLE: {
+        doc["type"] = "toggle";
+        if (s.valuePtr) {
+          doc["value"] = static_cast<int>(SETTINGS.*(s.valuePtr));
+        }
+        break;
+      }
+      case SettingType::ENUM: {
+        doc["type"] = "enum";
+        if (s.valuePtr) {
+          doc["value"] = static_cast<int>(SETTINGS.*(s.valuePtr));
+        } else if (s.valueGetter) {
+          doc["value"] = static_cast<int>(s.valueGetter());
+        }
+        JsonArray options = doc["options"].to<JsonArray>();
+        for (const auto& opt : s.enumValues) {
+          options.add(opt);
+        }
+        break;
+      }
+      case SettingType::VALUE: {
+        doc["type"] = "value";
+        if (s.valuePtr) {
+          doc["value"] = static_cast<int>(SETTINGS.*(s.valuePtr));
+        }
+        doc["min"] = s.valueRange.min;
+        doc["max"] = s.valueRange.max;
+        doc["step"] = s.valueRange.step;
+        break;
+      }
+      case SettingType::STRING: {
+        doc["type"] = "string";
+        if (s.stringGetter) {
+          doc["value"] = s.stringGetter();
+        } else if (s.stringPtr) {
+          doc["value"] = s.stringPtr;
+        }
+        break;
+      }
+      default:
+        continue;
+    }
+
+    const size_t written = serializeJson(doc, output, outputSize);
+    if (written >= outputSize) {
+      Serial.printf("[%lu] [WEB] Skipping oversized setting JSON for: %s\n", millis(), s.key);
+      continue;
+    }
+
+    if (seenFirst) {
+      server->sendContent(",");
+    } else {
+      seenFirst = true;
+    }
+    server->sendContent(output);
+  }
+
+  server->sendContent("]");
+  server->sendContent("");
+  Serial.printf("[%lu] [WEB] Served settings API\n", millis());
+}
+
+void CrossPointWebServer::handlePostSettings() {
+  if (!server->hasArg("plain")) {
+    server->send(400, "text/plain", "Missing JSON body");
+    return;
+  }
+
+  const String body = server->arg("plain");
+  JsonDocument doc;
+  const DeserializationError err = deserializeJson(doc, body);
+  if (err) {
+    server->send(400, "text/plain", String("Invalid JSON: ") + err.c_str());
+    return;
+  }
+
+  auto settings = getSettingsList();
+  int applied = 0;
+
+  for (auto& s : settings) {
+    if (!s.key) continue;
+    if (!doc[s.key].is<JsonVariant>()) continue;
+
+    switch (s.type) {
+      case SettingType::TOGGLE: {
+        const int val = doc[s.key].as<int>() ? 1 : 0;
+        if (s.valuePtr) {
+          SETTINGS.*(s.valuePtr) = val;
+        }
+        applied++;
+        break;
+      }
+      case SettingType::ENUM: {
+        const int val = doc[s.key].as<int>();
+        if (val >= 0 && val < static_cast<int>(s.enumValues.size())) {
+          if (s.valuePtr) {
+            SETTINGS.*(s.valuePtr) = static_cast<uint8_t>(val);
+          } else if (s.valueSetter) {
+            s.valueSetter(static_cast<uint8_t>(val));
+          }
+          applied++;
+        }
+        break;
+      }
+      case SettingType::VALUE: {
+        const int val = doc[s.key].as<int>();
+        if (val >= s.valueRange.min && val <= s.valueRange.max) {
+          if (s.valuePtr) {
+            SETTINGS.*(s.valuePtr) = static_cast<uint8_t>(val);
+          }
+          applied++;
+        }
+        break;
+      }
+      case SettingType::STRING: {
+        const std::string val = doc[s.key].as<std::string>();
+        if (s.stringSetter) {
+          s.stringSetter(val);
+        } else if (s.stringPtr && s.stringMaxLen > 0) {
+          strncpy(s.stringPtr, val.c_str(), s.stringMaxLen - 1);
+          s.stringPtr[s.stringMaxLen - 1] = '\0';
+        }
+        applied++;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  SETTINGS.saveToFile();
+
+  Serial.printf("[%lu] [WEB] Applied %d setting(s)\n", millis(), applied);
+  server->send(200, "text/plain", String("Applied ") + String(applied) + " setting(s)");
+}
+
 // WebSocket callback trampoline
 void CrossPointWebServer::wsEventCallback(uint8_t num, WStype_t type, uint8_t* payload, size_t length) {
   if (wsInstance) {

src/network/CrossPointWebServer.h

@@ -100,4 +100,9 @@ class CrossPointWebServer {
   void handleRename() const;
   void handleMove() const;
   void handleDelete() const;
+
+  // Settings handlers
+  void handleSettingsPage() const;
+  void handleGetSettings() const;
+  void handlePostSettings();
 };

src/network/html/FilesPage.html

@@ -628,6 +628,7 @@
 <div class="nav-links">
   <a href="/">Home</a>
   <a href="/files">File Manager</a>
+  <a href="/settings">Settings</a>
 </div>
 
 <div class="page-header">

src/network/html/HomePage.html

@@ -77,6 +77,7 @@
     <div class="nav-links">
       <a href="/">Home</a>
       <a href="/files">File Manager</a>
+      <a href="/settings">Settings</a>
     </div>
 
     <div class="card">

src/network/html/SettingsPage.html

@@ -0,0 +1,414 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>CrossPoint Reader - Settings</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+        Oxygen, Ubuntu, sans-serif;
+      max-width: 800px;
+      margin: 0 auto;
+      padding: 20px;
+      background-color: #f5f5f5;
+      color: #333;
+    }
+    h1 {
+      color: #2c3e50;
+      border-bottom: 2px solid #3498db;
+      padding-bottom: 10px;
+    }
+    h2 {
+      color: #34495e;
+      margin-top: 0;
+    }
+    .card {
+      background: white;
+      border-radius: 8px;
+      padding: 20px;
+      margin: 15px 0;
+      box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+    }
+    .nav-links {
+      margin: 20px 0;
+    }
+    .nav-links a {
+      display: inline-block;
+      padding: 10px 20px;
+      background-color: #3498db;
+      color: white;
+      text-decoration: none;
+      border-radius: 4px;
+      margin-right: 10px;
+    }
+    .nav-links a:hover {
+      background-color: #2980b9;
+    }
+    .setting-row {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      padding: 10px 0;
+      border-bottom: 1px solid #eee;
+    }
+    .setting-row:last-child {
+      border-bottom: none;
+    }
+    .setting-name {
+      font-weight: 500;
+      color: #2c3e50;
+      flex: 1;
+      min-width: 0;
+      padding-right: 12px;
+    }
+    .setting-control {
+      flex-shrink: 0;
+    }
+    .setting-control select,
+    .setting-control input[type="number"],
+    .setting-control input[type="text"],
+    .setting-control input[type="password"] {
+      padding: 6px 10px;
+      border: 1px solid #ddd;
+      border-radius: 4px;
+      font-size: 0.95em;
+      background: white;
+    }
+    .setting-control select {
+      min-width: 160px;
+    }
+    .setting-control input[type="text"],
+    .setting-control input[type="password"] {
+      width: 220px;
+    }
+    .setting-control input[type="number"] {
+      width: 80px;
+    }
+    /* Toggle switch */
+    .toggle-switch {
+      display: inline-block;
+      position: relative;
+      width: 48px;
+      height: 26px;
+    }
+    .toggle-switch input {
+      opacity: 0;
+      width: 0;
+      height: 0;
+    }
+    .toggle-slider {
+      position: absolute;
+      cursor: pointer;
+      top: 0; left: 0; right: 0; bottom: 0;
+      background-color: #ccc;
+      border-radius: 26px;
+      transition: 0.3s;
+    }
+    .toggle-slider:before {
+      position: absolute;
+      content: "";
+      height: 20px;
+      width: 20px;
+      left: 3px;
+      bottom: 3px;
+      background-color: white;
+      border-radius: 50%;
+      transition: 0.3s;
+    }
+    .toggle-switch input:checked + .toggle-slider {
+      background-color: #27ae60;
+    }
+    .toggle-switch input:checked + .toggle-slider:before {
+      transform: translateX(22px);
+    }
+    .save-container {
+      text-align: center;
+      margin: 20px 0;
+    }
+    .save-btn {
+      background-color: #27ae60;
+      color: white;
+      padding: 12px 40px;
+      border: none;
+      border-radius: 4px;
+      cursor: pointer;
+      font-size: 1.1em;
+      font-weight: 600;
+    }
+    .save-btn:hover {
+      background-color: #219a52;
+    }
+    .save-btn:disabled {
+      background-color: #95a5a6;
+      cursor: not-allowed;
+    }
+    .message {
+      padding: 12px;
+      border-radius: 4px;
+      margin: 15px 0;
+      text-align: center;
+      display: none;
+    }
+    .message.success {
+      background-color: #d4edda;
+      color: #155724;
+      border: 1px solid #c3e6cb;
+    }
+    .message.error {
+      background-color: #f8d7da;
+      color: #721c24;
+      border: 1px solid #f5c6cb;
+    }
+    .loader-container {
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      margin: 20px 0;
+    }
+    .loader {
+      width: 48px;
+      height: 48px;
+      border: 5px solid #AAA;
+      border-bottom-color: transparent;
+      border-radius: 50%;
+      display: inline-block;
+      box-sizing: border-box;
+      animation: rotation 1s linear infinite;
+    }
+    @keyframes rotation {
+      from { transform: rotate(0deg); }
+      to { transform: rotate(360deg); }
+    }
+    @media (max-width: 600px) {
+      body {
+        padding: 10px;
+        font-size: 14px;
+      }
+      .card {
+        padding: 12px;
+        margin: 10px 0;
+      }
+      h1 {
+        font-size: 1.3em;
+      }
+      .nav-links a {
+        padding: 8px 12px;
+        margin-right: 6px;
+        font-size: 0.9em;
+      }
+      .setting-row {
+        flex-wrap: wrap;
+        gap: 6px;
+      }
+      .setting-control select,
+      .setting-control input[type="text"],
+      .setting-control input[type="password"] {
+        min-width: 0;
+        width: 100%;
+      }
+    }
+  </style>
+</head>
+<body>
+  <h1>⚙️ Settings</h1>
+
+  <div class="nav-links">
+    <a href="/">Home</a>
+    <a href="/files">File Manager</a>
+    <a href="/settings">Settings</a>
+  </div>
+
+  <div id="message" class="message"></div>
+
+  <div id="settings-container">
+    <div class="loader-container">
+      <span class="loader"></span>
+    </div>
+  </div>
+
+  <div class="save-container" id="save-container" style="display:none;">
+    <button class="save-btn" id="saveBtn" onclick="saveSettings()">Save Settings</button>
+  </div>
+
+  <div class="card">
+    <p style="text-align: center; color: #95a5a6; margin: 0;">
+      CrossPoint E-Reader • Open Source
+    </p>
+  </div>
+
+<script>
+  let allSettings = [];
+  let originalValues = {};
+
+  function escapeHtml(unsafe) {
+    return unsafe
+      .replaceAll("&", "&amp;")
+      .replaceAll("<", "&lt;")
+      .replaceAll(">", "&gt;")
+      .replaceAll('"', "&quot;")
+      .replaceAll("'", "&#039;");
+  }
+
+  function showMessage(text, isError) {
+    const msg = document.getElementById('message');
+    msg.textContent = text;
+    msg.className = 'message ' + (isError ? 'error' : 'success');
+    msg.style.display = 'block';
+    setTimeout(function() { msg.style.display = 'none'; }, 4000);
+  }
+
+  function renderControl(setting) {
+    const id = 'setting-' + setting.key;
+
+    if (setting.type === 'toggle') {
+      const checked = setting.value ? 'checked' : '';
+      return '<label class="toggle-switch">' +
+        '<input type="checkbox" id="' + id + '" ' + checked + ' onchange="markChanged()">' +
+        '<span class="toggle-slider"></span></label>';
+    }
+
+    if (setting.type === 'enum') {
+      let html = '<select id="' + id + '" onchange="markChanged()">';
+      setting.options.forEach(function(opt, idx) {
+        const selected = idx === setting.value ? ' selected' : '';
+        html += '<option value="' + idx + '"' + selected + '>' + escapeHtml(opt) + '</option>';
+      });
+      html += '</select>';
+      return html;
+    }
+
+    if (setting.type === 'value') {
+      return '<input type="number" id="' + id + '" value="' + setting.value + '"' +
+        ' min="' + setting.min + '" max="' + setting.max + '" step="' + setting.step + '"' +
+        ' onchange="markChanged()">';
+    }
+
+    if (setting.type === 'string') {
+      const inputType = setting.name.toLowerCase().includes('password') ? 'password' : 'text';
+      const val = setting.value || '';
+      return '<input type="' + inputType + '" id="' + id + '" value="' + escapeHtml(val) + '"' +
+        ' oninput="markChanged()">';
+    }
+
+    return '';
+  }
+
+  function getValue(setting) {
+    const el = document.getElementById('setting-' + setting.key);
+    if (!el) return undefined;
+
+    if (setting.type === 'toggle') {
+      return el.checked ? 1 : 0;
+    }
+    if (setting.type === 'enum') {
+      return parseInt(el.value, 10);
+    }
+    if (setting.type === 'value') {
+      return parseInt(el.value, 10);
+    }
+    if (setting.type === 'string') {
+      return el.value;
+    }
+    return undefined;
+  }
+
+  function markChanged() {
+    document.getElementById('saveBtn').disabled = false;
+  }
+
+  async function loadSettings() {
+    try {
+      const response = await fetch('/api/settings');
+      if (!response.ok) {
+        throw new Error('Failed to load settings: ' + response.status);
+      }
+      allSettings = await response.json();
+
+      // Store original values
+      originalValues = {};
+      allSettings.forEach(function(s) {
+        originalValues[s.key] = s.value;
+      });
+
+      // Group by category
+      const groups = {};
+      allSettings.forEach(function(s) {
+        if (!groups[s.category]) groups[s.category] = [];
+        groups[s.category].push(s);
+      });
+
+      const container = document.getElementById('settings-container');
+      let html = '';
+
+      for (const category in groups) {
+        html += '<div class="card"><h2>' + escapeHtml(category) + '</h2>';
+        groups[category].forEach(function(s) {
+          html += '<div class="setting-row">' +
+            '<span class="setting-name">' + escapeHtml(s.name) + '</span>' +
+            '<span class="setting-control">' + renderControl(s) + '</span>' +
+            '</div>';
+        });
+        html += '</div>';
+      }
+
+      container.innerHTML = html;
+      document.getElementById('save-container').style.display = '';
+      document.getElementById('saveBtn').disabled = true;
+    } catch (e) {
+      console.error(e);
+      document.getElementById('settings-container').innerHTML =
+        '<div class="card"><p style="text-align:center;color:#e74c3c;">Failed to load settings</p></div>';
+    }
+  }
+
+  async function saveSettings() {
+    const btn = document.getElementById('saveBtn');
+    btn.disabled = true;
+    btn.textContent = 'Saving...';
+
+    // Collect only changed values
+    const changes = {};
+    allSettings.forEach(function(s) {
+      const current = getValue(s);
+      if (current !== undefined && current !== originalValues[s.key]) {
+        changes[s.key] = current;
+      }
+    });
+
+    if (Object.keys(changes).length === 0) {
+      showMessage('No changes to save.', false);
+      btn.textContent = 'Save Settings';
+      return;
+    }
+
+    try {
+      const response = await fetch('/api/settings', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(changes)
+      });
+
+      if (!response.ok) {
+        const text = await response.text();
+        throw new Error(text || 'Save failed');
+      }
+
+      // Update original values to new values
+      for (const key in changes) {
+        originalValues[key] = changes[key];
+      }
+
+      showMessage('Settings saved successfully!', false);
+    } catch (e) {
+      console.error(e);
+      showMessage('Error: ' + e.message, true);
+    }
+
+    btn.textContent = 'Save Settings';
+  }
+
+  loadSettings();
+</script>
+</body>
+</html>