refactor(settings-ui): HA-faithful redesign, auto-save, dedicated package (#1695)

* refactor(settings-ui): HA-faithful redesign, auto-save, dedicated package

- Move settings UI into src/ha_mcp/settings_ui/ package; extract markup,
  CSS and JS into settings.html/settings.css/settings.js loaded at import
- Restyle controls to match the HA frontend (ha-switch, ha-button, ha-alert,
  filled fields); replace persistent status pills with an HA-style toast
- Auto-save Server Settings fields (drop the Save buttons); keep the Backups
  and Tool-Security-Policies form Save buttons
- Add read-only/writes/deletes capability badges via a shared
  categorize_capability(), the same classifier that routes the
  read/write/delete proxies, so badge and routing never disagree
- Fix mid-save data loss in advanced auto-save: preserve pending edits across
  the post-save reload and guard against re-entrancy

* fix(packaging): point PyInstaller spec and parity comments at settings_ui/

The settings UI assets moved into src/ha_mcp/settings_ui/; the PyInstaller
spec still referenced the old src/ha_mcp/settings.js|css paths, failing every
binary Build. Point the spec at the settings_ui/ dir, add settings.html (now
a third mandatory asset), and bundle into ha_mcp/settings_ui. Update the stale
src/ha_mcp/settings.* / settings_ui.py cross-reference comments in the docs
site to the new paths.

* fix(settings-ui): address Gemini review (toast timer race, a11y)

- Clear the 200ms leave-removal timer when a toast is reused so a
  replace-on-new toast is not yanked from the DOM by the prior removal
- Add aria-live (polite/assertive) to the toast alongside role so every
  screen reader announces the update
- Drop the redundant aria-label on the theme <select> (the wrapping
  <label> with visible text already supplies the accessible name)
- Promote panel-server and panel-accessibility section titles from h3 to
  h2 so the heading hierarchy no longer skips a level (styling is
  class-controlled, no visual change)
- Add a regression test for the toast removal-timer race and assert aria-live

---------

Co-authored-by: Sergey <sergey@example.com>

Author: sergeykad

AGENTS.md

@@ -344,7 +344,8 @@ On merge, `hotfix-release.yml` runs semantic-release, creates GitHub release, sy
 ### Setup
 ```bash
 uv sync --group dev        # Install with dev dependencies
-uv run ha-mcp              # Run MCP server
+uv run ha-mcp              # Run MCP server (stdio; needs interactive stdin)
+uv run ha-mcp-web          # Run HTTP server; web settings UI at http://localhost:8086/mcp/settings (see src/ha_mcp/settings_ui/AGENTS.md)
 cp .env.example .env       # Configure HA connection
 ```
 
@@ -379,6 +380,8 @@ Test token centralized in `tests/test_constants.py`.
 ### Code Quality
 ```bash
 uv run ruff check src/ tests/ --fix
+# Note: --fix removes unused imports from non-__init__ modules (lefthook runs it on commit with
+# stage_fixed). When adding an import, include its first use in the same change or it gets stripped.
 uv run mypy src/
 ```
 

MANIFEST.in

@@ -1,5 +1,6 @@
 include README.md
 include LICENSE
-include src/ha_mcp/settings.js
-include src/ha_mcp/settings.css
+include src/ha_mcp/settings_ui/settings.html
+include src/ha_mcp/settings_ui/settings.js
+include src/ha_mcp/settings_ui/settings.css
 recursive-include src/ha_mcp/resources *.md *.json

packaging/binary/ha-mcp.spec

@@ -37,16 +37,15 @@ for dir_name in stdlib_dirs:
     if os.path.exists(dir_path):
         datas.append((dir_path, dir_name))
 
-# settings_ui.py reads settings.js and settings.css via Path(__file__).parent
-# at import, so a missing file would build a working-looking but broken binary.
-# collect_all('ha_mcp') below also picks them up via package-data, but add them
-# explicitly and WITHOUT an existence guard: both are mandatory, so let the
-# build fail loudly if either is absent rather than ship a broken binary
+# settings_ui/__init__.py reads settings.html, settings.js and settings.css via
+# Path(__file__).parent at import, so a missing file would build a working-looking
+# but broken binary. collect_all('ha_mcp') below also picks them up via package-data,
+# but add them explicitly and WITHOUT an existence guard: all three are mandatory, so
+# let the build fail loudly if any is absent rather than ship a broken binary
 # (PyInstaller dedups the duplicate datas entries).
-_settings_js = os.path.join(PROJECT_ROOT, 'src', 'ha_mcp', 'settings.js')
-datas.append((_settings_js, 'ha_mcp'))
-_settings_css = os.path.join(PROJECT_ROOT, 'src', 'ha_mcp', 'settings.css')
-datas.append((_settings_css, 'ha_mcp'))
+_settings_ui_dir = os.path.join(PROJECT_ROOT, 'src', 'ha_mcp', 'settings_ui')
+for _asset in ('settings.html', 'settings.js', 'settings.css'):
+    datas.append((os.path.join(_settings_ui_dir, _asset), 'ha_mcp/settings_ui'))
 
 binaries = []
 hiddenimports = []

pyproject.toml

@@ -54,7 +54,7 @@ package-dir = {"" = "src", "tests" = "tests"}
 packages = { find = { where = ["src", "."], include = ["ha_mcp*", "tests"] } }
 
 [tool.setuptools.package-data]
-ha_mcp = ["py.typed", "_pypi_marker", "settings.js", "settings.css", "resources/skills-vendor/**/*"]
+ha_mcp = ["py.typed", "_pypi_marker", "settings_ui/settings.html", "settings_ui/settings.js", "settings_ui/settings.css", "resources/skills-vendor/**/*"]
 
 [tool.mypy]
 python_version = "3.13"

site/src/layouts/Layout.astro

@@ -25,7 +25,7 @@ const { title } = Astro.props;
       // from localStorage with safe defaults. Auto is the default (#1574
       // review: follow the OS preference out of the box); Dark stays one
       // click away as a preset.
-      // Same logic as in src/ha_mcp/settings_ui.py head — both surfaces use
+      // Same logic as in src/ha_mcp/settings_ui/__init__.py head — both surfaces use
       // the same localStorage key names interpreted identically, but storage
       // is per-origin, so each surface keeps its own saved values. Any change
       // here must be mirrored there (and vice versa) or the surfaces drift
@@ -111,7 +111,7 @@ const { title } = Astro.props;
       // attributes. The Layout head anti-FOUC script already set the initial
       // attributes; this module keeps them in sync for the rest of the
       // session and persists user changes. The block from `const PREFS` to
-      // `const APPLY` must stay logically identical to src/ha_mcp/settings.js
+      // `const APPLY` must stay logically identical to src/ha_mcp/settings_ui/settings.js
       // (comments and formatting may differ) — enforced by
       // tests/src/unit/test_anti_fouc_parity.py.
       (function bindAccessibilityPrefs() {

site/src/styles/global.css

@@ -323,7 +323,7 @@ fieldset.a11y-options { border: 0; padding: 0; margin: 0; min-inline-size: auto;
 /* Preset chips (#1574 review): one-click theme presets modeled on Firefox
    Reader View's Colors menu. Each chip shows a miniature swatch of its
    actual scheme — fixed preview colors by design. Mirrors the same chip
-   palette in src/ha_mcp/settings.css. */
+   palette in src/ha_mcp/settings_ui/settings.css. */
 .a11y-preset-chip {
   width: 20px; height: 20px; border-radius: 5px; display: inline-flex;
   align-items: center; justify-content: center; font-size: 0.65rem; font-weight: 600;
@@ -355,7 +355,7 @@ fieldset.a11y-options { border: 0; padding: 0; margin: 0; min-inline-size: auto;
 .a11y-reset:hover { background: rgb(var(--surface-2)); color: var(--text-primary); }
 
 /* Light-mode background shade picker (#1572). Mirrors the same selectors
-   used in src/ha_mcp/settings.css so the docs site and the settings UI
+   used in src/ha_mcp/settings_ui/settings.css so the docs site and the settings UI
    honor the same localStorage shade key. Only the page background flips —
    surfaces (cards, glass-card) keep their tuned palette. */
 :root[data-theme="light"][data-shade="paper"] body.body-background { background-color: #f4ede0; }