"""HTML-specific rendering utilities.

This module contains all HTML generation code:
- CSS class computation from message type and modifiers
- Message emoji generation
- HTML escaping and markdown rendering
- Collapsible content rendering
- Tool-specific HTML formatters
- Message content HTML rendering
- Template environment management

The functions here transform format-neutral TemplateMessage data into
HTML-specific output.
"""

import functools
import html
import json
import logging
import os
import re
import shutil
from pathlib import Path
from typing import Any, Optional, TYPE_CHECKING
from urllib.parse import urlsplit

from jinja2 import Environment, FileSystemLoader, select_autoescape

from wenmode import HTMLRenderer, Wenmode
from wenmode.renderers.html import (
    normalize_url_for_scheme_check as _normalize_url_for_scheme_check,
)
from wenmode.renderers.html import render_code as _default_render_code

from .renderer_code import highlight_code_with_pygments, truncate_highlighted_preview
from ..json_depth import exceeds_depth
from ..models import (
    AssistantTextMessage,
    AwaySummaryMessage,
    HookAttachmentMessage,
    BashInputMessage,
    BashOutputMessage,
    CommandOutputMessage,
    CompactedSummaryMessage,
    HookSummaryMessage,
    MessageContent,
    SessionHeaderMessage,
    SlashCommandMessage,
    SystemMessage,
    TaskNotificationMessage,
    TeammateMessage,
    ThinkingMessage,
    ToolResultMessage,
    ToolUseMessage,
    UnknownMessage,
    UserMemoryMessage,
    UserSlashCommandMessage,
    UserSteeringMessage,
    UserTextMessage,
    WorkflowAgentMessage,
    WorkflowPhaseMessage,
)
from ..render_cache import markdown_cache
from ..renderer_timings import timing_stat

if TYPE_CHECKING:
    from ..renderer import TemplateMessage


# -- Auto-memory detection ----------------------------------------------------
# Claude's auto-memory (https://code.claude.com/docs/en/memory#auto-memory)
# has no dedicated tool: it surfaces in transcripts as ordinary Read/Write/Edit
# calls whose file_path points into the per-project memory directory. We anchor
# on the full default path ``~/.claude/projects/<slug>/memory/`` rather than a
# bare ``memory/`` substring so a project's own ``memory/`` folder can't yield
# false positives (issue #192).
#
# The regex is forward-slash anchored; ``_normalize_sep`` folds Windows
# backslash paths to forward slashes first so detection works on windows-latest
# (transcript file_paths may use the native separator).
#
# Limitation (acceptable for v1; see work/parse-memory-spike.md): a custom
# ``autoMemoryDirectory`` setting relocates memory outside this path and won't
# be detected — that needs config plumbing, so it stays deferred.
_MEMORY_PATH_RE = re.compile(r"/\.claude/projects/[^/]+/memory/")


# File tools whose paths we flag as memory interactions. Bash references a
# memory path inside its command string (not a typed field) and is rare, so
# it's intentionally out of scope for v1 (issue #192).
_MEMORY_TOOL_NAMES = frozenset({"Read", "Write", "Edit"})


def _normalize_sep(file_path: str) -> str:
    """Fold Windows backslash separators to forward slashes for matching."""
    return file_path.replace("\\", "/")


def is_memory_path(file_path: Optional[str]) -> bool:
    """True if ``file_path`` lives inside an auto-memory directory."""
    return (
        bool(file_path)
        and _MEMORY_PATH_RE.search(_normalize_sep(file_path)) is not None
    )


# -- Markdown-file detection --------------------------------------------------
# A file whose own format is Markdown. Read/Write of such a file renders the
# body as Markdown rather than Pygments-highlighted source (issue #232).
# Auto-memory files (always ``.md``) are a subset: ``is_memory_path`` ⊂
# ``is_markdown_path``. The memory specialization that survives is the 🧠 title
# (and memory's relative-link resolution + always-Markdown body); for any other
# ``.md`` the generalization keys on this predicate instead.
_MARKDOWN_EXTS = (".md", ".markdown")


def is_markdown_path(file_path: Optional[str]) -> bool:
    """True if ``file_path`` names a Markdown file (``.md`` / ``.markdown``)."""
    return bool(file_path) and _normalize_sep(file_path).lower().endswith(
        _MARKDOWN_EXTS
    )


def is_memory_tool(tool_name: Optional[str], file_path: Optional[str]) -> bool:
    """True if a tool call/result is an auto-memory interaction.

    A file tool (Read/Write/Edit) acting on a path inside a ``memory/``
    directory. Used to tag both the ``tool_use`` call and its paired
    ``tool_result`` with the ``memory`` CSS modifier.
    """
    return tool_name in _MEMORY_TOOL_NAMES and is_memory_path(file_path)


def memory_short_path(file_path: str) -> str:
    """Return the path relative to the ``memory/`` directory.

    e.g. ``…/memory/MEMORY.md`` -> ``MEMORY.md``,
    ``…/memory/sub/topic.md`` -> ``sub/topic.md``. Separators are normalized to
    ``/`` (so Windows paths render consistently). Falls back to the normalized
    path if the marker isn't found (shouldn't happen for memory paths).
    """
    normalized = _normalize_sep(file_path)
    parts = _MEMORY_PATH_RE.split(normalized, maxsplit=1)
    return parts[-1] if len(parts) > 1 else normalized


# Relative href/src in rendered memory-file markdown (e.g. a MEMORY.md link to
# a sibling topic file: ``feedback_x.md``). Absolute URLs (scheme://), in-page
# anchors (#…), root-absolute (/…) and protocol-relative (//…) are left alone.
_RELATIVE_LINK_ATTR_RE = re.compile(r'((?:href|src)=")([^"#/][^":]*)(")', re.IGNORECASE)


def resolve_memory_body_links(html: str, file_path: str) -> str:
    """Anchor relative links in rendered memory-file markdown to the memory dir.

    Memory files live at ``…/<slug>/memory/`` and link to sibling memory files
    with bare relative paths. When that markdown is rendered into a transcript
    page that lives one level up (``…/<slug>/``), the browser resolves those
    links against the page's directory and drops the ``memory/`` segment (#192).
    Rewriting them to ``file://`` URLs under the memory file's own directory
    fixes the target and is independent of where the page is written.
    """
    dir_path = _normalize_sep(file_path).rsplit("/", 1)[0]
    # file:// URLs need a leading slash before the path. POSIX paths already
    # start with "/" (-> file:///home/...); a Windows drive-letter path
    # (C:/Users/...) does not, so add one (-> file:///C:/Users/...).
    if not dir_path.startswith("/"):
        dir_path = "/" + dir_path
    base = "file://" + dir_path

    def _rewrite(m: "re.Match[str]") -> str:
        target = m.group(2)
        # Skip anything with a scheme (foo://…, mailto:) — the ``[^":]`` guard
        # in the pattern already excludes ``:`` so only truly relative targets
        # reach here, but keep the wrapper resilient.
        return f"{m.group(1)}{base}/{target}{m.group(3)}"

    return _RELATIVE_LINK_ATTR_RE.sub(_rewrite, html)


# -- CSS Class Registry -------------------------------------------------------
# Maps content types to their CSS classes.
# The first class is typically the base type (user, assistant, system, etc.),
# followed by any static modifiers.

CSS_CLASS_REGISTRY: dict[type[MessageContent], list[str]] = {
    # System message types
    SystemMessage: ["system"],  # level added dynamically
    HookSummaryMessage: ["system", "system-hook"],
    HookAttachmentMessage: ["system", "system-hook-attachment"],
    AwaySummaryMessage: ["system", "system-away-summary"],
    # User message types
    UserTextMessage: ["user"],
    UserSteeringMessage: ["user", "steering"],
    SlashCommandMessage: ["user", "slash-command"],
    UserSlashCommandMessage: ["user", "slash-command"],
    UserMemoryMessage: ["user"],
    CompactedSummaryMessage: ["user", "compacted"],
    CommandOutputMessage: ["user", "command-output"],
    TeammateMessage: ["user", "teammate"],
    # Async-agent <task-notification> entry (issue #90). Carries the
    # `user` class so the runtime "User" filter toggle keeps it visible
    # — without it, the rendered <div> would only carry the
    # `task-notification` modifier, which matches no filter toolbar
    # type and would be permanently flagged `filtered-hidden`. The
    # modifier itself uses hyphens to match the rest of this registry
    # (`system-hook`, `slash-command`, `command-output`, `bash-input`,
    # `bash-output`, `task-notification-card`/`-backlink` in CSS) — the
    # underlying message-type identifier `"task_notification"` (set on
    # `TaskNotificationMessage.message_type`) keeps its underscore.
    TaskNotificationMessage: ["user", "task-notification"],
    # Assistant message types
    AssistantTextMessage: ["assistant"],
    # Tool message types
    ToolUseMessage: ["tool_use"],
    ToolResultMessage: ["tool_result"],  # error added dynamically
    # Other message types
    ThinkingMessage: ["thinking"],
    SessionHeaderMessage: ["session_header"],
    BashInputMessage: ["bash-input"],
    BashOutputMessage: ["bash-output"],
    UnknownMessage: ["unknown"],
    # Dynamic-workflow synthetic nodes (#174 PR3): phase/agent cards spliced
    # under a Workflow tool_use. The `tool_use` class keeps them visible under
    # the runtime "Tool Use" filter toggle (the splice lives inside a tool_use
    # subtree); the `workflow_phase`/`workflow_agent` modifiers drive styling
    # and the timeline's dedicated detection branch.
    WorkflowPhaseMessage: ["tool_use", "workflow_phase"],
    WorkflowAgentMessage: ["tool_use", "workflow_agent"],
}


def _get_css_classes_from_content(content: MessageContent) -> list[str]:
    """Get CSS classes from content type using the registry.

    Walks the MRO to find a matching registry entry, then adds
    any dynamic modifiers based on content attributes.
    """
    for cls in type(content).__mro__:
        if not issubclass(cls, MessageContent):
            continue
        if classes := CSS_CLASS_REGISTRY.get(cls):
            result = list(classes)
            # Dynamic modifiers based on content attributes
            if isinstance(content, SystemMessage):
                result.append(f"system-{content.level}")
            elif isinstance(content, ToolResultMessage):
                if content.is_error:
                    result.append("error")
                # Memory interaction (recalled memory): tag the result so the
                # filter/timeline hide or isolate the whole call+result pair.
                if is_memory_tool(content.tool_name, content.file_path):
                    result.append("memory")
            elif isinstance(content, ToolUseMessage):
                # Memory interaction (writing/recalling memory): a Read/Write/
                # Edit on a path inside the project's memory/ directory (#192).
                file_path = getattr(content.input, "file_path", None)
                if is_memory_tool(content.tool_name, file_path):
                    result.append("memory")
            return result
    return []


# -- CSS and Message Display --------------------------------------------------


def css_class_from_message(msg: "TemplateMessage") -> str:
    """Generate CSS class string from message type and modifiers.

    Uses CSS_CLASS_REGISTRY to derive classes from content type,
    with fallback to msg.type for messages without registered content.

    The order of classes follows the original pattern:
    1. Message type (from content type or msg.type fallback)
    2. Content-derived modifiers (e.g., slash-command, compacted, error)
    3. Cross-cutting modifier flags: steering, sidechain

    Args:
        msg: The template message to generate CSS classes for

    Returns:
        Space-separated CSS class string (e.g., "user slash-command sidechain")
    """
    # Get base classes and content-derived modifiers from content type
    if msg.content:
        parts = _get_css_classes_from_content(msg.content)
        if not parts:
            parts = [msg.type]  # Fallback if content type not in registry
    else:
        parts = [msg.type]

    # Cross-cutting modifier flags (not derivable from content type alone)
    if msg.is_sidechain:
        parts.append("sidechain")

    # Agent-nesting depth (#213 visual layer). A message at depth d (d >= 1)
    # carries:
    #   - ``agent-depth-{d}``       exact depth (data / tests / timeline)
    #   - ``agent-ring-{1..5}``     5-colour cycle bucket for the group line
    #   - ``agent-deep``            d >= 6 → compress the indent step
    # All three are derivable from d, but CSS can't compute them, so we emit
    # the classes. Depth 0 (trunk / non-agent) adds nothing.
    if msg.agent_depth >= 1:
        d = msg.agent_depth
        parts.append(f"agent-depth-{d}")
        parts.append(f"agent-ring-{((d - 1) % 5) + 1}")
        if d >= 6:
            parts.append("agent-deep")

    return " ".join(parts)


def is_session_header(msg: "TemplateMessage") -> bool:
    """Check if message is a session header.

    Args:
        msg: The template message to check

    Returns:
        True if message content is a SessionHeaderMessage
    """
    return isinstance(msg.content, SessionHeaderMessage)


def get_message_emoji(msg: "TemplateMessage") -> str:
    """Return appropriate emoji for message type.

    Args:
        msg: The template message to get emoji for

    Returns:
        Emoji string for the message type, or empty string if no emoji
    """
    msg_type = msg.type

    if msg_type == "session_header":
        return "📋"
    elif msg_type == "user":
        # Command output has no emoji (neutral - can be from built-in or user command)
        if isinstance(msg.content, CommandOutputMessage):
            return ""
        return "🤷"
    elif msg_type == "bash-input":
        return "💻"
    elif msg_type == "assistant":
        if msg.is_sidechain:
            return "🔗"
        return "🤖"
    elif msg_type == "system":
        # Recap entries (away_summary) carry the same `system` message_type
        # as generic system info but are content, not noise. Give them a
        # distinct memo glyph so they read at-a-glance in scrolling lists,
        # and drop the matching label from the body chrome (one icon, one
        # title — see format_away_summary_content).
        if isinstance(msg.content, AwaySummaryMessage):
            return "📝"
        # Hook entries (both the typed attachment from #128 and the
        # legacy stop_hook_summary system entry) get a hook glyph at
        # the title level so the body summary doesn't have to repeat
        # "🪝 Hook output" as a redundant subheader.
        if isinstance(msg.content, (HookAttachmentMessage, HookSummaryMessage)):
            return "🪝"
        return "⚙️"
    elif msg_type == "tool_use":
        return "🛠️"
    elif msg_type == "tool_result":
        if isinstance(msg.content, ToolResultMessage) and msg.content.is_error:
            return "🚨"
        return "🧰"
    elif msg_type == "thinking":
        return "💭"
    elif msg_type == "image":
        return "🖼️"
    elif msg_type == "workflow_phase":
        return "🧩"
    elif msg_type == "workflow_agent":
        return "🤖"
    return ""


# -- HTML Utilities -----------------------------------------------------------


def escape_html(text: str) -> str:
    """Escape HTML special characters in text.

    Also normalizes line endings (CRLF -> LF) to prevent double spacing in <pre> blocks.
    """
    # Normalize CRLF to LF to prevent double line breaks in HTML
    normalized = text.replace("\r\n", "\n").replace("\r", "\n")
    return html.escape(normalized)


def _render_code_with_pygments(renderer: Any, node: Any, context: Any) -> str:
    """wenmode ``code`` handler: Pygments when the fence names a language.

    Falls back to wenmode's own ``<pre><code>`` rendering when there is
    no language hint, so plain fences stay as they were.
    """
    if not node.lang:
        return str(_default_render_code(renderer, node, context))
    from pygments import highlight
    from pygments.lexer import Lexer
    from pygments.lexers import get_lexer_by_name, TextLexer
    from pygments.formatter import Formatter
    from pygments.formatters import HtmlFormatter
    from pygments.util import ClassNotFound

    lang = node.lang.split()[0]
    lexer: Lexer = TextLexer()
    try:
        lexer = get_lexer_by_name(lang, stripall=False)
    except ClassNotFound:
        pass  # Already have default
    formatter: Formatter = HtmlFormatter(
        linenos=False,  # No line numbers in markdown code blocks
        cssclass="highlight",
        wrapcode=True,
    )
    with timing_stat("_pygments_timings"):
        return str(highlight(node.value, lexer, formatter))


def _render_html_escaped(renderer: Any, node: Any, context: Any) -> str:
    """wenmode ``html`` handler: raw HTML is shown as text, never live.

    Transcript content is untrusted from every source (#245 XSS), so
    every raw-HTML node is entity-escaped. A block-level one (marked by
    ``markdown_plugins.BlockHtmlMarker``) is wrapped in a paragraph so
    it lays out like the text it now is.
    """
    if node.data and node.data.get("block"):
        return "<p>" + str(renderer.escape_html(node.value.strip())) + "</p>\n"
    return str(renderer.escape_html(node.value))


# Schemes a link or image in a transcript must never carry: mistune's
# list, plus OS protocol handlers that a click would hand to the desktop
# (``search-ms:`` and ``ms-appinstaller:`` have real abuse history) and
# the browser-internal ones. Anything else — ``cci:`` editor links,
# ``vercel.json:20`` file references, relative paths — stays a working
# link: transcripts are full of targets no allowlist would anticipate,
# and none of those can execute script.
_HARMFUL_URL_SCHEMES = frozenset(
    {
        "javascript",
        "vbscript",
        "file",
        "data",
        "feed",
        "jar",
        "livescript",
        "mocha",
        "ms-its",
        "mk",
        "res",
        "view-source",
        # beyond mistune's list
        "search-ms",
        "ms-appinstaller",
        "ms-msdt",
        "intent",
        "blob",
        "filesystem",
        "about",
    }
)
_GOOD_DATA_PREFIXES = (
    "data:image/gif;",
    "data:image/png;",
    "data:image/jpeg;",
    "data:image/webp;",
)


class _TranscriptHTMLRenderer(HTMLRenderer):
    """wenmode's HTML renderer with a denylist URL policy.

    wenmode's default allows only ``http``, ``https``, ``irc``, ``ircs``,
    ``mailto`` and ``tel``; every other scheme loses its ``href``. The
    XSS contract (#245) only needs the dangerous schemes gone, so this
    keeps mistune's denylist (``file:`` included) and lets the rest
    through unchanged. Attribute sanitising and raw-HTML escaping are
    wenmode's defaults, untouched.
    """

    def sanitize_url(self, value: str) -> Optional[str]:
        try:
            normalized = _normalize_url_for_scheme_check(value)
            scheme = urlsplit(normalized).scheme.lower()
        except ValueError:
            return None
        if scheme in _HARMFUL_URL_SCHEMES and not normalized.lower().startswith(
            _GOOD_DATA_PREFIXES
        ):
            return None
        return value


class _TranscriptHtmlHandlers:
    """wenmode plugin installing the transcript HTML handlers above."""

    def setup(self, wen: Wenmode, /) -> None:
        wen.register_renderer_handlers(
            {
                "html": {
                    "code": _render_code_with_pygments,
                    "html": _render_html_escaped,
                }
            }
        )


def _build_transcript_markdown(document: bool = False) -> Wenmode:
    """The wenmode pipeline both content renderers use.

    ``escape=True`` renders raw HTML embedded in the source text
    (``<script>``, ``<img onerror=…>``, bare ``<b>``, …) as literal
    entity-escaped text rather than injected as live DOM, and the
    renderer's URL policy drops ``javascript:``/``data:`` link targets. Transcript content is **not** trusted from any source: the
    assistant routinely echoes arbitrary user/file/web input verbatim —
    e.g. "write an E2E test that types ``<script>alert(1)</script>`` into
    the field" — so rendering it unescaped lets that payload execute when
    the transcript HTML is opened. The Markdown output path neutralises
    raw HTML the same way (see ``markdown/renderer.py::_protect_html_tags``).
    Escaping does not affect Markdown formatting, Pygments output, SHA
    links or code fences — only raw HTML in the body.

    The SHA → commit-URL linkifier (issue #156) reads the per-render cwd
    from a ContextVar, so the cached singleton keeps working unchanged
    across transcripts from different repos.

    ``document`` adds wenmode's ``frontmatter`` plugin, for a whole body
    (a message, a Markdown file, a plan) that may open with YAML front
    matter; see ``render_markdown_document``.
    """
    from ..markdown_plugins import transcript_plugins, transcript_rules
    from ..git_remote import resolve_sha_for_current_render

    plugins: list[Any] = [*transcript_plugins(), _TranscriptHtmlHandlers()]
    if document:
        from wenmode.plugins import frontmatter

        from ..frontmatter import load_frontmatter

        plugins.append(frontmatter.configure(load=load_frontmatter))
    return Wenmode(
        transcript_rules(resolve_sha_for_current_render),
        # escape: untrusted content (XSS, #245). soft_break: a newline in
        # prose is a line break (checklists in assistant messages carry no
        # two-trailing-spaces markup) — mistune's hard_wrap.
        renderer=_TranscriptHTMLRenderer(escape=True, soft_break="br"),
        plugins=plugins,
    )


@functools.lru_cache(maxsize=1)
def _get_markdown_renderer() -> Wenmode:
    """Cached renderer for assistant/tool/web-authored content.

    Assistant prose, Task/WebSearch/WebFetch results, plans, system
    messages, teammate bodies. See ``_build_transcript_markdown`` for
    the escaping contract.
    """
    return _build_transcript_markdown()


@functools.lru_cache(maxsize=1)
def _get_document_markdown_renderer() -> Wenmode:
    """Cached renderer for whole bodies that open with YAML front matter.

    The transcript pipeline plus wenmode's ``frontmatter`` plugin. Only
    ``render_markdown_document`` uses it: inline renders, previews and the
    Markdown inside a params-table value never parse front matter.
    """
    return _build_transcript_markdown(document=True)


def _frontmatter_html(value: Any) -> str:
    """HTML for loaded front matter: a params table, or a YAML code block."""
    from ..frontmatter import RawFrontmatter, yaml_fence
    from .tool_formatters import render_params_table

    if isinstance(value, RawFrontmatter):
        body = render_markdown(yaml_fence(value.source))
    else:
        body = render_params_table(value)
    return f"<div class='frontmatter'>{body}</div>"


def render_markdown_document(text: str, user: bool = False) -> str:
    """Render a whole Markdown body, showing YAML front matter as data.

    A body that opens with front matter (``frontmatter.is_frontmatter_start``)
    is parsed by the document renderer, whose ``frontmatter`` plugin takes
    the block out of the body; it renders as a params table above the rest
    (a YAML code block when it is not a mapping). Any other body renders
    exactly as ``render_markdown`` (``render_user_markdown`` when ``user``).
    ``user`` does not apply to the front-matter path: the document renderer
    is the same escaping pipeline as both, so one memo entry serves either.
    """
    from ..frontmatter import is_frontmatter_start
    from ..git_remote import current_render_repo_cwd

    if not is_frontmatter_start(text):
        return _render_markdown_memoized(text, escaping_user_renderer=user)

    memo_key = ("document", current_render_repo_cwd(), text)
    cached = markdown_cache.get(memo_key)
    if cached is not None:
        return cached
    with timing_stat("_markdown_timings"):
        renderer = _get_document_markdown_renderer()
        root = renderer.parse(text)
        body = renderer.render_node(root)
        data = root.data or {}
        if "frontmatter" in data:
            body = _frontmatter_html(data["frontmatter"]) + body
    markdown_cache.put(memo_key, body)
    return body


def _render_markdown_memoized(text: str, escaping_user_renderer: bool) -> str:
    """Render ``text`` through one of the two wenmode singletons, memoized.

    Markdown output is a pure function of the text *and* the active render
    repo cwd: the SHA-linkifier plugin resolves commit hashes against
    ``git_remote._render_repo_cwd``, so the same ``5baac35`` links to
    different repositories in different transcripts. The cwd is therefore
    part of the key — without it a long-lived host (``serve``, the TUI)
    would serve one project's commit links inside another's page.

    ``escaping_user_renderer`` selects between the two renderer singletons
    (they differ only in call site convention today, but they are distinct
    objects and must not share cache entries).
    """
    from ..git_remote import current_render_repo_cwd

    memo_key = (escaping_user_renderer, current_render_repo_cwd(), text)
    cached = markdown_cache.get(memo_key)
    if cached is not None:
        return cached

    # Track markdown rendering time if enabled
    with timing_stat("_markdown_timings"):
        renderer = (
            _get_user_markdown_renderer()
            if escaping_user_renderer
            else _get_markdown_renderer()
        )
        rendered = renderer.render(text)
    markdown_cache.put(memo_key, rendered)
    return rendered


def render_markdown(text: str) -> str:
    """Convert markdown text to HTML using wenmode with Pygments syntax highlighting."""
    return _render_markdown_memoized(text, escaping_user_renderer=False)


_INLINE_PARA_BOUNDARY_RE = re.compile(r"</p>\s*<p>")


def render_markdown_inline(text: str) -> str:
    """Render markdown collapsed to inline-safe HTML.

    Question/option text from AskUserQuestion is LLM-authored, so it carries
    real Markdown (inline code, emphasis, links). Callers embed the result
    inside inline wrappers (``<strong>``, ``<li>``), so this unwraps the
    enclosing ``<p>`` and folds any paragraph boundaries into ``<br>`` —
    a multi-paragraph free-form reply must not emit block ``<p>`` inside an
    inline element.

    Uses the ``escape=True`` renderer so raw HTML in the text (``<script>``,
    ``<option>``, …) is escaped to literal characters rather than injected —
    these short fields were previously HTML-escaped, so keep that contract.
    """
    rendered = _render_markdown_memoized(text, escaping_user_renderer=True).strip()
    if rendered.startswith("<p>") and rendered.endswith("</p>"):
        inner = rendered[len("<p>") : -len("</p>")]
        return _INLINE_PARA_BOUNDARY_RE.sub("<br>", inner)
    return rendered


@functools.lru_cache(maxsize=1)
def _get_user_markdown_renderer() -> Wenmode:
    """Cached renderer for user-authored text.

    Same pipeline as ``_get_markdown_renderer`` — the shared renderer was
    historically ``escape=False`` for assistant/tool output that emitted
    pre-formed HTML; both now escape (#245 XSS) because transcript
    content is untrusted from every source. This one is retained as a
    distinct object for the user-content call sites
    (``render_user_markdown``); the memo keys on which singleton rendered.
    """
    return _build_transcript_markdown()


def render_user_markdown(text: str) -> str:
    """Render user-authored Markdown with HTML escaping enabled."""
    return _render_markdown_memoized(text, escaping_user_renderer=True)


# HTML tags that are self-closing / void per the HTML spec — these do
# not appear on the open-tag stack in `is_well_formed_html`.
_VOID_HTML_TAGS = frozenset(
    {
        "area",
        "base",
        "br",
        "col",
        "embed",
        "hr",
        "img",
        "input",
        "link",
        "meta",
        "param",
        "source",
        "track",
        "wbr",
    }
)


def is_well_formed_html(fragment: str) -> bool:
    """Check that an HTML fragment has balanced open/close tags.

    Uses stdlib `html.parser.HTMLParser` to walk the fragment, tracking
    an open-tag stack. Returns False if:

    - A close tag appears with no matching open tag on the stack.
    - Tags remain open at end of input.
    - The parser raises (malformed start tag, bad attribute quoting, etc.).

    Void elements (``<br>``, ``<img>``, …) don't push to the stack, and
    XHTML-style self-closing syntax (``<br />``, ``<hr />``) is treated
    as equivalent — wenmode emits XHTML self-closing for voids so the
    check must accept both.
    """
    from html.parser import HTMLParser

    stack: list[str] = []
    errors: list[str] = []

    class _Checker(HTMLParser):
        def handle_starttag(
            self, tag: str, attrs: list[tuple[str, Optional[str]]]
        ) -> None:
            if tag not in _VOID_HTML_TAGS:
                stack.append(tag)

        def handle_endtag(self, tag: str) -> None:
            if not stack:
                errors.append(f"unexpected </{tag}>")
                return
            if stack[-1] != tag:
                errors.append(
                    f"mismatched close: expected </{stack[-1]}>, got </{tag}>"
                )
                return
            stack.pop()

        def handle_startendtag(
            self, tag: str, attrs: list[tuple[str, Optional[str]]]
        ) -> None:
            # ``<tag />`` — XHTML self-closing. The element opens and
            # closes in one token, so neither push nor pop is needed.
            # Don't fall through to the default implementation, which
            # calls `handle_starttag` + `handle_endtag` and would make
            # a non-void `<br />` look unbalanced.
            return

        def error(
            self, message: str
        ) -> None:  # pragma: no cover — stdlib subclasses don't call this in 3.10+
            errors.append(message)

    parser = _Checker(convert_charrefs=True)
    try:
        parser.feed(fragment)
        parser.close()
    except Exception as exc:  # parser itself raised — treat as ill-formed
        errors.append(str(exc))

    return not errors and not stack


# -- Collapsible Content Rendering --------------------------------------------


def render_collapsible_code(
    preview_html: str,
    full_html: str,
    line_count: int,
    is_markdown: bool = False,
) -> str:
    """Render a collapsible code/content block with preview.

    Creates a details element with a line count badge and preview content
    that expands to show the full content.

    Args:
        preview_html: HTML content to show in the collapsed summary
        full_html: HTML content to show when expanded
        line_count: Number of lines (shown in the badge)
        is_markdown: If True, adds 'markdown' class to preview and full content divs

    Returns:
        HTML string with collapsible details element
    """
    markdown_class = " markdown" if is_markdown else ""
    return f"""<details class='collapsible-code'>
        <summary>
            <span class='line-count'>{line_count} lines</span>
            <div class='preview-content{markdown_class}'>{preview_html}</div>
        </summary>
        <div class='code-full{markdown_class}'>{full_html}</div>
    </details>"""


def _preview_source(text: str) -> str:
    """The text a collapsed preview is cut from: the body after any front
    matter (a preview never parses front matter, so cutting it would leave
    the setext-heading misreading), or the front matter as a YAML block
    when nothing follows it."""
    from ..frontmatter import split_frontmatter, yaml_fence

    split = split_frontmatter(text)
    if split is None:
        return text
    source, body = split
    return body if body.strip() else yaml_fence(source)


def _markdown_collapsible(
    raw_content: str,
    css_class: str,
    user: bool,
    line_threshold: int,
    preview_line_count: int,
) -> str:
    """Shared body for the collapsible-markdown helpers; ``user`` picks the
    user-content renderer. Both escape raw HTML (``escape=True``):
    transcript content is untrusted regardless of source — assistant/tool
    output routinely echoes arbitrary user/file/web input — so raw tags are
    neutralised rather than injected as live DOM (XSS). The full body is a
    document (front matter shows as data); the preview is not."""
    render_fn = render_user_markdown if user else render_markdown
    rendered_html = render_markdown_document(raw_content, user=user)

    lines = raw_content.splitlines()
    if len(lines) <= line_threshold:
        # Short content, show inline
        return f'<div class="{css_class} markdown">{rendered_html}</div>'

    # Long content - make collapsible with rendered preview
    preview_lines = _preview_source(raw_content).splitlines()[:preview_line_count]
    preview_text = "\n".join(preview_lines)
    if len(lines) > preview_line_count:
        preview_text += "\n\n..."
    # Render truncated markdown (produces valid HTML with proper tag closure)
    preview_html = render_fn(preview_text)

    collapsible = render_collapsible_code(
        preview_html, rendered_html, len(lines), is_markdown=True
    )
    return f'<div class="{css_class}">{collapsible}</div>'


def render_markdown_collapsible(
    raw_content: str,
    css_class: str,
    line_threshold: int = 20,
    preview_line_count: int = 5,
) -> str:
    """Render markdown content, making it collapsible if it exceeds a line threshold.

    For long content, creates a collapsible details element with a preview.
    For short content, renders inline with the specified CSS class.

    Renders via the shared HTML-escaping renderer (``render_markdown``),
    so raw HTML in assistant/tool/web-authored content (Task results,
    WebSearch/WebFetch, plans) is neutralised — transcript content is
    untrusted (the assistant echoes arbitrary input). Markdown formatting,
    Pygments highlighting and code fences are unaffected.

    Args:
        raw_content: The raw text content to render as markdown
        css_class: CSS class for the wrapper div (e.g., "task-prompt", "task-result")
        line_threshold: Number of lines above which content becomes collapsible (default 20)
        preview_line_count: Number of lines to show in the preview (default 5)

    Returns:
        HTML string with rendered markdown, optionally wrapped in collapsible details
    """
    return _markdown_collapsible(
        raw_content, css_class, False, line_threshold, preview_line_count
    )


def render_markdown_preview(
    text: str, css_class: str, inline_lines: int, inline_chars: int
) -> str:
    """The minimal theme's short preview of a long Markdown block.

    Text of at most ``inline_lines`` lines and ``inline_chars`` characters
    renders inline (as ``render_markdown_collapsible`` would); anything
    longer always becomes the shared collapsible preview — its first two
    non-blank lines in the ``<summary>`` (clipped to two lines by the
    theme's CSS; no "..." line, the fade and the "+N lines" label say there
    is more) and the full text in the body. Used for a sub-agent's prompt
    on its spawn row (P7c) and for its answer on the merge row (P8), so a
    long agent report reads as two lines in "Main only" like every other
    long block.
    """
    lines = text.splitlines()
    if len(lines) <= inline_lines and len(text) <= inline_chars:
        return render_markdown_collapsible(text, css_class)
    preview_lines = _preview_source(text).splitlines()
    preview = "\n".join([line for line in preview_lines if line.strip()][:2])
    collapsible = render_collapsible_code(
        render_markdown(preview),
        render_markdown_document(text),
        len(lines),
        is_markdown=True,
    )
    return f'<div class="{css_class}">{collapsible}</div>'


# The minimal theme's agent answers (sync results, async notifications): a
# reply this short reads in full on the merge row; anything longer previews.
ANSWER_INLINE_LINES = 3
ANSWER_INLINE_CHARS = 320


def render_user_markdown_collapsible(
    raw_content: str,
    css_class: str,
    line_threshold: int = 20,
    preview_line_count: int = 5,
) -> str:
    """Like ``render_markdown_collapsible`` but with HTML escaping enabled.

    For content that is not trusted to emit pre-formed HTML — e.g. auto-memory
    files (#192), whose markdown may contain literal ``<script>``/HTML that must
    render as escaped text, not live DOM, when the transcript is opened.
    """
    return _markdown_collapsible(
        raw_content, css_class, True, line_threshold, preview_line_count
    )


def render_file_content_collapsible(
    code_content: str,
    file_path: str,
    css_class: str,
    linenostart: int = 1,
    line_threshold: int = 12,
    preview_line_count: int = 5,
    suffix_html: str = "",
) -> str:
    """Render file content with syntax highlighting, collapsible if long.

    Highlights code using Pygments and wraps in a collapsible details element
    if the content exceeds the line threshold. Uses preview truncation from
    already-highlighted HTML to avoid double Pygments calls.

    Args:
        code_content: The raw code content to highlight
        file_path: File path for syntax detection (extension-based)
        css_class: CSS class for the wrapper div (e.g., 'write-tool-content')
        linenostart: Starting line number for Pygments (default 1)
        line_threshold: Number of lines above which content becomes collapsible
        preview_line_count: Number of lines to show in the preview
        suffix_html: Optional HTML to append after the code (inside wrapper div)

    Returns:
        HTML string with highlighted code, collapsible if >line_threshold lines
    """
    # Highlight code with Pygments (single call)
    highlighted_html = highlight_code_with_pygments(
        code_content, file_path, linenostart=linenostart
    )

    html_parts = [f"<div class='{css_class}'>"]

    lines = code_content.splitlines()
    if len(lines) > line_threshold:
        # Extract preview from already-highlighted HTML (avoids double highlighting)
        preview_html = truncate_highlighted_preview(
            highlighted_html, preview_line_count
        )
        html_parts.append(
            render_collapsible_code(preview_html, highlighted_html, len(lines))
        )
    else:
        # Show directly without collapsible
        html_parts.append(highlighted_html)

    if suffix_html:
        html_parts.append(suffix_html)

    html_parts.append("</div>")
    return "".join(html_parts)


def render_async_result_body(text: str, css_class: str, preview: bool = False) -> str:
    """Render an async-result body, JSON-aware (issue #174 D4).

    A JSON-shaped payload — ``lstrip()`` starts with ``{"`` per cboos's
    heuristic, and so possibly truncated — is pretty-printed when it parses
    and Pygments-highlighted as JSON (collapsible when long); everything
    else (plain markdown answers from non-workflow async agents) falls back
    to the existing markdown rendering, so this is a safe no-op for them.

    (Spilling to the full untruncated ``tool-results/<taskId>.txt`` is a
    separate enhancement — it needs the taskId plumbed to this layer — and
    is deferred to a follow-up.)

    ``preview`` (minimal theme): a Markdown answer longer than a few lines
    is the short two-line preview (``render_markdown_preview``) rather than
    the 20-line threshold's five-line one.
    """
    stripped = (text or "").lstrip()
    if stripped.startswith('{"'):
        rendered = text
        try:
            parsed = json.loads(text)
            # Too deep to pretty-print: every level adds indentation, so
            # the output grows quadratically. Highlight the text as-is.
            if not exceeds_depth(parsed):
                rendered = json.dumps(parsed, indent=2, ensure_ascii=False)
        except (ValueError, RecursionError):
            pass  # truncated / variant payload — highlight the raw text as-is
        return render_file_content_collapsible(
            rendered,
            "result.json",
            css_class,
            line_threshold=10,
            preview_line_count=6,
        )
    if preview:
        return render_markdown_preview(
            text, css_class, ANSWER_INLINE_LINES, ANSWER_INLINE_CHARS
        )
    return render_markdown_collapsible(text, css_class)


# -- Template Environment -----------------------------------------------------


def starts_with_emoji(text: str) -> bool:
    """Check if a string starts with an emoji character.

    Checks common emoji Unicode ranges:
    - Misc Technical: U+2300 - U+23FF (⏰ ⏳ ⏱️ ⏲️ ⏸ ⏹ ⏺ ⏏ etc.)
    - Misc Symbols: U+2600 - U+26FF
    - Dingbats: U+2700 - U+27BF
    - Misc Symbols and Pictographs: U+1F300 - U+1F5FF
    - Emoticons: U+1F600 - U+1F64F
    - Transport and Map Symbols: U+1F680 - U+1F6FF
    - Supplemental Symbols: U+1F900 - U+1F9FF
    - Geometric Shapes Extended, coloured circles/squares: U+1F7E0 - U+1F7FF (🟢 🟦)
    - Symbols and Pictographs Extended-A: U+1FA70 - U+1FAFF (🪝 🩺 🪙)
    - White medium star: U+2B50 (⭐)

    Used by the transcript template to suppress the default ``🛠️``
    (tool_use) or ``🧰`` (tool_result) emoji prefix when a tool title
    already starts with its own icon — e.g. a plugin result titled
    ``📨 Mails …``. The error ``🚨`` is never suppressed. No built-in
    result title starts with an emoji.
    Misses here cause a redundant wrench to appear in front of an
    otherwise-iconified title (e.g. ``🛠️ ⏰ ScheduleWakeup ...``);
    Misc Technical (U+2300-U+23FF) is included because the alarm
    clock and other time/control glyphs live there but are real
    emoji in practice.
    """
    if not text:
        return False

    first_char = text[0]
    code_point = ord(first_char)

    return (
        0x2300 <= code_point <= 0x23FF  # Misc Technical (⏰ ⏳ ⏱️ ...)
        or 0x2600 <= code_point <= 0x26FF  # Misc Symbols
        or 0x2700 <= code_point <= 0x27BF  # Dingbats
        or 0x1F300 <= code_point <= 0x1F5FF  # Misc Symbols and Pictographs
        or 0x1F600 <= code_point <= 0x1F64F  # Emoticons
        or 0x1F680 <= code_point <= 0x1F6FF  # Transport and Map Symbols
        or 0x1F900 <= code_point <= 0x1F9FF  # Supplemental Symbols
        or 0x1F7E0 <= code_point <= 0x1F7FF  # Coloured circles/squares (🟢 🟦)
        or 0x1FA70 <= code_point <= 0x1FAFF  # Pictographs Extended-A (🪝 🩺)
        or code_point == 0x2B50  # White medium star (⭐)
    )


@functools.lru_cache(maxsize=1)
def get_template_environment() -> Environment:
    """Get cached Jinja2 template environment for HTML rendering.

    Creates a Jinja2 environment configured with:
    - Template loading from the templates directory
    - HTML auto-escaping
    - Custom template filters/functions (starts_with_emoji)

    Returns:
        Configured Jinja2 Environment (cached after first call)
    """
    templates_dir = Path(__file__).parent / "templates"
    env = Environment(
        loader=FileSystemLoader(templates_dir),
        autoescape=select_autoescape(["html", "xml"]),
    )
    # Add custom filters/functions
    # Cast to Any to bypass Jinja2's overly strict globals type
    globals_dict: Any = env.globals
    globals_dict["starts_with_emoji"] = starts_with_emoji
    # Minimal-theme gutter/meta helpers — called only from the template's
    # `{% if minimal %}` branches, so classic output never touches them.
    from . import minimal_icons, minimal_theme

    globals_dict["mn_role_label"] = minimal_theme.role_label
    globals_dict["mn_role_icon"] = minimal_icons.role_icon_markup
    globals_dict["mn_icon"] = minimal_icons.icon_markup
    globals_dict["mn_icon_sprite"] = minimal_icons.icon_sprite
    globals_dict["mn_is_generic_title"] = minimal_theme.is_generic_title
    globals_dict["mn_compact_tokens"] = minimal_theme.compact_token_usage
    globals_dict["mn_gutter_time"] = minimal_theme.gutter_time
    globals_dict["mn_page_meta"] = minimal_theme.page_meta
    globals_dict["mn_call_title"] = minimal_theme.call_title
    globals_dict["mn_session_header"] = minimal_theme.session_header
    globals_dict["mn_lane_attrs"] = minimal_theme.lane_attrs
    globals_dict["mn_cross_links"] = minimal_theme.cross_links
    # The project index and archive search pages (minimal only).
    globals_dict["mn_when"] = minimal_theme.when
    globals_dict["mn_project_when"] = minimal_theme.project_when
    globals_dict["mn_index_summary_meta"] = minimal_theme.index_summary_meta
    globals_dict["mn_project_meta"] = minimal_theme.project_meta
    globals_dict["mn_project_tooltip"] = minimal_theme.project_tooltip
    globals_dict["mn_index_sessions"] = minimal_theme.index_sessions
    return env


# Sub-directory (relative to a transcript HTML file) where vendored
# front-end assets are written. All transcript pages for a project live
# flat in one output directory, so this relative path is constant across
# session / combined / paginated pages.
VENDOR_ASSETS_DIRNAME = "assets"

# The vendored vis-timeline build, resolved from the package's
# ``assets/vendor`` directory (see that dir's ``PROVENANCE.md``). Vendored
# rather than CDN-loaded so generated HTML stays fully offline and leaks
# no request to a third party (issue #278). The version is part of each
# file name: an upgrade writes new files instead of comparing old ones,
# and a page rendered by an older release keeps pointing at the build it
# was rendered against.
VIS_TIMELINE_VERSION = "8.5.1"
VIS_TIMELINE_JS = f"vis-timeline-graph2d-{VIS_TIMELINE_VERSION}.min.js"
VIS_TIMELINE_CSS = f"vis-timeline-graph2d-{VIS_TIMELINE_VERSION}.min.css"
_VENDOR_ASSET_FILES = (VIS_TIMELINE_JS, VIS_TIMELINE_CSS)


def _vendor_source_dir() -> Path:
    return Path(__file__).parent / "assets" / "vendor"


def ensure_vendor_assets(output_dir: Path) -> bool:
    """Copy the vendored front-end assets into ``output_dir/assets``.

    Called by the HTML renderer for every page it renders into a real
    output directory, so it is cheap when there is nothing to do: a file
    already present at the source's size is left alone (the versioned
    name means same name + same size is the same build). Writes go through
    a pid-named temp file and ``os.replace``, because render-pool workers
    rendering one project's pages all call this at once, and a plain copy
    could let one worker's page load another's half-written bundle.

    Returns False instead of raising when the directory can't be written:
    the page still renders, and its timeline reports the missing library
    when opened. String-only renders (no output dir) never call this.
    """
    src_dir = _vendor_source_dir()
    dest_dir = output_dir / VENDOR_ASSETS_DIRNAME
    try:
        dest_dir.mkdir(parents=True, exist_ok=True)
        for name in _VENDOR_ASSET_FILES:
            src = src_dir / name
            dest = dest_dir / name
            if dest.is_file() and dest.stat().st_size == src.stat().st_size:
                continue
            tmp = dest_dir / f".{name}.{os.getpid()}.tmp"
            try:
                shutil.copyfile(src, tmp)
                os.replace(tmp, dest)
            finally:
                tmp.unlink(missing_ok=True)
    except OSError as exc:
        logging.getLogger(__name__).warning(
            "Could not write timeline assets to %s: %s", dest_dir, exc
        )
        return False
    return True