python-color-math 0.1.0__py3-none-any.whl

color_math/parsers/taxonomy.py

@@ -0,0 +1,124 @@
+"""Mathematical taxonomy and semantic role coloring."""
+from __future__ import annotations
+import re
+
+from ..config import COLORS, MATH_CONSTANTS, MATH_PARAMETERS, MATH_FUNCTIONS
+from ..utils.spans import ColorSpan
+from ..utils.latex_helpers import read_color_command, read_braced
+from .units import find_unit_spans, UnitSpan
+from .differentials import find_differential_spans, DifferentialSpan
+from .dimensionless import find_dimensionless_spans, DimensionlessSpan
+
+
+OPAQUE_MACROS = frozenset({
+    "text", "mathrm", "mathbf", "mathit", "mathsf", "mathtt", "mathcal",
+    "mathbb", "boldsymbol", "operatorname", "textbf", "textit", "textrm", "texttt"
+})
+
+
+def _skip_comment(text: str, start: int) -> int:
+    idx = start + 1
+    while idx < len(text) and text[idx] not in ("\r", "\n"):
+        idx += 1
+    if idx < len(text) and text[idx] == "\r" and idx + 1 < len(text) and text[idx + 1] == "\n":
+        return idx + 2
+    return min(idx + 1, len(text))
+
+
+def collect_taxonomy_spans(
+    body: str,
+    palette: dict[str, str] | None = None,
+    unit_spans: list[UnitSpan] | None = None,
+    diff_spans: list[DifferentialSpan] | None = None,
+    dim_spans: list[DimensionlessSpan] | None = None,
+) -> list[ColorSpan]:
+    """Collects semantic spans for constants, parameters, and bound indices."""
+    pal = palette or COLORS
+    units = unit_spans if unit_spans is not None else find_unit_spans(body)
+    diffs = diff_spans if diff_spans is not None else find_differential_spans(body)
+    dims = dim_spans if dim_spans is not None else find_dimensionless_spans(body)
+    spans: list[ColorSpan] = []
+
+    # 1. Bound iteration indices in \sum, \prod, \lim
+    index_re = re.compile(
+        r"(\\(?:sum|prod|coprod|bigcup|bigcap|lim|inf|sup))_\{?\s*([A-Za-z])\s*(?:=|\\to)"
+    )
+    for m in index_re.finditer(body):
+        var_name = m.group(2)
+        var_start = m.start() + m.group(0).rfind(var_name)
+        spans.append(ColorSpan(var_start, var_start + len(var_name), pal.get("chain", "#9ece6a"), priority=23))
+
+    # 2. Token-level scan for constants, functions, parameters, and dot derivatives
+    idx = 0
+    while idx < len(body):
+        if body[idx] == "%":
+            idx = _skip_comment(body, idx)
+            continue
+
+        existing = read_color_command(body, idx)
+        if existing is not None:
+            idx = existing[1]
+            continue
+
+        if any(u.start <= idx < u.end for u in units):
+            idx = next(u.end for u in units if u.start <= idx < u.end)
+            continue
+        if any(d.start <= idx < d.end for d in diffs):
+            idx = next(d.end for d in diffs if d.start <= idx < d.end)
+            continue
+        if any(d.start <= idx < d.end for d in dims):
+            idx = next(d.end for d in dims if d.start <= idx < d.end)
+            continue
+
+        if body[idx] == "\\":
+            m = re.match(r"^(\\[A-Za-z]+|\\.)", body[idx:])
+            if m:
+                cmd_name = m.group(1)
+                cmd_end = idx + len(cmd_name)
+
+                macro_key = cmd_name[1:]
+                if macro_key in OPAQUE_MACROS:
+                    braced = read_braced(body, cmd_end)
+                    if braced is not None:
+                        idx = braced[1]
+                        continue
+
+                if cmd_name in ("\\dot", "\\ddot", "\\dddot"):
+                    target_start = cmd_end
+                    while target_start < len(body) and body[target_start].isspace():
+                        target_start += 1
+                    if target_start < len(body):
+                        target_end = target_start + 1
+                        if body[target_start] == "{":
+                            braced = read_braced(body, target_start)
+                            if braced is not None:
+                                target_end = braced[1]
+                        else:
+                            let_m = re.match(r"^[a-zA-Z]('*)*", body[target_start:])
+                            if let_m:
+                                target_end = target_start + len(let_m.group(0))
+                        spans.append(ColorSpan(idx, target_end, pal.get("derivative", "#bb9af7"), priority=22))
+                        idx = target_end
+                        continue
+
+                if cmd_name in MATH_CONSTANTS:
+                    spans.append(ColorSpan(idx, cmd_end, pal.get("orange", "#e0af68"), priority=22))
+                    idx = cmd_end
+                    continue
+
+                if cmd_name in MATH_FUNCTIONS:
+                    spans.append(ColorSpan(idx, cmd_end, pal.get("main", "#7aa2f7"), priority=22))
+                    idx = cmd_end
+                    continue
+
+                if cmd_name in MATH_PARAMETERS:
+                    spans.append(ColorSpan(idx, cmd_end, pal.get("parameter", pal.get("derivative", "#bb9af7")), priority=20))
+                    idx = cmd_end
+                    continue
+
+                idx = cmd_end
+                continue
+
+        idx += 1
+
+    return sorted(spans, key=lambda s: s.start)

color_math/parsers/units.py

@@ -0,0 +1,98 @@
+"""Physical units and metric prefixes disambiguation."""
+from __future__ import annotations
+from dataclasses import dataclass
+import re
+
+from ..config import COLORS
+from ..utils.spans import ColorSpan
+
+
+@dataclass
+class UnitSpan:
+    start: int
+    end: int
+    text: str
+
+
+SI_UNITS = (
+    r"m|s|g|Hz|N|Pa|J|W|C|V|F|T|H|mol|L|l|K|bar|atm|torr|eV|cal|rad|deg|\\Omega|dB|bps|B|Ω"
+)
+PREFIXES = r"k|M|G|T|c|m|n|p|f|d|da|\\mu|µ"
+SAFE_MICRO_UNITS = r"m|s|g|mol|Hz|Pa|bar|rad|\\Omega|L|l"
+AMBIGUOUS_MICRO_UNITS = r"N|A|V|F|H|W|J|C"
+
+
+def find_unit_spans(body: str) -> list[UnitSpan]:
+    """Scans LaTeX math body to identify physical unit spans."""
+    spans: list[UnitSpan] = []
+
+    def add_span(start: int, end: int, text: str) -> None:
+        if start >= end:
+            return
+        if not any(start < s.end and end > s.start for s in spans):
+            spans.append(UnitSpan(start, end, text))
+
+    # 1a. \mu\text{...} or \mu\mathrm{...}
+    micro_text_re = re.compile(
+        r"\\mu\s*(?:\\(?:text|mathrm)\s*\{\s*([A-Za-z°℃%Ωμ/^0-9\s.\-]+?)\s*\})(?:\^\{?-?\d+\}?)?"
+    )
+    for m in micro_text_re.finditer(body):
+        add_span(m.start(), m.end(), m.group(0))
+
+    # 1b. Bare \mu with safe micro units: \mu m, \mu s, etc.
+    safe_micro_re = re.compile(
+        r"\\mu\s*(" + SAFE_MICRO_UNITS + r")(?![A-Za-z0-9_])(?:\^\{?-?\d+\}?)?"
+    )
+    for m in safe_micro_re.finditer(body):
+        add_span(m.start(), m.end(), m.group(0))
+
+    # 2. Degree units: ^\circ C, ^\circ\text{C}, ^\circ F
+    deg_re = re.compile(r"\^\s*\\circ\s*(?:\\(?:text|mathrm)\s*\{[A-Za-z]+\}|[A-Za-z]+)")
+    for m in deg_re.finditer(body):
+        add_span(m.start(), m.end(), m.group(0))
+
+    # 3. Units preceded by a number (Magnitude + Unit)
+    num_unit_pattern = (
+        r"(?:^|[^A-Za-z0-9_])(?:\d+(?:\.\d+)?|\.\d+)(?:\s*(?:\\times|\\cdot|·|\*)\s*10\^\{?[+-]?\d+\}?|\s*[eE][+-]?\d+)?(?:\s*|\,|\:|\;|\s*\\quad|\s*\\qquad|~)*"
+        r"("
+        r"\\(?:text|mathrm)\s*\{[^}]+\}(?:\^\{?-?\d+\}?)?"
+        r"|"
+        r"\\mu\s*(?:" + SAFE_MICRO_UNITS + r"|" + AMBIGUOUS_MICRO_UNITS + r")(?![A-Za-z0-9_])(?:\^\{?-?\d+\}?)?"
+        r"|"
+        r"(?:(?:" + PREFIXES + r")?(?:" + SI_UNITS + r"))(?:\/(?:(?:" + PREFIXES + r")?(?:" + SI_UNITS + r")))*(?:\^\{?-?\d+\}?)?(?![A-Za-z0-9_({])"
+        r")"
+    )
+    for m in re.finditer(num_unit_pattern, body):
+        full_match = m.group(0)
+        unit_part = m.group(1)
+        unit_offset = full_match.rfind(unit_part)
+        unit_start = m.start() + unit_offset
+        unit_end = unit_start + len(unit_part)
+        add_span(unit_start, unit_end, unit_part)
+
+    # 4. Standalone Text / mathrm units with \text{...} or \mathrm{...}
+    text_unit_re = re.compile(
+        r"\\(?:text|mathrm)\s*\{\s*([A-Za-z°℃%Ωμ/^0-9\s.\-]+?)\s*\}(?:\^\{?-?\d+\}?)?"
+    )
+    is_unit_re = re.compile(
+        r"^(?:(?:" + PREFIXES + r")?(?:" + SI_UNITS + r"))(?:\/(?:(?:" + PREFIXES + r")?(?:" + SI_UNITS + r")))*(?:\^\{?-?\d+\}?)?$",
+        re.IGNORECASE,
+    )
+    for m in text_unit_re.finditer(body):
+        inner = m.group(1).strip()
+        if is_unit_re.match(inner):
+            add_span(m.start(), m.end(), m.group(0))
+
+    return sorted(spans, key=lambda s: s.start)
+
+
+def collect_unit_spans(
+    body: str,
+    palette: dict[str, str] | None = None,
+    unit_spans: list[UnitSpan] | None = None,
+) -> list[ColorSpan]:
+    """Returns ColorSpans for units with unit color."""
+    pal = palette or COLORS
+    units = unit_spans if unit_spans is not None else find_unit_spans(body)
+    unit_color = pal.get("unit", "#73daca")
+    return [ColorSpan(u.start, u.end, unit_color, priority=25) for u in units]

color_math/parsers/variable_hash.py

@@ -0,0 +1,126 @@
+"""Variable data-flow hashing parser."""
+from __future__ import annotations
+import re
+
+from ..config import VARIABLE_HASH_PALETTE, hash_string_to_color, MATH_ACCENTS
+from ..utils.spans import ColorSpan
+from ..utils.latex_helpers import read_color_command, read_braced
+from .units import find_unit_spans, UnitSpan
+from .differentials import find_differential_spans, DifferentialSpan
+from .dimensionless import find_dimensionless_spans, DimensionlessSpan
+
+
+OPAQUE_MACROS = frozenset({
+    "text", "mathrm", "mathbf", "mathit", "mathsf", "mathtt", "mathcal",
+    "mathbb", "boldsymbol", "operatorname", "textbf", "textit", "textrm", "texttt"
+})
+
+
+def _skip_comment(text: str, start: int) -> int:
+    idx = start + 1
+    while idx < len(text) and text[idx] not in ("\r", "\n"):
+        idx += 1
+    if idx < len(text) and text[idx] == "\r" and idx + 1 < len(text) and text[idx + 1] == "\n":
+        return idx + 2
+    return min(idx + 1, len(text))
+
+
+def collect_variable_spans(
+    body: str,
+    palette: list[str] | None = None,
+    unit_spans: list[UnitSpan] | None = None,
+    diff_spans: list[DifferentialSpan] | None = None,
+    dim_spans: list[DimensionlessSpan] | None = None,
+) -> list[ColorSpan]:
+    """Assigns deterministic colors to distinct identifiers across an expression."""
+    pal = palette or VARIABLE_HASH_PALETTE
+    units = unit_spans if unit_spans is not None else find_unit_spans(body)
+    diffs = diff_spans if diff_spans is not None else find_differential_spans(body)
+    dims = dim_spans if dim_spans is not None else find_dimensionless_spans(body)
+    spans: list[ColorSpan] = []
+
+    idx = 0
+    while idx < len(body):
+        if body[idx] == "%":
+            idx = _skip_comment(body, idx)
+            continue
+
+        existing = read_color_command(body, idx)
+        if existing is not None:
+            idx = existing[1]
+            continue
+
+        if any(u.start <= idx < u.end for u in units):
+            idx = next(u.end for u in units if u.start <= idx < u.end)
+            continue
+        if any(d.start <= idx < d.end for d in diffs):
+            idx = next(d.end for d in diffs if d.start <= idx < d.end)
+            continue
+        if any(d.start <= idx < d.end for d in dims):
+            idx = next(d.end for d in dims if d.start <= idx < d.end)
+            continue
+
+        # Backslash commands
+        if body[idx] == "\\":
+            m = re.match(r"^(\\[A-Za-z]+|\\.)", body[idx:])
+            if m:
+                cmd_name = m.group(1)
+                cmd_end = idx + len(cmd_name)
+
+                # Accents like \dot, \ddot, \vec, \hat, \bar, \tilde
+                if cmd_name in MATH_ACCENTS:
+                    target_start = cmd_end
+                    while target_start < len(body) and body[target_start].isspace():
+                        target_start += 1
+                    if target_start < len(body):
+                        if body[target_start] == "{":
+                            braced = read_braced(body, target_start)
+                            if braced is not None:
+                                inner = body[braced[0]:braced[1]]
+                                base_m = re.search(r"[a-zA-Z]", inner)
+                                base_letter = base_m.group(0) if base_m else "x"
+                                color = hash_string_to_color(base_letter, pal)
+                                spans.append(ColorSpan(idx, braced[1], color, priority=15))
+                                idx = braced[1]
+                                continue
+                        else:
+                            let_m = re.match(r"^[a-zA-Z]('*)*", body[target_start:])
+                            if let_m:
+                                full_var = let_m.group(0)
+                                base_letter = full_var.replace("'", "")
+                                color = hash_string_to_color(base_letter, pal)
+                                spans.append(ColorSpan(idx, target_start + len(full_var), color, priority=15))
+                                idx = target_start + len(full_var)
+                                continue
+
+                macro_key = cmd_name[1:]
+                if macro_key in OPAQUE_MACROS:
+                    braced = read_braced(body, cmd_end)
+                    if braced is not None:
+                        idx = braced[1]
+                        continue
+
+                idx = cmd_end
+                continue
+
+        # Single letter variables (optionally with prime): x, y, z, t, x', y''
+        var_m = re.match(r"^[a-zA-Z]('*)*", body[idx:])
+        if var_m:
+            full_var = var_m.group(0)
+            base_letter = full_var.replace("'", "")
+            var_end = idx + len(full_var)
+
+            # Check if followed by ( or \left( -> function call like f(x)
+            after_var = body[var_end:].lstrip()
+            is_function = after_var.startswith("(") or after_var.startswith(r"\left(")
+
+            if not is_function:
+                color = hash_string_to_color(base_letter, pal)
+                spans.append(ColorSpan(idx, var_end, color, priority=15))
+
+            idx = var_end
+            continue
+
+        idx += 1
+
+    return sorted(spans, key=lambda s: s.start)

color_math/self_test.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+
+from .adapters import transform_document
+from .converters.block import convert_text
+from .converters.matrix import convert_matrix_block
+from .parsers.math_parser import (
+    format_math_structure,
+    parse_math_blocks,
+    parse_math_body,
+)
+from .undo import uncolor_fragment, uncolor_text
+
+
+Check = tuple[str, object, object]
+
+
+def _run_checks(checks: Iterable[Check]) -> int:
+    failed = False
+    print("Running installed self-tests...\n")
+    for name, actual, expected in checks:
+        passed = actual == expected
+        print(f"{'OK' if passed else 'FAIL'}  {name}")
+        if not passed:
+            print(f"Expected: {expected!r}")
+            print(f"Got:      {actual!r}\n")
+            failed = True
+    print("\nAll tests passed." if not failed else "\nSome tests failed.")
+    return int(failed)
+
+
+def run_self_test(update_generated: bool = False) -> int:
+    """Run installed smoke checks without reading or writing repository files."""
+    if update_generated:
+        print(
+            "--update-generated is repository-only; run "
+            "`python -m tests.self_test --update-generated` from a checkout."
+        )
+        return 2
+
+    nested = r"$$y(x(g(3)))$$"
+    nested_colored = (
+        r"$$\textcolor{#7aa2f7}{y}("
+        r"\textcolor{#bb9af7}{x}("
+        r"\textcolor{#9ece6a}{g}("
+        r"\textcolor{#e0af68}{3})))$$"
+    )
+    prime = r"$$f'(g(3))$$"
+    prime_colored = (
+        r"$$\textcolor{#7aa2f7}{f'}("
+        r"\textcolor{#bb9af7}{g}("
+        r"\textcolor{#e0af68}{3}))$$"
+    )
+    fenced = "```latex\n$$\\sum_{i=1}^n$$\n```"
+    nested_fence = (
+        "- item\n"
+        "  > [!note]\n"
+        "  > ~~~~latex\n"
+        "  > $$y(x(g(3)))$$\n"
+        "  > ~~~~\n"
+    )
+    commented = "$$f(x)% }\n+g(x)% {\n+h(x)$$"
+    commented_colored = (
+        "$$\\textcolor{#7aa2f7}{f}(x)% }\n"
+        "+\\textcolor{#7aa2f7}{g}(x)% {\n"
+        "+\\textcolor{#7aa2f7}{h}(x)$$"
+    )
+    verb = r"$$\verb|y(x(g(3)))|$$"
+    verb_star = r"$$\verb*|y(x(g(3)))|$$"
+    scalar_sum = r"$$\sum_{i=1}^{n} x_i$$"
+    nested_array = (
+        r"$$\mathbf{M}=\left(\begin{array}{cc}a&b\\c&d"
+        r"\end{array}\right)$$"
+    )
+    nested_array_colored = (
+        r"$$\textcolor{#7aa2f7}{\mathbf{M}}\textcolor{white}{=}"
+        r"\textcolor{#bb9af7}{\left(\begin{array}{cc}"
+        r"\textcolor{#7aa2f7}{a}&\textcolor{#bb9af7}{b}\\"
+        r"\textcolor{#9ece6a}{c}&\textcolor{#7aa2f7}{d}"
+        r"\end{array}\right)}$$"
+    )
+    grouped_command = r"$$\operatorname*{arg\,max}_{x} f(x)$$"
+    grouped_command_colored = (
+        r"$$\textcolor{#7aa2f7}{\operatorname*{arg"
+        r"\textcolor{white}{\,}max}}_"
+        r"{\textcolor{#9ece6a}{x}} \textcolor{#7aa2f7}{f}(x)$$"
+    )
+    styled = r"$$f(x)+\displaystyle g(x)$$"
+    styled_colored = (
+        r"$$\textcolor{#7aa2f7}{f}(x)+\displaystyle "
+        r"\textcolor{#7aa2f7}{g}(x)$$"
+    )
+    inline_code = "Prose `$$x=1$$` remains plain."
+    prose = "# Original Equations\n\nOrdinary prose stays unchanged.\n"
+    anki = r"Front\t\(f(x)\)"
+    tex = "\\documentclass{article}\n\\begin{document}\n$f(x)$\n\\end{document}\n"
+    notebook = json.dumps(
+        {
+            "cells": [
+                {"cell_type": "markdown", "metadata": {}, "source": "$$f(x)$$"},
+                {"cell_type": "code", "metadata": {}, "source": "$$f(x)$$"},
+            ],
+            "metadata": {},
+            "nbformat": 4,
+            "nbformat_minor": 5,
+        }
+    )
+    notebook_colored = transform_document(notebook, "jupyter")
+
+    return _run_checks(
+        (
+            ("scoped nested colors", convert_text(nested), nested_colored),
+            ("exact undo round trip", uncolor_text(nested_colored), nested),
+            (
+                "conversion idempotence",
+                convert_text(nested_colored),
+                nested_colored,
+            ),
+            ("prime notation", convert_text(prime), prime_colored),
+            ("prime round trip", uncolor_text(prime_colored), prime),
+            (
+                "no invented primes",
+                "y'" in convert_text(
+                    r"$$\frac{d}{dx}f(y)^n=nf(y)^{n-1}\cdot f'(y)y$$"
+                ),
+                False,
+            ),
+            ("prose preservation", convert_text(prose), prose),
+            ("fenced code preservation", convert_text(fenced), fenced),
+            (
+                "comment braces round trip",
+                uncolor_text(convert_text(commented)),
+                commented,
+            ),
+            (
+                "comment braces idempotence",
+                convert_text(commented_colored),
+                commented_colored,
+            ),
+            (
+                "nested tilde fence preservation",
+                convert_text(nested_fence),
+                nested_fence,
+            ),
+            (
+                "nested tilde fence is not parsed",
+                parse_math_blocks(nested_fence),
+                [],
+            ),
+            ("verb payload preservation", convert_text(verb), verb),
+            ("verb-star payload preservation", convert_text(verb_star), verb_star),
+            (
+                "verb payload is not inspected",
+                format_math_structure(parse_math_body(verb[2:-2])),
+                "No nested function calls found.",
+            ),
+            (
+                "scalar sum is not a matrix",
+                convert_matrix_block(scalar_sum),
+                None,
+            ),
+            (
+                "nested array matrix recognition",
+                convert_matrix_block(nested_array),
+                nested_array_colored,
+            ),
+            (
+                "operatorname-star stays whole",
+                convert_text(grouped_command),
+                grouped_command_colored,
+            ),
+            (
+                "style declaration stays unwrapped",
+                convert_text(styled),
+                styled_colored,
+            ),
+            ("inline code preservation", convert_text(inline_code), inline_code),
+            (
+                "text macro preservation",
+                convert_text(r"$$f(\text{use x=y literally})$$"),
+                r"$$\textcolor{#7aa2f7}{f}(\text{use x=y literally})$$",
+            ),
+            (
+                "malformed script preservation",
+                convert_text(r"$$x^{abc$$"),
+                r"$$x^{abc$$",
+            ),
+            (
+                "unclosed call preservation",
+                convert_text(r"$$y(x$$"),
+                r"$$y(x$$",
+            ),
+            (
+                "nested function structure",
+                format_math_structure(parse_math_body("y(x(g(3)))")),
+                "Function y\n  Function x\n    Function g\n      Constant 3",
+            ),
+            (
+                "legacy and scoped undo",
+                uncolor_fragment(r"\textcolor{red}{x+\color{blue}{y}}"),
+                "x+y",
+            ),
+            (
+                "Anki adapter round trip",
+                transform_document(transform_document(anki, "anki"), "anki", True),
+                anki,
+            ),
+            (
+                "native TeX adapter round trip",
+                transform_document(transform_document(tex, "tex"), "tex", True),
+                tex,
+            ),
+            (
+                "Jupyter adapter changes only Markdown cells",
+                (
+                    "textcolor" in json.loads(notebook_colored)["cells"][0]["source"]
+                    and json.loads(notebook_colored)["cells"][1]["source"] == "$$f(x)$$"
+                ),
+                True,
+            ),
+        )
+    )

color_math/undo.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from .parsers.markdown_scanner import scan_markdown
+from .utils.latex_helpers import (
+    COMMAND_RE,
+    read_color_wrapper,
+    read_comment_end,
+    read_verb_end,
+)
+
+
+def uncolor_fragment(text: str) -> str:
+    r"""Remove nested ``\textcolor`` and legacy ``\color`` wrappers."""
+    output: list[str] = []
+    index = 0
+
+    while index < len(text):
+        if text[index] == "%":
+            end = read_comment_end(text, index)
+            output.append(text[index:end])
+            index = end
+            continue
+
+        if text[index] == "\\":
+            wrapper = read_color_wrapper(text, index)
+            if wrapper is not None:
+                value, index = wrapper
+                output.append(uncolor_fragment(value))
+                continue
+
+            verb = read_verb_end(text, index)
+            if verb is not None:
+                end, _ = verb
+                output.append(text[index:end])
+                index = end
+                continue
+
+            command = COMMAND_RE.match(text, index)
+            if command is not None:
+                output.append(command.group(0))
+                index = command.end()
+                continue
+
+        output.append(text[index])
+        index += 1
+
+    return "".join(output)
+
+
+def uncolor_text(text: str) -> str:
+    r"""Remove wrappers in display math; leave all other Markdown untouched."""
+    math_blocks = scan_markdown(text).math_blocks
+    if not math_blocks:
+        return text
+
+    output: list[str] = []
+    index = 0
+    for span in math_blocks:
+        output.append(text[index:span.start])
+        output.append(uncolor_fragment(text[span.start:span.end]))
+        index = span.end
+    output.append(text[index:])
+    return "".join(output)

color_math/utils/__init__.py

@@ -0,0 +1,30 @@
+# utils/__init__.py
+
+from .latex_helpers import (
+    read_braced,
+    read_script_argument,
+    read_script,
+    read_color_wrapper,
+    read_color_command,
+    contains_color_wrapper,
+)
+
+from .coloring import (
+    latex_color,
+    command_color,
+)
+
+
+__all__ = [
+    # latex_helpers.py
+    "read_braced",
+    "read_script_argument",
+    "read_script",
+    "read_color_wrapper",
+    "read_color_command",
+    "contains_color_wrapper",
+
+    # coloring.py
+    "latex_color",
+    "command_color",
+]