quantui 0.7.0__tar.gz → 0.8.1__tar.gz

{quantui-0.7.0 → quantui-0.8.1}/CHANGELOG.md

@@ -7,6 +7,142 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-08-26
+
+### Added
+
+- **PNG export on the geometry-optimization trajectory, vibrational mode, and
+  molecule viewers** — the same camera-accurate Save-PNG capture already
+  available on the orbital isosurface and reorganization-energy geometry
+  viewers now covers every 3-D viewer in the app. The molecule viewer (shown
+  on the Calculate, Results, and Analysis tabs) captures only on the py3Dmol
+  backend, since Plotly already provides its own "download plot as PNG"
+  button; each of its three tabs gets an independent capture button so a
+  save from one tab can never be mislabeled with another tab's molecule or
+  overwrite another tab's file.
+
+## [0.8.0] - 2026-08-25
+
+### Added
+
+- **Transition-metal and coordination-complex support.** QuantUI now
+  recognizes and handles metal centers throughout the pipeline instead of
+  erroring or silently mishandling them: a pre-run guard catches
+  basis-coverage and charge/multiplicity problems before a run starts (with a
+  one-click "Switch to def2-SVP" fix when that alone resolves it); a GFN-FF
+  (xtb) pre-optimization backend actually relaxes coordination complexes,
+  since RDKit's organic valence model can't; the 3D viewer falls back to
+  py3Dmol instead of showing a "Visualization failed" box; a fetched
+  structure that resolves to a disconnected salt (e.g. cisplatin as separate
+  NH₃/HCl/Pt fragments) is flagged before you compute the wrong geometry;
+  coordination bonds are drawn dashed since 3Dmol.js's own bond perception
+  draws none to a metal; and an oxidation-state → spin-state multiplicity
+  suggestion engine proposes — never auto-sets — physically reasonable
+  multiplicities, naming the strong- vs weak-field ligand ambiguity where one
+  exists.
+- **14 bundled inorganic examples** (up from 3), GFN-FF-validated, spanning
+  octahedral (aqua and cyanide, high- and low-spin), tetrahedral, and
+  square-planar geometries — a teaching spread across spin states and
+  charges.
+- **Density fitting (RI)** as an opt-in SCF speedup — a large win for TD-DFT
+  and larger systems, roughly neutral for small single points, so it defaults
+  off. Shown on/off in the run-header provenance banner and flagged on the
+  result card ("⚡ RI") whenever it was actually applied.
+- **Mulliken Populations Analysis panel.** Per-atom Mulliken charges as a
+  table and bar chart after Single Point and Geometry Optimization runs, with
+  its own 3D viewer below the energy-level diagram: atoms colored by charge,
+  a center-of-mass dipole arrow, a color-vividness slider, and a
+  magnitude-only fallback when an older History result has ‖μ‖ but no saved
+  vector.
+- **NMR stick plot** with a ¹H/¹³C nucleus toggle, mirroring the existing
+  IR/UV-Vis panels; UV-Vis gains λ min/max axis-bound inputs.
+- **Click-to-measure atom selection** on the Analysis-tab viewer — click 2, 3,
+  or 4 atoms to read a bond length, angle, or dihedral, GaussView-style
+  (py3Dmol only for now; the Plotly viewer shows an explanatory message
+  instead of a silent no-op).
+- **Interactive XYZ input.** An atom-row builder and a cleanup-coordinates
+  accept/reject preview on the Calculate tab. Loading no longer enforces
+  charge/multiplicity parity at parse time — an odd-electron geometry loads
+  with a note instead of an error — and charge/multiplicity now stay owned by
+  Calculation Setup.
+- **Suggest charge & multiplicity from geometry** — a Calculation Setup
+  button proposes a neutral charge and a parity-compatible multiplicity from
+  the loaded structure, with an explicit Apply step rather than a silent
+  auto-fill.
+- **Export provenance.** Cube, PNG, and XYZ exports now carry method, basis,
+  and resolution (plus charge/multiplicity for XYZ) as embedded metadata, not
+  just filenames. Reorganization Energy gained its own XYZ export — one file
+  per distinct geometry — and a generalized PNG-capture bridge shared with
+  the isosurface viewer.
+- **Reorganization Energy is checkpointed.** The run most likely to be
+  interrupted — two geometry optimizations plus four SCF energies under one
+  Calculate-tab run — can now resume mid-leg instead of restarting from
+  scratch.
+- Orbital isosurfaces gained **smoothed meshes** (no more visible
+  marching-cubes facets) and a **wireframe finish toggle**.
+- TD-DFT's live status label now surfaces **per-root convergence**
+  ("TD-DFT root 3 converged @ 16.663 eV") during the excited-state solve,
+  instead of only a generic heartbeat.
+- A representative example gallery in the README and GitHub Pages site, and
+  new documentation for inorganic/coordination-complex support.
+
+### Fixed
+
+- **Heavy-element runs on an ECP basis were silently wrong.** Cisplatin and
+  similar complexes on LANL2DZ or def2 were built with the basis set but no
+  effective core potential attached, so PySCF ran all-electron against a
+  valence-only basis — converging to a nonphysical energy (positive HOMO)
+  with garbage gradients, which made a geometry optimization look like it was
+  diverging. ECPs are now attached consistently across every calculation
+  type.
+- **Frequency time estimates for app runs were systematically inflated.** The
+  estimator's fallback cost model wasn't told which pool a run came from, so
+  small-molecule Frequency estimates drew on the calibration pool's
+  fresh-subprocess import overhead instead of the app-run pool.
+- **Density fitting's "⚡ RI" badge could silently vanish.** TD-DFT, NMR,
+  Frequency, and Geometry Optimization results discarded the density-fitting
+  flag instead of storing it, and results were never persisting it to disk
+  for *any* calculation type — so even a live single point's badge
+  disappeared on History replay.
+- **A warm-start rejection could abort an otherwise-good calculation.** A
+  GPU-migrated mean-field rejecting a host density, or an incompatible
+  chkfile density, now logs a warning and retries from a scratch guess
+  instead of failing the whole run.
+- **Resuming a resumed-and-interrupted-again optimization under-reported its
+  progress** — the BFGS step counter wasn't seeded from the checkpoint, so it
+  restarted counting at 0 instead of continuing from what had already been
+  banked.
+- The resume list's Restore/Discard buttons now log an unexpected exception
+  instead of letting it escape into ipywidgets' click dispatch, matching
+  every other action button.
+- **Converged-but-near-degenerate metal runs no longer show a stale "HOMO ==
+  LUMO" warning** (observed on ferrocene) — the check now looks at the
+  converged gap, not PySCF's initial-guess density, which is always
+  near-degenerate for a bare d-manifold starting guess.
+- Click-to-measure's highlight halo no longer sits buried inside larger atoms
+  — it was a fixed radius; ball-and-stick atoms render at a radius scaled
+  from each element's VDW radius.
+- Analysis-tab polish: the welcome logo's SVG fill token, accordions
+  expanding automatically when they have data, scroll-to-top on tab entry,
+  and a shared seed-geometry dropdown for NMR Shielding.
+- **Older History results without saved Mulliken data now say so
+  explicitly**, with a magnitude-only note for dipoles recorded before the
+  full vector was saved, instead of a blank or misleading panel.
+- The CPU Apptainer build crashing on a floating `miniforge3:latest` base
+  image — libmamba choking on a fuzzy version pin. See
+  `apptainer/quantui.def`.
+
+### Changed
+
+- Three separate calc-type label→key mappings, and three separate
+  implementations of the Hill-formula algorithm, had drifted apart; each is
+  now a single shared helper.
+- `python -m quantui.estimator_eval`'s replay is now linear time instead of
+  quadratic.
+- ~380 scattered hex color literals across the chrome files are now one
+  theme token map.
+- Real type checking restored in CI.
+
 ## [0.7.0] - 2026-08-06
 
 ### Fixed

{quantui-0.7.0/quantui.egg-info → quantui-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantui
-Version: 0.7.0
+Version: 0.8.1
 Summary: An open-source frontend for DFT and post-HF quantum chemistry with PySCF
 Author-email: Jonathan Schultz <nccu-schultz-lab@users.noreply.github.com>
 License: MIT License
@@ -62,6 +62,9 @@ Requires-Dist: pyscf<3,>=2.13.0; extra == "pyscf"
 Requires-Dist: pyscf-properties; extra == "pyscf"
 Provides-Extra: ase
 Requires-Dist: ase<4,>=3.22.0; extra == "ase"
+Provides-Extra: xtb
+Requires-Dist: xtb>=22.1; extra == "xtb"
+Requires-Dist: ase<4,>=3.22.0; extra == "xtb"
 Provides-Extra: app
 Requires-Dist: voila<0.6,>=0.5.0; extra == "app"
 Requires-Dist: ipykernel<8,>=6.0.0; extra == "app"
@@ -81,7 +84,7 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
 Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
-Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: mypy<2.4,>=1.10; extra == "dev"
 Requires-Dist: types-requests>=2.28.0; extra == "dev"
 Requires-Dist: black~=26.5.1; python_version >= "3.10" and extra == "dev"
 Requires-Dist: black~=25.11.0; python_version < "3.10" and extra == "dev"
@@ -109,13 +112,49 @@ research and classroom use.
 
 ---
 
+## Example results
+
+Real output from QuantUI, straight from the app:
+
+<table>
+  <tr>
+    <td width="50%" align="center" valign="top">
+      <img src="docs/images/cisplatin_lumo.png" alt="Cisplatin LUMO isosurface" width="400"><br>
+      <b>Cisplatin LUMO</b><br>
+      <sub>Molecular-orbital isosurface · B3LYP/LANL2DZ (ECP on Pt &amp; Cl)</sub>
+    </td>
+    <td width="50%" align="center" valign="top">
+      <img src="docs/images/aspartame_orbital_diagram.png" alt="Aspartame orbital energy-level diagram" width="300"><br>
+      <b>Aspartame orbital energies</b><br>
+      <sub>Occupied/virtual levels · HOMO–LUMO gap 6.09 eV · B3LYP/6-31G*</sub>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" align="center" valign="top">
+      <img src="docs/images/benzene_ir_spectrum.png" alt="Benzene IR spectrum" width="400"><br>
+      <b>Benzene IR spectrum</b><br>
+      <sub>Analytical Hessian · ωB97X-D/6-31G · the four IR-active bands</sub>
+    </td>
+    <td width="50%" align="center" valign="top">
+      <img src="docs/images/cisplatin_optimization.png" alt="Cisplatin geometry-optimization energy convergence" width="400"><br>
+      <b>Geometry optimization</b><br>
+      <sub>Cisplatin relaxing over 21 BFGS steps · B3LYP/LANL2DZ</sub>
+    </td>
+  </tr>
+</table>
+
+▶ **[Live interactive gallery →](https://the-schultz-lab.github.io/QuantUI/#examples)** — rotate the 3D structures, and watch the optimization trajectory and a vibrational mode animate.
+
+---
+
 ## What it does
 
-- **Molecule input** — paste XYZ coordinates, browse an indexed three-tier
-  bundled library (20 presets + 156 curated molecules + ~1,900 QM9 structures,
-  searchable by name/formula), or run a structure search by name, SMILES,
-  InChI, PubChem CID, InChIKey, or CAS number (PubChem → NCI CACTUS → offline
-  bundled-library fallback; SMILES/InChI resolve locally with no network)
+- **Molecule input** — paste XYZ coordinates, browse an indexed bundled library
+  (organic presets + curated molecules + ~1,900 QM9 structures + **14
+  ready-to-run coordination complexes**, searchable by name/formula), or run a
+  structure search by name, SMILES, InChI, PubChem CID, InChIKey, or CAS number
+  (PubChem → NCI CACTUS → offline bundled-library fallback; SMILES/InChI resolve
+  locally with no network)
 - **Offline-first** — runs with no internet: the bundled molecule library and
   the 3D viewer's JavaScript (3Dmol.js) are vendored, so structure lookup and
   every 3D view work in an air-gapped classroom. (Network is used only for the
@@ -139,6 +178,18 @@ research and classroom use.
   animation; vibrational frequency analysis with animated normal modes,
   user-tunable playback FPS, and a per-result-directory disk cache so mode
   switches on repeat visits and history replay are instant
+- **Inorganic / coordination complexes** — first-class support for
+  transition-metal chemistry the organic pipeline can't handle: 14 bundled
+  metal complexes (octahedral / tetrahedral / square-planar; aqua, ammine,
+  cyanide, carbonyl, halide, oxo) with correct charge and spin; a pre-run guard
+  that catches a metal on an incompatible basis (nudges to def2-SVP / LANL2DZ)
+  and an impossible charge/multiplicity before the calculation starts; a
+  **spin-state helper** that suggests a multiplicity from a metal centre's
+  oxidation state and geometry (both high- and low-spin where the ligand field
+  decides — you pick); optional **GFN-FF (xtb) pre-optimization** that relaxes a
+  metal complex the classical organic force field can't; a warning when a name
+  search returns a disconnected salt instead of the coordinated complex; and a
+  viewer that draws the coordination bonds so the metal is never a lone dot
 - **Results persistence** — every calculation is saved automatically to a
   timestamped directory; a built-in browser lets you reload past results
   after a kernel restart; the full `pyscf.log` is shown inline
@@ -255,6 +306,26 @@ and result cards will display the compute device.
 Whenever gpu4pyscf can't offload a particular call, QuantUI falls back
 to CPU automatically and the result card reflects which device ran.
 
+### Optional: GFN-FF metal pre-optimization (xtb)
+
+The classical (MMFF/UFF) pre-optimizer relies on RDKit's organic valence
+model, which can't handle a transition metal. Install
+[xtb](https://github.com/grimme-lab/xtb) to enable **GFN-FF**, a general
+force field that relaxes coordination complexes across the whole periodic
+table. Fully optional — without it, metal pre-opt simply reports that it
+isn't available and points you to the DFT geometry optimization.
+
+```bash
+# Linux (PyPI wheels bundle the compiled library):
+pip install quantui[xtb]
+
+# Windows / macOS (no PyPI wheel — use conda-forge):
+conda install -c conda-forge xtb-python
+```
+
+QuantUI detects xtb automatically and routes metal pre-optimizations through
+GFN-FF; organic molecules still use the faster RDKit force field.
+
 ---
 
 ## Quick start
@@ -456,7 +527,13 @@ Five step-by-step notebooks in [`notebooks/tutorials/`](https://github.com/The-S
 ### Basis sets
 
 STO-3G (fast, good for learning) → 3-21G → 6-31G / 6-31G\* / 6-31G\*\* →
-cc-pVDZ / cc-pVTZ → def2-SVP / def2-TZVP
+cc-pVDZ / cc-pVTZ → def2-SVP / def2-TZVP → LANL2DZ
+
+For **transition metals and heavy elements**, use **def2-SVP** / **def2-TZVP**
+or **LANL2DZ** — these carry the effective core potentials that cover metals,
+whereas the Pople (`6-31G…`) and Dunning (`cc-pV…`) sets do not. QuantUI's
+pre-run guard flags a metal on an incompatible basis and offers a one-click
+switch to def2-SVP before the calculation starts.
 
 ---
 

{quantui-0.7.0 → quantui-0.8.1}/README.md

@@ -18,13 +18,49 @@ research and classroom use.
 
 ---
 
+## Example results
+
+Real output from QuantUI, straight from the app:
+
+<table>
+  <tr>
+    <td width="50%" align="center" valign="top">
+      <img src="docs/images/cisplatin_lumo.png" alt="Cisplatin LUMO isosurface" width="400"><br>
+      <b>Cisplatin LUMO</b><br>
+      <sub>Molecular-orbital isosurface · B3LYP/LANL2DZ (ECP on Pt &amp; Cl)</sub>
+    </td>
+    <td width="50%" align="center" valign="top">
+      <img src="docs/images/aspartame_orbital_diagram.png" alt="Aspartame orbital energy-level diagram" width="300"><br>
+      <b>Aspartame orbital energies</b><br>
+      <sub>Occupied/virtual levels · HOMO–LUMO gap 6.09 eV · B3LYP/6-31G*</sub>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" align="center" valign="top">
+      <img src="docs/images/benzene_ir_spectrum.png" alt="Benzene IR spectrum" width="400"><br>
+      <b>Benzene IR spectrum</b><br>
+      <sub>Analytical Hessian · ωB97X-D/6-31G · the four IR-active bands</sub>
+    </td>
+    <td width="50%" align="center" valign="top">
+      <img src="docs/images/cisplatin_optimization.png" alt="Cisplatin geometry-optimization energy convergence" width="400"><br>
+      <b>Geometry optimization</b><br>
+      <sub>Cisplatin relaxing over 21 BFGS steps · B3LYP/LANL2DZ</sub>
+    </td>
+  </tr>
+</table>
+
+▶ **[Live interactive gallery →](https://the-schultz-lab.github.io/QuantUI/#examples)** — rotate the 3D structures, and watch the optimization trajectory and a vibrational mode animate.
+
+---
+
 ## What it does
 
-- **Molecule input** — paste XYZ coordinates, browse an indexed three-tier
-  bundled library (20 presets + 156 curated molecules + ~1,900 QM9 structures,
-  searchable by name/formula), or run a structure search by name, SMILES,
-  InChI, PubChem CID, InChIKey, or CAS number (PubChem → NCI CACTUS → offline
-  bundled-library fallback; SMILES/InChI resolve locally with no network)
+- **Molecule input** — paste XYZ coordinates, browse an indexed bundled library
+  (organic presets + curated molecules + ~1,900 QM9 structures + **14
+  ready-to-run coordination complexes**, searchable by name/formula), or run a
+  structure search by name, SMILES, InChI, PubChem CID, InChIKey, or CAS number
+  (PubChem → NCI CACTUS → offline bundled-library fallback; SMILES/InChI resolve
+  locally with no network)
 - **Offline-first** — runs with no internet: the bundled molecule library and
   the 3D viewer's JavaScript (3Dmol.js) are vendored, so structure lookup and
   every 3D view work in an air-gapped classroom. (Network is used only for the
@@ -48,6 +84,18 @@ research and classroom use.
   animation; vibrational frequency analysis with animated normal modes,
   user-tunable playback FPS, and a per-result-directory disk cache so mode
   switches on repeat visits and history replay are instant
+- **Inorganic / coordination complexes** — first-class support for
+  transition-metal chemistry the organic pipeline can't handle: 14 bundled
+  metal complexes (octahedral / tetrahedral / square-planar; aqua, ammine,
+  cyanide, carbonyl, halide, oxo) with correct charge and spin; a pre-run guard
+  that catches a metal on an incompatible basis (nudges to def2-SVP / LANL2DZ)
+  and an impossible charge/multiplicity before the calculation starts; a
+  **spin-state helper** that suggests a multiplicity from a metal centre's
+  oxidation state and geometry (both high- and low-spin where the ligand field
+  decides — you pick); optional **GFN-FF (xtb) pre-optimization** that relaxes a
+  metal complex the classical organic force field can't; a warning when a name
+  search returns a disconnected salt instead of the coordinated complex; and a
+  viewer that draws the coordination bonds so the metal is never a lone dot
 - **Results persistence** — every calculation is saved automatically to a
   timestamped directory; a built-in browser lets you reload past results
   after a kernel restart; the full `pyscf.log` is shown inline
@@ -164,6 +212,26 @@ and result cards will display the compute device.
 Whenever gpu4pyscf can't offload a particular call, QuantUI falls back
 to CPU automatically and the result card reflects which device ran.
 
+### Optional: GFN-FF metal pre-optimization (xtb)
+
+The classical (MMFF/UFF) pre-optimizer relies on RDKit's organic valence
+model, which can't handle a transition metal. Install
+[xtb](https://github.com/grimme-lab/xtb) to enable **GFN-FF**, a general
+force field that relaxes coordination complexes across the whole periodic
+table. Fully optional — without it, metal pre-opt simply reports that it
+isn't available and points you to the DFT geometry optimization.
+
+```bash
+# Linux (PyPI wheels bundle the compiled library):
+pip install quantui[xtb]
+
+# Windows / macOS (no PyPI wheel — use conda-forge):
+conda install -c conda-forge xtb-python
+```
+
+QuantUI detects xtb automatically and routes metal pre-optimizations through
+GFN-FF; organic molecules still use the faster RDKit force field.
+
 ---
 
 ## Quick start
@@ -365,7 +433,13 @@ Five step-by-step notebooks in [`notebooks/tutorials/`](https://github.com/The-S
 ### Basis sets
 
 STO-3G (fast, good for learning) → 3-21G → 6-31G / 6-31G\* / 6-31G\*\* →
-cc-pVDZ / cc-pVTZ → def2-SVP / def2-TZVP
+cc-pVDZ / cc-pVTZ → def2-SVP / def2-TZVP → LANL2DZ
+
+For **transition metals and heavy elements**, use **def2-SVP** / **def2-TZVP**
+or **LANL2DZ** — these carry the effective core potentials that cover metals,
+whereas the Pople (`6-31G…`) and Dunning (`cc-pV…`) sets do not. QuantUI's
+pre-run guard flags a metal on an incompatible basis and offers a one-click
+switch to def2-SVP before the calculation starts.
 
 ---
 

{quantui-0.7.0 → quantui-0.8.1}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantui"
-version = "0.7.0"
+version = "0.8.1"
 description = "An open-source frontend for DFT and post-HF quantum chemistry with PySCF"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -118,6 +118,17 @@ ase = [
     "ase>=3.22.0,<4",
 ]
 
+# GFN-FF metal-capable classical pre-optimization via xtb (Grimme's general
+# force field). RDKit's organic valence model can't touch a transition metal;
+# GFN-FF covers the whole periodic table. quantui.preopt uses it when present
+# and falls back gracefully otherwise. xtb publishes **Linux pip wheels only** —
+# on Windows/macOS install it from conda-forge (see local-setup/environment.yml).
+# Depends on ase (the optimizer driving the relaxation).
+xtb = [
+    "xtb>=22.1",
+    "ase>=3.22.0,<4",
+]
+
 # Voilà app server — hides notebook code; students see only the widget UI.
 # Run with: voila notebooks/molecule_computations.ipynb
 app = [
@@ -164,7 +175,11 @@ dev = [
     "pytest-cov>=4.0.0",
     "pytest-mock>=3.10.0",
     "pytest-xdist>=3.0.0",  # parallel test execution (-n=auto in addopts)
-    "mypy>=1.0.0",
+    "mypy>=1.10,<2.4",  # pinned, not an open floor — same reasoning as
+    # black/ruff below: it must agree with .pre-commit-config.yaml's rev,
+    # which is what CI enforces (M-TYPECHECK TYPE.2). A newer mypy silently
+    # disagrees: 2.x drops support for python_version = "3.9" (this repo's
+    # floor) and reports a different error set than the pinned check.
     "types-requests>=2.28.0",
     # Formatter/linter versions are pinned to a compatible range, NOT an open
     # floor: they must agree with the revs in .pre-commit-config.yaml, which is

{quantui-0.7.0 → quantui-0.8.1}/quantui/__init__.py

@@ -7,7 +7,7 @@ Calculations run locally in the Jupyter session — no cluster or SLURM required
 PySCF requires Linux/macOS/WSL. Windows users should use the Apptainer container.
 """
 
-__version__ = "0.7.0"
+__version__ = "0.8.1"
 
 import logging
 from typing import Any

{quantui-0.7.0 → quantui-0.8.1}/quantui/analytics.py

@@ -34,7 +34,7 @@ import statistics
 from collections import defaultdict
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Optional
+from typing import Optional, cast
 
 from quantui.calc_log import _log_dir, get_perf_history, get_prediction_history
 
@@ -280,11 +280,17 @@ def _bar_chart_html(
         margin=dict(l=40, r=20, t=10, b=40),
         plot_bgcolor="#ffffff",
     )
-    return pio.to_html(
-        fig,
-        include_plotlyjs="inline" if include_plotlyjs else False,
-        full_html=False,
-        config={"displayModeBar": False},
+    # plotly has no bundled type stubs; --ignore-missing-imports leaves
+    # pio.to_html untyped. It genuinely returns str (verified: this
+    # function's other returns are explicit None for the no-data case).
+    return cast(
+        str,
+        pio.to_html(
+            fig,
+            include_plotlyjs="inline" if include_plotlyjs else False,
+            full_html=False,
+            config={"displayModeBar": False},
+        ),
     )
 
 
@@ -344,11 +350,14 @@ def _timeline_html(records: list[dict], *, include_plotlyjs: bool) -> Optional[s
         plot_bgcolor="#ffffff",
         legend=dict(orientation="h", x=0, y=1.05),
     )
-    return pio.to_html(
-        fig,
-        include_plotlyjs="inline" if include_plotlyjs else False,
-        full_html=False,
-        config={"displayModeBar": False},
+    return cast(
+        str,
+        pio.to_html(
+            fig,
+            include_plotlyjs="inline" if include_plotlyjs else False,
+            full_html=False,
+            config={"displayModeBar": False},
+        ),
     )
 
 
@@ -452,11 +461,14 @@ def _prediction_scatter_html(
         plot_bgcolor="#ffffff",
         legend=dict(orientation="h", x=0, y=1.05),
     )
-    return pio.to_html(
-        fig,
-        include_plotlyjs="inline" if include_plotlyjs else False,
-        full_html=False,
-        config={"displayModeBar": False},
+    return cast(
+        str,
+        pio.to_html(
+            fig,
+            include_plotlyjs="inline" if include_plotlyjs else False,
+            full_html=False,
+            config={"displayModeBar": False},
+        ),
     )