induscode 0.1.0__py3-none-any.whl

induscode/transcript_export/publish.py

@@ -0,0 +1,455 @@
+"""publish_transcript — render a session transcript to a standalone,
+self-contained HTML document.
+
+Port of TS ``src/transcript-export/publish.ts``, with the two third-party
+renderers swapped for their Python counterparts: ``marked`` →
+**markdown-it-py** (CommonMark with the GFM-ish ``table`` + ``strikethrough``
+rules enabled) and ``highlight.js`` → **Pygments** (a small custom emitter
+maps Pygments token families onto the page's existing ``xhl-*`` class
+family). Everything else — the SGR painting, the widget splice, the base64
+payload, the shell fill — is the TS pipeline verbatim.
+
+The publisher takes a list of transcript entries (each carrying a framework
+message) and produces one HTML string with no external dependencies: prose is
+rendered to HTML with markdown-it-py, fenced code is syntax-highlighted with
+Pygments, terminal-styled tool output is painted to spans by
+:func:`~induscode.transcript_export.sgr.paint_sgr`, and all colors come from a
+:class:`~induscode.transcript_export.contract.ThemeBridge` over an
+:class:`~induscode.transcript_export.contract.ExportTheme`. Markdown and
+highlighting are run *here*, at publish time, so the rendered HTML is baked
+into the page payload and the page needs no client-side parser to display —
+the page ships ready to read.
+
+The two third-party libraries this layer leans on are MIT (markdown-it-py)
+and BSD-2-Clause (Pygments); their license notices are preserved verbatim in
+the emitted document (the ``MARKED_LIB`` / ``HIGHLIGHT_LIB`` shell slots) as
+the licenses require, while the libraries themselves are used, never
+reimplemented.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from collections.abc import Mapping, MutableMapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Final, Literal
+
+from markdown_it import MarkdownIt
+from pygments.lexer import Lexer
+from pygments.lexers import get_lexer_by_name, guess_lexer
+from pygments.token import Comment, Keyword
+from pygments.token import Literal as LiteralToken
+from pygments.token import Number, String, _TokenType
+from pygments.util import ClassNotFound
+
+from .contract import (
+    FALLBACK_EXPORT_THEME,
+    SHELL_SLOTS,
+    ImageContent,
+    MessagePart,
+    PublishEntry,
+    PublishOptions,
+    PublishRole,
+    TextContent,
+    ThemeBridge,
+    WidgetRender,
+    briefing_fault,
+)
+from .sgr import paint_sgr
+from .template import CLIENT_SCRIPT, PAGE_SHELL, PAGE_STYLES, SlotValues, fill
+from .theme_bridge import create_theme_bridge
+
+__all__ = [
+    "HIGHLIGHT_LICENSE",
+    "MARKDOWN_LICENSE",
+    "publish_transcript",
+]
+
+
+# ---------------------------------------------------------------------------
+# Preserved third-party license notices
+# ---------------------------------------------------------------------------
+
+#: The MIT notice for ``markdown-it-py``, embedded so the export honors the
+#: library's license. Copyright line preserved verbatim; not paraphrased.
+#: (Replaces the TS build's ``marked`` notice — the Python port renders
+#: markdown with markdown-it-py.)
+MARKDOWN_LICENSE: Final[str] = "\n".join(
+    [
+        "markdown-it-py — https://github.com/executablebooks/markdown-it-py",
+        "Copyright (c) 2020 ExecutableBookProject",
+        "Released under the MIT License.",
+    ]
+)
+
+#: The BSD-2-Clause notice for ``Pygments``, embedded so the export honors
+#: the library's license. Copyright lines preserved verbatim; not paraphrased.
+#: (Replaces the TS build's ``highlight.js`` notice — the Python port
+#: highlights code with Pygments.)
+HIGHLIGHT_LICENSE: Final[str] = "\n".join(
+    [
+        "Pygments — https://github.com/pygments/pygments",
+        "Copyright (c) 2006-2022 by the respective authors (see AUTHORS file).",
+        "All rights reserved.",
+        "Released under the BSD-2-Clause License.",
+    ]
+)
+
+
+# ---------------------------------------------------------------------------
+# Turn model (the rendered payload)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _RenderedTurn:
+    """A rendered transcript turn in the page payload. The client script
+    injects each turn's already-built HTML; the publisher does all rendering
+    here so the page stays parser-free.
+    """
+
+    # Either a styled card ("turn") or a standalone informational "note".
+    kind: Literal["turn", "note"]
+    # Attribution role, used for the card's accent.
+    role: PublishRole
+    # Heading label for the card.
+    label: str
+    # The pre-rendered inner HTML for the turn body.
+    html: str
+
+
+# ---------------------------------------------------------------------------
+# Escaping helpers
+# ---------------------------------------------------------------------------
+
+
+def _escape_html(text: str) -> str:
+    """HTML-escape the five significant characters in element/attribute
+    text."""
+    return (
+        text.replace("&", "&")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+        .replace("'", "&#39;")
+    )
+
+
+def _has_ansi(text: str) -> bool:
+    """True when a string carries an ANSI escape introducer worth painting."""
+    return "\x1b[" in text
+
+
+# ---------------------------------------------------------------------------
+# Markdown + code rendering
+# ---------------------------------------------------------------------------
+
+#: Pygments token families mapped onto the page's own ``xhl-*`` classes (the
+#: family the stylesheet declares: keyword / string / comment / number /
+#: literal). The narrower ``String`` / ``Number`` families come before their
+#: ``Literal`` parent so a string literal classes as ``xhl-string``, not
+#: ``xhl-literal``; token types outside every family are emitted as plain
+#: escaped text, exactly as the TS build left unrecognized hljs spans
+#: unstyled.
+_XHL_FAMILIES: Final[tuple[tuple[_TokenType, str], ...]] = (
+    (String, "xhl-string"),
+    (Number, "xhl-number"),
+    (Comment, "xhl-comment"),
+    (Keyword, "xhl-keyword"),
+    (LiteralToken, "xhl-literal"),
+)
+
+
+def _xhl_class_for(token_type: _TokenType) -> str | None:
+    """Resolve a Pygments token type to its ``xhl-*`` class, or ``None`` when
+    the type belongs to no styled family."""
+    for family, css_class in _XHL_FAMILIES:
+        if token_type in family:
+            return css_class
+    return None
+
+
+def _emit_xhl(lexer: Lexer, code: str) -> str:
+    """Run a Pygments lexer over a code string and emit the inner HTML of a
+    code block: each token's text escaped, tokens in a styled family wrapped
+    in a ``<span class="xhl-*">``. The Python analogue of hljs's ``.value``
+    (no wrapping ``<pre>``/``<code>``)."""
+    pieces: list[tuple[_TokenType, str]] = list(lexer.get_tokens(code))
+    # Pygments guarantees the lexed source ends with a newline, appending one
+    # when the input lacked it; trim that synthetic newline so the emitted
+    # block mirrors the input exactly.
+    if not code.endswith("\n") and pieces and pieces[-1][1].endswith("\n"):
+        last_type, last_text = pieces[-1]
+        pieces[-1] = (last_type, last_text[:-1])
+
+    out: list[str] = []
+    for token_type, value in pieces:
+        if value == "":
+            continue
+        safe = _escape_html(value)
+        css_class = _xhl_class_for(token_type)
+        out.append(f'<span class="{css_class}">{safe}</span>' if css_class else safe)
+    return "".join(out)
+
+
+def _highlight_code(code: str, language: str | None) -> str:
+    """Highlight a fenced code block to HTML using Pygments. A recognized
+    language is highlighted under that grammar; otherwise the guesser picks
+    one. Highlighting failures fall back to plain escaped code so a published
+    page never breaks on an exotic snippet.
+    """
+    try:
+        lexer: Lexer | None = None
+        if language:
+            try:
+                lexer = get_lexer_by_name(language)
+            except ClassNotFound:
+                lexer = None
+        if lexer is None:
+            try:
+                lexer = guess_lexer(code)
+            except ClassNotFound:
+                return _escape_html(code)
+        return _emit_xhl(lexer, code)
+    except Exception:
+        return _escape_html(code)
+
+
+def _render_code_rule(self: Any, tokens: Any, idx: int, options: Any, env: Any) -> str:
+    """The markdown-it render rule routing fenced (and indented) code through
+    :func:`_highlight_code` — the Python analogue of the TS ``marked``
+    renderer override. The fence's info string is trimmed and used whole as
+    the language tag, exactly as the TS build did."""
+    token = tokens[idx]
+    lang = (token.info or "").strip() or None
+    text = token.content
+    # The fence token's content carries the block's trailing newline; the TS
+    # marked token did not — trim it so the highlighted block matches.
+    if text.endswith("\n"):
+        text = text[:-1]
+    highlighted = _highlight_code(text, lang)
+    cls = f' class="language-{_escape_html(lang)}"' if lang else ""
+    return f"<pre><code{cls}>{highlighted}</code></pre>\n"
+
+
+def _configured_markdown() -> MarkdownIt:
+    """A markdown-it-py instance configured GFM-ish (CommonMark plus the
+    ``table`` and ``strikethrough`` rules — the table/strikethrough surface
+    the TS build's ``gfm: true`` provided) with fenced code routed through
+    :func:`_highlight_code`. Built once and reused across every turn in a
+    publish."""
+    md = MarkdownIt("commonmark").enable("table").enable("strikethrough")
+    md.add_render_rule("fence", _render_code_rule)
+    md.add_render_rule("code_block", _render_code_rule)
+    return md
+
+
+def _render_markdown(md: MarkdownIt, source: str) -> str:
+    """Render a markdown string to an HTML fragment synchronously."""
+    out = md.render(source)
+    return out if isinstance(out, str) else ""
+
+
+# ---------------------------------------------------------------------------
+# Content-part rendering
+# ---------------------------------------------------------------------------
+
+
+def _render_image(part: ImageContent) -> str:
+    """Render one image content part as an inline data-URI ``<img>``."""
+    src = f"data:{_escape_html(part.mimeType)};base64,{part.data}"
+    return f'<img alt="attached image" src="{src}" />'
+
+
+def _render_tool_call(name: str, arguments: Mapping[str, object]) -> str:
+    """Render a tool-call part as a labeled invocation frame."""
+    try:
+        payload = json.dumps(dict(arguments), indent=2, ensure_ascii=False, default=str)
+    except Exception:
+        payload = str(arguments)
+    return (
+        f'<div class="tool-frame"><strong>{_escape_html(name)}</strong>\n'
+        f"{_escape_html(payload)}</div>"
+    )
+
+
+def _render_tool_text(text: str) -> str:
+    """Render terminal-styled tool output: ANSI-bearing text is painted to
+    styled spans inside a ``<pre>``; plain text is escaped into the same
+    frame. The result is always a self-contained fragment safe to inject.
+    """
+    inner = paint_sgr(text) if _has_ansi(text) else _escape_html(text)
+    return f'<pre class="tool-frame">{inner}</pre>'
+
+
+def _parts_of(content: str | Sequence[MessagePart]) -> Sequence[MessagePart]:
+    """Coerce a message's content into a list of parts. A bare string becomes
+    a single text part; an existing list is returned as-is.
+    """
+    if isinstance(content, str):
+        return (TextContent(text=content),)
+    return content
+
+
+# ---------------------------------------------------------------------------
+# Turn rendering
+# ---------------------------------------------------------------------------
+
+#: Human-facing heading for each role.
+_ROLE_LABEL: Final[Mapping[PublishRole, str]] = {
+    "user": "You",
+    "assistant": "Assistant",
+    "tool": "Tool",
+    "system": "System",
+    "condense": "Summary",
+    "note": "Note",
+}
+
+
+def _render_entry(
+    entry: PublishEntry,
+    md: MarkdownIt,
+    widgets: Mapping[str, WidgetRender],
+) -> _RenderedTurn:
+    """Render one transcript entry into a :class:`_RenderedTurn`.
+
+    User/assistant prose runs through markdown; images inline as data URIs;
+    assistant tool-call parts render as invocation frames. A tool-result entry
+    first tries its pre-rendered
+    :class:`~induscode.transcript_export.contract.WidgetRender` (looked up by
+    ``toolCallId``); absent that, its text parts render through the SGR-aware
+    tool frame. System and condense entries become standalone notes.
+
+    :param entry: the transcript node to render
+    :param md: the configured markdown renderer
+    :param widgets: pre-rendered custom-tool blocks, keyed by tool-call id
+    """
+    role = entry.role
+    label = _ROLE_LABEL.get(role, role)
+
+    # A tool result may have a pre-rendered widget block keyed to its call.
+    if role == "tool" and entry.message.toolCallId is not None:
+        widget = widgets.get(entry.message.toolCallId)
+        if widget is not None:
+            return _RenderedTurn(kind="turn", role=role, label=label, html=widget.html)
+
+    fragments: list[str] = []
+    for part in _parts_of(entry.message.content):
+        match getattr(part, "type", None):
+            case "text":
+                if role == "tool":
+                    fragments.append(_render_tool_text(part.text))
+                else:
+                    fragments.append(_render_markdown(md, part.text))
+            case "image":
+                fragments.append(_render_image(part))
+            case "thinking":
+                # Internal reasoning is rendered as a muted note, not prose.
+                fragments.append(
+                    f'<div class="aside-note">{_escape_html(part.thinking)}</div>'
+                )
+            case "toolCall":
+                fragments.append(_render_tool_call(part.name, part.arguments))
+            case _:
+                pass
+
+    html = "\n".join(fragments)
+    kind: Literal["turn", "note"] = "note" if role in ("system", "condense") else "turn"
+    return _RenderedTurn(kind=kind, role=role, label=label, html=html)
+
+
+# ---------------------------------------------------------------------------
+# Payload + assembly
+# ---------------------------------------------------------------------------
+
+
+def _to_base64(text: str) -> str:
+    """Encode a UTF-8 string to base64."""
+    return base64.b64encode(text.encode("utf-8")).decode("ascii")
+
+
+#: Uppercase run the camelCase→hyphen projection rewrites.
+_UPPERCASE = re.compile(r"[A-Z]")
+
+
+def _theme_vars_block(bridge: ThemeBridge) -> str:
+    """Build the CSS custom-property block for the ``THEME_VARS`` slot from a
+    :class:`~induscode.transcript_export.contract.ThemeBridge`, mapping each
+    camelCase token to a hyphenated ``--x-*`` variable the stylesheet reads.
+    """
+    css_vars = bridge.to_css_vars()
+
+    def hyphenate(name: str) -> str:
+        return _UPPERCASE.sub(lambda m: f"-{m.group(0).lower()}", name)
+
+    return "\n".join(
+        f"  --x-{hyphenate(token)}: {value};" for token, value in css_vars.items()
+    )
+
+
+def publish_transcript(
+    entries: Sequence[PublishEntry],
+    opts: PublishOptions | None = None,
+) -> str:
+    """Render a session transcript to a standalone HTML document.
+
+    Configures the markdown + highlight pipeline, renders every entry to a
+    turn, serializes the turns into a base64 payload, resolves the theme
+    through a :class:`~induscode.transcript_export.contract.ThemeBridge`, and
+    fills the page shell. The returned string is a complete
+    ``<!doctype html>`` document with all styling, content, and the preserved
+    library notices inlined — it can be written to disk and opened directly.
+
+    :param entries: the transcript nodes to publish, in display order
+    :param opts: optional theme, title, output directory, and widget overrides
+    :returns: the rendered standalone HTML document
+    :raises BriefingFault: of kind ``"publish"`` if assembly fails
+    """
+    options = opts if opts is not None else PublishOptions()
+    try:
+        theme = options.theme if options.theme is not None else FALLBACK_EXPORT_THEME
+        bridge = create_theme_bridge(theme)
+        md = _configured_markdown()
+
+        widget_index: dict[str, WidgetRender] = {
+            w.callId: w for w in (options.widgets if options.widgets is not None else ())
+        }
+
+        turns = [_render_entry(entry, md, widget_index) for entry in entries]
+
+        title = options.title if options.title is not None else "Session Transcript"
+        payload_turns: list[MutableMapping[str, str]] = []
+        for t in turns:
+            row: dict[str, str] = {}
+            if t.kind == "note":
+                row["kind"] = "note"
+            row["role"] = t.role
+            row["label"] = t.label
+            row["html"] = t.html
+            payload_turns.append(row)
+        payload_json = json.dumps(
+            {"title": title, "turns": payload_turns},
+            ensure_ascii=False,
+            separators=(",", ":"),
+        )
+        payload = _to_base64(payload_json)
+
+        slots: SlotValues = {
+            SHELL_SLOTS["themeVars"]: _theme_vars_block(bridge),
+            SHELL_SLOTS["pageSurface"]: theme.pageSurface,
+            SHELL_SLOTS["cardSurface"]: theme.cardSurface,
+            SHELL_SLOTS["noteSurface"]: theme.noteSurface,
+            SHELL_SLOTS["styles"]: PAGE_STYLES,
+            SHELL_SLOTS["script"]: CLIENT_SCRIPT,
+            SHELL_SLOTS["payload"]: payload,
+            SHELL_SLOTS["markedLib"]: MARKDOWN_LICENSE,
+            SHELL_SLOTS["highlightLib"]: HIGHLIGHT_LICENSE,
+        }
+
+        return fill(PAGE_SHELL, slots)
+    except Exception as cause:
+        raise briefing_fault(
+            "publish", "Failed to render the HTML transcript.", cause
+        ) from cause