Skip to content

About and support

An About/Support window: capabilities, preferences, counters and a support bundle.

Same example in PowerShell: About and support

About and support

Real capture on KDE Plasma 6.6 Wayland with the released packages.

What it teaches: capabilities; desktop_preferences; host_diagnostics; export_support_bundle.

Run it

uv init --app myapp && cd myapp    # once: a uv project for your app
uv add nativehtmlkit
# save the example file(s) in the project folder, then:
uv run diagnostics.py

Related guide: diagnostics and troubleshooting

Source: diagnostics.py

View on GitHub

"""Diagnostics: an "About / Support" window with capabilities, counters and a support bundle.

What it teaches
  * ``Application.capabilities()`` for feature detection: the top-level flags say which APIs the
    host offers; ``features[name]["available"]`` is True/False when observed and None otherwise
  * ``Application.desktop_preferences()`` (colour scheme, reduced motion, high contrast)
  * ``Application.host_diagnostics()`` and the SDK recorder (``nativehtmlkit.diagnostics``):
    loss and failure counters
  * ``Document.diagnostics()`` (CSS/resource notes for one document)
  * ``export_support_bundle`` (a local, redacted ZIP; nothing is uploaded)

Run:  uv run diagnostics.py [OUTPUT_FOLDER]      (default: the temporary folder)
Tip:  set NATIVEHTMLKIT_DIAGNOSTICS=trace (or run ``uv run nativehtmlkit-python --diagnostics trace ...``)
      to record callback and request timing in the bundle.
"""
from __future__ import annotations

import html
import platform
import sys
import tempfile
import time
from pathlib import Path

import nativehtmlkit
from nativehtmlkit import Application, Document, diagnostics, export_support_bundle

PAGE = """<!doctype html>
<html><head><meta charset="utf-8"><style>
  body { font-family: system-ui, sans-serif; margin: 18px; font-size: 14px; }
  h2 { font-size: 16px; margin: 18px 0 6px; }
  table { border-collapse: collapse; }
  td, th { text-align: left; padding: 2px 12px 2px 0; vertical-align: top; }
  td.yes { color: #2e7d32; } td.no { color: #8a1c1c; }
  #bundle { font-family: monospace; font-size: 12px; }
</style></head>
<body>
  <h2>Host</h2><table id="host"></table>
  <h2>Features</h2><table id="features"></table>
  <h2>Desktop preferences</h2><table id="prefs"></table>
  <h2>Connection counters</h2><table id="counters"></table>
  <h2>Support</h2>
  <p><button id="refresh">Refresh</button> <button id="export">Save support bundle</button></p>
  <p id="bundle" role="status"></p>
</body></html>"""

# Top-level capability flag -> its entry in capabilities()["features"] (the host names drops differently).
FEATURES = {"clipboard_text": "clipboard_text", "file_dialogs": "file_dialogs", "external_open": "external_open",
            "drag_drop": "incoming_drop", "ime": "ime", "accessibility": "accessibility"}


def feature_state(caps: dict, flag: str) -> tuple[str, bool]:
    """(text, usable) for one feature.

    The top-level flag says whether the host offers the API in this session. The feature entry's
    ``available`` is True/False when the host has observed the native service and None ("not
    observed") otherwise; on a native desktop Core 1.0.3 reports None for these services.
    None is not False.
    """
    if not caps.get(flag):
        return "not available", False
    available = caps.get("features", {}).get(FEATURES[flag], {}).get("available")
    if available is None:
        return "enabled (not observed)", True
    return ("available", True) if available else ("unavailable", False)


def rows(pairs: list[tuple[str, object]]) -> str:
    """Values from the host are data: always escaped, never trusted as markup."""
    out = []
    for name, value in pairs:
        css = (' class="yes"' if value else ' class="no"') if isinstance(value, bool) else ""
        text = "unknown" if value is None else str(value)
        out.append(f"<tr><th>{html.escape(name)}</th><td{css}>{html.escape(text)}</td></tr>")
    return "".join(out)


class SupportWindow:
    def __init__(self, app: Application, document: Document, output: Path):
        self.app, self.document, self.output = app, document, output
        document.on("click", lambda _event: self.refresh(), element="refresh")
        document.on("click", lambda _event: self.export(), element="export")
        self.refresh()

    def refresh(self) -> dict:
        caps = self.app.capabilities()
        prefs = self.app.desktop_preferences()
        host = self.app.host_diagnostics()
        recorder = diagnostics.recorder()
        summary = recorder.summary()
        failures = sum(1 for r in recorder.history() if r.get("event") == "callback.failed")
        counters = {
            "Host dropped notifications": host.get("dropped_notifications"),
            "SDK dropped notifications": self.app.rpc.dropped_notifications,
            "Pending host jobs": host.get("pending_jobs"),
            "Callback failures": failures,
            "SDK records (dropped)": f"{summary['records']} ({summary['dropped']})",
            "Document diagnostics": len(self.document.diagnostics().get("diagnostics", [])),
        }
        self.document.batch([
            {"op": "replace_children_html", "element": "host", "html": rows([
                ("Platform", caps.get("platform")), ("Native session", caps.get("native")),
                ("Headless", caps.get("headless")), ("Renderer", caps.get("renderer")),
                ("CSS profile", caps.get("css_profile")), ("Max windows", caps.get("max_windows")),
                ("Python", f"{platform.python_implementation()} {platform.python_version()}"),
                ("SDK", nativehtmlkit.__version__)])},
            {"op": "replace_children_html", "element": "features", "html": "".join(
                f'<tr><th>{html.escape(flag)}</th><td class="{"yes" if usable else "no"}">{html.escape(text)}</td></tr>'
                for flag, (text, usable) in ((flag, feature_state(caps, flag)) for flag in FEATURES))},
            {"op": "replace_children_html", "element": "prefs", "html": rows([
                ("Source", prefs.get("source")), ("Colour scheme", prefs.get("color_scheme")),
                ("Reduced motion", prefs.get("reduced_motion")), ("High contrast", prefs.get("high_contrast"))])},
            {"op": "replace_children_html", "element": "counters", "html": rows(list(counters.items()))},
        ])
        return counters

    def export(self) -> Path | None:
        target = self.output / f"nativehtmlkit-support-{time.strftime('%Y%m%d-%H%M%S')}.zip"
        try:
            path = export_support_bundle(target, overwrite=True)
        except (OSError, ValueError) as error:
            self.document.set_text("bundle", f"Could not save the bundle: {error}")
            return None
        self.document.set_text("bundle", f"Saved {path} ({path.stat().st_size} bytes). Attach it to a bug report.")
        return path


def build(app: Application, output: Path) -> SupportWindow:
    window = app.open_html(PAGE, title="About and support", width=760, height=640)
    return SupportWindow(app, window.document, output)


def main() -> None:
    with Application.start(name="Diagnostics") as app:
        output = Path(sys.argv[1]) if len(sys.argv) > 1 else Path(tempfile.gettempdir())
        build(app, output)
        app.run()


if __name__ == "__main__":
    main()