quantui 0.5.1__py3-none-any.whl

quantui/visualization_py3dmol.py

@@ -0,0 +1,593 @@
+"""
+Molecular visualization using py3Dmol (and optional PlotlyMol).
+
+This module provides 3D molecular visualization using py3Dmol as the primary
+backend (stable, widely used, already installed). PlotlyMol is supported as
+an optional alternative for users who prefer Plotly-based figures.
+
+Author: Jonathan Schultz, NCCU
+Created: 2026-02-17
+"""
+
+import logging
+import os
+import tempfile
+from typing import Literal, cast
+
+logger = logging.getLogger(__name__)
+
+Py3DmolStyle = Literal["ball+stick", "stick", "sphere", "line", "cartoon"]
+BackendName = Literal["auto", "py3dmol", "plotlymol"]
+
+# Check available visualization backends
+try:
+    import py3Dmol  # noqa: F401 — availability probe; views build via viz_assets.make_view
+
+    PY3DMOL_AVAILABLE = True
+except ImportError:
+    PY3DMOL_AVAILABLE = False
+    logger.warning("py3Dmol not available - primary visualization disabled")
+
+try:
+    from plotlymol3d import draw_3D_rep
+    from plotlymol3d import format_lighting as _plotlymol_format_lighting
+
+    PLOTLYMOL_AVAILABLE = True
+except ImportError:
+    PLOTLYMOL_AVAILABLE = False
+    _plotlymol_format_lighting = None  # type: ignore[assignment]
+    logger.info("PlotlyMol not available (optional)")
+
+# ── Visualization style and lighting constants ────────────────────────────────
+
+# Display-style options presented in the UI.  The value is the canonical key
+# used internally; each backend maps it to its own representation.
+VIZ_STYLE_OPTIONS: list[tuple[str, str]] = [
+    ("Ball & Stick", "ball+stick"),
+    ("Stick", "stick"),
+    ("Sphere (VDW)", "sphere"),
+    ("Line", "line"),
+]
+
+# Named lighting presets — identical to those in the plotlyMol dash app.
+# Only applied when the PlotlyMol backend is active.
+LIGHTING_PRESETS: dict[str, dict] = {
+    "soft": {"ambient": 0.4, "diffuse": 0.8, "specular": 0.1, "roughness": 0.8},
+    "default": {"ambient": 0.0, "diffuse": 1.0, "specular": 0.0, "roughness": 1.0},
+    "bright": {"ambient": 0.5, "diffuse": 0.8, "specular": 0.3, "roughness": 0.5},
+    "metallic": {"ambient": 0.2, "diffuse": 0.7, "specular": 1.0, "roughness": 0.1},
+    "dramatic": {"ambient": 0.0, "diffuse": 1.0, "specular": 0.6, "roughness": 0.2},
+}
+LIGHTING_OPTIONS: list[tuple[str, str]] = [
+    ("Soft", "soft"),
+    ("Default", "default"),
+    ("Bright", "bright"),
+    ("Metallic", "metallic"),
+    ("Dramatic", "dramatic"),
+]
+
+DEFAULT_STYLE: str = "ball+stick"
+DEFAULT_LIGHTING: str = "soft"
+
+
+def is_visualization_available() -> bool:
+    """
+    Check if molecular visualization is available.
+
+    Returns:
+        True if py3Dmol OR PlotlyMol is available, False otherwise.
+    """
+    return PY3DMOL_AVAILABLE or PLOTLYMOL_AVAILABLE
+
+
+def get_available_backends() -> list[str]:
+    """
+    Get list of available visualization backends.
+
+    Returns:
+        List of available backend names (e.g., ['py3dmol', 'plotlymol'])
+    """
+    backends = []
+    if PY3DMOL_AVAILABLE:
+        backends.append("py3dmol")
+    if PLOTLYMOL_AVAILABLE:
+        backends.append("plotlymol")
+    return backends
+
+
+def molecule_to_xyz_string(molecule) -> str:
+    """
+    Convert QuantUI Molecule to XYZ string format.
+
+    Args:
+        molecule: QuantUI Molecule object
+
+    Returns:
+        XYZ format string suitable for py3Dmol or PlotlyMol
+    """
+    from quantui.molecule import Molecule
+
+    if not isinstance(molecule, Molecule):
+        raise TypeError("Expected QuantUI Molecule object")
+
+    return molecule.to_xyz_string()
+
+
+def visualize_molecule_py3dmol(
+    molecule,
+    style: Py3DmolStyle = "ball+stick",
+    width: int = 600,
+    height: int = 500,
+    bgcolor: str = "white",
+    lighting: str = "soft",  # accepted for API symmetry; py3Dmol has no preset lighting
+):
+    """
+    Create interactive 3D visualization using py3Dmol.
+
+    Args:
+        molecule: QuantUI Molecule object
+        style: Visualization style:
+            - "stick": Stick representation (default, good for small molecules)
+            - "sphere": Van der Waals spheres
+            - "line": Line representation
+            - "cartoon": Cartoon (for proteins)
+        width: Viewer width in pixels (default: 600)
+        height: Viewer height in pixels (default: 500)
+        bgcolor: Background color (default: "white")
+
+    Returns:
+        py3Dmol.view object (call .show() in Jupyter to display)
+
+    Raises:
+        ImportError: If py3Dmol is not installed
+
+    Example:
+        >>> mol = Molecule(['O', 'H', 'H'], [[0,0,0], [0.757,0.587,0], [-0.757,0.587,0]])
+        >>> view = visualize_molecule_py3dmol(mol, style="stick")
+        >>> view.show()  # In Jupyter
+    """
+    if not PY3DMOL_AVAILABLE:
+        raise ImportError(
+            "py3Dmol is not installed. To enable 3D visualization:\n"
+            "  pip install py3dmol"
+        )
+
+    # Build a well-formed XYZ block: count line + title line + coordinates.
+    # py3Dmol is lenient about the header in most environments, but browsers
+    # running the exported HTML require the standard two-line header to parse
+    # the format correctly.
+    bare_xyz = molecule.to_xyz_string()
+    xyz_string = f"{len(molecule.atoms)}\n{molecule.get_formula()}\n{bare_xyz}"
+
+    logger.info(
+        f"Creating py3Dmol visualization for {molecule.get_formula()} "
+        f"(style={style})"
+    )
+
+    # Create viewer — via the offline-safe factory so 3Dmol.js loads from the
+    # vendored bundle (the page bootstrap), never the CDN (offline classroom).
+    from quantui.viz_assets import make_view
+
+    view = make_view(width=width, height=height)
+
+    # Add molecule
+    view.addModel(xyz_string, "xyz")
+
+    # Set style — "ball+stick" requires a compound spec in py3Dmol
+    if style == "ball+stick":
+        view.setStyle({"stick": {}, "sphere": {"scale": 0.3}})
+    else:
+        view.setStyle({style: {}})
+
+    # Set background
+    view.setBackgroundColor(bgcolor)
+
+    # Zoom to fit
+    view.zoomTo()
+
+    return view
+
+
+def _validate_py3dmol_style(style: str) -> Py3DmolStyle:
+    valid_styles: tuple[Py3DmolStyle, ...] = (
+        "ball+stick",
+        "stick",
+        "sphere",
+        "line",
+        "cartoon",
+    )
+    if style not in valid_styles:
+        raise ValueError(f"style must be one of {list(valid_styles)}, got '{style}'")
+    return cast(Py3DmolStyle, style)
+
+
+def visualize_molecule_plotlymol(
+    molecule,
+    mode: str = "ball+stick",
+    resolution: int = 32,
+    width: int = 600,
+    height: int = 500,
+    bgcolor: str = "#ffffff",
+    lighting: str = "soft",
+):
+    """
+    Create interactive 3D visualization using PlotlyMol (optional backend).
+
+    Args:
+        molecule: QuantUI Molecule object
+        mode: Visualization mode - one of:
+            - "ball+stick": Full-size atoms with bonds (default)
+            - "stick": Small atoms with bonds
+            - "vdw": Van der Waals spheres only (no bonds)
+        resolution: Sphere tessellation resolution (16-64, default: 32)
+        width: Figure width in pixels (default: 600)
+        height: Figure height in pixels (default: 500)
+        bgcolor: Background color as hex string or name (default: "#ffffff")
+
+    Returns:
+        plotly.graph_objects.Figure object
+
+    Raises:
+        ImportError: If PlotlyMol is not installed
+    """
+    if not PLOTLYMOL_AVAILABLE:
+        raise ImportError(
+            "PlotlyMol is not installed. To enable PlotlyMol visualization:\n"
+            "  pip install plotlymol"
+        )
+
+    # Validate mode
+    valid_modes = ["ball+stick", "stick", "vdw"]
+    if mode not in valid_modes:
+        raise ValueError(f"mode must be one of {valid_modes}, got '{mode}'")
+
+    # Convert to XYZ string
+    xyz_string = molecule_to_xyz_string(molecule)
+
+    # Get charge for RDKit processing
+    charge = molecule.charge
+
+    logger.info(
+        f"Creating PlotlyMol visualization for {molecule.get_formula()} "
+        f"(mode={mode}, resolution={resolution})"
+    )
+
+    # draw_3D_rep takes a file path, not an in-memory string
+    full_xyz = f"{len(molecule.atoms)}\n\n{xyz_string}\n"
+    tmp = tempfile.NamedTemporaryFile(
+        mode="w", suffix=".xyz", delete=False, encoding="utf-8"
+    )
+    try:
+        tmp.write(full_xyz)
+        tmp.close()
+        fig = draw_3D_rep(
+            xyzfile=tmp.name,
+            charge=charge,
+            mode=mode,
+            resolution=resolution,
+        )
+        if _plotlymol_format_lighting is not None:
+            preset = LIGHTING_PRESETS.get(lighting, LIGHTING_PRESETS["soft"])
+            fig = _plotlymol_format_lighting(fig, **preset)
+    finally:
+        os.unlink(tmp.name)
+
+    fig.update_layout(
+        width=width,
+        height=height,
+        title=f"{molecule.get_formula()} - {mode.replace('+', ' & ').title()}",
+        paper_bgcolor=bgcolor,
+        scene=dict(bgcolor=bgcolor),
+    )
+    return fig
+
+
+def visualize_molecule(
+    molecule,
+    backend: BackendName = "auto",
+    style: str = "ball+stick",
+    width: int = 600,
+    height: int = 500,
+    bgcolor: str = "white",
+    lighting: str = "soft",
+    **kwargs,
+):
+    """
+    Create interactive 3D visualization (backend-agnostic).
+
+    This is the main visualization function. It automatically selects the
+    best available backend or uses the one specified.
+
+    Args:
+        molecule: QuantUI Molecule object
+        backend: Visualization backend:
+            - "auto": Use py3Dmol if available, else PlotlyMol (default)
+            - "py3dmol": Use py3Dmol (recommended, stable)
+            - "plotlymol": Use PlotlyMol (optional, Plotly-based)
+        style: Visualization style (backend-dependent):
+            - py3Dmol: "stick", "sphere", "line", "cartoon"
+            - PlotlyMol: "ball+stick", "stick", "vdw"
+        width: Viewer/figure width in pixels (default: 600)
+        height: Viewer/figure height in pixels (default: 500)
+        bgcolor: Background color (default: "white")
+        **kwargs: Additional backend-specific arguments
+
+    Returns:
+        py3Dmol.view or plotly Figure depending on backend
+
+    Raises:
+        ImportError: If no visualization backend is available
+        ValueError: If specified backend is not available
+
+    Example:
+        >>> mol = Molecule(['H', 'H'], [[0, 0, 0], [0, 0, 0.74]])
+        >>> # Use default backend (py3Dmol)
+        >>> view = visualize_molecule(mol)
+        >>> view.show()  # In Jupyter
+    """
+    # Determine backend
+    if backend == "auto":
+        if PLOTLYMOL_AVAILABLE:
+            backend = "plotlymol"
+        elif PY3DMOL_AVAILABLE:
+            backend = "py3dmol"
+        else:
+            raise ImportError(
+                "No visualization backend available. Install one of:\n"
+                "  pip install py3dmol  (recommended)\n"
+                "  pip install plotlymol"
+            )
+
+    # Use selected backend
+    if backend == "py3dmol":
+        py3dmol_style = _validate_py3dmol_style(style)
+        return visualize_molecule_py3dmol(
+            molecule,
+            style=py3dmol_style,
+            width=width,
+            height=height,
+            bgcolor=bgcolor,
+            lighting=lighting,
+        )
+    elif backend == "plotlymol":
+        # Map UI style keys to PlotlyMol mode names
+        mode_map = {
+            "ball+stick": "ball+stick",
+            "stick": "stick",
+            "sphere": "vdw",
+            "line": "stick",  # plotlyMol has no line mode; use stick
+        }
+        mode = mode_map.get(style, "ball+stick")
+        return visualize_molecule_plotlymol(
+            molecule,
+            mode=mode,
+            width=width,
+            height=height,
+            bgcolor=bgcolor,
+            lighting=lighting,
+            **kwargs,
+        )
+    else:
+        raise ValueError(f"Unknown backend: {backend}")
+
+
+def _info_box_html(molecule, backend: str) -> str:
+    """Build the info-box HTML fragment shown above the 3D viewer."""
+    backends = get_available_backends()
+    backend_str = ", ".join(backends)
+    selected = backend if backend != "auto" else (backends[0] if backends else "")
+    return (
+        '<div style="background-color: #f0f8ff; padding: 10px;'
+        " border-radius: 5px; margin-bottom: 10px;"
+        ' border-left: 4px solid #4a90e2;">'
+        "<strong>📊 Molecule Information</strong><br>"
+        f"<strong>Formula:</strong> {molecule.get_formula()} | "
+        f"<strong>Atoms:</strong> {len(molecule.atoms)} | "
+        f"<strong>Electrons:</strong> {molecule.get_electron_count()} | "
+        f"<strong>Charge:</strong> {molecule.charge} | "
+        f"<strong>Multiplicity:</strong> {molecule.multiplicity}<br>"
+        f'<small style="color: #666;">Using: {selected} '
+        f"(available: {backend_str})</small>"
+        "</div>"
+    )
+
+
+def _unavailable_html(molecule) -> str:
+    """HTML fallback when no 3D visualization backend is installed."""
+    return (
+        '<div style="padding:10px;font-family:sans-serif;color:#444;">'
+        "<p>⚠️ 3D visualization not available.</p>"
+        "<p>To enable visualization, install one of:</p>"
+        "<ul><li><code>pip install py3dmol</code> (recommended)</li>"
+        "<li><code>pip install plotlymol</code></li></ul>"
+        "<p><strong>Molecule Information</strong><br>"
+        f"Formula: {molecule.get_formula()}<br>"
+        f"Atoms: {len(molecule.atoms)}<br>"
+        f"Electrons: {molecule.get_electron_count()}<br>"
+        f"Charge: {molecule.charge}<br>"
+        f"Multiplicity: {molecule.multiplicity}</p>"
+        f"<pre>{molecule.to_xyz_string()}</pre>"
+        "</div>"
+    )
+
+
+def render_molecule_html(
+    molecule,
+    backend: Literal["auto", "py3dmol", "plotlymol"] = "auto",
+    style: str = "ball+stick",
+    show_info: bool = True,
+    width: int = 600,
+    height: int = 500,
+    bgcolor: str = "#ffffff",
+    lighting: str = "soft",
+) -> str:
+    """Return self-contained HTML for the molecule viewer (no display side-effects).
+
+    Mirrors :func:`display_molecule` but emits a single HTML string so callers
+    can route through an atomic ``Output.outputs`` swap (Rule 6 in
+    ``reflections/01-voila-rendering-and-display.md``) rather than
+    ``with output: display(viz)`` — the latter is a known root-cause
+    family for trajectory and Analysis-tab rendering regressions. Errors are
+    caught and returned as inline HTML so the caller sees a
+    visible failure message in the viewer slot instead of a blank 🙁 panel.
+    """
+    if not is_visualization_available():
+        return _unavailable_html(molecule)
+
+    parts: list[str] = []
+    if show_info:
+        parts.append(_info_box_html(molecule, backend))
+
+    try:
+        viz = visualize_molecule(
+            molecule,
+            backend=backend,
+            style=style,
+            width=width,
+            height=height,
+            bgcolor=bgcolor,
+            lighting=lighting,
+        )
+        make_html = getattr(viz, "_make_html", None)
+        if callable(make_html):
+            parts.append(viz._make_html())
+        else:
+            import plotly.io as _pio
+
+            parts.append(
+                _pio.to_html(
+                    viz,
+                    full_html=False,
+                    include_plotlyjs="require",
+                    config={"responsive": True},
+                )
+            )
+        logger.info(f"Rendered HTML for {molecule.get_formula()}")
+    except Exception as e:
+        logger.error(f"Render failed for {molecule.get_formula()}: {e}")
+        parts.append(
+            '<div style="color:#b91c1c;padding:8px;">'
+            f"❌ Visualization failed: {e}</div>"
+        )
+    return "\n".join(parts)
+
+
+def display_molecule(
+    molecule,
+    backend: Literal["auto", "py3dmol", "plotlymol"] = "auto",
+    style: str = "ball+stick",
+    show_info: bool = True,
+    width: int = 600,
+    height: int = 500,
+    bgcolor: str = "#ffffff",
+    lighting: str = "soft",
+):
+    """
+    Display molecule in Jupyter notebook with optional info box.
+
+    This is the main function for notebook integration. It handles all
+    available backends and provides a consistent interface.
+
+    Args:
+        molecule: QuantUI Molecule object
+        backend: Visualization backend ("auto", "py3dmol", "plotlymol")
+        style: Visualization style (backend-dependent)
+        show_info: Whether to show molecular info box
+        width: Viewer/figure width in pixels
+        height: Viewer/figure height in pixels
+
+    Example:
+        >>> # In Jupyter notebook
+        >>> mol = Molecule(['H', 'H'], [[0, 0, 0], [0, 0, 0.74]])
+        >>> display_molecule(mol)  # Uses py3Dmol by default
+    """
+    from IPython.display import HTML, display
+
+    if not is_visualization_available():
+        # Fallback: show text representation
+        print("⚠️  3D visualization not available")
+        print("\nTo enable visualization, install one of:")
+        print("  pip install py3dmol  (recommended)")
+        print("  pip install plotlymol")
+        print("\nMolecule Information:")
+        print(f"  Formula: {molecule.get_formula()}")
+        print(f"  Atoms: {len(molecule.atoms)}")
+        print(f"  Electrons: {molecule.get_electron_count()}")
+        print(f"  Charge: {molecule.charge}")
+        print(f"  Multiplicity: {molecule.multiplicity}")
+        print("\nXYZ Coordinates:")
+        print(molecule.to_xyz_string())
+        return
+
+    # Show info box if requested
+    if show_info:
+        backends = get_available_backends()
+        backend_str = ", ".join(backends)
+        selected = backend if backend != "auto" else backends[0]
+
+        info_html = f"""
+        <div style="background-color: #f0f8ff; padding: 10px; border-radius: 5px;
+                    margin-bottom: 10px; border-left: 4px solid #4a90e2;">
+            <strong>📊 Molecule Information</strong><br>
+            <strong>Formula:</strong> {molecule.get_formula()} |
+            <strong>Atoms:</strong> {len(molecule.atoms)} |
+            <strong>Electrons:</strong> {molecule.get_electron_count()} |
+            <strong>Charge:</strong> {molecule.charge} |
+            <strong>Multiplicity:</strong> {molecule.multiplicity}<br>
+            <small style="color: #666;">Using: {selected} (available: {backend_str})</small>
+        </div>
+        """
+        display(HTML(info_html))
+
+    # Create and display visualization
+    try:
+        viz = visualize_molecule(
+            molecule,
+            backend=backend,
+            style=style,
+            width=width,
+            height=height,
+            bgcolor=bgcolor,
+            lighting=lighting,
+        )
+
+        # display(viz) triggers py3Dmol's _repr_html_() method, which embeds
+        # the viewer as self-contained HTML.  This works in both JupyterLab
+        # and classic Notebook.  viz.show() uses IPython.display.Javascript
+        # which is blocked by JupyterLab's content-security-policy and
+        # returns None (causing "None" to appear in cell output).
+        display(viz)
+
+        logger.info(f"Successfully displayed {molecule.get_formula()}")
+    except Exception as e:
+        print(f"❌ Visualization failed: {e}")
+        logger.error(f"Display failed for {molecule.get_formula()}: {e}")
+
+
+def get_installation_message() -> str:
+    """
+    Get installation instructions for visualization backends.
+
+    Returns:
+        Formatted string with installation instructions
+    """
+    return """
+To enable 3D molecular visualization:
+
+Option 1 (Recommended): py3Dmol
+  pip install py3dmol
+
+Option 2 (Optional): PlotlyMol
+  conda install -c conda-forge rdkit plotly kaleido
+  pip install plotlymol
+
+For most users, py3Dmol is sufficient and more stable.
+"""
+
+
+# Module-level check and logging
+available = get_available_backends()
+if available:
+    logger.info(f"Visualization backends available: {', '.join(available)}")
+else:
+    logger.warning("No visualization backends available")

quantui/viz_assets.py

@@ -0,0 +1,101 @@
+"""Offline-safe py3Dmol asset loading.
+
+py3Dmol's ``view()`` constructor defaults to
+``js='https://cdn.jsdelivr.net/npm/3dmol@2.5.4/build/3Dmol-min.js'`` and its
+``_make_html()`` emits a ``loadScriptAsync('<that URL>')`` call. On any host
+with no network (offline classroom — QuantUI's primary target) or a restrictive
+CSP, that fetch fails silently and the viewer renders blank. This is the
+py3Dmol analogue of the Plotly CDN trap in
+``reflections/01-voila-rendering-and-display.md`` Rule 1.
+
+Approach (no new dependency)
+----------------------------
+The 3Dmol.js bundle is vendored as package data (``data/js/3Dmol-min.js``, the
+exact 2.5.4 build py3Dmol targets). :func:`make_view` builds every viewer with
+``js=<data: URI of the vendored bytes>`` instead of the CDN URL. This reuses
+**py3Dmol's own per-view loader verbatim** — only the source URL changes from a
+remote CDN to a local ``data:`` URI — so the viewer loads 3Dmol.js offline with
+no network.
+
+Why per-view and NOT a one-time page bootstrap: an earlier version injected the
+loader once at app startup (the first display output). Running py3Dmol's
+``exports``/``module``-juggling loader during Voilà's own RequireJS/AMD
+bootstrap polluted the global module system at the worst moment and broke widget
+startup offline. The per-view approach runs the identical loader **after** the
+page is up (when a viewer renders) — exactly when py3Dmol normally runs it — so
+it never interferes with startup. py3Dmol's ``$3Dmolpromise`` global guard means
+only the first viewer on a page actually loads 3Dmol; later views reuse it.
+
+Trade-off: the (cached, ~0.7 MB base64) data: URI rides in each viewer's HTML
+payload. Fine for the molecule preview / isosurface / result viewer; heavier for
+rapid trajectory/vib frame swaps (the bytes ship per payload even though only
+the first triggers a load). Correctness and offline support take priority over
+that payload size; optimizing the rapid-swap path is a possible follow-up.
+
+Author: Jonathan Schultz, NCCU
+Created: 2026-06-15
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+from functools import lru_cache
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Vendored 3Dmol.js — the exact build py3Dmol 2.x's constructor default points
+# at, so the API the py3Dmol-generated JS calls (createViewer, addModel,
+# addVolumetricData, addModelsAsFrames, animate, ...) is guaranteed present.
+# Provenance + license: data/js/PROVENANCE.md, data/js/3Dmol-min.js.LICENSE.txt.
+THREEDMOL_VERSION = "2.5.4"
+_JS_PATH = Path(__file__).parent / "data" / "js" / "3Dmol-min.js"
+
+# The CDN URL we replace — kept so a test can assert it never appears in any
+# emitted HTML.
+CDN_URL = "https://cdn.jsdelivr.net/npm/3dmol@2.5.4/build/3Dmol-min.js"
+
+
+@lru_cache(maxsize=1)
+def _js_data_uri() -> str:
+    """Return the vendored 3Dmol.js as a base64 ``data:`` URI (cached).
+
+    Empty string if the bundle is missing, in which case :func:`make_view`
+    falls back to py3Dmol's default (CDN) ``js`` rather than handing the viewer
+    an unusable source.
+    """
+    try:
+        raw = _JS_PATH.read_bytes()
+    except OSError as exc:
+        logger.warning("Vendored 3Dmol.js unreadable (%s); falling back to CDN", exc)
+        return ""
+    b64 = base64.b64encode(raw).decode("ascii")
+    return f"data:text/javascript;base64,{b64}"
+
+
+def make_view(**kwargs):
+    """Build a ``py3Dmol.view`` that loads 3Dmol.js offline (no CDN).
+
+    Identical to ``py3Dmol.view(**kwargs)`` except ``js`` defaults to a ``data:``
+    URI of the vendored 3Dmol.js, so the viewer never reaches the network. Use
+    this in place of ``py3Dmol.view(...)`` everywhere in the app. If the bundle
+    is missing we leave py3Dmol's default ``js`` (CDN) in place.
+    """
+    import py3Dmol
+
+    data_uri = _js_data_uri()
+    if data_uri and "js" not in kwargs:
+        kwargs["js"] = data_uri
+    return py3Dmol.view(**kwargs)
+
+
+def standalone_html(view_html: str) -> str:
+    """Return viewer HTML suitable for a standalone (exported) file.
+
+    Views built via :func:`make_view` already embed the vendored 3Dmol.js
+    loader (``js=<data: URI>``), so an exported file is self-contained and plays
+    offline as-is. Kept as a no-op pass-through for call-site clarity / API
+    stability.
+    """
+    return view_html