python-materialsdb 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

materialsdb/gui/server.py

@@ -9,14 +9,26 @@ from dataclasses import asdict
 from pathlib import Path
 from urllib.parse import parse_qs, unquote, urlparse
 
-from materialsdb import config, utils
+from materialsdb import config, schemes, utils
 from materialsdb.construction import finite_or_none
 from materialsdb.ifc.material_builder import add_material
+from materialsdb.store import FINGERPRINT_SCHEME
 
 STATIC_DIR = Path(__file__).with_name("static")
 
 _LISTENER_STALE_S = 5.0
 
+# model statuses
+_ABSENT = "absent"
+_CURRENT = "current"
+_CHANGED = "changed"
+_UNKNOWN = "unknown"
+_GONE = "gone"
+
+# producer geometry is resolved per country and can round-trip through JSON;
+# thickness comparisons use the shared micrometre tolerance (utils)
+_SCALAR_REPORT_FIELDS = ("name", "description", "category", "color", "style_name")
+
 
 def _float(value):
     try:
@@ -26,7 +38,257 @@ def _float(value):
 
 
 def _resolve_display_name(names, lang):
-    return str(names.get(lang) or names.get("") or "")
+    for key in (lang, "", "en"):
+        value = names.get(key)
+        if value:
+            return str(value)
+    return str(next((value for value in names.values() if value), ""))
+
+
+def _active_model_path(state) -> str | None:
+    """The ``model_path`` of the listener seen most recently (non-empty)."""
+    listeners = [listener for listener in state.listeners.values() if listener.get("model_path")]
+    if not listeners:
+        return None
+    return max(listeners, key=lambda listener: listener.get("last_seen") or 0.0)["model_path"]
+
+
+def _status_from_entry(store_, entry, material_id) -> str:
+    """Derive a material's model status from its cached model-map entry."""
+    if entry is None:
+        return _ABSENT
+    digest = store_.material_fingerprint(material_id)
+    if digest is None:
+        return _GONE
+    # A model entry without a per-layer map (no org_layer) is a legacy
+    # baseline: there is nothing to match or report, so it is never `changed`.
+    if not entry.get("layers"):
+        return _UNKNOWN
+    fingerprint = entry.get("fingerprint")
+    if not fingerprint or entry.get("scheme") != FINGERPRINT_SCHEME:
+        return _UNKNOWN
+    if fingerprint != digest:
+        return _CHANGED
+    return _CURRENT
+
+
+def _material_status(store_, model_path, material_id) -> str:
+    """Status of ``material_id`` in the model cached under ``model_path``."""
+    if not model_path:
+        return _ABSENT
+    entry = store_.get_model_materials(model_path).get(material_id)
+    return _status_from_entry(store_, entry, material_id)
+
+
+def _new_layers(store_, material_id) -> list[dict]:
+    """The current store layers of ``material_id`` as {layer_id, thick} (metres)."""
+    from materialsdb.gui.listener import build_add_materials_payload
+
+    payload, _missing = build_add_materials_payload(store_, [{"id": material_id}])
+    layers = []
+    for entry in payload["materials"]:
+        org_layer = (entry.get("psets") or {}).get("materialsdb.org_layer") or {}
+        thick = org_layer.get("thick")
+        if thick is None:
+            thick = (entry.get("layer") or {}).get("thick_m")
+        layers.append({"layer_id": str(entry.get("layer_id") or ""), "thick": thick})
+    return layers
+
+
+def _layer_candidates(model_layer, new_layers) -> list[str]:
+    """New layer ids a single model layer can be updated to, in preference order."""
+    model_layer_id = model_layer.get("layer_id")
+    if model_layer_id:
+        for new_layer in new_layers:
+            if new_layer["layer_id"] == str(model_layer_id):
+                return [new_layer["layer_id"]]
+    thick = model_layer.get("thick")
+    matches = []
+    if thick:
+        matches = [
+            new_layer["layer_id"]
+            for new_layer in new_layers
+            if new_layer["thick"] is not None and abs(new_layer["thick"] - thick) <= utils.THICKNESS_EPS_M
+        ]
+    if matches:
+        return matches
+    if len(new_layers) == 1:
+        # λ-only materials have a single layer with no thickness to match on
+        return [new_layers[0]["layer_id"]]
+    # No thickness match and several variants: propose them so the user can
+    # choose (the model layer's own thickness is never changed).
+    return [new_layer["layer_id"] for new_layer in new_layers]
+
+
+def _layer_key(model_layer) -> str:
+    """Stable per-model-layer key: the IfcMaterial entity id, falling back to
+    the org_layer GUID for older maps."""
+    return str(model_layer.get("entity_id") or model_layer.get("layer_id") or "")
+
+
+def _match_layers(store_, material_id, model_layers) -> dict:
+    """Match the model's layers onto the current store version.
+
+    Returns ``{state, mapping, candidates}`` where state is one of
+    ``updatable`` / ``ambiguous`` / ``unmatched`` / ``unknown``; keys are
+    per-model-layer entity ids."""
+    summary = store_.get_summary(material_id)
+    if summary is None:
+        return {"state": _UNKNOWN, "mapping": {}, "candidates": {}}
+    if summary.type != "simple":
+        # btk/complex materials cannot be updated in place layer by layer
+        return {"state": "unmatched", "mapping": {}, "candidates": {}}
+    if not model_layers:
+        return {"state": _UNKNOWN, "mapping": {}, "candidates": {}}
+    new_layers = _new_layers(store_, material_id)
+    if not new_layers:
+        return {"state": "unmatched", "mapping": {}, "candidates": {}}
+
+    mapping: dict[str, str] = {}
+    candidates: dict[str, list[str]] = {}
+    unmatched = False
+    for model_layer in model_layers:
+        key = _layer_key(model_layer)
+        matches = _layer_candidates(model_layer, new_layers)
+        if len(matches) == 1:
+            mapping[key] = matches[0]
+        elif len(matches) > 1:
+            candidates[key] = matches
+        else:
+            unmatched = True
+    if unmatched:
+        return {"state": "unmatched", "mapping": mapping, "candidates": candidates}
+    if candidates:
+        return {"state": "ambiguous", "mapping": mapping, "candidates": candidates}
+    return {"state": "updatable", "mapping": mapping, "candidates": {}}
+
+
+def _force_plan(store_, model_path, choices) -> tuple[list[dict], dict, list[str]]:
+    """Plan a force update of every material used by walls/slabs/roofs.
+
+    Returns ``(entries, unresolved, skipped)``: resolvable model layers become
+    ``mode="update"`` ``force=True`` payload entries; layers the user has not
+    chosen yet land in ``unresolved`` with their candidate new-layer ids;
+    materials no longer in the store are ``skipped``."""
+    from materialsdb.gui.listener import build_add_materials_payload
+
+    model = store_.get_model_materials(model_path)
+    entries: list[dict] = []
+    unresolved: dict = {}
+    skipped: list[str] = []
+    for material_id, entry in model.items():
+        if not entry.get("used_in"):
+            continue
+        if store_.material_fingerprint(material_id) is None:
+            skipped.append(material_id)
+            continue
+        model_layers = entry.get("layers") or []
+        mapping = dict(_match_layers(store_, material_id, model_layers)["mapping"])
+        for entity_id, new_layer_id in (choices or {}).items():
+            if any(_layer_key(layer) == str(entity_id) for layer in model_layers):
+                mapping[str(entity_id)] = str(new_layer_id)
+        missing = [layer for layer in model_layers if _layer_key(layer) not in mapping]
+        if missing:
+            unresolved[material_id] = [
+                {
+                    "entity_id": _layer_key(layer),
+                    "thick": layer.get("thick"),
+                    "candidates": _layer_candidates(layer, _new_layers(store_, material_id)),
+                }
+                for layer in missing
+            ]
+            continue
+        payload, _missing = build_add_materials_payload(
+            store_, [{"id": material_id, "mode": "update", "force": True, "update": mapping}]
+        )
+        for entry in payload["materials"]:
+            layer_id = str(entry.get("layer_id") or "")
+            targets = {key: value for key, value in mapping.items() if value == layer_id}
+            if not targets:
+                continue
+            entry["update"] = targets
+            entries.append(entry)
+    return entries, unresolved, skipped
+
+
+def _restyle_plan(store_, model_path, scheme, ignore_producer_color):
+    """(entries, skipped): style-only entries for every model material still in the store."""
+    from materialsdb.gui.listener import style_for
+
+    entries, skipped = [], []
+    for material_id in store_.get_model_materials(model_path):
+        material = store_.get(material_id)
+        if material is None:
+            skipped.append(material_id)
+            continue
+        style_name, rgb = style_for(
+            getattr(material.information, "color", None),
+            str(getattr(material.information, "group", "") or ""),
+            scheme=scheme,
+            ignore_producer_color=ignore_producer_color,
+        )
+        entries.append(
+            {
+                "material_id": material_id,
+                "style_name": style_name,
+                "style_color": [round(component, 6) for component in rgb],
+            }
+        )
+    return entries, skipped
+
+
+def _lambda_value(entry) -> float | None:
+    thermal = (entry.get("psets") or {}).get("materialsdb.org_thermal") or {}
+    return thermal.get("lambda_value_dry")
+
+
+def _change_report(store_, model_path, material_id, model_layers, mapping) -> tuple[list[dict], bool]:
+    """Old → new schedule of the fields that changed since the push snapshot.
+
+    Snapshots are keyed by the *model* layer id recorded at push time, which may
+    have been re-keyed upstream; pair each model layer to its matched current
+    store layer via ``mapping`` (model layer id → new layer id). Returns
+    ``(report, has_snapshot)``; ``([], False)`` when nothing was pushed."""
+    from materialsdb.gui.listener import build_add_materials_payload
+
+    payload, _missing = build_add_materials_payload(store_, [{"id": material_id}])
+    entries = payload["materials"]
+    by_layer = {str(entry.get("layer_id") or ""): entry for entry in entries}
+    fallback_entry = entries[0] if entries else None
+    report: list[dict] = []
+    has_snapshot = False
+    scalars_done: set[str] = set()
+    for model_layer in model_layers:
+        model_layer_id = str(model_layer.get("layer_id") or "")
+        snapshot = store_.get_pushed_material(model_path, material_id, model_layer_id or None)
+        if snapshot is None:
+            continue
+        has_snapshot = True
+        new_layer_id = mapping.get(_layer_key(model_layer))
+        paired_entry = by_layer.get(new_layer_id) if new_layer_id is not None else None
+        # a model layer with no matched current layer can still surface the
+        # material-level scalar changes against any current entry
+        comparison_entry = paired_entry if paired_entry is not None else fallback_entry
+        if comparison_entry is None:
+            continue
+        for field in _SCALAR_REPORT_FIELDS:
+            if field in scalars_done:
+                continue
+            old, new = snapshot.get(field), comparison_entry.get(field)
+            if old != new:
+                report.append({"field": field, "old": old, "new": new})
+            scalars_done.add(field)
+        if paired_entry is None:
+            # thickness/lambda can only be compared against a matched layer
+            continue
+        old_thick = (snapshot.get("layer") or {}).get("thick_m")
+        new_thick = (paired_entry.get("layer") or {}).get("thick_m")
+        if old_thick != new_thick:
+            report.append({"field": "thickness", "old": old_thick, "new": new_thick})
+        old_lambda, new_lambda = _lambda_value(snapshot), _lambda_value(paired_entry)
+        if old_lambda != new_lambda:
+            report.append({"field": "lambda", "old": old_lambda, "new": new_lambda})
+    return report, has_snapshot
 
 
 def _progress_cb(state):
@@ -108,6 +370,8 @@ class GuiState:
         self.file = None
         # client_id -> {"model_path": str, "last_seen": float, "pending": dict | None, "last_status": dict | None}
         self.listeners = {}
+        # most recent model path whose map was cached (served when offline)
+        self.last_model_path: str | None = None
         # constructions pushed from a model (newest first, capped at 20)
         self.incoming = []
         self.updates_available = False
@@ -215,14 +479,28 @@ class GuiHandler(http.server.BaseHTTPRequestHandler):
             self._send(400, {"error": "client_id required"})
             return
         self._prune_listeners()
+        model_path = str(payload.get("model_path") or "")
+        if model_path:
+            self.state.last_model_path = model_path
         self.state.listeners[client_id] = {
-            "model_path": str(payload.get("model_path") or ""),
+            "model_path": model_path,
             "last_seen": time.time(),
             "pending": None,
             "last_status": None,
         }
         self._send(200, {"ok": True})
 
+    def _listener_model(self, payload):
+        model_path = str(payload.get("model_path") or "")
+        materials = payload.get("materials")
+        if not isinstance(materials, dict):
+            self._send(400, {"error": "materials must be an object"})
+            return
+        if model_path:
+            self.state.last_model_path = model_path
+        self.state.resolve_store().set_model_materials(model_path, materials)
+        self._send(200, {"ok": True})
+
     def _listener_poll(self, parsed):
         client_id = (parse_qs(parsed.query).get("client_id") or [""])[0]
         listener = self.state.listeners.get(client_id)
@@ -244,6 +522,78 @@ class GuiHandler(http.server.BaseHTTPRequestHandler):
         except ConnectionError:
             self.close_connection = True
 
+    def _model_force_update(self, store_, payload):
+        """Queue an in-place refresh of every model material used by
+        walls/slabs/roofs, regardless of its fingerprint state."""
+        model_path = _active_model_path(self.state) or self.state.last_model_path
+        if not model_path:
+            self._send(409, {"error": "no model connected"})
+            return
+        client_id = next(
+            (cid for cid, listener in self.state.listeners.items() if listener.get("model_path") == model_path),
+            None,
+        )
+        if client_id is None:
+            self._send(409, {"error": "no listener connected for the active model"})
+            return
+        entries, unresolved, skipped = _force_plan(store_, model_path, payload.get("choices") or {})
+        if entries:
+            resolved = {"action": "add_materials", "materials": entries}
+            store_.record_pushed_materials(model_path, entries)
+            listener = self.state.listeners[client_id]
+            listener["pending"] = resolved
+            listener["last_status"] = {"status": "pending", "detail": ""}
+        self._send(
+            200,
+            {
+                "queued": len(entries),
+                "unresolved": unresolved,
+                "skipped": skipped,
+                "counts": {
+                    "queued": len(entries),
+                    "unresolved": len(unresolved),
+                    "skipped": len(skipped),
+                },
+            },
+        )
+
+    def _model_restyle(self, store_, payload):
+        """Queue a style-only restyle of every material cached for a model.
+
+        With an explicit ``client_id`` the named listener's model is targeted;
+        otherwise the active model (most recent listener, then last cached path)
+        keeps the historical behaviour."""
+        requested = str(payload.get("client_id") or "")
+        if requested:
+            listener = self.state.listeners.get(requested)
+            if listener is None:
+                self._send(404, {"error": f"unknown listener: {requested}"})
+                return
+            if not listener.get("model_path"):
+                self._send(409, {"error": "listener has no model connected"})
+                return
+            client_id = requested
+            model_path = listener["model_path"]
+        else:
+            model_path = _active_model_path(self.state) or self.state.last_model_path
+            if not model_path:
+                self._send(409, {"error": "no model connected"})
+                return
+            client_id = next(
+                (cid for cid, listener in self.state.listeners.items() if listener.get("model_path") == model_path),
+                None,
+            )
+            if client_id is None:
+                self._send(409, {"error": "no listener connected for the active model"})
+                return
+        scheme = config.get_scheme() or schemes.DEFAULT_SCHEME
+        entries, skipped = _restyle_plan(store_, model_path, scheme, config.get_ignore_producer_color())
+        if entries:
+            listener = self.state.listeners[client_id]
+            listener["pending"] = {"action": "restyle", "materials": entries}
+            listener["last_status"] = {"status": "pending", "detail": ""}
+        self._send(200, {"queued": len(entries), "skipped": skipped, "scheme": scheme})
+
     def _listener_send(self, store_, payload):
         client_id = str(payload.get("client_id") or "")
         listener = self.state.listeners.get(client_id)
@@ -252,6 +602,7 @@ class GuiHandler(http.server.BaseHTTPRequestHandler):
             return
         action = str(payload.get("action") or "add_materials")
         missing = []
+        warnings = []
         if action == "add_materials":
             from materialsdb.gui.listener import build_add_materials_payload
 
@@ -270,14 +621,23 @@ class GuiHandler(http.server.BaseHTTPRequestHandler):
                 return
             queued = len(resolved["construction"]["layers"])
             summary = f"construction '{resolved['construction']['name']}' ({queued} layer(s))"
+            warnings = [str(w) for w in resolved["construction"].get("warnings") or []]
         else:
             self._send(400, {"error": f"unsupported action: {action}"})
             return
+        # record what was pushed so a later task can diff the model against it
+        model_path = listener.get("model_path")
+        if model_path:
+            if action == "add_materials":
+                entries = resolved["materials"]
+            else:
+                entries = [layer["material"] for layer in resolved["construction"]["layers"] if layer.get("material")]
+            store_.record_pushed_materials(model_path, entries)
         listener["pending"] = resolved
         # a fresh push invalidates the previous applied/error mark: the
         # dropdown shows a pending state until the add-on reports the new one
         listener["last_status"] = {"status": "pending", "detail": ""}
-        self._send(200, {"ok": True, "queued": queued, "summary": summary, "missing": missing})
+        self._send(200, {"ok": True, "queued": queued, "summary": summary, "missing": missing, "warnings": warnings})
 
     def _listener_status(self, payload):
         client_id = str(payload.get("client_id") or "")
@@ -299,6 +659,56 @@ class GuiHandler(http.server.BaseHTTPRequestHandler):
         ]
         self._send(200, {"clients": clients})
 
+    def _model_changes(self, store_):
+        """Status of every cached model material, with the change report."""
+        model_path = _active_model_path(self.state) or self.state.last_model_path
+        if not model_path:
+            self._send(
+                200,
+                {
+                    "model_path": None,
+                    "seen_at": None,
+                    "counts": {"changed": 0, "gone": 0, "unknown": 0},
+                    "changed": [],
+                    "gone": [],
+                    "unknown": [],
+                },
+            )
+            return
+        model = store_.get_model_materials(model_path)
+        changed, gone, unknown = [], [], []
+        for material_id, entry in model.items():
+            status = _status_from_entry(store_, entry, material_id)
+            if status == _CHANGED:
+                model_layers = entry.get("layers") or []
+                matching = _match_layers(store_, material_id, model_layers)
+                report, has_snapshot = _change_report(
+                    store_, model_path, material_id, model_layers, matching["mapping"]
+                )
+                changed.append(
+                    {
+                        "material_id": material_id,
+                        "matching": matching,
+                        "report": report,
+                        "has_snapshot": has_snapshot,
+                    }
+                )
+            elif status == _GONE:
+                gone.append(material_id)
+            elif status == _UNKNOWN:
+                unknown.append(material_id)
+        self._send(
+            200,
+            {
+                "model_path": model_path,
+                "seen_at": store_.model_seen_at(model_path),
+                "counts": {"changed": len(changed), "gone": len(gone), "unknown": len(unknown)},
+                "changed": changed,
+                "gone": gone,
+                "unknown": unknown,
+            },
+        )
+
     def _composer_push(self, payload):
         name = str(payload.get("name") or "").strip()
         layers = payload.get("layers")
@@ -388,6 +798,23 @@ class GuiHandler(http.server.BaseHTTPRequestHandler):
                 return
             self._send(200, content_type="text/javascript; charset=utf-8", raw=js.encode("utf-8"))
             return
+        if parsed.path == "/settings.html":
+            try:
+                html = (STATIC_DIR / "settings.html").read_text(encoding="utf-8")
+            except FileNotFoundError:
+                self._send(404, {"error": "not found"})
+                return
+            html = html.replace("__TOKEN__", self.state.token)
+            self._send(200, content_type="text/html; charset=utf-8", raw=html.encode("utf-8"))
+            return
+        if parsed.path == "/settings.js":
+            try:
+                js = (STATIC_DIR / "settings.js").read_text(encoding="utf-8")
+            except FileNotFoundError:
+                self._send(404, {"error": "not found"})
+                return
+            self._send(200, content_type="text/javascript; charset=utf-8", raw=js.encode("utf-8"))
+            return
         if parsed.path == "/picker-core.js":
             try:
                 js = (STATIC_DIR / "picker-core.js").read_text(encoding="utf-8")
@@ -413,10 +840,13 @@ class GuiHandler(http.server.BaseHTTPRequestHandler):
                 lang=params.get("lang") or None,
             )
             lang = params.get("lang") or config.get_lang()
+            model_path = _active_model_path(self.state) or self.state.last_model_path
+            model = store_.get_model_materials(model_path) if model_path else {}
             materials = []
             for row in rows:
                 item = asdict(row)
                 item["display_name"] = _resolve_display_name(item["names"], lang)
+                item["model"] = _status_from_entry(store_, model.get(item["id"]), item["id"])
                 materials.append(item)
             self._send(200, {"materials": materials})
             return
@@ -441,10 +871,27 @@ class GuiHandler(http.server.BaseHTTPRequestHandler):
 
             self._send(200, {"constructions": cm.list_constructions()})
             return
+        if parsed.path == "/api/schemes":
+            self._schemes_list()
+            return
+        if parsed.path.startswith("/api/schemes/"):
+            self._scheme_get(parsed)
+            return
         if parsed.path == "/api/config":
             from materialsdb import config as cfg
 
-            self._send(200, {"lang": cfg.get_lang(), "country": cfg.get_country()})
+            stored_scheme = cfg.get_scheme()
+            self._send(
+                200,
+                {
+                    "lang": cfg.get_lang(),
+                    "country": cfg.get_country(),
+                    # effective scheme: a stored-but-absent name resolves to the default
+                    "scheme": stored_scheme if stored_scheme in schemes.available() else schemes.DEFAULT_SCHEME,
+                    "schemes": list(schemes.available()),
+                    "ignore_producer_color": cfg.get_ignore_producer_color(),
+                },
+            )
             return
         if parsed.path == "/api/listener/poll":
             if not self._authorized():
@@ -467,6 +914,9 @@ class GuiHandler(http.server.BaseHTTPRequestHandler):
         if parsed.path == "/api/updates":
             self._send(200, {"updates_available": self.state.updates_available})
             return
+        if parsed.path == "/api/model/changes":
+            self._model_changes(store_)
+            return
         if parsed.path.startswith("/api/constructions/"):
             from materialsdb import construction as cm
 
@@ -575,12 +1025,22 @@ class GuiHandler(http.server.BaseHTTPRequestHandler):
                 self._composer_push(payload)
             elif parsed.path == "/api/composer/incoming/consume":
                 self._composer_consume(payload)
+            elif parsed.path == "/api/schemes/import":
+                self._scheme_import(payload)
+            elif parsed.path.startswith("/api/schemes/"):
+                self._scheme_post(parsed, payload)
             elif parsed.path.startswith("/api/constructions/"):
                 self._construction_save(store_, parsed, payload)
             elif parsed.path == "/api/listener/register":
                 self._listener_register(payload)
+            elif parsed.path == "/api/listener/model":
+                self._listener_model(payload)
             elif parsed.path == "/api/listener/send":
                 self._listener_send(store_, payload)
+            elif parsed.path == "/api/model/force-update":
+                self._model_force_update(store_, payload)
+            elif parsed.path == "/api/model/restyle":
+                self._model_restyle(store_, payload)
             elif parsed.path == "/api/listener/status":
                 self._listener_status(payload)
             else:
@@ -717,8 +1177,104 @@ class GuiHandler(http.server.BaseHTTPRequestHandler):
             config.set_lang(str(lang).lower())
         if country:
             config.set_country(str(country).upper())
+        if "scheme" in payload:
+            scheme = str(payload["scheme"])
+            if scheme not in schemes.available():
+                self._send(400, {"error": f"unknown scheme: {scheme}"})
+                return
+            config.set_scheme(scheme)
+        if "ignore_producer_color" in payload:
+            config.set_ignore_producer_color(bool(payload["ignore_producer_color"]))
+        self._send(200, {"ok": True})
+
+    def _schemes_list(self):
+        names = list(schemes.available())
+        self._send(
+            200,
+            {
+                "schemes": [{"name": name, "builtin": name in schemes.BUILTIN} for name in names],
+                "error": schemes.load_error(),
+            },
+        )
+
+    def _scheme_get(self, parsed):
+        rest = unquote(parsed.path[len("/api/schemes/") :])
+        export = rest.endswith("/export")
+        name = rest[: -len("/export")] if export else rest
+        palette = schemes.get(name)
+        if palette is None:
+            self._send(404, {"error": f"unknown scheme: {name}"})
+            return
+        if export:
+            self._send(200, schemes.export_payload(name))
+            return
+        self._send(200, {"name": name, "builtin": name in schemes.BUILTIN, "categories": palette})
+
+    def _scheme_post(self, parsed, payload):
+        rest = unquote(parsed.path[len("/api/schemes/") :])
+        if rest.endswith("/rename"):
+            self._scheme_rename(rest[: -len("/rename")], payload)
+        elif rest.endswith("/delete"):
+            self._scheme_delete(rest[: -len("/delete")])
+        else:
+            self._scheme_save(rest, payload)
+
+    def _scheme_save(self, name, payload):
+        if name in schemes.BUILTIN:
+            self._send(400, {"error": f"built-in scheme {name!r} cannot be modified"})
+            return
+        categories = payload.get("categories") if isinstance(payload, dict) else None
+        try:
+            schemes.save(name, categories)
+        except schemes.SchemeError as err:
+            self._send(400, {"error": str(err)})
+            return
+        self._send(200, {"ok": True})
+
+    def _scheme_rename(self, name, payload):
+        new_name = payload.get("new_name") if isinstance(payload, dict) else None
+        if not isinstance(new_name, str):
+            self._send(400, {"error": "new_name must be a string"})
+            return
+        new_name = new_name.strip()  # schemes.rename stores the stripped name; config must match
+        try:
+            schemes.rename(name, new_name)
+        except schemes.SchemeError as err:
+            self._send(400, {"error": str(err)})
+            return
+        if config.get_scheme() == name:
+            config.set_scheme(new_name)
         self._send(200, {"ok": True})
 
+    def _scheme_delete(self, name):
+        if schemes.get(name) is None:
+            self._send(404, {"error": f"unknown scheme: {name}"})
+            return
+        if name in schemes.BUILTIN:
+            self._send(400, {"error": f"built-in scheme {name!r} cannot be deleted"})
+            return
+        active = config.get_scheme() == name
+        try:
+            schemes.delete(name)
+        except schemes.SchemeError as err:
+            self._send(400, {"error": str(err)})
+            return
+        if active:
+            config.set_scheme(schemes.DEFAULT_SCHEME)
+        self._send(200, {"ok": True})
+
+    def _scheme_import(self, payload):
+        name = payload.get("name") if isinstance(payload, dict) else None
+        if isinstance(name, str) and name in schemes.available():
+            self._send(409, {"error": f"a scheme named {name!r} already exists"})
+            return
+        try:
+            imported = schemes.import_payload(payload)
+        except schemes.SchemeError as err:
+            self._send(400, {"error": str(err)})
+            return
+        self._send(200, {"name": imported})
+
     def _refresh(self, payload):
         job = self.state.refresh_job
         if job is not None and job["status"] == "running":