induscode 0.1.0__py3-none-any.whl

induscode/transcript_export/sgr.py

@@ -0,0 +1,566 @@
+"""SGR painter — a table-driven ANSI Select-Graphic-Rendition state machine
+that converts a terminal byte stream into a sequence of styled HTML spans.
+
+Port of TS ``src/transcript-export/sgr.ts`` (verbatim logic).
+
+Terminal programs encode color and emphasis with CSI sequences of the form
+``ESC [ p1 ; p2 ; … m`` (the trailing ``m`` is the SGR final byte). The
+parameters are small integers whose meaning is fixed by ECMA-48 / ISO 6429:
+``0`` resets, ``1``/``3``/``4`` switch on weight/italic/underline, ``30``–``37``
+and ``90``–``97`` set the foreground from the sixteen-color palette,
+``40``–``47`` and ``100``–``107`` set the background, and the two extended
+introducers ``38``/``48`` pull a 256-index or a 24-bit triple out of the
+following parameters.
+
+Rather than a long ``switch``, the semantics live in a *table*: each handled
+code maps to an :data:`~induscode.transcript_export.contract.SgrMutation` —
+the partial :class:`~induscode.transcript_export.contract.SgrState` that code
+imposes — and the painter folds the matched mutation over the running state.
+Extending the machine is adding a row, never editing control flow. The two
+extended introducers are the only parametric cases and are handled by a small
+reader that consumes their trailing parameters.
+
+The pipeline is three stages:
+
+1. :func:`tokenize_sgr` splits the raw stream into an alternation of text
+   runs and SGR parameter lists (:data:`SgrToken` values).
+2. :func:`fold_sgr` folds an SGR parameter list into the running
+   :class:`SgrState` using the :data:`SGR_CODE_TABLE` dispatch table.
+3. :func:`paint_sgr` drives the two over the whole stream, wrapping each text
+   run in a ``<span>`` whose class list and inline color style reflect the
+   state in force.
+
+The :class:`SgrState` / :data:`SgrToken` / :data:`SgrMutation` vocabulary is
+the transcript-export contract's; the SGR code meanings are the published
+standard's.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import replace
+from types import MappingProxyType
+from typing import Any, Final, Mapping, cast
+
+from .contract import (
+    SGR_INITIAL_STATE,
+    SgrCommandToken,
+    SgrMutation,
+    SgrState,
+    SgrTextToken,
+    SgrToken,
+)
+
+__all__ = [
+    "SGR_CODE_TABLE",
+    "fold_sgr",
+    "paint_sgr",
+    "tokenize_sgr",
+]
+
+
+# ---------------------------------------------------------------------------
+# Palette
+# ---------------------------------------------------------------------------
+
+#: The eight base ANSI colors, in palette order (indices 0–7). The bright
+#: variants (8–15) are the same hues lifted toward white. Values are concrete
+#: CSS colors so the emitted spans are self-contained — the page need not ship
+#: an ANSI palette to render them.
+_BASE_PALETTE: Final[tuple[str, ...]] = (
+    "#1c1c1c",  # black
+    "#c14a4a",  # red
+    "#5aa45a",  # green
+    "#b5963c",  # yellow
+    "#4a7fc1",  # blue
+    "#a05aa0",  # magenta
+    "#42a0a0",  # cyan
+    "#c9c9c9",  # white
+)
+
+#: The eight bright ANSI colors, in palette order (indices 8–15) — the base
+#: hues pushed brighter, used by the ``90``–``97`` / ``100``–``107`` parameter
+#: ranges and by the high half of the 256-color cube's first sixteen entries.
+_BRIGHT_PALETTE: Final[tuple[str, ...]] = (
+    "#5c5c5c",  # bright black (gray)
+    "#e06666",  # bright red
+    "#86d186",  # bright green
+    "#e6cc66",  # bright yellow
+    "#6fa8e6",  # bright blue
+    "#c986c9",  # bright magenta
+    "#6fcccc",  # bright cyan
+    "#f5f5f5",  # bright white
+)
+
+#: The full sixteen-entry indexed palette: base 0–7 then bright 8–15.
+_PALETTE_16: Final[tuple[str, ...]] = _BASE_PALETTE + _BRIGHT_PALETTE
+
+
+def _clamp_byte(value: int) -> int:
+    """Clamp an integer into the 0–255 byte range."""
+    if value < 0:
+        return 0
+    if value > 255:
+        return 255
+    return int(value)
+
+
+def _hex_pair(value: int) -> str:
+    """Render a 0–255 channel as a two-digit lowercase hex pair."""
+    return format(_clamp_byte(value), "02x")
+
+
+def _rgb_hex(r: int, g: int, b: int) -> str:
+    """Compose an ``#rrggbb`` CSS color from three 0–255 channels."""
+    return f"#{_hex_pair(r)}{_hex_pair(g)}{_hex_pair(b)}"
+
+
+def _color_256(index: int) -> str:
+    """Resolve a 256-color palette index to a CSS color, per the standard
+    layout:
+
+    - ``0–15`` the sixteen indexed colors above;
+    - ``16–231`` a 6×6×6 RGB cube, each axis stepping through the six levels
+      ``{0, 95, 135, 175, 215, 255}``;
+    - ``232–255`` a 24-step neutral gray ramp from near-black to near-white.
+    """
+    i = _clamp_byte(index)
+    if i < 16:
+        return _PALETTE_16[i]
+    if i < 232:
+        c = i - 16
+        levels = (0, 95, 135, 175, 215, 255)
+        r = levels[(c // 36) % 6]
+        g = levels[(c // 6) % 6]
+        b = levels[c % 6]
+        return _rgb_hex(r, g, b)
+    step = 8 + (i - 232) * 10
+    return _rgb_hex(step, step, step)
+
+
+# ---------------------------------------------------------------------------
+# Code table
+# ---------------------------------------------------------------------------
+
+
+def _build_code_table() -> dict[int, SgrMutation]:
+    """Build the fixed-meaning portion of the SGR dispatch table. The two
+    color-range runs (``30``–``37`` foreground, ``90``–``97`` bright
+    foreground, and the background counterparts) are generated from the
+    palette so the table stays a single source rather than a wall of literal
+    rows.
+    """
+    table: dict[int, SgrMutation] = {}
+
+    # Reset: return to exactly the neutral starting style. Stored as a full
+    # copy of the initial state so the fold replaces every field in one step.
+    table[0] = {
+        "fg": SGR_INITIAL_STATE.fg,
+        "bg": SGR_INITIAL_STATE.bg,
+        "bold": SGR_INITIAL_STATE.bold,
+        "dim": SGR_INITIAL_STATE.dim,
+        "italic": SGR_INITIAL_STATE.italic,
+        "underline": SGR_INITIAL_STATE.underline,
+        "blink": SGR_INITIAL_STATE.blink,
+        "inverse": SGR_INITIAL_STATE.inverse,
+        "hidden": SGR_INITIAL_STATE.hidden,
+        "strike": SGR_INITIAL_STATE.strike,
+    }
+
+    # Attribute on-switches.
+    table[1] = {"bold": True}
+    table[2] = {"dim": True}
+    table[3] = {"italic": True}
+    table[4] = {"underline": True}
+    table[5] = {"blink": True}
+    table[6] = {"blink": True}  # rapid blink — folded to the same hook
+    table[7] = {"inverse": True}
+    table[8] = {"hidden": True}
+    table[9] = {"strike": True}
+
+    # Attribute off-switches (the standard's single-attribute resets).
+    table[21] = {"bold": False}  # doubly-underline in some terminals; treated as bold-off
+    table[22] = {"bold": False, "dim": False}
+    table[23] = {"italic": False}
+    table[24] = {"underline": False}
+    table[25] = {"blink": False}
+    table[27] = {"inverse": False}
+    table[28] = {"hidden": False}
+    table[29] = {"strike": False}
+
+    # Foreground: 30–37 base, 90–97 bright; default at 39.
+    for n in range(8):
+        table[30 + n] = {"fg": _BASE_PALETTE[n]}
+        table[90 + n] = {"fg": _BRIGHT_PALETTE[n]}
+    table[39] = {"fg": None}
+
+    # Background: 40–47 base, 100–107 bright; default at 49.
+    for n in range(8):
+        table[40 + n] = {"bg": _BASE_PALETTE[n]}
+        table[100 + n] = {"bg": _BRIGHT_PALETTE[n]}
+    table[49] = {"bg": None}
+
+    return table
+
+
+#: The read-only public view of the SGR dispatch table — each fixed-meaning
+#: SGR code mapped to the :data:`SgrMutation` it imposes. Exported so callers
+#: can introspect the handled code space (the extended ``38``/``48``
+#: introducers are not present here; they are parametric and resolved by the
+#: painter).
+SGR_CODE_TABLE: Final[Mapping[int, SgrMutation]] = MappingProxyType(_build_code_table())
+
+
+# ---------------------------------------------------------------------------
+# Extended color introducers (38 / 48)
+# ---------------------------------------------------------------------------
+
+
+def _read_extended_color(
+    params: tuple[int, ...], introducer_index: int
+) -> tuple[str | None, int]:
+    """Read an extended-color value starting at the parameter after a ``38``
+    or ``48`` introducer. Returns the resolved CSS color (or ``None`` for an
+    unsupported mode) together with the number of parameters consumed
+    *including the introducer*, so the fold can advance its cursor correctly.
+
+    The two recognized sub-forms are the standard ones:
+
+    - ``…;5;n`` a single index into the 256-color palette;
+    - ``…;2;r;g;b`` a direct 24-bit triple.
+
+    A malformed or unsupported selector consumes only the introducer and
+    yields no color change, so a bad sequence degrades to a no-op rather than
+    corrupting the scan.
+    """
+
+    def at(index: int) -> int | None:
+        return params[index] if 0 <= index < len(params) else None
+
+    selector = at(introducer_index + 1)
+    if selector == 5:
+        index = at(introducer_index + 2)
+        if index is None:
+            return None, 1
+        return _color_256(index), 3
+    if selector == 2:
+        r = at(introducer_index + 2)
+        g = at(introducer_index + 3)
+        b = at(introducer_index + 4)
+        if r is None or g is None or b is None:
+            return None, 1
+        return _rgb_hex(r, g, b), 5
+    return None, 1
+
+
+# ---------------------------------------------------------------------------
+# Fold
+# ---------------------------------------------------------------------------
+
+
+def fold_sgr(state: SgrState, params: tuple[int, ...]) -> SgrState:
+    """Fold one SGR parameter list into a running :class:`SgrState`,
+    returning the next state.
+
+    Walks the parameters left to right. A fixed-meaning code is resolved
+    through the code table and its mutation merged over the state. The two
+    extended introducers ``38`` (foreground) and ``48`` (background) are
+    handled inline: the reader consumes their trailing ``5;n`` or ``2;r;g;b``
+    parameters and the resolved color is written to the matching channel. An
+    empty list is the bare ``ESC[m`` form and is treated as a reset, matching
+    terminal behavior.
+
+    Pure: the input state is never mutated; a fresh value is returned.
+
+    :param state: the style in force before this sequence
+    :param params: the numeric parameter list of one SGR sequence
+    """
+    if len(params) == 0:
+        return replace(SGR_INITIAL_STATE)
+
+    next_state = state
+    i = 0
+    while i < len(params):
+        code = params[i]
+
+        if code in (38, 48):
+            color, consumed = _read_extended_color(params, i)
+            if color is not None:
+                next_state = (
+                    replace(next_state, fg=color)
+                    if code == 38
+                    else replace(next_state, bg=color)
+                )
+            i += consumed  # skip the introducer's trailing parameters
+            continue
+
+        mutation = SGR_CODE_TABLE.get(code)
+        if mutation is not None:
+            next_state = replace(next_state, **cast("dict[str, Any]", dict(mutation)))
+        i += 1
+    return next_state
+
+
+# ---------------------------------------------------------------------------
+# Tokenizer
+# ---------------------------------------------------------------------------
+
+#: The escape byte that opens a control sequence.
+_ESC: Final[str] = "\x1b"
+
+
+def tokenize_sgr(input_text: str) -> list[SgrToken]:
+    """Split a raw terminal stream into an ordered list of :data:`SgrToken`
+    values.
+
+    Scans for CSI sequences of the form ``ESC [ … m``. Each such sequence
+    becomes an ``sgr`` token carrying its parsed numeric parameters (an empty
+    selector yields an empty list, the bare-reset form). The runs of ordinary
+    characters between sequences become ``text`` tokens. Non-SGR control
+    sequences — any CSI whose final byte is not ``m``, plus bare escapes — are
+    dropped: they carry cursor and screen commands that have no place in
+    flowed HTML, so swallowing them keeps the output clean while preserving
+    every printable character.
+
+    Empty ``text`` runs are never emitted, so the token stream is dense.
+
+    :param input_text: the raw ANSI/terminal byte stream
+    """
+    tokens: list[SgrToken] = []
+    text_start = 0
+    i = 0
+    n = len(input_text)
+
+    def flush_text(end: int) -> None:
+        if end > text_start:
+            tokens.append(SgrTextToken(text=input_text[text_start:end]))
+
+    while i < n:
+        if input_text[i] != _ESC:
+            i += 1
+            continue
+
+        # A control sequence begins; flush any pending text before it.
+        flush_text(i)
+
+        if i + 1 >= n or input_text[i + 1] != "[":
+            # A bare escape or a non-CSI escape (e.g. ESC followed by a single
+            # byte). Skip the escape and its immediate selector byte if present.
+            i += 1 if i + 1 >= n else 2
+            text_start = i
+            continue
+
+        # Consume the parameter/intermediate bytes up to the final byte.
+        j = i + 2
+        while j < n and not _is_final_byte(input_text[j]):
+            j += 1
+        final_byte = input_text[j] if j < n else None
+        body = input_text[i + 2 : j]
+
+        if final_byte == "m":
+            tokens.append(SgrCommandToken(params=_parse_params(body)))
+        # Any other final byte (or an unterminated sequence) is a non-SGR
+        # command and is dropped along with its parameters.
+
+        i = j + 1
+        text_start = i
+
+    flush_text(n)
+    return tokens
+
+
+def _is_final_byte(ch: str) -> bool:
+    """A CSI sequence's final byte is in the range ``@``–``~`` (0x40–0x7e);
+    the bytes before it are parameters (``0``–``?``) and intermediates. This
+    predicate marks the end of the sequence's body during the scan.
+    """
+    code = ord(ch)
+    return 0x40 <= code <= 0x7E
+
+
+#: Numeric prefix of one CSI parameter field (the TS port used ``parseInt``,
+#: which reads an optional sign and the leading digits, ignoring the rest).
+_PARAM_PREFIX = re.compile(r"\s*([+-]?\d+)")
+
+
+def _parse_params(body: str) -> tuple[int, ...]:
+    """Parse a CSI parameter body (the bytes between ``ESC[`` and the final
+    ``m``) into a numeric list. Parameters are separated by ``;``; an empty
+    field is the standard's "default" parameter, which for SGR means ``0``,
+    so it is read as zero. Stray non-numeric characters in a field are
+    ignored, leaving the field's numeric prefix.
+    """
+    if len(body) == 0:
+        return ()
+
+    def field_value(field: str) -> int:
+        m = _PARAM_PREFIX.match(field)
+        return int(m.group(1)) if m is not None else 0
+
+    return tuple(field_value(field) for field in body.split(";"))
+
+
+# ---------------------------------------------------------------------------
+# Rendering
+# ---------------------------------------------------------------------------
+
+#: Map of each HTML-significant character to its text-safe entity.
+_HTML_ESCAPES: Final[Mapping[str, str]] = MappingProxyType(
+    {
+        "&": "&amp;",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+        "'": "&#39;",
+    }
+)
+
+
+def _escape_html(text: str) -> str:
+    """Escape a text run for safe inclusion as HTML element content/attribute
+    text."""
+    out: list[str] = []
+    for ch in text:
+        out.append(_HTML_ESCAPES.get(ch, ch))
+    return "".join(out)
+
+
+#: The CSS class prefix for every emitted attribute class, keeping the output
+#: namespaced.
+_CLASS_PREFIX: Final[str] = "sgr"
+
+#: The boolean attributes of an :class:`SgrState` that map to a
+#: presentational CSS class, paired with the class suffix each contributes.
+#: ``inverse`` and ``hidden`` are handled separately (they reshape the colors
+#: / visibility) and so are not in this list.
+_FLAG_CLASSES: Final[tuple[tuple[str, str], ...]] = (
+    ("bold", "bold"),
+    ("dim", "dim"),
+    ("italic", "italic"),
+    ("underline", "underline"),
+    ("blink", "blink"),
+    ("strike", "strike"),
+)
+
+
+def _classes_for(state: SgrState) -> list[str]:
+    """Collect the presentational CSS classes a state contributes, in
+    declaration order. ``inverse`` adds a marker class as well, so a
+    stylesheet can react to the swap if it wants to, even though the swap is
+    also applied to the colors.
+    """
+    classes: list[str] = []
+    for key, suffix in _FLAG_CLASSES:
+        if getattr(state, key):
+            classes.append(f"{_CLASS_PREFIX}-{suffix}")
+    if state.inverse:
+        classes.append(f"{_CLASS_PREFIX}-inverse")
+    if state.hidden:
+        classes.append(f"{_CLASS_PREFIX}-hidden")
+    return classes
+
+
+def _styles_for(state: SgrState) -> list[str]:
+    """Build the inline ``style`` declarations for a state's colors, resolving
+    the ``inverse`` swap and the ``hidden`` conceal at render time:
+
+    - under ``inverse``, foreground and background trade places (with the
+      default ink/surface filled in so the swap is visible even when a channel
+      was the default);
+    - under ``hidden``, the foreground is forced to match the background so
+      the text is concealed while still occupying its space.
+    """
+    fg = state.fg
+    bg = state.bg
+
+    if state.inverse:
+        swapped = fg
+        fg = bg if bg is not None else "var(--sgr-default-bg, #13161c)"
+        bg = swapped if swapped is not None else "var(--sgr-default-fg, #e6e8ee)"
+    if state.hidden:
+        fg = bg if bg is not None else "transparent"
+
+    decls: list[str] = []
+    if fg is not None:
+        decls.append(f"color:{fg}")
+    if bg is not None:
+        decls.append(f"background-color:{bg}")
+    return decls
+
+
+def _is_plain(state: SgrState) -> bool:
+    """True when a state carries no style at all — its text needs no wrapping
+    span."""
+    return (
+        state.fg is None
+        and state.bg is None
+        and not state.bold
+        and not state.dim
+        and not state.italic
+        and not state.underline
+        and not state.blink
+        and not state.inverse
+        and not state.hidden
+        and not state.strike
+    )
+
+
+def _render_run(text: str, state: SgrState) -> str:
+    """Wrap one escaped text run in a ``<span>`` carrying the state's classes
+    and inline color style. A run under the neutral state is emitted bare (no
+    span), so plain output stays plain HTML.
+    """
+    safe = _escape_html(text)
+    if _is_plain(state):
+        return safe
+
+    classes = _classes_for(state)
+    styles = _styles_for(state)
+
+    attrs: list[str] = []
+    if len(classes) > 0:
+        attrs.append(f'class="{" ".join(classes)}"')
+    if len(styles) > 0:
+        attrs.append(f'style="{";".join(styles)}"')
+
+    attr_text = " " + " ".join(attrs) if len(attrs) > 0 else ""
+    return f"<span{attr_text}>{safe}</span>"
+
+
+# ---------------------------------------------------------------------------
+# Public entry
+# ---------------------------------------------------------------------------
+
+
+def paint_sgr(input_text: str) -> str:
+    """Paint an ANSI/terminal byte stream into a string of styled HTML spans.
+
+    Drives the three stages end to end: tokenize the stream, fold each SGR
+    sequence into the running :class:`SgrState`, and wrap each intervening
+    text run in a span reflecting the state in force when that run was
+    emitted. Text is HTML-escaped; non-SGR control sequences are dropped; runs
+    under the neutral state are emitted without a wrapping span. The result is
+    safe to splice directly into a transcript page.
+
+    The state resets to :data:`SGR_INITIAL_STATE` only on an explicit reset
+    code (or a bare ``ESC[m``); it otherwise persists across text runs, so a
+    color set once stays in force until changed, exactly as a terminal renders
+    it.
+
+    :param input_text: the raw ANSI/terminal byte stream to convert
+    :returns: an HTML fragment of escaped text and styled ``<span>`` runs
+    """
+    if len(input_text) == 0:
+        return ""
+
+    tokens = tokenize_sgr(input_text)
+    state = replace(SGR_INITIAL_STATE)
+    out: list[str] = []
+
+    for token in tokens:
+        if token.kind == "sgr":
+            state = fold_sgr(state, token.params)
+        else:
+            out.append(_render_run(token.text, state))
+
+    return "".join(out)