LEDMatrix/web_interface/blueprints/api_v3/config.py

"""Reading and writing configuration, including schedules.

Routes decorate the shared `api_v3` Blueprint from the package `__init__`,
so their endpoint names are unchanged by living here.
"""
from web_interface.blueprints.api_v3 import (
    ErrorCode, Optional, _coerce_to_bool,
    _redact_credentials, _validate_time_format, api_v3, deep_merge,
    describe_exception, error_response, json, jsonify,
    logger, mask_all_secret_values, merge_secrets,
    request, strip_masked_values, success_response,
)
from src.common.path_safety import resolve_under
from src.display_geometry import ORIENTATION_ROTATE_DEGREES
from src.matrix_support import INT_SETTING_LIMITS, describe_range, library_refusals, refusal_message
from src.pi5_matrix_support import is_raspberry_pi_5
from web_interface.cache import invalidate_cache
from web_interface.auth import SECTION as _WEB_AUTH_SECTION, strip_auth_section
import web_interface.blueprints.api_v3 as _pkg
import copy
from typing import Any, Dict, Iterable, Tuple

# Read through the module rather than bound by value: tests patch these
# as module attributes, and a value binding would not see the patch.
# Several are also called from helpers that live in __init__, so the
# package is the only patch point that covers every caller.

#: Hidden input the v3 settings forms (general.html, display.html,
#: durations.html) post to /config/main. Its presence tells save_main_config
#: that a missing checkbox was unchecked, not merely left out of an API call.
FORM_SECTION_FIELD = '__form_section'

#: Fields of the General tab. Any one of them in a /config/main post means the
#: General form was submitted, so its unchecked checkboxes read as False.
GENERAL_FIELDS = ('timezone', 'city', 'state', 'country', 'web_display_autostart',
                  'plugins_directory', 'auto_update_enabled', 'auto_update_channel')

#: Settings in config.json the running display applies without a restart,
#: as key paths (a path covers everything under it). Brightness goes over the
#: control socket (brightness.set) and the config watcher's refresh
#: (DisplayController._refresh_config_cache); the per-mode durations are read
#: from the live config each time a mode starts (_get_display_duration).
#: Plugin sections are live as well (each plugin's on_config_change), and
#: save_main_config adds the ones a request saves.
LIVE_CONFIG_PATHS: Tuple[Tuple[str, ...], ...] = (
    ('display', 'hardware', 'brightness'),
    ('display', 'display_durations'),
)


_MISSING = object()


def _config_leaves(config: Any, prefix: Tuple[str, ...] = ()) -> Dict[Tuple[str, ...], Any]:
    """Every non-dict value in ``config``, by key path. An empty dict has none,
    so a section created empty on the way to a field is not a change."""
    if not isinstance(config, dict):
        return {prefix: config}
    leaves: Dict[Tuple[str, ...], Any] = {}
    for key, value in config.items():
        leaves.update(_config_leaves(value, prefix + (str(key),)))
    return leaves


def restart_needed(before: Dict[str, Any], after: Dict[str, Any],
                   live_paths: Iterable[Tuple[str, ...]] = LIVE_CONFIG_PATHS) -> bool:
    """Does going from config ``before`` to ``after`` need a display restart?

    True when anything changed outside ``live_paths``. A save that changes
    only live settings, or nothing at all, does not.
    """
    live = tuple(live_paths)
    old, new = _config_leaves(before), _config_leaves(after)
    for path in set(old) | set(new):
        if old.get(path, _MISSING) == new.get(path, _MISSING):
            continue
        if not any(path[:len(prefix)] == prefix for prefix in live):
            return True
    return False


#: Top-level fields save_main_config stores somewhere of its own (location,
#: plugin_system, ...), never as a config key of the same name.
_MAPPED_TOP_LEVEL_FIELDS = GENERAL_FIELDS + (
    'auto_discover', 'auto_load_enabled', 'development_mode', 'target_fps')


def _plugin_id_list(raw, field_name):
    """``(ids, None)`` for a list of plugin ids, or ``(None, message)``.

    The settings forms post these lists as JSON text in a hidden input; a JSON
    client may send the array itself. Anything else is refused rather than
    coerced: storing ``[]`` for a malformed value clears the saved order or
    exclusions without a word.
    """
    try:
        parsed = json.loads(raw) if isinstance(raw, str) else raw
    except (json.JSONDecodeError, TypeError, ValueError):
        return None, f'{field_name} must be valid JSON'
    if not isinstance(parsed, list) or not all(isinstance(p, str) for p in parsed):
        return None, f'{field_name} must be a list of plugin-id strings'
    return parsed, None


def _day_setting(data, day, flat_key, nested_key):
    """(present, value) of one per-day schedule setting in a POST body.

    The schedule forms post flat keys (``monday_start``), while GET returns
    the stored shape, ``days.monday.start_time``. Accept both, so a client can
    post back what it read; a flat key wins when a body carries both.
    """
    if flat_key in data:
        return True, data[flat_key]
    days = data.get('days')
    day_config = days.get(day) if isinstance(days, dict) else None
    if isinstance(day_config, dict) and nested_key in day_config:
        return True, day_config[nested_key]
    return False, None


def _disabled_day_times(data, day, start_key, end_key):
    """The times posted for a day that is off, the valid ones.

    Nothing reads them while the day is off, but the schedule picker posts
    them and GET returns them, so keeping them means turning the day back on
    finds what was there. An invalid one is dropped rather than refused, for
    the same reason.
    """
    times = {}
    for field, key in (('start_time', start_key), ('end_time', end_key)):
        value = _day_setting(data, day, key, field)[1]
        if value and _validate_time_format(value)[0]:
            times[field] = value
    return times


@api_v3.route('/config/main', methods=['GET'])
def get_main_config():
    """Get main configuration, with credentials redacted."""
    if not api_v3.config_manager:
        return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500

    config = api_v3.config_manager.load_config()
    # load_config() merges config_secrets.json in, web_auth (the login
    # password hash, token hashes and cookie key) included. No client needs
    # any of it; /api/v3/auth/* manages it.
    return jsonify({'status': 'success',
                    'data': _redact_credentials(strip_auth_section(config))})
def _panel_refresh_hz(config):
    """(hz, source): the rate the panel really refreshes at, else the cap.

    The display service writes what it measured to the frame-stats file. The
    configured limit_refresh_rate_hz is only a cap (a 120Hz cap refreshes at
    ~126Hz on one rig, ~95Hz on a long chain), and the speeds that look smooth
    are fractions of the real rate, so advice built on the cap can be wrong.
    """
    from src.common import frame_timing, scroll_config
    cap = scroll_config.refresh_hz_from_config(config)
    try:
        with open(frame_timing.default_stats_path(), encoding='utf-8') as fh:
            measured = float(json.load(fh).get('measured_refresh_hz') or 0)
    except (OSError, ValueError, TypeError, AttributeError):
        measured = 0.0
    # Reject a stale file from a previous hardware config: a measurement far
    # off the cap says the config changed since it was written.
    if measured > 0 and 0.5 * cap <= measured <= 1.5 * cap:
        return measured, 'measured'
    return cap, 'configured'


@api_v3.route('/config/scroll-speed-advice', methods=['GET'])
def get_scroll_speed_advice():
    """What this panel does with a requested scroll speed, and smooth options.

    Backs the hint under the Vegas Scroll Speed slider.
    """
    from src.common import scroll_config
    try:
        speed = float(request.args.get('speed', ''))
        lo = float(request.args.get('min', 10))
        hi = float(request.args.get('max', 200))
    except ValueError:
        return jsonify({'status': 'error', 'message': 'speed must be a number'}), 400
    if not api_v3.config_manager:
        return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500
    hz, source = _panel_refresh_hz(api_v3.config_manager.load_config())
    advice = scroll_config.speed_advice(speed, hz, lo, hi)
    advice['refresh_source'] = source
    return jsonify({'status': 'success', 'data': advice})


@api_v3.route('/config/schedule', methods=['GET'])
def get_schedule_config():
    """Get current schedule configuration"""
    try:
        if not api_v3.config_manager:
            return error_response(
                ErrorCode.CONFIG_LOAD_FAILED,
                'Config manager not initialized',
                status_code=500
            )

        config = api_v3.config_manager.load_config()
        schedule_config = config.get('schedule', {})

        return success_response(data=schedule_config)
    except Exception as e:
        logger.error("%s failed", request.path, exc_info=True)
        return error_response(
            ErrorCode.CONFIG_LOAD_FAILED,
            "An error occurred; see logs for details",
            details=describe_exception(e),
            status_code=500
        )
@api_v3.route('/config/schedule', methods=['POST'])
def save_schedule_config():
    """Save schedule configuration"""
    try:
        if not api_v3.config_manager:
            return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500

        data = request.get_json(silent=True)
        if not data:
            return jsonify({'status': 'error', 'message': 'No data provided'}), 400

        # Load current config
        current_config = api_v3.config_manager.load_config()

        # Build schedule configuration
        # Handle enabled checkbox - can be True, False, or 'on'
        enabled_value = data.get('enabled', False)
        if isinstance(enabled_value, str):
            enabled_value = enabled_value.lower() in ('true', 'on', '1')
        schedule_config = {
            'enabled': enabled_value
        }

        mode = data.get('mode', 'global')
        schedule_config['mode'] = mode

        if mode == 'global':
            # Simple global schedule
            start_time = data.get('start_time', '07:00')
            end_time = data.get('end_time', '23:00')

            # Validate time formats
            is_valid, error_msg = _validate_time_format(start_time)
            if not is_valid:
                return error_response(
                    ErrorCode.VALIDATION_ERROR,
                    error_msg,
                    status_code=400
                )

            is_valid, error_msg = _validate_time_format(end_time)
            if not is_valid:
                return error_response(
                    ErrorCode.VALIDATION_ERROR,
                    error_msg,
                    status_code=400
                )

            schedule_config['start_time'] = start_time
            schedule_config['end_time'] = end_time
            # Remove days config when switching to global mode
            schedule_config.pop('days', None)
        else:
            # Per-day schedule
            schedule_config['days'] = {}
            # Remove global times when switching to per-day mode
            schedule_config.pop('start_time', None)
            schedule_config.pop('end_time', None)
            days = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday']
            enabled_days_count = 0

            for day in days:
                day_config = {}
                enabled_key = f'{day}_enabled'
                start_key = f'{day}_start'
                end_key = f'{day}_end'

                # Check if day is enabled
                has_enabled, enabled_val = _day_setting(data, day, enabled_key, 'enabled')
                if has_enabled:
                    # Handle checkbox values that may come as 'on', True, or False
                    if isinstance(enabled_val, str):
                        day_config['enabled'] = enabled_val.lower() in ('true', 'on', '1')
                    else:
                        day_config['enabled'] = bool(enabled_val)
                else:
                    # Default to enabled if not specified
                    day_config['enabled'] = True

                # Only add times if day is enabled
                if day_config.get('enabled', True):
                    enabled_days_count += 1
                    start_time = None
                    end_time = None

                    start_time = _day_setting(data, day, start_key, 'start_time')[1] or '07:00'
                    end_time = _day_setting(data, day, end_key, 'end_time')[1] or '23:00'

                    # Validate time formats
                    is_valid, error_msg = _validate_time_format(start_time)
                    if not is_valid:
                        return error_response(
                            ErrorCode.VALIDATION_ERROR,
                            f"Invalid start time for {day}: {error_msg}",
                            status_code=400
                        )

                    is_valid, error_msg = _validate_time_format(end_time)
                    if not is_valid:
                        return error_response(
                            ErrorCode.VALIDATION_ERROR,
                            f"Invalid end time for {day}: {error_msg}",
                            status_code=400
                        )

                    day_config['start_time'] = start_time
                    day_config['end_time'] = end_time
                else:
                    day_config.update(_disabled_day_times(data, day, start_key, end_key))

                schedule_config['days'][day] = day_config

            # An enabled per-day schedule needs a day to be on. A disabled
            # one does not: every day off with the schedule off is what
            # config.template.json ships, so refusing it meant a fresh
            # install could not post back the schedule GET returned.
            if enabled_days_count == 0 and enabled_value:
                return error_response(
                    ErrorCode.VALIDATION_ERROR,
                    "At least one day must be enabled in per-day schedule mode",
                    status_code=400
                )

        # Update and save config using atomic save
        current_config['schedule'] = schedule_config
        success, error_msg = _pkg._save_config_atomic(api_v3.config_manager, current_config, create_backup=True)
        if not success:
            return error_response(
                ErrorCode.CONFIG_SAVE_FAILED,
                f"Failed to save schedule configuration: {error_msg}",
                status_code=500
            )

        invalidate_cache()

        return success_response(message='Schedule configuration saved successfully')
    except Exception as e:
        logger.error("Error saving schedule config", exc_info=True)
        return error_response(
            ErrorCode.CONFIG_SAVE_FAILED,
            "An error occurred; see logs for details",

            status_code=500, details=describe_exception(e)
        )
@api_v3.route('/config/dim-schedule', methods=['GET'])
def get_dim_schedule_config():
    """Get current dim schedule configuration"""
    if not api_v3.config_manager:
        logger.error("[DIM SCHEDULE] Config manager not initialized")
        return error_response(
            ErrorCode.CONFIG_LOAD_FAILED,
            'Config manager not initialized',
            status_code=500
        )

    try:
        config = api_v3.config_manager.load_config()
        dim_schedule_config = config.get('dim_schedule', {
            'enabled': False,
            'dim_brightness': 30,
            'mode': 'global',
            'start_time': '20:00',
            'end_time': '07:00',
            'days': {}
        })

        return success_response(data=dim_schedule_config)
    except FileNotFoundError as e:
        logger.error(f"[DIM SCHEDULE] Config file not found: {e}", exc_info=True)
        return error_response(
            ErrorCode.CONFIG_LOAD_FAILED,
            "Configuration file not found",
            status_code=500
        )
    except json.JSONDecodeError as e:
        logger.error(f"[DIM SCHEDULE] Invalid JSON in config file: {e}", exc_info=True)
        return error_response(
            ErrorCode.CONFIG_LOAD_FAILED,
            "Configuration file contains invalid JSON",
            status_code=500
        )
    except (IOError, OSError) as e:
        logger.error(f"[DIM SCHEDULE] Error reading config file: {e}", exc_info=True)
        return error_response(
            ErrorCode.CONFIG_LOAD_FAILED,
            "An error occurred; see logs for details",
            status_code=500, details=describe_exception(e)
        )
    except Exception as e:
        logger.error(f"[DIM SCHEDULE] Unexpected error loading config: {e}", exc_info=True)
        return error_response(
            ErrorCode.CONFIG_LOAD_FAILED,
            "An error occurred; see logs for details",
            status_code=500, details=describe_exception(e)
        )
@api_v3.route('/config/dim-schedule', methods=['POST'])
def save_dim_schedule_config():
    """Save dim schedule configuration"""
    try:
        if not api_v3.config_manager:
            return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500

        data = request.get_json(silent=True)
        if not data:
            return jsonify({'status': 'error', 'message': 'No data provided'}), 400

        # Load current config
        current_config = api_v3.config_manager.load_config()

        # Build dim schedule configuration
        enabled_value = data.get('enabled', False)
        if isinstance(enabled_value, str):
            enabled_value = enabled_value.lower() in ('true', 'on', '1')

        # Validate and get dim_brightness
        dim_brightness_raw = data.get('dim_brightness', 30)
        try:
            # Handle empty string or None
            if dim_brightness_raw is None or dim_brightness_raw == '':
                dim_brightness = 30
            else:
                dim_brightness = int(dim_brightness_raw)
        except (ValueError, TypeError, OverflowError):
            return error_response(
                ErrorCode.VALIDATION_ERROR,
                "dim_brightness must be an integer between 0 and 100",
                status_code=400
            )

        if not 0 <= dim_brightness <= 100:
            return error_response(
                ErrorCode.VALIDATION_ERROR,
                "dim_brightness must be between 0 and 100",
                status_code=400
            )

        dim_schedule_config = {
            'enabled': enabled_value,
            'dim_brightness': dim_brightness
        }

        mode = data.get('mode', 'global')
        dim_schedule_config['mode'] = mode

        if mode == 'global':
            # Simple global schedule
            start_time = data.get('start_time', '20:00')
            end_time = data.get('end_time', '07:00')

            # Validate time formats
            is_valid, error_msg = _validate_time_format(start_time)
            if not is_valid:
                return error_response(
                    ErrorCode.VALIDATION_ERROR,
                    error_msg,
                    status_code=400
                )

            is_valid, error_msg = _validate_time_format(end_time)
            if not is_valid:
                return error_response(
                    ErrorCode.VALIDATION_ERROR,
                    error_msg,
                    status_code=400
                )

            dim_schedule_config['start_time'] = start_time
            dim_schedule_config['end_time'] = end_time
            # Remove days config when switching to global mode
            dim_schedule_config.pop('days', None)
        else:
            # Per-day schedule
            dim_schedule_config['days'] = {}
            # Remove global times when switching to per-day mode
            dim_schedule_config.pop('start_time', None)
            dim_schedule_config.pop('end_time', None)
            days = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday']
            enabled_days_count = 0

            for day in days:
                day_config = {}
                enabled_key = f'{day}_enabled'
                start_key = f'{day}_start'
                end_key = f'{day}_end'

                # Check if day is enabled
                has_enabled, enabled_val = _day_setting(data, day, enabled_key, 'enabled')
                if has_enabled:
                    if isinstance(enabled_val, str):
                        day_config['enabled'] = enabled_val.lower() in ('true', 'on', '1')
                    else:
                        day_config['enabled'] = bool(enabled_val)
                else:
                    day_config['enabled'] = True

                # Only add times if day is enabled
                if day_config.get('enabled', True):
                    enabled_days_count += 1
                    start_time = _day_setting(data, day, start_key, 'start_time')[1] or '20:00'
                    end_time = _day_setting(data, day, end_key, 'end_time')[1] or '07:00'

                    # Validate time formats
                    is_valid, error_msg = _validate_time_format(start_time)
                    if not is_valid:
                        return error_response(
                            ErrorCode.VALIDATION_ERROR,
                            f"Invalid start time for {day}: {error_msg}",
                            status_code=400
                        )

                    is_valid, error_msg = _validate_time_format(end_time)
                    if not is_valid:
                        return error_response(
                            ErrorCode.VALIDATION_ERROR,
                            f"Invalid end time for {day}: {error_msg}",
                            status_code=400
                        )

                    day_config['start_time'] = start_time
                    day_config['end_time'] = end_time
                else:
                    day_config.update(_disabled_day_times(data, day, start_key, end_key))

                dim_schedule_config['days'][day] = day_config

            # As for the on/off schedule: only an enabled one needs a day on.
            if enabled_days_count == 0 and enabled_value:
                return error_response(
                    ErrorCode.VALIDATION_ERROR,
                    "At least one day must be enabled in per-day dim schedule mode",
                    status_code=400
                )

        # Update and save config using atomic save
        current_config['dim_schedule'] = dim_schedule_config
        success, error_msg = _pkg._save_config_atomic(api_v3.config_manager, current_config, create_backup=True)
        if not success:
            return error_response(
                ErrorCode.CONFIG_SAVE_FAILED,
                f"Failed to save dim schedule configuration: {error_msg}",
                status_code=500
            )

        invalidate_cache()

        return success_response(message='Dim schedule configuration saved successfully')
    except Exception as e:
        logger.error("Error saving dim schedule config", exc_info=True)
        return error_response(
            ErrorCode.CONFIG_SAVE_FAILED,
            "An error occurred; see logs for details",

            status_code=500, details=describe_exception(e)
        )
@api_v3.route('/config/main', methods=['POST'])
def save_main_config():
    """Save main configuration"""
    try:
        if not api_v3.config_manager:
            return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500

        # Try to get JSON data first, fallback to form data
        data = None
        if request.is_json:
            data = request.get_json()
            if data is not None and not isinstance(data, dict):
                return jsonify({'status': 'error', 'message': 'Request body must be a JSON object'}), 400
        else:
            # Handle form data
            data = request.form.to_dict()
            # Convert checkbox values
            for key in ['web_display_autostart']:
                if key in data:
                    data[key] = data[key] == 'on'

        # The login settings are secrets with their own routes
        # (/api/v3/auth/*); a web_auth key here would land in config.json.
        if isinstance(data, dict):
            data.pop(_WEB_AUTH_SECTION, None)

        if not data:
            return jsonify({'status': 'error', 'message': 'No data provided'}), 400

        # A missing checkbox means different things to the two kinds of caller.
        # The settings forms post every field, and a browser leaves an
        # unchecked box out entirely, so for them absent means False. A JSON
        # API client (the MQTT bridge's brightness slider, a curl call from the
        # REST docs) sends only what it is changing, and there absent means
        # "leave it alone": treating it as unchecked turned off
        # disable_hardware_pulsing and three other settings on every
        # brightness change, and weekly auto-updates on every timezone change.
        # The v3 forms post JSON too (htmx json-enc), so they identify
        # themselves with a hidden FORM_SECTION_FIELD input. A form-encoded
        # post is a form by definition.
        is_form_submission = bool(data.pop(FORM_SECTION_FIELD, None)) or not request.is_json

        def _set_checkbox(section, key, field):
            """Store checkbox ``field`` as ``section[key]``, if this request sets it."""
            if is_form_submission or field in data:
                section[key] = _coerce_to_bool(data.get(field))

        # What arrives here is the config itself, and the headers carry the
        # session cookie -- neither belongs in the journal, least of all at
        # ERROR on every save. The shape of the request is the part with
        # diagnostic value, so log that, at the level it deserves.
        logger.debug("save_main_config: %s, %d top-level key(s)",
                     request.content_type or 'no content-type', len(data))

        # Merge with existing config (similar to original implementation)
        current_config = api_v3.config_manager.load_config()
        # What was stored, to tell which settings this save changed.
        stored_config = copy.deepcopy(current_config)
        was_auto_update_enabled = bool((current_config.get('auto_update') or {}).get('enabled'))

        is_general_update = any(k in data for k in GENERAL_FIELDS)

        if is_general_update:
            # For checkbox: if not present in data during a general *form*
            # update, it means unchecked (see _set_checkbox)
            _set_checkbox(current_config, 'web_display_autostart', 'web_display_autostart')
            if is_form_submission or 'auto_update_enabled' in data:
                if not isinstance(current_config.get('auto_update'), dict):
                    current_config['auto_update'] = {}
                _set_checkbox(current_config['auto_update'], 'enabled', 'auto_update_enabled')
            if 'auto_update_channel' in data:
                # stable/beta (web_interface/update_channel.py). Only stored
                # here; the next update applies it, never moving backwards.
                from web_interface import update_channel
                channel = update_channel.normalize_channel(data['auto_update_channel'])
                if channel is None:
                    return jsonify({'status': 'error',
                                    'message': "auto_update_channel must be 'stable' or 'beta'"}), 400
                if not isinstance(current_config.get('auto_update'), dict):
                    current_config['auto_update'] = {}
                if current_config['auto_update'].get('channel') != channel:
                    current_config['auto_update']['channel'] = channel
                    # The Overview banner compares against the channel's target.
                    _pkg._update_check_cache['result'] = None

        if 'timezone' in data:
            current_config['timezone'] = data['timezone']

        # Device-wide scroll frame rate, read by plugins via
        # BasePlugin.global_config. Bounds match ScrollHelper.set_target_fps,
        # which clamps silently -- rejecting here instead means a value that
        # would have been quietly altered is reported rather than appearing to
        # save and then behaving differently.
        if 'target_fps' in data and data['target_fps'] not in ('', None):
            raw_target_fps = data['target_fps']
            # A JSON body can carry real floats and bools, where int() would
            # silently truncate: 90.5 would save as 90, and true as 1. Reject
            # them rather than storing a value the user did not ask for. Form
            # posts arrive as strings, so '90.5' still fails in int() below.
            if isinstance(raw_target_fps, (bool, float)):
                return jsonify({
                    'status': 'error',
                    'message': "Invalid value for target_fps: must be an integer"
                }), 400
            try:
                target_fps = int(raw_target_fps)
            except (ValueError, TypeError, OverflowError):
                return jsonify({
                    'status': 'error',
                    'message': "Invalid value for target_fps: must be an integer"
                }), 400
            if not (30 <= target_fps <= 200):
                return jsonify({
                    'status': 'error',
                    'message': "Invalid value for target_fps: must be between 30 and 200"
                }), 400
            current_config['target_fps'] = target_fps

        # Handle location settings
        if 'city' in data or 'state' in data or 'country' in data:
            if 'location' not in current_config:
                current_config['location'] = {}
            if 'city' in data:
                current_config['location']['city'] = data['city']
            if 'state' in data:
                current_config['location']['state'] = data['state']
            if 'country' in data:
                current_config['location']['country'] = data['country']

        # Handle plugin system settings
        if 'auto_discover' in data or 'auto_load_enabled' in data or 'development_mode' in data or 'plugins_directory' in data:
            if 'plugin_system' not in current_config:
                current_config['plugin_system'] = {}

            # auto_discover / auto_load_enabled / development_mode are read by
            # nothing and no longer have General-tab toggles. The form still
            # posts plugins_directory, so treating a missing key as an
            # unchecked box would rewrite stored values to false on every
            # save; only store what a client actually sends.
            for legacy_flag in ['auto_discover', 'auto_load_enabled', 'development_mode']:
                if legacy_flag in data:
                    current_config['plugin_system'][legacy_flag] = _coerce_to_bool(data.get(legacy_flag))

            # Handle plugins_directory
            if 'plugins_directory' in data:
                current_config['plugin_system']['plugins_directory'] = data['plugins_directory']

        # Handle display settings
        display_fields = ['rows', 'cols', 'chain_length', 'parallel', 'brightness', 'hardware_mapping',
                         'gpio_slowdown', 'rp1_rio', 'scan_mode', 'disable_hardware_pulsing', 'inverse_colors', 'show_refresh_rate',
                         'pwm_bits', 'pwm_dither_bits', 'pwm_lsb_nanoseconds', 'limit_refresh_rate_hz', 'use_short_date_format',
                         'max_dynamic_duration_seconds', 'led_rgb_sequence', 'multiplexing', 'panel_type',
                         'row_address_type', 'pixel_mapper_config', 'orientation']

        if any(k in data for k in display_fields):
            if 'display' not in current_config:
                current_config['display'] = {}
            if 'hardware' not in current_config['display']:
                current_config['display']['hardware'] = {}
            if 'runtime' not in current_config['display']:
                current_config['display']['runtime'] = {}

            # Allowed values for validated string fields
            LED_RGB_ALLOWED = {'RGB', 'RBG', 'GRB', 'GBR', 'BRG', 'BGR'}
            PANEL_TYPE_ALLOWED = {'', 'FM6126A', 'FM6127'}

            # Validate led_rgb_sequence
            if 'led_rgb_sequence' in data and data['led_rgb_sequence'] not in LED_RGB_ALLOWED:
                return jsonify({'status': 'error', 'message': f"Invalid LED RGB sequence '{data['led_rgb_sequence']}'. Allowed values: {', '.join(sorted(LED_RGB_ALLOWED))}"}), 400

            # Validate panel_type
            if 'panel_type' in data and data['panel_type'] not in PANEL_TYPE_ALLOWED:
                return jsonify({'status': 'error', 'message': f"Invalid panel type '{data['panel_type']}'. Allowed values: Standard (empty), FM6126A, FM6127"}), 400

            # Validate pixel_mapper_config (free-form mapper string, e.g. "U-mapper;Rotate:90")
            if 'pixel_mapper_config' in data and not isinstance(data['pixel_mapper_config'], str):
                return jsonify({'status': 'error', 'message': 'pixel_mapper_config must be a string (e.g. "U-mapper;Rotate:90" or empty)'}), 400

            # Validate orientation (physical mounting rotation; composed onto pixel_mapper_config at runtime)
            ORIENTATION_ALLOWED = set(ORIENTATION_ROTATE_DEGREES)
            if 'orientation' in data and data['orientation'] not in ORIENTATION_ALLOWED:
                return jsonify({'status': 'error', 'message': f"Invalid orientation '{data['orientation']}'. Allowed values: {', '.join(sorted(ORIENTATION_ALLOWED))}"}), 400

            # Panel geometry, PWM and GPIO timing, held to what the rgbmatrix
            # library and its Python binding accept (src/matrix_support.py:
            # Options::Validate, the gpio_slowdown check, and the binding's
            # uint8_t setters, which cap chain_length at 255). Outside those
            # ranges the library returns no matrix and the display service
            # crash-loops rather than falling back, so they never save.
            def _hardware_int_error(field, low, high, even=False):
                """A 400 response if data[field] is not an allowed integer, else None."""
                raw = data[field]
                rejection = (jsonify({'status': 'error', 'message': f"Invalid {field} '{raw}'. Must be {describe_range(low, high, even)}."}), 400)
                # int() would quietly turn true into 1 and 48.5 into 48.
                if isinstance(raw, bool) or (isinstance(raw, float) and not raw.is_integer()):
                    return rejection
                try:
                    value = int(raw)
                except (ValueError, TypeError, OverflowError):
                    return rejection
                if value < low or value > high or (even and value % 2):
                    return rejection
                return None

            # rp1_rio has its own check below.
            for field, (_section, low, high, even) in INT_SETTING_LIMITS.items():
                if field in data and field != 'rp1_rio':
                    error = _hardware_int_error(field, low, high, even)
                    if error:
                        return error

            # Combinations the library can't start with: a hardware mapping it
            # doesn't have, more parallel chains than the mapping has outputs,
            # and on a Pi 5 its narrower RP1 support. Reported only when this
            # request sets one of the settings involved, so a problem already
            # stored doesn't block unrelated saves.
            combination_fields = ('hardware_mapping', 'parallel', 'row_address_type')
            if any(k in data for k in combination_fields):
                effective = dict(current_config['display']['hardware'])
                effective.update({k: v for k, v in data.items()
                                  if k in combination_fields or k in INT_SETTING_LIMITS})
                refusals = [r for r in library_refusals(effective, pi5=is_raspberry_pi_5())
                            if any(f in data for f in r.fields)]
                if refusals:
                    return jsonify({'status': 'error', 'message': refusal_message(refusals)}), 400

            # Handle hardware settings
            for field in ['rows', 'cols', 'chain_length', 'parallel', 'brightness', 'hardware_mapping', 'scan_mode',
                         'pwm_bits', 'pwm_dither_bits', 'pwm_lsb_nanoseconds', 'limit_refresh_rate_hz',
                         'led_rgb_sequence', 'multiplexing', 'panel_type', 'row_address_type',
                         'pixel_mapper_config', 'orientation']:
                if field in data:
                    if field in ['rows', 'cols', 'chain_length', 'parallel', 'brightness', 'scan_mode',
                               'pwm_bits', 'pwm_dither_bits', 'pwm_lsb_nanoseconds', 'limit_refresh_rate_hz',
                               'multiplexing', 'row_address_type']:
                        current_config['display']['hardware'][field] = int(data[field])
                    else:
                        current_config['display']['hardware'][field] = data[field]

            # Handle runtime settings
            if 'gpio_slowdown' in data:
                current_config['display']['runtime']['gpio_slowdown'] = int(data['gpio_slowdown'])
            if 'rp1_rio' in data:
                try:
                    rp1_val = int(data['rp1_rio'])
                    if rp1_val not in (0, 1):
                        return jsonify({'status': 'error', 'message': "rp1_rio must be 0 (PIO) or 1 (RIO)"}), 400
                    current_config['display']['runtime']['rp1_rio'] = rp1_val
                except (ValueError, TypeError, OverflowError):
                    return jsonify({'status': 'error', 'message': "rp1_rio must be 0 or 1"}), 400

            # Handle checkboxes - coerce to bool to ensure proper JSON types
            for checkbox in ['disable_hardware_pulsing', 'inverse_colors', 'show_refresh_rate']:
                _set_checkbox(current_config['display']['hardware'], checkbox, checkbox)

            # Handle display-level checkboxes (unchecked state on form saves)
            _set_checkbox(current_config['display'], 'use_short_date_format', 'use_short_date_format')

            # Handle dynamic duration settings
            # The Display form posts this on every save, as "" when the box
            # was cleared; int("") was a 500 that lost the whole save. Blank
            # keeps the stored cap, and anything else is held to the form's
            # 30-1800 range instead of raising.
            max_dynamic = data.get('max_dynamic_duration_seconds')
            if max_dynamic is None or (isinstance(max_dynamic, str) and not max_dynamic.strip()):
                max_dynamic = None
            else:
                error = _hardware_int_error('max_dynamic_duration_seconds', 30, 1800)
                if error:
                    return error
            if max_dynamic is not None:
                if 'dynamic_duration' not in current_config['display']:
                    current_config['display']['dynamic_duration'] = {}
                current_config['display']['dynamic_duration']['max_duration_seconds'] = int(max_dynamic)

        # Handle double-sided display settings
        double_sided_fields = ['double_sided_enabled', 'double_sided_copies', 'double_sided_axis']
        if any(k in data for k in double_sided_fields):
            if 'display' not in current_config:
                current_config['display'] = {}
            if 'double_sided' not in current_config['display']:
                current_config['display']['double_sided'] = {}
            ds_config = current_config['display']['double_sided']

            # Enabled checkbox: omitted from the form when unchecked.
            # The Display form posts copies/axis on every save regardless of this
            # checkbox, so when the feature is off we accept the values without
            # rejecting the whole save — otherwise a stale copies/chain_length
            # mismatch locks the user out of every other display setting.
            if is_form_submission or 'double_sided_enabled' in data:
                enabled = _coerce_to_bool(data.get('double_sided_enabled'))
                ds_config['enabled'] = enabled
            else:
                enabled = _coerce_to_bool(ds_config.get('enabled'))

            def _copies_fits_hardware(copies: int) -> Optional[str]:
                """Error message if copies doesn't divide the panel evenly, else None."""
                # Use axis from this request if provided, else from stored config.
                hw = current_config.get('display', {}).get('hardware', {})
                effective_axis = (data.get('double_sided_axis')
                                  or current_config.get('display', {}).get('double_sided', {}).get('axis', 'horizontal'))
                if effective_axis == 'horizontal':
                    chain_length = int(hw.get('chain_length', 2) or 2)
                    if chain_length % copies != 0:
                        return f"Double-sided copies ({copies}) must divide chain length ({chain_length}) evenly"
                elif effective_axis == 'vertical':
                    parallel = int(hw.get('parallel', 1) or 1)
                    if parallel % copies != 0:
                        return f"Double-sided copies ({copies}) must divide parallel ({parallel}) evenly"
                return None

            if 'double_sided_copies' in data and data['double_sided_copies'] not in ('', None):
                copies = None
                try:
                    copies = int(data['double_sided_copies'])
                except (ValueError, TypeError, OverflowError):
                    if enabled:
                        return jsonify({'status': 'error', 'message': "Double-sided copies must be an integer"}), 400
                if copies is not None and not (2 <= copies <= 8):
                    if enabled:
                        return jsonify({'status': 'error', 'message': "Double-sided copies must be between 2 and 8"}), 400
                    # Disabled: leave the stored value alone rather than writing junk.
                    copies = None
                if copies is not None:
                    # Divisibility is a hardware-relational check — only meaningful
                    # when the feature is actually on.
                    if enabled:
                        fit_error = _copies_fits_hardware(copies)
                        if fit_error:
                            return jsonify({'status': 'error', 'message': fit_error}), 400
                    ds_config['copies'] = copies

            if 'double_sided_axis' in data:
                axis = data['double_sided_axis']
                if axis not in ('horizontal', 'vertical'):
                    if enabled:
                        return jsonify({'status': 'error', 'message': "Double-sided axis must be 'horizontal' or 'vertical'"}), 400
                else:
                    ds_config['axis'] = axis

        # Handle Vegas scroll mode settings
        vegas_fields = ['vegas_scroll_enabled', 'vegas_scroll_speed', 'vegas_separator_width',
                       'vegas_target_fps', 'vegas_buffer_ahead', 'vegas_plugin_order', 'vegas_excluded_plugins',
                       'vegas_auto_trim', 'vegas_trim_threshold', 'vegas_content_padding',
                       'vegas_min_plugin_width', 'vegas_lead_in_width', 'vegas_plugins_per_cycle',
                       'vegas_max_plugin_width_ratio', 'vegas_dynamic_duration_enabled',
                       'vegas_min_cycle_duration', 'vegas_max_cycle_duration',
                       'vegas_intra_plugin_gap', 'vegas_render_width_pct',
                       'vegas_min_content_separation', 'vegas_min_cut_gap',
                       'vegas_continuous_scroll', 'vegas_extend_threshold_screens',
                       'vegas_smooth_scroll', 'vegas_overflow_mode', 'vegas_live_refresh',
                       'vegas_live_in_ticker']

        if any(k in data for k in vegas_fields):
            if 'display' not in current_config:
                current_config['display'] = {}
            if 'vegas_scroll' not in current_config['display']:
                current_config['display']['vegas_scroll'] = {}

            vegas_config = current_config['display']['vegas_scroll']

            # Handle enabled checkbox
            # HTML checkboxes omit the key entirely when unchecked, so if the form
            # was submitted (any vegas field present) but enabled key is missing,
            # the checkbox was unchecked and we should set enabled=False.
            # A JSON API call only changes the checkboxes it sends.
            _set_checkbox(vegas_config, 'enabled', 'vegas_scroll_enabled')
            _set_checkbox(vegas_config, 'auto_trim', 'vegas_auto_trim')
            _set_checkbox(vegas_config, 'dynamic_duration_enabled', 'vegas_dynamic_duration_enabled')
            _set_checkbox(vegas_config, 'continuous_scroll', 'vegas_continuous_scroll')
            _set_checkbox(vegas_config, 'smooth_scroll', 'vegas_smooth_scroll')
            _set_checkbox(vegas_config, 'live_refresh', 'vegas_live_refresh')
            _set_checkbox(vegas_config, 'live_in_ticker', 'vegas_live_in_ticker')

            # max_plugin_width_ratio is the one fractional setting, so it is
            # handled outside the integer loop below.
            if data.get('vegas_overflow_mode') not in ('', None):
                mode = str(data['vegas_overflow_mode']).strip().lower()
                if mode not in ('rotate', 'truncate'):
                    return jsonify({
                        'status': 'error',
                        'message': "Invalid value for vegas_overflow_mode: "
                                   "must be 'rotate' or 'truncate'"
                    }), 400
                vegas_config['overflow_mode'] = mode

            if data.get('vegas_extend_threshold_screens') not in ('', None):
                try:
                    screens = float(data['vegas_extend_threshold_screens'])
                except (ValueError, TypeError, OverflowError):
                    return jsonify({
                        'status': 'error',
                        'message': "Invalid value for vegas_extend_threshold_screens: "
                                   "must be a number"
                    }), 400
                if not (1.0 <= screens <= 10.0):
                    return jsonify({
                        'status': 'error',
                        'message': "Invalid value for vegas_extend_threshold_screens: "
                                   "must be between 1.0 and 10.0"
                    }), 400
                vegas_config['extend_threshold_screens'] = screens

            if data.get('vegas_max_plugin_width_ratio') not in ('', None):
                try:
                    ratio = float(data['vegas_max_plugin_width_ratio'])
                except (ValueError, TypeError, OverflowError):
                    return jsonify({
                        'status': 'error',
                        'message': "Invalid value for vegas_max_plugin_width_ratio: "
                                   "must be a number"
                    }), 400
                if not (0 <= ratio <= 20):
                    return jsonify({
                        'status': 'error',
                        'message': "Invalid value for vegas_max_plugin_width_ratio: "
                                   "must be between 0 and 20 (0 disables the cap)"
                    }), 400
                vegas_config['max_plugin_width_ratio'] = ratio

            # Handle numeric settings with validation.
            #
            # These bounds must match VegasModeConfig.validate(), which is what
            # actually gates Vegas starting. Where they were looser, a value
            # saved with a 200 and then made VegasModeCoordinator.start() bail
            # out with only a log line, so the ticker silently never ran.
            # Where they were tighter (scroll_speed capped at 100 against a
            # slider that goes to 200), a legitimate value was rejected with a
            # 400. See test_vegas_api_bounds_match_validate.
            numeric_fields = {
                'vegas_scroll_speed': ('scroll_speed', 1, 200),
                'vegas_separator_width': ('separator_width', 0, 128),
                'vegas_intra_plugin_gap': ('intra_plugin_gap', 0, 128),
                'vegas_render_width_pct': ('render_width_pct', 10, 100),
                'vegas_min_content_separation': ('min_content_separation', 0, 256),
                'vegas_min_cut_gap': ('min_cut_gap', 1, 128),
                'vegas_target_fps': ('target_fps', 30, 200),
                'vegas_buffer_ahead': ('buffer_ahead', 1, 5),
                'vegas_trim_threshold': ('trim_threshold', 0, 254),
                'vegas_content_padding': ('content_padding', 0, 128),
                'vegas_min_plugin_width': ('min_plugin_width', 0, 512),
                'vegas_lead_in_width': ('lead_in_width', 0, 2048),
                'vegas_plugins_per_cycle': ('plugins_per_cycle', 1, 50),
                'vegas_min_cycle_duration': ('min_cycle_duration', 5, 3600),
                'vegas_max_cycle_duration': ('max_cycle_duration', 10, 3600),
            }
            for field_name, (config_key, min_val, max_val) in numeric_fields.items():
                if field_name in data:
                    raw_value = data[field_name]
                    # Skip empty strings (treat as "not provided")
                    if raw_value == '' or raw_value is None:
                        continue
                    try:
                        int_value = int(raw_value)
                    except (ValueError, TypeError, OverflowError):
                        return jsonify({
                            'status': 'error',
                            'message': f"Invalid value for {field_name}: must be an integer"
                        }), 400
                    if not (min_val <= int_value <= max_val):
                        return jsonify({
                            'status': 'error',
                            'message': f"Invalid value for {field_name}: must be between {min_val} and {max_val}"
                        }), 400
                    vegas_config[config_key] = int_value

            for field_name, config_key in (('vegas_plugin_order', 'plugin_order'),
                                           ('vegas_excluded_plugins', 'excluded_plugins')):
                if field_name in data:
                    ids, id_error = _plugin_id_list(data[field_name], field_name)
                    if id_error:
                        return jsonify({'status': 'error', 'message': id_error}), 400
                    vegas_config[config_key] = ids

        # Handle multi-display sync settings
        sync_fields = ["sync_role", "sync_port", "sync_follower_position"]
        if any(k in data for k in sync_fields):
            if 'sync' not in current_config:
                current_config['sync'] = {}
            SYNC_ROLE_ALLOWED = {'standalone', 'leader', 'follower'}
            if 'sync_role' in data:
                role_val = str(data['sync_role']).lower()
                if role_val not in SYNC_ROLE_ALLOWED:
                    return jsonify({'status': 'error', 'message': f"Invalid sync role '{role_val}'. Must be one of: standalone, leader, follower"}), 400
                current_config['sync']['role'] = role_val
            if 'sync_port' in data:
                try:
                    port_val = int(data['sync_port'])
                    if not (1024 <= port_val <= 65535):
                        return jsonify({'status': 'error', 'message': "sync_port must be between 1024 and 65535"}), 400
                    current_config['sync']['port'] = port_val
                except (ValueError, TypeError, OverflowError):
                    return jsonify({'status': 'error', 'message': "sync_port must be an integer"}), 400

            if "sync_follower_position" in data:
                pos_val = str(data["sync_follower_position"]).lower()
                if pos_val not in {"left", "right"}:
                    return jsonify({"status": "error", "message": "sync_follower_position must be left or right"}), 400
                current_config["sync"]["follower_position"] = pos_val

        if 'plugin_rotation_order' in data:
            parsed, id_error = _plugin_id_list(data.pop('plugin_rotation_order'),
                                               'plugin_rotation_order')
            if id_error:
                return jsonify({'status': 'error', 'message': id_error}), 400
            if 'display' not in current_config:
                current_config['display'] = {}
            current_config['display']['plugin_rotation_order'] = parsed

        # Handle display durations. Popped from `data` (not just read) so
        # they can never also fall through to the generic "remaining keys"
        # merge near the end of this function, which would otherwise write
        # them AGAIN as bogus top-level config keys (e.g. "clock_duration": 30
        # sitting at config root alongside the correct
        # display.display_durations.clock_duration).
        # The Vegas cycle-time fields (vegas_min_cycle_duration, ...) share the
        # suffix but are Vegas settings, already handled above: counting them
        # here wrote junk mode durations, and a blank one 400'd the save.
        duration_fields = [k for k in list(data.keys())
                           if (k.endswith('_duration') and k not in vegas_fields)
                           or k in ('default_duration', 'transition_duration')]
        if duration_fields:
            if 'display' not in current_config:
                current_config['display'] = {}
            if 'display_durations' not in current_config['display']:
                current_config['display']['display_durations'] = {}

            for field in duration_fields:
                raw_value = data.pop(field)
                try:
                    int_value = int(raw_value)
                except (ValueError, TypeError, OverflowError):
                    return jsonify({'status': 'error',
                                    'message': f"Invalid duration for {field}: must be an integer"}), 400
                current_config['display']['display_durations'][field] = int_value

        # Per-mode durations from the Rotation & Durations page, posted as
        # duration__<mode_key> (mode keys are arbitrary plugin mode names, so
        # they can't use the suffix convention above). Same pop-and-validate
        # treatment, for the same reason.
        mode_duration_fields = [k for k in list(data.keys()) if k.startswith('duration__')]
        if mode_duration_fields:
            if 'display' not in current_config:
                current_config['display'] = {}
            if 'display_durations' not in current_config['display']:
                current_config['display']['display_durations'] = {}

            for field in mode_duration_fields:
                raw_value = data.pop(field)
                mode_key = field[len('duration__'):]
                if not mode_key:
                    continue
                if raw_value is None or str(raw_value).strip() == '':
                    # Blank means "use the plugin's own duration".
                    current_config['display']['display_durations'].pop(mode_key, None)
                    continue
                try:
                    int_value = int(raw_value)
                except (ValueError, TypeError, OverflowError):
                    return jsonify({'status': 'error',
                                    'message': f"Invalid duration for mode '{mode_key}': must be an integer"}), 400
                current_config['display']['display_durations'][mode_key] = int_value

        # Handle plugin configurations dynamically
        # Any key that matches a plugin ID is that plugin's settings. They go
        # through the same preparation as POST /plugins/config -- merged onto
        # the stored section, legacy booleans and schema defaults applied,
        # filtered, validated, secrets split out -- so this route can't store
        # a config that one rejects (stored verbatim, it left the plugin
        # flagged degraded at its next load).
        plugin_keys_to_remove = []
        plugin_secrets_updates = {}
        # Discovered first: a plugin key not recognised here skips secret
        # separation below and falls through to the generic merge, which wrote
        # the plugin's API key into config.json in plain text whenever nothing
        # had yet discovered plugins in this process (any save after a restart).
        plugin_manifests = _pkg._discovered_plugin_manifests()
        for key in data:
            # Check if this key is a plugin ID
            if api_v3.plugin_catalog and key in plugin_manifests:
                plugin_id = key
                submitted_config = data[key]
                if not isinstance(submitted_config, dict):
                    return error_response(
                        ErrorCode.VALIDATION_ERROR,
                        f"Settings for plugin '{plugin_id}' must be a JSON object",
                        status_code=400
                    )

                # plugin_id is already known to be a loaded plugin (the
                # membership test above), so this cannot currently traverse --
                # but the path is built from a request key, and the guard and
                # the schema load are far enough apart that a later edit could
                # separate them. Refuse rather than save without knowing which
                # fields are secrets.
                schema_path = resolve_under(api_v3.plugin_catalog.plugins_dir,
                                            plugin_id, 'config_schema.json')
                if schema_path is None:
                    return error_response(
                        ErrorCode.VALIDATION_ERROR,
                        f"Invalid plugin id '{plugin_id}'",
                        status_code=400
                    )

                schema_mgr = api_v3.schema_manager
                if not schema_mgr:
                    return error_response(
                        ErrorCode.SYSTEM_ERROR,
                        'Schema manager not initialized',
                        status_code=500
                    )
                schema = schema_mgr.load_schema(plugin_id, use_cache=False)

                from web_interface.blueprints.api_v3.plugin_config import (
                    _merge_onto_stored_plugin_config, _prepare_plugin_config_for_save,
                )
                plugin_config = _merge_onto_stored_plugin_config(
                    plugin_id, submitted_config, current_config)
                regular_config, secrets_config, error = _prepare_plugin_config_for_save(
                    plugin_id, plugin_config, schema, schema_mgr, is_json=True)
                if error:
                    return error

                # Deep merge regular config into main config, dropping
                # retired core keys (skin, skin_options) from the stored section
                from src.plugin_system.schema_manager import drop_retired_plugin_keys
                stored_section = current_config.get(plugin_id)
                current_config[plugin_id] = deep_merge(
                    drop_retired_plugin_keys(
                        stored_section if isinstance(stored_section, dict) else {}, schema),
                    regular_config)
                if secrets_config:
                    plugin_secrets_updates[plugin_id] = secrets_config

                # Mark for removal from data dict (already processed)
                plugin_keys_to_remove.append(key)

        # Deep merge secrets into secrets config, once every plugin section
        # has validated
        if plugin_secrets_updates:
            current_secrets = api_v3.config_manager.get_raw_file_content('secrets')
            for plugin_id, secrets_config in plugin_secrets_updates.items():
                if plugin_id not in current_secrets:
                    current_secrets[plugin_id] = {}
                # Lists merge by replacement, so deep_merge here wrote a
                # blanked array straight over the stored credentials.
                current_secrets[plugin_id] = merge_secrets(
                    current_secrets[plugin_id], secrets_config)
            # Save secrets file
            api_v3.config_manager.save_raw_file_content('secrets', current_secrets)

        # Remove processed plugin keys from data (they're already in current_config)
        for key in plugin_keys_to_remove:
            del data[key]

        # Whatever no section above claimed is stored as a top-level key, a
        # dict merged onto the stored one. Plugin sections were handled and
        # removed above. Form field names the sections above already stored
        # elsewhere are skipped, or each would land as a top-level key too.
        mapped_fields = set(_MAPPED_TOP_LEVEL_FIELDS).union(
            display_fields, sync_fields, vegas_fields, double_sided_fields)
        for key in data:
            if key in mapped_fields:
                continue
            if key in current_config and isinstance(current_config[key], dict) and isinstance(data[key], dict):
                # Deep merge to preserve existing settings
                current_config[key] = deep_merge(current_config[key], data[key])
            else:
                current_config[key] = data[key]

        # Save the merged config using atomic save
        success, error_msg = _pkg._save_config_atomic(api_v3.config_manager, current_config, create_backup=True)
        if not success:
            return error_response(
                ErrorCode.CONFIG_SAVE_FAILED,
                f"Failed to save configuration: {error_msg}",
                status_code=500
            )

        invalidate_cache()

        # Saved plugin sections reach the running plugins through the display
        # process's config watcher (on_config_change there); nothing runs a
        # plugin in this process.

        message = 'Configuration saved successfully'
        # Switching automatic updates on finishes their setup, which needs
        # the display service to restart (web_interface/auto_update.py).
        try:
            from web_interface import auto_update
            note = auto_update.start_setup_if_needed(was_auto_update_enabled, current_config)
            if note:
                message = f'{message}. {note}'
        except Exception:
            logger.warning("Automatic update setup could not be started", exc_info=True)
        # Display hardware, rotation order and general settings take effect
        # after a display restart; the UI shows its restart banner on this
        # flag. Brightness, mode durations and plugin settings are applied by
        # the running display (LIVE_CONFIG_PATHS), so a save that changed
        # only those -- or nothing -- does not ask for one.
        live_paths = LIVE_CONFIG_PATHS + tuple((plugin_id,) for plugin_id in plugin_keys_to_remove)
        extra = {'restart_required': restart_needed(stored_config, current_config, live_paths)}
        # Over the control socket a saved brightness lands at once, instead
        # of when the config watcher next looks (up to ~2 s).
        if 'brightness' in data:
            saved = (current_config.get('display', {}).get('hardware', {}) or {}).get('brightness')
            if isinstance(saved, int) and not isinstance(saved, bool):
                extra.update(_pkg._apply_brightness_on_display(saved))
        return success_response(message=message, extra=extra)
    except Exception as e:
        logger.error("Error saving config", exc_info=True)
        return error_response(
            ErrorCode.CONFIG_SAVE_FAILED,
            "An error occurred; see logs for details",
            status_code=500, details=describe_exception(e)
        )
@api_v3.route('/config/secrets', methods=['GET'])
def get_secrets_config():
    """Get secrets configuration"""
    if not api_v3.config_manager:
        return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500

    config = api_v3.config_manager.get_raw_file_content('secrets')
    # This interface has no authentication, and this file is nothing but
    # credentials. It was handing all of them to anyone who could reach
    # the port. Values are masked; empty and YOUR_* placeholders are left
    # alone so a client can still tell "set" from "not set".
    # web_auth is left out altogether, not masked: it is managed by
    # /api/v3/auth/*, and the raw save below keeps whatever is stored.
    return jsonify({'status': 'success',
                    'data': mask_all_secret_values(strip_auth_section(config))})
def _raw_config_save_error(e):
    """The 500 both raw-config save routes answer a failed save with.

    A ConfigError that names its file says which one; the rest is the same
    for every failure. raw_json.html reads only ``message``, which this
    keeps, alongside ``status`` and ``details`` as before.
    """
    from src.exceptions import ConfigError
    error_message = 'An error occurred; see logs for details'
    config_path = getattr(e, 'config_path', None) if isinstance(e, ConfigError) else None
    if config_path:
        error_message = f"{error_message} (config_path: {config_path})"
    return error_response(
        ErrorCode.CONFIG_SAVE_FAILED if isinstance(e, ConfigError) else ErrorCode.UNKNOWN_ERROR,
        error_message,
        details=describe_exception(e),
        context={'config_path': config_path} if config_path else None,
        status_code=500
    )


@api_v3.route('/config/raw/main', methods=['POST'])
def save_raw_main_config():
    """Save raw main configuration JSON"""
    try:
        if not api_v3.config_manager:
            return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500

        # silent=True so a malformed body returns None instead of raising
        # Werkzeug's own BadRequest, which would answer in a different
        # shape than this API's. Distinguish the two causes: a body that
        # was sent but does not parse is a different mistake from no body.
        data = request.get_json(silent=True)
        if data is None and request.get_data():
            return jsonify({'status': 'error', 'message': 'Invalid JSON in request body'}), 400
        if not data:
            return jsonify({'status': 'error', 'message': 'No data provided'}), 400
        # A JSON array or string parses fine and would be written over
        # config.json as-is, leaving a file nothing can load.
        if not isinstance(data, dict):
            return jsonify({'status': 'error', 'message': 'Configuration must be a JSON object'}), 400

        was_auto_update_enabled = False
        try:
            previous = api_v3.config_manager.get_raw_file_content('main') or {}
            was_auto_update_enabled = bool((previous.get('auto_update') or {}).get('enabled'))
        except Exception:
            logger.debug("Could not read the previous auto_update setting", exc_info=True)

        # Save the raw config file
        api_v3.config_manager.save_raw_file_content('main', data)

        message = 'Main configuration saved successfully'
        # Same hook as save_main_config: switching automatic updates on here
        # must finish their setup too, not wait for the next service restart.
        try:
            from web_interface import auto_update
            note = auto_update.start_setup_if_needed(was_auto_update_enabled, data)
            if note:
                message = f'{message}. {note}'
        except Exception:
            logger.warning("Automatic update setup could not be started", exc_info=True)
        return jsonify({'status': 'success', 'message': message})
    except Exception as e:
        logger.error("Error saving raw main config", exc_info=True)
        return _raw_config_save_error(e)
@api_v3.route('/config/raw/secrets', methods=['POST'])
def save_raw_secrets_config():
    """Save raw secrets configuration JSON"""
    try:
        if not api_v3.config_manager:
            return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500

        # See save_raw_main_config: silent parsing, with a sent-but-broken
        # body reported separately from a missing one.
        data = request.get_json(silent=True)
        if data is None and request.get_data():
            return jsonify({'status': 'error', 'message': 'Invalid JSON in request body'}), 400
        if not data:
            return jsonify({'status': 'error', 'message': 'No data provided'}), 400
        # strip_masked_values/deep_merge below expect an object; anything
        # else was a 500 at best and a replaced secrets file at worst.
        if not isinstance(data, dict):
            return jsonify({'status': 'error', 'message': 'Secrets configuration must be a JSON object'}), 400

        # The GET above masks what it returns, and this endpoint's only client
        # reads the whole file, edits one field and posts all of it back. So
        # most of what arrives here is the mask, echoed rather than changed --
        # storing it verbatim would replace every untouched credential with
        # eight bullets. Strip those, then merge onto what is already stored,
        # which makes "unchanged" mean unchanged.
        #
        # The cost is that a secret can no longer be cleared by blanking it.
        # That needs its own affordance; a control that erases credentials as
        # a side effect of saving an unrelated one is not it.
        # The login section never reaches this editor (see the GET above) and
        # is not written from it: a hand-typed password_hash would be a
        # plaintext that no password matches. The stored one is kept.
        data.pop(_WEB_AUTH_SECTION, None)
        current = api_v3.config_manager.get_raw_file_content('secrets') or {}
        merged = deep_merge(current, strip_masked_values(data))
        api_v3.config_manager.save_raw_file_content('secrets', merged)

        # Reload GitHub token in plugin store manager if it exists
        if api_v3.plugin_store_manager:
            api_v3.plugin_store_manager.github_token = api_v3.plugin_store_manager._load_github_token()

        return jsonify({'status': 'success', 'message': 'Secrets configuration saved successfully'})
    except Exception as e:
        logger.error("Error saving raw secrets config", exc_info=True)
        return _raw_config_save_error(e)