From 58a28f3a14a8ab91d2f21ef73046335074968542 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 8 Jul 2026 15:01:19 +0000
Subject: [PATCH 1/9] Add settings tooltips and search to the web UI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Help users quickly find settings and understand how each one works.

Tooltips: a new delegated controller (static/v3/js/tooltips.js) drives an
accessible (i) info tooltip that appears on hover, keyboard focus, and tap.
A shared `help_tip` Jinja macro (partials/_macros.html) emits the trigger;
the plugin config macro and the core settings partials now surface help
text through it. Per the design, the always-visible field help paragraphs
are folded into the tooltip to declutter the forms, and the hardware/display
settings carry authored detail (default, range, recommendation).

Search: a global header search box finds settings across every settings tab
— even ones not yet opened — via a lazy client-side index built by scanning
the same field markup (static/v3/js/settings-search.js). Selecting a result
switches tabs, waits for the field to load, then scrolls to and flashes it.
A per-tab filter box hides non-matching fields on the current tab.

Plugin settings get tooltips for free by reusing each field's schema
`description`; every settings field also gets a stable `setting-<tab>-<key>`
anchor id for search navigation.

Styling uses the existing --color-* theme vars so light/dark mode both work,
and honors prefers-reduced-motion. Adds Flask render smoke tests that assert
each settings partial ships tooltips, anchors, and a filter box.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz
---
 test/test_web_settings_ui.py                  | 117 +++++
 web_interface/static/v3/app.css               | 145 ++++++
 web_interface/static/v3/js/settings-search.js | 428 ++++++++++++++++++
 web_interface/static/v3/js/tooltips.js        | 161 +++++++
 web_interface/templates/v3/base.html          |  25 +-
 .../templates/v3/partials/_macros.html        |  42 ++
 .../templates/v3/partials/backup_restore.html |  13 +-
 .../templates/v3/partials/display.html        | 158 +++----
 .../templates/v3/partials/durations.html      |   8 +-
 .../templates/v3/partials/general.html        |  41 +-
 .../templates/v3/partials/plugin_config.html  |  22 +-
 .../templates/v3/partials/schedule.html       |   8 +-
 web_interface/templates/v3/partials/wifi.html |  30 +-
 13 files changed, 1044 insertions(+), 154 deletions(-)
 create mode 100644 test/test_web_settings_ui.py
 create mode 100644 web_interface/static/v3/js/settings-search.js
 create mode 100644 web_interface/static/v3/js/tooltips.js
 create mode 100644 web_interface/templates/v3/partials/_macros.html

diff --git a/test/test_web_settings_ui.py b/test/test_web_settings_ui.py
new file mode 100644
index 000000000..657f5c54f
--- /dev/null
+++ b/test/test_web_settings_ui.py
@@ -0,0 +1,117 @@
+"""
+Smoke tests for the settings tooltips + search UI.
+
+These render the settings partials through Flask and assert that every settings
+field carries:
+  - a stable search anchor id (`id="setting-..."` on its .form-group), and
+  - an info tooltip (`class="help-tip"` emitted by the help_tip macro).
+
+They guard against macro/import breakage and against fields losing their anchor
+or tooltip when partials are edited. See web_interface/static/v3/js/tooltips.js
+and settings-search.js for the consumers of this markup.
+"""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+from flask import Flask
+
+PROJECT_ROOT = Path(__file__).parent.parent
+sys.path.insert(0, str(PROJECT_ROOT))
+
+
+# A realistic-enough config so the hand-written partials render every field.
+REALISTIC_CONFIG = {
+    "web_display_autostart": True,
+    "timezone": "America/Chicago",
+    "location": {"city": "Dallas", "state": "Texas", "country": "US"},
+    "plugin_system": {
+        "auto_discover": True,
+        "auto_load_enabled": True,
+        "development_mode": False,
+        "plugins_directory": "plugin-repos",
+    },
+    "schedule": {},
+    "dim_schedule": {"dim_brightness": 30},
+    "sync": {"role": "standalone", "port": 5765, "follower_position": "left"},
+    "display": {
+        "hardware": {
+            "rows": 32, "cols": 64, "chain_length": 2, "parallel": 1,
+            "brightness": 95, "hardware_mapping": "adafruit-hat-pwm",
+            "led_rgb_sequence": "RGB", "multiplexing": 0, "panel_type": "",
+            "row_address_type": 0, "scan_mode": 0, "pwm_bits": 9,
+            "pwm_dither_bits": 1, "pwm_lsb_nanoseconds": 130,
+            "limit_refresh_rate_hz": 120, "disable_hardware_pulsing": False,
+            "inverse_colors": False, "show_refresh_rate": False,
+        },
+        "runtime": {"gpio_slowdown": 3, "rp1_rio": 0},
+        "double_sided": {"enabled": False, "copies": 2, "axis": "horizontal"},
+        "use_short_date_format": False,
+        "dynamic_duration": {"max_duration_seconds": 180},
+        "vegas_scroll": {
+            "enabled": False, "scroll_speed": 50, "separator_width": 32,
+            "target_fps": 125, "buffer_ahead": 2,
+            "plugin_order": [], "excluded_plugins": [],
+        },
+        "display_durations": {"clock": 15, "weather": 30},
+    },
+}
+
+
+@pytest.fixture
+def client():
+    base = PROJECT_ROOT / "web_interface"
+    app = Flask(
+        __name__,
+        template_folder=str(base / "templates"),
+        static_folder=str(base / "static"),
+    )
+    app.config["TESTING"] = True
+
+    from web_interface.blueprints import pages_v3 as pv
+
+    mock_cm = MagicMock()
+    mock_cm.load_config.return_value = REALISTIC_CONFIG
+    mock_cm.get_raw_file_content.return_value = REALISTIC_CONFIG
+    mock_cm.get_config_path.return_value = "config/config.json"
+    mock_cm.get_secrets_path.return_value = "config/config_secrets.json"
+    pv.pages_v3.config_manager = mock_cm
+    pv.pages_v3.plugin_manager = MagicMock(plugins={})
+
+    app.register_blueprint(pv.pages_v3, url_prefix="/v3")
+    return app.test_client()
+
+
+# Settings tabs that must expose searchable, tooltipped fields.
+SETTINGS_TABS = ["general", "display", "durations", "schedule", "wifi"]
+
+
+@pytest.mark.parametrize("tab", SETTINGS_TABS)
+def test_settings_partial_has_tooltips_and_anchors(client, tab):
+    resp = client.get(f"/v3/partials/{tab}")
+    assert resp.status_code == 200, f"{tab} partial failed to render"
+    body = resp.get_data(as_text=True)
+
+    assert 'class="help-tip"' in body, f"{tab}: no tooltips rendered"
+    assert 'id="setting-' in body, f"{tab}: no search anchors rendered"
+    # Every settings field should be both anchored and tooltipped; tooltip count
+    # should not exceed anchor count (each field has at most one help_tip).
+    anchors = body.count('id="setting-')
+    tips = body.count('class="help-tip"')
+    assert tips >= 1 and anchors >= 1
+    assert tips <= anchors, f"{tab}: more tooltips ({tips}) than anchors ({anchors})"
+
+
+@pytest.mark.parametrize("tab", SETTINGS_TABS)
+def test_settings_partial_has_per_tab_filter(client, tab):
+    body = client.get(f"/v3/partials/{tab}").get_data(as_text=True)
+    assert 'class="settings-filter' in body, f"{tab}: per-tab filter box missing"
+
+
+def test_display_tooltip_carries_rich_text(client):
+    # The brightness tooltip should include the authored guidance, not just a label.
+    body = client.get("/v3/partials/display").get_data(as_text=True)
+    assert 'id="setting-display-brightness"' in body
+    assert "Recommended:" in body  # rich detail authored into a tooltip
diff --git a/web_interface/static/v3/app.css b/web_interface/static/v3/app.css
index 7ed7574a1..66870db4f 100644
--- a/web_interface/static/v3/app.css
+++ b/web_interface/static/v3/app.css
@@ -766,6 +766,151 @@ button.bg-white {
     }
 }
 
+/* ============================================================================ */
+/* Settings tooltips (help_tip macro + tooltips.js)                             */
+/* ============================================================================ */
+
+/* The (i) info trigger placed next to a setting label. */
+.help-tip {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.15rem;
+    height: 1.15rem;
+    margin-left: 0.375rem;
+    padding: 0;
+    border: none;
+    background: transparent;
+    color: var(--color-text-tertiary);
+    font-size: 0.8125rem;
+    line-height: 1;
+    cursor: help;
+    vertical-align: middle;
+    border-radius: 9999px;
+    transition: color 0.12s ease;
+}
+
+.help-tip:hover,
+.help-tip:focus-visible {
+    color: var(--color-primary);
+}
+
+.help-tip:focus-visible {
+    outline: 2px solid var(--color-primary);
+    outline-offset: 2px;
+}
+
+/* Singleton tooltip panel appended to <body> by tooltips.js. */
+#ledm-tooltip {
+    position: fixed;
+    z-index: 1000;
+    max-width: 20rem;
+    padding: 0.5rem 0.75rem;
+    background: var(--color-surface);
+    color: var(--color-text-secondary);
+    border: 1px solid var(--color-border);
+    border-radius: 0.5rem;
+    box-shadow: var(--shadow-lg);
+    font-size: 0.8125rem;
+    line-height: 1.45;
+    white-space: pre-line; /* renders authored "\n" line breaks */
+    pointer-events: none;  /* never steals hover/click from the page */
+    animation: tooltipFade 0.12s ease;
+}
+
+#ledm-tooltip[hidden] {
+    display: none;
+}
+
+@keyframes tooltipFade {
+    from { opacity: 0; }
+    to { opacity: 1; }
+}
+
+/* ============================================================================ */
+/* Settings search — global header dropdown + per-tab filter                    */
+/* ============================================================================ */
+
+#settings-search-results {
+    background: var(--color-surface);
+    border: 1px solid var(--color-border);
+    border-radius: 0.5rem;
+    box-shadow: var(--shadow-lg);
+    z-index: 50;
+    padding: 0.25rem;
+}
+
+.ssr-group {
+    padding: 0.375rem 0.625rem 0.25rem;
+    font-size: 0.6875rem;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--color-text-tertiary);
+    position: sticky;
+    top: 0;
+    background: var(--color-surface);
+}
+
+.ssr-option {
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+    text-align: left;
+    padding: 0.4rem 0.625rem;
+    border: none;
+    background: transparent;
+    border-radius: 0.375rem;
+    cursor: pointer;
+    color: var(--color-text-primary);
+}
+
+.ssr-option:hover,
+.ssr-option.active {
+    background: var(--color-info-bg);
+}
+
+.ssr-label {
+    font-size: 0.875rem;
+    font-weight: 500;
+}
+
+.ssr-help {
+    font-size: 0.75rem;
+    color: var(--color-text-tertiary);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    max-width: 100%;
+}
+
+.ssr-empty {
+    padding: 0.75rem 0.625rem;
+    font-size: 0.8125rem;
+    color: var(--color-text-tertiary);
+}
+
+/* Flash highlight applied to a field after search navigation. */
+@keyframes settingFlash {
+    0% { box-shadow: 0 0 0 0 rgba(37, 99, 235, 0); }
+    25% { box-shadow: 0 0 0 3px var(--color-primary); }
+    100% { box-shadow: 0 0 0 0 rgba(37, 99, 235, 0); }
+}
+
+.setting-flash {
+    animation: settingFlash 1.4s ease;
+    border-radius: 0.5rem;
+}
+
+@media (prefers-reduced-motion: reduce) {
+    #ledm-tooltip { animation: none; }
+    .setting-flash {
+        animation: none;
+        outline: 2px solid var(--color-primary);
+        outline-offset: 2px;
+    }
+}
+
 /* Removed .divider and .divider-light - not used anywhere */
 
 /* Enhanced Spacing Utilities - Only unique classes not in main utility section */
diff --git a/web_interface/static/v3/js/settings-search.js b/web_interface/static/v3/js/settings-search.js
new file mode 100644
index 000000000..914b680f8
--- /dev/null
+++ b/web_interface/static/v3/js/settings-search.js
@@ -0,0 +1,428 @@
+/*
+ * settings-search.js — global settings search + per-tab filter for the v3 UI.
+ *
+ * Two features share one lightweight index built from the same markup the
+ * tooltip work standardizes (.form-group[id^="setting-"] + <label> +
+ * .help-tip[data-tooltip]), so it can never drift from what is rendered:
+ *
+ *   1. Global search (header box): finds settings across ALL tabs, even ones
+ *      not yet opened, by fetching each tab's partial once and scanning it.
+ *      Clicking a result switches to the tab, waits for the field to load,
+ *      then scrolls to and flashes it.
+ *   2. Per-tab filter (the .settings-filter box under a partial title):
+ *      hides non-matching fields on the current tab. Delegated, so it keeps
+ *      working across HTMX swaps.
+ *
+ * No backend endpoint is required — plugins are enumerated from
+ * window.installedPlugins and their config partials are fetched the same way.
+ */
+(function () {
+    'use strict';
+
+    if (window._settingsSearchInit) return;
+    window._settingsSearchInit = true;
+
+    // Core settings tabs to index. Only tabs that contain real settings fields
+    // (a .form-group[id^="setting-"]) are listed. Operational/action tabs
+    // (overview, logs, history, cache, tools, fonts, backup/restore, raw config
+    // editor, plugin store) have nothing to navigate to and are excluded.
+    var CORE_TABS = [
+        { tab: 'general', label: 'General', url: '/v3/partials/general' },
+        { tab: 'display', label: 'Display', url: '/v3/partials/display' },
+        { tab: 'schedule', label: 'Schedule', url: '/v3/partials/schedule' },
+        { tab: 'wifi', label: 'WiFi', url: '/v3/partials/wifi' }
+    ];
+
+    var MAX_RESULTS = 25;
+
+    function debounce(fn, ms) {
+        var t;
+        return function () {
+            var args = arguments, ctx = this;
+            clearTimeout(t);
+            t = setTimeout(function () { fn.apply(ctx, args); }, ms);
+        };
+    }
+
+    function escapeHtml(s) {
+        return String(s == null ? '' : s)
+            .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+    }
+
+    function textOf(el) {
+        return (el && el.textContent ? el.textContent : '').replace(/\s+/g, ' ').trim();
+    }
+
+    // --- Index building -------------------------------------------------------
+
+    // Extract one index entry per settings field from a parsed document.
+    function scanDoc(doc, tab, tabLabel) {
+        var entries = [];
+        var nodes = doc.querySelectorAll('h2, h3, h4, .form-group[id^="setting-"]');
+        var section = '';
+        nodes.forEach(function (node) {
+            var tag = node.tagName.toLowerCase();
+            if (tag === 'h3' || tag === 'h4') {
+                section = textOf(node);
+                return;
+            }
+            if (tag === 'h2') { section = ''; return; }
+            // A settings .form-group
+            var labelEl = node.querySelector('label');
+            var label = textOf(labelEl) || node.id.replace(/^setting-/, '');
+            var tipEl = node.querySelector('.help-tip');
+            var help = tipEl ? (tipEl.getAttribute('data-tooltip') || '') : '';
+            var key = node.getAttribute('data-setting-key') || node.id.replace(/^setting-/, '');
+            entries.push({
+                tab: tab,
+                tabLabel: tabLabel,
+                section: section,
+                key: key,
+                label: label,
+                help: help,
+                anchorId: node.id,
+                hay: [label, help, key, tabLabel, section].join(' ').toLowerCase()
+            });
+        });
+        return entries;
+    }
+
+    function fetchAndScan(url, tab, tabLabel) {
+        return fetch(url, { headers: { 'X-Requested-With': 'settings-search' } })
+            .then(function (r) { return r.ok ? r.text() : ''; })
+            .then(function (html) {
+                if (!html) return [];
+                var doc = new DOMParser().parseFromString(html, 'text/html');
+                return scanDoc(doc, tab, tabLabel);
+            })
+            .catch(function () { return []; });
+    }
+
+    var buildPromise = null;
+    function buildIndex(force) {
+        if (window._settingsIndex && !force) return Promise.resolve(window._settingsIndex);
+        if (buildPromise && !force) return buildPromise;
+
+        var jobs = CORE_TABS.map(function (t) { return fetchAndScan(t.url, t.tab, t.label); });
+
+        var plugins = (window.installedPlugins || []);
+        plugins.forEach(function (p) {
+            if (!p || !p.id) return;
+            jobs.push(fetchAndScan('/v3/partials/plugin-config/' + encodeURIComponent(p.id),
+                p.id, p.name || p.id));
+        });
+
+        buildPromise = Promise.all(jobs).then(function (lists) {
+            var index = [];
+            lists.forEach(function (l) { index = index.concat(l); });
+            window._settingsIndex = index;
+            return index;
+        });
+        return buildPromise;
+    }
+
+    // --- Global search UI -----------------------------------------------------
+
+    var input = null, resultsBox = null, activeIndex = -1, currentResults = [];
+
+    function search(q) {
+        q = q.trim().toLowerCase();
+        if (!q) return [];
+        var terms = q.split(/\s+/);
+        var index = window._settingsIndex || [];
+        var out = [];
+        for (var i = 0; i < index.length && out.length < MAX_RESULTS; i++) {
+            var hay = index[i].hay;
+            var ok = true;
+            for (var j = 0; j < terms.length; j++) {
+                if (hay.indexOf(terms[j]) === -1) { ok = false; break; }
+            }
+            if (ok) out.push(index[i]);
+        }
+        return out;
+    }
+
+    function renderResults(results) {
+        currentResults = results;
+        activeIndex = -1;
+        if (!results.length) {
+            resultsBox.innerHTML = '<div class="ssr-empty">No settings found.</div>';
+            openResults();
+            return;
+        }
+        var html = '';
+        var lastTab = null;
+        results.forEach(function (r, i) {
+            if (r.tabLabel !== lastTab) {
+                html += '<div class="ssr-group">' + escapeHtml(r.tabLabel) + '</div>';
+                lastTab = r.tabLabel;
+            }
+            var sub = r.section ? (r.section + ' · ') : '';
+            var snippet = r.help ? r.help.split('\n')[0] : '';
+            html += '<button type="button" class="ssr-option" role="option" id="ssr-' + i + '" data-idx="' + i + '">' +
+                '<span class="ssr-label">' + escapeHtml(r.label) + '</span>' +
+                (snippet ? '<span class="ssr-help">' + escapeHtml(sub + snippet) + '</span>'
+                         : (sub ? '<span class="ssr-help">' + escapeHtml(r.section) + '</span>' : '')) +
+                '</button>';
+        });
+        resultsBox.innerHTML = html;
+        openResults();
+    }
+
+    function openResults() {
+        resultsBox.classList.remove('hidden');
+        if (input) input.setAttribute('aria-expanded', 'true');
+    }
+    function closeResults() {
+        resultsBox.classList.add('hidden');
+        activeIndex = -1;
+        if (input) {
+            input.setAttribute('aria-expanded', 'false');
+            input.removeAttribute('aria-activedescendant');
+        }
+    }
+
+    function highlight(idx) {
+        var opts = resultsBox.querySelectorAll('.ssr-option');
+        opts.forEach(function (o) { o.classList.remove('active'); });
+        if (idx < 0 || idx >= opts.length) { activeIndex = -1; return; }
+        activeIndex = idx;
+        var el = opts[idx];
+        el.classList.add('active');
+        el.scrollIntoView({ block: 'nearest' });
+        input.setAttribute('aria-activedescendant', el.id);
+    }
+
+    // --- Navigation to a setting ---------------------------------------------
+
+    function getAppData() {
+        var appEl = document.querySelector('[x-data="app()"]') || document.querySelector('[x-data]');
+        if (!appEl) return null;
+        if (appEl._x_dataStack && appEl._x_dataStack[0]) return appEl._x_dataStack[0];
+        if (appEl.__x && appEl.__x.$data) return appEl.__x.$data;
+        return null;
+    }
+
+    function setActiveTab(tab) {
+        var data = getAppData();
+        if (data) { data.activeTab = tab; return true; }
+        return false;
+    }
+
+    function waitForElement(id, timeout) {
+        return new Promise(function (resolve) {
+            var existing = document.getElementById(id);
+            if (existing) { resolve(existing); return; }
+            var host = document.getElementById('tab-content') || document.body;
+            var done = false;
+            var obs = new MutationObserver(function () {
+                var el = document.getElementById(id);
+                if (el && !done) {
+                    done = true;
+                    obs.disconnect();
+                    resolve(el);
+                }
+            });
+            obs.observe(host, { childList: true, subtree: true });
+            setTimeout(function () {
+                if (!done) { done = true; obs.disconnect(); resolve(document.getElementById(id)); }
+            }, timeout || 6000);
+        });
+    }
+
+    // Reveal any collapsed nested section (from render_nested_section) so the
+    // target field is actually visible before we scroll to it.
+    function revealAncestors(el) {
+        var node = el.parentElement;
+        while (node && node !== document.body) {
+            if (node.classList && node.classList.contains('nested-content')) {
+                var hidden = node.classList.contains('hidden') ||
+                    (node.style && node.style.display === 'none') ||
+                    (window.getComputedStyle(node).display === 'none');
+                if (hidden) {
+                    // toggleSection handles the class, inline display, and chevron.
+                    if (node.id && typeof window.toggleSection === 'function') {
+                        window.toggleSection(node.id);
+                    } else {
+                        node.classList.remove('hidden');
+                        node.style.display = 'block';
+                    }
+                }
+            }
+            node = node.parentElement;
+        }
+    }
+
+    function flash(el) {
+        el.classList.remove('setting-flash');
+        // force reflow so re-adding the class restarts the animation
+        void el.offsetWidth;
+        el.classList.add('setting-flash');
+        var clear = function () { el.classList.remove('setting-flash'); el.removeEventListener('animationend', clear); };
+        el.addEventListener('animationend', clear);
+    }
+
+    function navigateToSetting(entry) {
+        closeResults();
+        setActiveTab(entry.tab);
+        waitForElement(entry.anchorId, 6000).then(function (el) {
+            if (!el) return;
+            revealAncestors(el);
+            // Let the tab transition settle before scrolling.
+            setTimeout(function () {
+                el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+                flash(el);
+            }, 60);
+        });
+    }
+
+    // --- Wire up the header search box ----------------------------------------
+
+    function initSearchBox() {
+        input = document.getElementById('settings-search');
+        resultsBox = document.getElementById('settings-search-results');
+        if (!input || !resultsBox) return;
+
+        // Warm the index in the background so the first search is instant.
+        var warm = function () { buildIndex().catch(function () {}); };
+        if ('requestIdleCallback' in window) {
+            requestIdleCallback(warm, { timeout: 4000 });
+        } else {
+            setTimeout(warm, 3000);
+        }
+
+        input.addEventListener('focus', function () {
+            buildIndex().then(function () {
+                if (input.value.trim()) renderResults(search(input.value));
+            });
+        });
+
+        input.addEventListener('input', debounce(function () {
+            var q = input.value;
+            if (!q.trim()) { closeResults(); return; }
+            buildIndex().then(function () { renderResults(search(q)); });
+        }, 200));
+
+        input.addEventListener('keydown', function (e) {
+            var opts = resultsBox.querySelectorAll('.ssr-option');
+            if (e.key === 'ArrowDown') {
+                e.preventDefault();
+                if (resultsBox.classList.contains('hidden')) { renderResults(search(input.value)); return; }
+                highlight(Math.min(activeIndex + 1, opts.length - 1));
+            } else if (e.key === 'ArrowUp') {
+                e.preventDefault();
+                highlight(Math.max(activeIndex - 1, 0));
+            } else if (e.key === 'Enter') {
+                if (activeIndex >= 0 && currentResults[activeIndex]) {
+                    e.preventDefault();
+                    navigateToSetting(currentResults[activeIndex]);
+                } else if (currentResults.length) {
+                    e.preventDefault();
+                    navigateToSetting(currentResults[0]);
+                }
+            } else if (e.key === 'Escape') {
+                closeResults();
+                input.blur();
+            }
+        });
+
+        resultsBox.addEventListener('mousedown', function (e) {
+            // mousedown (not click) so it fires before the input blur closes us
+            var opt = e.target.closest('.ssr-option');
+            if (!opt) return;
+            e.preventDefault();
+            var idx = parseInt(opt.getAttribute('data-idx'), 10);
+            if (currentResults[idx]) navigateToSetting(currentResults[idx]);
+        });
+
+        document.addEventListener('click', function (e) {
+            if (!input) return;
+            if (e.target === input || resultsBox.contains(e.target)) return;
+            closeResults();
+        });
+    }
+
+    // --- Per-tab filter (delegated) -------------------------------------------
+
+    function filterScope(input) {
+        return input.closest('.plugin-config-tab') ||
+               input.closest('[id$="-content"]') ||
+               input.closest('.bg-white') ||
+               document;
+    }
+
+    function fieldHay(fg) {
+        var label = textOf(fg.querySelector('label'));
+        var tip = fg.querySelector('.help-tip');
+        var help = tip ? (tip.getAttribute('data-tooltip') || '') : '';
+        var key = fg.getAttribute('data-setting-key') || fg.id.replace(/^setting-/, '');
+        return (label + ' ' + help + ' ' + key).toLowerCase();
+    }
+
+    function applyTabFilter(scope, q) {
+        q = q.trim().toLowerCase();
+        var terms = q ? q.split(/\s+/) : [];
+        var fields = scope.querySelectorAll('.form-group[id^="setting-"]');
+        var anyVisible = false;
+
+        fields.forEach(function (fg) {
+            var show = true;
+            if (terms.length) {
+                var hay = fieldHay(fg);
+                for (var i = 0; i < terms.length; i++) {
+                    if (hay.indexOf(terms[i]) === -1) { show = false; break; }
+                }
+            }
+            fg.style.display = show ? '' : 'none';
+            if (show) anyVisible = true;
+        });
+
+        // Hide section headings whose settings all got filtered out.
+        var nodes = scope.querySelectorAll('h3, h4, .form-group');
+        var headings = [];
+        var current = null;
+        nodes.forEach(function (node) {
+            if (node.tagName === 'H3' || node.tagName === 'H4') {
+                current = { el: node, total: 0, visible: 0 };
+                headings.push(current);
+            } else if (current && node.matches('.form-group[id^="setting-"]')) {
+                current.total++;
+                if (node.style.display !== 'none') current.visible++;
+            }
+        });
+        headings.forEach(function (h) {
+            // Only auto-hide headings that exclusively group settings fields.
+            h.el.style.display = (terms.length && h.total > 0 && h.visible === 0) ? 'none' : '';
+        });
+
+        // Toggle the "no matches" note if the filter box provides one.
+        var wrap = scope.querySelector('.settings-filter-wrap');
+        if (wrap) {
+            var empty = wrap.querySelector('.settings-filter-empty');
+            if (empty) empty.classList.toggle('hidden', !(terms.length && !anyVisible));
+        }
+    }
+
+    document.addEventListener('input', function (e) {
+        var box = e.target.closest ? e.target.closest('.settings-filter') : null;
+        if (!box) return;
+        applyTabFilter(filterScope(box), box.value);
+    });
+
+    // --- Boot -----------------------------------------------------------------
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', initSearchBox);
+    } else {
+        initSearchBox();
+    }
+
+    // Expose for debugging / programmatic use.
+    window.LEDMatrixSettingsSearch = {
+        buildIndex: buildIndex,
+        navigateToSetting: navigateToSetting
+    };
+
+    console.log('[SettingsSearch] registered');
+})();
diff --git a/web_interface/static/v3/js/tooltips.js b/web_interface/static/v3/js/tooltips.js
new file mode 100644
index 000000000..bcebbb3cc
--- /dev/null
+++ b/web_interface/static/v3/js/tooltips.js
@@ -0,0 +1,161 @@
+/*
+ * tooltips.js — accessible, delegated tooltip controller for the v3 web UI.
+ *
+ * A single controller handles every `.help-tip` trigger on the page, including
+ * ones inside partials that HTMX swaps in later, with zero per-field wiring.
+ * Triggers are emitted by the `help_tip` Jinja macro (partials/_macros.html) as
+ * <button class="help-tip" data-tooltip="..."><i class="fas fa-circle-info">.
+ *
+ * Behaviour:
+ *   - hover (mouse)            -> show / hide
+ *   - keyboard focus           -> show / hide (only for :focus-visible)
+ *   - click / tap              -> toggle (the touch path)
+ *   - Escape / outside click   -> hide
+ * The tooltip text is set via textContent (XSS-safe) and supports "\n" line
+ * breaks via CSS `white-space: pre-line`. Styling lives in app.css and uses the
+ * --color-* theme vars, so light/dark mode work automatically.
+ */
+(function () {
+    'use strict';
+
+    if (window._tooltipsInit) return;
+    window._tooltipsInit = true;
+
+    var panel = null;
+    var currentTrigger = null;
+
+    function getPanel() {
+        if (panel) return panel;
+        panel = document.createElement('div');
+        panel.id = 'ledm-tooltip';
+        panel.setAttribute('role', 'tooltip');
+        panel.hidden = true;
+        document.body.appendChild(panel);
+        return panel;
+    }
+
+    function positionPanel(trigger) {
+        var p = getPanel();
+        var margin = 8;
+        var rect = trigger.getBoundingClientRect();
+        var pw = p.offsetWidth;
+        var ph = p.offsetHeight;
+        var vw = document.documentElement.clientWidth;
+        var vh = document.documentElement.clientHeight;
+
+        // Prefer above the trigger; flip below if it would clip the top.
+        var top = rect.top - ph - margin;
+        var placedBelow = false;
+        if (top < margin) {
+            top = rect.bottom + margin;
+            placedBelow = true;
+        }
+        // Keep it on screen vertically as a last resort.
+        if (top + ph > vh - margin) top = Math.max(margin, vh - ph - margin);
+
+        // Center horizontally on the trigger, clamped to the viewport.
+        var left = rect.left + rect.width / 2 - pw / 2;
+        if (left < margin) left = margin;
+        if (left + pw > vw - margin) left = Math.max(margin, vw - pw - margin);
+
+        p.style.top = Math.round(top) + 'px';
+        p.style.left = Math.round(left) + 'px';
+        p.setAttribute('data-placement', placedBelow ? 'below' : 'above');
+    }
+
+    function show(trigger) {
+        var text = trigger.getAttribute('data-tooltip');
+        if (!text) return;
+        var p = getPanel();
+        p.textContent = text;
+        p.hidden = false;
+        // Measure after it is displayed, then position.
+        positionPanel(trigger);
+        trigger.setAttribute('aria-describedby', 'ledm-tooltip');
+        currentTrigger = trigger;
+    }
+
+    function hide() {
+        if (!panel) return;
+        panel.hidden = true;
+        if (currentTrigger) {
+            currentTrigger.removeAttribute('aria-describedby');
+            currentTrigger = null;
+        }
+    }
+
+    function triggerFrom(target) {
+        return target && target.closest ? target.closest('.help-tip') : null;
+    }
+
+    // --- Delegated listeners on document (survive HTMX swaps) ---
+
+    document.addEventListener('mouseover', function (e) {
+        var t = triggerFrom(e.target);
+        if (t) show(t);
+    });
+
+    document.addEventListener('mouseout', function (e) {
+        var t = triggerFrom(e.target);
+        if (!t) return;
+        // Ignore moves that stay within the same trigger.
+        var to = e.relatedTarget;
+        if (to && t.contains(to)) return;
+        if (currentTrigger === t) hide();
+    });
+
+    document.addEventListener('focusin', function (e) {
+        var t = triggerFrom(e.target);
+        if (!t) return;
+        // Only auto-show on keyboard focus, so a mouse/touch focus does not
+        // fight the click handler below.
+        var focusVisible = true;
+        try {
+            focusVisible = t.matches(':focus-visible');
+        } catch (err) {
+            focusVisible = true; // older browsers: fall back to always show
+        }
+        if (focusVisible) show(t);
+    });
+
+    document.addEventListener('focusout', function (e) {
+        var t = triggerFrom(e.target);
+        if (t && currentTrigger === t) hide();
+    });
+
+    document.addEventListener('click', function (e) {
+        var t = triggerFrom(e.target);
+        if (t) {
+            // Prevent an enclosing <label> from toggling its control, and
+            // prevent form submission.
+            e.preventDefault();
+            e.stopPropagation();
+            if (currentTrigger === t && !getPanel().hidden) {
+                hide();
+            } else {
+                show(t);
+            }
+            return;
+        }
+        // Click anywhere else closes an open tooltip.
+        if (panel && !panel.hidden && !panel.contains(e.target)) hide();
+    });
+
+    document.addEventListener('keydown', function (e) {
+        if (e.key === 'Escape' && panel && !panel.hidden) hide();
+    });
+
+    // Reposition while visible; close when content is swapped out.
+    window.addEventListener('scroll', function () {
+        if (currentTrigger && panel && !panel.hidden) positionPanel(currentTrigger);
+    }, true);
+    window.addEventListener('resize', function () {
+        if (currentTrigger && panel && !panel.hidden) positionPanel(currentTrigger);
+    });
+    document.body.addEventListener('htmx:afterSwap', function () {
+        // The current trigger may have been removed by the swap.
+        if (currentTrigger && !document.body.contains(currentTrigger)) hide();
+    });
+
+    console.log('[Tooltips] controller registered');
+})();
diff --git a/web_interface/templates/v3/base.html b/web_interface/templates/v3/base.html
index c3f396dc6..8ec96d183 100644
--- a/web_interface/templates/v3/base.html
+++ b/web_interface/templates/v3/base.html
@@ -882,6 +882,25 @@ <h1 class="text-xl font-bold text-gray-900">
 
                 <!-- Connection status and theme toggle -->
                 <div class="flex items-center space-x-4">
+                    <!-- Global settings search -->
+                    <div class="relative hidden sm:block" id="settings-search-wrap">
+                        <input id="settings-search"
+                               type="text"
+                               role="combobox"
+                               aria-expanded="false"
+                               aria-autocomplete="list"
+                               aria-controls="settings-search-results"
+                               aria-label="Search settings"
+                               placeholder="Search settings…"
+                               autocomplete="off"
+                               class="form-control text-sm pl-8 pr-4 py-1.5 w-48 lg:w-64">
+                        <i class="fas fa-search absolute left-3 top-1/2 transform -translate-y-1/2 text-gray-400 text-xs" aria-hidden="true"></i>
+                        <div id="settings-search-results"
+                             role="listbox"
+                             aria-label="Settings search results"
+                             class="hidden absolute right-0 mt-1 w-80 max-h-96 overflow-y-auto"></div>
+                    </div>
+
                     <!-- Theme toggle -->
                     <button id="theme-toggle"
                             type="button"
@@ -4747,7 +4766,11 @@ <h4 class="font-medium ${colors.text} mb-1">
 
     <!-- Custom v3 JavaScript -->
     <script src="{{ url_for('static', filename='v3/app.js') }}" defer></script>
-    
+
+    <!-- Settings tooltips + settings search -->
+    <script src="{{ url_for('static', filename='v3/js/tooltips.js') }}" defer></script>
+    <script src="{{ url_for('static', filename='v3/js/settings-search.js') }}" defer></script>
+
     <!-- Modular Plugin Management JavaScript -->
     <!-- Load utilities first -->
     <script src="{{ url_for('static', filename='v3/js/utils/error_handler.js') }}" defer></script>
diff --git a/web_interface/templates/v3/partials/_macros.html b/web_interface/templates/v3/partials/_macros.html
new file mode 100644
index 000000000..4a6047ca3
--- /dev/null
+++ b/web_interface/templates/v3/partials/_macros.html
@@ -0,0 +1,42 @@
+{# ============================================================================ #}
+{# Shared UI macros for the v3 web interface.                                    #}
+{#                                                                               #}
+{# Import at the top of a partial with:                                          #}
+{#   {% import 'v3/partials/_macros.html' as ui %}                               #}
+{#                                                                               #}
+{# These power the settings tooltips and the settings search feature:           #}
+{#   - help_tip(text, label): the (i) info icon whose hover/focus tooltip        #}
+{#       explains a setting. This replaces the old always-visible <p> help.      #}
+{#   - fg_id(tab, key): stable anchor id for a .form-group so global search      #}
+{#       can scroll to it (e.g. "setting-display-brightness").                   #}
+{#   - settings_filter(): the per-tab filter box shown under a partial title.    #}
+{# ============================================================================ #}
+
+{# Info (i) tooltip trigger placed next to a setting label.                      #}
+{# `text` supports "\n" line breaks (rendered via CSS white-space: pre-line).    #}
+{# Renders nothing when `text` is empty so callers can pass through schema data. #}
+{% macro help_tip(text, label='') -%}
+{%- if text -%}
+<button type="button" class="help-tip" data-tooltip="{{ text }}"
+        aria-label="{% if label %}Help for {{ label }}{% else %}More information{% endif %}">
+<i class="fas fa-circle-info" aria-hidden="true"></i>
+</button>
+{%- endif -%}
+{%- endmacro %}
+
+{# Stable anchor id for a settings field's .form-group wrapper. #}
+{% macro fg_id(tab, key) -%}setting-{{ tab }}-{{ key }}{%- endmacro %}
+
+{# Per-tab filter box. Place directly under a partial's <h2> title block. #}
+{# The delegated handler in settings-search.js scopes to the enclosing tab. #}
+{% macro settings_filter(placeholder='Filter these settings…') -%}
+<div class="settings-filter-wrap relative mb-6">
+<input type="text"
+class="settings-filter form-control text-sm pl-9 pr-4 py-2 w-full"
+placeholder="{{ placeholder }}"
+aria-label="Filter settings on this tab"
+autocomplete="off">
+<i class="fas fa-search absolute left-3 top-1/2 transform -translate-y-1/2 text-gray-400 text-sm" aria-hidden="true"></i>
+<p class="settings-filter-empty text-sm text-gray-500 mt-3 hidden">No settings match your filter.</p>
+</div>
+{%- endmacro %}
diff --git a/web_interface/templates/v3/partials/backup_restore.html b/web_interface/templates/v3/partials/backup_restore.html
index 65696284e..b4525a47c 100644
--- a/web_interface/templates/v3/partials/backup_restore.html
+++ b/web_interface/templates/v3/partials/backup_restore.html
@@ -1,3 +1,4 @@
+{% import 'v3/partials/_macros.html' as ui %}
 <div class="space-y-6" id="backup-restore-root">
 
     <!-- Security warning -->
@@ -70,12 +71,12 @@ <h3 class="text-sm font-medium text-gray-900 mb-2">Backup contents</h3>
 
                 <h3 class="text-sm font-medium text-gray-900 mt-4 mb-2">Choose what to restore</h3>
                 <div class="grid grid-cols-1 md:grid-cols-2 gap-2 text-sm text-gray-700">
-                    <label class="flex items-center gap-2"><input type="checkbox" id="opt-config" checked> <span>Main configuration</span></label>
-                    <label class="flex items-center gap-2"><input type="checkbox" id="opt-secrets" checked> <span>API keys (secrets)</span></label>
-                    <label class="flex items-center gap-2"><input type="checkbox" id="opt-wifi" checked> <span>WiFi configuration</span></label>
-                    <label class="flex items-center gap-2"><input type="checkbox" id="opt-fonts" checked> <span>User-uploaded fonts</span></label>
-                    <label class="flex items-center gap-2"><input type="checkbox" id="opt-plugin-uploads" checked> <span>Plugin image uploads</span></label>
-                    <label class="flex items-center gap-2"><input type="checkbox" id="opt-reinstall" checked> <span>Reinstall missing plugins</span></label>
+                    <label class="flex items-center gap-2"><input type="checkbox" id="opt-config" checked> <span>Main configuration</span>{{ ui.help_tip('Restore config.json — display settings, schedules, location, and plugin configuration.', 'Main configuration') }}</label>
+                    <label class="flex items-center gap-2"><input type="checkbox" id="opt-secrets" checked> <span>API keys (secrets)</span>{{ ui.help_tip('Restore config_secrets.json — your weather, sports, and other service API keys.\nLeave off if you prefer to re-enter keys by hand.', 'API keys') }}</label>
+                    <label class="flex items-center gap-2"><input type="checkbox" id="opt-wifi" checked> <span>WiFi configuration</span>{{ ui.help_tip('Restore saved WiFi network names and credentials.', 'WiFi configuration') }}</label>
+                    <label class="flex items-center gap-2"><input type="checkbox" id="opt-fonts" checked> <span>User-uploaded fonts</span>{{ ui.help_tip('Restore any custom fonts you uploaded via the Fonts tab.', 'User-uploaded fonts') }}</label>
+                    <label class="flex items-center gap-2"><input type="checkbox" id="opt-plugin-uploads" checked> <span>Plugin image uploads</span>{{ ui.help_tip('Restore images and files that plugins let you upload (logos, backgrounds, etc.).', 'Plugin image uploads') }}</label>
+                    <label class="flex items-center gap-2"><input type="checkbox" id="opt-reinstall" checked> <span>Reinstall missing plugins</span>{{ ui.help_tip('After restoring, re-download any plugins that were installed in the backup but are missing now.', 'Reinstall missing plugins') }}</label>
                 </div>
 
                 <div class="mt-4 flex gap-2">
diff --git a/web_interface/templates/v3/partials/display.html b/web_interface/templates/v3/partials/display.html
index be9b6e041..d9ffd15ec 100644
--- a/web_interface/templates/v3/partials/display.html
+++ b/web_interface/templates/v3/partials/display.html
@@ -1,9 +1,12 @@
+{% import 'v3/partials/_macros.html' as ui %}
 <div class="bg-white rounded-lg shadow p-6">
     <div class="border-b border-gray-200 pb-4 mb-6">
         <h2 class="text-lg font-semibold text-gray-900">Display Settings</h2>
         <p class="mt-1 text-sm text-gray-600">Configure LED matrix hardware settings and display options.</p>
     </div>
 
+    {{ ui.settings_filter('Filter display settings…') }}
+
     <!-- Hardware status banner: shown when display service is in fallback/simulation mode -->
     <div x-data="{ show: false, errorMsg: '' }"
          x-init="fetch('/api/v3/hardware/status').then(r => r.json()).then(d => {
@@ -37,8 +40,8 @@ <h2 class="text-lg font-semibold text-gray-900">Display Settings</h2>
             <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
 
             <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 xl:grid-cols-4 2xl:grid-cols-4 gap-4 mb-4">
-                <div class="form-group">
-                    <label for="rows" class="block text-sm font-medium text-gray-700">Rows</label>
+                <div class="form-group" id="setting-display-rows" data-setting-key="display.hardware.rows">
+                    <label for="rows" class="block text-sm font-medium text-gray-700">Rows{{ ui.help_tip('Number of LED rows on a single panel.\nCommon: 16, 32, or 64. Default: 32. Must match your panel.', 'Rows') }}</label>
                     <input type="number"
                            id="rows"
                            name="rows"
@@ -46,11 +49,10 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
                            min="1"
                            max="64"
                            class="form-control">
-                    <p class="mt-1 text-sm text-gray-600">Number of LED rows</p>
                 </div>
 
-                <div class="form-group">
-                    <label for="cols" class="block text-sm font-medium text-gray-700">Columns</label>
+                <div class="form-group" id="setting-display-cols" data-setting-key="display.hardware.cols">
+                    <label for="cols" class="block text-sm font-medium text-gray-700">Columns{{ ui.help_tip('Number of LED columns on a single panel.\nCommon: 32 or 64. Default: 64. Must match your panel.', 'Columns') }}</label>
                     <input type="number"
                            id="cols"
                            name="cols"
@@ -58,11 +60,10 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
                            min="1"
                            max="128"
                            class="form-control">
-                    <p class="mt-1 text-sm text-gray-600">Number of LED columns</p>
                 </div>
 
-                <div class="form-group">
-                    <label for="chain_length" class="block text-sm font-medium text-gray-700">Chain Length</label>
+                <div class="form-group" id="setting-display-chain_length" data-setting-key="display.hardware.chain_length">
+                    <label for="chain_length" class="block text-sm font-medium text-gray-700">Chain Length{{ ui.help_tip('How many panels are wired end-to-end in one chain.\nDefault: 2. Example: two 64×32 panels chained make a 128×32 display.', 'Chain Length') }}</label>
                     <input type="number"
                            id="chain_length"
                            name="chain_length"
@@ -70,11 +71,10 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
                            min="1"
                            max="24"
                            class="form-control">
-                    <p class="mt-1 text-sm text-gray-600">Number of LED panels chained together</p>
                 </div>
 
-                <div class="form-group">
-                    <label for="parallel" class="block text-sm font-medium text-gray-700">Parallel</label>
+                <div class="form-group" id="setting-display-parallel" data-setting-key="display.hardware.parallel">
+                    <label for="parallel" class="block text-sm font-medium text-gray-700">Parallel{{ ui.help_tip('Number of separate chains driven in parallel from the HAT.\nDefault: 1. The Raspberry Pi supports up to 3 (some HATs allow more).', 'Parallel') }}</label>
                     <input type="number"
                            id="parallel"
                            name="parallel"
@@ -82,13 +82,12 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
                            min="1"
                            max="4"
                            class="form-control">
-                    <p class="mt-1 text-sm text-gray-600">Number of parallel chains</p>
                 </div>
             </div>
 
             <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-                <div class="form-group">
-                    <label for="brightness" class="block text-sm font-medium text-gray-700">Brightness</label>
+                <div class="form-group" id="setting-display-brightness" data-setting-key="display.hardware.brightness">
+                    <label for="brightness" class="block text-sm font-medium text-gray-700">Brightness{{ ui.help_tip('Overall LED brightness (1–100%).\nLower is dimmer, higher is brighter. Recommended: 70–90 indoors, 90–100 in bright rooms.', 'Brightness') }}</label>
                     <div class="flex items-center space-x-2">
                         <input type="range"
                                id="brightness"
@@ -99,11 +98,10 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
                                class="flex-1">
                         <span id="brightness-value" class="text-sm font-medium w-12">{{ main_config.display.hardware.brightness or 95 }}</span>
                     </div>
-                    <p class="mt-1 text-sm text-gray-600">LED brightness: <span id="brightness-display">{{ main_config.display.hardware.brightness or 95 }}</span>%</p>
                 </div>
 
-                <div class="form-group">
-                    <label for="hardware_mapping" class="block text-sm font-medium text-gray-700">Hardware Mapping</label>
+                <div class="form-group" id="setting-display-hardware_mapping" data-setting-key="display.hardware.hardware_mapping">
+                    <label for="hardware_mapping" class="block text-sm font-medium text-gray-700">Hardware Mapping{{ ui.help_tip('How the LED panel is wired to the Pi.\nUse "Adafruit HAT PWM" for an Adafruit HAT/Bonnet with the PWM solder mod; "Adafruit HAT" without it; "Regular" for direct GPIO wiring.', 'Hardware Mapping') }}</label>
                     <select id="hardware_mapping" name="hardware_mapping" class="form-control">
                         <option value="adafruit-hat-pwm" {% if main_config.display.hardware.hardware_mapping == "adafruit-hat-pwm" %}selected{% endif %}>Adafruit HAT PWM</option>
                         <option value="adafruit-hat" {% if main_config.display.hardware.hardware_mapping == "adafruit-hat" %}selected{% endif %}>Adafruit HAT</option>
@@ -114,8 +112,8 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
             </div>
 
             <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
-                <div class="form-group">
-                    <label for="led_rgb_sequence" class="block text-sm font-medium text-gray-700">LED RGB Sequence</label>
+                <div class="form-group" id="setting-display-led_rgb_sequence" data-setting-key="display.hardware.led_rgb_sequence">
+                    <label for="led_rgb_sequence" class="block text-sm font-medium text-gray-700">LED RGB Sequence{{ ui.help_tip('Order the panel expects color channels in.\nChange this only if reds/greens/blues look swapped. Default: RGB.', 'LED RGB Sequence') }}</label>
                     <select id="led_rgb_sequence" name="led_rgb_sequence" class="form-control">
                         <option value="RGB" {% if main_config.display.hardware.get('led_rgb_sequence', 'RGB') == "RGB" %}selected{% endif %}>RGB</option>
                         <option value="RBG" {% if main_config.display.hardware.get('led_rgb_sequence', 'RGB') == "RBG" %}selected{% endif %}>RBG</option>
@@ -124,11 +122,10 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
                         <option value="BRG" {% if main_config.display.hardware.get('led_rgb_sequence', 'RGB') == "BRG" %}selected{% endif %}>BRG</option>
                         <option value="BGR" {% if main_config.display.hardware.get('led_rgb_sequence', 'RGB') == "BGR" %}selected{% endif %}>BGR</option>
                     </select>
-                    <p class="mt-1 text-sm text-gray-600">Color channel order for your LED panels</p>
                 </div>
 
-                <div class="form-group">
-                    <label for="multiplexing" class="block text-sm font-medium text-gray-700">Multiplexing</label>
+                <div class="form-group" id="setting-display-multiplexing" data-setting-key="display.hardware.multiplexing">
+                    <label for="multiplexing" class="block text-sm font-medium text-gray-700">Multiplexing{{ ui.help_tip('Pixel-mapping scheme used by outdoor/specialty panels.\nLeave at 0 (Direct) for most indoor panels. Only change if the image is scrambled — try values until it looks right.', 'Multiplexing') }}</label>
                     <select id="multiplexing" name="multiplexing" class="form-control">
                         <option value="0" {% if main_config.display.hardware.get('multiplexing', 0)|int == 0 %}selected{% endif %}>0 - Direct</option>
                         <option value="1" {% if main_config.display.hardware.get('multiplexing', 0)|int == 1 %}selected{% endif %}>1 - Stripe</option>
@@ -154,21 +151,19 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
                         <option value="21" {% if main_config.display.hardware.get('multiplexing', 0)|int == 21 %}selected{% endif %}>21 - DoubleZMultiplex</option>
                         <option value="22" {% if main_config.display.hardware.get('multiplexing', 0)|int == 22 %}selected{% endif %}>22 - P4Outdoor-80x40</option>
                     </select>
-                    <p class="mt-1 text-sm text-gray-600">Multiplexing scheme for your LED panels</p>
                 </div>
 
-                <div class="form-group">
-                    <label for="panel_type" class="block text-sm font-medium text-gray-700">Panel Type</label>
+                <div class="form-group" id="setting-display-panel_type" data-setting-key="display.hardware.panel_type">
+                    <label for="panel_type" class="block text-sm font-medium text-gray-700">Panel Type{{ ui.help_tip('Special initialization for panels with a specific driver chip (e.g. FM6126A, FM6127).\nLeave on Standard unless your panel stays blank or shows only the first pixel.', 'Panel Type') }}</label>
                     <select id="panel_type" name="panel_type" class="form-control">
                         <option value="" {% if not main_config.display.hardware.get('panel_type', '') %}selected{% endif %}>Standard</option>
                         <option value="FM6126A" {% if main_config.display.hardware.get('panel_type', '') == "FM6126A" %}selected{% endif %}>FM6126A</option>
                         <option value="FM6127" {% if main_config.display.hardware.get('panel_type', '') == "FM6127" %}selected{% endif %}>FM6127</option>
                     </select>
-                    <p class="mt-1 text-sm text-gray-600">Special panel chipset initialization (use Standard unless your panel requires it)</p>
                 </div>
 
-                <div class="form-group">
-                    <label for="row_address_type" class="block text-sm font-medium text-gray-700">Row Address Type</label>
+                <div class="form-group" id="setting-display-row_address_type" data-setting-key="display.hardware.row_address_type">
+                    <label for="row_address_type" class="block text-sm font-medium text-gray-700">Row Address Type{{ ui.help_tip('Row addressing scheme used by the panel.\nLeave at 0 (Default) unless your panel needs AB/ABC addressing — a wrong value shows a garbled or shifted image.', 'Row Address Type') }}</label>
                     <select id="row_address_type" name="row_address_type" class="form-control">
                         <option value="0" {% if main_config.display.hardware.get('row_address_type', 0)|int == 0 %}selected{% endif %}>0 - Default</option>
                         <option value="1" {% if main_config.display.hardware.get('row_address_type', 0)|int == 1 %}selected{% endif %}>1 - AB-addressed panels</option>
@@ -176,13 +171,12 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
                         <option value="3" {% if main_config.display.hardware.get('row_address_type', 0)|int == 3 %}selected{% endif %}>3 - ABC-addressed panels</option>
                         <option value="4" {% if main_config.display.hardware.get('row_address_type', 0)|int == 4 %}selected{% endif %}>4 - ABC Shift + DE direct</option>
                     </select>
-                    <p class="mt-1 text-sm text-gray-600">Row addressing scheme — leave at Default (0) unless your panel requires a specific type</p>
                 </div>
             </div>
 
             <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
-                <div class="form-group">
-                    <label for="gpio_slowdown" class="block text-sm font-medium text-gray-700">GPIO Slowdown</label>
+                <div class="form-group" id="setting-display-gpio_slowdown" data-setting-key="display.runtime.gpio_slowdown">
+                    <label for="gpio_slowdown" class="block text-sm font-medium text-gray-700">GPIO Slowdown{{ ui.help_tip('Slows the GPIO signal so the panel keeps up.\nGuide: Pi 3 → 1–2, Pi 4 → 2–4, Pi 5 (PIO) → 1–3. Increase if the display shows garbage or flicker; in RIO mode higher values may improve performance.', 'GPIO Slowdown') }}</label>
                     <input type="number"
                            id="gpio_slowdown"
                            name="gpio_slowdown"
@@ -190,22 +184,20 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
                            min="0"
                            max="10"
                            class="form-control">
-                    <p class="mt-1 text-sm text-gray-600">Pi 3: 1&ndash;2 &middot; Pi 4: 2&ndash;4 &middot; Pi 5 PIO: 1&ndash;3. Increase if display shows garbage; in RIO mode higher values may improve performance.</p>
                 </div>
 
-                <div class="form-group">
+                <div class="form-group" id="setting-display-rp1_rio" data-setting-key="display.runtime.rp1_rio">
                     <label for="rp1_rio" class="block text-sm font-medium text-gray-700">
-                        RP1 Backend <span class="text-xs text-gray-400 font-normal">(Pi 5 only)</span>
+                        RP1 Backend <span class="text-xs text-gray-400 font-normal">(Pi 5 only)</span>{{ ui.help_tip('Pi 5 RP1 coprocessor driver mode.\nPIO (0) is the default and uses less CPU. RIO (1) can push a higher refresh rate but inverts the GPIO Slowdown behavior. Ignored on Pi 3/4.', 'RP1 Backend') }}
                     </label>
                     <select id="rp1_rio" name="rp1_rio" class="form-control">
                         <option value="0" {% if main_config.display.get('runtime', {}).get('rp1_rio', 0)|int == 0 %}selected{% endif %}>0 &mdash; PIO (default, low CPU)</option>
                         <option value="1" {% if main_config.display.get('runtime', {}).get('rp1_rio', 0)|int == 1 %}selected{% endif %}>1 &mdash; RIO (higher throughput; slowdown inverted)</option>
                     </select>
-                    <p class="mt-1 text-sm text-gray-600">Pi 5 RP1 coprocessor mode. Ignored on Pi 3/4.</p>
                 </div>
 
-                <div class="form-group">
-                    <label for="scan_mode" class="block text-sm font-medium text-gray-700">Scan Mode</label>
+                <div class="form-group" id="setting-display-scan_mode" data-setting-key="display.hardware.scan_mode">
+                    <label for="scan_mode" class="block text-sm font-medium text-gray-700">Scan Mode{{ ui.help_tip('Order rows are refreshed in.\n0 = progressive (default), 1 = interlaced. Change only if you see banding or flicker on certain panels.', 'Scan Mode') }}</label>
                     <input type="number"
                            id="scan_mode"
                            name="scan_mode"
@@ -213,13 +205,12 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
                            min="0"
                            max="1"
                            class="form-control">
-                    <p class="mt-1 text-sm text-gray-600">Scan mode for LED matrix (0-1)</p>
                 </div>
             </div>
 
             <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-                <div class="form-group">
-                    <label for="pwm_bits" class="block text-sm font-medium text-gray-700">PWM Bits</label>
+                <div class="form-group" id="setting-display-pwm_bits" data-setting-key="display.hardware.pwm_bits">
+                    <label for="pwm_bits" class="block text-sm font-medium text-gray-700">PWM Bits{{ ui.help_tip('Color depth per channel (1–11).\nHigher means smoother color but a lower refresh rate; lower means faster refresh with more banding. Default: 11 (this build defaults to 9).', 'PWM Bits') }}</label>
                     <input type="number"
                            id="pwm_bits"
                            name="pwm_bits"
@@ -227,11 +218,10 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
                            min="1"
                            max="11"
                            class="form-control">
-                    <p class="mt-1 text-sm text-gray-600">PWM bits for brightness control (1-11)</p>
                 </div>
 
-                <div class="form-group">
-                    <label for="pwm_dither_bits" class="block text-sm font-medium text-gray-700">PWM Dither Bits</label>
+                <div class="form-group" id="setting-display-pwm_dither_bits" data-setting-key="display.hardware.pwm_dither_bits">
+                    <label for="pwm_dither_bits" class="block text-sm font-medium text-gray-700">PWM Dither Bits{{ ui.help_tip('Time-dithering to gain apparent color depth (0–4).\nDefault: 0. Raising it can smooth gradients at the cost of a slightly lower refresh rate.', 'PWM Dither Bits') }}</label>
                     <input type="number"
                            id="pwm_dither_bits"
                            name="pwm_dither_bits"
@@ -239,13 +229,12 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
                            min="0"
                            max="4"
                            class="form-control">
-                    <p class="mt-1 text-sm text-gray-600">PWM dither bits (0-4)</p>
                 </div>
             </div>
 
             <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-                <div class="form-group">
-                    <label for="pwm_lsb_nanoseconds" class="block text-sm font-medium text-gray-700">PWM LSB Nanoseconds</label>
+                <div class="form-group" id="setting-display-pwm_lsb_nanoseconds" data-setting-key="display.hardware.pwm_lsb_nanoseconds">
+                    <label for="pwm_lsb_nanoseconds" class="block text-sm font-medium text-gray-700">PWM LSB Nanoseconds{{ ui.help_tip('Base time for the least-significant color bit (50–500 ns).\nDefault: 130. Raising it can reduce flicker on some panels but lowers the maximum refresh rate.', 'PWM LSB Nanoseconds') }}</label>
                     <input type="number"
                            id="pwm_lsb_nanoseconds"
                            name="pwm_lsb_nanoseconds"
@@ -253,11 +242,10 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
                            min="50"
                            max="500"
                            class="form-control">
-                    <p class="mt-1 text-sm text-gray-600">PWM LSB nanoseconds (50-500)</p>
                 </div>
 
-                <div class="form-group">
-                    <label for="limit_refresh_rate_hz" class="block text-sm font-medium text-gray-700">Limit Refresh Rate (Hz)</label>
+                <div class="form-group" id="setting-display-limit_refresh_rate_hz" data-setting-key="display.hardware.limit_refresh_rate_hz">
+                    <label for="limit_refresh_rate_hz" class="block text-sm font-medium text-gray-700">Limit Refresh Rate (Hz){{ ui.help_tip('Caps the panel refresh rate (1–1000 Hz).\nDefault: 120. A steady cap reduces flicker in camera recordings and keeps timing consistent. Set higher or to the max your panel supports for the smoothest motion.', 'Limit Refresh Rate') }}</label>
                     <input type="number"
                            id="limit_refresh_rate_hz"
                            name="limit_refresh_rate_hz"
@@ -265,7 +253,6 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Hardware Configuration</h3>
                            min="1"
                            max="1000"
                            class="form-control">
-                    <p class="mt-1 text-sm text-gray-600">Limit refresh rate in Hz (1-1000)</p>
                 </div>
             </div>
         </div>
@@ -276,7 +263,7 @@ <h3 class="text-md font-medium text-gray-900 mb-1">Double-Sided Display</h3>
             <p class="text-sm text-gray-600 mb-4">Show the same content on every panel in the chain &mdash; e.g. two 64&times;32 panels mirrored, or four panels as two identical screens. Rendered once and duplicated, so it adds no extra CPU. Takes effect after a display restart.</p>
 
             <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
-                <div class="form-group">
+                <div class="form-group" id="setting-display-double_sided_enabled" data-setting-key="display.double_sided.enabled">
                     <label class="flex items-center gap-2">
                         <input type="checkbox"
                                id="double_sided_enabled"
@@ -285,12 +272,12 @@ <h3 class="text-md font-medium text-gray-900 mb-1">Double-Sided Display</h3>
                                {% if main_config.display.get('double_sided', {}).get('enabled') %}checked{% endif %}
                                class="form-control h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded">
                         <span class="text-sm font-medium text-gray-700">Enabled</span>
+                        {{ ui.help_tip('Show the same content mirrored across every panel in the chain.\nRendered once and duplicated, so it adds no extra CPU. Takes effect after a display restart.', 'Double-Sided Enabled') }}
                     </label>
-                    <p class="mt-1 text-sm text-gray-600">Mirror one screen across all panels.</p>
                 </div>
 
-                <div class="form-group">
-                    <label for="double_sided_copies" class="block text-sm font-medium text-gray-700">Copies</label>
+                <div class="form-group" id="setting-display-double_sided_copies" data-setting-key="display.double_sided.copies">
+                    <label for="double_sided_copies" class="block text-sm font-medium text-gray-700">Copies{{ ui.help_tip('How many identical screens to split the panel area into (2–8).\nMust divide the panel evenly — e.g. 2 for a two-sided cube.', 'Copies') }}</label>
                     <input type="number"
                            id="double_sided_copies"
                            name="double_sided_copies"
@@ -298,16 +285,14 @@ <h3 class="text-md font-medium text-gray-900 mb-1">Double-Sided Display</h3>
                            min="2"
                            max="8"
                            class="form-control">
-                    <p class="mt-1 text-sm text-gray-600">Number of identical screens. Must divide the panel evenly.</p>
                 </div>
 
-                <div class="form-group">
-                    <label for="double_sided_axis" class="block text-sm font-medium text-gray-700">Split Axis</label>
+                <div class="form-group" id="setting-display-double_sided_axis" data-setting-key="display.double_sided.axis">
+                    <label for="double_sided_axis" class="block text-sm font-medium text-gray-700">Split Axis{{ ui.help_tip('Direction the display is divided into copies.\nHorizontal splits along the chained panels (side by side); Vertical splits along parallel chains (stacked).', 'Split Axis') }}</label>
                     <select id="double_sided_axis" name="double_sided_axis" class="form-control">
                         <option value="horizontal" {% if main_config.display.get('double_sided', {}).get('axis', 'horizontal') == 'horizontal' %}selected{% endif %}>Horizontal &mdash; chained panels (side by side)</option>
                         <option value="vertical" {% if main_config.display.get('double_sided', {}).get('axis', 'horizontal') == 'vertical' %}selected{% endif %}>Vertical &mdash; parallel chains (stacked)</option>
                     </select>
-                    <p class="mt-1 text-sm text-gray-600">Horizontal splits the chain; vertical splits parallel outputs.</p>
                 </div>
             </div>
         </div>
@@ -317,7 +302,7 @@ <h3 class="text-md font-medium text-gray-900 mb-1">Double-Sided Display</h3>
             <h3 class="text-md font-medium text-gray-900 mb-4">Display Options</h3>
 
             <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-                <div class="form-group">
+                <div class="form-group" id="setting-display-disable_hardware_pulsing" data-setting-key="display.hardware.disable_hardware_pulsing">
                     <label class="flex items-center">
                         <input type="checkbox"
                                name="disable_hardware_pulsing"
@@ -325,10 +310,11 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Display Options</h3>
                                {% if main_config.display.hardware.disable_hardware_pulsing %}checked{% endif %}
                                class="form-control h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded">
                         <span class="ml-2 text-sm font-medium text-gray-900">Disable Hardware Pulsing</span>
+                        {{ ui.help_tip('Turn off hardware PWM pulsing.\nEnable this if the Pi audio is in use or you hear buzzing / see instability. Slightly increases CPU usage.', 'Disable Hardware Pulsing') }}
                     </label>
                 </div>
 
-                <div class="form-group">
+                <div class="form-group" id="setting-display-inverse_colors" data-setting-key="display.hardware.inverse_colors">
                     <label class="flex items-center">
                         <input type="checkbox"
                                name="inverse_colors"
@@ -336,10 +322,11 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Display Options</h3>
                                {% if main_config.display.hardware.inverse_colors %}checked{% endif %}
                                class="form-control h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded">
                         <span class="ml-2 text-sm font-medium text-gray-900">Inverse Colors</span>
+                        {{ ui.help_tip('Invert every color the panel shows.\nDefault: off. Only needed for panels wired with inverted color logic.', 'Inverse Colors') }}
                     </label>
                 </div>
 
-                <div class="form-group">
+                <div class="form-group" id="setting-display-show_refresh_rate" data-setting-key="display.hardware.show_refresh_rate">
                     <label class="flex items-center">
                         <input type="checkbox"
                                name="show_refresh_rate"
@@ -347,10 +334,11 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Display Options</h3>
                                {% if main_config.display.hardware.show_refresh_rate %}checked{% endif %}
                                class="form-control h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded">
                         <span class="ml-2 text-sm font-medium text-gray-900">Show Refresh Rate</span>
+                        {{ ui.help_tip('Overlay the live panel refresh rate on the display.\nUseful for tuning GPIO Slowdown and PWM settings; turn off for normal use.', 'Show Refresh Rate') }}
                     </label>
                 </div>
 
-                <div class="form-group">
+                <div class="form-group" id="setting-display-use_short_date_format" data-setting-key="display.use_short_date_format">
                     <label class="flex items-center">
                         <input type="checkbox"
                                name="use_short_date_format"
@@ -358,6 +346,7 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Display Options</h3>
                                {% if main_config.display.use_short_date_format %}checked{% endif %}
                                class="form-control h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded">
                         <span class="ml-2 text-sm font-medium text-gray-900">Use Short Date Format</span>
+                        {{ ui.help_tip('Show dates in a compact form (e.g. 7/8 instead of July 8).\nHandy on narrow displays where space is tight.', 'Use Short Date Format') }}
                     </label>
                 </div>
             </div>
@@ -366,8 +355,8 @@ <h3 class="text-md font-medium text-gray-900 mb-4">Display Options</h3>
             <div class="mt-6 pt-4 border-t border-gray-300">
                 <h4 class="text-sm font-medium text-gray-900 mb-3">Dynamic Duration</h4>
                 <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-                    <div class="form-group">
-                        <label for="max_dynamic_duration_seconds" class="block text-sm font-medium text-gray-700">Max Dynamic Duration (seconds)</label>
+                    <div class="form-group" id="setting-display-max_dynamic_duration_seconds" data-setting-key="display.dynamic_duration.max_duration_seconds">
+                        <label for="max_dynamic_duration_seconds" class="block text-sm font-medium text-gray-700">Max Dynamic Duration (seconds){{ ui.help_tip('Ceiling on how long a plugin may extend its own on-screen time (30–1800s).\nDefault: 180. Plugins with live content (e.g. a game in progress) can request extra time up to this limit.', 'Max Dynamic Duration') }}</label>
                         <input type="number"
                                id="max_dynamic_duration_seconds"
                                name="max_dynamic_duration_seconds"
@@ -375,7 +364,6 @@ <h4 class="text-sm font-medium text-gray-900 mb-3">Dynamic Duration</h4>
                                min="30"
                                max="1800"
                                class="form-control">
-                        <p class="mt-1 text-sm text-gray-600">Maximum time plugins can extend display duration (30-1800 seconds)</p>
                     </div>
                 </div>
             </div>
@@ -405,8 +393,8 @@ <h3 id="vegas_scroll_label" class="text-md font-medium text-gray-900">
             <!-- Vegas Settings (shown when enabled) -->
             <div id="vegas_scroll_settings" class="space-y-4" style="{% if not main_config.display.get('vegas_scroll', {}).get('enabled', false) %}display: none;{% endif %}">
                 <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-                    <div class="form-group">
-                        <label for="vegas_scroll_speed" class="block text-sm font-medium text-gray-700">Scroll Speed (pixels/second)</label>
+                    <div class="form-group" id="setting-display-vegas_scroll_speed" data-setting-key="display.vegas_scroll.scroll_speed">
+                        <label for="vegas_scroll_speed" class="block text-sm font-medium text-gray-700">Scroll Speed (pixels/second){{ ui.help_tip('How fast the Vegas ticker scrolls (10–200 px/s).\nDefault: 50. Higher is faster but harder to read.', 'Scroll Speed') }}</label>
                         <div class="flex items-center space-x-2">
                             <input type="range"
                                    id="vegas_scroll_speed"
@@ -418,11 +406,10 @@ <h3 id="vegas_scroll_label" class="text-md font-medium text-gray-900">
                                    class="flex-1">
                             <span id="vegas_scroll_speed_value" class="text-sm font-medium w-12">{{ main_config.display.get('vegas_scroll', {}).get('scroll_speed', 50) }}</span>
                         </div>
-                        <p class="mt-1 text-sm text-gray-600">Speed of the scrolling ticker (10-200 px/s)</p>
                     </div>
 
-                    <div class="form-group">
-                        <label for="vegas_separator_width" class="block text-sm font-medium text-gray-700">Separator Width (pixels)</label>
+                    <div class="form-group" id="setting-display-vegas_separator_width" data-setting-key="display.vegas_scroll.separator_width">
+                        <label for="vegas_separator_width" class="block text-sm font-medium text-gray-700">Separator Width (pixels){{ ui.help_tip('Blank gap inserted between each plugin block in the ticker (0–128 px).\nDefault: 32. Larger values make the boundary between plugins clearer.', 'Separator Width') }}</label>
                         <input type="number"
                                id="vegas_separator_width"
                                name="vegas_separator_width"
@@ -430,29 +417,26 @@ <h3 id="vegas_scroll_label" class="text-md font-medium text-gray-900">
                                min="0"
                                max="128"
                                class="form-control">
-                        <p class="mt-1 text-sm text-gray-600">Gap between plugin content blocks (0-128 px)</p>
                     </div>
                 </div>
 
                 <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-                    <div class="form-group">
-                        <label for="vegas_target_fps" class="block text-sm font-medium text-gray-700">Target FPS</label>
+                    <div class="form-group" id="setting-display-vegas_target_fps" data-setting-key="display.vegas_scroll.target_fps">
+                        <label for="vegas_target_fps" class="block text-sm font-medium text-gray-700">Target FPS{{ ui.help_tip('Frames per second the Vegas ticker aims to render.\nHigher = smoother scrolling but more CPU. Default: 125 (smoothest). Drop to 60/90 if the Pi runs hot.', 'Target FPS') }}</label>
                         <select id="vegas_target_fps" name="vegas_target_fps" class="form-control">
                             <option value="60" {% if main_config.display.get('vegas_scroll', {}).get('target_fps', 125) == 60 %}selected{% endif %}>60 FPS (Lower CPU)</option>
                             <option value="90" {% if main_config.display.get('vegas_scroll', {}).get('target_fps', 125) == 90 %}selected{% endif %}>90 FPS (Balanced)</option>
                             <option value="125" {% if main_config.display.get('vegas_scroll', {}).get('target_fps', 125) == 125 %}selected{% endif %}>125 FPS (Smoothest)</option>
                         </select>
-                        <p class="mt-1 text-sm text-gray-600">Higher FPS = smoother scroll, more CPU usage</p>
                     </div>
 
-                    <div class="form-group">
-                        <label for="vegas_buffer_ahead" class="block text-sm font-medium text-gray-700">Buffer Ahead</label>
+                    <div class="form-group" id="setting-display-vegas_buffer_ahead" data-setting-key="display.vegas_scroll.buffer_ahead">
+                        <label for="vegas_buffer_ahead" class="block text-sm font-medium text-gray-700">Buffer Ahead{{ ui.help_tip('How many upcoming plugins to pre-render so the scroll never stalls.\nDefault: 2 (recommended). More uses extra memory; less saves memory but risks hitches.', 'Buffer Ahead') }}</label>
                         <select id="vegas_buffer_ahead" name="vegas_buffer_ahead" class="form-control">
                             <option value="1" {% if main_config.display.get('vegas_scroll', {}).get('buffer_ahead', 2) == 1 %}selected{% endif %}>1 Plugin (Less memory)</option>
                             <option value="2" {% if main_config.display.get('vegas_scroll', {}).get('buffer_ahead', 2) == 2 %}selected{% endif %}>2 Plugins (Recommended)</option>
                             <option value="3" {% if main_config.display.get('vegas_scroll', {}).get('buffer_ahead', 2) == 3 %}selected{% endif %}>3 Plugins (More buffer)</option>
                         </select>
-                        <p class="mt-1 text-sm text-gray-600">How many plugins to pre-load ahead</p>
                     </div>
                 </div>
 
@@ -485,18 +469,17 @@ <h3 class="text-md font-medium text-gray-900">
             </div>
 
             <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-                <div class="form-group">
-                    <label for="sync_role" class="block text-sm font-medium text-gray-700">Role</label>
+                <div class="form-group" id="setting-display-sync_role" data-setting-key="sync.role">
+                    <label for="sync_role" class="block text-sm font-medium text-gray-700">Role{{ ui.help_tip('This unit\'s part in a two-display setup.\nStandalone = sync off. Set one Pi to Leader (drives the scroll) and the other to Follower (receives frames). Restart required after changing.', 'Sync Role') }}</label>
                     <select id="sync_role" name="sync_role" class="form-control" onchange="updateSyncUI()">
                         <option value="standalone" {% if main_config.get('sync', {}).get('role', 'standalone') == 'standalone' %}selected{% endif %}>Standalone (disabled)</option>
                         <option value="leader"     {% if main_config.get('sync', {}).get('role', 'standalone') == 'leader'     %}selected{% endif %}>Leader (drives scroll)</option>
                         <option value="follower"   {% if main_config.get('sync', {}).get('role', 'standalone') == 'follower'   %}selected{% endif %}>Follower (receives frames)</option>
                     </select>
-                    <p class="mt-1 text-sm text-gray-600">Set Leader on one Pi, Follower on the other. Restart required after changing.</p>
                 </div>
 
-                <div class="form-group">
-                    <label for="sync_port" class="block text-sm font-medium text-gray-700">UDP Port</label>
+                <div class="form-group" id="setting-display-sync_port" data-setting-key="sync.port">
+                    <label for="sync_port" class="block text-sm font-medium text-gray-700">UDP Port{{ ui.help_tip('UDP port the two displays use to exchange frames (1024–65535).\nDefault: 5765. Must match on both Pis. If the ufw firewall is active, allow it with: sudo ufw allow ' ~ main_config.get('sync', {}).get('port', 5765) ~ '/udp', 'Sync UDP Port') }}</label>
                     <input type="number"
                            id="sync_port"
                            name="sync_port"
@@ -504,19 +487,14 @@ <h3 class="text-md font-medium text-gray-900">
                            min="1024"
                            max="65535"
                            class="form-control">
-                    <p class="mt-1 text-sm text-gray-600">
-                        Must match on both Pis. If ufw is active:
-                        <code class="text-xs bg-gray-200 px-1 rounded">sudo ufw allow {{ main_config.get('sync', {}).get('port', 5765) }}/udp</code>
-                    </p>
                 </div>
 
-                <div class="form-group" id="sync_position_group" style="display:none">
-                    <label for="sync_follower_position" class="block text-sm font-medium text-gray-700">Position</label>
+                <div class="form-group" id="setting-display-sync_follower_position" data-setting-key="sync.follower_position" style="display:none">
+                    <label for="sync_follower_position" class="block text-sm font-medium text-gray-700">Position{{ ui.help_tip('Which side of the leader this follower display sits on.\nSets whether this unit shows the left or right half of the extended scroll.', 'Follower Position') }}</label>
                     <select id="sync_follower_position" name="sync_follower_position" class="form-control">
                         <option value="left"  {% if main_config.get('sync', {}).get('follower_position', 'left') == 'left'  %}selected{% endif %}>Left of leader</option>
                         <option value="right" {% if main_config.get('sync', {}).get('follower_position', 'left') == 'right' %}selected{% endif %}>Right of leader</option>
                     </select>
-                    <p class="mt-1 text-sm text-gray-600">Which side of the leader display this unit sits on.</p>
                 </div>
             </div>
 
@@ -795,7 +773,7 @@ <h3 class="text-md font-medium text-gray-900">
     function updateSyncUI() {
         const role = document.getElementById('sync_role').value;
         const bar = document.getElementById('sync_status_bar');
-        const posGroup = document.getElementById('sync_position_group');
+        const posGroup = document.getElementById('setting-display-sync_follower_position');
         if (role === 'standalone') {
             bar.classList.add('hidden');
             document.getElementById('sync_error_detail').classList.add('hidden');
diff --git a/web_interface/templates/v3/partials/durations.html b/web_interface/templates/v3/partials/durations.html
index e0833d992..0a1f05aa3 100644
--- a/web_interface/templates/v3/partials/durations.html
+++ b/web_interface/templates/v3/partials/durations.html
@@ -1,9 +1,12 @@
+{% import 'v3/partials/_macros.html' as ui %}
 <div class="bg-white rounded-lg shadow p-6">
     <div class="border-b border-gray-200 pb-4 mb-6">
         <h2 class="text-lg font-semibold text-gray-900">Display Durations</h2>
         <p class="mt-1 text-sm text-gray-600">Configure how long each screen is shown before switching. Values in seconds.</p>
     </div>
 
+    {{ ui.settings_filter() }}
+
     <form hx-post="/api/v3/config/main"
           hx-ext="json-enc"
           hx-headers='{"Content-Type": "application/json"}'
@@ -15,9 +18,9 @@ <h2 class="text-lg font-semibold text-gray-900">Display Durations</h2>
 
         <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
             {% for key, value in main_config.display.display_durations.items() %}
-            <div class="form-group">
+            <div class="form-group" id="setting-durations-{{ key }}" data-setting-key="display.display_durations.{{ key }}">
                 <label for="duration_{{ key }}" class="block text-sm font-medium text-gray-700">
-                    {{ key | replace('_', ' ') | title }}
+                    {{ key | replace('_', ' ') | title }}{{ ui.help_tip('How long the ' ~ (key | replace('_', ' ')) ~ ' screen stays on before rotating to the next one, in seconds.\nRange: 5–600. Currently ' ~ value ~ 's.', key | replace('_', ' ') | title) }}
                 </label>
                 <input type="number"
                        id="duration_{{ key }}"
@@ -26,7 +29,6 @@ <h2 class="text-lg font-semibold text-gray-900">Display Durations</h2>
                        min="5"
                        max="600"
                        class="form-control">
-                <p class="mt-1 text-sm text-gray-600">{{ value }} seconds</p>
             </div>
             {% endfor %}
         </div>
diff --git a/web_interface/templates/v3/partials/general.html b/web_interface/templates/v3/partials/general.html
index 780bf0f6d..60cc6f6cf 100644
--- a/web_interface/templates/v3/partials/general.html
+++ b/web_interface/templates/v3/partials/general.html
@@ -1,9 +1,12 @@
+{% import 'v3/partials/_macros.html' as ui %}
 <div class="bg-white rounded-lg shadow p-6">
     <div class="border-b border-gray-200 pb-4 mb-6">
         <h2 class="text-lg font-semibold text-gray-900">General Settings</h2>
         <p class="mt-1 text-sm text-gray-600">Configure general system settings and location information.</p>
     </div>
 
+    {{ ui.settings_filter() }}
+
     <form hx-post="/api/v3/config/main"
           hx-ext="json-enc"
           hx-headers='{"Content-Type": "application/json"}'
@@ -29,7 +32,7 @@ <h2 class="text-lg font-semibold text-gray-900">General Settings</h2>
           class="space-y-6">
 
         <!-- Web Display Autostart -->
-        <div class="form-group">
+        <div class="form-group" id="setting-general-web_display_autostart" data-setting-key="web_display_autostart">
             <label class="flex items-center">
                 <input type="checkbox"
                        name="web_display_autostart"
@@ -37,15 +40,14 @@ <h2 class="text-lg font-semibold text-gray-900">General Settings</h2>
                        {% if main_config.web_display_autostart %}checked{% endif %}
                        class="form-control h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded">
                 <span class="ml-2 text-sm font-medium text-gray-900">Web Display Autostart</span>
+                {{ ui.help_tip('Automatically start the web interface when the device boots.\nDefault: on. Turn off if you launch the web UI manually or run headless.', 'Web Display Autostart') }}
             </label>
-            <p class="mt-1 text-sm text-gray-600">Start the web interface on boot for easier access.</p>
         </div>
 
         <!-- Timezone -->
-        <div class="form-group">
-            <label for="timezone" class="block text-sm font-medium text-gray-700">Timezone</label>
+        <div class="form-group" id="setting-general-timezone" data-setting-key="timezone">
+            <label for="timezone" class="block text-sm font-medium text-gray-700">Timezone{{ ui.help_tip('Time zone used for clocks, schedules, and time-based content.\nChoose the zone where the display physically lives so on/off schedules fire at the correct local time.', 'Timezone') }}</label>
             <div id="timezone_container" class="mt-1"></div>
-            <p class="mt-1 text-sm text-gray-600">Select your timezone for time-based features and scheduling.</p>
         </div>
         <script>
         (function() {
@@ -80,8 +82,8 @@ <h2 class="text-lg font-semibold text-gray-900">General Settings</h2>
 
         <!-- Location Information -->
         <div class="grid grid-cols-1 md:grid-cols-3 xl:grid-cols-3 2xl:grid-cols-3 gap-4">
-            <div class="form-group">
-                <label for="city" class="block text-sm font-medium text-gray-700">City</label>
+            <div class="form-group" id="setting-general-city" data-setting-key="location.city">
+                <label for="city" class="block text-sm font-medium text-gray-700">City{{ ui.help_tip('City used for weather, sunrise/sunset, and other location-based content.\nExample: Dallas.', 'City') }}</label>
                 <input type="text"
                        id="city"
                        name="city"
@@ -89,8 +91,8 @@ <h2 class="text-lg font-semibold text-gray-900">General Settings</h2>
                        class="form-control">
             </div>
 
-            <div class="form-group">
-                <label for="state" class="block text-sm font-medium text-gray-700">State</label>
+            <div class="form-group" id="setting-general-state" data-setting-key="location.state">
+                <label for="state" class="block text-sm font-medium text-gray-700">State{{ ui.help_tip('State or region for your location.\nExample: Texas. Improves location-lookup accuracy.', 'State') }}</label>
                 <input type="text"
                        id="state"
                        name="state"
@@ -98,8 +100,8 @@ <h2 class="text-lg font-semibold text-gray-900">General Settings</h2>
                        class="form-control">
             </div>
 
-            <div class="form-group">
-                <label for="country" class="block text-sm font-medium text-gray-700">Country</label>
+            <div class="form-group" id="setting-general-country" data-setting-key="location.country">
+                <label for="country" class="block text-sm font-medium text-gray-700">Country{{ ui.help_tip('Country code or name for your location.\nExample: US. Used with City and State for weather and geolocation.', 'Country') }}</label>
                 <input type="text"
                        id="country"
                        name="country"
@@ -115,7 +117,7 @@ <h3 class="text-lg font-semibold text-gray-900 mb-4">Plugin System Settings</h3>
 
             <div class="space-y-4">
                 <!-- Auto Discover -->
-                <div class="form-group">
+                <div class="form-group" id="setting-general-auto_discover" data-setting-key="plugin_system.auto_discover">
                     <label class="flex items-center">
                         <input type="checkbox"
                                name="auto_discover"
@@ -123,12 +125,12 @@ <h3 class="text-lg font-semibold text-gray-900 mb-4">Plugin System Settings</h3>
                                {% if main_config.get('plugin_system', {}).get('auto_discover', True) %}checked{% endif %}
                                class="form-control h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded">
                         <span class="ml-2 text-sm font-medium text-gray-900">Auto Discover Plugins</span>
+                        {{ ui.help_tip('Scan the plugins directory for installed plugins each time the service starts.\nDefault: on. Leave on unless you manage plugins manually.', 'Auto Discover Plugins') }}
                     </label>
-                    <p class="mt-1 text-sm text-gray-600">Automatically discover plugins in the plugins directory on startup.</p>
                 </div>
 
                 <!-- Auto Load Enabled -->
-                <div class="form-group">
+                <div class="form-group" id="setting-general-auto_load_enabled" data-setting-key="plugin_system.auto_load_enabled">
                     <label class="flex items-center">
                         <input type="checkbox"
                                name="auto_load_enabled"
@@ -136,12 +138,12 @@ <h3 class="text-lg font-semibold text-gray-900 mb-4">Plugin System Settings</h3>
                                {% if main_config.get('plugin_system', {}).get('auto_load_enabled', True) %}checked{% endif %}
                                class="form-control h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded">
                         <span class="ml-2 text-sm font-medium text-gray-900">Auto Load Enabled Plugins</span>
+                        {{ ui.help_tip('Load every plugin marked enabled in the configuration at startup.\nDefault: on. Turn off to keep plugins installed but dormant.', 'Auto Load Enabled Plugins') }}
                     </label>
-                    <p class="mt-1 text-sm text-gray-600">Automatically load plugins that are enabled in configuration.</p>
                 </div>
 
                 <!-- Development Mode -->
-                <div class="form-group">
+                <div class="form-group" id="setting-general-development_mode" data-setting-key="plugin_system.development_mode">
                     <label class="flex items-center">
                         <input type="checkbox"
                                name="development_mode"
@@ -149,20 +151,19 @@ <h3 class="text-lg font-semibold text-gray-900 mb-4">Plugin System Settings</h3>
                                {% if main_config.get('plugin_system', {}).get('development_mode', False) %}checked{% endif %}
                                class="form-control h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded">
                         <span class="ml-2 text-sm font-medium text-gray-900">Development Mode</span>
+                        {{ ui.help_tip('Enable verbose logging and developer features for plugin debugging.\nDefault: off. Keep off for normal use — it increases log volume.', 'Development Mode') }}
                     </label>
-                    <p class="mt-1 text-gray-600 text-sm">Enable verbose logging and development features for plugin debugging.</p>
                 </div>
 
                 <!-- Plugins Directory -->
-                <div class="form-group">
-                    <label for="plugins_directory" class="block text-sm font-medium text-gray-700">Plugins Directory</label>
+                <div class="form-group" id="setting-general-plugins_directory" data-setting-key="plugin_system.plugins_directory">
+                    <label for="plugins_directory" class="block text-sm font-medium text-gray-700">Plugins Directory{{ ui.help_tip('Folder (relative to the project root) where plugins are stored.\nDefault: plugin-repos. Only change this if you keep plugins in a custom location.', 'Plugins Directory') }}</label>
                     <input type="text"
                            id="plugins_directory"
                            name="plugins_directory"
                            value="{{ main_config.get('plugin_system', {}).get('plugins_directory', 'plugin-repos') }}"
                            placeholder="plugin-repos"
                            class="form-control">
-                    <p class="mt-1 text-sm text-gray-600">Directory where plugins are stored (relative to project root).</p>
                 </div>
             </div>
         </div>
diff --git a/web_interface/templates/v3/partials/plugin_config.html b/web_interface/templates/v3/partials/plugin_config.html
index d0857d49f..ad05d0812 100644
--- a/web_interface/templates/v3/partials/plugin_config.html
+++ b/web_interface/templates/v3/partials/plugin_config.html
@@ -1,6 +1,8 @@
 {# Plugin Configuration Partial - Server-side rendered form #}
 {# This template is loaded via HTMX when a plugin tab is clicked #}
 
+{% import 'v3/partials/_macros.html' as ui %}
+
 {# ===== MACROS FOR FORM FIELD GENERATION ===== #}
 
 {# Render a single form field based on schema type #}
@@ -18,9 +20,8 @@
         {% if obj_widget == 'schedule-picker' %}
             {# Schedule picker widget - renders enable/mode/times UI #}
             {% set obj_value = value if value is not none else {} %}
-            <div class="form-group mb-4">
-                <label class="block text-sm font-medium text-gray-700 mb-1">{{ label }}</label>
-                {% if description %}<p class="text-sm text-gray-500 mb-2">{{ description }}</p>{% endif %}
+            <div class="form-group mb-4" id="setting-{{ field_id }}" data-setting-key="{{ full_key }}">
+                <label class="block text-sm font-medium text-gray-700 mb-1">{{ label }}{{ ui.help_tip(description, label) }}</label>
                 <div id="{{ field_id }}_container" class="schedule-picker-container mt-1"></div>
                 <input type="hidden" id="{{ field_id }}_data" name="{{ full_key }}" value='{{ (obj_value|tojson|safe)|replace("'", "&#39;") }}'>
             </div>
@@ -46,9 +47,8 @@
         {% elif obj_widget == 'time-range' %}
             {# Time range widget - renders start/end time inputs #}
             {% set obj_value = value if value is not none else {} %}
-            <div class="form-group mb-4">
-                <label class="block text-sm font-medium text-gray-700 mb-1">{{ label }}</label>
-                {% if description %}<p class="text-sm text-gray-500 mb-2">{{ description }}</p>{% endif %}
+            <div class="form-group mb-4" id="setting-{{ field_id }}" data-setting-key="{{ full_key }}">
+                <label class="block text-sm font-medium text-gray-700 mb-1">{{ label }}{{ ui.help_tip(description, label) }}</label>
                 <div id="{{ field_id }}_container" class="time-range-container mt-1"></div>
                 <input type="hidden" id="{{ field_id }}_data" name="{{ full_key }}" value='{{ (obj_value|tojson|safe)|replace("'", "&#39;") }}'>
             </div>
@@ -75,15 +75,11 @@
             {{ render_nested_section(key, prop, value, prefix, plugin_id) }}
         {% endif %}
     {% else %}
-        <div class="form-group mb-4">
+        <div class="form-group mb-4" id="setting-{{ field_id }}" data-setting-key="{{ full_key }}">
             <label for="{{ field_id }}" class="block text-sm font-medium text-gray-700 mb-1">
-                {{ label }}
+                {{ label }}{{ ui.help_tip(description, label) }}
             </label>
-            
-            {% if description %}
-            <p class="text-sm text-gray-500 mb-2">{{ description }}</p>
-            {% endif %}
-            
+
             {# Boolean - check for widget first #}
             {% if field_type == 'boolean' %}
             {% set bool_widget = prop.get('x-widget') or prop.get('x_widget') %}
diff --git a/web_interface/templates/v3/partials/schedule.html b/web_interface/templates/v3/partials/schedule.html
index 839f6fa10..e949cd7c6 100644
--- a/web_interface/templates/v3/partials/schedule.html
+++ b/web_interface/templates/v3/partials/schedule.html
@@ -1,9 +1,12 @@
+{% import 'v3/partials/_macros.html' as ui %}
 <div class="bg-white rounded-lg shadow p-6">
     <div class="border-b border-gray-200 pb-4 mb-6">
         <h2 class="text-lg font-semibold text-gray-900">Schedule Settings</h2>
         <p class="mt-1 text-sm text-gray-600">Configure when the LED matrix display should be active. You can set global hours or customize times for each day of the week.</p>
     </div>
 
+    {{ ui.settings_filter() }}
+
     <form id="schedule_form"
           hx-post="/api/v3/config/schedule"
           hx-ext="json-enc"
@@ -42,9 +45,9 @@ <h2 class="text-lg font-semibold text-gray-900">Dim Schedule Settings</h2>
           class="space-y-6">
 
         <!-- Dim Brightness Level -->
-        <div class="bg-gray-50 rounded-lg p-4 mb-4">
+        <div class="form-group bg-gray-50 rounded-lg p-4 mb-4" id="setting-schedule-dim_brightness" data-setting-key="dim_schedule.dim_brightness">
             <label for="dim_brightness" class="block text-sm font-medium text-gray-700 mb-2">
-                Dim Brightness Level
+                Dim Brightness Level{{ ui.help_tip('Brightness the display drops to during dim hours (0–100%).\nApplies only while the display is on. Your normal brightness is currently ' ~ normal_brightness ~ '%.', 'Dim Brightness Level') }}
             </label>
             <div class="flex items-center space-x-4">
                 <input type="range"
@@ -59,7 +62,6 @@ <h2 class="text-lg font-semibold text-gray-900">Dim Schedule Settings</h2>
                     {{ dim_schedule_config.dim_brightness | default(30) }}%
                 </span>
             </div>
-            <p class="mt-1 text-xs text-gray-500">Current normal brightness: {{ normal_brightness }}%</p>
         </div>
 
         <!-- Dim Schedule Picker Widget Container -->
diff --git a/web_interface/templates/v3/partials/wifi.html b/web_interface/templates/v3/partials/wifi.html
index ff1e78822..f6478aa35 100644
--- a/web_interface/templates/v3/partials/wifi.html
+++ b/web_interface/templates/v3/partials/wifi.html
@@ -1,3 +1,4 @@
+{% import 'v3/partials/_macros.html' as ui %}
 <div class="bg-white rounded-lg shadow p-6" x-data="wifiSetup()" x-init="init(); loadStatus()">
     <!-- Captive Portal Banner (shown when AP mode is active) -->
     <div x-show="status.ap_mode_active" 
@@ -23,6 +24,8 @@ <h2 class="text-lg font-semibold text-gray-900">
         <p class="mt-1 text-sm text-gray-600">Configure WiFi connection for your Raspberry Pi. Access point mode will automatically activate when no WiFi connection is detected.</p>
     </div>
 
+    {{ ui.settings_filter('Filter WiFi settings…') }}
+
     <!-- Current WiFi Status -->
     <div class="mb-6 p-4 bg-gray-50 rounded-lg">
         <h3 class="text-sm font-medium text-gray-900 mb-2">Current Status</h3>
@@ -73,9 +76,9 @@ <h3 class="text-sm font-medium text-gray-900 mb-2">Current Status</h3>
         <h3 class="text-sm font-medium text-gray-900 mb-4">Connect to WiFi Network</h3>
         
         <!-- Network Selection -->
-        <div class="form-group mb-4">
+        <div class="form-group mb-4" id="setting-wifi-ssid" data-setting-key="wifi.ssid">
             <label for="wifi-ssid" class="block text-sm font-medium text-gray-700 mb-2">
-                Step 1: Select Network
+                Step 1: Select Network{{ ui.help_tip('Choose the WiFi network to join.\nClick Scan to list nearby networks, or type the name manually below if it is hidden.', 'Select Network') }}
             </label>
             <div class="flex gap-2">
                 <select id="wifi-ssid" 
@@ -98,7 +101,6 @@ <h3 class="text-sm font-medium text-gray-900 mb-4">Connect to WiFi Network</h3>
                     <span class="ml-2">Scan</span>
                 </button>
             </div>
-            <p class="mt-1 text-sm text-gray-600">Scan for available networks or manually enter SSID below.</p>
             <!-- Show selected network -->
             <div x-show="selectedSSID" class="mt-2 p-2 bg-blue-50 border border-blue-200 rounded text-sm" x-cloak>
                 <i class="fas fa-check-circle text-blue-600 mr-2"></i>
@@ -107,9 +109,9 @@ <h3 class="text-sm font-medium text-gray-900 mb-4">Connect to WiFi Network</h3>
         </div>
 
         <!-- Manual SSID Entry -->
-        <div class="form-group mb-4">
+        <div class="form-group mb-4" id="setting-wifi-manual_ssid" data-setting-key="wifi.manual_ssid">
             <label for="manual-ssid" class="block text-sm font-medium text-gray-700 mb-2">
-                Or Enter SSID Manually
+                Or Enter SSID Manually{{ ui.help_tip('Type a network name by hand when it is hidden or not shown in the scan results.\nExact spelling and capitalization matter.', 'Enter SSID Manually') }}
             </label>
             <input type="text" 
                    id="manual-ssid"
@@ -120,19 +122,15 @@ <h3 class="text-sm font-medium text-gray-900 mb-4">Connect to WiFi Network</h3>
         </div>
 
         <!-- Password -->
-        <div class="form-group mb-4">
+        <div class="form-group mb-4" id="setting-wifi-password" data-setting-key="wifi.password">
             <label for="wifi-password" class="block text-sm font-medium text-gray-700 mb-2">
-                Step 2: Enter Password
+                Step 2: Enter Password{{ ui.help_tip('Password for the selected network.\nLeave empty if the network is open (no password required).', 'WiFi Password') }}
             </label>
-            <input type="password" 
+            <input type="password"
                    id="wifi-password"
                    x-model="password"
                    placeholder="Enter password (leave empty for open networks)"
                    class="form-control">
-            <p class="mt-1 text-sm text-gray-600">
-                <i class="fas fa-info-circle mr-1"></i>
-                Enter the WiFi password. Leave empty if the network is open (no password required).
-            </p>
         </div>
 
         <!-- Connect Button -->
@@ -154,14 +152,10 @@ <h3 class="text-sm font-medium text-gray-900 mb-4">Access Point Mode</h3>
         </p>
         
         <!-- Auto-Enable Toggle -->
-        <div class="mb-4 p-4 bg-gray-50 rounded-lg border border-gray-200">
+        <div class="form-group mb-4 p-4 bg-gray-50 rounded-lg border border-gray-200" id="setting-wifi-auto_enable_ap_mode" data-setting-key="wifi.auto_enable_ap_mode">
             <div class="flex items-start justify-between gap-4">
                 <div class="flex-1">
-                    <label class="text-sm font-medium text-gray-900 block mb-1">Auto-Enable AP Mode</label>
-                    <p class="text-xs text-gray-600">
-                        When enabled, AP mode will automatically activate when both WiFi and Ethernet are disconnected.
-                        When disabled, AP mode must be manually enabled.
-                    </p>
+                    <label class="text-sm font-medium text-gray-900 block mb-1">Auto-Enable AP Mode{{ ui.help_tip('Automatically start access-point mode when both WiFi and Ethernet are disconnected, so you can always reach the device to reconfigure it.\nDefault: on. When off, AP mode must be enabled manually.', 'Auto-Enable AP Mode') }}</label>
                 </div>
                 <div class="flex-shrink-0">
                     <button type="button"

From 22d3d8c1ffbf4338a8c7291484a5693e6cd5fe62 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 8 Jul 2026 15:13:26 +0000
Subject: [PATCH 2/9] Address Codacy static-analysis findings in settings JS
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refactor the two new modules to clear the flagged patterns without any
behavior change:

- Build the search dropdown with DOM nodes + textContent instead of
  innerHTML string concatenation, removing the XSS sinks and the manual
  escapeHtml helper it needed.
- Replace numeric index access (index[i], terms[j], opts[idx],
  currentResults[i]) with array iteration methods, NodeList.item(), and
  Array.prototype.at() to clear detect-object-injection.
- Use === via a shared termsMatch() helper, optional-catch binding, and
  drop a useless initial assignment.

Verified with ESLint (eslint:recommended + eslint-plugin-security) at zero
findings and re-ran the headless-Chromium behavior test (tooltip, per-tab
filter, global search navigation) — all green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz
---
 web_interface/static/v3/js/settings-search.js | 75 ++++++++++---------
 web_interface/static/v3/js/tooltips.js        |  6 +-
 2 files changed, 42 insertions(+), 39 deletions(-)

diff --git a/web_interface/static/v3/js/settings-search.js b/web_interface/static/v3/js/settings-search.js
index 914b680f8..4b0ff04cd 100644
--- a/web_interface/static/v3/js/settings-search.js
+++ b/web_interface/static/v3/js/settings-search.js
@@ -44,10 +44,9 @@
         };
     }
 
-    function escapeHtml(s) {
-        return String(s == null ? '' : s)
-            .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-            .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+    // True when every search term is present in the haystack.
+    function termsMatch(hay, terms) {
+        return terms.every(function (t) { return hay.indexOf(t) !== -1; });
     }
 
     function textOf(el) {
@@ -130,43 +129,54 @@
         q = q.trim().toLowerCase();
         if (!q) return [];
         var terms = q.split(/\s+/);
-        var index = window._settingsIndex || [];
         var out = [];
-        for (var i = 0; i < index.length && out.length < MAX_RESULTS; i++) {
-            var hay = index[i].hay;
-            var ok = true;
-            for (var j = 0; j < terms.length; j++) {
-                if (hay.indexOf(terms[j]) === -1) { ok = false; break; }
-            }
-            if (ok) out.push(index[i]);
-        }
+        (window._settingsIndex || []).some(function (entry) {
+            if (termsMatch(entry.hay, terms)) out.push(entry);
+            return out.length >= MAX_RESULTS; // stop once we have enough
+        });
         return out;
     }
 
+    function span(cls, text) {
+        var s = document.createElement('span');
+        s.className = cls;
+        s.textContent = text;
+        return s;
+    }
+
+    // Build the dropdown with DOM nodes + textContent (never innerHTML) so
+    // setting labels/help can never be interpreted as markup.
     function renderResults(results) {
         currentResults = results;
         activeIndex = -1;
+        resultsBox.textContent = '';
         if (!results.length) {
-            resultsBox.innerHTML = '<div class="ssr-empty">No settings found.</div>';
+            resultsBox.appendChild(span('ssr-empty', 'No settings found.'));
             openResults();
             return;
         }
-        var html = '';
         var lastTab = null;
         results.forEach(function (r, i) {
             if (r.tabLabel !== lastTab) {
-                html += '<div class="ssr-group">' + escapeHtml(r.tabLabel) + '</div>';
+                var group = document.createElement('div');
+                group.className = 'ssr-group';
+                group.textContent = r.tabLabel;
+                resultsBox.appendChild(group);
                 lastTab = r.tabLabel;
             }
             var sub = r.section ? (r.section + ' · ') : '';
             var snippet = r.help ? r.help.split('\n')[0] : '';
-            html += '<button type="button" class="ssr-option" role="option" id="ssr-' + i + '" data-idx="' + i + '">' +
-                '<span class="ssr-label">' + escapeHtml(r.label) + '</span>' +
-                (snippet ? '<span class="ssr-help">' + escapeHtml(sub + snippet) + '</span>'
-                         : (sub ? '<span class="ssr-help">' + escapeHtml(r.section) + '</span>' : '')) +
-                '</button>';
+            var opt = document.createElement('button');
+            opt.type = 'button';
+            opt.className = 'ssr-option';
+            opt.setAttribute('role', 'option');
+            opt.id = 'ssr-' + i;
+            opt.setAttribute('data-idx', String(i));
+            opt.appendChild(span('ssr-label', r.label));
+            var helpText = snippet ? (sub + snippet) : (sub ? r.section : '');
+            if (helpText) opt.appendChild(span('ssr-help', helpText));
+            resultsBox.appendChild(opt);
         });
-        resultsBox.innerHTML = html;
         openResults();
     }
 
@@ -188,7 +198,7 @@
         opts.forEach(function (o) { o.classList.remove('active'); });
         if (idx < 0 || idx >= opts.length) { activeIndex = -1; return; }
         activeIndex = idx;
-        var el = opts[idx];
+        var el = opts.item(idx);
         el.classList.add('active');
         el.scrollIntoView({ block: 'nearest' });
         input.setAttribute('aria-activedescendant', el.id);
@@ -314,12 +324,10 @@
                 e.preventDefault();
                 highlight(Math.max(activeIndex - 1, 0));
             } else if (e.key === 'Enter') {
-                if (activeIndex >= 0 && currentResults[activeIndex]) {
-                    e.preventDefault();
-                    navigateToSetting(currentResults[activeIndex]);
-                } else if (currentResults.length) {
+                var chosen = currentResults.at(activeIndex >= 0 ? activeIndex : 0);
+                if (chosen) {
                     e.preventDefault();
-                    navigateToSetting(currentResults[0]);
+                    navigateToSetting(chosen);
                 }
             } else if (e.key === 'Escape') {
                 closeResults();
@@ -333,7 +341,8 @@
             if (!opt) return;
             e.preventDefault();
             var idx = parseInt(opt.getAttribute('data-idx'), 10);
-            if (currentResults[idx]) navigateToSetting(currentResults[idx]);
+            var chosen = currentResults.at(idx);
+            if (chosen) navigateToSetting(chosen);
         });
 
         document.addEventListener('click', function (e) {
@@ -367,13 +376,7 @@
         var anyVisible = false;
 
         fields.forEach(function (fg) {
-            var show = true;
-            if (terms.length) {
-                var hay = fieldHay(fg);
-                for (var i = 0; i < terms.length; i++) {
-                    if (hay.indexOf(terms[i]) === -1) { show = false; break; }
-                }
-            }
+            var show = !terms.length || termsMatch(fieldHay(fg), terms);
             fg.style.display = show ? '' : 'none';
             if (show) anyVisible = true;
         });
diff --git a/web_interface/static/v3/js/tooltips.js b/web_interface/static/v3/js/tooltips.js
index bcebbb3cc..fd81bdd99 100644
--- a/web_interface/static/v3/js/tooltips.js
+++ b/web_interface/static/v3/js/tooltips.js
@@ -109,11 +109,11 @@
         if (!t) return;
         // Only auto-show on keyboard focus, so a mouse/touch focus does not
         // fight the click handler below.
-        var focusVisible = true;
+        var focusVisible;
         try {
             focusVisible = t.matches(':focus-visible');
-        } catch (err) {
-            focusVisible = true; // older browsers: fall back to always show
+        } catch { // older browsers without :focus-visible
+            focusVisible = true;
         }
         if (focusVisible) show(t);
     });

From 6e3f334e1090655f581d00dd04e764fb0e3c6eeb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 8 Jul 2026 15:19:53 +0000
Subject: [PATCH 3/9] Reduce complexity of revealAncestors in settings search

Extract isNodeHidden() and revealNode() helpers so revealAncestors drops
below the cyclomatic-complexity threshold. No behavior change; verified with
the headless-Chromium test.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz
---
 web_interface/static/v3/js/settings-search.js | 31 +++++++++++--------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/web_interface/static/v3/js/settings-search.js b/web_interface/static/v3/js/settings-search.js
index 4b0ff04cd..05401768f 100644
--- a/web_interface/static/v3/js/settings-search.js
+++ b/web_interface/static/v3/js/settings-search.js
@@ -241,24 +241,29 @@
         });
     }
 
+    function isNodeHidden(node) {
+        return node.classList.contains('hidden') ||
+            (node.style && node.style.display === 'none') ||
+            window.getComputedStyle(node).display === 'none';
+    }
+
+    function revealNode(node) {
+        // toggleSection handles the class, inline display, and chevron.
+        if (node.id && typeof window.toggleSection === 'function') {
+            window.toggleSection(node.id);
+        } else {
+            node.classList.remove('hidden');
+            node.style.display = 'block';
+        }
+    }
+
     // Reveal any collapsed nested section (from render_nested_section) so the
     // target field is actually visible before we scroll to it.
     function revealAncestors(el) {
         var node = el.parentElement;
         while (node && node !== document.body) {
-            if (node.classList && node.classList.contains('nested-content')) {
-                var hidden = node.classList.contains('hidden') ||
-                    (node.style && node.style.display === 'none') ||
-                    (window.getComputedStyle(node).display === 'none');
-                if (hidden) {
-                    // toggleSection handles the class, inline display, and chevron.
-                    if (node.id && typeof window.toggleSection === 'function') {
-                        window.toggleSection(node.id);
-                    } else {
-                        node.classList.remove('hidden');
-                        node.style.display = 'block';
-                    }
-                }
+            if (node.classList && node.classList.contains('nested-content') && isNodeHidden(node)) {
+                revealNode(node);
             }
             node = node.parentElement;
         }

From c0d785967b5592ec6206ddce5dd767ca16f75c24 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 8 Jul 2026 15:40:22 +0000
Subject: [PATCH 4/9] Resolve remaining Codacy findings in settings search

- Validate plugin ids against a strict allowlist (mirroring the server's
  _SAFE_PLUGIN_ID_RE) before they can appear in a fetch path, so the request
  URL is never built from unvalidated input (Codacy: user-controlled URL).
- Document that the fetched HTML is parsed into an inert document (scripts
  never run, never inserted into the live DOM) purely to read field text for
  the search index.
- Declare block-scoped locals with const instead of var where they were
  nested inside conditionals (Codacy: var not at function root).

No behavior change; re-verified with ESLint and the headless-Chromium test.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz
---
 web_interface/static/v3/js/settings-search.js | 29 +++++++++++++------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/web_interface/static/v3/js/settings-search.js b/web_interface/static/v3/js/settings-search.js
index 05401768f..e773b0cf6 100644
--- a/web_interface/static/v3/js/settings-search.js
+++ b/web_interface/static/v3/js/settings-search.js
@@ -35,6 +35,11 @@
 
     var MAX_RESULTS = 25;
 
+    // Plugin ids are constrained to this allowlist (mirrors the server's
+    // _SAFE_PLUGIN_ID_RE in pages_v3.py) before they can appear in a request
+    // path, so a fetched URL can never be influenced by untrusted input.
+    var PLUGIN_ID_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+
     function debounce(fn, ms) {
         var t;
         return function () {
@@ -88,10 +93,15 @@
     }
 
     function fetchAndScan(url, tab, tabLabel) {
+        // `url` is always one of our own same-origin settings partial paths
+        // (CORE_TABS literals or a plugin path built from an allowlisted id).
         return fetch(url, { headers: { 'X-Requested-With': 'settings-search' } })
             .then(function (r) { return r.ok ? r.text() : ''; })
             .then(function (html) {
                 if (!html) return [];
+                // Parsed into an inert document: scripts do not run and it is
+                // never inserted into the live DOM — we only read labels and
+                // tooltip text from it to build the search index.
                 var doc = new DOMParser().parseFromString(html, 'text/html');
                 return scanDoc(doc, tab, tabLabel);
             })
@@ -107,9 +117,10 @@
 
         var plugins = (window.installedPlugins || []);
         plugins.forEach(function (p) {
-            if (!p || !p.id) return;
-            jobs.push(fetchAndScan('/v3/partials/plugin-config/' + encodeURIComponent(p.id),
-                p.id, p.name || p.id));
+            // Skip ids that don't match the strict allowlist so the request
+            // path is always built from safe, validated components.
+            if (!p || !p.id || !PLUGIN_ID_RE.test(p.id)) return;
+            jobs.push(fetchAndScan('/v3/partials/plugin-config/' + p.id, p.id, p.name || p.id));
         });
 
         buildPromise = Promise.all(jobs).then(function (lists) {
@@ -158,7 +169,7 @@
         var lastTab = null;
         results.forEach(function (r, i) {
             if (r.tabLabel !== lastTab) {
-                var group = document.createElement('div');
+                const group = document.createElement('div');
                 group.className = 'ssr-group';
                 group.textContent = r.tabLabel;
                 resultsBox.appendChild(group);
@@ -329,7 +340,7 @@
                 e.preventDefault();
                 highlight(Math.max(activeIndex - 1, 0));
             } else if (e.key === 'Enter') {
-                var chosen = currentResults.at(activeIndex >= 0 ? activeIndex : 0);
+                const chosen = currentResults.at(activeIndex >= 0 ? activeIndex : 0);
                 if (chosen) {
                     e.preventDefault();
                     navigateToSetting(chosen);
@@ -345,8 +356,8 @@
             var opt = e.target.closest('.ssr-option');
             if (!opt) return;
             e.preventDefault();
-            var idx = parseInt(opt.getAttribute('data-idx'), 10);
-            var chosen = currentResults.at(idx);
+            const idx = parseInt(opt.getAttribute('data-idx'), 10);
+            const chosen = currentResults.at(idx);
             if (chosen) navigateToSetting(chosen);
         });
 
@@ -405,9 +416,9 @@
         });
 
         // Toggle the "no matches" note if the filter box provides one.
-        var wrap = scope.querySelector('.settings-filter-wrap');
+        const wrap = scope.querySelector('.settings-filter-wrap');
         if (wrap) {
-            var empty = wrap.querySelector('.settings-filter-empty');
+            const empty = wrap.querySelector('.settings-filter-empty');
             if (empty) empty.classList.toggle('hidden', !(terms.length && !anyVisible));
         }
     }

From a2fb3d180f66d7dc29df4023edf66b67ea34cf75 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 8 Jul 2026 16:11:11 +0000
Subject: [PATCH 5/9] Serve the settings search index from the server as JSON

Move index building off the client so there is no client-side HTML fetching
or DOM parsing (resolves Codacy's variable-fetch and DOMParser flags on the
read-only, same-origin index build).

- Add GET /v3/settings/search-index (pages_v3.py): renders the settings
  partials server-side and extracts each field's anchor id, key, label,
  tooltip, and section with a small stdlib HTMLParser, then caches the result
  keyed on the installed-plugin set. Parsing the rendered HTML keeps anchor
  ids identical to the live DOM, so the index cannot drift.
- settings-search.js: buildIndex() now does a single fetch of the literal
  endpoint + .json(); removed the per-partial fetch loop, DOMParser, scanDoc,
  CORE_TABS, and the plugin-id allowlist. Search, keyboard nav, navigation,
  and the per-tab filter are unchanged.

Net: fewer requests and no client-side HTML parsing. Verified with a new
endpoint test in test_web_settings_ui.py (12 pass) and the headless-Chromium
test (tooltip, filter, search navigate + flash all green).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz
---
 test/test_web_settings_ui.py                  |  25 +++
 web_interface/blueprints/pages_v3.py          | 160 +++++++++++++++++-
 web_interface/static/v3/js/settings-search.js |  98 ++---------
 3 files changed, 202 insertions(+), 81 deletions(-)

diff --git a/test/test_web_settings_ui.py b/test/test_web_settings_ui.py
index 657f5c54f..9ae4c1cb6 100644
--- a/test/test_web_settings_ui.py
+++ b/test/test_web_settings_ui.py
@@ -115,3 +115,28 @@ def test_display_tooltip_carries_rich_text(client):
     body = client.get("/v3/partials/display").get_data(as_text=True)
     assert 'id="setting-display-brightness"' in body
     assert "Recommended:" in body  # rich detail authored into a tooltip
+
+
+def test_search_index_endpoint(client):
+    """The server-built search index powers the global settings search."""
+    resp = client.get("/v3/settings/search-index")
+    assert resp.status_code == 200
+    data = resp.get_json()
+    assert isinstance(data, dict) and isinstance(data.get("fields"), list)
+    fields = data["fields"]
+    assert len(fields) >= 40, "expected the core settings fields to be indexed"
+
+    by_id = {f["anchorId"]: f for f in fields}
+    # Representative fields across tabs must be present with usable text.
+    for anchor in ("setting-general-timezone", "setting-display-brightness",
+                   "setting-wifi-password"):
+        assert anchor in by_id, f"{anchor} missing from search index"
+        entry = by_id[anchor]
+        assert entry["label"], f"{anchor} has no label"
+        assert entry["help"], f"{anchor} has no tooltip help"
+        assert entry["tab"] and entry["tabLabel"]
+
+    # Every entry must carry a non-empty label and a stable anchor id.
+    assert all(f["label"] and f["anchorId"].startswith("setting-") for f in fields)
+    # Section context is captured for grouped fields (e.g. Display hardware).
+    assert by_id["setting-display-brightness"]["section"] == "Hardware Configuration"
diff --git a/web_interface/blueprints/pages_v3.py b/web_interface/blueprints/pages_v3.py
index b011480a7..1966f7ea7 100644
--- a/web_interface/blueprints/pages_v3.py
+++ b/web_interface/blueprints/pages_v3.py
@@ -1,6 +1,7 @@
-from flask import Blueprint, render_template, flash
+from flask import Blueprint, render_template, flash, jsonify
 from jinja2 import TemplateNotFound
 from markupsafe import escape
+from html.parser import HTMLParser
 import json
 import logging
 import os
@@ -22,6 +23,114 @@
 
 pages_v3 = Blueprint('pages_v3', __name__)
 
+
+class _SettingsIndexParser(HTMLParser):
+    """Extract searchable settings fields from a rendered partial's HTML.
+
+    Captures one entry per ``<div class="form-group" id="setting-…">``: the
+    anchor id, ``data-setting-key``, the field's ``<label>`` text, the
+    ``.help-tip`` tooltip text (``data-tooltip``), and the nearest preceding
+    ``<h3>``/``<h4>`` section heading. Parsing the *rendered* HTML (rather than
+    the schema) guarantees the anchor ids match the live DOM exactly, so the
+    search index cannot drift from what users actually see.
+    """
+
+    def __init__(self, tab, tab_label):
+        super().__init__(convert_charrefs=True)
+        self.tab = tab
+        self.tab_label = tab_label
+        self.fields = []
+        self._section = ''
+        self._field = None
+        self._depth = 0            # open-div depth within the current field
+        self._in_label = False
+        self._label_parts = []
+        self._in_heading = False
+        self._heading_parts = []
+
+    def handle_starttag(self, tag, attrs):
+        a = {k: (v or '') for k, v in attrs}
+        classes = a.get('class', '').split()
+        # Section headings (only when not already inside a field)
+        if tag in ('h3', 'h4') and self._field is None:
+            self._in_heading = True
+            self._heading_parts = []
+        if tag == 'div':
+            fid = a.get('id', '')
+            if self._field is None and 'form-group' in classes and fid.startswith('setting-'):
+                self._field = {
+                    'anchorId': fid,
+                    'key': a.get('data-setting-key', '') or fid[len('setting-'):],
+                    'label': '',
+                    'help': '',
+                    'section': self._section,
+                    'tab': self.tab,
+                    'tabLabel': self.tab_label,
+                }
+                self._depth = 1
+                return
+            if self._field is not None:
+                self._depth += 1
+        if self._field is not None:
+            if tag == 'label' and not self._field['label']:
+                self._in_label = True
+                self._label_parts = []
+            if tag == 'button' and 'help-tip' in classes and not self._field['help']:
+                self._field['help'] = a.get('data-tooltip', '')
+
+    def handle_data(self, data):
+        if self._in_label:
+            self._label_parts.append(data)
+        elif self._in_heading:
+            self._heading_parts.append(data)
+
+    def handle_endtag(self, tag):
+        if tag in ('h3', 'h4') and self._in_heading:
+            self._in_heading = False
+            self._section = ' '.join(''.join(self._heading_parts).split()).strip()
+            return
+        if self._field is None:
+            return
+        if tag == 'label' and self._in_label:
+            self._in_label = False
+            self._field['label'] = ' '.join(''.join(self._label_parts).split()).strip()
+        elif tag == 'div':
+            self._depth -= 1
+            if self._depth <= 0:
+                if self._field['label']:
+                    self.fields.append(self._field)
+                self._field = None
+                self._depth = 0
+
+
+def _partial_html(loader):
+    """Run a partial loader and return its HTML string ('' on error)."""
+    try:
+        result = loader()
+    except Exception:
+        logger.warning("search-index: partial render failed", exc_info=True)
+        return ''
+    if isinstance(result, str):
+        return result
+    if isinstance(result, tuple):  # loaders return (msg, status) on error
+        return ''
+    try:
+        return result.get_data(as_text=True)
+    except Exception:
+        return ''
+
+
+def _extract_settings_fields(html, tab, tab_label):
+    parser = _SettingsIndexParser(tab, tab_label)
+    parser.feed(html)
+    return parser.fields
+
+
+# Cache the built index keyed on the installed-plugin set. Core labels/tooltips
+# are static template text, so only a change in installed plugins invalidates it.
+_SEARCH_INDEX_CACHE = {'sig': None, 'fields': None}
+
+
 @pages_v3.route('/')
 def index():
     """Main v3 interface page"""
@@ -111,6 +220,55 @@ def load_plugin_config_partial(plugin_id):
         return '<div class="text-red-500 p-4">Error loading plugin config; see logs for details</div>', 500
 
 
+@pages_v3.route('/settings/search-index')
+def settings_search_index():
+    """Return a flat JSON index of every searchable setting (core + plugin).
+
+    Powers the web UI's global settings search. Built by rendering the settings
+    partials server-side and extracting field metadata, then cached per
+    installed-plugin set so it is off the display's hot path.
+    """
+    # Core settings tabs: (activeTab value, human label, loader).
+    core_tabs = [
+        ('general', 'General', _load_general_partial),
+        ('display', 'Display', _load_display_partial),
+        ('schedule', 'Schedule', _load_schedule_partial),
+        ('wifi', 'WiFi', _load_wifi_partial),
+    ]
+    try:
+        plugin_ids = []
+        if pages_v3.plugin_manager:
+            try:
+                pages_v3.plugin_manager.discover_plugins()
+                plugin_ids = sorted(
+                    pi.get('id') for pi in pages_v3.plugin_manager.get_all_plugin_info()
+                    if pi.get('id')
+                )
+            except Exception:
+                logger.warning("search-index: could not enumerate plugins", exc_info=True)
+
+        sig = tuple(plugin_ids)
+        if _SEARCH_INDEX_CACHE['sig'] == sig and _SEARCH_INDEX_CACHE['fields'] is not None:
+            return jsonify({'fields': _SEARCH_INDEX_CACHE['fields']})
+
+        fields = []
+        for tab, label, loader in core_tabs:
+            fields.extend(_extract_settings_fields(_partial_html(loader), tab, label))
+
+        for pid in plugin_ids:
+            info = pages_v3.plugin_manager.get_plugin_info(pid) or {}
+            label = info.get('name', pid)
+            html = _partial_html(lambda pid=pid: _load_plugin_config_partial(pid))
+            fields.extend(_extract_settings_fields(html, pid, label))
+
+        _SEARCH_INDEX_CACHE['sig'] = sig
+        _SEARCH_INDEX_CACHE['fields'] = fields
+        return jsonify({'fields': fields})
+    except Exception:
+        logger.error("Error building settings search index", exc_info=True)
+        return jsonify({'fields': []}), 500
+
+
 @pages_v3.route('/plugin-ui/<plugin_id>/web-ui/<path:filename>')
 def serve_plugin_web_ui(plugin_id, filename):
     """Serve a plugin's web_ui/ HTML fragment as a standalone page.
diff --git a/web_interface/static/v3/js/settings-search.js b/web_interface/static/v3/js/settings-search.js
index e773b0cf6..615850761 100644
--- a/web_interface/static/v3/js/settings-search.js
+++ b/web_interface/static/v3/js/settings-search.js
@@ -22,24 +22,8 @@
     if (window._settingsSearchInit) return;
     window._settingsSearchInit = true;
 
-    // Core settings tabs to index. Only tabs that contain real settings fields
-    // (a .form-group[id^="setting-"]) are listed. Operational/action tabs
-    // (overview, logs, history, cache, tools, fonts, backup/restore, raw config
-    // editor, plugin store) have nothing to navigate to and are excluded.
-    var CORE_TABS = [
-        { tab: 'general', label: 'General', url: '/v3/partials/general' },
-        { tab: 'display', label: 'Display', url: '/v3/partials/display' },
-        { tab: 'schedule', label: 'Schedule', url: '/v3/partials/schedule' },
-        { tab: 'wifi', label: 'WiFi', url: '/v3/partials/wifi' }
-    ];
-
     var MAX_RESULTS = 25;
 
-    // Plugin ids are constrained to this allowlist (mirrors the server's
-    // _SAFE_PLUGIN_ID_RE in pages_v3.py) before they can appear in a request
-    // path, so a fetched URL can never be influenced by untrusted input.
-    var PLUGIN_ID_RE = /^[a-zA-Z0-9_-]{1,64}$/;
-
     function debounce(fn, ms) {
         var t;
         return function () {
@@ -60,75 +44,29 @@
 
     // --- Index building -------------------------------------------------------
 
-    // Extract one index entry per settings field from a parsed document.
-    function scanDoc(doc, tab, tabLabel) {
-        var entries = [];
-        var nodes = doc.querySelectorAll('h2, h3, h4, .form-group[id^="setting-"]');
-        var section = '';
-        nodes.forEach(function (node) {
-            var tag = node.tagName.toLowerCase();
-            if (tag === 'h3' || tag === 'h4') {
-                section = textOf(node);
-                return;
-            }
-            if (tag === 'h2') { section = ''; return; }
-            // A settings .form-group
-            var labelEl = node.querySelector('label');
-            var label = textOf(labelEl) || node.id.replace(/^setting-/, '');
-            var tipEl = node.querySelector('.help-tip');
-            var help = tipEl ? (tipEl.getAttribute('data-tooltip') || '') : '';
-            var key = node.getAttribute('data-setting-key') || node.id.replace(/^setting-/, '');
-            entries.push({
-                tab: tab,
-                tabLabel: tabLabel,
-                section: section,
-                key: key,
-                label: label,
-                help: help,
-                anchorId: node.id,
-                hay: [label, help, key, tabLabel, section].join(' ').toLowerCase()
-            });
-        });
-        return entries;
-    }
-
-    function fetchAndScan(url, tab, tabLabel) {
-        // `url` is always one of our own same-origin settings partial paths
-        // (CORE_TABS literals or a plugin path built from an allowlisted id).
-        return fetch(url, { headers: { 'X-Requested-With': 'settings-search' } })
-            .then(function (r) { return r.ok ? r.text() : ''; })
-            .then(function (html) {
-                if (!html) return [];
-                // Parsed into an inert document: scripts do not run and it is
-                // never inserted into the live DOM — we only read labels and
-                // tooltip text from it to build the search index.
-                var doc = new DOMParser().parseFromString(html, 'text/html');
-                return scanDoc(doc, tab, tabLabel);
-            })
-            .catch(function () { return []; });
-    }
-
     var buildPromise = null;
+
+    // Fetch the prebuilt index from the server (one literal-URL JSON request)
+    // and cache it for the session. Each entry gets a lowercased `hay` haystack
+    // for matching. The server owns which tabs/plugins are included.
     function buildIndex(force) {
         if (window._settingsIndex && !force) return Promise.resolve(window._settingsIndex);
         if (buildPromise && !force) return buildPromise;
 
-        var jobs = CORE_TABS.map(function (t) { return fetchAndScan(t.url, t.tab, t.label); });
-
-        var plugins = (window.installedPlugins || []);
-        plugins.forEach(function (p) {
-            // Skip ids that don't match the strict allowlist so the request
-            // path is always built from safe, validated components.
-            if (!p || !p.id || !PLUGIN_ID_RE.test(p.id)) return;
-            jobs.push(fetchAndScan('/v3/partials/plugin-config/' + p.id, p.id, p.name || p.id));
-        });
-
-        buildPromise = Promise.all(jobs).then(function (lists) {
-            var index = [];
-            lists.forEach(function (l) { index = index.concat(l); });
-            window._settingsIndex = index;
-            return index;
-        });
+        buildPromise = fetch('/v3/settings/search-index', { headers: { 'X-Requested-With': 'settings-search' } })
+            .then(function (r) { return r.ok ? r.json() : { fields: [] }; })
+            .then(function (data) {
+                var fields = (data && data.fields) || [];
+                fields.forEach(function (f) {
+                    f.hay = [f.label, f.help, f.key, f.tabLabel, f.section].join(' ').toLowerCase();
+                });
+                window._settingsIndex = fields;
+                return fields;
+            })
+            .catch(function () {
+                window._settingsIndex = [];
+                return window._settingsIndex;
+            });
         return buildPromise;
     }
 

From 497a103d8cfebfe8b60bf12a8fcf79f24b3d58e8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 8 Jul 2026 17:20:03 +0000
Subject: [PATCH 6/9] Address CodeRabbit review on settings search/tooltips

- pages_v3: include Durations tab in the search index so
  setting-durations-* fields are actually indexed
- test_web_settings_ui: assert setting-durations-clock is present in
  the search-index endpoint response
- settings-search.js: on index fetch failure, reset buildPromise
  instead of caching an empty (truthy) index so search can retry
- settings-search.js: filterScope returns null (not document) when no
  tab container matches, and the caller guards, so the per-tab filter
  can't hide fields across unrelated tabs
- settings-search.js: refresh the stale header comment to describe the
  server-side JSON index flow
- app.css: cap #settings-search-results height with overflow-y so the
  dropdown scrolls instead of overflowing small screens

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz
---
 test/test_web_settings_ui.py                  |  2 +-
 web_interface/blueprints/pages_v3.py          |  1 +
 web_interface/static/v3/app.css               |  2 ++
 web_interface/static/v3/js/settings-search.js | 20 ++++++++++++-------
 4 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/test/test_web_settings_ui.py b/test/test_web_settings_ui.py
index 9ae4c1cb6..89abb7785 100644
--- a/test/test_web_settings_ui.py
+++ b/test/test_web_settings_ui.py
@@ -129,7 +129,7 @@ def test_search_index_endpoint(client):
     by_id = {f["anchorId"]: f for f in fields}
     # Representative fields across tabs must be present with usable text.
     for anchor in ("setting-general-timezone", "setting-display-brightness",
-                   "setting-wifi-password"):
+                   "setting-wifi-password", "setting-durations-clock"):
         assert anchor in by_id, f"{anchor} missing from search index"
         entry = by_id[anchor]
         assert entry["label"], f"{anchor} has no label"
diff --git a/web_interface/blueprints/pages_v3.py b/web_interface/blueprints/pages_v3.py
index 1966f7ea7..8c3c1bbc6 100644
--- a/web_interface/blueprints/pages_v3.py
+++ b/web_interface/blueprints/pages_v3.py
@@ -232,6 +232,7 @@ def settings_search_index():
     core_tabs = [
         ('general', 'General', _load_general_partial),
         ('display', 'Display', _load_display_partial),
+        ('durations', 'Durations', _load_durations_partial),
         ('schedule', 'Schedule', _load_schedule_partial),
         ('wifi', 'WiFi', _load_wifi_partial),
     ]
diff --git a/web_interface/static/v3/app.css b/web_interface/static/v3/app.css
index 66870db4f..a1342955d 100644
--- a/web_interface/static/v3/app.css
+++ b/web_interface/static/v3/app.css
@@ -838,6 +838,8 @@ button.bg-white {
     box-shadow: var(--shadow-lg);
     z-index: 50;
     padding: 0.25rem;
+    max-height: min(60vh, 24rem);
+    overflow-y: auto;
 }
 
 .ssr-group {
diff --git a/web_interface/static/v3/js/settings-search.js b/web_interface/static/v3/js/settings-search.js
index 615850761..397902ffd 100644
--- a/web_interface/static/v3/js/settings-search.js
+++ b/web_interface/static/v3/js/settings-search.js
@@ -6,15 +6,16 @@
  * .help-tip[data-tooltip]), so it can never drift from what is rendered:
  *
  *   1. Global search (header box): finds settings across ALL tabs, even ones
- *      not yet opened, by fetching each tab's partial once and scanning it.
+ *      not yet opened, by fetching a single server-side JSON index
+ *      (/v3/settings/search-index) built from all rendered partials.
  *      Clicking a result switches to the tab, waits for the field to load,
  *      then scrolls to and flashes it.
  *   2. Per-tab filter (the .settings-filter box under a partial title):
  *      hides non-matching fields on the current tab. Delegated, so it keeps
  *      working across HTMX swaps.
  *
- * No backend endpoint is required — plugins are enumerated from
- * window.installedPlugins and their config partials are fetched the same way.
+ * The server owns index generation (including plugin enumeration) and caches
+ * it per installed-plugin set, so the client makes exactly one JSON request.
  */
 (function () {
     'use strict';
@@ -64,8 +65,10 @@
                 return fields;
             })
             .catch(function () {
-                window._settingsIndex = [];
-                return window._settingsIndex;
+                // Don't cache the failure: clear the in-flight promise so a
+                // later call can retry after a transient fetch error.
+                buildPromise = null;
+                return [];
             });
         return buildPromise;
     }
@@ -309,10 +312,12 @@
     // --- Per-tab filter (delegated) -------------------------------------------
 
     function filterScope(input) {
+        // Return the nearest tab/content container, or null — never `document`,
+        // which would let the filter hide setting fields across unrelated tabs.
         return input.closest('.plugin-config-tab') ||
                input.closest('[id$="-content"]') ||
                input.closest('.bg-white') ||
-               document;
+               null;
     }
 
     function fieldHay(fg) {
@@ -364,7 +369,8 @@
     document.addEventListener('input', function (e) {
         var box = e.target.closest ? e.target.closest('.settings-filter') : null;
         if (!box) return;
-        applyTabFilter(filterScope(box), box.value);
+        var scope = filterScope(box);
+        if (scope) applyTabFilter(scope, box.value);
     });
 
     // --- Boot -----------------------------------------------------------------

From e79a07f25989b5a8e2565373453d52db18e4086a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 8 Jul 2026 20:26:04 +0000
Subject: [PATCH 7/9] Fix stuck search dropdown; add plugin-tab nested-settings
 filter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Global search:
- Close the results dropdown on input blur (guarded, with a short delay)
  so it reliably dismisses when focus leaves — previously it could linger
  because the only outside-close was a document click that Alpine/HTMX
  handlers can swallow.
- Clear the query text after navigating to a result so refocusing the box
  doesn't re-open stale results.
- Also dismiss on htmx:afterSwap (tab changes / navigation).

Per-tab filter (now on plugin tabs too):
- Render the shared settings_filter box in the plugin Configuration panel.
  It auto-wires: the delegated input handler and filterScope already target
  .plugin-config-tab.
- Teach applyTabFilter to reveal matches inside collapsed nested sections
  (render_nested_section defaults them shut), hide nested-section wrappers
  with no matches, and restore the original collapsed layout when cleared
  (only re-collapsing sections the filter itself opened).
- Count a visible nested-section as content for its parent heading so the
  heading isn't hidden while a subsection below still has matches.

Adds a plugin-config render test (filter box + nested anchors + tooltips).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz
---
 test/test_web_settings_ui.py                  | 42 +++++++++++
 web_interface/static/v3/js/settings-search.js | 75 ++++++++++++++++++-
 .../templates/v3/partials/plugin_config.html  |  1 +
 3 files changed, 115 insertions(+), 3 deletions(-)

diff --git a/test/test_web_settings_ui.py b/test/test_web_settings_ui.py
index 89abb7785..d68524478 100644
--- a/test/test_web_settings_ui.py
+++ b/test/test_web_settings_ui.py
@@ -140,3 +140,45 @@ def test_search_index_endpoint(client):
     assert all(f["label"] and f["anchorId"].startswith("setting-") for f in fields)
     # Section context is captured for grouped fields (e.g. Display hardware).
     assert by_id["setting-display-brightness"]["section"] == "Hardware Configuration"
+
+
+def test_plugin_config_partial_has_filter_and_nested_anchors():
+    """Plugin config tabs expose the per-tab filter and anchor nested fields.
+
+    The client fixture has no installed plugins, so render the partial directly
+    with a schema that includes a nested section (render_nested_section).
+    """
+    from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+    env = Environment(
+        loader=FileSystemLoader(str(PROJECT_ROOT / "web_interface" / "templates")),
+        autoescape=select_autoescape(["html"]),
+    )
+    plugin = {
+        "id": "demo-plugin", "name": "Demo Plugin", "description": "A demo",
+        "enabled": True, "author": "me", "version": "1.0.0",
+    }
+    schema = {
+        "type": "object",
+        "properties": {
+            "title_text": {"type": "string", "title": "Title Text",
+                           "description": "The heading."},
+            "advanced": {
+                "type": "object", "title": "Advanced Options",
+                "description": "Nested options.",
+                "properties": {
+                    "scroll_speed": {"type": "integer", "title": "Scroll Speed",
+                                     "description": "Pixels per second."},
+                },
+            },
+        },
+    }
+    config = {"title_text": "Hi", "advanced": {"scroll_speed": 50}}
+    html = env.get_template("v3/partials/plugin_config.html").render(
+        plugin=plugin, schema=schema, config=config
+    )
+
+    assert 'class="settings-filter' in html, "plugin config: per-tab filter box missing"
+    assert "nested-content" in html, "plugin config: nested section not rendered"
+    assert 'id="setting-' in html, "plugin config: no search anchors rendered"
+    assert 'class="help-tip"' in html, "plugin config: no tooltips rendered"
diff --git a/web_interface/static/v3/js/settings-search.js b/web_interface/static/v3/js/settings-search.js
index 397902ffd..9a0031680 100644
--- a/web_interface/static/v3/js/settings-search.js
+++ b/web_interface/static/v3/js/settings-search.js
@@ -209,6 +209,18 @@
         }
     }
 
+    // Re-collapse a nested section the filter previously opened. toggleSection is
+    // state-based, so only toggle while the node is actually visible.
+    function collapseNode(node) {
+        if (isNodeHidden(node)) return;
+        if (node.id && typeof window.toggleSection === 'function') {
+            window.toggleSection(node.id);
+        } else {
+            node.classList.add('hidden');
+            node.style.display = 'none';
+        }
+    }
+
     // Reveal any collapsed nested section (from render_nested_section) so the
     // target field is actually visible before we scroll to it.
     function revealAncestors(el) {
@@ -221,6 +233,19 @@
         }
     }
 
+    // Like revealAncestors, but tags each section we open so the per-tab filter
+    // can restore the original collapsed layout once the query is cleared.
+    function expandNestedFor(el) {
+        var node = el.parentElement;
+        while (node && node !== document.body) {
+            if (node.classList && node.classList.contains('nested-content') && isNodeHidden(node)) {
+                revealNode(node);
+                node.dataset.filterExpanded = '1';
+            }
+            node = node.parentElement;
+        }
+    }
+
     function flash(el) {
         el.classList.remove('setting-flash');
         // force reflow so re-adding the class restarts the animation
@@ -232,6 +257,8 @@
 
     function navigateToSetting(entry) {
         closeResults();
+        // Clear the box so it doesn't re-open stale results when refocused.
+        if (input) input.value = '';
         setActiveTab(entry.tab);
         waitForElement(entry.anchorId, 6000).then(function (el) {
             if (!el) return;
@@ -307,6 +334,20 @@
             if (e.target === input || resultsBox.contains(e.target)) return;
             closeResults();
         });
+
+        // Reliable dismiss: close shortly after focus leaves the box. Result
+        // selection uses mousedown + preventDefault (focus stays on the input),
+        // so this never fires on a result click; the guard covers focus landing
+        // in the results list (e.g. dragging its scrollbar).
+        input.addEventListener('blur', function () {
+            setTimeout(function () {
+                if (resultsBox && resultsBox.contains(document.activeElement)) return;
+                closeResults();
+            }, 120);
+        });
+
+        // A tab swap (including our own search navigation) should dismiss it.
+        document.body.addEventListener('htmx:afterSwap', closeResults);
     }
 
     // --- Per-tab filter (delegated) -------------------------------------------
@@ -337,11 +378,36 @@
         fields.forEach(function (fg) {
             var show = !terms.length || termsMatch(fieldHay(fg), terms);
             fg.style.display = show ? '' : 'none';
-            if (show) anyVisible = true;
+            if (show) {
+                anyVisible = true;
+                // Expand any collapsed nested section holding this match so it
+                // is actually visible (plugin tabs default their sections shut).
+                if (terms.length) expandNestedFor(fg);
+            }
         });
 
-        // Hide section headings whose settings all got filtered out.
-        var nodes = scope.querySelectorAll('h3, h4, .form-group');
+        if (!terms.length) {
+            // Filter cleared: restore the sections we opened and un-hide every
+            // nested-section wrapper, leaving user-expanded sections untouched.
+            scope.querySelectorAll('.nested-content[data-filter-expanded]').forEach(function (nc) {
+                collapseNode(nc);
+                delete nc.dataset.filterExpanded;
+            });
+            scope.querySelectorAll('.nested-section').forEach(function (ns) { ns.style.display = ''; });
+        } else {
+            // Hide nested-section wrappers whose fields all filtered out.
+            scope.querySelectorAll('.nested-section').forEach(function (ns) {
+                var secFields = ns.querySelectorAll('.form-group[id^="setting-"]');
+                var visible = 0;
+                secFields.forEach(function (f) { if (f.style.display !== 'none') visible++; });
+                ns.style.display = (secFields.length > 0 && visible === 0) ? 'none' : '';
+            });
+        }
+
+        // Hide section headings whose settings all got filtered out. A visible
+        // nested-section (plugin tabs) counts as content for its parent heading,
+        // so a heading isn't hidden while a subsection below it still has matches.
+        var nodes = scope.querySelectorAll('h3, h4, .form-group, .nested-section');
         var headings = [];
         var current = null;
         nodes.forEach(function (node) {
@@ -351,6 +417,9 @@
             } else if (current && node.matches('.form-group[id^="setting-"]')) {
                 current.total++;
                 if (node.style.display !== 'none') current.visible++;
+            } else if (current && node.classList.contains('nested-section')) {
+                current.total++;
+                if (node.style.display !== 'none') current.visible++;
             }
         });
         headings.forEach(function (h) {
diff --git a/web_interface/templates/v3/partials/plugin_config.html b/web_interface/templates/v3/partials/plugin_config.html
index ad05d0812..e427918f1 100644
--- a/web_interface/templates/v3/partials/plugin_config.html
+++ b/web_interface/templates/v3/partials/plugin_config.html
@@ -999,6 +999,7 @@ <h3 class="text-md font-medium text-gray-900 mb-3">Plugin Information</h3>
             {# Configuration Form Panel #}
             <div class="bg-gray-50 rounded-lg p-4">
                 <h3 class="text-md font-medium text-gray-900 mb-3">Configuration</h3>
+                {{ ui.settings_filter("Filter this plugin's settings…") }}
                 <div class="space-y-4 max-h-96 overflow-y-auto pr-2">
                     {% if schema and schema.properties %}
                         {# Use property order if defined, otherwise use natural order #}

From aa7d6c43908c61f2dbc2faacb0fab2e98d465a6f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 9 Jul 2026 11:56:32 +0000
Subject: [PATCH 8/9] Close search dropdown via capture-phase outside-click

The dropdown could stay open after clicking away because the only
outside-click close was a bubble-phase document listener. The v3 UI is
one Alpine app() component full of HTMX/Alpine/widget click handlers;
when a click lands inside an element that calls stopPropagation(), the
event never bubbles to document and the close never runs.

- Replace the bubble-phase document 'click' close with a capture-phase
  'pointerdown' listener scoped to #settings-search-wrap. Capture runs
  before any bubbling stopPropagation can swallow the event, so it always
  fires; pointerdown also covers touch on the Pi screen. Clicking a result
  stays inside the wrap, so selection is unaffected.
- Guard the debounced input handler so a delayed render can't re-open the
  box after focus has left (type-then-click-away race).

Keeps the existing blur / Escape / htmx:afterSwap closes as secondary paths.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz
---
 web_interface/static/v3/js/settings-search.js | 24 ++++++++++++++-----
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/web_interface/static/v3/js/settings-search.js b/web_interface/static/v3/js/settings-search.js
index 9a0031680..ca6612d6d 100644
--- a/web_interface/static/v3/js/settings-search.js
+++ b/web_interface/static/v3/js/settings-search.js
@@ -295,7 +295,12 @@
         input.addEventListener('input', debounce(function () {
             var q = input.value;
             if (!q.trim()) { closeResults(); return; }
-            buildIndex().then(function () { renderResults(search(q)); });
+            // Focus may have left during the debounce (typed then clicked away);
+            // don't re-open a dropdown the user has already dismissed.
+            if (document.activeElement !== input) return;
+            buildIndex().then(function () {
+                if (document.activeElement === input) renderResults(search(q));
+            });
         }, 200));
 
         input.addEventListener('keydown', function (e) {
@@ -329,11 +334,18 @@
             if (chosen) navigateToSetting(chosen);
         });
 
-        document.addEventListener('click', function (e) {
-            if (!input) return;
-            if (e.target === input || resultsBox.contains(e.target)) return;
-            closeResults();
-        });
+        // Close when a click/tap lands outside the search widget. Capture phase
+        // (the `true`) runs on the way DOWN, before any bubbling stopPropagation
+        // from Alpine/HTMX/widget handlers can swallow the event — a plain
+        // bubble-phase document listener was being eaten and never closing us.
+        // pointerdown also covers touch (Raspberry Pi screen).
+        document.addEventListener('pointerdown', function (e) {
+            if (!input || resultsBox.classList.contains('hidden')) return;
+            var wrap = document.getElementById('settings-search-wrap');
+            var inside = wrap ? wrap.contains(e.target)
+                              : (e.target === input || resultsBox.contains(e.target));
+            if (!inside) closeResults();
+        }, true);
 
         // Reliable dismiss: close shortly after focus leaves the box. Result
         // selection uses mousedown + preventDefault (focus stays on the input),

From b38a27e5d1e8ee8787b9a33b082fc2f63178d57b Mon Sep 17 00:00:00 2001
From: ChuckBuilds <charlesmynard@gmail.com>
Date: Thu, 9 Jul 2026 08:46:26 -0400
Subject: [PATCH 9/9] Fix settings search dropdown not visually closing

.hidden has no effect in this app: app.css is a hand-picked utility
subset (no Tailwind build step) and never defines .hidden { display:
none }. openResults()/closeResults() only toggled the class, so the
dropdown stayed rendered (display: block) even once closeResults()
ran - confirmed via computed style in a headless browser. Set
style.display directly, matching the fallback already used by
revealNode()/collapseNode() elsewhere in this file.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 web_interface/static/v3/js/settings-search.js | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/web_interface/static/v3/js/settings-search.js b/web_interface/static/v3/js/settings-search.js
index ca6612d6d..5c794a004 100644
--- a/web_interface/static/v3/js/settings-search.js
+++ b/web_interface/static/v3/js/settings-search.js
@@ -134,10 +134,15 @@
 
     function openResults() {
         resultsBox.classList.remove('hidden');
+        // .hidden has no effect without a matching CSS rule (this app's stylesheet
+        // is a hand-picked utility subset, not full Tailwind) - force it directly,
+        // same as the revealNode/collapseNode fallback below.
+        resultsBox.style.display = '';
         if (input) input.setAttribute('aria-expanded', 'true');
     }
     function closeResults() {
         resultsBox.classList.add('hidden');
+        resultsBox.style.display = 'none';
         activeIndex = -1;
         if (input) {
             input.setAttribute('aria-expanded', 'false');