dvm-mdview 0.1.0__py3-none-any.whl

dvm_mdview-0.1.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: dvm-mdview
+Version: 0.1.0
+Summary: Markdown viewer and live-preview editor with a graphical UI and a terminal UI
+Project-URL: Homepage, https://github.com/divyavanmahajan/mdview
+Project-URL: Issues, https://github.com/divyavanmahajan/mdview/issues
+License-Expression: MIT
+License-File: LICENSE
+License-File: src/mdview/web/vendor/LICENSE-katex
+License-File: src/mdview/web/vendor/LICENSE-mermaid
+Keywords: editor,gui,markdown,preview,tui,viewer
+Classifier: Environment :: Console
+Classifier: Environment :: MacOS X
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Editors
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Requires-Dist: linkify-it-py>=2.0
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: mdit-py-plugins>=0.4.1
+Requires-Dist: pygments>=2.17
+Requires-Dist: pywebview>=5.3
+Requires-Dist: textual>=3.0
+Description-Content-Type: text/markdown
+
+# mdview
+
+A Markdown viewer and editor with live preview, for macOS, Windows and Linux.
+It has two interfaces that share one renderer:
+
+- a **graphical UI** in a native window, and
+- a **terminal UI** for use in a shell or over SSH.
+
+Published on PyPI as **`dvm-mdview`**.
+
+## Run it
+
+With [uv](https://docs.astral.sh/uv/) installed, nothing else needs installing:
+
+```bash
+uvx dvm-mdview README.md
+```
+
+```bash
+uvx dvm-mdview --tui README.md
+```
+
+Or install it, which gives you the shorter `mdview` command:
+
+```bash
+uv tool install dvm-mdview
+```
+
+```bash
+mdview notes.md
+```
+
+| Option | Effect |
+|---|---|
+| *(none)* | Graphical UI. Falls back to the terminal UI when there is no display. |
+| `-t`, `--tui` | Terminal UI. |
+| `-b`, `--browser` | Graphical UI in your default browser instead of a native window. |
+| `-e`, `--edit` | Start with editor and preview side by side. |
+| `-r`, `--read` | Start with the preview only. |
+
+A file that does not exist yet is opened empty and created when you save.
+Passing a folder opens its `README.md`.
+
+## Features
+
+- **Live preview.** View, Split (editor and preview side by side) and Edit layouts. The preview
+  updates as you type.
+- **Link navigation.** Links to other Markdown files open in place, with back and forward history.
+  Links to headings scroll to them. Web links open in your browser. A link to a file that does not
+  exist starts a new document at that path.
+- **Markdown.** CommonMark with GitHub tables, task lists, strikethrough and autolinks, plus
+  footnotes, YAML front matter and heading anchors.
+- **Code highlighting** in both interfaces.
+- **Mermaid diagrams and LaTeX math** rendered in the graphical UI (shown as source in the terminal).
+  Both work offline; the libraries are bundled.
+- **Safe saving.** Files are written atomically, you are asked before unsaved changes are lost, and
+  a file changed by another program is reloaded (or flagged, if you have edits of your own).
+- Outline sidebar, light and dark themes, and relative images in the graphical UI.
+
+## Keys
+
+### Graphical UI
+
+`Cmd` replaces `Ctrl` on macOS.
+
+| Key | Action |
+|---|---|
+| `Ctrl+E` | Cycle View / Split / Edit |
+| `Ctrl+S`, `Ctrl+Shift+S` | Save, Save as |
+| `Ctrl+O`, `Ctrl+N` | Open, New |
+| `Alt+Left`, `Alt+Right` | Back, Forward |
+| `Ctrl+B`, `Ctrl+I`, `Ctrl+K` | Bold, italic, link |
+
+### Terminal UI
+
+| Key | Action |
+|---|---|
+| `Ctrl+E` | Cycle View / Split / Edit |
+| `F6` | Switch between editor and preview |
+| `Ctrl+S` | Save |
+| `Ctrl+O` | Open |
+| `Ctrl+L` | List the document's links and follow one |
+| `Alt+Left`, `Alt+Right` | Back, Forward |
+| `Ctrl+P` | Command palette (Save as, New, theme, ...) |
+| `Ctrl+Q` | Quit |
+
+Links can also be clicked with the mouse. While the preview has focus, single keys work too:
+`e` edit, `l` links, `o` open, `b` back, `f` forward, `j`/`k` scroll, `q` quit.
+
+## How it is built
+
+| Part | Library |
+|---|---|
+| Markdown parsing | [markdown-it-py](https://github.com/executablebooks/markdown-it-py) and [mdit-py-plugins](https://github.com/executablebooks/mdit-py-plugins) |
+| Code highlighting | [Pygments](https://pygments.org/) |
+| Native window | [pywebview](https://pywebview.flowrl.com/) (WebKit on macOS, WebView2 on Windows) |
+| Terminal UI | [Textual](https://textual.textualize.io/) |
+| Diagrams and math | [Mermaid](https://mermaid.js.org/) and [KaTeX](https://katex.org/), bundled |
+
+The graphical UI is a small web app served by a local backend (`src/mdview/server.py`) that listens
+only on `127.0.0.1` and requires a per-run secret token. Raw HTML in a document is displayed, but a
+strict Content-Security-Policy stops any script in it from running.
+
+On Linux a native window needs GTK or Qt bindings for pywebview; without them mdview uses the
+browser automatically.
+
+## Development
+
+```bash
+uv sync
+```
+
+```bash
+uv run pytest
+```
+
+```bash
+uv run mdview README.md
+```
+
+### Releasing
+
+The version comes from the git tag, so the tag and the PyPI version always match.
+
+1. Once, on pypi.org, add this repository as a *trusted publisher* for `dvm-mdview`
+   (workflow `publish.yml`, environment `pypi`).
+2. Tag a commit on `main` and push the tag:
+
+```bash
+git tag v1.2.3
+```
+
+```bash
+git push origin v1.2.3
+```
+
+The `Release` workflow builds version 1.2.3, creates the GitHub release and uploads to PyPI.
+
+## License
+
+MIT. Bundled Mermaid and KaTeX are MIT licensed; their licences are in `src/mdview/web/vendor/`.

dvm_mdview-0.1.0.dist-info/RECORD

@@ -0,0 +1,43 @@
+mdview/__init__.py,sha256=QNVQYqj8c4yWLj2uKX0TJ-04Vxdv9WZp75EGBCuela0,190
+mdview/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+mdview/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+mdview/cli.py,sha256=hnB3UwEahMve51MiRUABOtCO96OBuuoLQh95B8HPZoM,2499
+mdview/gui.py,sha256=h3IN7PaaPfd0ILOfoosb-ZDUUbXG5foMM6FOfYIgEaw,3625
+mdview/render.py,sha256=rHW64F4F_l_41TwF9NUyTEwCDaOQVGd8fAo9KueVKKg,8083
+mdview/server.py,sha256=NMXjLBbTj6ntgm-93ObRiDBPHGYEq2oQFc5TU4jMaPw,11823
+mdview/tui.py,sha256=rEXRTlsDHTqkOWAWQfaagCGfKijw5mqvtqWEmr9Un-k,19441
+mdview/web/app.css,sha256=gN-msc2HWV_DF2h2spLZ-ahMz5aXFpqyAVkikEhB3JM,8482
+mdview/web/app.js,sha256=mQ188a9oZV5yBk2HDhiuPvNTyjoTw8dqJ1pX6DAQeqY,25415
+mdview/web/index.html,sha256=CNmPFSh8htTAj8gvnJD7dh039KZ-BB-IM0CyUFpf_Sc,2624
+mdview/web/vendor/LICENSE-katex,sha256=dmzMHzBsiFqkVUKphGu9ClBbJ6A3TxRneBccIlTOGOM,1107
+mdview/web/vendor/LICENSE-mermaid,sha256=7J-2fcsl7MxBbtVuGquBkiLIBaKkv-TLGedVa_L_3oA,1089
+mdview/web/vendor/katex.min.css,sha256=AOCwlBcbB_WEIgdfRptP6sKy97zhruyUPAjaTWl_Tc8,24793
+mdview/web/vendor/katex.min.js,sha256=-hQEmLjPyDAsvl58sb28H5Urw4s_oljt4J5z7b-adLw,273081
+mdview/web/vendor/mermaid.min.js,sha256=M234A9h6OLcKAec25mbI92AdLOQvXkfI-v5dchB0uaM,5537838
+mdview/web/vendor/fonts/KaTeX_AMS-Regular.woff2,sha256=DN04fJWQoan5eUVgAi27WWVKfYbxh6oMgUla1C06cwg,28076
+mdview/web/vendor/fonts/KaTeX_Caligraphic-Bold.woff2,sha256=3ncB5Czx9M8LdmwD-yeXcgfu4vT9XXb6ghiEBtpD6kw,6912
+mdview/web/vendor/fonts/KaTeX_Caligraphic-Regular.woff2,sha256=XVPnCtYHwjUhYt7J4JI_tU7Nr6zL9gTNjc99APrLmJs,6908
+mdview/web/vendor/fonts/KaTeX_Fraktur-Bold.woff2,sha256=dERO_Vk8AF4_RXO0RSRwTArwqTf-kRzKnpQGjQ0UDT8,11348
+mdview/web/vendor/fonts/KaTeX_Fraktur-Regular.woff2,sha256=UYFNJw0G_wJV26B5mZT6TYyE0R8JlR1HWV9Kux82Atw,11316
+mdview/web/vendor/fonts/KaTeX_Main-Bold.woff2,sha256=D2DRuJeTjskYyM4HMJJBG6-UOPZzlGVpP_GLD50gsCE,25324
+mdview/web/vendor/fonts/KaTeX_Main-BoldItalic.woff2,sha256=mc1Co8By2Rjy9EmEqAfPeqFuE1Rf0IdfwHxsZfmecVs,16780
+mdview/web/vendor/fonts/KaTeX_Main-Italic.woff2,sha256=l0ecpszpBqvJYeyslvql-couYbjnZw1HWCa83umnwmc,16988
+mdview/web/vendor/fonts/KaTeX_Main-Regular.woff2,sha256=wjQs2Lhp4BdSqTIdwXIT_EDU0Ex5aIwdQ_LPMWq9eGY,26272
+mdview/web/vendor/fonts/KaTeX_Math-BoldItalic.woff2,sha256=3Ec0TbtstbZVyEYNVh9N9fUBuQyAStPGzsZf4yI1GrE,16400
+mdview/web/vendor/fonts/KaTeX_Math-Italic.woff2,sha256=evWMXsjxMqLd3pAnxteBTezOTTuCKhEZKkKiDi6XMmQ,16440
+mdview/web/vendor/fonts/KaTeX_SansSerif-Bold.woff2,sha256=6ZrlEUS_EjLvzBv-Wt02JixoZrD6qyT6dXQOG5hXemI,12216
+mdview/web/vendor/fonts/KaTeX_SansSerif-Italic.woff2,sha256=ALJqyCXiCVBWOW4FU7isJtP4rRWMOCbii0xFs4XEcUo,12028
+mdview/web/vendor/fonts/KaTeX_SansSerif-Regular.woff2,sha256=aOjHPvQq_TzOxYvw-6MCzORIk45_wCCl4x-KlS7uE0I,10344
+mdview/web/vendor/fonts/KaTeX_Script-Regular.woff2,sha256=A21OlRSbaf-bzAzVV3Hv6yX_o5Ryk-aazXjVrDKMaEs,9644
+mdview/web/vendor/fonts/KaTeX_Size1-Regular.woff2,sha256=a0fEAWa22-IaXfyncYQT8hR_0jmb4bpgXYrTnO3yXf4,5468
+mdview/web/vendor/fonts/KaTeX_Size2-Regular.woff2,sha256=0ExUIZ-ersbU1P1C37KHhZdaR5TWsvxx5Wa5zW24Qt0,5208
+mdview/web/vendor/fonts/KaTeX_Size3-Regular.woff2,sha256=c9WRJxsWBJYMsQu5D-4CFnCvcpcBfg6YSAszLRH1GZU,3624
+mdview/web/vendor/fonts/KaTeX_Size4-Regular.woff2,sha256=pK99QURAocF5CCXPtwDPnPQ7DyxLBPDrxSMBGtmFPsA,4928
+mdview/web/vendor/fonts/KaTeX_Typewriter-Regular.woff2,sha256=cdUX1ngneHz6vfGGkUzDNY7aU543kxlB8rL9SiH2jAs,13568
+dvm_mdview-0.1.0.dist-info/METADATA,sha256=tDVMakAwb-tfGHgX7xMn6Jc7X5InM9njh1wJEO8vEhM,5561
+dvm_mdview-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+dvm_mdview-0.1.0.dist-info/entry_points.txt,sha256=Qe5ZpLRorUw4blEDkewOV4sckD2RLVeocrJRcaVkgVg,72
+dvm_mdview-0.1.0.dist-info/licenses/LICENSE,sha256=ChIUAQiTt_OLpli_wB1UNm0E2wivUyUCr6HvfvG0GrA,1072
+dvm_mdview-0.1.0.dist-info/licenses/src/mdview/web/vendor/LICENSE-katex,sha256=dmzMHzBsiFqkVUKphGu9ClBbJ6A3TxRneBccIlTOGOM,1107
+dvm_mdview-0.1.0.dist-info/licenses/src/mdview/web/vendor/LICENSE-mermaid,sha256=7J-2fcsl7MxBbtVuGquBkiLIBaKkv-TLGedVa_L_3oA,1089
+dvm_mdview-0.1.0.dist-info/RECORD,,

dvm_mdview-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dvm_mdview-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+dvm-mdview = mdview.cli:main
+mdview = mdview.cli:main

dvm_mdview-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 divyavanmahajan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dvm_mdview-0.1.0.dist-info/licenses/src/mdview/web/vendor/LICENSE-katex

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-2020 Khan Academy and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dvm_mdview-0.1.0.dist-info/licenses/src/mdview/web/vendor/LICENSE-mermaid

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 - 2022 Knut Sveidqvist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mdview/__init__.py

@@ -0,0 +1,4 @@
+try:
+    from ._version import __version__  # written at build time from the git tag
+except ImportError:  # running from a source tree that was never built
+    __version__ = "0.0.0+unknown"

mdview/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

mdview/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

mdview/cli.py

@@ -0,0 +1,64 @@
+"""Command line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mdview",
+        description="Markdown viewer and live-preview editor (graphical and terminal UI).",
+    )
+    parser.add_argument("file", nargs="?", help="Markdown file to open (created on save if missing)")
+    ui = parser.add_mutually_exclusive_group()
+    ui.add_argument("-t", "--tui", action="store_true", help="use the terminal UI")
+    ui.add_argument("-g", "--gui", action="store_true", help="use the graphical UI (default)")
+    ui.add_argument(
+        "-b", "--browser", action="store_true",
+        help="graphical UI in the default web browser instead of a native window",
+    )
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("-e", "--edit", action="store_true", help="start with editor and preview side by side")
+    mode.add_argument("-r", "--read", action="store_true", help="start in read-only preview")
+    parser.add_argument("--port", type=int, default=0, help="port for --browser (default: any free port)")
+    parser.add_argument("--no-open", action="store_true", help="with --browser, do not launch the browser")
+    parser.add_argument("-V", "--version", action="version", version=f"mdview {__version__}")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    path = os.path.abspath(os.path.expanduser(args.file)) if args.file else None
+    if path and os.path.isdir(path):
+        for name in ("README.md", "index.md", "readme.md"):
+            if os.path.isfile(os.path.join(path, name)):
+                path = os.path.join(path, name)
+                break
+        else:
+            print(f"mdview: {path} is a folder without a README.md", file=sys.stderr)
+            return 2
+    mode = "split" if args.edit else "view" if args.read else None
+
+    from .gui import has_display
+
+    use_tui = args.tui
+    if not (args.tui or args.gui or args.browser) and not has_display():
+        use_tui = True  # e.g. an SSH session: no display to open a window on
+    if use_tui:
+        from .tui import run as run_tui
+
+        return run_tui(path, mode)
+
+    from .gui import run as run_gui
+    from .server import AppState
+
+    return run_gui(AppState(path, mode), args.browser, args.port, not args.no_open)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mdview/gui.py

@@ -0,0 +1,105 @@
+"""Graphical UI: a native window (pywebview) around the local web app."""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+import webbrowser
+
+from .server import AppState, start_server
+
+FILE_TYPES = ("Markdown (*.md;*.markdown;*.mdown;*.mkd;*.mdx;*.txt)", "All files (*.*)")
+
+
+def has_display() -> bool:
+    if sys.platform in ("win32", "darwin"):
+        return True
+    return bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
+
+
+def run_browser(state: AppState, port: int = 0, open_browser: bool = True) -> int:
+    """Serve the UI and show it in the default browser until interrupted."""
+    server, url = start_server(state, port)
+    print(f"mdview is running at {url}\nPress Ctrl+C to stop.", flush=True)
+    if open_browser:
+        webbrowser.open(url)
+    try:
+        while True:
+            time.sleep(3600)
+    except KeyboardInterrupt:
+        print()
+    finally:
+        server.shutdown()
+    return 0
+
+
+def run_window(state: AppState) -> int:
+    """Show the UI in a native window. Raises ImportError if pywebview is unusable."""
+    import logging
+
+    import webview
+
+    logging.getLogger("pywebview").setLevel(logging.CRITICAL)  # we report failures ourselves
+    server, url = start_server(state)
+    window = webview.create_window(
+        "mdview", url, width=1200, height=820, min_size=(480, 320), text_select=True
+    )
+    closing_for_real = threading.Event()
+
+    def native_dialog(kind: str, directory: str, name: str) -> str | None:
+        try:
+            dialogs = webview.FileDialog  # pywebview >= 6
+            open_kind, save_kind = dialogs.OPEN, dialogs.SAVE
+        except AttributeError:
+            open_kind, save_kind = webview.OPEN_DIALOG, webview.SAVE_DIALOG
+        if not os.path.isdir(directory):
+            directory = os.getcwd()
+        if kind == "save":
+            result = window.create_file_dialog(
+                save_kind, directory=directory, save_filename=name or "untitled.md",
+                file_types=FILE_TYPES,
+            )
+        else:
+            result = window.create_file_dialog(
+                open_kind, directory=directory, allow_multiple=False, file_types=FILE_TYPES
+            )
+        if not result:
+            return None
+        return result if isinstance(result, str) else result[0]
+
+    def on_closing():
+        if closing_for_real.is_set() or not state.dirty:
+            return True
+        # Unsaved changes: cancel the close and let the page ask Save / Discard.
+        # evaluate_js must not run on the GUI thread that is delivering this event.
+        threading.Thread(
+            target=lambda: window.evaluate_js("window.mdviewRequestClose()"), daemon=True
+        ).start()
+        return False
+
+    def close_window() -> None:
+        closing_for_real.set()
+        window.destroy()
+
+    state.native_dialog = native_dialog
+    state.set_title = window.set_title
+    state.close_window = close_window
+    window.events.closing += on_closing
+    try:
+        webview.start(private_mode=True)
+    finally:
+        server.shutdown()
+    return 0
+
+
+def run(state: AppState, browser: bool = False, port: int = 0, open_browser: bool = True) -> int:
+    if browser:
+        return run_browser(state, port, open_browser)
+    try:
+        return run_window(state)
+    except Exception as exc:  # no web engine, missing GTK/Qt, pythonnet trouble, ...
+        print(f"mdview: native window unavailable ({exc}); using the browser.", file=sys.stderr)
+        state.native_dialog = state.set_title = state.close_window = None
+        return run_browser(state, port, open_browser)