scrollback 0.1.0__py3-none-any.whl

scrollback/highlight.py

@@ -0,0 +1,128 @@
+"""A tiny, dependency-free syntax highlighter for code blocks in exports.
+
+Scope is intentionally narrow: the languages that dominate AI coding
+transcripts (bash/shell, python, javascript/jsx/typescript, json), plus a
+generic fallback that highlights strings/comments/numbers. The goal is a
+*self-contained* HTML export -- colourful code with no JS and no external
+dependency, suitable for printing or offline viewing.
+
+Safety: the public `highlight(code, lang)` takes RAW (unescaped) source,
+HTML-escapes it, and only ever emits `<span class="hl-...">` wrappers. It
+never emits attributes derived from the input, so transcript content
+cannot inject markup.
+"""
+
+from __future__ import annotations
+
+import html as _html
+import re
+
+# Token CSS classes (paired with the palette in CSS_LIGHT / CSS_DARK).
+_KW = "hl-kw"
+_STR = "hl-str"
+_COM = "hl-com"
+_NUM = "hl-num"
+_FUNC = "hl-fn"
+
+_PY_KEYWORDS = {
+    "def", "class", "return", "if", "elif", "else", "for", "while", "try",
+    "except", "finally", "with", "as", "import", "from", "in", "not", "and",
+    "or", "is", "lambda", "None", "True", "False", "pass", "break", "continue",
+    "raise", "yield", "global", "nonlocal", "assert", "del", "async", "await",
+}
+_JS_KEYWORDS = {
+    "function", "return", "if", "else", "for", "while", "do", "switch", "case",
+    "break", "continue", "const", "let", "var", "new", "class", "extends",
+    "import", "from", "export", "default", "try", "catch", "finally", "throw",
+    "typeof", "instanceof", "in", "of", "this", "super", "async", "await",
+    "yield", "null", "undefined", "true", "false", "void", "delete",
+}
+_SH_KEYWORDS = {
+    "if", "then", "elif", "else", "fi", "for", "while", "do", "done", "case",
+    "esac", "in", "function", "return", "export", "local", "cd", "echo",
+    "set", "unset", "source",
+}
+
+_LANG_KEYWORDS = {
+    "python": _PY_KEYWORDS, "py": _PY_KEYWORDS,
+    "javascript": _JS_KEYWORDS, "js": _JS_KEYWORDS, "jsx": _JS_KEYWORDS,
+    "typescript": _JS_KEYWORDS, "ts": _JS_KEYWORDS, "tsx": _JS_KEYWORDS,
+    "bash": _SH_KEYWORDS, "sh": _SH_KEYWORDS, "shell": _SH_KEYWORDS, "zsh": _SH_KEYWORDS,
+}
+
+_COMMENT_PREFIX = {
+    "python": "#", "py": "#", "bash": "#", "sh": "#", "shell": "#", "zsh": "#",
+    "yaml": "#", "yml": "#", "toml": "#", "ruby": "#", "r": "#",
+}
+
+# A single tokenizer pass: strings, comments, numbers, identifiers, other.
+_TOKEN = re.compile(
+    r"""
+    (?P<dstr>"(?:\\.|[^"\\])*") |
+    (?P<sstr>'(?:\\.|[^'\\])*') |
+    (?P<tstr>`(?:\\.|[^`\\])*`) |
+    (?P<num>\b\d+\.?\d*\b) |
+    (?P<ident>[A-Za-z_][A-Za-z0-9_]*) |
+    (?P<ws>\s+) |
+    (?P<other>.)
+    """,
+    re.VERBOSE,
+)
+
+
+def highlight(code: str, lang: str | None) -> str:
+    """Return HTML (escaped) for `code`, with `<span>` highlight wrappers."""
+    lang = (lang or "").lower()
+    keywords = _LANG_KEYWORDS.get(lang)
+    comment_prefix = _COMMENT_PREFIX.get(lang, "#" if keywords is _SH_KEYWORDS else None)
+
+    out: list[str] = []
+    for raw_line in code.split("\n"):
+        out.append(_highlight_line(raw_line, keywords, lang, comment_prefix))
+    return "\n".join(out)
+
+
+def _highlight_line(line: str, keywords, lang: str, comment_prefix: str | None) -> str:
+    # Whole-line comment handling for # / // styles (kept simple + safe).
+    stripped = line.lstrip()
+    indent = line[: len(line) - len(stripped)]
+    if comment_prefix and stripped.startswith(comment_prefix):
+        return indent + _wrap(_COM, _html.escape(stripped))
+    if lang in ("js", "jsx", "ts", "tsx", "javascript", "typescript") and stripped.startswith("//"):
+        return indent + _wrap(_COM, _html.escape(stripped))
+
+    pieces: list[str] = []
+    for m in _TOKEN.finditer(line):
+        kind = m.lastgroup
+        val = m.group()
+        if kind in ("dstr", "sstr", "tstr"):
+            pieces.append(_wrap(_STR, _html.escape(val)))
+        elif kind == "num":
+            pieces.append(_wrap(_NUM, _html.escape(val)))
+        elif kind == "ident" and keywords and val in keywords:
+            pieces.append(_wrap(_KW, _html.escape(val)))
+        else:
+            pieces.append(_html.escape(val))
+    return "".join(pieces)
+
+
+def _wrap(cls: str, escaped_text: str) -> str:
+    return f'<span class="{cls}">{escaped_text}</span>'
+
+
+# Inlined palette for the export. Theme-aware via prefers-color-scheme so the
+# single self-contained file looks right in both light and dark.
+HL_CSS = """
+.md pre code .hl-kw { color: #cf6cd6; }
+.md pre code .hl-str { color: #6aab73; }
+.md pre code .hl-com { color: #8a8f99; font-style: italic; }
+.md pre code .hl-num { color: #d39a4f; }
+.md pre code .hl-fn { color: #4c95d6; }
+@media (prefers-color-scheme: light) {
+  .md pre code .hl-kw { color: #a626a4; }
+  .md pre code .hl-str { color: #50a14f; }
+  .md pre code .hl-com { color: #9aa0a6; }
+  .md pre code .hl-num { color: #b76b01; }
+  .md pre code .hl-fn { color: #4078f2; }
+}
+"""

scrollback/katexbundle.py

@@ -0,0 +1,81 @@
+"""Inline the vendored KaTeX into a self-contained HTML export.
+
+The static HTML export must typeset math **offline** -- a researcher saves or
+prints a transcript and the equations have to render with no network and no
+sibling asset files. So when an export is rendered in ``math="rendered"``
+mode we embed everything KaTeX needs directly in the document:
+
+- the KaTeX stylesheet, with every ``@font-face`` ``url(...)`` rewritten to a
+  base64 ``data:`` URI so the fonts travel inside the file;
+- the KaTeX JavaScript;
+- a small boot script that typesets each ``.math-tex`` placeholder emitted by
+  :func:`scrollback.minimd.render`.
+
+The assets are the same files served to the live web app
+(``web/static/vendor/katex``); they are read once and cached per process.
+"""
+
+from __future__ import annotations
+
+import base64
+import functools
+import re
+from pathlib import Path
+
+_KATEX_DIR = Path(__file__).parent / "web" / "static" / "vendor" / "katex"
+_FONT_URL_RE = re.compile(r"url\(fonts/([A-Za-z0-9_.-]+)\.(woff2|woff|ttf)\)")
+_FONT_MIME = {"woff2": "font/woff2", "woff": "font/woff", "ttf": "font/ttf"}
+
+
+def available() -> bool:
+    """True if the vendored KaTeX JS + CSS are present."""
+    return (_KATEX_DIR / "katex.min.js").is_file() and (
+        _KATEX_DIR / "katex.min.css"
+    ).is_file()
+
+
+@functools.lru_cache(maxsize=1)
+def _inlined_css() -> str:
+    css = (_KATEX_DIR / "katex.min.css").read_text(encoding="utf-8")
+    fonts_dir = _KATEX_DIR / "fonts"
+
+    def _sub(m: re.Match[str]) -> str:
+        name, ext = m.group(1), m.group(2)
+        path = fonts_dir / f"{name}.{ext}"
+        if not path.is_file():
+            # Drop references to fonts we do not ship (only woff2 is vendored);
+            # browsers fall back to the woff2 face listed alongside.
+            return "url()"
+        data = base64.b64encode(path.read_bytes()).decode("ascii")
+        return f"url(data:{_FONT_MIME[ext]};base64,{data})"
+
+    return _FONT_URL_RE.sub(_sub, css)
+
+
+@functools.lru_cache(maxsize=1)
+def _katex_js() -> str:
+    return (_KATEX_DIR / "katex.min.js").read_text(encoding="utf-8")
+
+
+def head_assets() -> str:
+    """Return ``<style>`` (KaTeX CSS, fonts inlined) for the document head."""
+    if not available():
+        return ""
+    return f"<style>{_inlined_css()}</style>"
+
+
+def autorender_script() -> str:
+    """Return the ``<script>`` block: KaTeX plus the typeset-on-load boot code."""
+    if not available():
+        return ""
+    boot = (
+        "<script>"
+        "window.addEventListener('load',function(){"
+        "if(typeof katex==='undefined')return;"
+        "document.querySelectorAll('.math-tex').forEach(function(n){"
+        "try{katex.render(n.textContent,n,{displayMode:n.dataset.display==='true',"
+        "throwOnError:false,output:'html'});}catch(e){}"
+        "});});"
+        "</script>"
+    )
+    return f"<script>{_katex_js()}</script>\n{boot}"

scrollback/launcher_install.py

@@ -0,0 +1,209 @@
+"""Install double-clickable launchers for pip-installed users.
+
+The bundled launcher templates live in `scrollback/launchers/`. For a
+source checkout users could double-click them directly, but a
+`pip install` user needs them copied somewhere reachable. This module
+implements `scrollback install-launcher`:
+
+* macOS  -> copies `scrollback.command` to ~/Desktop (or `--dest`), and
+            optionally builds a real `scrollback.app` bundle.
+* Linux  -> installs `scrollback.desktop` into the application menu, and
+            copies `scrollback.sh` to ~/Desktop (or `--dest`).
+* Windows-> copies `scrollback.bat` to the Desktop (or `--dest`).
+
+It never overwrites without telling the user, and it prints exactly what
+it created so there is no hidden state.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import stat
+import sys
+from importlib import resources
+from pathlib import Path
+
+_PKG = "scrollback.launchers"
+
+
+def _read_bundled(name: str) -> str:
+    return resources.files(_PKG).joinpath(name).read_text(encoding="utf-8")
+
+
+def _desktop_dir() -> Path:
+    d = Path.home() / "Desktop"
+    return d if d.is_dir() else Path.home()
+
+
+def _make_executable(path: Path) -> None:
+    mode = path.stat().st_mode
+    path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def _write(path: Path, content: str, *, executable: bool = False) -> None:
+    path.write_text(content, encoding="utf-8")
+    if executable:
+        _make_executable(path)
+
+
+def install(dest: Path | None = None, *, desktop: bool = False,
+            app_bundle: bool = False) -> list[Path]:
+    """Install the OS-appropriate launcher(s). Returns the paths created.
+
+    The two selectors choose *which* artifacts to create:
+
+    - ``desktop``    -- the Desktop launcher (macOS ``.command`` / Windows
+      ``.bat`` / Linux ``.desktop`` + ``.sh``).
+    - ``app_bundle`` -- a double-clickable ``.app`` (macOS only).
+
+    If **neither** is requested, both are created (the "give me everything"
+    default). On platforms without an ``.app``, ``app_bundle`` falls back to
+    the Desktop launcher, so the flag never errors.
+    """
+    want_desktop = desktop or not (desktop or app_bundle)
+    want_app = app_bundle or not (desktop or app_bundle)
+
+    created: list[Path] = []
+    if sys.platform == "darwin":
+        created += _install_macos(dest, desktop=want_desktop, app_bundle=want_app)
+    elif sys.platform == "win32":
+        # No .app on Windows; any selection maps to the Desktop launcher.
+        created += _install_windows(dest)
+    else:
+        created += _install_linux(dest)
+    return created
+
+
+def _install_macos(dest: Path | None, *, desktop: bool, app_bundle: bool) -> list[Path]:
+    created: list[Path] = []
+    if desktop:
+        target_dir = dest or _desktop_dir()
+        target_dir.mkdir(parents=True, exist_ok=True)
+        cmd = target_dir / "scrollback.command"
+        # Generate with the interpreter path baked in (Finder/GUI launches run
+        # with a minimal PATH that excludes conda/venv bins).
+        _write(cmd, _command_script(), executable=True)
+        created.append(cmd)
+    if app_bundle:
+        created.append(_build_macos_app(dest))
+    return created
+
+
+def _command_script() -> str:
+    """A .command launcher that opens a Terminal window and shows status."""
+    # shlex.quote so an interpreter path with spaces/quotes/$ is shell-safe.
+    py = shlex.quote(sys.executable or "python3")
+    return (
+        "#!/bin/bash\n"
+        "# Generated by `scrollback install-launcher`. Double-click to run.\n"
+        f"PY={py}\n"
+        'if [ ! -x "$PY" ]; then PY="$(command -v python3 || command -v python)"; fi\n'
+        'echo "Starting scrollback  (close the app window to stop)"\n'
+        # --app: native window if pywebview is present (no lingering terminal);
+        # otherwise it falls back to a browser window that auto-stops the
+        # server when closed.
+        'exec "$PY" -m scrollback.cli web --app\n'
+    )
+
+
+def _runner_script() -> str:
+    """A self-contained launch script with the interpreter path baked in.
+
+    Uses the absolute path of the Python that is running `install-launcher`
+    (which, by construction, has scrollback installed). This survives the
+    minimal PATH that macOS/GUI launchers run with. Errors are logged to
+    ~/Library/Logs so a silent failure can be diagnosed.
+    """
+    # The script is intentionally dumb: it only locates the interpreter and
+    # delegates everything (including how to open a window) to Python, which
+    # owns all platform-specific logic. `--app` opens a native window when
+    # pywebview is available (no terminal; closing it stops the server), and
+    # otherwise falls back to a browser window with heartbeat auto-shutdown.
+    py = shlex.quote(sys.executable or "python3")
+    return (
+        "#!/bin/bash\n"
+        "# Generated by `scrollback install-launcher`.\n"
+        f"PY={py}\n"
+        'LOG="$HOME/Library/Logs/scrollback-launcher.log"\n'
+        'mkdir -p "$(dirname "$LOG")" 2>/dev/null\n'
+        'if [ ! -x "$PY" ]; then PY="$(command -v python3 || command -v python)"; fi\n'
+        'exec "$PY" -m scrollback.cli web --app >> "$LOG" 2>&1\n'
+    )
+
+
+def _build_macos_app(dest: Path | None) -> Path:
+    """Create a minimal double-clickable scrollback.app bundle."""
+    base = dest or (Path.home() / "Applications")
+    base.mkdir(parents=True, exist_ok=True)
+    app = base / "scrollback.app"
+    macos = app / "Contents" / "MacOS"
+    macos.mkdir(parents=True, exist_ok=True)
+
+    # Launcher script inside the bundle. macOS launches .app bundles with a
+    # minimal PATH that excludes conda/venv bins, so we bake the ABSOLUTE
+    # interpreter path (known at install time) instead of relying on PATH.
+    runner = macos / "scrollback"
+    _write(runner, _runner_script(), executable=True)
+
+    from . import __version__
+
+    # Copy the bundled .icns into Contents/Resources so Finder/Dock show it.
+    icon_line = ""
+    try:
+        icns = resources.files("scrollback.assets").joinpath("icon.icns").read_bytes()
+        resources_dir = app / "Contents" / "Resources"
+        resources_dir.mkdir(parents=True, exist_ok=True)
+        (resources_dir / "scrollback.icns").write_bytes(icns)
+        icon_line = "  <key>CFBundleIconFile</key><string>scrollback</string>\n"
+    except (OSError, ModuleNotFoundError, FileNotFoundError):
+        pass  # icon is optional; bundle still works without it
+
+    info = app / "Contents" / "Info.plist"
+    info.write_text(
+        '<?xml version="1.0" encoding="UTF-8"?>\n'
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" '
+        '"http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n'
+        '<plist version="1.0"><dict>\n'
+        "  <key>CFBundleInfoDictionaryVersion</key><string>6.0</string>\n"
+        "  <key>CFBundleName</key><string>scrollback</string>\n"
+        "  <key>CFBundleDisplayName</key><string>scrollback</string>\n"
+        "  <key>CFBundleIdentifier</key><string>dev.scrollback.app</string>\n"
+        f"  <key>CFBundleVersion</key><string>{__version__}</string>\n"
+        f"  <key>CFBundleShortVersionString</key><string>{__version__}</string>\n"
+        "  <key>CFBundlePackageType</key><string>APPL</string>\n"
+        "  <key>CFBundleExecutable</key><string>scrollback</string>\n"
+        + icon_line
+        + "  <key>LSUIElement</key><false/>\n"
+        "</dict></plist>\n",
+        encoding="utf-8",
+    )
+    return app
+
+
+def _install_windows(dest: Path | None) -> list[Path]:
+    target_dir = dest or _desktop_dir()
+    target_dir.mkdir(parents=True, exist_ok=True)
+    bat = target_dir / "scrollback.bat"
+    _write(bat, _read_bundled("scrollback.bat"))
+    return [bat]
+
+
+def _install_linux(dest: Path | None) -> list[Path]:
+    created: list[Path] = []
+    # 1) application-menu entry
+    apps_dir = (
+        dest
+        if dest
+        else Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share"))
+        / "applications"
+    )
+    apps_dir.mkdir(parents=True, exist_ok=True)
+    desktop = apps_dir / "scrollback.desktop"
+    _write(desktop, _read_bundled("scrollback.desktop"), executable=True)
+    created.append(desktop)
+    # 2) a double-clickable copy on the Desktop
+    sh = _desktop_dir() / "scrollback.sh"
+    _write(sh, _read_bundled("scrollback.sh"), executable=True)
+    created.append(sh)
+    return created

scrollback/launchers/scrollback.bat

@@ -0,0 +1,19 @@
+@echo off
+REM Double-clickable launcher for Windows.
+REM Starts the scrollback web app in a standalone browser window.
+
+where scrollback >nul 2>nul
+if %errorlevel%==0 (
+  scrollback web --window
+  goto :eof
+)
+
+python -c "import scrollback" >nul 2>nul
+if %errorlevel%==0 (
+  python -m scrollback.cli web --window
+  goto :eof
+)
+
+echo scrollback is not installed.
+echo Install it with:  pip install "scrollback[web]"
+pause

scrollback/launchers/scrollback.command

@@ -0,0 +1,19 @@
+#!/bin/bash
+# Double-clickable launcher for macOS (Finder: double-click this file).
+# Starts the scrollback web app and opens it in your default browser.
+#
+# Install a copy you can double-click with:  scrollback install-launcher
+# First-time setup: right-click -> Open (to bypass Gatekeeper once).
+#
+# If `scrollback` is not on PATH, this falls back to `python3 -m scrollback`.
+
+if command -v scrollback >/dev/null 2>&1; then
+  exec scrollback web
+elif python3 -c "import scrollback" >/dev/null 2>&1; then
+  exec python3 -m scrollback.cli web
+else
+  echo "scrollback is not installed."
+  echo "Install it with:  pip install \"scrollback[web]\""
+  echo
+  read -r -p "Press Return to close."
+fi

scrollback/launchers/scrollback.desktop

@@ -0,0 +1,10 @@
+[Desktop Entry]
+Type=Application
+Name=scrollback
+Comment=Browse your AI coding-agent sessions
+Exec=scrollback web --window
+Terminal=false
+Categories=Development;Utility;
+# Install: copy to ~/.local/share/applications/ (and `chmod +x` if needed),
+# or run `xdg-desktop-menu install scrollback.desktop`. Then launch from your
+# application menu like any other app.

scrollback/launchers/scrollback.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# Launcher for Linux / BSD. Make executable (chmod +x scrollback.sh) and run,
+# or wire it into a .desktop entry (see scrollback.desktop).
+
+if command -v scrollback >/dev/null 2>&1; then
+  exec scrollback web --window
+elif python3 -c "import scrollback" >/dev/null 2>&1; then
+  exec python3 -m scrollback.cli web --window
+else
+  echo "scrollback is not installed. Install with: pip install \"scrollback[web]\""
+  exit 1
+fi

scrollback/mathspan.py

@@ -0,0 +1,180 @@
+"""Detect and protect delimited-LaTeX math spans in transcript text.
+
+A model often replies with LaTeX -- inline (`$\\nabla\\cdot u = 0$`,
+`\\(x^2\\)`) or display (`$$E=mc^2$$`, `\\[\\int_0^1 x\\,dx\\]`). Left to the
+Markdown renderer, the `\\`, `_`, `*`, and `^` inside such a span get
+mangled (a `_` becomes emphasis, a stray `\\` is dropped, ...), corrupting
+the equation. This module finds those spans so the rest of the pipeline can
+shield them.
+
+Scope is *delimited* LaTeX only. The three forms math appears in are:
+delimited LaTeX (handled here, because it can be detected reliably),
+Unicode math (`\u2207\u00b7u`), and plain ASCII (`x^2 + y^2`). The latter two are
+deliberately out of scope -- detecting them would mean guessing, with false
+positives in ordinary prose and code.
+
+The detection is intentionally conservative:
+
+- Display delimiters (`$$...$$`, `\\[...\\]`) and the escaped-paren inline
+  form (`\\(...\\)`) are unambiguous and always recognised.
+- The single-`$...$` inline form is recognised only when it does not look
+  like ordinary currency/prose: no whitespace directly inside the
+  delimiters, no digit immediately after the closing `$` (so `$5` and
+  `$3.50` and `it cost $5 to $10` are left alone), and the body is
+  non-empty and single-line.
+- Nothing inside a fenced/inline code span is treated as math; the caller
+  is responsible for not handing code to this module (both `minimd` and the
+  browser pass only prose runs / use code placeholders first).
+
+The public surface is small:
+
+- `find_spans(text)` -> list of `Span` (start, end, body, mode, raw).
+- `protect(text)` -> `(masked_text, tokens)` where each math span is
+  replaced by an opaque placeholder safe to pass through Markdown.
+- `restore(html, tokens, render)` -> the placeholders swapped back, each
+  rendered by the supplied `render(body, display) -> str` callback.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# Placeholder wrapper. Uses NUL bytes so it cannot collide with real
+# transcript text and so the Markdown renderers treat it as inert inline
+# text (no special characters inside).
+_PH_OPEN = "\x00MATH"
+_PH_CLOSE = "\x00"
+_PH_RE = re.compile(r"\x00MATH(\d+)\x00")
+
+
+@dataclass(frozen=True)
+class Span:
+    """A detected math span within the source text."""
+
+    start: int  # index of the first delimiter char
+    end: int  # index just past the last delimiter char
+    body: str  # the LaTeX between the delimiters (delimiters stripped)
+    display: bool  # True for display math ($$ / \[), False for inline
+    raw: str  # the full matched text including delimiters
+
+
+# Ordered by precedence: longer / unambiguous delimiters first so e.g. `$$`
+# is consumed before the single-`$` rule ever sees it.
+#
+# Each entry is (compiled_regex, display, body_group). The regexes are
+# matched against the *whole* text with finditer; overlap is prevented by
+# scanning left to right and skipping matches that start inside an already
+# claimed span (see find_spans).
+_DISPLAY_DOLLAR = re.compile(r"\$\$(.+?)\$\$", re.DOTALL)
+_DISPLAY_BRACKET = re.compile(r"\\\[(.+?)\\\]", re.DOTALL)
+_INLINE_PAREN = re.compile(r"\\\((.+?)\\\)", re.DOTALL)
+# Single-dollar inline: no whitespace just inside, single line, non-empty,
+# not immediately followed by a digit (currency guard). The body may not
+# contain a `$`.
+_INLINE_DOLLAR = re.compile(r"\$(?!\s)([^$\n]*[^$\s])\$(?![\d])")
+
+_PATTERNS: tuple[tuple[re.Pattern[str], bool], ...] = (
+    (_DISPLAY_DOLLAR, True),
+    (_DISPLAY_BRACKET, True),
+    (_INLINE_PAREN, False),
+    (_INLINE_DOLLAR, False),
+)
+
+# Code regions, which must never be treated as math. Fenced blocks first so
+# their (possibly `$`-containing) bodies are claimed before inline spans.
+_FENCE_BLOCK = re.compile(r"(?m)^[ \t]*(`{3,}|~{3,}).*?\n.*?(?:^[ \t]*\1[ \t]*$|\Z)", re.DOTALL)
+_INLINE_CODE = re.compile(r"(`+)(?:.+?)\1")
+
+
+def _code_ranges(text: str) -> list[tuple[int, int]]:
+    ranges: list[tuple[int, int]] = []
+    for m in _FENCE_BLOCK.finditer(text):
+        ranges.append((m.start(), m.end()))
+
+    def _in_fence(pos: int) -> bool:
+        return any(a <= pos < b for a, b in ranges)
+
+    for m in _INLINE_CODE.finditer(text):
+        if not _in_fence(m.start()):
+            ranges.append((m.start(), m.end()))
+    return ranges
+
+
+def find_spans(text: str) -> list[Span]:
+    """Return the non-overlapping math spans in `text`, left to right.
+
+    Spans overlapping a fenced or inline code region are excluded -- code is
+    never math.
+    """
+    code = _code_ranges(text)
+
+    def _in_code(start: int, end: int) -> bool:
+        return any(start < b and a < end for a, b in code)
+
+    candidates: list[Span] = []
+    for pattern, display in _PATTERNS:
+        for m in pattern.finditer(text):
+            if _in_code(m.start(), m.end()):
+                continue
+            candidates.append(
+                Span(
+                    start=m.start(),
+                    end=m.end(),
+                    body=m.group(1),
+                    display=display,
+                    raw=m.group(0),
+                )
+            )
+    # Resolve overlaps: sort by start, then prefer the longer match at the
+    # same start (display `$$` over inline `$`). Greedily accept spans that
+    # do not overlap one already accepted.
+    candidates.sort(key=lambda s: (s.start, -(s.end - s.start)))
+    chosen: list[Span] = []
+    claimed_until = -1
+    for span in candidates:
+        if span.start >= claimed_until:
+            chosen.append(span)
+            claimed_until = span.end
+    return chosen
+
+
+def protect(text: str) -> tuple[str, list[Span]]:
+    """Replace math spans in `text` with inert placeholders.
+
+    Returns `(masked, tokens)`. Feed `masked` through the Markdown renderer
+    (the placeholders survive untouched), then call `restore` with the same
+    `tokens` to swap the rendered math back in.
+    """
+    spans = find_spans(text)
+    if not spans:
+        return text, []
+    out: list[str] = []
+    last = 0
+    for i, span in enumerate(spans):
+        out.append(text[last:span.start])
+        out.append(f"{_PH_OPEN}{i}{_PH_CLOSE}")
+        last = span.end
+    out.append(text[last:])
+    return "".join(out), spans
+
+
+def restore(rendered: str, tokens: list[Span], render) -> str:
+    """Swap placeholders in `rendered` back for `render(span)`.
+
+    `render` is a callback `(span: Span) -> str` returning the HTML (or
+    text) to substitute for each math span; it is responsible for its own
+    escaping.
+    """
+    if not tokens:
+        return rendered
+
+    def _sub(m: re.Match[str]) -> str:
+        return render(tokens[int(m.group(1))])
+
+    return _PH_RE.sub(_sub, rendered)
+
+
+def has_placeholder(text: str) -> bool:
+    """True if `text` still contains an unrestored math placeholder."""
+    return bool(_PH_RE.search(text))