feat(tools): manage the MQTT bridge and Pixlet editor from the Tools tab

PR #544's change, ported onto the api_v3 package split (#553). Identical
behaviour; only the placement of the new code differs.

The original added 508 lines to web_interface/blueprints/api_v3.py, which #553
deletes, so every hunk of it would conflict irreconcilably. Ported by AST:
26 new top-level items sorted to where the split puts each kind --

  __init__.py   2 imports, 11 constants, 7 helpers
  starlark.py   4 routes  (/starlark/editor/{apps,status,start,stop})
  misc.py       2 routes  (/integrations/mqtt-bridge{,/config})

Everything outside api_v3.py -- the Tools partial, the installer scripts, the
JS tests -- applied unchanged.

Routes: 111 from the split plus these 6 = 117, and the url-map snapshot is
regenerated to match, which is exactly what test_api_v3_url_map.py is designed
to make you do when routes are added.

Full Python suite: 4,278 passed, 68 skipped, 0 failed. The JS tests this PR
ships could not be run here -- node is not installed on this machine -- so
test/js/dom/test_tools_sections.js is unverified.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014RRtqXDCnvnY6EQwhT5CV9

web_interface/blueprints/api_v3/__init__.py

@@ -17,6 +17,8 @@ everything they need has to exist first.
 """
 from flask import Blueprint, request, jsonify, Response
 import json
+import signal
+import contextlib
 import os
 import re
 import stat
@@ -1769,6 +1771,206 @@ def _toggle_starlark_app(app_id: str, enabled: bool):
                     'enabled': enabled})
 
 
+_PIXLET_EDITOR_SCRIPT = PROJECT_ROOT / 'scripts' / 'utils' / 'pixlet_config_editor.sh'
+
+# Deliberately under /tmp: a session cannot survive a reboot, so neither should
+# the record of one.
+_PIXLET_EDITOR_STATE = Path(tempfile.gettempdir()) / 'ledmatrix_pixlet_editor.json'
+
+_PIXLET_EDITOR_DEFAULT_PORT = 8080
+
+_PIXLET_EDITOR_DEFAULT_TIMEOUT = 1800
+
+_PIXLET_EDITOR_MAX_TIMEOUT = 14400
+
+def _read_pixlet_editor_state() -> Optional[Dict[str, Any]]:
+    try:
+        if _PIXLET_EDITOR_STATE.is_file():
+            with open(_PIXLET_EDITOR_STATE, encoding='utf-8') as handle:
+                state = json.load(handle)
+            return state if isinstance(state, dict) else None
+    except (OSError, json.JSONDecodeError):
+        logger.debug('Unreadable pixlet editor state; treating as no session', exc_info=True)
+    return None
+
+def _clear_pixlet_editor_state() -> None:
+    with contextlib.suppress(OSError):
+        _PIXLET_EDITOR_STATE.unlink()
+
+def _pixlet_editor_alive(pid: Optional[int]) -> bool:
+    """Is the recorded session still running?
+
+    os.kill(pid, 0) is not enough on its own: the script is a child of this
+    process, so once it exits it stays a zombie until reaped, and signal 0
+    succeeds against a zombie. Left at that, a finished session would read as
+    running forever and the UI would keep offering a Stop button for it.
+    """
+    if not pid:
+        return False
+
+    # Reap it if it is ours and already finished; harmless if it is not.
+    with contextlib.suppress(ChildProcessError, OSError):
+        reaped, _ = os.waitpid(pid, os.WNOHANG)
+        if reaped == pid:
+            return False
+
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        # Exists but is not ours to signal, which still counts as running.
+        return True
+
+    # Not our child (e.g. the web service restarted under a live session), so
+    # waitpid told us nothing -- ask /proc whether it is merely a zombie.
+    with contextlib.suppress(OSError, IndexError, ValueError):
+        with open(f'/proc/{pid}/stat', encoding='utf-8') as handle:
+            # The comm field can contain spaces and parens; everything after
+            # the final ')' is positional, and state is the first of those.
+            fields = handle.read().rsplit(')', 1)[1].split()
+        if fields and fields[0] == 'Z':
+            return False
+    return True
+
+def _pixlet_editor_status() -> Dict[str, Any]:
+    """Current session, reconciled against reality.
+
+    The state file records what we started; the process may have ended on its
+    own (its timeout, a crash, a manual kill). Anything stale is cleared here so
+    the UI never offers a Stop button for a session that is already over.
+    """
+    state = _read_pixlet_editor_state()
+    if not state:
+        return {'running': False}
+    if not _pixlet_editor_alive(state.get('pid')):
+        _clear_pixlet_editor_state()
+        return {'running': False}
+
+    remaining = None
+    deadline = state.get('deadline')
+    if isinstance(deadline, (int, float)):
+        remaining = max(0, int(deadline - time.time()))
+    return {
+        'running': True,
+        'app_id': state.get('app_id'),
+        'port': state.get('port', _PIXLET_EDITOR_DEFAULT_PORT),
+        'pid': state.get('pid'),
+        'started_at': state.get('started_at'),
+        'timeout': state.get('timeout'),
+        'seconds_remaining': remaining,
+        'host_bound': state.get('host', '0.0.0.0'),
+    }
+
+_MQTT_BRIDGE_DIR = PROJECT_ROOT / 'integrations' / 'mqtt_bridge'
+
+_MQTT_BRIDGE_CONFIG = _MQTT_BRIDGE_DIR / 'bridge_config.json'
+
+_MQTT_BRIDGE_EXAMPLE = _MQTT_BRIDGE_DIR / 'bridge_config.example.json'
+
+_MQTT_BRIDGE_SERVICE = 'ledmatrix-mqtt-bridge.service'
+
+# Mirrors DEFAULTS in ledmatrix_mqtt_bridge.py. Duplicated rather than imported
+# because that module pulls in paho-mqtt, which the web process does not need
+# installed just to render a settings form.
+_MQTT_BRIDGE_DEFAULTS = {
+    'mqtt_host': 'localhost',
+    'mqtt_port': 1883,
+    'mqtt_username': None,
+    'mqtt_client_id': 'ledmatrix-mqtt-bridge',
+    'mqtt_topic': 'ledmatrix/command',
+    'mqtt_tls': False,
+    'mqtt_tls_insecure': False,
+    'ledmatrix_api_base': 'http://localhost:5000',
+    'request_timeout': 15,
+    'on_demand_duration': None,
+    'log_level': 'INFO',
+}
+
+_MQTT_BRIDGE_LOG_LEVELS = ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL')
+
+def _mqtt_bridge_service_state() -> Dict[str, Any]:
+    """installed / active / enabled for the bridge unit."""
+    state = {'installed': False, 'active': False, 'enabled': False}
+    try:
+        listed = _run_systemctl_command(
+            ['systemctl', 'list-unit-files', _MQTT_BRIDGE_SERVICE, '--no-legend'])
+        state['installed'] = bool((listed.get('stdout') or '').strip())
+        state['active'] = _run_systemctl_command(
+            ['systemctl', 'is-active', _MQTT_BRIDGE_SERVICE]).get('stdout', '').strip() == 'active'
+        state['enabled'] = _run_systemctl_command(
+            ['systemctl', 'is-enabled', _MQTT_BRIDGE_SERVICE]).get('stdout', '').strip() == 'enabled'
+    except Exception:
+        logger.debug('Could not read %s state', _MQTT_BRIDGE_SERVICE, exc_info=True)
+    return state
+
+def _read_mqtt_bridge_config() -> Dict[str, Any]:
+    """Stored config overlaid on the defaults. Missing file is not an error."""
+    config = dict(_MQTT_BRIDGE_DEFAULTS)
+    config['mqtt_password'] = None
+    try:
+        if _MQTT_BRIDGE_CONFIG.is_file():
+            with open(_MQTT_BRIDGE_CONFIG, encoding='utf-8') as handle:
+                stored = json.load(handle)
+            if isinstance(stored, dict):
+                config.update(stored)
+    except (OSError, json.JSONDecodeError) as err:
+        logger.warning('Could not read %s: %s', _MQTT_BRIDGE_CONFIG, err)
+    return config
+
+def _coerce_mqtt_bridge_value(key: str, raw: Any) -> Tuple[Any, Optional[str]]:
+    """Validate one submitted field. Returns (value, error)."""
+    if key in ('mqtt_port',):
+        try:
+            port = int(raw)
+        except (TypeError, ValueError):
+            return None, 'Port must be a whole number'
+        if not 1 <= port <= 65535:
+            return None, 'Port must be between 1 and 65535'
+        return port, None
+    if key in ('request_timeout',):
+        try:
+            timeout = int(raw)
+        except (TypeError, ValueError):
+            return None, 'Request timeout must be a whole number'
+        if not 1 <= timeout <= 300:
+            return None, 'Request timeout must be between 1 and 300 seconds'
+        return timeout, None
+    if key == 'on_demand_duration':
+        if raw in (None, ''):
+            return None, None
+        try:
+            duration = int(raw)
+        except (TypeError, ValueError):
+            return None, 'On-demand duration must be a whole number of seconds'
+        if not 1 <= duration <= 86400:
+            return None, 'On-demand duration must be between 1 and 86400 seconds'
+        return duration, None
+    if key in ('mqtt_tls', 'mqtt_tls_insecure'):
+        return bool(raw) if isinstance(raw, bool) else str(raw).lower() in ('1', 'true', 'yes', 'on'), None
+    if key == 'log_level':
+        level = str(raw or '').upper()
+        if level not in _MQTT_BRIDGE_LOG_LEVELS:
+            return None, f"Log level must be one of {', '.join(_MQTT_BRIDGE_LOG_LEVELS)}"
+        return level, None
+    if key == 'ledmatrix_api_base':
+        base = str(raw or '').strip().rstrip('/')
+        if not base.startswith(('http://', 'https://')):
+            return None, 'API base must start with http:// or https://'
+        if len(base) > 300:
+            return None, 'API base is too long'
+        return base, None
+    # Remaining keys are free text; empty means "unset" for the optional ones.
+    text = '' if raw is None else str(raw).strip()
+    if len(text) > 300:
+        return None, f'{key} is too long'
+    if key == 'mqtt_username' and not text:
+        return None, None
+    if key in ('mqtt_host', 'mqtt_client_id', 'mqtt_topic') and not text:
+        return None, f'{key.replace("_", " ")} cannot be empty'
+    return text, None
+
+
 # Imported last, and for their side effect: each registers its routes on
 # api_v3. They import names from this module, so this module must be fully
 # executed before they run.

web_interface/blueprints/api_v3/backup.py

@@ -4,9 +4,8 @@ Routes decorate the shared `api_v3` Blueprint from ._common, so their
 endpoint names are unchanged by living here.
 """
 from web_interface.blueprints.api_v3 import (
-    PROJECT_ROOT, Path, _safe_backup_path, api_v3,
-    datetime, json, jsonify, logger, os, plugin_store_manager, request,
-    tempfile,
+    PROJECT_ROOT, Path, _safe_backup_path, api_v3, datetime, json, jsonify,
+    logger, os, plugin_store_manager, request, tempfile,
 )
 import web_interface.blueprints.api_v3 as _pkg
 # Read through the module rather than bound by value: tests patch these

web_interface/blueprints/api_v3/config.py

@@ -5,9 +5,9 @@ endpoint names are unchanged by living here.
 """
 from web_interface.blueprints.api_v3 import (
     ErrorCode, Optional, PROJECT_ROOT, Path, _coerce_to_bool,
-    _redact_credentials, _validate_time_format, api_v3,
-    deep_merge, describe_exception, error_response, find_secret_fields, json,
-    jsonify, logger, logging, mask_all_secret_values, merge_secrets, os,
+    _redact_credentials, _validate_time_format, api_v3, deep_merge,
+    describe_exception, error_response, find_secret_fields, json, jsonify,
+    logger, logging, mask_all_secret_values, merge_secrets, os,
     remove_empty_secrets, request, separate_secrets, strip_masked_values,
     success_response,
 )

web_interface/blueprints/api_v3/misc.py

@@ -5,9 +5,12 @@ Routes decorate the shared `api_v3` Blueprint from ._common, so their
 endpoint names are unchanged by living here.
 """
 from web_interface.blueprints.api_v3 import (
-    ErrorCode, Path, _JOURNALCTL, _SUDO, _get_display_service_status, api_v3,
-    describe_exception, error_response, get_error_aggregator, json, jsonify,
-    logger, os, request, subprocess, success_response,
+    ErrorCode, Path, _JOURNALCTL, _MQTT_BRIDGE_CONFIG, _MQTT_BRIDGE_DEFAULTS,
+    _MQTT_BRIDGE_DIR, _SUDO, _coerce_mqtt_bridge_value,
+    _get_display_service_status, _mqtt_bridge_service_state,
+    _read_mqtt_bridge_config, api_v3, contextlib, describe_exception,
+    error_response, get_error_aggregator, json, jsonify, logger, os, request,
+    subprocess, success_response, tempfile,
 )
 import web_interface.blueprints.api_v3 as _pkg
 # Read through the module rather than bound by value: tests patch these
@@ -396,3 +399,98 @@ def clear_old_errors():
             message="Failed to clear old errors",
             status_code=500
         )
+
+
+@api_v3.route('/integrations/mqtt-bridge', methods=['GET'])
+def get_mqtt_bridge():
+    """Bridge service state and its settings, minus the password."""
+    try:
+        config = _read_mqtt_bridge_config()
+        password = config.get('mqtt_password')
+        safe = {key: config.get(key, default)
+                for key, default in _MQTT_BRIDGE_DEFAULTS.items()}
+        return jsonify({
+            'status': 'success',
+            'data': {
+                'service': _mqtt_bridge_service_state(),
+                'config_exists': _MQTT_BRIDGE_CONFIG.is_file(),
+                'config_path': str(_MQTT_BRIDGE_CONFIG),
+                'config': safe,
+                # Enough to render "a password is set" without disclosing it.
+                'password_set': bool(password),
+                'env_override_prefix': 'LEDMATRIX_MQTT_',
+            }
+        })
+    except Exception as e:
+        logger.exception('Error reading MQTT bridge settings')
+        return jsonify({'status': 'error', 'message': 'Could not read bridge settings',
+                        'details': describe_exception(e)}), 500
+
+@api_v3.route('/integrations/mqtt-bridge/config', methods=['PUT'])
+def update_mqtt_bridge_config():
+    """Write bridge_config.json.
+
+    The password is write-only: omit it to leave whatever is stored alone, send
+    a value to replace it, or send clear_password to remove it. It is never
+    returned by the GET above, so a form that round-tripped it would otherwise
+    have to blank it on every save.
+    """
+    try:
+        data = request.get_json(silent=True) or {}
+        if not isinstance(data, dict):
+            return jsonify({'status': 'error', 'message': 'Body must be a JSON object'}), 400
+
+        config = _read_mqtt_bridge_config()
+        existing_password = config.get('mqtt_password')
+
+        updates = {}
+        for key in _MQTT_BRIDGE_DEFAULTS:
+            if key not in data:
+                continue
+            value, err = _coerce_mqtt_bridge_value(key, data[key])
+            if err:
+                return jsonify({'status': 'error', 'message': err}), 400
+            updates[key] = value
+
+        config.update(updates)
+
+        if data.get('clear_password'):
+            config['mqtt_password'] = None
+        elif 'mqtt_password' in data and str(data['mqtt_password']) != '':
+            new_password = str(data['mqtt_password'])
+            if len(new_password) > 300:
+                return jsonify({'status': 'error', 'message': 'Password is too long'}), 400
+            config['mqtt_password'] = new_password
+        else:
+            config['mqtt_password'] = existing_password
+
+        if config.get('mqtt_password') and not config.get('mqtt_tls'):
+            logger.warning('MQTT bridge: a password is set without TLS; '
+                           'credentials will cross the network in cleartext')
+
+        _MQTT_BRIDGE_DIR.mkdir(parents=True, exist_ok=True)
+        # Write via a temp file in the same directory so a crash mid-write
+        # cannot leave a half-written config the bridge would refuse to load.
+        fd, tmp_path = tempfile.mkstemp(dir=str(_MQTT_BRIDGE_DIR), prefix='.bridge_config.')
+        try:
+            with os.fdopen(fd, 'w', encoding='utf-8') as handle:
+                json.dump(config, handle, indent=2, sort_keys=True)
+                handle.write('\n')
+            os.chmod(tmp_path, 0o600)
+            os.replace(tmp_path, _MQTT_BRIDGE_CONFIG)
+        except Exception:
+            with contextlib.suppress(OSError):
+                os.unlink(tmp_path)
+            raise
+
+        service = _mqtt_bridge_service_state()
+        message = 'Bridge settings saved.'
+        if service['active']:
+            message += ' Restart the bridge for them to take effect.'
+        return jsonify({'status': 'success', 'message': message,
+                        'data': {'password_set': bool(config.get('mqtt_password')),
+                                 'restart_required': service['active']}})
+    except Exception as e:
+        logger.exception('Error saving MQTT bridge settings')
+        return jsonify({'status': 'error', 'message': 'Could not save bridge settings',
+                        'details': describe_exception(e)}), 500

web_interface/blueprints/api_v3/plugins.py

@@ -5,17 +5,18 @@ endpoint names are unchanged by living here.
 """
 from web_interface.blueprints.api_v3 import (
     ErrorCode, OperationType, PROJECT_ROOT, Path, Response,
-    _CALENDAR_LIST_MAX_PAGES, _SKIP_FIELD,
-    _coerce_to_bool, _do_transactional_uninstall,
-    _enhance_schema_with_core_properties, _filter_config_by_schema,
-    _get_plugin_version, _get_schema_property, _installed_plugin_ids,
-    _is_plugin_update_available, _parse_form_value_with_schema,
-    _prune_credential_backups, _run_calendar_registration, _set_missing_booleans_to_false, _set_nested_value,
-    _starlark_virtual_plugins, _toggle_starlark_app, api_v3, datetime,
-    deep_merge, describe_exception, error_response, find_secret_fields,
-    hashlib, json, jsonify, logger, logging, merge_secrets, os, redact_text,
-    remove_empty_secrets, request, separate_secrets, shutil, stat, subprocess,
-    success_response, sys, tempfile, uuid, validate_request_json,
+    _CALENDAR_LIST_MAX_PAGES, _SKIP_FIELD, _coerce_to_bool,
+    _do_transactional_uninstall, _enhance_schema_with_core_properties,
+    _filter_config_by_schema, _get_plugin_version, _get_schema_property,
+    _installed_plugin_ids, _is_plugin_update_available,
+    _parse_form_value_with_schema, _prune_credential_backups,
+    _run_calendar_registration, _set_missing_booleans_to_false,
+    _set_nested_value, _starlark_virtual_plugins, _toggle_starlark_app,
+    api_v3, datetime, deep_merge, describe_exception, error_response,
+    find_secret_fields, hashlib, json, jsonify, logger, logging,
+    merge_secrets, os, redact_text, remove_empty_secrets, request,
+    separate_secrets, shutil, stat, subprocess, success_response, sys,
+    tempfile, uuid, validate_request_json,
 )
 import web_interface.blueprints.api_v3 as _pkg
 # Read through the module rather than bound by value: tests patch these

web_interface/blueprints/api_v3/starlark.py

@@ -4,10 +4,15 @@ Routes decorate the shared `api_v3` Blueprint from ._common, so their
 endpoint names are unchanged by living here.
 """
 from web_interface.blueprints.api_v3 import (
-    PROJECT_ROOT, Path, _find_pixlet_binary, _install_star_file, _standalone_render_starlark_app,
-    _starlark_github_token, _validate_and_sanitize_app_id,
-    _validate_starlark_app_path, _validate_timing_value, api_v3, describe_exception, json, jsonify,
-    logger, os, request, shutil, subprocess, tempfile,
+    PROJECT_ROOT, Path, _PIXLET_EDITOR_DEFAULT_PORT,
+    _PIXLET_EDITOR_DEFAULT_TIMEOUT, _PIXLET_EDITOR_MAX_TIMEOUT,
+    _PIXLET_EDITOR_SCRIPT, _PIXLET_EDITOR_STATE, _clear_pixlet_editor_state,
+    _find_pixlet_binary, _install_star_file, _pixlet_editor_alive,
+    _pixlet_editor_status, _read_pixlet_editor_state,
+    _standalone_render_starlark_app, _starlark_github_token,
+    _validate_and_sanitize_app_id, _validate_starlark_app_path,
+    _validate_timing_value, api_v3, contextlib, describe_exception, json,
+    jsonify, logger, os, request, shutil, signal, subprocess, tempfile,
 )
 import web_interface.blueprints.api_v3 as _pkg
 # Read through the module rather than bound by value: tests patch these
@@ -690,3 +695,178 @@ def get_tronbyte_categories():
     except Exception as e:
         logger.exception("[Starlark] get_tronbyte_categories failed")
         return jsonify({'status': 'error', 'message': 'Failed to fetch categories', 'details': describe_exception(e)}), 500
+
+
+@api_v3.route('/starlark/editor/apps', methods=['GET'])
+def list_pixlet_editor_apps():
+    """Apps on disk that the editor can open.
+
+    Read from the directory rather than the loaded plugin: the editor works on
+    files, and the plugin may not be loaded in this process at all.
+    """
+    try:
+        apps = []
+        if _STARLARK_APPS_DIR.is_dir():
+            for entry in sorted(_STARLARK_APPS_DIR.iterdir()):
+                if not entry.is_dir():
+                    continue
+                star_files = sorted(entry.glob('*.star'))
+                name = entry.name
+                manifest = entry / 'manifest.json'
+                if manifest.is_file():
+                    try:
+                        with open(manifest, encoding='utf-8') as handle:
+                            data = json.load(handle)
+                        if isinstance(data, dict):
+                            name = data.get('name') or name
+                    except (OSError, json.JSONDecodeError):
+                        pass
+                apps.append({
+                    'id': entry.name,
+                    'name': name,
+                    'editable': bool(star_files),
+                    'has_config': (entry / 'config.json').is_file(),
+                })
+        return jsonify({'status': 'success', 'data': {
+            'apps': apps,
+            'apps_dir': str(_STARLARK_APPS_DIR),
+            'pixlet_available': _find_pixlet_binary() is not None,
+        }})
+    except Exception as e:
+        logger.exception('Error listing editor apps')
+        return jsonify({'status': 'error', 'message': 'Could not list apps',
+                        'details': describe_exception(e)}), 500
+
+@api_v3.route('/starlark/editor/status', methods=['GET'])
+def get_pixlet_editor_status():
+    """Whether a session is running, and how long it has left."""
+    try:
+        return jsonify({'status': 'success', 'data': _pixlet_editor_status()})
+    except Exception as e:
+        logger.exception('Error reading editor status')
+        return jsonify({'status': 'error', 'message': 'Could not read editor status',
+                        'details': describe_exception(e)}), 500
+
+@api_v3.route('/starlark/editor/start', methods=['POST'])
+def start_pixlet_editor():
+    """Start an editing session for one app."""
+    try:
+        data = request.get_json(silent=True) or {}
+        app_id = data.get('app_id')
+
+        app_dir, err = _validate_starlark_app_path(app_id or '')
+        if err or not app_dir:
+            return jsonify({'status': 'error', 'message': err or 'Invalid app_id'}), 400
+        if not app_dir.is_dir():
+            return jsonify({'status': 'error', 'message': f'No such app: {app_id}'}), 404
+        if not any(app_dir.glob('*.star')):
+            return jsonify({'status': 'error',
+                            'message': f'{app_id} has no .star file to edit'}), 400
+        if not _PIXLET_EDITOR_SCRIPT.is_file():
+            return jsonify({'status': 'error', 'message': 'Editor script not found'}), 404
+        if _find_pixlet_binary() is None:
+            return jsonify({'status': 'error',
+                            'message': 'Pixlet is not installed - install it first'}), 503
+
+        current = _pixlet_editor_status()
+        if current.get('running'):
+            return jsonify({'status': 'error',
+                            'message': f"An editor session for '{current.get('app_id')}' is "
+                                       f"already running; stop it first"}), 409
+
+        try:
+            timeout_s = int(data.get('timeout') or _PIXLET_EDITOR_DEFAULT_TIMEOUT)
+        except (TypeError, ValueError):
+            return jsonify({'status': 'error', 'message': 'timeout must be a whole number'}), 400
+        if not 60 <= timeout_s <= _PIXLET_EDITOR_MAX_TIMEOUT:
+            return jsonify({'status': 'error',
+                            'message': f'timeout must be between 60 and '
+                                       f'{_PIXLET_EDITOR_MAX_TIMEOUT} seconds'}), 400
+        try:
+            port = int(data.get('port') or _PIXLET_EDITOR_DEFAULT_PORT)
+        except (TypeError, ValueError):
+            return jsonify({'status': 'error', 'message': 'port must be a whole number'}), 400
+        if not 1024 <= port <= 65535:
+            return jsonify({'status': 'error', 'message': 'port must be between 1024 and 65535'}), 400
+
+        env = dict(os.environ)
+        env['PIXLET_EDITOR_PORT'] = str(port)
+        env['PIXLET_EDITOR_TIMEOUT'] = str(timeout_s)
+        # A browser reaching this endpoint is remote by definition, so the
+        # session has to listen on more than loopback to be usable at all.
+        env['PIXLET_EDITOR_HOST'] = '0.0.0.0'
+
+        log_path = Path(tempfile.gettempdir()) / 'ledmatrix_pixlet_editor.log'
+        log_handle = open(log_path, 'w', encoding='utf-8')  # noqa: SIM115 - owned by the child
+        try:
+            # start_new_session so the script leads its own process group: the
+            # stop route signals the group, which is what lets the EXIT trap run
+            # and hand the display back.
+            process = subprocess.Popen(  # nosec B603 - fixed script path, validated app_id
+                ['/bin/bash', str(_PIXLET_EDITOR_SCRIPT), app_dir.name],
+                cwd=str(PROJECT_ROOT), env=env,
+                stdout=log_handle, stderr=subprocess.STDOUT,
+                start_new_session=True)
+        finally:
+            log_handle.close()
+
+        now = time.time()
+        state = {'pid': process.pid, 'app_id': app_dir.name, 'port': port,
+                 'timeout': timeout_s, 'started_at': now, 'deadline': now + timeout_s,
+                 'host': '0.0.0.0', 'log': str(log_path)}
+        try:
+            with open(_PIXLET_EDITOR_STATE, 'w', encoding='utf-8') as handle:
+                json.dump(state, handle)
+        except OSError as err:
+            logger.warning('Started an editor session but could not record it: %s', err)
+
+        logger.info('Pixlet editor started for %s on port %s (pid %s, %ss limit)',
+                    app_dir.name, port, process.pid, timeout_s)
+        return jsonify({'status': 'success',
+                        'message': f"Editing '{app_dir.name}'. The display is stopped until "
+                                   f"the session ends.",
+                        'data': _pixlet_editor_status()})
+    except Exception as e:
+        logger.exception('Error starting the pixlet editor')
+        return jsonify({'status': 'error', 'message': 'Could not start the editor',
+                        'details': describe_exception(e)}), 500
+
+@api_v3.route('/starlark/editor/stop', methods=['POST'])
+def stop_pixlet_editor():
+    """End the running session and give the display back."""
+    try:
+        state = _read_pixlet_editor_state()
+        if not state or not _pixlet_editor_alive(state.get('pid')):
+            _clear_pixlet_editor_state()
+            return jsonify({'status': 'success', 'message': 'No editor session was running.',
+                            'data': {'running': False}})
+
+        pid = int(state['pid'])
+        # SIGTERM the group, not the pid: bash forwards nothing to `timeout` and
+        # its child on its own, and the trap needs to run to restart the display.
+        try:
+            os.killpg(os.getpgid(pid), signal.SIGTERM)
+        except (ProcessLookupError, PermissionError, OSError) as err:
+            logger.debug('Could not signal the editor process group: %s', err)
+            with contextlib.suppress(ProcessLookupError, PermissionError):
+                os.kill(pid, signal.SIGTERM)
+
+        # Give the trap a moment to stop pixlet and restart ledmatrix.
+        deadline = time.time() + 10
+        while time.time() < deadline and _pixlet_editor_alive(pid):
+            time.sleep(0.25)
+
+        if _pixlet_editor_alive(pid):
+            logger.warning('Editor session %s ignored SIGTERM; sending SIGKILL. The display '
+                           'may need a manual restart.', pid)
+            with contextlib.suppress(ProcessLookupError, PermissionError, OSError):
+                os.killpg(os.getpgid(pid), signal.SIGKILL)
+
+        _clear_pixlet_editor_state()
+        return jsonify({'status': 'success',
+                        'message': 'Editor stopped; the display is restarting.',
+                        'data': {'running': False}})
+    except Exception as e:
+        logger.exception('Error stopping the pixlet editor')
+        return jsonify({'status': 'error', 'message': 'Could not stop the editor',
+                        'details': describe_exception(e)}), 500

web_interface/templates/v3/partials/tools.html

@@ -233,6 +233,46 @@
         </div>
     </div>
 
+    <!-- MQTT Bridge -->
+    <div class="bg-white rounded-lg shadow p-6">
+        <div class="border-b border-gray-200 pb-4 mb-6">
+            <div class="flex items-center justify-between gap-4">
+                <h2 class="text-lg font-semibold text-gray-900">MQTT Bridge</h2>
+                <span id="mqtt-bridge-state" class="text-xs px-2 py-1 rounded-full bg-gray-100 text-gray-600">checking&hellip;</span>
+            </div>
+            <p class="mt-1 text-sm text-gray-600">
+                Exposes the display to Home Assistant over MQTT &mdash; force a mode on demand, set
+                brightness, toggle power. Runs as <code class="bg-gray-100 px-1 rounded">ledmatrix-mqtt-bridge.service</code>.
+            </p>
+        </div>
+
+        <div id="mqtt-bridge-body" class="space-y-4">
+            <p class="text-sm text-gray-500">Loading settings&hellip;</p>
+        </div>
+    </div>
+
+    <!-- Pixlet Config Editor -->
+    <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">Pixlet Config Editor</h2>
+            <p class="mt-1 text-sm text-gray-600">
+                Opens a Starlark app in Pixlet's own config form, which runs the app for real &mdash;
+                so dropdowns that build their options at runtime work, and you see the render update
+                as you type.
+            </p>
+            <p class="mt-2 text-sm text-amber-700 bg-amber-50 border border-amber-200 rounded-md p-2">
+                <i class="fas fa-exclamation-triangle mr-1"></i>
+                The display stops while a session is open, and the editor has no password &mdash; the
+                same footing as this page. Sessions end by themselves after 30&nbsp;minutes, so the
+                panel is never left dark.
+            </p>
+        </div>
+
+        <div id="pixlet-editor-body" class="space-y-4">
+            <p class="text-sm text-gray-500">Loading apps&hellip;</p>
+        </div>
+    </div>
+
     <!-- System Power -->
     <div class="bg-white rounded-lg shadow p-6">
         <div class="border-b border-gray-200 pb-4 mb-6">
@@ -962,5 +1002,339 @@
 
     // WiFi radio current state.
     window.loadWifiRadio();
+
+    // ── MQTT bridge ───────────────────────────────────────────────────────────
+
+    const MQTT_BRIDGE_URL = '/api/v3/integrations/mqtt-bridge';
+
+    function mqttBadge(service, configExists) {
+        if (!service.installed) return ['bg-gray-100 text-gray-600', 'not installed'];
+        if (service.active) return ['bg-green-100 text-green-700', 'running'];
+        if (!configExists) return ['bg-amber-100 text-amber-700', 'not configured'];
+        return ['bg-amber-100 text-amber-700', 'stopped'];
+    }
+
+    function renderMqttBridge(data) {
+        const badge = document.getElementById('mqtt-bridge-state');
+        const [cls, label] = mqttBadge(data.service, data.config_exists);
+        if (badge) {
+            badge.className = 'text-xs px-2 py-1 rounded-full ' + cls;
+            badge.textContent = label;
+        }
+
+        const c = data.config || {};
+        const field = (id, label, value, type, extra) => `
+            <label class="block">
+                <span class="text-xs font-medium text-gray-700">${escHtml(label)}</span>
+                <input id="${id}" type="${type || 'text'}" value="${value === null || value === undefined ? '' : escHtml(String(value))}"
+                       ${extra || ''}
+                       class="mt-1 w-full px-2 py-1.5 text-sm border border-gray-300 rounded-md">
+            </label>`;
+
+        document.getElementById('mqtt-bridge-body').innerHTML = `
+            <div class="grid grid-cols-1 sm:grid-cols-2 gap-3">
+                ${field('mqtt-host', 'Broker host', c.mqtt_host)}
+                ${field('mqtt-port', 'Port', c.mqtt_port, 'number', 'min="1" max="65535"')}
+                ${field('mqtt-username', 'Username (optional)', c.mqtt_username)}
+                <label class="block">
+                    <span class="text-xs font-medium text-gray-700">Password</span>
+                    <input id="mqtt-password" type="password" value=""
+                           placeholder="${data.password_set ? 'unchanged — leave blank to keep' : 'none set'}"
+                           class="mt-1 w-full px-2 py-1.5 text-sm border border-gray-300 rounded-md">
+                    <span class="text-xs text-gray-500">
+                        Never sent back to the browser.
+                        ${data.password_set ? '<button type="button" id="mqtt-clear-password" class="text-red-600 hover:underline ml-1">Clear it</button>' : ''}
+                    </span>
+                </label>
+                ${field('mqtt-topic', 'Command topic', c.mqtt_topic)}
+                ${field('mqtt-client-id', 'Client ID', c.mqtt_client_id)}
+                ${field('mqtt-api-base', 'LEDMatrix API base', c.ledmatrix_api_base)}
+                ${field('mqtt-timeout', 'Request timeout (s)', c.request_timeout, 'number', 'min="1" max="300"')}
+                ${field('mqtt-duration', 'On-demand duration (s, blank = default)', c.on_demand_duration, 'number', 'min="1" max="86400"')}
+                <label class="block">
+                    <span class="text-xs font-medium text-gray-700">Log level</span>
+                    <select id="mqtt-log-level" class="mt-1 w-full px-2 py-1.5 text-sm border border-gray-300 rounded-md bg-white">
+                        ${['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'].map(l =>
+                            `<option value="${l}" ${c.log_level === l ? 'selected' : ''}>${l}</option>`).join('')}
+                    </select>
+                </label>
+            </div>
+
+            <label class="flex items-center gap-2 text-sm text-gray-700">
+                <input id="mqtt-tls" type="checkbox" ${c.mqtt_tls ? 'checked' : ''}
+                       class="rounded border-gray-300">
+                Use TLS
+                <span class="text-xs text-gray-500">(a password without TLS crosses the network in the clear)</span>
+            </label>
+
+            <div class="flex items-center justify-between gap-4 pt-2">
+                <p class="text-xs text-gray-500">
+                    Saved to <code class="bg-gray-100 px-1 rounded">${escHtml(data.config_path)}</code>.
+                    Any field can also be set as
+                    <code class="bg-gray-100 px-1 rounded">${escHtml(data.env_override_prefix)}&lt;KEY&gt;</code>,
+                    which wins over the file.
+                </p>
+                <button id="btn-mqtt-save" onclick="saveMqttBridge()"
+                        class="shrink-0 inline-flex items-center px-3 py-2 border border-transparent text-sm font-medium rounded-md text-white bg-blue-600 hover:bg-blue-700">
+                    <i class="fas fa-save mr-2"></i>Save settings
+                </button>
+            </div>
+            <div id="result-mqtt-save" class="hidden"></div>
+
+            <div class="flex flex-wrap items-center gap-2 pt-4 border-t border-gray-100">
+                ${data.service.installed ? `
+                    <button id="btn-mqtt-restart" onclick="toolsAction('mqtt_bridge_restart','btn-mqtt-restart','result-mqtt-service')"
+                            class="inline-flex items-center px-3 py-2 border border-gray-300 text-sm font-medium rounded-md text-gray-700 bg-white hover:bg-gray-50">
+                        <i class="fas fa-sync-alt mr-2"></i>Restart
+                    </button>
+                    <button id="btn-mqtt-startstop"
+                            onclick="toolsAction('${data.service.active ? 'mqtt_bridge_stop' : 'mqtt_bridge_start'}','btn-mqtt-startstop','result-mqtt-service')"
+                            class="inline-flex items-center px-3 py-2 border border-gray-300 text-sm font-medium rounded-md text-gray-700 bg-white hover:bg-gray-50">
+                        <i class="fas fa-${data.service.active ? 'stop' : 'play'} mr-2"></i>${data.service.active ? 'Stop' : 'Start'}
+                    </button>` : `
+                    <button id="btn-mqtt-install" onclick="installMqttBridge()"
+                            class="inline-flex items-center px-3 py-2 border border-transparent text-sm font-medium rounded-md text-white bg-green-600 hover:bg-green-700">
+                        <i class="fas fa-download mr-2"></i>Install &amp; start bridge
+                    </button>
+                    <span class="text-xs text-gray-500">Installs dependencies, enables the unit and starts it.</span>`}
+            </div>
+            <div id="result-mqtt-service" class="hidden"></div>
+        `;
+
+        const clearBtn = document.getElementById('mqtt-clear-password');
+        if (clearBtn) clearBtn.addEventListener('click', () => clearMqttPassword());
+    }
+
+    window.loadMqttBridge = function() {
+        fetch(MQTT_BRIDGE_URL)
+            .then(r => r.json())
+            .then(d => {
+                if (d.status !== 'success') throw new Error(d.message || 'Failed');
+                renderMqttBridge(d.data);
+            })
+            .catch(err => {
+                document.getElementById('mqtt-bridge-body').innerHTML =
+                    `<p class="text-sm text-red-600">Could not load bridge settings: ${escHtml(err.message)}</p>`;
+            });
+    };
+
+    function mqttBody() {
+        const val = id => (document.getElementById(id) || {}).value;
+        const body = {
+            mqtt_host: val('mqtt-host'),
+            mqtt_port: val('mqtt-port'),
+            mqtt_username: val('mqtt-username'),
+            mqtt_topic: val('mqtt-topic'),
+            mqtt_client_id: val('mqtt-client-id'),
+            ledmatrix_api_base: val('mqtt-api-base'),
+            request_timeout: val('mqtt-timeout'),
+            on_demand_duration: val('mqtt-duration') === '' ? null : val('mqtt-duration'),
+            log_level: val('mqtt-log-level'),
+            mqtt_tls: !!(document.getElementById('mqtt-tls') || {}).checked,
+        };
+        // Only send a password when one was typed; blank means "leave it alone".
+        const pw = val('mqtt-password');
+        if (pw) body.mqtt_password = pw;
+        return body;
+    }
+
+    window.saveMqttBridge = function() {
+        setBusy('btn-mqtt-save', true);
+        fetch(MQTT_BRIDGE_URL + '/config', {
+            method: 'PUT',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify(mqttBody())
+        })
+        .then(r => r.json().then(d => ({ok: r.ok, d})))
+        .then(({ok, d}) => {
+            showResult('result-mqtt-save', ok && d.status === 'success',
+                       d.message || (ok ? 'Saved' : 'Failed'));
+            if (ok && d.status === 'success') loadMqttBridge();
+        })
+        .catch(err => showResult('result-mqtt-save', false, 'Request failed: ' + err.message))
+        .finally(() => setBusy('btn-mqtt-save', false));
+    };
+
+    function clearMqttPassword() {
+        if (!confirm('Remove the stored MQTT password?')) return;
+        fetch(MQTT_BRIDGE_URL + '/config', {
+            method: 'PUT',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({clear_password: true})
+        })
+        .then(r => r.json())
+        .then(d => {
+            showResult('result-mqtt-save', d.status === 'success', d.message || 'Password cleared');
+            loadMqttBridge();
+        })
+        .catch(err => showResult('result-mqtt-save', false, 'Request failed: ' + err.message));
+    }
+
+    window.installMqttBridge = function() {
+        // Installing pulls dependencies, so it is slower than the other actions
+        // and worth saying so rather than leaving a spinner unexplained.
+        showResult('result-mqtt-service', true, 'Installing — this pulls Python dependencies and can take a minute…');
+        setBusy('btn-mqtt-install', true);
+        fetch('/api/v3/system/action', {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({action: 'mqtt_bridge_install'})
+        })
+        .then(r => r.json())
+        .then(d => {
+            showResult('result-mqtt-service', d.status === 'success',
+                       d.message || (d.status === 'success' ? 'Installed' : 'Failed'), d.output || '');
+            loadMqttBridge();
+        })
+        .catch(err => showResult('result-mqtt-service', false, 'Request failed: ' + err.message))
+        .finally(() => setBusy('btn-mqtt-install', false));
+    };
+
+    // ── Pixlet config editor ──────────────────────────────────────────────────
+
+    const PIXLET_EDITOR_URL = '/api/v3/starlark/editor';
+    let pixletPollTimer = null;
+
+    function fmtRemaining(seconds) {
+        if (seconds === null || seconds === undefined) return '';
+        const m = Math.floor(seconds / 60), s = seconds % 60;
+        return `${m}:${String(s).padStart(2, '0')}`;
+    }
+
+    function editorHost(port) {
+        // The session binds 0.0.0.0, so whatever host reached this page reaches
+        // the editor too -- no tunnel, and no guessing the device's address.
+        return `${window.location.protocol}//${window.location.hostname}:${port}/`;
+    }
+
+    function renderPixletEditor(status, apps, pixletAvailable, appsDir) {
+        const body = document.getElementById('pixlet-editor-body');
+        if (!body) return;
+
+        if (!pixletAvailable) {
+            body.innerHTML = `
+                <p class="text-sm text-gray-700">
+                    Pixlet is not installed, so there is nothing to edit with. Install it from the
+                    Starlark Apps section of the Plugins tab, or run
+                    <code class="bg-gray-100 px-1 rounded">./scripts/download_pixlet.sh</code>.
+                </p>`;
+            return;
+        }
+
+        const active = status.running ? `
+            <div class="rounded-md border border-amber-300 bg-amber-50 p-3">
+                <div class="flex items-start justify-between gap-4">
+                    <div>
+                        <p class="text-sm font-medium text-amber-900">
+                            <i class="fas fa-circle-notch fa-spin mr-1"></i>
+                            Editing <code class="bg-amber-100 px-1 rounded">${escHtml(status.app_id)}</code> — the display is stopped
+                        </p>
+                        <p class="text-xs text-amber-800 mt-1">
+                            <a href="${editorHost(status.port)}" target="_blank" rel="noopener"
+                               class="underline font-medium">Open the editor &rarr;</a>
+                            <span class="ml-2">stops on its own in
+                                <span id="pixlet-countdown">${fmtRemaining(status.seconds_remaining)}</span></span>
+                        </p>
+                    </div>
+                    <button id="btn-pixlet-stop" onclick="stopPixletEditor()"
+                            class="shrink-0 inline-flex items-center px-3 py-2 border border-transparent text-sm font-medium rounded-md text-white bg-red-600 hover:bg-red-700">
+                        <i class="fas fa-stop mr-2"></i>Stop now
+                    </button>
+                </div>
+            </div>` : '';
+
+        const rows = apps.length ? apps.map(a => `
+            <div class="flex items-center justify-between gap-4 py-2 border-t border-gray-100 first:border-t-0">
+                <div class="min-w-0">
+                    <p class="text-sm font-medium text-gray-900 truncate">${escHtml(a.name)}</p>
+                    <p class="text-xs text-gray-500 truncate">${escHtml(a.id)}${a.editable ? '' : ' — no .star file'}</p>
+                </div>
+                <button id="btn-pixlet-edit-${escHtml(a.id)}"
+                        ${(!a.editable || status.running) ? 'disabled' : ''}
+                        onclick="startPixletEditor('${escHtml(a.id)}')"
+                        class="shrink-0 inline-flex items-center px-3 py-2 border border-gray-300 text-sm font-medium rounded-md text-gray-700 bg-white hover:bg-gray-50 disabled:opacity-50 disabled:cursor-not-allowed">
+                    <i class="fas fa-sliders-h mr-2"></i>Edit
+                </button>
+            </div>`).join('') : `
+            <p class="text-sm text-gray-500">
+                No Starlark apps installed. Install one from the Plugins tab first
+                (looked in <code class="bg-gray-100 px-1 rounded">${escHtml(appsDir)}</code>).
+            </p>`;
+
+        body.innerHTML = active + `<div class="mt-2">${rows}</div>
+            <div id="result-pixlet" class="hidden"></div>`;
+    }
+
+    window.loadPixletEditor = function() {
+        Promise.all([
+            fetch(PIXLET_EDITOR_URL + '/status').then(r => r.json()),
+            fetch(PIXLET_EDITOR_URL + '/apps').then(r => r.json())
+        ])
+        .then(([s, a]) => {
+            const status = (s.data || {});
+            const apps = (a.data || {}).apps || [];
+            renderPixletEditor(status, apps, (a.data || {}).pixlet_available, (a.data || {}).apps_dir || '');
+            schedulePixletPoll(status.running);
+        })
+        .catch(err => {
+            const body = document.getElementById('pixlet-editor-body');
+            if (body) body.innerHTML = `<p class="text-sm text-red-600">Could not load: ${escHtml(err.message)}</p>`;
+        });
+    };
+
+    function schedulePixletPoll(running) {
+        // Poll only while a session is open: that is the state worth watching,
+        // and it is what makes the banner survive a page reload.
+        if (pixletPollTimer) { clearInterval(pixletPollTimer); pixletPollTimer = null; }
+        if (!running) return;
+        pixletPollTimer = setInterval(() => {
+            fetch(PIXLET_EDITOR_URL + '/status')
+                .then(r => r.json())
+                .then(d => {
+                    const st = d.data || {};
+                    if (!st.running) { loadPixletEditor(); return; }
+                    const el = document.getElementById('pixlet-countdown');
+                    if (el) el.textContent = fmtRemaining(st.seconds_remaining);
+                })
+                .catch(() => {});
+        }, 5000);
+    }
+
+    window.startPixletEditor = function(appId) {
+        const btnId = 'btn-pixlet-edit-' + appId;
+        setBusy(btnId, true);
+        fetch(PIXLET_EDITOR_URL + '/start', {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({app_id: appId})
+        })
+        .then(r => r.json().then(d => ({ok: r.ok, d})))
+        .then(({ok, d}) => {
+            if (!ok || d.status !== 'success') {
+                showResult('result-pixlet', false, d.message || 'Could not start the editor');
+                return;
+            }
+            loadPixletEditor();
+        })
+        .catch(err => showResult('result-pixlet', false, 'Request failed: ' + err.message))
+        .finally(() => setBusy(btnId, false));
+    };
+
+    window.stopPixletEditor = function() {
+        setBusy('btn-pixlet-stop', true);
+        fetch(PIXLET_EDITOR_URL + '/stop', {method: 'POST'})
+            .then(r => r.json())
+            .then(d => { showResult('result-pixlet', d.status === 'success', d.message || 'Stopped'); loadPixletEditor(); })
+            .catch(err => showResult('result-pixlet', false, 'Request failed: ' + err.message))
+            .finally(() => setBusy('btn-pixlet-stop', false));
+    };
+
+    // Initial load for both sections. Down here rather than at the shared init
+    // site above, because these are assignments to window rather than hoisted
+    // declarations -- calling them earlier in the file throws.
+    loadMqttBridge();
+    loadPixletEditor();
+
 })();
+
 </script>