quantui 0.5.1__tar.gz → 0.5.2__tar.gz

{quantui-0.5.1 → quantui-0.5.2}/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-08-03
+
+### Fixed
+
+- **Dark mode now has visible panel edges.** Borders, cards, and dividers were
+  effectively invisible in Dark mode — measured at 1.14:1 against the panel
+  background, well under the 3:1 that WCAG asks of a UI component. Dark mode is
+  a whole-page colour inversion rather than a separate palette, so a light grey
+  border inverts to a near-black one on a near-black page and disappears. The
+  borders are now a mid-tone that stays visible in *both* modes (3.20:1 light,
+  4.30:1 dark). Text contrast was measured too and was never the problem — it
+  is 7.24:1 in light mode and slightly *better* inverted — so text colours are
+  deliberately unchanged.
+
+### Added
+
+- **Every 3-D viewer now has a border around it**, so it is clear where the
+  view ends and where the page can be scrolled without dragging the structure.
+  This covers the molecule preview, the results and analysis structure views,
+  the geometry-optimization trajectory, the vibrational-mode animation, and the
+  classical pre-optimization preview. The frame hugs the plot itself rather
+  than spanning the window width, and looks the same whichever rendering
+  backend (py3Dmol or plotlymol3d) is active.
+
 ## [0.5.1] - 2026-07-31
 
 ### Fixed
@@ -484,7 +508,8 @@ Initial public scaffolding of the QuantUI package: `quantui` package with
 `calculator.py`, basic notebook launcher, Apptainer container definition,
 MIT license, and project metadata.
 
-[Unreleased]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.5.1...HEAD
+[Unreleased]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.5.2...HEAD
+[0.5.2]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.4.1...v0.5.0
 [0.4.1]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.4.0...v0.4.1

{quantui-0.5.1/quantui.egg-info → quantui-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantui
-Version: 0.5.1
+Version: 0.5.2
 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
@@ -91,7 +91,7 @@ Dynamic: license-file
 
 # QuantUI
 
-[![PyPI](https://img.shields.io/pypi/v/quantui)](https://pypi.org/project/quantui/)
+[![PyPI](https://img.shields.io/pypi/v/quantui?v=2)](https://pypi.org/project/quantui/)
 [![CI](https://github.com/The-Schultz-Lab/QuantUI/actions/workflows/ci.yml/badge.svg)](https://github.com/The-Schultz-Lab/QuantUI/actions/workflows/ci.yml)
 [![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://the-schultz-lab.github.io/QuantUI/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/The-Schultz-Lab/QuantUI/blob/main/LICENSE)

{quantui-0.5.1 → quantui-0.5.2}/README.md

@@ -1,6 +1,6 @@
 # QuantUI
 
-[![PyPI](https://img.shields.io/pypi/v/quantui)](https://pypi.org/project/quantui/)
+[![PyPI](https://img.shields.io/pypi/v/quantui?v=2)](https://pypi.org/project/quantui/)
 [![CI](https://github.com/The-Schultz-Lab/QuantUI/actions/workflows/ci.yml/badge.svg)](https://github.com/The-Schultz-Lab/QuantUI/actions/workflows/ci.yml)
 [![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://the-schultz-lab.github.io/QuantUI/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/The-Schultz-Lab/QuantUI/blob/main/LICENSE)

{quantui-0.5.1 → quantui-0.5.2}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantui"
-version = "0.5.1"
+version = "0.5.2"
 description = "An open-source frontend for DFT and post-HF quantum chemistry with PySCF"
 readme = "README.md"
 requires-python = ">=3.9"

{quantui-0.5.1 → quantui-0.5.2}/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.5.1"
+__version__ = "0.5.2"
 
 import logging
 from typing import Any

{quantui-0.5.1 → quantui-0.5.2}/quantui/app.py

@@ -32,6 +32,7 @@ import quantui
 import quantui.calc_log as _calc_log
 import quantui.issue_tracker as _issue_tracker
 from quantui import molecule_library as _ml
+from quantui import theme as _theme
 from quantui.app_analysis import (
     activate_ana_panel as _ana_activate_ana_panel,
 )
@@ -450,9 +451,6 @@ try:
     from quantui.visualization_py3dmol import (
         VIZ_STYLE_OPTIONS as _VIZ_STYLE_OPTIONS,
     )
-    from quantui.visualization_py3dmol import (
-        display_molecule as _display_molecule,
-    )
     from quantui.visualization_py3dmol import (
         render_molecule_html as _render_molecule_html,
     )
@@ -460,7 +458,6 @@ try:
     VISUALIZATION_AVAILABLE = True
 except ImportError:
     VISUALIZATION_AVAILABLE = False
-    _display_molecule = None  # type: ignore[assignment]
     _render_molecule_html = None  # type: ignore[assignment]
     _PLOTLYMOL_VIZ = False
     _PY3DMOL_VIZ = False
@@ -616,7 +613,7 @@ h3 {
     color: #64748b !important;
     margin: 24px 0 10px !important;
     padding-bottom: 5px !important;
-    border-bottom: 1px solid #e2e8f0 !important;
+    border-bottom: 1px solid __Q_BORDER__ !important;
 }
 
 /* Rounded corners on inputs, dropdowns, and buttons -------------------- */
@@ -632,21 +629,6 @@ h3 {
     background: transparent !important;
 }
 
-/* 3D molecule-viewer frames — a subtle bounding box so the viewer
-   extent reads clearly. The light border inverts to dark automatically under
-   the global dark-mode invert filter. */
-.quantui-viewer-frame {
-    border: 1px solid #c0ccd8 !important;
-    border-radius: 6px !important;
-    overflow: hidden !important;
-}
-/* Collapse the frame to nothing when the viewer output is empty (e.g. before
-   a calc runs) so no hollow box shows. Degrades to an always-on border where
-   :has() is unsupported. */
-.quantui-viewer-frame:not(:has(.jp-OutputArea-child)) {
-    border-color: transparent !important;
-}
-
 /* Inline "calculating" spinner — shown next to slow on-demand
    controls (e.g. orbital-isosurface generation) while work is in flight. */
 @keyframes quantui-spin { to { transform: rotate(360deg); } }
@@ -654,13 +636,20 @@ h3 {
     display: inline-block;
     width: 14px;
     height: 14px;
-    border: 2px solid #c0ccd8;
+    border: 2px solid __Q_BORDER__;
     border-top-color: #2563eb;
     border-radius: 50%;
     animation: quantui-spin 0.7s linear infinite;
     vertical-align: middle;
 }
-</style>"""
+</style>""".replace(
+    # Sentinel substitution rather than an f-string: this block is dense with
+    # CSS braces, every one of which would need doubling. If a second sentinel
+    # is ever added, substitute the LONGER name first — "__Q_BORDER__" matches
+    # inside "__Q_BORDER_STRONG__" and would leave a dangling "_STRONG__".
+    "__Q_BORDER__",
+    _theme.BORDER,
+)
 
 _LAYOUT_TRAITS: frozenset[str] = frozenset(widgets.Layout.class_trait_names())
 
@@ -2383,7 +2372,7 @@ class QuantUIApp:
                     body = rows[1:]
                     head_html = "".join(
                         f'<th style="padding:4px 10px;text-align:left;'
-                        f"border-bottom:1px solid #cbd5e1;font-size:12px;"
+                        f"border-bottom:1px solid {_theme.BORDER};font-size:12px;"
                         f'color:#1e293b">{_html.escape(str(c))}</th>'
                         for c in header
                     )
@@ -2427,7 +2416,7 @@ class QuantUIApp:
                     # reach the parent app.
                     iframe_html = (
                         '<iframe sandbox="allow-scripts" '
-                        'style="width:100%;height:400px;border:1px solid #cbd5e1;'
+                        f'style="width:100%;height:400px;border:1px solid {_theme.BORDER};'
                         'border-radius:4px" '
                         f'srcdoc="{_html.escape(raw, quote=True)}"></iframe>'
                     )
@@ -2871,7 +2860,7 @@ class QuantUIApp:
     def _rerender_3d_views(self) -> None:
         """Re-render visible 3D molecule viewers using the router to pick a
         backend per task. Updates the "Rendering with: X" label widgets."""
-        if _display_molecule is None:
+        if _render_molecule_html is None:
             return
 
         # Calculate-tab molecule preview (MOLECULE_PREVIEW task).
@@ -2884,15 +2873,19 @@ class QuantUIApp:
         if self._analysis_displayed_molecule is not None:
             chosen = self._resolve_backend(VizTask.ANALYSIS_STRUCTURE_VIEW)
             if chosen is not None:
-                self._analysis_mol_output.clear_output()
-                with self._analysis_mol_output:
-                    _display_molecule(
-                        self._analysis_displayed_molecule,
-                        backend=str(chosen),
-                        style=self._viz_style,
-                        lighting=self._viz_lighting,
-                        bgcolor=self._plotly_theme_colors()["scene_bgcolor"],
-                    )
+                # Same render path as the first draw (app_visualization.
+                # _show_result_3d), not display(): the fragment it returns
+                # carries the viewer's own border. Going through display()
+                # here would silently drop that border the moment a user
+                # toggled backends on the Analysis tab.
+                html = _render_molecule_html(
+                    self._analysis_displayed_molecule,
+                    backend=str(chosen),
+                    style=self._viz_style,
+                    lighting=self._viz_lighting,
+                    bgcolor=self._plotly_theme_colors()["scene_bgcolor"],
+                )
+                self._set_html_output(self._analysis_mol_output, html)
                 self._update_analysis_backend_label(chosen)
 
     def _update_analysis_backend_label(self, chosen: VizBackend) -> None:
@@ -5514,7 +5507,7 @@ class QuantUIApp:
             rows.append(f'<div style="{style}">{esc}</div>')
         self._log_output_html.value = (
             '<div style="font-family:monospace;font-size:12px;line-height:1.4;'
-            "padding:8px 10px;background:#f8fafc;border:1px solid #e2e8f0;"
+            f"padding:8px 10px;background:#f8fafc;border:1px solid {_theme.BORDER};"
             'border-radius:4px;overflow-x:auto;max-height:550px;overflow-y:auto">'
             + "".join(rows)
             + "</div>"
@@ -5530,7 +5523,7 @@ class QuantUIApp:
         if key and key in HELP_TOPICS:
             entry = HELP_TOPICS[key]
             self.help_content_html.value = (
-                f'<div style="border:1px solid #e2e8f0;border-radius:6px;'
+                f'<div style="border:1px solid {_theme.BORDER};border-radius:6px;'
                 f'padding:14px 18px;margin:8px 0;background:#f8fafc;max-width:700px">'
                 f'<h4 style="margin:0 0 10px;color:#1e293b;font-size:15px;font-weight:700">'
                 f'{entry["title"]}</h4>'

{quantui-0.5.1 → quantui-0.5.2}/quantui/app_builders.py

@@ -11,6 +11,7 @@ from IPython.display import HTML, display
 
 import quantui
 from quantui import molecule_library as _ml
+from quantui import theme as _theme
 from quantui.help_content import HELP_TOPICS
 from quantui.live_log import LiveLog
 
@@ -153,7 +154,7 @@ def build_status_panel(
             for k, v in items
         )
         return (
-            '<div style="background:#f8fafc;border:1px solid #e2e8f0;'
+            f'<div style="background:#f8fafc;border:1px solid {_theme.BORDER};'
             "border-left:4px solid #3b82f6;"
             'padding:12px 16px;border-radius:6px;margin:4px 0 8px">'
             '<div style="font-weight:600;font-size:14px;color:#1e293b">'
@@ -188,7 +189,7 @@ def build_status_panel(
         ],
     )
     settings_html = widgets.HTML(
-        '<div style="background:#f8fafc;border:1px solid #e2e8f0;'
+        f'<div style="background:#f8fafc;border:1px solid {_theme.BORDER};'
         "border-left:4px solid #94a3b8;padding:12px 16px;border-radius:6px;"
         'margin:8px 0 4px">'
         '<div style="font-weight:600;font-size:14px;color:#1e293b">Settings</div>'
@@ -645,8 +646,20 @@ def build_shared_widgets(
     # overflow hidden (not auto): the 3D viewer is a fixed-size canvas, so it
     # needs no scrollbar — clipping a few px of margin avoids an internal
     # scrollbar that resets to the top on every backend/palette swap.
-    app.viz_output = widgets.Output(layout=layout_fn(height="510px", overflow="hidden"))
-    app.viz_output.add_class("quantui-viewer-frame")
+    # min_height, not height: the fragment is the info box (~110px) PLUS the
+    # 500px canvas plus its border, so the old fixed 510px — sized for the
+    # canvas alone — clipped the bottom border off. A minimum still reserves
+    # space so the page doesn't jump when a molecule first renders, but lets
+    # the box grow if the info box wraps to more lines on a narrow window.
+    app.viz_output = widgets.Output(
+        layout=layout_fn(min_height="620px", overflow="hidden")
+    )
+    # No .quantui-viewer-frame here: this output renders via
+    # render_molecule_html, whose fragment now carries its own border sized
+    # to the viewer's exact pixel width. The class's border would sit on the
+    # Output widget, which CANNOT shrink-wrap (JupyterLab's Lumino layout
+    # pins its children to the full window width — measured 2026-08-03), so
+    # it would draw a second, full-width box around the tight one.
     # Live calc log — a QuantUI-owned scroll container, not a widgets.Output
     # (M-LOGSCROLL route C). An Output rebuilds its DOM subtree and resets
     # scrollTop on every appended line, which made it impossible to scroll up
@@ -663,7 +676,9 @@ def build_shared_widgets(
     app.run_output.add_class("quantui-run-output")
     app.result_output = widgets.Output()
     app.result_viz_output = widgets.Output()
-    app.result_viz_output.add_class("quantui-viewer-frame")
+    # Same as viz_output above — bordered by the rendered fragment itself.
+    # overflow is set on the layout since the class no longer supplies it.
+    app.result_viz_output.layout.overflow = "hidden"
     app.comparison_output = widgets.Output()
     app._last_result_dir = None
 
@@ -808,10 +823,12 @@ def build_shared_widgets(
     app.preopt_preview_output = widgets.Output(
         layout=layout_fn(
             # 290px viewer + stepper controls (slider / play / compare) below.
-            height="360px",
+            # min_height, not height: build_preopt_preview_html now returns a
+            # framed fragment, and a fixed height would clip its bottom border
+            # off under overflow:hidden.
+            min_height="380px",
             width="100%",
             max_width="480px",
-            border="1px solid #e2e8f0",
             overflow="hidden",
         )
     )
@@ -1279,7 +1296,7 @@ def build_welcome_header(app: Any, *, layout_fn: Any = None) -> None:
             justify_content="flex-start",
             padding="22px 4px 18px",
             margin="0 0 4px",
-            border_bottom="1px solid #e2e8f0",
+            border_bottom=f"1px solid {_theme.BORDER}",
         ),
     )
 
@@ -1629,7 +1646,9 @@ def build_results_section(app: Any, *, layout_fn: Any) -> None:
     # switch. Matches the trajectory frame_out fix pattern. 460+20=480
     # accommodates the py3Dmol view (460px) plus a small horizontal pad;
     # 420+20=440 likewise for the 420px view height.
-    app.vib_output = widgets.Output(layout=layout_fn(height="440px", width="480px"))
+    # min_height: the vib renderers return a framed fragment, and a fixed
+    # height clips its bottom border off under the tab's overflow rules.
+    app.vib_output = widgets.Output(layout=layout_fn(min_height="450px", width="480px"))
 
     # Vibration animation export: writes the current mode as a self-contained
     # HTML file. Backend selection is independent of the user's default — see
@@ -2006,8 +2025,11 @@ def build_results_section(app: Any, *, layout_fn: Any) -> None:
     )
     app.results_panel = app.results_tab_panel
 
+    # No .quantui-viewer-frame: this renders via render_molecule_html (see
+    # app_visualization._show_result_3d), so the fragment carries its own
+    # border fitted to the viewer. The class would add a second, full-width
+    # box around it — the Output widget cannot shrink-wrap.
     app._analysis_mol_output = widgets.Output()
-    app._analysis_mol_output.add_class("quantui-viewer-frame")
 
     # Analysis-tab backend toggle — mirrors the Calculate-tab `viz_backend_toggle`.
     # Created only when both backends are available (matches Calculate-tab
@@ -2239,7 +2261,7 @@ def build_output_tab(app: Any, *, layout_fn: Any) -> None:
             app._log_output_html,
             app._result_log_accordion,
             widgets.HTML(
-                '<hr style="border:none;border-top:1px solid #e2e8f0;margin:16px 0 10px"/>'
+                f'<hr style="border:none;border-top:1px solid {_theme.BORDER};margin:16px 0 10px"/>'
                 '<p style="color:#94a3b8;font-size:12px;margin:0 0 6px">'
                 "Session event log — records molecule loads, calculations, "
                 "and issue reports across this session.</p>"
@@ -2315,7 +2337,7 @@ def build_files_tab(app: Any, *, layout_fn: Any) -> None:
     )
     app._files_preview_output = widgets.Output(
         layout=layout_fn(
-            border="1px solid #cbd5e1",
+            border=f"1px solid {_theme.BORDER}",
             min_height="220px",
             max_height="420px",
             overflow="auto",
@@ -2403,7 +2425,7 @@ def build_help_section(app: Any, *, layout_fn: Any) -> None:
         layout=layout_fn(
             display="none",
             padding="8px 0",
-            border="1px solid #e2e8f0",
+            border=f"1px solid {_theme.BORDER}",
             border_radius="6px",
             padding_left="12px",
             margin="0 0 8px",

{quantui-0.5.1 → quantui-0.5.2}/quantui/app_formatters.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any, Optional
 
+from quantui import theme as _theme
+
 
 def _result_extra_rows(get: Any) -> str:
     """Build the shared 'extra' result-card rows from an accessor.
@@ -478,7 +480,7 @@ def format_past_result(data: dict[str, Any], result_dir: Optional[Path] = None)
             _thumb_html = (
                 f'<img src="data:image/png;base64,{_img_b64}" '
                 f'style="float:right;margin:0 0 6px 14px;border-radius:4px;'
-                f'border:1px solid #e2e8f0" width="173" height="108" />'
+                f'border:1px solid {_theme.BORDER}" width="173" height="108" />'
             )
 
     return (

{quantui-0.5.1 → quantui-0.5.2}/quantui/app_visualization.py

@@ -11,6 +11,8 @@ from typing import Any, List
 import ipywidgets as widgets
 from IPython.display import HTML, display
 
+from quantui import theme as _theme
+
 
 @contextmanager
 def _viz_render_event(app: Any, task: Any, backend: Any, **extras: Any):
@@ -306,9 +308,11 @@ def show_opt_trajectory(
         return
 
     # --- Single-viewer trajectory stepper (all frames preloaded) ---
+    # min_height, not height: build_trajectory_viewer_html returns a framed
+    # fragment, and a fixed height would clip its bottom border off.
     viewer_output = widgets.Output(
         layout=layout_fn(
-            height="410px", width="100%", max_width="500px", overflow="hidden"
+            min_height="420px", width="100%", max_width="500px", overflow="hidden"
         )
     )
     try:
@@ -1689,7 +1693,8 @@ def _render_vib_mode_py3dmol(
         from quantui.viz_assets import make_view
 
         interval_ms = max(1, int(round(1000.0 / fps)))
-        view = make_view(width=460, height=420)
+        vib_width = 460
+        view = make_view(width=vib_width, height=420)
         view.addModelsAsFrames(xyz_string, "xyz")
         view.setStyle({"stick": {}, "sphere": {"scale": 0.3}})
         bg = "white" if app.theme_btn.value == "Light" else "#1e1e1e"
@@ -1700,7 +1705,9 @@ def _render_vib_mode_py3dmol(
         # pan/rotate state survives mode switches. The hook is idempotent
         # (guarded by ``_quantuiVibCameraHookInstalled``) and ships inside
         # the cached HTML too — so disk-cache hits also persist the camera.
-        html_str = _VIB_CAMERA_PERSISTENCE_JS + view._make_html()
+        html_str = _theme.frame_viewer_html(
+            _VIB_CAMERA_PERSISTENCE_JS + view._make_html(), width=vib_width
+        )
     except Exception as exc:
         if not _is_vib_stale(app, render_token):
             _vib_err(app, f"Vibrational animation render failed: {exc}")
@@ -1798,7 +1805,11 @@ def _render_vib_mode_plotlymol(
             mode="ball+stick",
             resolution=12,
         )
-        anim_fig.update_layout(height=420)
+        # Explicit width, not just height: the frame is sized in pixels, and a
+        # responsive-width figure would otherwise render this mode at a
+        # different size than the py3Dmol path. 460 matches the viewer in
+        # _render_vib_mode_py3dmol so the two backends look the same.
+        anim_fig.update_layout(width=460, height=420)
     except Exception as exc:
         if not _is_vib_stale(app, render_token):
             _vib_err(app, f"Animation generation failed: {exc}")
@@ -1814,7 +1825,7 @@ def _render_vib_mode_plotlymol(
     )
     if _is_vib_stale(app, render_token):
         return
-    _swap_vib_output(app, anim_html)
+    _swap_vib_output(app, _theme.frame_viewer_html(anim_html, width=460))
 
 
 def render_vib_mode(
@@ -1919,7 +1930,7 @@ def on_vib_mode_changed(app: Any, change: dict[str, Any]) -> None:
 
 
 _STEPPER_BTN_STYLE = (
-    "padding:2px 9px;border:1px solid #cbd5e1;border-radius:4px;"
+    f"padding:2px 9px;border:1px solid {_theme.BORDER};border-radius:4px;"
     "background:#f8fafc;color:#334155;cursor:pointer;font-size:13px;line-height:1.4;"
 )
 
@@ -2099,7 +2110,8 @@ def build_preopt_preview_html(
             lines.append(f"{sym} {xyz[0]:.6f} {xyz[1]:.6f} {xyz[2]:.6f}")
     xyz_string = "\n".join(lines) + "\n"
 
-    view = make_view(width=460, height=290)
+    width = 460
+    view = make_view(width=width, height=290)
     view.addModelsAsFrames(xyz_string, "xyz")
     view.setStyle({"stick": {}, "sphere": {"scale": 0.3}})
     view.setBackgroundColor(bgcolor)
@@ -2109,7 +2121,7 @@ def build_preopt_preview_html(
     n_frames = len(frames)
     # Single frame (FF no-op / RDKit absent): nothing to step through.
     if n_frames <= 1:
-        return view_html
+        return _theme.frame_viewer_html(view_html, width=width)
 
     m = re.search(r"3dmolviewer_(\w+)", view_html)
     if m is None:
@@ -2117,11 +2129,11 @@ def build_preopt_preview_html(
         # plain auto-loop animation so the relaxation is still visible.
         interval_ms = max(1, int(round(1000.0 / max(1, fps))))
         view.animate({"loop": "forward", "interval": interval_ms, "reps": 0})
-        return view._make_html()
+        return _theme.frame_viewer_html(view._make_html(), width=width)
 
     interval_ms = max(1, int(round(1000.0 / max(1, fps))))
     controls = _preopt_controls_html(m.group(1), n_frames, interval_ms)
-    return f'<div style="max-width:480px">{view_html}{controls}</div>'
+    return _theme.frame_viewer_html(view_html, width=width, controls=controls)
 
 
 def build_trajectory_viewer_html(
@@ -2162,11 +2174,12 @@ def build_trajectory_viewer_html(
     view_html = view._make_html()
 
     if n <= 1:
-        return view_html
+        return _theme.frame_viewer_html(view_html, width=width)
 
     m = re.search(r"3dmolviewer_(\w+)", view_html)
     if m is None:
-        return view_html  # can't wire controls without the viewer id
+        # can't wire controls without the viewer id
+        return _theme.frame_viewer_html(view_html, width=width)
 
     interval_ms = max(1, int(round(1000.0 / max(1, fps))))
     eabs = json.dumps([float(e) for e in energies]) if energies else "null"
@@ -2192,7 +2205,7 @@ def build_trajectory_viewer_html(
         scrub_title="Scrub the optimization steps",
         extra_decls=f"var EABS={eabs}; var EREL={erel};",
     )
-    return f'<div style="max-width:{width + 20}px">{view_html}{controls}</div>'
+    return _theme.frame_viewer_html(view_html, width=width, controls=controls)
 
 
 # Single-viewer vibrational animation. ONE py3Dmol viewer holds every mode; the
@@ -2324,9 +2337,7 @@ def build_vib_viewer_html(
         .replace("__BG__", json.dumps(bgcolor))
         .replace("__INIT__", str(int(initial_mode)))
     )
-    return (
-        f'<div style="max-width:{width + 20}px">{view_html}<script>{js}</script></div>'
-    )
+    return _theme.frame_viewer_html(f"{view_html}<script>{js}</script>", width=width)
 
 
 def _vib_single_viewer_supported(app: Any, freq_result: Any) -> bool:

{quantui-0.5.1 → quantui-0.5.2}/quantui/live_log.py

@@ -73,6 +73,8 @@ from typing import Any, Optional
 import ipywidgets as widgets
 from IPython.display import Javascript, display
 
+from quantui import theme as _theme
+
 _LOG = logging.getLogger(__name__)
 
 # Coalescing window for appends. PySCF emits many lines per second; batching
@@ -88,7 +90,7 @@ _MAIL_CLASS = "quantui-live-mail"
 # ASCII header exactly as .jp-OutputArea-output did (see GOTCHAS).
 _CONTAINER_STYLE = (
     "height:300px;overflow-y:auto;overflow-anchor:auto;"
-    "border:1px solid #c0ccd8;border-radius:2px;padding:8px;"
+    f"border:1px solid {_theme.BORDER};border-radius:2px;padding:8px;"
     "font-family:ui-monospace,SFMono-Regular,'SF Mono',Menlo,Consolas,"
     "'Liberation Mono','Courier New',monospace;"
     "font-size:12.5px;line-height:1.35;white-space:pre-wrap;"

quantui-0.5.2/quantui/theme.py

@@ -0,0 +1,125 @@
+"""Theme colour tokens (M-THEME).
+
+Why this module exists
+----------------------
+QuantUI's dark mode is **not a palette swap** — it is a whole-page CSS filter::
+
+    html { filter: invert(1) hue-rotate(180deg) !important; }
+    canvas, img, iframe, video { filter: invert(1) hue-rotate(180deg) !important; }
+
+(see ``app.QuantUIApp._theme_css``). Every colour in the UI is written once, for
+light mode, and dark mode is that same colour mathematically inverted. The
+counter-filter on ``canvas/img/iframe/video`` double-inverts embedded renderers
+(3-D viewers, plots) back to their intended appearance.
+
+**The consequence that matters, and the reason this module exists:** you cannot
+tune light and dark independently. There is exactly one source value per colour,
+and dark mode is whatever that value inverts to.
+
+The mid-tone rule
+-----------------
+That constraint has a non-obvious implication for anything whose job is
+*separation* rather than *legibility*:
+
+- A **light** grey border (``#e2e8f0``) looks correct on a white page, but
+  inverts to a near-black border (``#121820``) on a near-black panel — invisible.
+- A **dark** border has the mirror-image problem: fine in dark mode, invisible
+  in light.
+- A **mid-tone** border stays mid-tone under inversion, so it is visible in
+  *both*. Mid-tones are the only values that survive.
+
+Measured, not assumed (2026-07-31)
+----------------------------------
+Contrast ratios computed through the actual filter chain (invert, then the W3C
+``hue-rotate`` matrix), against the panel background ``#f8fafc``:
+
+===========  ==============  =============  ==================================
+candidate    light vs panel  dark vs panel  verdict
+===========  ==============  =============  ==================================
+``#e2e8f0``  1.18:1          1.14:1         the old value — fails both
+``#c0ccd8``  1.56:1          1.65:1         fails both
+``#94a3b8``  2.45:1          3.12:1         passes dark only
+``#7d8ea3``  3.20:1          4.30:1         **passes both** — chosen
+``#64748b``  4.55:1          6.17:1         passes both, but heavy in light
+===========  ==============  =============  ==================================
+
+``BORDER`` is the *lightest* value clearing WCAG 1.4.11's **3:1** bar for
+non-text UI components in both modes. ``#64748b`` clears it more comfortably but
+reads as a heavy rule in light mode, which is a real cost for a subtle panel
+divider.
+
+What was NOT the problem
+------------------------
+Text contrast was measured too, and it was never broken — body text on a panel
+is 7.24:1 in light and *improves* to 8.91:1 inverted. The user-reported "fix
+dark mode contrasts" was, on measurement, entirely about **structural
+separation**: panels and their borders were invisible against the page, which is
+why the same request also asked to "add borders". Text colours are deliberately
+left alone here.
+
+Scope of this module today
+--------------------------
+Only the tokens needed for the THEME.5 fix. It is intentionally not a
+full-palette migration: the codebase has ~390 hardcoded hex literals across 17
+files, most of them *semantic* accents (error red, success green, link blue)
+whose hue survives ``hue-rotate(180)`` and which look correct in both modes
+already. Migrating those wholesale would be a large, visually-unverifiable
+change for no user-visible gain.
+
+When THEME.6 (customisable palettes) lands, the invert filter has to go — a
+palette system cannot work when dark mode is a derived inversion rather than an
+independent set of values. At that point these tokens become the seam: they
+grow light/dark variants and the ``_theme_css`` filter is replaced. Keeping them
+named here means that change edits this file plus the CSS, not 19 call sites
+again.
+"""
+
+from __future__ import annotations
+
+# ── Structural / chrome ──────────────────────────────────────────────────────
+
+#: Panel, card, and viewer borders. Mid-tone so it survives inversion — see the
+#: module docstring's table. Replaced ``#e2e8f0`` / ``#e5e7eb`` / ``#cbd5e1`` /
+#: ``#c0ccd8``, all of which were invisible in dark mode (1.14-1.65:1).
+BORDER = "#7d8ea3"
+
+#: Emphasised border for elements that should read as framed even at a glance
+#: (the 3-D viewer frame, which sits on its own rather than in a card stack).
+BORDER_STRONG = "#64748b"
+
+
+def frame_viewer_html(view_html: str, *, width: int, controls: str = "") -> str:
+    """Wrap a 3-D viewer fragment in the standard frame, sized to the viewer.
+
+    Every 3-D viewer in the app — static molecule, optimization trajectory,
+    vibrational mode, classical pre-opt preview — goes through here so they all
+    frame identically and a token change lands everywhere at once.
+
+    ``width`` must be the viewer's own pixel width. The frame is built at that
+    width **here**, in the code that knows it, rather than as a CSS class on the
+    hosting ``widgets.Output``. Measured in the browser 2026-08-03: an Output's
+    children are Lumino widgets that JupyterLab sizes with explicit pixel widths
+    tracking the window, so a class-borne ``fit-content`` always resolves to the
+    full page width. The border then enclosed a wide strip of dead space beside
+    the plot, which is actively misleading — it implies the whole strip is
+    interactive and hides where the page can be scrolled without dragging the
+    3-D view.
+
+    ``controls`` is optional stepper/player markup rendered below the viewer.
+    It is inset so the buttons don't sit flush against the frame; the viewer
+    itself stays flush, since its canvas is its own edge.
+
+    Note for callers: the hosting Output must not pin a fixed ``height``, or the
+    frame's bottom edge is clipped off by ``overflow: hidden``. Use
+    ``min_height`` — see ``app_builders.build_shared_widgets``.
+    """
+    if controls:
+        controls = f'<div style="padding:0 8px 6px">{controls}</div>'
+    return (
+        f'<div style="width:{width}px;max-width:100%;'
+        f"border:1px solid {BORDER_STRONG};border-radius:6px;"
+        f'overflow:hidden">{view_html}{controls}</div>'
+    )
+
+
+__all__ = ["BORDER", "BORDER_STRONG", "frame_viewer_html"]

{quantui-0.5.1 → quantui-0.5.2}/quantui/visualization_py3dmol.py

@@ -14,6 +14,8 @@ import os
 import tempfile
 from typing import Literal, cast
 
+from quantui import theme as _theme
+
 logger = logging.getLogger(__name__)
 
 Py3DmolStyle = Literal["ball+stick", "stick", "sphere", "line", "cartoon"]
@@ -469,7 +471,10 @@ def render_molecule_html(
             '<div style="color:#b91c1c;padding:8px;">'
             f"❌ Visualization failed: {e}</div>"
         )
-    return "\n".join(parts)
+    # Frame the fragment at the viewer's own width — see theme.frame_viewer_html
+    # for why the border cannot live on the hosting Output widget's CSS class.
+    # The info box is INSIDE the frame so it aligns with the canvas.
+    return _theme.frame_viewer_html("\n".join(parts), width=width)
 
 
 def display_molecule(

{quantui-0.5.1 → quantui-0.5.2/quantui.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantui
-Version: 0.5.1
+Version: 0.5.2
 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
@@ -91,7 +91,7 @@ Dynamic: license-file
 
 # QuantUI
 
-[![PyPI](https://img.shields.io/pypi/v/quantui)](https://pypi.org/project/quantui/)
+[![PyPI](https://img.shields.io/pypi/v/quantui?v=2)](https://pypi.org/project/quantui/)
 [![CI](https://github.com/The-Schultz-Lab/QuantUI/actions/workflows/ci.yml/badge.svg)](https://github.com/The-Schultz-Lab/QuantUI/actions/workflows/ci.yml)
 [![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://the-schultz-lab.github.io/QuantUI/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/The-Schultz-Lab/QuantUI/blob/main/LICENSE)

{quantui-0.5.1 → quantui-0.5.2}/quantui.egg-info/SOURCES.txt

@@ -48,6 +48,7 @@ quantui/security.py
 quantui/session_calc.py
 quantui/structure_providers.py
 quantui/tddft_calc.py
+quantui/theme.py
 quantui/user_settings.py
 quantui/utils.py
 quantui/vib_cache.py