python-materialsdb 0.2.0__tar.gz → 0.3.0__tar.gz

{python_materialsdb-0.2.0/src/python_materialsdb.egg-info → python_materialsdb-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-materialsdb
-Version: 0.2.0
+Version: 0.3.0
 Summary: A library to work with materialsdb.org open standard for building materials.
 Author-email: Cyril Waechter <cyrwae@hotmail.com>
 License-Expression: GPL-3.0-or-later
@@ -97,7 +97,10 @@ PYTHONPATH=src python3 -m materialsdb.gui
 
 The materials index uses schema v2: the first launch after upgrading rebuilds
 it automatically (previous index is discarded — source of truth is your cached
-XML). Click *refresh cache* once to repopulate.
+XML). *Refresh cache* downloads any newer producer files from
+materialsdb.org and re-ingests them — on a fresh machine it fills the
+empty list after one click, behind a progress dialog (cancellable). The
+app shows a notice when updates are available on materialsdb.org.
 
 Browse, sort and filter all cached materials; multi-select then either export
 a standalone `.ifc`, or open one of your own `.ifc` files and append the
@@ -129,7 +132,8 @@ Push materials straight from the picker into the IFC model open in
 [Bonsai](https://bonsai.ifcopenshell.org). Install it from the
 extension repository: in Blender, *Preferences ▸ Get Extensions ▸ ⌄ ▸
 Add Remote Repository* and add
-`https://cyrilwaechter.github.io/python-materialsdb/`, then install
+`https://cyrilwaechter.github.io/python-materialsdb/index.json`, then
+install
 *materialsdb listener* (updates appear in the same panel). Manual
 install stays available: build `dist/materialsdb_listener.zip` with
 `python3 dev_utils/build_bonsai_addon.py` and use
@@ -145,10 +149,15 @@ into the model's material library (identity + per-layer psets included);
 assigning them to objects stays a normal Bonsai action. Pushed
 constructions become typed elements (`IfcWallType`/`IfcSlabType`/
 `IfcRoofType` per the design usage) with their `IfcMaterialLayerSet`,
-visible in the outliner and revertible with Ctrl+Z. Round-trip: select
+visible in the outliner and revertible with Ctrl+Z. Each pushed type
+also carries its computed U-value as `ThermalTransmittance` in
+`Pset_WallCommon`/`Pset_SlabCommon`/`Pset_RoofCommon` (per the element
+type). Round-trip: select
 the wall (or its type) in Bonsai and hit *Send type to composer* in the
 materialsdb panel — the construction appears under *incoming from model*
-on the constructions page for editing. Layers whose material is not a
+on the constructions page for editing. Any layer's material can be
+replaced from the catalog with the pencil button or a double-click on
+the material row. Layers whose material is not a
 materialsdb material are kept as "model material" placeholders (λ read
 from the model) and re-attach to the same material on push-back.
 

{python_materialsdb-0.2.0 → python_materialsdb-0.3.0}/README.md

@@ -70,7 +70,10 @@ PYTHONPATH=src python3 -m materialsdb.gui
 
 The materials index uses schema v2: the first launch after upgrading rebuilds
 it automatically (previous index is discarded — source of truth is your cached
-XML). Click *refresh cache* once to repopulate.
+XML). *Refresh cache* downloads any newer producer files from
+materialsdb.org and re-ingests them — on a fresh machine it fills the
+empty list after one click, behind a progress dialog (cancellable). The
+app shows a notice when updates are available on materialsdb.org.
 
 Browse, sort and filter all cached materials; multi-select then either export
 a standalone `.ifc`, or open one of your own `.ifc` files and append the
@@ -102,7 +105,8 @@ Push materials straight from the picker into the IFC model open in
 [Bonsai](https://bonsai.ifcopenshell.org). Install it from the
 extension repository: in Blender, *Preferences ▸ Get Extensions ▸ ⌄ ▸
 Add Remote Repository* and add
-`https://cyrilwaechter.github.io/python-materialsdb/`, then install
+`https://cyrilwaechter.github.io/python-materialsdb/index.json`, then
+install
 *materialsdb listener* (updates appear in the same panel). Manual
 install stays available: build `dist/materialsdb_listener.zip` with
 `python3 dev_utils/build_bonsai_addon.py` and use
@@ -118,10 +122,15 @@ into the model's material library (identity + per-layer psets included);
 assigning them to objects stays a normal Bonsai action. Pushed
 constructions become typed elements (`IfcWallType`/`IfcSlabType`/
 `IfcRoofType` per the design usage) with their `IfcMaterialLayerSet`,
-visible in the outliner and revertible with Ctrl+Z. Round-trip: select
+visible in the outliner and revertible with Ctrl+Z. Each pushed type
+also carries its computed U-value as `ThermalTransmittance` in
+`Pset_WallCommon`/`Pset_SlabCommon`/`Pset_RoofCommon` (per the element
+type). Round-trip: select
 the wall (or its type) in Bonsai and hit *Send type to composer* in the
 materialsdb panel — the construction appears under *incoming from model*
-on the constructions page for editing. Layers whose material is not a
+on the constructions page for editing. Any layer's material can be
+replaced from the catalog with the pencil button or a double-click on
+the material row. Layers whose material is not a
 materialsdb material are kept as "model material" placeholders (λ read
 from the model) and re-attach to the same material on push-back.
 

{python_materialsdb-0.2.0 → python_materialsdb-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-materialsdb"
-version = "0.2.0"
+version = "0.3.0"
 description = "A library to work with materialsdb.org open standard for building materials."
 readme = "README.md"
 license = "GPL-3.0-or-later"

{python_materialsdb-0.2.0 → python_materialsdb-0.3.0}/src/materialsdb/cache.py

@@ -58,47 +58,75 @@ def get_producers_dir() -> pathlib.Path:
 Report = namedtuple("Report", ["existing", "updated", "deleted"])
 
 
-def update_producers_data(url_list=MATERIALSDBINDEXURLLIST):
-    existing = []
-    updated = []
-    deleted = []
-    for index in url_list:
-        report = update_producers_from_index(index)
-        existing.extend(report.existing)
-        updated.extend(report.updated)
-        deleted.extend(report.deleted)
-    return Report(existing, updated, deleted)
+class _IndexPlan:
+    def __init__(self, index, new_index, unchanged, todos):
+        self.index = index
+        self.new_index = new_index
+        self.unchanged = unchanged
+        self.todos = todos  # list[(company, cached_producer|None, producer_path)]
 
 
-def update_producers_from_index(index):
+def _plan_index(index):
     cached_index = parse_cached_index(index)
     cached_root = cached_index.getroot()
     with urllib.request.urlopen(index) as response:
         new_index = etree.parse(response)
     new_root = new_index.getroot()
     producers_dir = get_producers_dir()
-    has_index_update = False
-    existing = []
-    updated = []
-    deleted = []
+    unchanged = []
+    todos = []
     for company in new_root:
         cached_producer = get_by_id(cached_root, company.get("id"))
         producer_path = producers_dir / pathlib.Path(company.get("href")).name
         if not require_update(cached_producer, company) and producer_path.exists():
-            existing.append(producer_path)
+            unchanged.append(producer_path)
             continue
-        if cached_producer:
-            cached_path = producers_dir / pathlib.Path(cached_producer.get("href")).name
-            deleted.append(cached_path)
-            cached_path.unlink(True)
-        has_index_update = True
-        urllib.request.urlretrieve(company.get("href"), producer_path)
-        updated.append(producer_path)
-    if has_index_update:
-        new_index.write(str(get_cached_index_path(index)))
+        todos.append((company, cached_producer, producer_path))
+    return _IndexPlan(index, new_index, unchanged, todos)
+
+
+def update_producers_data(url_list=MATERIALSDBINDEXURLLIST, on_progress=None):
+    """on_progress(done, total, name) is called after each producer download
+    with a global running total; returning a truthy value stops the update
+    between two downloads (the partial Report is returned as-is)."""
+    plans = [_plan_index(index) for index in url_list]
+    total = sum(len(plan.todos) for plan in plans)
+    existing, updated, deleted = [], [], []
+    done = 0
+    for plan in plans:
+        for company, cached_producer, producer_path in plan.todos:
+            if cached_producer is not None:
+                cached_path = get_producers_dir() / pathlib.Path(cached_producer.get("href")).name
+                deleted.append(cached_path)
+                cached_path.unlink(True)
+            urllib.request.urlretrieve(company.get("href"), producer_path)
+            updated.append(producer_path)
+            done += 1
+            if on_progress is not None and on_progress(done, total, pathlib.Path(company.get("href")).name):
+                return Report(existing, updated, deleted)
+        if plan.todos:
+            plan.new_index.write(str(get_cached_index_path(plan.index)))
+        existing.extend(plan.unchanged)
     return Report(existing, updated, deleted)
 
 
+def update_producers_from_index(index):
+    """Legacy single-index entry point (no progress callback)."""
+    return update_producers_data([index])
+
+
+def updates_available(url_list=MATERIALSDBINDEXURLLIST) -> bool:
+    """True when any remote company differs from the cached index."""
+    for index in url_list:
+        cached_root = parse_cached_index(index).getroot()
+        with urllib.request.urlopen(index) as response:
+            new_root = etree.parse(response).getroot()
+        for company in new_root:
+            if require_update(get_by_id(cached_root, company.get("id")), company):
+                return True
+    return False
+
+
 def producers():
     for producer in get_producers_dir().iterdir():
         if producer.suffix.lower() == ".xml":

{python_materialsdb-0.2.0 → python_materialsdb-0.3.0}/src/materialsdb/construction.py

@@ -89,7 +89,12 @@ def _direction(design_usage: str | None) -> str:
 def u_value(construction: Construction, store_, preset: str = "ISO6946") -> UResult:
     if preset not in RESISTANCE_PRESETS:
         raise ValueError(f"unknown preset: {preset} (available: {sorted(RESISTANCE_PRESETS)})")
-    direction = _direction(construction.design_usage)
+    return _u_for_direction(construction, store_, _direction(construction.design_usage), preset)
+
+
+def _u_for_direction(construction: Construction, store_, direction: str, preset: str = "ISO6946") -> UResult:
+    if direction not in RESISTANCE_PRESETS[preset]:
+        raise ValueError(f"unknown direction: {direction}")
     rsi, rse = RESISTANCE_PRESETS[preset][direction]
     country = config.get_country()
 
@@ -128,6 +133,24 @@ def u_value(construction: Construction, store_, preset: str = "ISO6946") -> URes
     return UResult(u=u, rsi=rsi, rse=rse, contributions=contributions, missing_lambda_ids=missing)
 
 
+_TYPE_TO_DIRECTION = {
+    "IfcWallType": "wall",
+    "IfcSlabType": "floor",
+    "IfcRoofType": "roof",
+}
+
+
+def u_values_by_type(construction: Construction, store_, types, preset: str = "ISO6946") -> dict[str, float | None]:
+    """U per element class, each with its own heat-flow direction
+    (wall / floor / roof Rsi-Rse). Unresolvable λ → None for that type."""
+    if preset not in RESISTANCE_PRESETS:
+        raise ValueError(f"unknown preset: {preset} (available: {sorted(RESISTANCE_PRESETS)})")
+    for cls in types:
+        if cls not in _TYPE_TO_DIRECTION:
+            raise ValueError(f"unknown element type: {cls}")
+    return {cls: _u_for_direction(construction, store_, _TYPE_TO_DIRECTION[cls], preset).u for cls in types}
+
+
 def _has_identity_pset(file, material) -> bool:
     from materialsdb.ifc.material_builder import MATERIALSDB_PSET, _materials_of
 

{python_materialsdb-0.2.0 → python_materialsdb-0.3.0}/src/materialsdb/gui/__main__.py

@@ -1,12 +1,22 @@
 """Entry point for the materialsdb picker web UI."""
 
 import argparse
+import threading
 import webbrowser
 
 from materialsdb.gui.discovery import remove_listener_info, write_listener_info
 from materialsdb.gui.server import make_server
 
 
+def _startup_update_check(state):
+    from materialsdb import cache
+
+    try:
+        state.updates_available = cache.updates_available()
+    except Exception:  # noqa: BLE001, S110 - advisory flag: quiet on network errors
+        pass
+
+
 def main():
     parser = argparse.ArgumentParser(prog="materialsdb-gui", description="Explore and export materialsdb materials.")
     parser.add_argument("--port", type=int, default=8619, help="local port (default 8619)")
@@ -16,6 +26,7 @@ def main():
     server = make_server(port=args.port)
     url = f"http://127.0.0.1:{server.server_address[1]}"
     write_listener_info(server.server_address[1], server.gui_state.token)
+    threading.Thread(target=_startup_update_check, args=(server.gui_state,), daemon=True).start()
     print(f"materialsdb picker on {url} (Ctrl+C to stop)")
     if not args.no_browser:
         webbrowser.open(url)

{python_materialsdb-0.2.0 → python_materialsdb-0.3.0}/src/materialsdb/gui/listener.py

@@ -140,12 +140,16 @@ def build_add_construction_payload(store_, body, country=None, lang=None):
         )
     if problems:
         return None, problems
+    types = _DESIGN_USAGE_TO_TYPES.get(construction.design_usage or "", GENERIC_TYPES)
     return {
         "action": "add_construction",
         "construction": {
             "name": construction.name,
             "design_usage": construction.design_usage,
-            "types": _DESIGN_USAGE_TO_TYPES.get(construction.design_usage or "", GENERIC_TYPES),
+            "types": types,
+            "u_values": {
+                cls: u for cls, u in cm.u_values_by_type(construction, store_, types).items() if u is not None
+            },
             "layers": layers,
         },
     }, []

{python_materialsdb-0.2.0 → python_materialsdb-0.3.0}/src/materialsdb/gui/server.py

@@ -3,6 +3,7 @@
 import http.server
 import json
 import secrets
+import threading
 import time
 from dataclasses import asdict
 from pathlib import Path
@@ -28,6 +29,77 @@ def _resolve_display_name(names, lang):
     return str(names.get(lang) or names.get("") or "")
 
 
+def _progress_cb(state):
+    def on_progress(done, total, name):
+        job = state.refresh_job
+        job.update(done=done, total=total, label=f"downloading producer files {done}/{total} ({name})")
+        return bool(job.get("cancelled"))
+
+    return on_progress
+
+
+def _refresh_worker(state, force):
+    import urllib.error
+
+    from materialsdb import cache, query
+
+    state.refresh_job = {
+        "status": "running",
+        "done": 0,
+        "total": 0,
+        "label": "checking materialsdb.org",
+        "error": None,
+        "report": None,
+        "cancelled": False,
+    }
+    try:
+        cache.update_producers_data(on_progress=_progress_cb(state))
+    except (OSError, urllib.error.URLError) as err:
+        state.refresh_job.update(status="error", error=f"cache update failed: {err}")
+        return
+    except Exception as err:  # noqa: BLE001 - a crashing job must never stay "running"
+        state.refresh_job.update(status="error", error=f"unexpected error: {err}")
+        return
+    if state.refresh_job.get("cancelled"):
+        state.refresh_job.update(status="cancelled")
+        return
+    state.refresh_job.update(label="indexing…")
+    try:
+        report = query.refresh(force=force)
+    except Exception as err:  # noqa: BLE001 - the job must never raise into the void
+        state.refresh_job.update(status="error", error=str(err))
+        return
+    if state.refresh_job.get("cancelled"):
+        state.refresh_job.update(status="cancelled")
+        return
+    downloaded = state.refresh_job["done"]
+    # successful refresh clears the flag; the startup check in __main__ or the
+    # next refresh re-populates it — never re-check the network here
+    state.updates_available = False
+    # query.refresh normally returns a store Report; tolerate a falsy one
+    existing = list(getattr(report, "existing", None) or ())
+    updated = list(getattr(report, "updated", None) or ())
+    deleted = list(getattr(report, "deleted", None) or ())
+    skipped = list(getattr(report, "skipped", None) or ())
+    duplicates = list(getattr(report, "duplicates", None) or ())
+    state.refresh_job = {
+        "status": "complete",
+        "done": 0,
+        "total": 0,
+        "label": "",
+        "error": None,
+        "cancelled": False,
+        "report": {
+            "existing": len(existing),
+            "updated": [str(p) for p in updated],
+            "deleted": len(deleted),
+            "skipped": len(skipped),
+            "duplicates": len(duplicates),
+            "downloaded": downloaded,
+        },
+    }
+
+
 class GuiState:
     def __init__(self, store=None):
         self.token = secrets.token_urlsafe(16)
@@ -38,6 +110,9 @@ class GuiState:
         self.listeners = {}
         # constructions pushed from a model (newest first, capped at 20)
         self.incoming = []
+        self.updates_available = False
+        # status: running|complete|error|cancelled; report: old 200 payload
+        self.refresh_job: dict | None = None
 
     def resolve_store(self):
         if self.store is not None:
@@ -386,6 +461,12 @@ class GuiHandler(http.server.BaseHTTPRequestHandler):
         if parsed.path == "/api/composer/incoming":
             self._send(200, {"incoming": self.state.incoming})
             return
+        if parsed.path == "/api/refresh/status":
+            self._refresh_status()
+            return
+        if parsed.path == "/api/updates":
+            self._send(200, {"updates_available": self.state.updates_available})
+            return
         if parsed.path.startswith("/api/constructions/"):
             from materialsdb import construction as cm
 
@@ -482,6 +563,8 @@ class GuiHandler(http.server.BaseHTTPRequestHandler):
                 self._config(payload)
             elif parsed.path == "/api/refresh":
                 self._refresh(payload)
+            elif parsed.path == "/api/refresh/cancel":
+                self._refresh_cancel()
             elif parsed.path == "/api/u_value":
                 self._u_value(store_, payload)
             elif parsed.path == "/api/export-construction":
@@ -637,22 +720,41 @@ class GuiHandler(http.server.BaseHTTPRequestHandler):
         self._send(200, {"ok": True})
 
     def _refresh(self, payload):
-        from materialsdb import query
+        job = self.state.refresh_job
+        if job is not None and job["status"] == "running":
+            self._send(409, {"error": "already running"})
+            return
+        force = bool(payload.get("force"))
+        threading.Thread(target=_refresh_worker, args=(self.state, force), daemon=True).start()
+        self._send(200, {"started": True})
+
+    def _refresh_cancel(self):
+        job = self.state.refresh_job
+        if job is None or job["status"] != "running":
+            self._send(404, {"error": "no refresh running"})
+            return
+        job["cancelled"] = True
+        if self.state.refresh_job is not job:
+            # the worker completed between our check and the flag write:
+            # the completed job must not be marked cancelled
+            job["cancelled"] = False
+            self._send(404, {"error": "no refresh running"})
+            return
+        self._send(200, {"ok": True})
 
-        report = query.refresh(force=bool(payload.get("force")))
-        self._send(
-            200,
-            {
-                "existing": len(report.existing),
-                "updated": [str(p) for p in report.updated],
-                "deleted": [str(p) for p in report.deleted],
-                "skipped": [str(p) for p in report.skipped],
-                "duplicates": [
-                    {"material_id": d.material_id, "kept": d.kept_source, "skipped": d.skipped_source}
-                    for d in report.duplicates
-                ],
-            },
-        )
+    def _refresh_status(self):
+        job = self.state.refresh_job
+        if job is None:
+            job = {
+                "status": "idle",
+                "done": 0,
+                "total": 0,
+                "label": "",
+                "error": None,
+                "report": None,
+                "cancelled": False,
+            }
+        self._send(200, dict(job))
 
     def _construction_save(self, store_, parsed, payload):
         from materialsdb import construction as cm

{python_materialsdb-0.2.0 → python_materialsdb-0.3.0}/src/materialsdb/gui/static/app-constructions.js

@@ -134,9 +134,11 @@ function renderLayers() {
       ? PickerCore.categoryColorStyle(layer.category || "Others", layer.ownColor)
       : "#fff";
     const isPlaceholder = !layer.material_id && layer.placeholder;
-    const nameCell = isPlaceholder
+    const replaceBtn = `<span data-role="replace" data-index="${index}" style="display:inline-block;transform:scaleX(-1) rotate(75deg);cursor:pointer;margin-left:.3rem" title="replace material">✏</span>`;
+    const cell = isPlaceholder
       ? `${esc(layer.placeholder.name || "(model material)")} <span style="color:#888;font-size:.8rem">model material</span>`
       : esc(layer.display_name || layer.material_id);
+    const nameCell = `${cell}${replaceBtn}`;
     return `<tr data-index="${index}"${selectedAttr} style="cursor:pointer;border-left:4px solid ${catColor}">` +
       `<td>${index + 1}</td><td data-role="name">${nameCell}</td>` +
       `<td>${thicknessCellHtml(layer, index)}</td>` +
@@ -144,11 +146,22 @@ function renderLayers() {
   }).join("");
   tbody.innerHTML = rsBoundaryRow("exterior") + rows + rsBoundaryRow("interior");
   bindThicknessControls();
+  tbody.querySelectorAll("span[data-role=replace]").forEach((span) => {
+    span.addEventListener("click", (event) => {
+      event.stopPropagation();
+      openChooser(replaceLayerFromChooser(Number(span.dataset.index)));
+    });
+  });
   tbody.querySelectorAll("tr[data-index]").forEach((tr) => {
     tr.addEventListener("click", (event) => {
       if (event.target.tagName === "INPUT" || event.target.tagName === "SELECT") return;
       selectedRow = Number(tr.dataset.index);
-      renderLayers();
+      // toggle the highlight in place: rebuilding the row would destroy the
+      // dblclick target (the first click of a double-click re-rendered it,
+      // so the browser never found a common ancestor and dropped the event)
+      tbody.querySelectorAll("tr[data-index]").forEach((marked) => {
+        marked.style.background = Number(marked.dataset.index) === selectedRow ? "#eef" : "";
+      });
     });
   });
 }
@@ -475,6 +488,14 @@ $("delete").onclick = async () => {
   setStatus(`deleted ${name}`); loadList(); $("new").onclick();
 };
 $("add-layer").onclick = () => openChooser(addLayerFromChooser);
+$("layers").addEventListener("dblclick", (event) => {
+  if (event.target.closest("[data-role=replace]")) return;
+  const td = event.target.closest("td[data-role=name]");
+  if (!td) return;
+  const tr = td.closest("tr");
+  if (!tr || tr.dataset.index === undefined) return;  // boundary rows have no data-index
+  openChooser(replaceLayerFromChooser(Number(tr.dataset.index)));
+});
 
 async function addLayerFromChooser(picked) {
   const items = Array.isArray(picked) ? picked : [{ material_id: picked }];
@@ -503,6 +524,22 @@ async function addLayerFromChooser(picked) {
   if (added) await refreshU();
   else if (items.length) setStatus("selected materials already in construction");
 }
+
+function replaceLayerFromChooser(index) {
+  return async (picked) => {
+    const it = (Array.isArray(picked) ? picked : [{ material_id: picked }])[0];
+    if (!it || !it.material_id) { setStatus("no material picked"); return; }
+    const previous = layers[index];
+    const layer = { material_id: it.material_id, thickness_m: previous ? previous.thickness_m : 0.2 };
+    layers[index] = layer;
+    selectedRow = index;
+    renderLayers();
+    await attachLayerChoices(layer);
+    renderLayers();
+    await refreshU();
+    setStatus(`replaced layer ${index + 1} material`);
+  };
+}
 document.querySelector("[data-move=up]").onclick = () => {
   if (selectedRow > 0) { [layers[selectedRow - 1], layers[selectedRow]] = [layers[selectedRow], layers[selectedRow - 1]]; selectedRow -= 1; renderLayers(); refreshU(); }
 };
@@ -608,6 +645,7 @@ document.getElementById("country")?.addEventListener("change", async () => {
 
 /* --- chooser: embedded full picker via iframe --- */
 function openChooser(onPick) {
+  if (document.getElementById("chooser")) return;
   const overlay = document.createElement("div");
   overlay.id = "chooser";
   overlay.style.cssText = "position:fixed;inset:0;background:rgba(0,0,0,.35);display:flex;align-items:center;justify-content:center;z-index:1000";

{python_materialsdb-0.2.0 → python_materialsdb-0.3.0}/src/materialsdb/gui/static/app.js

@@ -119,6 +119,11 @@ async function loadMaterials() {
   const params = new URLSearchParams();
   params.set("lang", lang);
   const { materials } = await api(`/api/materials?${params}`);
+  const hint = document.getElementById("hint");
+  if (hint) {
+    hint.style.display = materials.length ? "none" : "block";
+    hint.textContent = "No materials cached yet — click Refresh to download from materialsdb.org";
+  }
   allMaterials = materials;
   renderHeader();
   applyModel();
@@ -407,14 +412,71 @@ async function sendToBonsai() {
 
 function setStatus(text) { $("status").textContent = text; return text; }
 
+async function syncUpdatesBanner() {
+  const banner = document.getElementById("updates");
+  if (!banner) return;
+  try {
+    const { updates_available } = await api("/api/updates");
+    banner.style.display = updates_available ? "inline" : "none";
+  } catch {}
+}
+
 $("export").onclick = () => pickIds("export").catch((err) => setStatus(err.message));
 $("pick").onclick = () => pickIds("pick").catch((err) => setStatus(err.message));
 $("open").onclick = () => openSession().catch((err) => setStatus(err.message));
 $("save").onclick = () => saveSession().catch((err) => setStatus(err.message));
-$("refresh").onclick = async () => {
-  const report = await api("/api/refresh", { method: "POST", body: "{}" });
-  setStatus(`cache refreshed: ${report.existing} unchanged, ${report.updated.length} updated`);
-};
+$("refresh").onclick = runRefresh;
+
+async function runRefresh() {
+  const existing = document.getElementById("refresh-overlay");
+  if (existing) return;
+  const overlay = document.createElement("div");
+  overlay.id = "refresh-overlay";
+  overlay.style.cssText = "position:fixed;inset:0;background:rgba(0,0,0,.35);display:flex;align-items:center;justify-content:center;z-index:1000";
+  overlay.innerHTML = `<div style="background:#fff;border-radius:6px;padding:1rem 1.2rem;min-width:22rem;display:flex;flex-direction:column;gap:.6rem">` +
+    `<b>refreshing materialsdb cache</b>` +
+    `<div style="height:.6rem;background:#eee;border-radius:.3rem;overflow:hidden"><div id="refresh-bar" style="height:100%;width:0;background:#468;border-radius:.3rem;transition:width .3s"></div></div>` +
+    `<div style="display:flex;justify-content:space-between;align-items:center"><span id="refresh-label" style="color:#666">starting…</span>` +
+    `<button id="refresh-cancel">cancel</button></div></div>`;
+  document.body.appendChild(overlay);
+  overlay.querySelector("#refresh-cancel").onclick = () =>
+    api("/api/refresh/cancel", { method: "POST", body: "{}" }).catch(() => {});
+  try {
+    await api("/api/refresh", { method: "POST", body: "{}" });
+  } catch (err) {
+    overlay.remove();
+    setStatus(err.message);
+    return;
+  }
+  let job = null;
+  for (let i = 0; i < 200; i++) {
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    try {
+      job = await api("/api/refresh/status");
+    } catch {
+      overlay.remove();
+      setStatus("server unreachable while refreshing");
+      return;
+    }
+    if (job.status !== "running" && job.status !== "idle") break;
+    const bar = overlay.querySelector("#refresh-bar");
+    bar.style.width = job.total ? `${Math.max(4, Math.round((job.done / job.total) * 100))}%` : "4%";
+    overlay.querySelector("#refresh-label").textContent = job.label || "…";
+  }
+  overlay.remove();
+  if (job && job.status === "cancelled") {
+    setStatus(`refresh cancelled (${job.done}/${job.total || "?"} downloaded)`);
+  } else if (job && job.status === "error") {
+    setStatus(job.error || "refresh failed");
+  } else if (job && job.report) {
+    const r = job.report;
+    setStatus(`cache refreshed: ${r.downloaded} downloaded, ${r.existing} unchanged, ${r.updated.length} indexed`);
+  } else {
+    setStatus("refresh still running in background — reopening it will show its progress");
+  }
+  await loadMaterials();
+  await syncUpdatesBanner();
+}
 $("send-bonsai").onclick = () => sendToBonsai().catch((err) => setStatus(err.message));
 const bonsaiTarget = PickerCore.startTargetPoll(api, $("bonsai-target"), $("send-bonsai"));
 
@@ -429,12 +491,14 @@ $("lang").addEventListener("change", async () => {
   await api("/api/config", { method: "POST", body: JSON.stringify({ lang }) });
   detailCache.clear();
   await loadMaterials();
+  await syncUpdatesBanner();
 });
 
 $("country").addEventListener("change", async () => {
   await api("/api/config", { method: "POST", body: JSON.stringify({ country: $("country").value }) });
   detailCache.clear();
   await loadMaterials();
+  await syncUpdatesBanner();
 });
 
 $("preview").onclick = async () => {
@@ -449,3 +513,4 @@ document.getElementById("settings-tab").addEventListener("click", (e) => {
 });
 
 loadMaterials();
+syncUpdatesBanner();