publish Hy3-preview

.gitignore

@@ -0,0 +1,40 @@
+debug/
+logs/
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+.build/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv*
+
+.idea/
+.DS_Store
+
+# Coverage reports
+.coverage
+coverage.xml
+htmlcov/
+
+*.db
+*.log
+*.http
+
+.env
+
+dist/
+.ruff_cache/
+.pytest_cache/
+
+# MkDocs
+site/
+
+.claude-trace
+.vscode/
+.cursor/
+.specify/
+test.py

README.md

@@ -1,13 +1,23 @@
 ---
-title: Hy3 preview
-emoji: 🌍
-colorFrom: green
-colorTo: pink
+title: Hy3-preview
+emoji: ⚡
+colorFrom: yellow
+colorTo: purple
 sdk: gradio
-sdk_version: 6.13.0
-python_version: '3.12'
+sdk_version: 6.12.0
 app_file: app.py
-pinned: true
+pinned: false
+short_description: Hy3-preview multi-turn streaming chat with function calling
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Hy3 Preview · Chat Demo
+
+
+### Features
+
+- Multi-turn chat with automatic context management
+- Token-by-token streaming output
+- Sidebar controls: think level, system prompt, temperature, max tokens, top-p, repetition penalty
+- Function calling: paste JSON definitions, see structured tool calls, submit results back
+- HTML code-block preview rendered in a sandboxed iframe
+- Light & dark themes

app.py

@@ -0,0 +1,438 @@
+import base64
+import json
+import re
+from pathlib import Path
+
+import gradio as gr
+
+from chat import (
+    HY_CHAT_INITIAL_HTML,
+    api_chat,
+    init_state,
+    new_chat,
+    send_message,
+    submit_tool_result,
+)
+from i18n import LANG, t
+from tools import validate_functions_json
+from styles import CSS
+
+_STATIC_DIR = Path(__file__).parent / "static"
+_VENDOR_DIR = _STATIC_DIR / "vendor"
+
+_FN_PLACEHOLDER = json.dumps([{
+    "type": "function",
+    "function": {
+        "name": "get_weather",
+        "description": "Get weather info for a city",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "location": {"type": "string", "description": "City name"}
+            },
+            "required": ["location"]
+        }
+    }
+}], indent=2, ensure_ascii=False)
+
+_EXTRACT_NAMES_PROMPT = """You are a text information extraction expert with exceptional abilities in information filtering and structured processing. Your core task is to accurately capture key information from the raw text provided by the user and output the result according to the required format, ensuring informational purity and logical consistency.
+
+Initial settings:
+1. All extracted information must strictly come from the text provided by the user.
+2. If the user's request requires extracting uncertainty-related words such as "possible" or "speculative," you must extract them as requested. Otherwise, you must not output uncertainty-related words such as "possible" or "speculative."
+3. You must strictly follow the output format below and must not include any content outside the required format. The output format is: "Extracted content: xxx". Here, "xxx" is a placeholder.
+
+Please help me extract all personal names from the text in order. Note that you do not need to remove duplicates.
+
+Text:
+In a warm and harmonious extended family, four elders—father, mother, grandfather, and grandmother—have always quietly watched over the family, supporting the whole household with love and tolerance. Meanwhile, six younger family members—Emily Carter, Olivia Brooks, Ethan Miller, Sophie Taylor, Grace Wilson, and Daniel Harris—are each growing along their own paths in life. The family supports one another and keeps each other company, making ordinary days feel warm and fulfilling. Father is hardworking and steady, carrying the family's responsibilities with strength. Mother is gentle and attentive, taking care of every detail of daily life. Grandfather is experienced and often tells the children stories from the past. Grandmother is kind and loving, warming everyone who returns home with hot meals. Emily Carter is sensible and motivated, setting a good example for her younger siblings. Olivia Brooks is lively and cheerful, always bringing laughter to the home. Ethan Miller is dependable and practical, taking every task seriously without being careless. Sophie Taylor is gentle and considerate, skilled at caring for the people around her. Grace Wilson loves life and is attentive to the beauty around her. Daniel Harris is energetic and full of expectations for the future. These ten family members each have their own traits and strengths, yet they share the same care and affection for one another. Together, they share joy, ease worries, pass through spring, summer, autumn, and winter, and move through the years side by side. Through family love, they gather the strongest support, making home the safest and warmest harbor, and making ordinary life full of happiness and light because of each other's companionship."""
+
+_CHONGQING_TRIP_PROMPT = """You are an experienced local tour guide in Chongqing. Based on the attraction information and the users' situation, you need to generate a travel summary arranged by travel date. You must not output anything else. The travel summary format is as follows:
+
+Date/Location/Ticket
+MM-dd/Travel location/Ticket price
+MM-dd/Travel location/Ticket price
+......
+
+For the Travel location field, choose exactly one from the following six options: Hongya Cave, Chaotianmen, Jiefangbei, Qiansimen, Shapingba, Jiangbeizui.
+
+Opening hours:
+Hongya Cave: 9:00–11:00
+Chaotianmen: 9:00–11:00
+Jiefangbei: 15:00–17:00
+Qiansimen: 11:00–13:00
+Shapingba: 12:00–14:00
+Jiangbeizui: 16:00–18:00
+
+Ticket prices:
+Hongya Cave: CNY 20 per person
+Chaotianmen: CNY 60 per person
+Jiefangbei: CNY 30 per person
+Qiansimen: CNY 50 per person
+Shapingba: CNY 60 per person
+Jiangbeizui: CNY 50 per person
+
+Alex: My friend Ben and I came to Chongqing on March 15 for a trip. For every attraction we visit, we must stay from opening time until closing time. We brought a total of CNY 300. On the first day, we visited two attractions.
+
+Ben: Although we had a great time on the first day, after the day's trip ended, I realized that I had lost CNY 200. So we did not plan to visit any attractions on the second day.
+
+Alex: Losing the money was really stressful for us. However, after 12:00 on the second day, our parents sent us another CNY 200, so we went to visit one attraction that afternoon.
+
+Ben: We were too tired from the first two days, so on the final day we visited only one attraction. None of the attractions we visited were repeated."""
+
+_RATIONAL_VARIETY_PROMPT = r"""Let \(K\) be an algebraically closed field and \(X\) the hypersurface in \(\mathbf{P}_{K}^{3}\) defined by the homogeneous equation     \[     x^{2} w-y^{2} z=0     \]     where \((x, y, z, w)\) are homogeneous coordinates on \(\mathbf{P}_{K}^{3}\). Prove that \(X\) is a rational variety, i.e., its function field is \(K\left(t_{1}, t_{2}\right)\), where \(t_{1}, t_{2}\) are algebraically independent over \(K\)."""
+
+_FISH_PUZZLE_PROMPT = """Three houses stand side by side, numbered 1–3 from left to right. Each house has:
+
+A different color: red, green, blue
+A resident of a different nationality: British, French, Japanese
+A different pet: dog, cat, fish
+
+Clues:
+The British resident lives in the red house.
+The French resident owns the dog.
+The green house is immediately to the left of the red house.
+The Japanese resident lives in House 1.
+The cat is kept in the blue house.
+
+Question:
+Who owns the fish? 🐟"""
+
+# The 4 showcase prompts are shared across languages — the full text is
+# kept verbatim (that's what we send to the model) while the frontend
+# truncates the button label for display; see ``createOverlay`` in
+# static/app.js for the label-truncation side.
+_SHOWCASE_PROMPTS = [
+    _EXTRACT_NAMES_PROMPT,
+    _CHONGQING_TRIP_PROMPT,
+    _RATIONAL_VARIETY_PROMPT,
+    _FISH_PUZZLE_PROMPT,
+]
+
+_EXAMPLES_BY_LANG = {
+    "en": _SHOWCASE_PROMPTS,
+    "zh": _SHOWCASE_PROMPTS,
+}
+EXAMPLES = _EXAMPLES_BY_LANG.get(LANG, _EXAMPLES_BY_LANG["en"])
+
+# ─── Vendored asset inlining ──────────────────────────────────────────
+# Every vendored library is INLINED into the ``js`` / ``css`` parameters
+# that ``gr.Blocks`` already serves on the page, so the app runs fully
+# self-contained without any external CDN or extra static-route plumbing.
+#
+# Order matters for JS: marked / katex / auto-render / hljs must be
+# defined as globals BEFORE static/chat.js runs; static/chat.js must
+# define ``window.HY_CHAT`` BEFORE static/app.js's ``bootstrap()``
+# polls for ``#hy-chat``. Concatenation order below preserves this.
+def _read(p: Path) -> str:
+    return p.read_text(encoding="utf-8")
+
+
+_VENDOR_JS = "\n;\n".join([
+    _read(_VENDOR_DIR / "marked" / "marked.min.js"),
+    _read(_VENDOR_DIR / "katex" / "katex.min.js"),
+    _read(_VENDOR_DIR / "katex" / "auto-render.min.js"),
+    _read(_VENDOR_DIR / "highlight" / "highlight.min.js"),
+])
+
+_CHAT_JS = _read(_STATIC_DIR / "chat.js")
+_APP_JS = _read(_STATIC_DIR / "app.js")
+
+# KaTeX's stylesheet references font files via ``url(fonts/KaTeX_*.woff2)``
+# — a path that only resolves if the CSS itself is served from the same
+# directory as the fonts. Since we inline the CSS into a <style> tag
+# the relative URLs would resolve against the document root and 404. We
+# rewrite each font URL into a ``data:`` URI so the CSS is fully
+# self-contained, and strip the ``.woff`` / ``.ttf`` fallback entries
+# from each ``@font-face`` src list so the browser doesn't fire requests
+# we know will 404 (we only ship the ``.woff2`` files).
+_KATEX_CSS = _read(_VENDOR_DIR / "katex" / "katex.min.css")
+_FONTS_DIR = _VENDOR_DIR / "katex" / "fonts"
+
+# Drop ``,url(fonts/X.woff) format("woff")`` and the ttf equivalent. The
+# minified CSS may use single OR double quotes around the format string;
+# match both. Run BEFORE inlining woff2 so the regex still sees the
+# ``url(fonts/...)`` token shape.
+_KATEX_CSS = re.sub(
+    r",\s*url\(fonts/[^)]+\.(?:woff|ttf)\)\s*format\(['\"](?:woff|truetype)['\"]\)",
+    "",
+    _KATEX_CSS,
+)
+
+# Inline every woff2 as a data URI.
+for _font_path in sorted(_FONTS_DIR.glob("*.woff2")):
+    _b64 = base64.b64encode(_font_path.read_bytes()).decode("ascii")
+    _data_uri = f"data:font/woff2;base64,{_b64}"
+    _KATEX_CSS = _KATEX_CSS.replace(
+        f"url(fonts/{_font_path.name})", f"url({_data_uri})"
+    )
+
+_HLJS_CSS = _read(_VENDOR_DIR / "highlight" / "github.min.css")
+_HLJS_DARK_CSS = _read(_VENDOR_DIR / "highlight" / "github-dark.min.css")
+
+# Gradio passes this string as the body of an init function it calls on
+# load. We bundle vendored libs first so they install their globals
+# (``window.marked``, ``window.katex``, ``window.renderMathInElement``,
+# ``window.hljs``), then chat.js (defines ``window.HY_CHAT`` and starts
+# the delta-channel observer), then app.js (the rest of the UX glue).
+_JS_INIT = f"""
+window.HY_EXAMPLES = {json.dumps(EXAMPLES)};
+window.HY_I18N = {json.dumps({
+    "examples_heading": t("examples_heading"),
+    "model_busy": t("warn.model_busy"),
+    "thinking": t("display.thinking"),
+    "thinking_done": t("display.thinking_done"),
+    "code_copy": t("display.code_copy"),
+    "code_copied": t("display.code_copied"),
+})};
+{_VENDOR_JS}
+;
+{_CHAT_JS}
+;
+{_APP_JS}
+"""
+
+# Append vendored CSS to whatever ``styles.py`` produced. The KaTeX
+# theme has higher specificity for math elements than our other rules,
+# so loading order doesn't matter for correctness; we just always
+# append it last for consistency.
+_FULL_CSS = (
+    CSS
+    + "\n/* === katex.min.css (inlined, fonts as data URIs) === */\n"
+    + _KATEX_CSS
+    + "\n/* === highlight.js github theme === */\n"
+    + _HLJS_CSS
+    + "\n/* === highlight.js github-dark theme (active under .dark) === */\n"
+    # Scope the dark theme to ``.dark`` so the light theme above is the
+    # default and the dark variant only kicks in when Gradio toggles its
+    # top-level ``.dark`` class. ``github-dark.min.css`` references
+    # ``.hljs`` (and many ``.hljs-...`` variants) at lots of positions:
+    # at the start of a rule, right after ``}``, AND comma-separated
+    # like ``.hljs-doctag,.hljs-keyword,...`` where only the first
+    # selector is preceded by ``}``. A simple global string replace
+    # works because ``.hljs`` only appears inside selectors in this
+    # file (never in property values or strings).
+    + _HLJS_DARK_CSS.replace(".hljs", ".dark .hljs")
+)
+
+
+
+with gr.Blocks(title=t("title"), fill_width=True, js=_JS_INIT) as demo:
+    state = gr.State(init_state)
+
+    with gr.Sidebar(width=420, open=True):
+        gr.HTML(
+            f"<h1 style='text-align:center;font-size:2rem;margin:0.2em 0 0.2em'>{t('title')}</h1>"
+            f"<p class='title-notice' style='text-align:center;font-size:0.88rem;"
+            f"line-height:1.4;color:var(--body-text-color,#444);"
+            f"margin:0 0 0.8em;padding:0 0.4em'>{t('title.notice_html')}</p>"
+        )
+        think_level = gr.Dropdown(
+            choices=["no_think", "low", "high"],
+            value="high",
+            label=t("sidebar.think_level"),
+            info=t("sidebar.think_level.info"),
+        )
+        system_prompt = gr.Textbox(
+            value="",
+            label=t("sidebar.system_prompt"),
+            lines=3,
+            placeholder=t("sidebar.system_prompt.placeholder"),
+        )
+        temperature = gr.Slider(
+            minimum=0, maximum=1, step=0.01, value=0.9,
+            label=t("sidebar.temperature"),
+            info=t("sidebar.temperature.info"),
+        )
+        max_tokens = gr.Slider(
+            minimum=256, maximum=65536, step=1, value=65536,
+            label=t("sidebar.max_tokens"),
+            info=t("sidebar.max_tokens.info"),
+        )
+        top_p = gr.Slider(
+            minimum=0, maximum=1, step=0.01, value=1.0,
+            label=t("sidebar.top_p"),
+            info=t("sidebar.top_p.info"),
+        )
+        rep_penalty = gr.Slider(
+            minimum=0, maximum=2, step=0.01, value=1.0,
+            label=t("sidebar.rep_penalty"),
+            info=t("sidebar.rep_penalty.info"),
+        )
+        with gr.Accordion(t("sidebar.functions"), open=False):
+            functions_json = gr.Textbox(
+                value="",
+                label=t("sidebar.functions.label"),
+                lines=15,
+                max_lines=30,
+                placeholder=_FN_PLACEHOLDER,
+            )
+            validate_fn_btn = gr.Button(t("sidebar.validate_btn"), size="sm")
+
+    # ── Custom chat surface ───────────────────────────────────────────
+    # The visible chat lives entirely inside <div id="hy-chat">, owned and
+    # mutated exclusively by static/chat.js. Server NEVER updates this
+    # component's value — it's set once at component creation and the
+    # renderer takes over from there.
+    chat_host = gr.HTML(
+        value=HY_CHAT_INITIAL_HTML,
+        elem_id="hy-chat-host",
+    )
+
+    # Hidden delta channel. Server pushes JSON ops payloads here; the
+    # client observes mutations on this element and applies each op to
+    # the chat container. Visually hidden via _hide.css (see the
+    # #hy-chat-delta rule there).
+    #
+    # Why a separate component (not a side-effect of chat_host updates):
+    # any update to chat_host's value would wipe the entire DOM the
+    # renderer has built. The delta channel is the safe back-door — its
+    # value can change freely on every yield without ever touching the
+    # visible chat surface.
+    chat_delta = gr.HTML(value="", elem_id="hy-chat-delta")
+
+    with gr.Column(visible=False, elem_id="tool-area") as tool_area:
+        tool_call_info = gr.Markdown("")
+        tool_result_input = gr.Textbox(
+            label=t("tool.result_label"),
+            placeholder=t("tool.result_placeholder"),
+            lines=1,
+        )
+        tool_submit_btn = gr.Button(t("tool.submit"), variant="primary", size="sm")
+
+    with gr.Row(elem_classes=["msg-row"]):
+        msg_input = gr.Textbox(
+            placeholder=t("msg_placeholder"),
+            show_label=False,
+            lines=1,
+            scale=8,
+            elem_classes=["msg-input"],
+        )
+        send_btn = gr.Button(
+            "➤", variant="primary",
+            scale=0, min_width=42,
+            elem_id="send-btn", elem_classes=["send-btn"],
+        )
+        new_chat_btn = gr.Button(
+            "+", variant="secondary",
+            scale=0, min_width=42,
+            elem_classes=["new-chat-btn"],
+        )
+
+    # Hidden busy-marker component. Driven by the streaming generators in
+    # chat.py:
+    #   * Streaming begins → value = HY_BUSY_HTML.
+    #   * Streaming ends   → value = HY_IDLE_HTML.
+    #
+    # The browser observes this single element and gates the Send button
+    # on it. Critically isolated from any chat content — unclosed
+    # <style>/<script>/<textarea> in model output cannot hijack it
+    # because it's a separate Gradio component.
+    busy_marker = gr.HTML("", elem_id="hy-busy-marker")
+
+    # ── Event wiring ──────────────────────────────────────────────────────
+    # IMPORTANT: the Send button's busy state is OWNED BY THE BROWSER, not
+    # by Gradio. We never call ``gr.update(interactive=False/True)`` on it
+    # from any handler. Instead the streaming generators drive busy_marker;
+    # static/app.js gates Send on its content (see file).
+    #
+    # ``concurrency_limit`` is SERVER-WIDE: up to N chat requests across
+    # ALL connected users can run in parallel. Per-session ``gr.State``
+    # isolates each user's conversation.
+    send_outputs = [
+        chat_delta, state, msg_input,
+        tool_area, tool_call_info, tool_result_input,
+        busy_marker,
+    ]
+    send_inputs = [
+        msg_input, state,
+        system_prompt, think_level, temperature, max_tokens, top_p, rep_penalty,
+        functions_json,
+    ]
+
+    chat_concurrency = {"concurrency_id": "chat", "concurrency_limit": 8}
+
+    for trigger in (msg_input.submit, send_btn.click):
+        trigger(
+            fn=send_message,
+            inputs=send_inputs,
+            outputs=send_outputs,
+            show_progress="hidden",
+            # UI-only handler: ships chat content as DOM-mutation deltas
+            # through ``chat_delta``, which is unusable from gradio_client.
+            # The headless ``/chat`` endpoint registered below is the
+            # supported programmatic surface.
+            api_visibility="private",
+            **chat_concurrency,
+        )
+
+    new_chat_btn.click(
+        fn=new_chat,
+        inputs=[state],
+        # ``busy_marker`` is in the output set so ``new_chat`` can release
+        # the Send-button lock immediately when it cancels an in-flight
+        # stream — without it the cancelled generator never reaches its
+        # terminal IDLE yield and the button would stay stuck until the
+        # client-side soft watchdog force-clears it.
+        outputs=[chat_delta, state, busy_marker],
+        show_progress="hidden",
+        api_visibility="private",
+    )
+
+    validate_fn_btn.click(
+        fn=validate_functions_json,
+        inputs=[functions_json],
+        outputs=[functions_json],
+        show_progress="hidden",
+        api_visibility="private",
+    )
+
+    tool_submit_inputs = [
+        tool_result_input, state,
+        system_prompt, think_level, temperature, max_tokens, top_p, rep_penalty,
+        functions_json,
+    ]
+    tool_submit_outputs = [
+        chat_delta, state,
+        tool_area, tool_call_info, tool_result_input,
+        busy_marker,
+    ]
+
+    for trigger in (tool_submit_btn.click, tool_result_input.submit):
+        trigger(
+            fn=submit_tool_result,
+            inputs=tool_submit_inputs,
+            outputs=tool_submit_outputs,
+            show_progress="hidden",
+            api_visibility="private",  # UI-only; see send_message wiring above.
+            **chat_concurrency,
+        )
+
+    # ── Programmatic API endpoint ────────────────────────────────────────
+    # Registered with ``gr.api`` so it has NO UI footprint — it derives its
+    # input/output schema from ``api_chat``'s type hints rather than from
+    # Gradio components. Callers reach it via:
+    #
+    #     from gradio_client import Client
+    #     client = Client("ericsqin/hy-demo")
+    #     content, reasoning, tool_calls, history = client.predict(
+    #         message="Hello!",
+    #         api_name="/chat",
+    #     )
+    gr.api(
+        api_chat,
+        api_name="chat",
+        concurrency_id="chat",
+        concurrency_limit=8,
+    )
+
+
+if __name__ == "__main__":
+    # Guarded so that ``import app`` (e.g. from tests or docs tooling)
+    # does not start a Gradio server as a side effect. HuggingFace Spaces
+    # invokes ``python app.py`` so this entry point still runs there.
+    demo.queue(default_concurrency_limit=16, max_size=64).launch(
+        css=_FULL_CSS,
+        ssr_mode=False,
+        show_error=True,
+    )

chat.py

@@ -0,0 +1,608 @@
+"""Gradio adapter layer — wires :mod:`core.chat` into Gradio events.
+
+All pure conversation logic lives in :mod:`core.chat`. This module only deals
+with Gradio types (``gr.update``, ``gr.Warning``) and yields the tuples that
+the Blocks event handlers expect.
+
+Architecture
+------------
+The chat surface is a custom HTML container (``<div id="hy-chat">``) owned
+and mutated by ``static/chat.js``. The server ships **deltas**, never full
+snapshots, via two hidden bridge components:
+
+* ``chat_delta`` (``gr.HTML``, ``elem_id="hy-chat-delta"``): a single
+  ``<div>`` whose textContent is the latest JSON payload of the form
+  ``{"seq": N, "ops": [...]}``. The browser observes mutations on this
+  element, parses, and applies each op to the chat container.
+* ``busy_marker`` (``gr.HTML``, ``elem_id="hy-busy-marker"``): drives the
+  Send button's enabled state. ``HY_BUSY_HTML`` while the model is
+  generating, ``HY_IDLE_HTML`` when it's done.
+
+Delta wire payload is just the new characters, and the client only
+re-renders the trailing in-progress paragraph; everything above it is
+frozen DOM that never changes again.
+
+Send-button busy-state ownership
+--------------------------------
+The Send button's busy state is **owned entirely by the browser** — there
+is NO server-side ``gr.update(interactive=...)`` toggling. See
+``static/app.js`` for the MutationObserver-based gate.
+
+The terminal IDLE-marker frame is shipped *separately* from any
+chat-content frame so that even when WebSocket is back-pressured the
+tiny marker frame still slips through and the UI unblocks promptly.
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+import logging
+from typing import Iterator
+
+import gradio as gr
+
+from core.chat import (
+    ChatState,
+    build_api_kwargs,
+    finalize_response,
+    flush_tool_results,
+    init_state,
+    record_tool_result,
+    reset_state_in_place,
+    stream_response,
+)
+from display import (
+    format_tool_call_prompt,
+    format_tool_calls_for_display,
+    preprocess_latex,
+)
+from i18n import t
+
+logger = logging.getLogger(__name__)
+
+# Sentinel values driven into the dedicated #hy-busy-marker gr.HTML
+# component on the server side, observed by the browser to drive the Send
+# button's enabled state.
+HY_BUSY_HTML = '<span data-hy-busy="1" data-hy-streaming="1" hidden aria-hidden="true"></span>'
+HY_IDLE_HTML = '<span data-hy-busy="0" hidden aria-hidden="true"></span>'
+
+# Initial value for the chat container (the inner <div> that the renderer
+# owns). Wrapped in another <div> so Gradio's gr.HTML wrapper has a stable
+# child to host the chat surface.
+HY_CHAT_INITIAL_HTML = '<div id="hy-chat" class="hy-chat" role="log" aria-live="polite"></div>'
+
+# Thread-safe monotonically-increasing sequence numbers for the delta
+# channel. Each delta payload carries one; the client uses it to dedup
+# (Gradio occasionally re-fires the same value on reconnect, and we never
+# want to re-apply the same ops twice).
+_seq_counter = itertools.count(1)
+
+
+def _next_seq() -> int:
+    return next(_seq_counter)
+
+
+# Bubble IDs are pre-allocated per assistant turn so all ops for the same
+# bubble (assistant_begin → reasoning_delta → content_delta → assistant_end →
+# tool_call) can be routed to the right DOM node on the client.
+_bubble_counter = itertools.count(1)
+
+
+def _next_bubble_id() -> str:
+    return f"a-{next(_bubble_counter)}"
+
+
+def _delta(ops: list[dict], epoch: int | None = None) -> str:
+    """Encode a list of ops as a delta payload string.
+
+    The payload is shipped through ``gr.HTML``'s value, which the front
+    end renders into the DOM via ``innerHTML``. Plain ``json.dumps``
+    output is valid HTML text 99 % of the time, but any user- or
+    model-supplied ``<`` would be parsed as the opening of an HTML tag
+    and silently truncate the payload (also a stored-XSS sink). We
+    pre-escape the three HTML-meta characters into their JSON
+    ``\\uNNNN`` form — the browser's ``JSON.parse`` reverses the escapes
+    so semantics are preserved end-to-end.
+
+    ``epoch`` tags the payload with the session's chat-epoch id so the
+    client can drop stale deltas that arrive after a "+" / new-chat
+    reset. The reset payload itself carries the NEW epoch — the client
+    adopts it, then ignores any later payload that still carries the
+    old one.
+    """
+    payload: dict = {"seq": _next_seq(), "ops": ops}
+    if epoch is not None:
+        payload["epoch"] = epoch
+    raw = json.dumps(payload, ensure_ascii=False)
+    return (
+        raw.replace("<", "\\u003c")
+           .replace(">", "\\u003e")
+           .replace("&", "\\u0026")
+    )
+
+
+# Re-export so ``from chat import init_state`` keeps working in app.py.
+__all__ = [
+    "init_state",
+    "send_message",
+    "new_chat",
+    "submit_tool_result",
+    "api_chat",
+    "HY_BUSY_HTML",
+    "HY_IDLE_HTML",
+    "HY_CHAT_INITIAL_HTML",
+]
+
+
+def _ensure_state(state) -> ChatState:
+    """Normalize ``state`` into a fresh ``ChatState`` dict.
+
+    ``gr.State(init_state)`` treats ``init_state`` as a per-session factory in
+    the browser, but stateless ``gradio_client`` calls hand the factory itself
+    to the handler. Accept callable/None and fall back to a fresh state so the
+    API works without breaking the in-browser per-session semantics.
+    """
+    if state is None or callable(state):
+        return init_state()
+    return state
+
+
+def _validate_user_message(message: str, functions_json_str: str) -> bool:
+    if not message or not message.strip():
+        gr.Warning(t("warn.empty_msg"))
+        return False
+    if functions_json_str and functions_json_str.strip():
+        try:
+            json.loads(functions_json_str)
+        except json.JSONDecodeError as e:
+            gr.Warning(t("warn.invalid_fn_json", err=str(e)))
+            return False
+    return True
+
+
+def _run_streaming_turn(
+    state: ChatState,
+    bubble_id: str,
+    epoch: int,
+    system_prompt: str,
+    think_level: str,
+    temperature: float,
+    max_tokens: int,
+    top_p: float,
+    rep_penalty: float,
+    functions_json_str: str,
+) -> Iterator[tuple[list[dict], bool, str]]:
+    """Stream a single turn. Yields ``(ops, show_tool, tool_md)``.
+
+    ``ops`` is the list of bubble-scoped ops (each carrying ``id=bubble_id``)
+    to ship on this frame. ``show_tool`` / ``tool_md`` carry the tool-area
+    UI state for the caller to translate into ``gr.update(...)`` outputs.
+
+    ``epoch`` is the chat-epoch captured by the caller at turn start.
+    We compare it against the live ``state["epoch"]`` between yields;
+    if they diverge the user clicked "+", so we stop yielding and let
+    the caller exit without finalising the assistant turn.
+    """
+    kwargs = build_api_kwargs(
+        state, system_prompt, functions_json_str,
+        think_level, temperature, max_tokens, top_p, rep_penalty,
+    )
+    logger.debug(
+        "streaming turn: reasoning_effort=%r temperature=%s max_tokens=%s top_p=%s",
+        think_level, temperature, max_tokens, top_p,
+    )
+
+    def _cancelled() -> bool:
+        return state.get("epoch") != epoch
+
+    last_ac, last_rc, last_tca = "", "", []
+    seen_first_content = False
+    for ops, ac, rc, tca, _rid in stream_response(kwargs, is_cancelled=_cancelled):
+        if _cancelled():
+            return
+        last_ac, last_rc, last_tca = ac, rc, tca
+        if not ops:
+            # Heartbeat — no new content. We still surface an empty-ops
+            # frame so the wire ticks (Gradio dedups equal values; the
+            # heartbeat carries the new seq via the delta payload below).
+            yield [], False, ""
+            continue
+        # Apply per-op LaTeX preprocessing on content_delta. The model may
+        # emit bare \begin{equation}...\end{equation} blocks etc.; KaTeX
+        # only renders math inside $$ delimiters.
+        out_ops: list[dict] = []
+        for op in ops:
+            if op["type"] == "content_delta":
+                # First content delta implicitly closes the thinking block on
+                # the client. We tag the FIRST content op with a flag so the
+                # client can switch the summary text and auto-collapse.
+                delta_text = preprocess_latex(op["delta"])
+                wrapped = {
+                    "type": "content_delta",
+                    "id": bubble_id,
+                    "delta": delta_text,
+                }
+                if not seen_first_content:
+                    wrapped["thinking_done"] = True
+                    seen_first_content = True
+                out_ops.append(wrapped)
+            elif op["type"] == "reasoning_delta":
+                out_ops.append({
+                    "type": "reasoning_delta",
+                    "id": bubble_id,
+                    "delta": op["delta"],
+                })
+            elif op["type"] == "tool_calls":
+                # Carry the snapshot through; we materialise it as a UI
+                # block only at end-of-turn (see the finalize section
+                # below). Skipping here keeps mid-stream wire payloads
+                # tiny — the same partial tool-call gets re-shipped on
+                # every frame otherwise.
+                continue
+        if out_ops:
+            yield out_ops, False, ""
+
+    # ── Terminal phase ─────────────────────────────────────────────────
+    if _cancelled():
+        return
+    has_tools, pending = finalize_response(
+        state, last_ac, last_rc, last_tca,
+    )
+    end_ops: list[dict] = [{"type": "assistant_end", "id": bubble_id}]
+    if has_tools:
+        # Render the tool-call display block as Markdown; the client will
+        # run marked over it. Append AFTER the assistant_end op so the DOM
+        # ordering stays correct (content → tool calls).
+        tc_markdown = format_tool_calls_for_display(pending)
+        end_ops.append({
+            "type": "tool_call",
+            "id": bubble_id,
+            "markdown": tc_markdown,
+        })
+        tool_md = format_tool_call_prompt(pending[0], 1, len(pending))
+        yield end_ops, True, tool_md
+    else:
+        yield end_ops, False, ""
+
+
+# ─── send_message ────────────────────────────────────────────────────────────
+# Output slot order (must match app.py's ``send_outputs``):
+#   0 chat_delta (gr.HTML, elem_id="hy-chat-delta")
+#   1 state
+#   2 msg_input
+#   3 tool_area
+#   4 tool_call_info
+#   5 tool_result_input
+#   6 busy_marker (gr.HTML, elem_id="hy-busy-marker")
+def send_message(
+    message, state,
+    system_prompt, think_level, temperature, max_tokens, top_p, rep_penalty,
+    functions_json_str,
+):
+    state = _ensure_state(state)
+
+    if not _validate_user_message(message, functions_json_str):
+        # Validation failure — never started streaming, marker stays idle,
+        # no chat ops emitted.
+        yield (
+            gr.update(), state, gr.update(),
+            gr.update(), gr.update(), gr.update(),
+            HY_IDLE_HTML,
+        )
+        return
+
+    message = message.strip()
+    state["messages"].append({"role": "user", "content": message})
+    bubble_id = _next_bubble_id()
+    # Capture the chat epoch at the start of the turn. ``new_chat`` bumps
+    # ``state["epoch"]`` in place; once that happens we stop yielding so
+    # the new fresh chat surface stays clean.
+    epoch = state["epoch"]
+
+    def _cancelled() -> bool:
+        return state.get("epoch") != epoch
+
+    # First frame: append the user bubble, open a new assistant bubble
+    # (with typing indicator), set busy marker, clear input.
+    yield (
+        _delta([
+            {"type": "user", "text": message},
+            {"type": "assistant_begin", "id": bubble_id},
+        ], epoch=epoch),
+        state, "",
+        gr.update(visible=False), gr.update(), gr.update(),
+        HY_BUSY_HTML,
+    )
+
+    try:
+        for ops, show_tool, tool_md in _run_streaming_turn(
+            state, bubble_id, epoch,
+            system_prompt, think_level, temperature, max_tokens, top_p, rep_penalty,
+            functions_json_str,
+        ):
+            if _cancelled():
+                return
+            # Heartbeat / no-op frame: still ship an empty-ops payload so
+            # the wire ticks and the proxy doesn't drop the connection.
+            payload = _delta(ops, epoch=epoch) if ops else _delta([], epoch=epoch)
+            if show_tool:
+                yield (
+                    payload, state, gr.update(),
+                    gr.update(visible=True), gr.update(value=tool_md), gr.update(value=""),
+                    gr.update(),
+                )
+            else:
+                yield (
+                    payload, state, gr.update(),
+                    gr.update(visible=False), gr.update(), gr.update(),
+                    gr.update(),
+                )
+
+    except Exception as e:
+        if _cancelled():
+            # Reset already cleaned the UI; swallow late-arriving errors
+            # from the abandoned upstream so we don't bounce a stale
+            # warning at the user.
+            return
+        logger.exception("send_message failed: %s", e)
+        if state["messages"] and state["messages"][-1].get("role") == "user":
+            state["messages"].pop()
+        gr.Warning(t("warn.request_failed"))
+        # Drop the typing-indicator placeholder bubble client-side, restore
+        # the user's message into the input box, release the busy marker.
+        yield (
+            _delta([{"type": "remove_bubble", "id": bubble_id}], epoch=epoch),
+            state, gr.update(value=message),
+            gr.update(visible=False), gr.update(), gr.update(),
+            HY_IDLE_HTML,
+        )
+        return
+
+    if _cancelled():
+        return
+
+    # ── Terminal IDLE-marker frame ──────────────────────────────────────
+    # Only changes the busy marker; every other slot is gr.update(). Tens
+    # of bytes on the wire — slips past any WebSocket back-pressure so the
+    # browser MutationObserver fires the moment the stream genuinely ends,
+    # releasing the Send button.
+    yield (
+        gr.update(), state, gr.update(),
+        gr.update(), gr.update(), gr.update(),
+        HY_IDLE_HTML,
+    )
+
+
+# ─── Programmatic API endpoint ───────────────────────────────────────────────
+# The UI handlers above (``send_message`` / ``submit_tool_result``) ship chat
+# content as DOM-mutation deltas through a hidden ``chat_delta`` HTML
+# component, which is unusable from ``gradio_client``: a remote caller would
+# only ever see the final ``gr.update()`` placeholders and the busy marker.
+#
+# ``api_chat`` is the headless counterpart: a stateless, generator function
+# whose YIELDED tuple is the entire reply so far. ``gradio_client.predict``
+# returns the last yield, so callers get the full ``(content, reasoning,
+# tool_calls, history)`` snapshot once the stream finishes; users that want
+# token-by-token streaming can iterate via ``client.submit(...)``.
+def api_chat(
+    message: str,
+    system_prompt: str = "",
+    history: list | None = None,
+    think_level: str = "high",
+    temperature: float = 0.9,
+    max_tokens: int = 65536,
+    top_p: float = 1.0,
+    rep_penalty: float = 1.0,
+    functions_json_str: str = "",
+) -> Iterator[tuple[str, str, list, list]]:
+    """Stateless chat endpoint for ``gradio_client`` callers.
+
+    Args:
+        message: The new user turn.
+        system_prompt: Optional system prompt prepended to every request.
+        history: Prior conversation as a list of OpenAI-style messages
+            (``[{"role": "user"|"assistant"|"tool", "content": ...}, ...]``).
+            Pass ``None`` or ``[]`` to start a fresh conversation. The caller
+            owns the history; pass the returned ``updated_history`` back on
+            the next call to continue multi-turn.
+        think_level: One of ``"no_think" | "low" | "high"``.
+        temperature, max_tokens, top_p, rep_penalty: Standard sampling knobs.
+        functions_json_str: JSON string of tool definitions (OpenAI tools
+            schema). Empty string disables function calling.
+
+    Yields:
+        ``(content, reasoning_content, tool_calls, updated_history)``
+        cumulative on every yield. The final yield is the complete reply.
+
+        * ``content``: assistant visible text.
+        * ``reasoning_content``: chain-of-thought (when ``think_level``
+          requests it). May be empty for ``no_think``.
+        * ``tool_calls``: list of OpenAI-style tool-call dicts the model
+          requested. Empty when no function was called. The caller is
+          responsible for executing each call and appending the
+          corresponding ``{"role": "tool", "tool_call_id": ..., "content":
+          ...}`` messages to ``history`` on the next ``api_chat`` call.
+        * ``updated_history``: full message list including the new user
+          turn and the assistant reply (with ``tool_calls`` attached when
+          present). Suitable for round-tripping into the next call.
+
+    Raises:
+        ValueError: when ``message`` is empty or ``functions_json_str`` is
+            not valid JSON.
+    """
+    if not message or not message.strip():
+        raise ValueError("message must be a non-empty string")
+    if functions_json_str and functions_json_str.strip():
+        try:
+            json.loads(functions_json_str)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"functions_json_str is not valid JSON: {e}") from e
+
+    state = init_state()
+    if history:
+        # Defensive copy — never mutate the caller's list.
+        state["messages"] = [dict(m) for m in history]
+    state["messages"].append({"role": "user", "content": message.strip()})
+
+    kwargs = build_api_kwargs(
+        state, system_prompt, functions_json_str,
+        think_level, temperature, max_tokens, top_p, rep_penalty,
+    )
+
+    last_ac, last_rc = "", ""
+    last_tca: list[dict] = []
+    yielded = False
+    for _ops, ac, rc, tca, _rid in stream_response(kwargs):
+        last_ac, last_rc, last_tca = ac, rc, tca
+        # Snapshot the in-flight assistant turn into a transient history
+        # view so streaming consumers see the assistant text growing.
+        in_flight = list(state["messages"])
+        in_flight.append({
+            "role": "assistant",
+            "content": ac or "",
+            **({"reasoning_content": rc} if rc else {}),
+            **({"tool_calls": list(tca)} if tca else {}),
+        })
+        yield ac or "", rc or "", list(tca), in_flight
+        yielded = True
+
+    finalize_response(state, last_ac, last_rc, last_tca)
+    final_history = list(state["messages"])
+
+    # Always emit a terminal frame so callers consuming only the last yield
+    # observe the persisted history (the in-flight snapshots above attach a
+    # provisional assistant message; this one is the canonical record).
+    if not yielded:
+        yield "", "", [], final_history
+    else:
+        yield last_ac or "", last_rc or "", list(last_tca), final_history
+
+
+def new_chat(state):
+    """Reset the conversation.
+
+    Critical: when there's an in-flight stream we MUTATE the existing
+    state dict in place (bumping its epoch) instead of returning a brand
+    new dict. The streaming generator holds a reference to this same
+    dict and polls ``state["epoch"]`` between yields — the in-place
+    bump is what tells it to abandon the rest of its turn. Returning a
+    fresh dict would leave the generator pointed at a stale dict it
+    would happily keep streaming into.
+
+    We also push ``HY_IDLE_HTML`` to the busy marker so the Send button
+    unlocks immediately. Without this the cancelled generator never
+    yields its terminal IDLE frame, so the button would stay stuck
+    until the soft watchdog in static/app.js force-clears it (~4s).
+    """
+    if not state or not isinstance(state, dict) or not state.get("messages"):
+        gr.Info(t("info.new_chat"))
+        return gr.update(), state, gr.update()
+    new_epoch = reset_state_in_place(state)
+    return (
+        _delta([{"type": "reset"}], epoch=new_epoch),
+        state,
+        HY_IDLE_HTML,
+    )
+
+
+# ─── submit_tool_result ──────────────────────────────────────────────────────
+# Output slot order (must match app.py's ``tool_submit_outputs``):
+#   0 chat_delta
+#   1 state
+#   2 tool_area
+#   3 tool_call_info
+#   4 tool_result_input
+#   5 busy_marker
+def submit_tool_result(
+    result_text, state,
+    system_prompt, think_level, temperature, max_tokens, top_p, rep_penalty,
+    functions_json_str,
+):
+    state = _ensure_state(state)
+    pending = state.get("pending_tool_calls", [])
+    if not pending:
+        yield (
+            gr.update(), state,
+            gr.update(visible=False), gr.update(), gr.update(),
+            HY_IDLE_HTML,
+        )
+        return
+
+    record_tool_result(state, pending[0], result_text)
+    state["pending_tool_calls"] = pending[1:]
+
+    if state["pending_tool_calls"]:
+        # More tool results still pending — keep the tool area visible,
+        # marker stays idle (we're not streaming yet).
+        remaining = state["pending_tool_calls"]
+        submitted = state.get("submitted_tool_results", [])
+        total = len(remaining) + len(submitted)
+        current_idx = len(submitted) + 1
+        tool_info_md = format_tool_call_prompt(remaining[0], current_idx, total)
+        yield (
+            gr.update(), state,
+            gr.update(visible=True), gr.update(value=tool_info_md), gr.update(value=""),
+            HY_IDLE_HTML,
+        )
+        return
+
+    flush_tool_results(state)
+    bubble_id = _next_bubble_id()
+    epoch = state["epoch"]
+
+    def _cancelled() -> bool:
+        return state.get("epoch") != epoch
+
+    # First streaming frame: open a new assistant bubble for the tool
+    # follow-up response, hide the tool area, set the busy marker.
+    yield (
+        _delta([{"type": "assistant_begin", "id": bubble_id}], epoch=epoch),
+        state,
+        gr.update(visible=False), gr.update(), gr.update(),
+        HY_BUSY_HTML,
+    )
+
+    try:
+        for ops, show_tool, tool_md in _run_streaming_turn(
+            state, bubble_id, epoch,
+            system_prompt, think_level, temperature, max_tokens, top_p, rep_penalty,
+            functions_json_str,
+        ):
+            if _cancelled():
+                return
+            payload = _delta(ops, epoch=epoch) if ops else _delta([], epoch=epoch)
+            if show_tool:
+                yield (
+                    payload, state,
+                    gr.update(visible=True), gr.update(value=tool_md), gr.update(value=""),
+                    gr.update(),
+                )
+            else:
+                yield (
+                    payload, state,
+                    gr.update(visible=False), gr.update(), gr.update(),
+                    gr.update(),
+                )
+
+    except Exception as e:
+        if _cancelled():
+            return
+        logger.exception("submit_tool_result failed: %s", e)
+        gr.Warning(t("warn.request_failed"))
+        yield (
+            _delta([{"type": "remove_bubble", "id": bubble_id}], epoch=epoch),
+            state,
+            gr.update(visible=False), gr.update(), gr.update(),
+            HY_IDLE_HTML,
+        )
+        return
+
+    if _cancelled():
+        return
+
+    yield (
+        gr.update(), state,
+        gr.update(), gr.update(), gr.update(),
+        HY_IDLE_HTML,
+    )

config.py

@@ -0,0 +1,70 @@
+"""Runtime configuration loaded from environment variables.
+
+Required:
+    HY_API_KEY        API key for the upstream OpenAI-compatible endpoint.
+    HY_BASE_URL       OpenAI-compatible base URL of the upstream endpoint.
+    HY_MODEL          Model name passed to chat.completions.create.
+
+Optional:
+    HY_LOG_LEVEL      One of DEBUG / INFO / WARNING / ERROR (default: WARNING).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from openai import OpenAI
+
+
+API_KEY = os.environ.get("HY_API_KEY", "").strip()
+BASE_URL = os.environ.get("HY_BASE_URL", "").strip()
+MODEL = os.environ.get("HY_MODEL", "").strip()
+LOG_LEVEL = os.environ.get("HY_LOG_LEVEL", "WARNING").upper()
+
+
+# Configure logging once at import time. Kept module-level (rather than
+# behind ``if __name__ == "__main__"``) because every module in the
+# project does ``logging.getLogger(__name__)`` and expects the format /
+# level to already be set up. The handler is only installed if no other
+# handler exists — embedders that have already configured logging are
+# left untouched.
+if not logging.getLogger().handlers:
+    logging.basicConfig(
+        level=getattr(logging, LOG_LEVEL, logging.WARNING),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+logger = logging.getLogger("Hy3-preview")
+
+
+# Surface missing required env vars loudly at import time. We don't
+# raise — that would prevent the Gradio server from even starting up
+# (and HuggingFace Spaces would just show a blank build-failed page),
+# making it harder to debug. Instead: warn now, and the per-request
+# code paths will still fail cleanly with the upstream API's own
+# error message.
+_missing = [
+    name
+    for name, val in (
+        ("HY_API_KEY", API_KEY),
+        ("HY_BASE_URL", BASE_URL),
+        ("HY_MODEL", MODEL),
+    )
+    if not val
+]
+if _missing:
+    logger.warning(
+        "Required env var(s) not set: %s. "
+        "The app will boot but every chat request will fail until they are "
+        "configured (e.g. as HuggingFace Space secrets / variables).",
+        ", ".join(_missing),
+    )
+
+
+# ``base_url=""`` would be passed through to httpx and produce undefined
+# request URLs. ``None`` makes the OpenAI SDK fall back to its default
+# (api.openai.com), which is at least a well-defined behaviour.
+client = OpenAI(
+    api_key=API_KEY or "missing-api-key",
+    base_url=BASE_URL or None,
+)

core/__init__.py

@@ -0,0 +1,23 @@
+"""Pure-Python core: conversation state + streaming logic, no Gradio."""
+
+from .chat import (
+    ChatState,
+    init_state,
+    build_messages_for_api,
+    build_api_kwargs,
+    stream_response,
+    finalize_response,
+    record_tool_result,
+    flush_tool_results,
+)
+
+__all__ = [
+    "ChatState",
+    "init_state",
+    "build_messages_for_api",
+    "build_api_kwargs",
+    "stream_response",
+    "finalize_response",
+    "record_tool_result",
+    "flush_tool_results",
+]

core/chat.py

@@ -0,0 +1,446 @@
+from __future__ import annotations
+
+import itertools
+import logging
+import queue
+import threading
+import time
+from typing import Any, Callable, Iterator, Optional, TypedDict
+
+from config import MODEL, client
+from tools import build_tools_list
+
+logger = logging.getLogger(__name__)
+
+# Monotonically-increasing epoch ids stamped on every per-session
+# ``ChatState`` and bumped on reset. Streaming handlers capture the
+# epoch at entry and check it between yields; if the user clicks "+"
+# (``new_chat``) mid-stream, ``reset_state_in_place`` mutates the SAME
+# state dict the running generator holds — bumping the epoch — so the
+# generator notices on its next iteration and exits without emitting
+# any further chat deltas.
+_epoch_counter = itertools.count(1)
+
+
+def _next_epoch() -> int:
+    return next(_epoch_counter)
+
+# Floor interval between streaming yields. The per-yield cost on the
+# wire is just a small delta payload, so 60ms ≈ 16 yields/sec — close
+# to one yield per browser frame, which is the natural ceiling for
+# human-perceptible smoothness anyway.
+_YIELD_INTERVAL = 0.06
+
+# How often to emit a keep-alive yield when no new chunks arrive. This keeps
+# the SSE/WebSocket connection alive through reverse-proxy idle timeouts
+# (e.g. HuggingFace Spaces proxy). Without heartbeats, a long pause between
+# reasoning and content chunks can cause the proxy to drop the connection,
+# silently terminating the generator.
+_HEARTBEAT_INTERVAL = 5.0
+
+# Sentinel placed in the chunk queue when the streaming thread finishes.
+_STREAM_DONE = object()
+
+
+def _drain_queue(q: queue.Queue) -> list:
+    """Pull every item currently in *q* without blocking. Empty list if none."""
+    out: list = []
+    while True:
+        try:
+            out.append(q.get_nowait())
+        except queue.Empty:
+            return out
+
+
+class ChatState(TypedDict, total=False):
+    messages: list[dict]
+    context_start_index: int
+    pending_tool_calls: list[dict]
+    pending_assistant_msg: Optional[dict]
+    submitted_tool_results: list[dict]
+    epoch: int
+
+
+def init_state() -> ChatState:
+    """Fresh per-session conversation state.
+
+    Note: there is intentionally NO server-side ``is_streaming`` flag. The
+    "model is busy" signal is owned entirely by the UI: a click on Send
+    instantly disables the Send button via a ``queue=False`` Gradio chain
+    BEFORE the streaming generator is even queued, so a duplicate submission
+    is impossible regardless of network latency or queue order.
+
+    ``epoch`` is the cancellation token: bumped by ``reset_state_in_place``
+    when the user clicks "+" mid-stream so the running generator can
+    detect the reset and abandon further yields.
+    """
+    return {
+        "messages": [],
+        "context_start_index": 0,
+        "pending_tool_calls": [],
+        "pending_assistant_msg": None,
+        "submitted_tool_results": [],
+        "epoch": _next_epoch(),
+    }
+
+
+def reset_state_in_place(state: ChatState) -> int:
+    """Reset *state* in place and bump its epoch. Returns the new epoch.
+
+    Critical: this MUTATES the caller's dict instead of returning a fresh
+    one. A streaming generator started before the reset still holds a
+    reference to this same dict — the in-place mutation is what lets it
+    observe the bumped epoch and stop yielding chat deltas. Returning a
+    new dict (and asking Gradio to swap it into the State component)
+    would leave the in-flight generator pointed at a stale dict it would
+    happily keep streaming into.
+    """
+    state["messages"] = []
+    state["context_start_index"] = 0
+    state["pending_tool_calls"] = []
+    state["pending_assistant_msg"] = None
+    state["submitted_tool_results"] = []
+    state["epoch"] = _next_epoch()
+    return state["epoch"]
+
+
+def get_context_messages(state: ChatState) -> list[dict]:
+    return state["messages"][state["context_start_index"]:]
+
+
+def build_messages_for_api(state: ChatState, system_prompt: str) -> list[dict]:
+    context = get_context_messages(state)
+    if system_prompt and system_prompt.strip():
+        return [{"role": "system", "content": system_prompt.strip()}] + context
+    return list(context)
+
+
+def build_api_kwargs(
+    state: ChatState,
+    system_prompt: str,
+    functions_json_str: Optional[str],
+    think_level: Optional[str],
+    temperature: Optional[float],
+    max_tokens: int,
+    top_p: Optional[float],
+    rep_penalty: Optional[float],
+) -> dict:
+    """Build the kwargs dict passed to ``client.chat.completions.create``."""
+    api_messages = build_messages_for_api(state, system_prompt)
+    tools = build_tools_list(functions_json_str)
+
+    extra_body: dict = {}
+    if rep_penalty is not None and float(rep_penalty) != 0:
+        extra_body["repetition_penalty"] = float(rep_penalty)
+
+    kwargs: dict = dict(
+        model=MODEL,
+        messages=api_messages,
+        stream=True,
+        max_tokens=int(max_tokens),
+        reasoning_effort=think_level or "no_think",
+    )
+    if temperature is not None and float(temperature) != 0:
+        kwargs["temperature"] = float(temperature)
+    if top_p is not None and float(top_p) != 0:
+        kwargs["top_p"] = float(top_p)
+    if extra_body:
+        kwargs["extra_body"] = extra_body
+    if tools:
+        kwargs["tools"] = tools
+    return kwargs
+
+
+def _accumulate_tool_call(tool_calls_acc: list[dict], delta_tcs: list[Any]) -> None:
+    """Merge streamed tool-call deltas into the accumulator."""
+    for tc in delta_tcs:
+        idx = getattr(tc, "index", 0) or 0
+        while len(tool_calls_acc) <= idx:
+            tool_calls_acc.append(
+                {"id": "", "type": "function", "function": {"name": "", "arguments": ""}}
+            )
+        if tc.id:
+            tool_calls_acc[idx]["id"] = tc.id
+        if tc.function:
+            if tc.function.name:
+                tool_calls_acc[idx]["function"]["name"] += tc.function.name
+            if tc.function.arguments:
+                tool_calls_acc[idx]["function"]["arguments"] += tc.function.arguments
+
+
+def _stream_worker(
+    kwargs: dict,
+    chunk_queue: queue.Queue,
+) -> None:
+    """Background thread: run the API call and feed chunks into *chunk_queue*."""
+    try:
+        stream = client.chat.completions.create(**kwargs)
+        for chunk in stream:
+            chunk_queue.put(chunk)
+    except Exception as exc:
+        chunk_queue.put(exc)
+    finally:
+        chunk_queue.put(_STREAM_DONE)
+
+
+# Hard ceilings: if no chunk has arrived for this long AND the worker thread
+# hasn't terminated, we abandon the stream so the UI lock can release. With a
+# healthy heartbeat the worker normally posts STREAM_DONE within seconds of
+# the model finishing, but reverse proxies / network blips can occasionally
+# leave the SSE connection in a half-open state that hangs ``for chunk in
+# stream`` indefinitely. Capping the wait guarantees ``send_message`` always
+# reaches its final yield (and therefore re-enables the Send button).
+#
+# Two separate ceilings because the two phases have very different shapes:
+#   * Before the first chunk the model may be doing reasoning / queueing /
+#     KV-cache warmup, so we allow a generous 30s first-token budget.
+#   * Once tokens are flowing we expect them to keep flowing; a 15s gap with
+#     nothing arriving (and no STREAM_DONE) almost certainly means the SSE
+#     socket is dead.
+_FIRST_CHUNK_TIMEOUT = 60.0
+_INTER_CHUNK_TIMEOUT = 15.0
+
+
+# Op type constants — keep in sync with static/chat.js.
+OP_REASONING_DELTA = "reasoning_delta"
+OP_CONTENT_DELTA = "content_delta"
+OP_TOOL_CALLS = "tool_calls"
+
+
+def stream_response(
+    kwargs: dict,
+    is_cancelled: Optional[Callable[[], bool]] = None,
+) -> Iterator[tuple[list[dict], str, str, list[dict], str]]:
+    """Stream chunks from the API and yield delta-op batches.
+
+    The actual HTTP stream runs in a daemon thread so that the generator can
+    emit keep-alive yields during API-side pauses (model thinking, network
+    hiccups, etc.). Without these heartbeats the SSE connection between the
+    browser and a reverse proxy (e.g. HuggingFace Spaces) may be dropped
+    for inactivity, silently killing the generator mid-response.
+
+    Drain coalescing
+    ----------------
+    Each iteration drains EVERY chunk currently buffered into a single batch
+    and emits one yield reflecting the merged deltas. Under back-pressure the
+    yield rate naturally collapses (more chunks per yield) without losing
+    data — the deltas accumulate in ``pending_*`` strings until the next
+    successful yield can drain them.
+
+    Two early-exit paths protect the UI from getting stuck:
+
+    * As soon as we see ``finish_reason`` we drain whatever is already in
+      the queue without blocking, then break. The model has logically
+      finished; waiting on the SSE socket close would only lengthen the
+      visible "stuck" window.
+    * Two timeout safety nets force a break if the stream stalls while
+      the worker is still technically alive.
+
+    Yields ``(ops, assistant_total, reasoning_total, tool_calls, request_id)``
+    where ``ops`` is the list of delta dicts since the previous yield.
+    Heartbeat yields produce an empty ``ops`` list — callers should treat
+    that as "no new content but the stream is still healthy".
+    """
+    assistant_content = ""
+    reasoning_content = ""
+    tool_calls_acc: list[dict] = []
+    request_id = ""
+
+    # Pending-since-last-yield deltas. Persist across drain iterations so
+    # a throttle-suppressed yield doesn't lose the chars; the next yield
+    # picks them up.
+    pending_reasoning = ""
+    pending_content = ""
+    tool_calls_dirty = False
+
+    chunk_q: queue.Queue = queue.Queue()
+    worker = threading.Thread(
+        target=_stream_worker, args=(kwargs, chunk_q), daemon=True,
+    )
+    worker.start()
+
+    saw_finish_reason = False
+
+    def take_ops() -> list[dict]:
+        """Drain pending deltas into an ops list; return [] if nothing pending."""
+        nonlocal pending_reasoning, pending_content, tool_calls_dirty
+        ops: list[dict] = []
+        if pending_reasoning:
+            ops.append({"type": OP_REASONING_DELTA, "delta": pending_reasoning})
+            pending_reasoning = ""
+        if pending_content:
+            ops.append({"type": OP_CONTENT_DELTA, "delta": pending_content})
+            pending_content = ""
+        if tool_calls_dirty:
+            ops.append({"type": OP_TOOL_CALLS, "tool_calls": list(tool_calls_acc)})
+            tool_calls_dirty = False
+        return ops
+
+    def apply_chunk(chunk) -> bool:
+        """Fold a single API chunk into the accumulators.
+
+        Returns True when this chunk produced visible-state changes
+        (content, reasoning, or tool-call deltas). Sets the outer
+        ``saw_finish_reason`` / ``request_id`` as a side effect.
+        """
+        nonlocal request_id, reasoning_content, assistant_content
+        nonlocal pending_reasoning, pending_content, tool_calls_dirty
+        nonlocal saw_finish_reason
+        if not request_id and getattr(chunk, "id", None):
+            request_id = chunk.id
+        if not chunk.choices:
+            return False
+        choice = chunk.choices[0]
+        delta = choice.delta
+        if getattr(choice, "finish_reason", None):
+            saw_finish_reason = True
+
+        changed = False
+        rc = getattr(delta, "reasoning_content", None)
+        if rc:
+            reasoning_content += rc
+            pending_reasoning += rc
+            changed = True
+        if delta.content:
+            assistant_content += delta.content
+            pending_content += delta.content
+            changed = True
+        if getattr(delta, "tool_calls", None):
+            _accumulate_tool_call(tool_calls_acc, delta.tool_calls)
+            tool_calls_dirty = True
+            changed = True
+        return changed
+
+    last_yield_at = 0.0
+    last_chunk_at = time.monotonic()
+    got_first_chunk = False
+    yielded = False
+    done = False
+
+    while not done:
+        # Cancellation check — caller (e.g. ``new_chat``) bumped the
+        # session epoch, so abandon the stream WITHOUT a final yield.
+        # The worker thread keeps running until the upstream API closes
+        # the connection, but its chunks pile harmlessly into the
+        # garbage-collected queue once we return.
+        if is_cancelled is not None and is_cancelled():
+            logger.debug("stream cancelled by caller, abandoning")
+            return
+
+        # ── block for the next item, with heartbeat / stall guards ──
+        try:
+            first = chunk_q.get(timeout=_HEARTBEAT_INTERVAL)
+        except queue.Empty:
+            if not worker.is_alive() and chunk_q.empty():
+                break
+            stall_budget = (
+                _INTER_CHUNK_TIMEOUT if got_first_chunk else _FIRST_CHUNK_TIMEOUT
+            )
+            if time.monotonic() - last_chunk_at > stall_budget:
+                logger.warning(
+                    "stream stalled %.1fs with no chunks (%s), abandoning",
+                    stall_budget,
+                    "inter-chunk" if got_first_chunk else "first-chunk",
+                )
+                break
+            # Heartbeat: re-emit current state with empty ops so Gradio
+            # ships an SSE frame and the upstream proxy doesn't consider
+            # the channel idle. The empty-ops frame is ~70 bytes and the
+            # client treats it as a noop.
+            yield [], assistant_content, reasoning_content, tool_calls_acc, request_id
+            yielded = True
+            last_yield_at = time.monotonic()
+            continue
+
+        # ── coalesce: pull every chunk currently buffered ──
+        batch = [first] + _drain_queue(chunk_q)
+
+        for item in batch:
+            if item is _STREAM_DONE:
+                done = True
+                continue
+            if isinstance(item, Exception):
+                raise item
+            last_chunk_at = time.monotonic()
+            got_first_chunk = True
+            apply_chunk(item)
+
+        # ── one throttled yield per drained batch ──
+        # Force-emit on done / finish so the final state always ships.
+        if pending_reasoning or pending_content or tool_calls_dirty:
+            now = time.monotonic()
+            if done or saw_finish_reason or now - last_yield_at >= _YIELD_INTERVAL:
+                ops = take_ops()
+                yield ops, assistant_content, reasoning_content, tool_calls_acc, request_id
+                yielded = True
+                last_yield_at = now
+
+        # ── finish_reason fast-exit ──
+        # Model has logically finished. Drain anything still buffered and
+        # exit. Don't wait on the SSE socket close.
+        if saw_finish_reason and not done:
+            for item in _drain_queue(chunk_q):
+                if item is _STREAM_DONE:
+                    break
+                if isinstance(item, Exception):
+                    raise item
+                apply_chunk(item)
+            ops = take_ops()
+            if ops:
+                yield ops, assistant_content, reasoning_content, tool_calls_acc, request_id
+                yielded = True
+            break
+
+    # Final flush — guarantee callers always observe terminal accumulator
+    # values, even when every prior content yield was suppressed by the
+    # throttle (e.g. a tiny response that finished within the floor).
+    ops = take_ops()
+    if ops or not yielded:
+        yield ops, assistant_content, reasoning_content, tool_calls_acc, request_id
+
+
+def finalize_response(
+    state: ChatState,
+    assistant_content: str,
+    reasoning_content: str,
+    tool_calls_acc: list[dict],
+) -> tuple[bool, list[dict]]:
+    """Persist the final assistant message into ``state``.
+
+    Returns ``(has_pending_tool_calls, pending_tool_calls)``. The Gradio
+    adapter is responsible for turning ``pending_tool_calls`` into UI
+    updates (see ``chat.py``).
+    """
+    assistant_msg: dict = {"role": "assistant", "content": assistant_content or None}
+    if reasoning_content:
+        assistant_msg["reasoning_content"] = reasoning_content
+
+    if tool_calls_acc:
+        assistant_msg["tool_calls"] = tool_calls_acc
+        state["messages"].append(assistant_msg)
+        state["pending_tool_calls"] = list(tool_calls_acc)
+        state["submitted_tool_results"] = []
+        state["pending_assistant_msg"] = assistant_msg
+        logger.debug("queued %d tool call(s)", len(tool_calls_acc))
+        return True, list(tool_calls_acc)
+
+    state["messages"].append(assistant_msg)
+    return False, []
+
+
+def record_tool_result(state: ChatState, tool_call: Any, result_text: str) -> None:
+    """Record a single tool-call result in the pending queue."""
+    tc_id = tool_call["id"] if isinstance(tool_call, dict) else tool_call.id
+    state.setdefault("submitted_tool_results", []).append({
+        "role": "tool",
+        "tool_call_id": tc_id,
+        "content": result_text or "",
+    })
+
+
+def flush_tool_results(state: ChatState) -> None:
+    """Move queued tool results into the main message log."""
+    for msg in state.get("submitted_tool_results", []):
+        state["messages"].append(msg)
+    state["submitted_tool_results"] = []
+    state["pending_assistant_msg"] = None

display.py

@@ -0,0 +1,174 @@
+"""Helpers that turn raw model output into Markdown for the chatbot widget."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from i18n import t
+
+# KaTeX renders negation macros (\neq, \notin, …) via \not + SVG slash
+# overlays.  The chat bubble's inflated line-height stretches those SVGs
+# into solid-black rectangles.  Replacing with Unicode avoids the SVG
+# path entirely — KaTeX renders the single glyph from its math fonts
+# instead.
+#
+# The dict covers both single-macro forms (\neq) and \not compound forms
+# (\not=, \not\equiv).  Sorted longest-first when building the regex so
+# longer patterns match before shorter prefixes.
+_NEGATION_UNICODE: dict[str, str] = {
+    # \not + symbol compounds
+    r"\not\subseteq": "⊈",
+    r"\not\supseteq": "⊉",
+    r"\not\parallel": "∦",
+    r"\not\approx":   "≉",
+    r"\not\subset":   "⊄",
+    r"\not\supset":   "⊅",
+    r"\not\simeq":    "≄",
+    r"\not\exists":   "∄",
+    r"\not\equiv":    "≢",
+    r"\not\cong":     "≇",
+    r"\not\leq":      "≰",
+    r"\not\geq":      "≱",
+    r"\not\sim":      "≁",
+    r"\not\mid":      "∤",
+    r"\not\le":       "≰",
+    r"\not\ge":       "≱",
+    r"\not\in":       "∉",
+    r"\not\ni":       "∌",
+    r"\not=":         "≠",
+    r"\not<":         "≮",
+    r"\not>":         "≯",
+    # Standard single-macro negations
+    r"\nsubseteq":    "⊈",
+    r"\nsupseteq":    "⊉",
+    r"\nparallel":    "∦",
+    r"\nexists":      "∄",
+    r"\nequiv":       "≢",
+    r"\notin":        "∉",
+    r"\nless":        "≮",
+    r"\nleq":         "≰",
+    r"\ngeq":         "≱",
+    r"\ngtr":         "≯",
+    r"\nmid":         "∤",
+    r"\ncong":        "≇",
+    r"\nsim":         "≁",
+    r"\neq":          "≠",
+    r"\ne":           "≠",
+}
+_NEGATION_RE = re.compile(
+    "("
+    + "|".join(
+        re.escape(m)
+        for m in sorted(_NEGATION_UNICODE, key=len, reverse=True)
+    )
+    + r")(?![a-zA-Z])",
+)
+
+
+_NOT_SPACE_RE = re.compile(r"\\not\s+(?=[\[=<>]|\\[a-zA-Z])")
+
+
+def _replace_negation_macros(text: str) -> str:
+    """Swap negation macros for Unicode glyphs to bypass SVG overlays."""
+    # Collapse optional whitespace after \not so \not \equiv → \not\equiv
+    text = _NOT_SPACE_RE.sub(r"\\not", text)
+    return _NEGATION_RE.sub(lambda m: _NEGATION_UNICODE[m.group(1)], text)
+
+
+# LaTeX environments that should be treated as display math.
+_MATH_ENVS = (
+    "equation", "align", "aligned", "gather", "gathered",
+    "multline", "cases", "array", "split",
+    "matrix", "bmatrix", "pmatrix", "vmatrix", "Vmatrix",
+    "eqnarray",
+)
+_ENV_NAMES = "|".join(_MATH_ENVS)
+
+# Matches \begin{env}...\end{env} blocks NOT already inside $$ delimiters.
+# Uses a backreference (\2) to ensure begin/end names match.
+_BARE_ENV_RE = re.compile(
+    r"(?<!\$)"
+    r"(\\begin\{(" + _ENV_NAMES + r")\*?\}"
+    r"[\s\S]*?"
+    r"\\end\{\2\*?\})"
+    r"(?!\$)",
+)
+
+
+def _wrap_bare_latex_envs(text: str) -> str:
+    r"""Wrap bare \begin{env}...\end{env} blocks in $$ for KaTeX.
+
+    Models sometimes output LaTeX environments without wrapping them in
+    display-math delimiters.  KaTeX only renders them when they appear
+    inside ``$$...$$`` or ``\[...\]``.
+    """
+    return _BARE_ENV_RE.sub(r"\n\n$$\1$$\n\n", text)
+
+
+def _escape_latex_delimiters(text: str) -> str:
+    r"""Replace LaTeX delimiters with HTML entities so a downstream
+    Markdown / KaTeX pass does not match them across the <details>
+    boundary.
+
+    Covers ``\(...\)``, ``\[...\]``, ``$...$``, and ``$$...$$``.
+    """
+    return (
+        text
+        .replace("\\(", "&#92;(")
+        .replace("\\)", "&#92;)")
+        .replace("\\[", "&#92;[")
+        .replace("\\]", "&#92;]")
+        .replace("$", "&#36;")
+    )
+
+
+def preprocess_latex(text: str) -> str:
+    """Normalize model output so KaTeX renders math correctly.
+
+    Applied to the assistant *content* (not thinking) before display.
+    """
+    text = _replace_negation_macros(text)
+    text = _wrap_bare_latex_envs(text)
+    return text
+
+
+def build_display_content(reasoning: str, content: str) -> str:
+    """Wrap reasoning + content into a collapsible Markdown block."""
+    parts: list[str] = []
+    if reasoning:
+        is_complete = bool(content)
+        summary = t("display.thinking_done") if is_complete else t("display.thinking")
+        open_attr = "" if is_complete else " open"
+        safe_reasoning = _escape_latex_delimiters(reasoning.strip())
+        parts.append(
+            f'<details class="thinking-block"{open_attr}>'
+            f'<summary>{summary}</summary>\n\n{safe_reasoning}\n\n</details>\n\n'
+        )
+    if content:
+        parts.append(preprocess_latex(content))
+    return "".join(parts)
+
+
+def format_tool_calls_for_display(tool_calls: list[Any]) -> str:
+    return "\n\n".join(_format_single_tool_call(tc) for tc in tool_calls)
+
+
+def format_tool_call_prompt(tc: Any, current_idx: int, total: int) -> str:
+    header = f"**{t('tool.call_header', i=current_idx, n=total)}**\n\n"
+    return header + _format_single_tool_call(tc)
+
+
+def _format_single_tool_call(tc: Any) -> str:
+    if isinstance(tc, dict):
+        name = tc["function"]["name"]
+        args_raw = tc["function"]["arguments"]
+    else:
+        name = tc.function.name
+        args_raw = tc.function.arguments
+    try:
+        args_formatted = json.dumps(json.loads(args_raw), indent=2, ensure_ascii=False)
+    except (json.JSONDecodeError, TypeError):
+        args_formatted = args_raw
+    return f"{t('tool.call_label')}: **{name}**\n```json\n{args_formatted}\n```"

i18n.py

@@ -0,0 +1,161 @@
+"""Tiny dictionary-based i18n helper.
+
+Selects the active language from ``HY_LANG`` env var (falls back to ``LANG`` /
+``LC_ALL``). Anything starting with ``zh`` resolves to Simplified Chinese,
+everything else to English.
+
+Usage::
+
+    from i18n import t
+    label = t("send")          # -> "Send" or "发送"
+    msg = t("warn.empty_msg")  # nested-dotted keys
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_LANG = "en"
+SUPPORTED_LANGS = ("en", "zh")
+
+
+def _detect_lang() -> str:
+    raw = (
+        os.environ.get("HY_LANG")
+        or os.environ.get("LC_ALL")
+        or os.environ.get("LANG")
+        or DEFAULT_LANG
+    )
+    raw = raw.strip().lower()
+    if raw.startswith("zh"):
+        return "zh"
+    if raw[:2] in SUPPORTED_LANGS:
+        return raw[:2]
+    return DEFAULT_LANG
+
+
+LANG = _detect_lang()
+
+
+# ─── Dictionary ────────────────────────────────────────────────────────────
+# Keys are flat dotted strings to keep lookup simple. Add new keys below in
+# alphabetical groups for readability.
+TRANSLATIONS: dict[str, dict[str, str]] = {
+    "en": {
+        # App chrome
+        "title": "Hy3-preview Chat Demo",
+        "title.notice_html": (
+            "The current demo version is offline; full-featured capabilities "
+            "will be available on the Tencent HY official website."
+        ),
+        "examples_heading": "What can I help you with?",
+        "msg_placeholder": "Type a message...",
+        # Sidebar
+        "sidebar.think_level": "Think level",
+        "sidebar.think_level.info": "Control reasoning depth",
+        "sidebar.system_prompt": "System prompt",
+        "sidebar.system_prompt.placeholder": "You are a helpful AI assistant...",
+        "sidebar.temperature": "Temperature",
+        "sidebar.temperature.info": "Higher values produce more random outputs",
+        "sidebar.max_tokens": "Max output tokens",
+        "sidebar.max_tokens.info": "Maximum tokens per response",
+        "sidebar.top_p": "Top P",
+        "sidebar.top_p.info": "Nucleus sampling probability threshold",
+        "sidebar.rep_penalty": "Repetition penalty",
+        "sidebar.rep_penalty.info": "Penalize repeated content",
+        "sidebar.functions": "🔧 Functions",
+        "sidebar.functions.label": "Function definitions (JSON array)",
+        "sidebar.validate_btn": "Validate & Format",
+        # Tool area
+        "tool.result_label": "Function result",
+        "tool.result_placeholder": "Enter function return value... (Enter to submit)",
+        "tool.submit": "Submit",
+        "tool.call_header": "Function call ({i}/{n})",
+        "tool.call_label": "🔧 Call function",
+        # Display
+        "display.thinking": "Thinking...",
+        "display.thinking_done": "Thinking complete",
+        "display.code_copy": "Copy",
+        "display.code_copied": "Copied",
+        # Warnings / info
+        "warn.empty_msg": "Please enter a message",
+        "warn.invalid_fn_json": "Invalid function JSON, please fix or clear before sending: {err}",
+        "warn.request_failed": "Request failed, please retry or adjust parameters",
+        "warn.model_busy": "Model is still responding. Please wait for it to finish before sending a new message.",
+        "info.new_chat": "Start a new chat",
+        "warn.fn.enter_json": "Please enter function definition JSON",
+        "warn.fn.invalid_format": "Invalid JSON format: {err}",
+        "warn.fn.must_be_array": "JSON must be an array [...] or a single object {{...}}",
+        "warn.fn.item_not_object": "Item {i} is not a JSON object",
+        "warn.fn.item_invalid": "Item {i} has invalid format, expected {{type, function}} or {{name, parameters}}",
+        "warn.fn.duplicate_name": "Duplicate function name '{name}'",
+        "info.fn.validation_passed": "Validation passed, {n} function(s): {names}",
+    },
+    "zh": {
+        "title": "Hy3-preview Chat Demo",
+        "title.notice_html": (
+            "The current demo version is offline; full-featured capabilities "
+            "will be available on the Tencent HY official website."
+        ),
+        "examples_heading": "今天我能帮你做点什么？",
+        "msg_placeholder": "输入消息...",
+        "sidebar.think_level": "思考等级",
+        "sidebar.think_level.info": "控制模型推理深度",
+        "sidebar.system_prompt": "系统提示词",
+        "sidebar.system_prompt.placeholder": "你是一个有帮助的 AI 助手...",
+        "sidebar.temperature": "Temperature",
+        "sidebar.temperature.info": "数值越高，回复越随机",
+        "sidebar.max_tokens": "最大输出 Tokens",
+        "sidebar.max_tokens.info": "单次回复的最大 token 数",
+        "sidebar.top_p": "Top P",
+        "sidebar.top_p.info": "核采样概率阈值",
+        "sidebar.rep_penalty": "重复惩��",
+        "sidebar.rep_penalty.info": "惩罚重复内容",
+        "sidebar.functions": "🔧 函数",
+        "sidebar.functions.label": "函数定义（JSON 数组）",
+        "sidebar.validate_btn": "校验 & 格式化",
+        "tool.result_label": "函数返回值",
+        "tool.result_placeholder": "请输入函数返回值...（回车提交）",
+        "tool.submit": "提交",
+        "tool.call_header": "函数调用 ({i}/{n})",
+        "tool.call_label": "🔧 调用函数",
+        "display.thinking": "思考中...",
+        "display.thinking_done": "已思考",
+        "display.code_copy": "复制",
+        "display.code_copied": "已复制",
+        "warn.empty_msg": "请输入消息内容",
+        "warn.invalid_fn_json": "函数 JSON 不合法，请先修正或清空: {err}",
+        "warn.request_failed": "请求失败，请重试或调整参数",
+        # Intentionally English for both locales: the warning should always
+        # appear in English regardless of the UI language.
+        "warn.model_busy": "Model is still responding. Please wait for it to finish before sending a new message.",
+        "info.new_chat": "已开启新会话",
+        "warn.fn.enter_json": "请输入函数定义 JSON",
+        "warn.fn.invalid_format": "JSON 格式错误: {err}",
+        "warn.fn.must_be_array": "JSON 必须是数组 [...] 或单个对象 {{...}}",
+        "warn.fn.item_not_object": "第 {i} 项不是 JSON 对象",
+        "warn.fn.item_invalid": "第 {i} 项格式不合法，期望 {{type, function}} 或 {{name, parameters}}",
+        "warn.fn.duplicate_name": "函数名 '{name}' 重复",
+        "info.fn.validation_passed": "校验通过，共 {n} 个函数: {names}",
+    },
+}
+
+
+def t(key: str, /, **fmt: Any) -> str:
+    """Translate ``key`` for the active language with optional formatting."""
+    table = TRANSLATIONS.get(LANG, TRANSLATIONS[DEFAULT_LANG])
+    template = table.get(key) or TRANSLATIONS[DEFAULT_LANG].get(key)
+    if template is None:
+        logger.warning("missing i18n key: %s", key)
+        return key
+    if not fmt:
+        return template
+    try:
+        return template.format(**fmt)
+    except (KeyError, IndexError):
+        logger.warning("i18n format failure for key=%s args=%r", key, fmt)
+        return template

pytest.ini

@@ -0,0 +1,5 @@
+[pytest]
+testpaths = tests
+addopts = -ra -q
+filterwarnings =
+    ignore::DeprecationWarning

requirements.txt

@@ -0,0 +1 @@
+openai>=1.66.0

static/app.js

@@ -0,0 +1,997 @@
+/* eslint-disable */
+/**
+ * Gradio app bootstrap.
+ *
+ * The Python side injects window.HY_EXAMPLES / window.HY_I18N before this
+ * script runs. The custom chat renderer (static/chat.js) owns all DOM
+ * mutations under #hy-chat — this file only deals with the surrounding
+ * UX (overlay, scroll, send-button state, copy/preview buttons).
+ *
+ * Responsibilities
+ * ────────────────
+ *   1. Render the empty-state "What can I help you with?" overlay above the
+ *      chat surface, with example prompts that auto-send when clicked.
+ *   2. Add a "▶ html preview" button below every Markdown HTML code block,
+ *      and render the code in a sandboxed iframe modal.
+ *   3. Add a "Copy" button to the top-right of every <pre> code block.
+ *   4. Own scroll behaviour: follow-the-tail while streaming, full user
+ *      control after streaming ends.
+ *   5. OWN the Send-button busy state. The server NEVER toggles the
+ *      button. Instead, the streaming generators in chat.py drive a
+ *      dedicated hidden ``gr.HTML`` component (``#hy-busy-marker``):
+ *      while streaming → it contains a single
+ *      ``<span data-hy-streaming="1">``; on the final yield → it's
+ *      idle. We observe that one component and disable Send iff the
+ *      marker span is present.
+ *
+ *      The marker lives in its OWN component (not inside the chat) so
+ *      unclosed ``<style>``/``<script>``/``<textarea>``/``<title>``/
+ *      ``<noscript>`` in model output cannot hijack it.
+ */
+(() => {
+  if (window.__HY_APP_INIT) return;
+  window.__HY_APP_INIT = true;
+
+  const EXAMPLES = (window.HY_EXAMPLES || []).slice();
+  const BUSY_MSG =
+    (window.HY_I18N && window.HY_I18N.model_busy) ||
+    "Model is still responding. Please wait for it to finish.";
+
+  // The chat surface lives at #hy-chat (built by static/chat.js into the
+  // value of the gr.HTML at #hy-chat-host). Throughout this file we treat
+  // #hy-chat as "the chatbot" — it's our custom replacement.
+  const CHAT_SELECTOR = "#hy-chat";
+
+  // CSS selector for the in-flight streaming marker. See chat.py
+  // (HY_BUSY_HTML) for the producer side.
+  const BUSY_MARKER_HOST_ID = "hy-busy-marker";
+  const STREAM_MARKER_SELECTOR =
+    '#' + BUSY_MARKER_HOST_ID + ' [data-hy-streaming="1"]';
+  // Explicit "server says idle" marker. Distinct from "no marker yet"
+  // (the host's initial empty value), so we can tell apart "still
+  // waiting for the first server frame" from "server already responded
+  // with idle" (e.g. validation short-circuit before any streaming).
+  const IDLE_MARKER_SELECTOR =
+    '#' + BUSY_MARKER_HOST_ID + ' [data-hy-busy="0"]';
+
+  // Set to ``performance.now()`` whenever the user clicks Send / hits Enter.
+  // Bridges the brief window between "user dispatched" and "first marker
+  // frame arrived" so a fast double-click can't sneak through.
+  let lastSendAt = 0;
+  const SEND_DEBOUNCE_MS = 400;
+
+  // Set to true the moment the user dispatches a send, cleared the moment
+  // either (a) the server's first busy-marker frame actually arrives, or
+  // (b) FIRST_FRAME_TIMEOUT_MS elapses (defensive timeout in case the
+  // request never lands — e.g. WebSocket dropped before the first frame).
+  //
+  // SEND_DEBOUNCE_MS alone is NOT enough: on a slow link the round-trip
+  // for the first frame can easily exceed 400ms and a second click slips
+  // through, causing two parallel streams (server-side concurrency_limit
+  // is 8 for the chat fn so the second request DOES run).
+  let awaitingFirstFrame = false;
+  const FIRST_FRAME_TIMEOUT_MS = 30 * 1000;
+
+  // Soft watchdog: if the busy marker is set but the chat DOM has been
+  // observably idle for this long AND it's been at least
+  // CHAT_IDLE_MIN_SINCE_SEND_MS since the user clicked Send, we force-
+  // clear the marker. Safety net for "the server's IDLE marker frame
+  // got coalesced/dropped on the wire".
+  const CHAT_IDLE_MS = 4000;
+  const CHAT_IDLE_MIN_SINCE_SEND_MS = 1500;
+
+  // Hard absolute cap. Defence-in-depth backstop in case the soft
+  // watchdog also fails for some reason.
+  const ABSOLUTE_BUSY_TIMEOUT_MS = 5 * 60 * 1000;
+
+  // Flipped to true on a real send dispatch so the scroll lock knows to
+  // re-enter follow mode for the next streaming turn even if the user had
+  // scrolled up during the previous turn.
+  let justSentNewMessage = false;
+
+  /* ── Chat mutation hub (rAF-batched) ───────────────────────────────────
+   *
+   * The chat DOM gets HAMMERED during streaming: every new token may
+   * mutate the trailing streaming segment. With each subsystem
+   * (scroll lock, code-block injector, busy-marker timestamp,
+   * empty-state visibility) installing its OWN MutationObserver,
+   * the per-mutation work multiplied by the number of subsystems
+   * was the dominant browser-side cost as conversations grew.
+   *
+   * We run a single MutationObserver and dispatch to subscribers via
+   * requestAnimationFrame. This caps total dispatches at ≤60/sec
+   * regardless of how many mutations the chat fires, and lets each
+   * subscriber see the WHOLE batch of mutations in one call instead
+   * of being woken N times in the same tick.
+   *
+   * Subscribers MUST be cheap — the rAF callback is on the critical
+   * path of the next paint. */
+  const chatSubscribers = [];
+  let chatPending = null;
+  let chatScheduled = false;
+
+  function subscribeChatMutations(cb) {
+    chatSubscribers.push(cb);
+  }
+
+  function startChatMutationHub(chatEl) {
+    new MutationObserver((mutations) => {
+      if (chatPending === null) chatPending = [];
+      // Ref-share the records — they're owned by the observer and we
+      // don't mutate them, just iterate.
+      for (let i = 0; i < mutations.length; i++) {
+        chatPending.push(mutations[i]);
+      }
+      if (chatScheduled) return;
+      chatScheduled = true;
+      requestAnimationFrame(() => {
+        chatScheduled = false;
+        const batch = chatPending;
+        chatPending = null;
+        for (let i = 0; i < chatSubscribers.length; i++) {
+          try {
+            chatSubscribers[i](batch);
+          } catch (err) {
+            console.error("[hy] chat subscriber error:", err);
+          }
+        }
+      });
+    }).observe(chatEl, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+  }
+
+  /* ── Empty-state examples overlay ─────────────────────────────────────── */
+  function createOverlay() {
+    const chatEl = document.querySelector(CHAT_SELECTOR);
+    if (!chatEl) {
+      setTimeout(createOverlay, 500);
+      return;
+    }
+    if (document.getElementById("examples-overlay")) return;
+
+    const overlay = document.createElement("div");
+    overlay.id = "examples-overlay";
+
+    const wrapper = document.createElement("div");
+    wrapper.className = "examples-wrapper";
+
+    const heading = document.createElement("p");
+    heading.className = "examples-heading";
+    heading.textContent =
+      (window.HY_I18N && window.HY_I18N.examples_heading) ||
+      "What can I help you with?";
+    wrapper.appendChild(heading);
+
+    const grid = document.createElement("div");
+    grid.className = "examples-grid";
+
+    // Example-button label.
+    //   * Collapse internal whitespace/newlines to single spaces so each
+    //     card flows as one paragraph; the CSS 2-line clamp on
+    //     .example-btn handles the visual cut-off + ellipsis.
+    //   * Hard cap at LABEL_MAX_CHARS as defence-in-depth — the prompts
+    //     can be multi-kilobyte system instructions and we don't want
+    //     all of that in the DOM just to be invisibly clamped.
+    //   * ``title`` shows the full text on hover.
+    // The FULL prompt is always what we dispatch to the model; this is
+    // a display-only transform.
+    const LABEL_MAX_CHARS = 200;
+    function makeLabel(text) {
+      const oneLine = String(text).replace(/\s+/g, " ").trim();
+      if (oneLine.length <= LABEL_MAX_CHARS) return oneLine;
+      return oneLine.slice(0, LABEL_MAX_CHARS).trimEnd() + "…";
+    }
+
+    EXAMPLES.forEach((text) => {
+      // Two-layer structure:
+      //   .example-btn       → flex container, owns size + centering
+      //   .example-btn-text  → -webkit-box, owns the 2-line clamp
+      // Splitting these is the only reliable way to get BOTH "vertical
+      // centering" (needs display:flex) AND "clamp to 2 lines with auto
+      // ellipsis" (needs display:-webkit-box) on the same card. Single-
+      // element setups force a choice and we always lost one.
+      const btn = document.createElement("div");
+      btn.className = "example-btn";
+      const inner = document.createElement("span");
+      inner.className = "example-btn-text";
+      inner.textContent = makeLabel(text);
+      btn.appendChild(inner);
+      btn.title = text;
+      btn.addEventListener("click", () => {
+        const textarea = document.querySelector(".msg-input textarea");
+        if (!textarea) return;
+        textarea.focus();
+        textarea.select();
+        document.execCommand("insertText", false, text);
+        setTimeout(() => {
+          const sendBtn = document.querySelector("#send-btn");
+          if (sendBtn) sendBtn.click();
+        }, 200);
+      });
+      grid.appendChild(btn);
+    });
+
+    wrapper.appendChild(grid);
+    overlay.appendChild(wrapper);
+
+    function positionOverlay() {
+      const r = chatEl.getBoundingClientRect();
+      overlay.style.top = `${r.top}px`;
+      overlay.style.left = `${r.left}px`;
+      overlay.style.width = `${r.width}px`;
+      overlay.style.height = `${r.height}px`;
+    }
+    positionOverlay();
+    document.body.appendChild(overlay);
+
+    function syncVisibility() {
+      const msgs = chatEl.querySelectorAll(".message-row");
+      overlay.style.display = msgs.length > 0 ? "none" : "";
+    }
+    syncVisibility();
+    subscribeChatMutations(syncVisibility);
+
+    window.addEventListener("resize", positionOverlay);
+    new ResizeObserver(positionOverlay).observe(chatEl);
+  }
+
+  /* ── HTML preview modal ───────────────────────────────────────────────── */
+  function openHtmlPreview(htmlCode) {
+    const existing = document.querySelector(".html-preview-overlay");
+    if (existing) existing.remove();
+
+    const overlay = document.createElement("div");
+    overlay.className = "html-preview-overlay";
+    overlay.addEventListener("click", (e) => {
+      if (e.target === overlay) overlay.remove();
+    });
+
+    const modal = document.createElement("div");
+    modal.className = "html-preview-modal";
+
+    const header = document.createElement("div");
+    header.className = "html-preview-header";
+
+    const title = document.createElement("span");
+    title.className = "html-preview-title";
+    title.textContent = "HTML Preview";
+
+    const closeBtn = document.createElement("button");
+    closeBtn.className = "html-preview-close";
+    closeBtn.innerHTML = "&times;";
+    closeBtn.addEventListener("click", () => overlay.remove());
+
+    header.appendChild(title);
+    header.appendChild(closeBtn);
+
+    const iframe = document.createElement("iframe");
+    iframe.className = "html-preview-iframe";
+    // Intentionally NOT including allow-same-origin: that would let the
+    // user-supplied HTML reach into the parent page and steal cookies/state.
+    iframe.sandbox = "allow-scripts allow-modals allow-forms allow-popups";
+
+    modal.appendChild(header);
+    modal.appendChild(iframe);
+    overlay.appendChild(modal);
+    document.body.appendChild(overlay);
+
+    iframe.srcdoc = htmlCode;
+
+    document.addEventListener("keydown", function escHandler(e) {
+      if (e.key === "Escape") {
+        overlay.remove();
+        document.removeEventListener("keydown", escHandler);
+      }
+    });
+  }
+
+  const HTML_TAG_RE =
+    /<\/(div|body|html|section|main|head|style|script|p|h[1-6]|span|table|form|ul|ol|nav|header|footer|article)>/i;
+
+  function looksLikeHtml(text) {
+    const trimmed = text.trim();
+    if (!trimmed) return false;
+    if (
+      trimmed.startsWith("<!DOCTYPE") ||
+      trimmed.startsWith("<!doctype") ||
+      trimmed.startsWith("<html")
+    ) {
+      return true;
+    }
+    return (
+      trimmed.startsWith("<") &&
+      trimmed.endsWith(">") &&
+      HTML_TAG_RE.test(trimmed)
+    );
+  }
+
+  function injectPreviewButtonFor(codeEl) {
+    // ``previewBtnInserted`` — set once on the codeEl after we attach a
+    // button. Must NEVER be set on a code element living inside
+    // ``.hy-streaming`` because that container's innerHTML is replaced
+    // on every delta — the codeEl gets discarded and a fresh one (no
+    // flag) appears, while the button (a sibling outside .hy-streaming)
+    // would silently leak. We only inject for code blocks that have
+    // settled into ``.hy-frozen`` (append-only, never re-rendered).
+    if (codeEl.dataset.previewBtnInserted) {
+      codeEl.__hyPreviewText = codeEl.textContent || "";
+      return;
+    }
+
+    const pre = codeEl.closest("pre");
+    if (!pre) return;
+
+    // Skip code blocks still in the streaming half. They'll be
+    // re-evaluated once the freeze boundary advances past them and the
+    // pre is moved into ``.hy-frozen`` as a fresh DOM node — at which
+    // point this MutationObserver fires again with the new pre as an
+    // added node and we inject exactly once.
+    const frozenAncestor = pre.closest(".hy-frozen");
+    if (!frozenAncestor) return;
+
+    const text = codeEl.textContent || "";
+    if (!looksLikeHtml(text)) return;
+
+    codeEl.dataset.previewBtnInserted = "true";
+    codeEl.__hyPreviewText = text;
+
+    const btn = document.createElement("button");
+    btn.className = "html-preview-btn";
+    btn.title = "Preview HTML";
+    btn.addEventListener("click", (e) => {
+      e.stopPropagation();
+      e.preventDefault();
+      openHtmlPreview(codeEl.__hyPreviewText || codeEl.textContent || "");
+    });
+
+    // Insert directly after the <pre> inside the same .hy-frozen
+    // container. This binds the button's lifecycle to the specific
+    // code block (instead of dumping all preview buttons into b.md as
+    // siblings of .hy-frozen / .hy-streaming) and keeps its position
+    // visually anchored to its source block.
+    pre.parentElement.insertBefore(btn, pre.nextSibling);
+  }
+
+  /* ── Code-block chrome (header w/ lang label + copy button) ───────────── */
+  function copyText(text) {
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      return navigator.clipboard.writeText(text).catch(() => fallbackCopy(text));
+    }
+    return fallbackCopy(text);
+  }
+
+  function fallbackCopy(text) {
+    return new Promise((resolve, reject) => {
+      try {
+        const ta = document.createElement("textarea");
+        ta.value = text;
+        ta.setAttribute("readonly", "");
+        ta.style.position = "absolute";
+        ta.style.left = "-9999px";
+        document.body.appendChild(ta);
+        ta.select();
+        document.execCommand("copy");
+        document.body.removeChild(ta);
+        resolve();
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+  const COPY_ICON_SVG =
+    '<svg viewBox="0 0 24 24" width="14" height="14" fill="none" ' +
+    'stroke="currentColor" stroke-width="2" stroke-linecap="round" ' +
+    'stroke-linejoin="round" aria-hidden="true">' +
+    '<rect x="9" y="9" width="11" height="11" rx="2" ry="2"></rect>' +
+    '<path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>' +
+    "</svg>";
+  const CHECK_ICON_SVG =
+    '<svg viewBox="0 0 24 24" width="14" height="14" fill="none" ' +
+    'stroke="currentColor" stroke-width="2.5" stroke-linecap="round" ' +
+    'stroke-linejoin="round" aria-hidden="true">' +
+    '<polyline points="4 12 10 18 20 6"></polyline>' +
+    "</svg>";
+
+  // Pull the language label off the <code> element. ``marked`` always
+  // emits ``class="language-X"`` from the fence info string, and
+  // ``hljs.highlightElement`` may also add ``language-X`` after detection.
+  // Anything else (no fence info, hljs failed) → blank label so the
+  // header still renders consistently.
+  function detectCodeLang(codeEl) {
+    const cls = codeEl.className || "";
+    const m = cls.match(/(?:^|\s)language-([\w+#.-]+)/i);
+    if (!m) return "";
+    const lang = m[1].toLowerCase();
+    // A few common aliases for nicer display.
+    const ALIASES = {
+      js: "javascript",
+      ts: "typescript",
+      sh: "shell",
+      bash: "shell",
+      zsh: "shell",
+      yml: "yaml",
+      md: "markdown",
+      "c++": "cpp",
+    };
+    return ALIASES[lang] || lang;
+  }
+
+  const COPY_LABEL =
+    (window.HY_I18N && window.HY_I18N.code_copy) || "Copy";
+  const COPIED_LABEL =
+    (window.HY_I18N && window.HY_I18N.code_copied) || "Copied";
+
+  function injectCopyButtonFor(codeEl) {
+    const pre = codeEl.closest("pre");
+    if (!pre || pre.dataset.copyInjected) return;
+    pre.dataset.copyInjected = "true";
+
+    // ── Build the wrapper card ────────────────────────────────────────
+    const wrapper = document.createElement("div");
+    wrapper.className = "hy-codeblock";
+
+    const header = document.createElement("div");
+    header.className = "hy-codeblock-header";
+
+    const lang = document.createElement("span");
+    lang.className = "hy-codeblock-lang";
+    lang.textContent = detectCodeLang(codeEl);
+    header.appendChild(lang);
+
+    const btn = document.createElement("button");
+    btn.type = "button";
+    btn.className = "code-copy-btn";
+    btn.setAttribute("aria-label", COPY_LABEL);
+    btn.title = COPY_LABEL;
+    btn.innerHTML = COPY_ICON_SVG;
+
+    let resetTimer = null;
+    btn.addEventListener("click", (e) => {
+      e.stopPropagation();
+      e.preventDefault();
+      const text = codeEl.textContent || "";
+      copyText(text).then(
+        () => {
+          btn.innerHTML = CHECK_ICON_SVG;
+          btn.classList.add("copied");
+          btn.title = COPIED_LABEL;
+          if (resetTimer) clearTimeout(resetTimer);
+          resetTimer = setTimeout(() => {
+            btn.innerHTML = COPY_ICON_SVG;
+            btn.classList.remove("copied");
+            btn.title = COPY_LABEL;
+          }, 1400);
+        },
+        () => {
+          btn.title = "Copy failed";
+          if (resetTimer) clearTimeout(resetTimer);
+          resetTimer = setTimeout(() => {
+            btn.title = COPY_LABEL;
+          }, 1400);
+        }
+      );
+    });
+    header.appendChild(btn);
+
+    // ── Splice wrapper into the DOM around <pre> ─────────────────────
+    // Insert the wrapper where <pre> lived, then move <pre> into it.
+    // The mutation observer that drives this function will re-fire for
+    // the wrapper's appearance, but ``dataset.copyInjected`` on <pre>
+    // makes the second pass a no-op.
+    const parent = pre.parentElement;
+    if (!parent) return;
+    parent.insertBefore(wrapper, pre);
+    wrapper.appendChild(header);
+    wrapper.appendChild(pre);
+  }
+
+  function processCodeBlock(codeEl) {
+    injectCopyButtonFor(codeEl);
+    injectPreviewButtonFor(codeEl);
+  }
+
+  function watchForHtmlBlocks() {
+    const chatEl = document.querySelector(CHAT_SELECTOR);
+    if (!chatEl) {
+      setTimeout(watchForHtmlBlocks, 500);
+      return;
+    }
+
+    chatEl.querySelectorAll("pre code").forEach(processCodeBlock);
+
+    // Subscribers receive the whole rAF batch in one call. Within a
+    // single batch the same code element may appear in many records
+    // (one per streamed token); we de-dup with a Set so we only
+    // re-evaluate ``injectPreviewButtonFor`` ONCE per affected code
+    // element per frame instead of once per mutation.
+    subscribeChatMutations((mutations) => {
+      const codeElsToCheck = new Set();
+      for (let i = 0; i < mutations.length; i++) {
+        const m = mutations[i];
+        if (m.type === "childList") {
+          const added = m.addedNodes;
+          for (let j = 0; j < added.length; j++) {
+            const node = added[j];
+            if (!(node instanceof HTMLElement)) continue;
+            if (node.matches && node.matches("pre code")) {
+              processCodeBlock(node);
+            } else if (node.querySelectorAll) {
+              const found = node.querySelectorAll("pre code");
+              for (let k = 0; k < found.length; k++) {
+                processCodeBlock(found[k]);
+              }
+            }
+          }
+        } else if (m.type === "characterData") {
+          const el = m.target.parentElement;
+          if (el && el.tagName === "CODE") codeElsToCheck.add(el);
+        }
+      }
+      // Late-arriving HTML detection: a code block may not have looked
+      // like HTML when first added but does now that more tokens have
+      // streamed in. injectPreviewButtonFor is idempotent so calling it
+      // again is safe and cheap.
+      codeElsToCheck.forEach(injectPreviewButtonFor);
+    });
+  }
+
+  /* ── Send button: helpers ─────────────────────────────────────────────── */
+  function getSendButton() {
+    const wrap = document.querySelector("#send-btn");
+    if (!wrap) return null;
+    if (wrap.tagName === "BUTTON") return wrap;
+    return wrap.querySelector("button");
+  }
+
+  function setSendDisabled(disabled) {
+    const btn = getSendButton();
+    if (!btn) return;
+    if (disabled) {
+      if (!btn.disabled) {
+        btn.setAttribute("disabled", "");
+        btn.disabled = true;
+      }
+    } else {
+      if (btn.disabled || btn.hasAttribute("disabled")) {
+        btn.removeAttribute("disabled");
+        btn.disabled = false;
+      }
+    }
+  }
+
+  function streamMarkerPresent() {
+    return !!document.querySelector(STREAM_MARKER_SELECTOR);
+  }
+
+  function idleMarkerPresent() {
+    return !!document.querySelector(IDLE_MARKER_SELECTOR);
+  }
+
+  function isModelBusy() {
+    const now = performance.now();
+    // Awaiting the server's first frame after a dispatch — must remain
+    // busy regardless of marker state, with a hard timeout to avoid a
+    // permanently-stuck button if the request silently failed.
+    if (awaitingFirstFrame && now - lastSendAt < FIRST_FRAME_TIMEOUT_MS) {
+      return true;
+    }
+    if (now - lastSendAt < SEND_DEBOUNCE_MS) return true;
+    return streamMarkerPresent();
+  }
+
+  /* ── Busy toast ───────────────────────────────────────────────────────── */
+  function ensureBusyToastHost() {
+    let host = document.getElementById("hy-busy-toast-host");
+    if (host) return host;
+    host = document.createElement("div");
+    host.id = "hy-busy-toast-host";
+    Object.assign(host.style, {
+      position: "fixed",
+      top: "24px",
+      left: "50%",
+      transform: "translateX(-50%)",
+      zIndex: "9999",
+      display: "flex",
+      flexDirection: "column",
+      gap: "8px",
+      pointerEvents: "none",
+    });
+    document.body.appendChild(host);
+    return host;
+  }
+
+  let lastToastAt = 0;
+  function showBusyToast() {
+    const now = performance.now();
+    if (now - lastToastAt < 800) return;
+    lastToastAt = now;
+
+    const host = ensureBusyToastHost();
+    const toast = document.createElement("div");
+    toast.className = "hy-busy-toast";
+    toast.textContent = BUSY_MSG;
+    Object.assign(toast.style, {
+      background: "#1f2937",
+      color: "#fff",
+      padding: "10px 16px",
+      borderRadius: "8px",
+      boxShadow: "0 6px 20px rgba(0,0,0,0.25)",
+      fontSize: "14px",
+      maxWidth: "min(92vw, 520px)",
+      lineHeight: "1.4",
+      opacity: "0",
+      transition: "opacity 180ms ease",
+      pointerEvents: "none",
+    });
+    host.appendChild(toast);
+    requestAnimationFrame(() => {
+      toast.style.opacity = "1";
+    });
+    setTimeout(() => {
+      toast.style.opacity = "0";
+      setTimeout(() => toast.remove(), 250);
+    }, 3200);
+  }
+
+  /* ── Send-button busy guard ───────────────────────────────────────────── */
+  // Three-layer disable signal, in priority order:
+  //
+  //   1. SEND_DEBOUNCE_MS round-trip window after the user dispatched
+  //      → disabled (prevents fast double-click before first server
+  //      frame arrives).
+  //   2. #hy-busy-marker contains [data-hy-streaming="1"]
+  //      → disabled (server is actively streaming).
+  //   3. Chat DOM has been *completely* idle for CHAT_IDLE_MS AND
+  //      we're past CHAT_IDLE_MIN_SINCE_SEND_MS since dispatch
+  //      → soft override: force-clear the marker and enable. Safety
+  //      net for "the server's IDLE marker frame was lost on the
+  //      wire".
+  let busyStartedAt = 0;
+  let lastChatMutationAt = 0;
+
+  function syncSendButtonState() {
+    const marker = streamMarkerPresent();
+    const now = performance.now();
+
+    if (marker) {
+      // First server frame has arrived — stop relying on the dispatch
+      // timer and hand over to the marker as the source of truth.
+      awaitingFirstFrame = false;
+      if (busyStartedAt === 0) busyStartedAt = now;
+
+      const sinceSend = now - lastSendAt;
+      const sinceMutation = now - lastChatMutationAt;
+      if (
+        lastSendAt > 0 &&
+        sinceSend > CHAT_IDLE_MIN_SINCE_SEND_MS &&
+        sinceMutation > CHAT_IDLE_MS
+      ) {
+        console.warn(
+          "[hy] Marker stuck while chat DOM idle for",
+          (sinceMutation / 1000).toFixed(1),
+          "s — force-clearing (server IDLE frame likely lost)."
+        );
+        document.querySelectorAll(STREAM_MARKER_SELECTOR).forEach((el) => {
+          el.removeAttribute("data-hy-streaming");
+        });
+        busyStartedAt = 0;
+        setSendDisabled(false);
+        return;
+      }
+
+      if (now - busyStartedAt > ABSOLUTE_BUSY_TIMEOUT_MS) {
+        console.warn(
+          "[hy] Stream marker stuck >",
+          ABSOLUTE_BUSY_TIMEOUT_MS / 1000,
+          "s — force-enabling Send."
+        );
+        document.querySelectorAll(STREAM_MARKER_SELECTOR).forEach((el) => {
+          el.removeAttribute("data-hy-streaming");
+        });
+        busyStartedAt = 0;
+        setSendDisabled(false);
+        return;
+      }
+
+      setSendDisabled(true);
+      return;
+    }
+
+    busyStartedAt = 0;
+
+    // Marker is idle. We may still be waiting for the FIRST frame after
+    // a freshly-dispatched send: keep the button disabled so a second
+    // click can't slip through during the initial request round-trip.
+    if (awaitingFirstFrame) {
+      // If the marker host explicitly contains the IDLE marker, the
+      // server has already responded — typically a short-circuit path
+      // like the functions-JSON validation failure in send_message,
+      // which yields HY_IDLE_HTML without ever yielding HY_BUSY_HTML.
+      // Without this branch, awaitingFirstFrame would stay set until
+      // FIRST_FRAME_TIMEOUT_MS (30s), causing the next Enter/click to
+      // wrongly trigger the "model is busy" toast.
+      if (idleMarkerPresent()) {
+        awaitingFirstFrame = false;
+      } else if (now - lastSendAt > FIRST_FRAME_TIMEOUT_MS) {
+        console.warn(
+          "[hy] First-frame timeout — re-enabling Send (request likely failed)."
+        );
+        awaitingFirstFrame = false;
+        setSendDisabled(false);
+        return;
+      } else {
+        setSendDisabled(true);
+        return;
+      }
+    }
+
+    if (now - lastSendAt < SEND_DEBOUNCE_MS) {
+      setSendDisabled(true);
+      return;
+    }
+    setSendDisabled(false);
+  }
+
+  function installBusyGuard() {
+    const sendBtn = document.querySelector("#send-btn");
+    const textarea = document.querySelector(".msg-input textarea");
+    const markerHost = document.getElementById(BUSY_MARKER_HOST_ID);
+    const chatEl = document.querySelector(CHAT_SELECTOR);
+    if (!sendBtn || !textarea || !markerHost || !chatEl) {
+      setTimeout(installBusyGuard, 500);
+      return;
+    }
+
+    // Track chat DOM activity for the soft watchdog above. ANY mutation
+    // refreshes the timestamp — including post-stream KaTeX/highlight
+    // injection — because if anything is still rendering the streaming
+    // MIGHT not be over yet. The watchdog only fires after a long quiet
+    // period.
+    lastChatMutationAt = performance.now();
+    subscribeChatMutations(() => {
+      lastChatMutationAt = performance.now();
+    });
+
+    // Block clicks while busy. Capture phase + stopImmediatePropagation
+    // ensures Gradio's own bubble-phase click handler never sees the
+    // event when we want to reject it.
+    //
+    // CRITICAL: in the NOT-busy path we do NOT call setSendDisabled(true)
+    // here. Gradio's Svelte Button checks ``this.disabled`` inside its
+    // own click handler that runs AFTER ours; if we flip the disabled
+    // attribute synchronously in capture, the actual send request is
+    // silently swallowed.
+    // Disable the Send button on the NEXT tick (after Gradio's own
+    // bubble-phase click handler has run and dispatched the request).
+    // We can't disable synchronously in capture or Gradio's Svelte
+    // Button checks ``this.disabled`` and silently swallows the send.
+    function lockSendAfterDispatch() {
+      setTimeout(() => {
+        setSendDisabled(true);
+      }, 0);
+    }
+
+    sendBtn.addEventListener(
+      "click",
+      (e) => {
+        if (isModelBusy()) {
+          e.preventDefault();
+          e.stopImmediatePropagation();
+          e.stopPropagation();
+          showBusyToast();
+          return;
+        }
+        lastSendAt = performance.now();
+        awaitingFirstFrame = true;
+        justSentNewMessage = true;
+        lockSendAfterDispatch();
+      },
+      true
+    );
+
+    // Same logic for Enter-to-submit on the textarea. Gradio's
+    // Textbox.submit fires regardless of the Send button's disabled
+    // state, so we ALSO need this gate.
+    textarea.addEventListener(
+      "keydown",
+      (e) => {
+        if (e.key !== "Enter" || e.shiftKey || e.isComposing) return;
+        if (isModelBusy()) {
+          e.preventDefault();
+          e.stopImmediatePropagation();
+          e.stopPropagation();
+          showBusyToast();
+          return;
+        }
+        lastSendAt = performance.now();
+        awaitingFirstFrame = true;
+        justSentNewMessage = true;
+        lockSendAfterDispatch();
+      },
+      true
+    );
+
+    // Drive the busy state from mutations of the dedicated marker host.
+    // Tiny subtree (one component, one inner span at most) so this is
+    // essentially free.
+    new MutationObserver(syncSendButtonState).observe(markerHost, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+      attributes: true,
+      attributeFilter: ["data-hy-streaming", "data-hy-busy"],
+    });
+
+    // Slow heartbeat in case the MutationObserver misses something.
+    setInterval(syncSendButtonState, 500);
+
+    // Initial sync.
+    syncSendButtonState();
+  }
+
+  /* ── Follow-the-tail scroller ─────────────────────────────────────────── */
+  // Design (simple & robust):
+  //   * ``follow`` mirrors "user is currently near the bottom of the
+  //     chat". It is updated on EVERY scroll event — both user-driven
+  //     and programmatic — because after our own ``scrollToBottom`` the
+  //     position IS at the bottom, so follow stays true automatically.
+  //   * When the user scrolls UP, the very next scroll event flips
+  //     follow to false; subsequent mutations don't re-pin the view.
+  //   * When the user is actively scrolling (wheel / touchmove /
+  //     scroll-key) we briefly pause programmatic scrolling so we don't
+  //     fight their fingers; once they let go (no gesture for
+  //     USER_QUIET_MS) auto-follow resumes if they ended near bottom.
+  //   * Two redundant triggers ensure we never miss a delta: the global
+  //     chat MutationObserver AND the explicit ``hy-chat:updated``
+  //     custom event dispatched by static/chat.js after each delta is
+  //     applied.
+  function installScrollLock() {
+    const chatEl = document.querySelector(CHAT_SELECTOR);
+    if (!chatEl) {
+      setTimeout(installScrollLock, 500);
+      return;
+    }
+
+    const NEAR_BOTTOM_PX = 100;
+    const USER_QUIET_MS = 120;
+
+    let scrollable = null;
+    let follow = true;
+    let lastUserGestureAt = 0;
+
+    function markUserGesture() {
+      lastUserGestureAt = performance.now();
+    }
+    window.addEventListener("wheel", markUserGesture, {
+      passive: true,
+      capture: true,
+    });
+    window.addEventListener("touchmove", markUserGesture, {
+      passive: true,
+      capture: true,
+    });
+    const SCROLL_KEYS = new Set([
+      "ArrowUp",
+      "ArrowDown",
+      "PageUp",
+      "PageDown",
+      "Home",
+      "End",
+      "Space",
+      " ",
+    ]);
+    window.addEventListener(
+      "keydown",
+      (e) => {
+        if (SCROLL_KEYS.has(e.key)) markUserGesture();
+      },
+      { capture: true }
+    );
+
+    function isNearBottom(el) {
+      return el.scrollHeight - el.scrollTop - el.clientHeight < NEAR_BOTTOM_PX;
+    }
+
+    function onScroll() {
+      if (!scrollable) return;
+      // Always reflect the current viewport state. After programmatic
+      // scrollToBottom the position IS at the bottom, so follow=true.
+      // After user scrolls up, follow flips to false on the very next
+      // scroll event. Simple and self-correcting.
+      follow = isNearBottom(scrollable);
+    }
+
+    function scrollToBottom() {
+      if (!scrollable) return;
+      // Don't fight an active user gesture. Once they stop (>120ms of
+      // silence) we'll catch up on the very next mutation OR custom
+      // event — both of which fire for every streamed delta.
+      if (performance.now() - lastUserGestureAt < USER_QUIET_MS) return;
+      const target = scrollable.scrollHeight - scrollable.clientHeight;
+      if (target > scrollable.scrollTop) scrollable.scrollTop = target;
+    }
+
+    function findScrollable() {
+      // Our chat element IS itself the scrollable container (see
+      // _chat.css). Attach to it eagerly even before content overflows
+      // so we catch the first scroll event the moment overflow appears.
+      const s = getComputedStyle(chatEl);
+      if (s.overflowY === "auto" || s.overflowY === "scroll") return chatEl;
+      // Fallback for unexpected layouts: walk the subtree.
+      const candidates = chatEl.querySelectorAll("*");
+      for (const el of candidates) {
+        const cs = getComputedStyle(el);
+        if (cs.overflowY === "auto" || cs.overflowY === "scroll") {
+          if (el.scrollHeight > el.clientHeight + 4) return el;
+        }
+      }
+      return chatEl;
+    }
+
+    function attach(el) {
+      if (scrollable === el) return;
+      if (scrollable) scrollable.removeEventListener("scroll", onScroll);
+      scrollable = el;
+      el.addEventListener("scroll", onScroll, { passive: true });
+      if (follow) scrollToBottom();
+    }
+
+    // Attach immediately — chat.js may not have any content yet but the
+    // element exists, so we can already wire the scroll listener.
+    attach(findScrollable());
+
+    function tick() {
+      if (justSentNewMessage) {
+        follow = true;
+        justSentNewMessage = false;
+      }
+      if (!scrollable || !document.contains(scrollable)) {
+        attach(findScrollable());
+      }
+      if (scrollable && follow) {
+        scrollToBottom();
+      }
+    }
+
+    // Trigger 1: the global chat MutationObserver hub. Catches every
+    // DOM change under #hy-chat (delta-driven appends, frozen flush,
+    // streaming innerHTML swaps, post-stream highlight injection).
+    subscribeChatMutations(tick);
+
+    // Trigger 2: the explicit ``hy-chat:updated`` event dispatched by
+    // static/chat.js at the end of every applyDelta. Belt-and-braces
+    // in case some pathological mutation pattern slips past the rAF
+    // batcher above.
+    chatEl.addEventListener("hy-chat:updated", tick);
+
+    // Trigger 3: window resize can change clientHeight which makes the
+    // previous "at bottom" position no longer at bottom. Re-pin.
+    window.addEventListener("resize", () => {
+      if (scrollable && follow) scrollToBottom();
+    });
+  }
+
+  /* ── kick off ─────────────────────────────────────────────────────────── */
+  function bootstrap() {
+    const chatEl = document.querySelector(CHAT_SELECTOR);
+    if (!chatEl) {
+      // chat.js renders #hy-chat into the gr.HTML wrapper; until that
+      // happens we can't install observers. Retry until ready —
+      // subsystems below all guard for the same node themselves but
+      // the mutation hub MUST be running before they install their
+      // subscribers — otherwise early mutations would be missed.
+      setTimeout(bootstrap, 200);
+      return;
+    }
+    startChatMutationHub(chatEl);
+    createOverlay();
+    watchForHtmlBlocks();
+    installScrollLock();
+    installBusyGuard();
+  }
+  setTimeout(bootstrap, 800);
+})();

static/chat.js

@@ -0,0 +1,688 @@
+/* eslint-disable */
+/**
+ * Hy3 custom chat renderer.
+ *
+ * The DOM under ``#hy-chat`` is owned exclusively by this module —
+ * nothing in Gradio touches it. The server pushes JSON deltas via the
+ * hidden ``#hy-chat-delta`` ``gr.HTML`` component; we observe its
+ * mutations, parse, and apply each op to the chat container.
+ *
+ * Design notes
+ * ────────────
+ *   1. Append-only DOM. Each new bubble is its own ``.message-row``.
+ *      The browser's per-row layout/paint isolation (``contain`` +
+ *      ``content-visibility`` from ``_perf.css``) keeps rendering cost
+ *      O(visible) regardless of conversation length.
+ *
+ *   2. Frozen / streaming split inside each assistant bubble. As content
+ *      streams in, every paragraph (or fenced code / display math) that
+ *      has CLOSED gets rendered ONCE into a stable ``.hy-frozen`` DOM
+ *      subtree and never touched again — KaTeX, ``marked``, and the
+ *      syntax highlighter all run exactly once per closed block. Only
+ *      the trailing in-progress paragraph re-renders on each delta,
+ *      and that block is small. As a result already-rendered formulas
+ *      never flicker / re-layout mid-stream.
+ *
+ *   3. Wire payload is ~just the new characters. A 100-char delta is
+ *      ~150 bytes on the wire, so WebSocket back-pressure essentially
+ *      goes away.
+ *
+ * Op contract — keep in sync with chat.py:
+ *
+ *   {type: "reset"}
+ *   {type: "user", text: "..."}
+ *   {type: "assistant_begin", id: "a-N"}
+ *   {type: "reasoning_delta", id: "a-N", delta: "..."}
+ *   {type: "content_delta",   id: "a-N", delta: "...", thinking_done?: bool}
+ *   {type: "assistant_end",   id: "a-N"}
+ *   {type: "tool_call",       id: "a-N", markdown: "..."}
+ *   {type: "remove_bubble",   id: "a-N"}
+ */
+(() => {
+  if (window.__HY_CHAT_INIT) return;
+  window.__HY_CHAT_INIT = true;
+
+  // ─── State ─────────────────────────────────────────────────────────────
+  const state = {
+    host: null,            // <div id="hy-chat">
+    bubbles: new Map(),    // bubble_id -> bubble record (see ensureBubble)
+    lastSeq: 0,            // de-dup gate against re-fires of the same payload
+    // Current chat epoch — bumped server-side every time the user clicks
+    // "+" / new_chat. Each delta payload carries the epoch it was
+    // produced under; deltas whose epoch doesn't match ours are dropped
+    // (they're tail bytes from a stream the user already abandoned).
+    // Initialised lazily from the first payload that arrives so legacy
+    // payloads without an epoch field still apply.
+    currentEpoch: null,
+  };
+
+  // ─── DOM helpers ───────────────────────────────────────────────────────
+  function ensureHost() {
+    if (state.host && document.contains(state.host)) return state.host;
+    state.host = document.getElementById("hy-chat");
+    return state.host;
+  }
+
+  function escapeHtml(s) {
+    return String(s)
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#39;");
+  }
+
+  // ─── Markdown + math renderer ──────────────────────────────────────────
+  // We DELIBERATELY do not sanitize here. The rest of the app depends
+  // on the model being able to emit raw HTML (e.g.
+  // <details class="thinking-block">, the HTML-preview workflow on raw
+  // HTML code blocks). The model is trusted output for this product
+  // surface; if that ever changes, swap marked for a sanitizing parser
+  // like markdown-it + DOMPurify.
+  const MARKED_OPTS = { gfm: true, breaks: false };
+
+  const KATEX_DELIMS = [
+    { left: "$$", right: "$$", display: true },
+    { left: "$", right: "$", display: false },
+    // We pre-convert \[…\] / \(…\) → $$…$$ / $…$ via normalizeMathDelims
+    // BEFORE marked.parse runs (see below) — so the auto-render scan
+    // never needs to worry about them. They are NOT listed here on
+    // purpose: marked treats ``\[`` and ``\(`` as backslash escapes
+    // and silently drops the leading ``\`` in the rendered HTML, so by
+    // the time KaTeX scans the DOM the original bracket delimiters are
+    // already gone. Pre-conversion is the only reliable fix.
+  ];
+
+  // ─── Math handling: two-stage pipeline ────────────────────────────────
+  //
+  // The model emits LaTeX in any of four delimiter styles: ``$$…$$``,
+  // ``\[…\]``, ``$…$``, ``\(…\)``. We need KaTeX (via auto-render) to
+  // pick all of them up while still letting ``marked.parse`` handle the
+  // surrounding markdown.
+  //
+  // Two problems block the naïve approach:
+  //
+  //   1. ``marked`` treats ``\[``, ``\]``, ``\(``, ``\)`` as backslash
+  //      escapes and silently drops the ``\``. By the time KaTeX scans
+  //      the rendered HTML the bracket delimiters are gone.
+  //
+  //   2. Even inside ``$$…$$``, ``marked`` strips backslashes before
+  //      ``\{``, ``\}``, ``\_``, etc. — so things like ``\{(0:0:1:0)\}``
+  //      lose their literal-brace escapes and KaTeX renders an empty
+  //      group instead of the intended literal braces.
+  //
+  // The fix is two passes that together keep marked away from the math
+  // content:
+  //
+  //   Stage A — ``normalizeMathDelims`` converts ``\[/\]`` → ``$$`` and
+  //   ``\(/\)`` → ``$`` OUTSIDE fenced/inline code blocks. After this
+  //   pass every math region is delimited with dollars.
+  //
+  //   Stage B — ``protectMath`` extracts every ``$$…$$`` / ``$…$`` from
+  //   the text and replaces it with a unique placeholder token (a NUL
+  //   character that ``marked`` will leave alone). After ``marked.parse``
+  //   we substitute the original math source back in. ``ignoredTags``
+  //   already keeps KaTeX out of ``<pre>``/``<code>``, so the only
+  //   regions that end up containing dollars in the rendered HTML are
+  //   the math ones — exactly what we want.
+  //
+  // The placeholder uses NUL as a delimiter because ``marked`` cannot
+  // produce a literal NUL on its own (every input source we'd see is
+  // valid Unicode text without NULs), so the ``restoreMath`` regex is
+  // unambiguous.
+  function normalizeMathDelims(text) {
+    if (!text) return text;
+    let out = "";
+    let i = 0;
+    const n = text.length;
+    while (i < n) {
+      const ch = text[i];
+
+      // Triple-backtick or triple-tilde fenced block — passthrough until
+      // matching closing fence on its own (or anywhere on a) line.
+      if ((ch === "`" && text.startsWith("```", i)) ||
+          (ch === "~" && text.startsWith("~~~", i))) {
+        const marker = text.substr(i, 3);
+        out += marker;
+        i += 3;
+        const close = text.indexOf(marker, i);
+        if (close < 0) {
+          // Unclosed fence — emit rest verbatim and stop.
+          out += text.slice(i);
+          return out;
+        }
+        out += text.slice(i, close + 3);
+        i = close + 3;
+        continue;
+      }
+
+      // Inline code: single or double backticks, ended by the same run
+      // length. Common case is a single backtick.
+      if (ch === "`") {
+        let runLen = 1;
+        while (i + runLen < n && text[i + runLen] === "`") runLen++;
+        const open = text.substr(i, runLen);
+        out += open;
+        i += runLen;
+        const close = text.indexOf(open, i);
+        if (close < 0) {
+          out += text.slice(i);
+          return out;
+        }
+        out += text.slice(i, close + runLen);
+        i = close + runLen;
+        continue;
+      }
+
+      // Backslash-bracket / backslash-paren delimiters. Must be the
+      // FIRST conversion check after the code-fence skip so we don't
+      // mistake e.g. ``\[`` inside a code fence for math.
+      if (ch === "\\") {
+        if (text[i + 1] === "[") { out += "$$"; i += 2; continue; }
+        if (text[i + 1] === "]") { out += "$$"; i += 2; continue; }
+        if (text[i + 1] === "(") { out += "$";  i += 2; continue; }
+        if (text[i + 1] === ")") { out += "$";  i += 2; continue; }
+      }
+
+      out += ch;
+      i++;
+    }
+    return out;
+  }
+
+  // Inline math regex requires the opening ``$`` to be IMMEDIATELY
+  // followed by a non-space, non-``$`` char (avoids matching prices like
+  // ``I have $5 and $10``) and the closing ``$`` to be IMMEDIATELY
+  // preceded by a non-space, non-``$`` char. Display math (``$$…$$``)
+  // is matched first (the alternative is left-most-greedy in a JS
+  // regex, but with non-greedy bodies and ``$$`` being a longer prefix
+  // it wins ties naturally).
+  const MATH_RE = /\$\$[\s\S]+?\$\$|\$(?=[^\s$])[^\n$]*?(?<=[^\s$])\$/g;
+
+  function protectMath(text) {
+    const stash = [];
+    const escaped = text.replace(MATH_RE, (m) => {
+      const idx = stash.length;
+      stash.push(m);
+      return `\u0000M${idx}\u0000`;
+    });
+    return { escaped, stash };
+  }
+
+  function restoreMath(html, stash) {
+    if (!stash.length) return html;
+    return html.replace(/\u0000M(\d+)\u0000/g, (_, n) => stash[+n]);
+  }
+
+  function renderMarkdownInto(el, text) {
+    if (!text) {
+      el.innerHTML = "";
+      return;
+    }
+    const normalized = normalizeMathDelims(text);
+    const { escaped, stash } = protectMath(normalized);
+    const rawMd = (window.marked && window.marked.parse)
+      ? window.marked.parse(escaped, MARKED_OPTS)
+      : escapeHtml(escaped);
+    el.innerHTML = restoreMath(rawMd, stash);
+
+    // Math
+    if (window.renderMathInElement) {
+      try {
+        window.renderMathInElement(el, {
+          delimiters: KATEX_DELIMS,
+          throwOnError: false,
+          // Skip math-detection inside elements that should never contain
+          // math (matches KaTeX auto-render defaults).
+          ignoredTags: ["script", "noscript", "style", "textarea", "pre", "code"],
+        });
+      } catch (err) {
+        console.warn("[hy-chat] katex render error:", err);
+      }
+    }
+
+    // Syntax highlighting (idempotent if hljs not loaded yet)
+    if (window.hljs && window.hljs.highlightElement) {
+      const codes = el.querySelectorAll("pre code");
+      for (let i = 0; i < codes.length; i++) {
+        const c = codes[i];
+        if (c.dataset.hljsDone) continue;
+        try {
+          window.hljs.highlightElement(c);
+        } catch (err) {
+          // hljs throws if the language is unknown — harmless, ignore.
+        }
+        c.dataset.hljsDone = "1";
+      }
+    }
+  }
+
+  // ─── Frozen / streaming split ──────────────────────────────────────────
+  // Find the highest "safe" boundary in the current content buffer up to
+  // which we can freeze the rendered DOM and never touch it again. A
+  // boundary is safe iff the markdown above it forms a complete set of
+  // top-level blocks — i.e. we are NOT inside an open fenced code block
+  // (``` / ~~~), display math ($$), or LaTeX env (\begin{…}).
+  //
+  // Returns the index in ``text`` immediately after the last safe block
+  // separator (\n\n).
+  function findFreezeBoundary(text) {
+    const len = text.length;
+    let i = 0;
+    let inFence = false;       // inside ``` … ``` or ~~~ … ~~~
+    let fenceMarker = null;
+    let inMath = false;        // inside $$ … $$
+    let inEnv = false;         // inside \begin{…} … \end{…}
+    let lastSafe = 0;
+
+    while (i < len) {
+      const ch = text[i];
+
+      // Fence detection (must check before single-char paths)
+      if (!inMath && !inEnv) {
+        if (ch === "`" && text.startsWith("```", i)) {
+          if (!inFence) { inFence = true; fenceMarker = "```"; }
+          else if (fenceMarker === "```") { inFence = false; fenceMarker = null; }
+          i += 3;
+          continue;
+        }
+        if (ch === "~" && text.startsWith("~~~", i)) {
+          if (!inFence) { inFence = true; fenceMarker = "~~~"; }
+          else if (fenceMarker === "~~~") { inFence = false; fenceMarker = null; }
+          i += 3;
+          continue;
+        }
+      }
+
+      if (inFence) { i++; continue; }
+
+      // Display math $$ … $$
+      if (!inEnv && ch === "$" && text[i + 1] === "$") {
+        inMath = !inMath;
+        i += 2;
+        continue;
+      }
+
+      if (inMath) { i++; continue; }
+
+      // \begin{env} … \end{env}
+      if (ch === "\\") {
+        if (text.startsWith("\\begin{", i)) { inEnv = true; i += 7; continue; }
+        if (text.startsWith("\\end{", i))   { inEnv = false; i += 5; continue; }
+      }
+
+      if (inEnv) { i++; continue; }
+
+      // Paragraph break outside any block — candidate freeze point.
+      if (ch === "\n" && text[i + 1] === "\n") {
+        // Skip past the entire run of blank lines so we don't freeze
+        // mid-blank-paragraph.
+        let j = i + 2;
+        while (j < len && (text[j] === "\n" || text[j] === " " || text[j] === "\t")) j++;
+        lastSafe = j;
+        i = j;
+        continue;
+      }
+
+      i++;
+    }
+
+    return lastSafe;
+  }
+
+  // ─── Bubble lifecycle ──────────────────────────────────────────────────
+  function ensureBubble(id) {
+    return state.bubbles.get(id);
+  }
+
+  function createAssistantBubble(id) {
+    const row = document.createElement("div");
+    row.className = "message-row bot-row";
+    row.dataset.testid = "bot";
+    row.dataset.role = "assistant";
+    row.dataset.bubbleId = id;
+
+    const msg = document.createElement("div");
+    msg.className = "message bot";
+
+    const md = document.createElement("div");
+    md.className = "markdown hy-markdown";
+
+    const typing = document.createElement("div");
+    typing.className = "typing-indicator hy-typing";
+    typing.innerHTML = "<span></span><span></span><span></span>";
+    md.appendChild(typing);
+
+    msg.appendChild(md);
+    row.appendChild(msg);
+    state.host.appendChild(row);
+
+    const record = {
+      row, md, typing,
+      // Reasoning (optional, lazily created)
+      reasoningEl: null,
+      reasoningSummaryEl: null,
+      reasoningBodyEl: null,
+      reasoningBuf: "",
+      thinkingDone: false,
+      // Content (lazily created on first content_delta)
+      frozenEl: null,
+      streamingEl: null,
+      contentBuf: "",
+      frozenLen: 0,
+      // Tool-call append region (lazily created)
+      toolCallContainer: null,
+      ended: false,
+    };
+    state.bubbles.set(id, record);
+    return record;
+  }
+
+  function ensureReasoning(b) {
+    if (b.reasoningEl) return;
+    const det = document.createElement("details");
+    det.className = "thinking-block";
+    det.open = true;
+    const sum = document.createElement("summary");
+    sum.textContent = (window.HY_I18N && window.HY_I18N.thinking) || "Thinking...";
+    det.appendChild(sum);
+    const body = document.createElement("div");
+    body.className = "hy-reasoning-body";
+    body.style.whiteSpace = "pre-wrap";
+    body.style.wordBreak = "break-word";
+    det.appendChild(body);
+    b.reasoningEl = det;
+    b.reasoningSummaryEl = sum;
+    b.reasoningBodyEl = body;
+    if (b.typing && b.typing.parentNode) b.typing.remove();
+    // Reasoning always goes ABOVE content, even if content has already
+    // started rendering (rare — most models stream reasoning first).
+    b.md.insertBefore(det, b.md.firstChild);
+  }
+
+  function ensureContent(b) {
+    if (b.frozenEl) return;
+    if (b.typing && b.typing.parentNode) b.typing.remove();
+    const frozen = document.createElement("div");
+    frozen.className = "hy-frozen";
+    const streaming = document.createElement("div");
+    streaming.className = "hy-streaming";
+    b.md.appendChild(frozen);
+    b.md.appendChild(streaming);
+    b.frozenEl = frozen;
+    b.streamingEl = streaming;
+  }
+
+  function markThinkingDone(b) {
+    if (!b.reasoningEl || b.thinkingDone) return;
+    b.thinkingDone = true;
+    b.reasoningSummaryEl.textContent =
+      (window.HY_I18N && window.HY_I18N.thinking_done) || "Thought";
+    b.reasoningEl.open = false;
+  }
+
+  // ─── Op handlers ───────────────────────────────────────────────────────
+  function opReset() {
+    state.host.innerHTML = "";
+    state.bubbles.clear();
+    state.lastSeq = 0;
+    // currentEpoch is updated by applyDelta BEFORE op dispatch when a
+    // reset op is in the payload — see the epoch handling there. We
+    // intentionally do NOT clear it here, otherwise we'd reopen the
+    // window for stale post-reset deltas.
+  }
+
+  function opUser(op) {
+    const row = document.createElement("div");
+    row.className = "message-row user-row";
+    row.dataset.testid = "user";
+    row.dataset.role = "user";
+
+    const msg = document.createElement("div");
+    msg.className = "message user user-message";
+
+    const md = document.createElement("div");
+    md.className = "markdown hy-markdown hy-user-text";
+    // Render as plain text — never run user input through marked / KaTeX.
+    md.style.whiteSpace = "pre-wrap";
+    md.style.wordBreak = "break-word";
+    md.textContent = op.text || "";
+
+    msg.appendChild(md);
+    row.appendChild(msg);
+    state.host.appendChild(row);
+  }
+
+  function opAssistantBegin(op) {
+    if (state.bubbles.has(op.id)) return; // idempotent on retry
+    createAssistantBubble(op.id);
+  }
+
+  function opReasoningDelta(op) {
+    let b = ensureBubble(op.id);
+    if (!b) b = createAssistantBubble(op.id);
+    ensureReasoning(b);
+    const d = op.delta || "";
+    if (!d) return;
+    b.reasoningBuf += d;
+    // Reasoning is shown as raw text — fast and never re-renders math.
+    // Append-only via textContent means even very long reasoning stays
+    // O(delta) per update; the DOM tree is just a single text node.
+    b.reasoningBodyEl.textContent = b.reasoningBuf;
+    // Keep the latest reasoning line visible inside the (max-height-
+    // scrollable) details body.
+    b.reasoningBodyEl.scrollTop = b.reasoningBodyEl.scrollHeight;
+  }
+
+  function opContentDelta(op) {
+    let b = ensureBubble(op.id);
+    if (!b) b = createAssistantBubble(op.id);
+    if (op.thinking_done) markThinkingDone(b);
+    ensureContent(b);
+    const d = op.delta || "";
+    if (!d) return;
+    b.contentBuf += d;
+
+    // Compute new freeze boundary. If it advanced past the last frozen
+    // length, render JUST the newly-frozen chunk (text since last
+    // boundary) ONCE and APPEND its DOM to the frozen container. The
+    // already-frozen DOM is never touched — KaTeX, hljs, and marked
+    // run exactly once per closed block.
+    //
+    // Why we can render the new chunk in isolation: the boundary is
+    // always at a paragraph break (\n\n) outside any open code fence /
+    // display math / LaTeX env, so each chunk is a complete set of
+    // top-level markdown blocks that ``marked`` parses identically
+    // whether or not it has the prior context.
+    const text = b.contentBuf;
+    const newBoundary = findFreezeBoundary(text);
+    if (newBoundary > b.frozenLen) {
+      const newChunk = text.slice(b.frozenLen, newBoundary);
+      const temp = document.createElement("div");
+      renderMarkdownInto(temp, newChunk);
+      // Move children from temp into frozenEl. Moving (not cloning)
+      // preserves the KaTeX/hljs work we just did, and crucially does
+      // NOT re-trigger any rendering of the already-frozen DOM.
+      while (temp.firstChild) {
+        b.frozenEl.appendChild(temp.firstChild);
+      }
+      b.frozenLen = newBoundary;
+    }
+    // Streaming segment (everything after the boundary) is re-rendered
+    // in full on each delta. It's bounded to roughly one paragraph, so
+    // the KaTeX / marked / hljs work is O(paragraph) — and since
+    // ``innerHTML = ...`` wipes the previous DOM, KaTeX never
+    // double-renders the same formula here either.
+    const streamingText = text.slice(b.frozenLen);
+    renderMarkdownInto(b.streamingEl, streamingText);
+  }
+
+  function opAssistantEnd(op) {
+    const b = ensureBubble(op.id);
+    if (!b) return;
+    b.ended = true;
+    if (b.typing && b.typing.parentNode) b.typing.remove();
+    // Final flush: take whatever is still in the streaming segment and
+    // append it to the frozen container as one last chunk, then empty
+    // streaming. Crucially we do NOT re-render the already-frozen DOM
+    // — that would re-run KaTeX over every formula the user has been
+    // looking at and produce a final visible flicker.
+    if (b.contentBuf) {
+      ensureContent(b);
+      const tail = b.contentBuf.slice(b.frozenLen);
+      if (tail) {
+        const temp = document.createElement("div");
+        renderMarkdownInto(temp, tail);
+        while (temp.firstChild) {
+          b.frozenEl.appendChild(temp.firstChild);
+        }
+      }
+      b.frozenLen = b.contentBuf.length;
+      b.streamingEl.innerHTML = "";
+    } else if (b.streamingEl) {
+      // No content at all (might be tool-call only) — clean up.
+      b.streamingEl.innerHTML = "";
+    }
+    if (b.reasoningEl && !b.thinkingDone) markThinkingDone(b);
+  }
+
+  function opToolCall(op) {
+    let b = ensureBubble(op.id);
+    if (!b) b = createAssistantBubble(op.id);
+    if (b.typing && b.typing.parentNode) b.typing.remove();
+    if (!b.toolCallContainer) {
+      const c = document.createElement("div");
+      c.className = "hy-tool-calls";
+      b.md.appendChild(c);
+      b.toolCallContainer = c;
+    }
+    const tc = document.createElement("div");
+    tc.className = "hy-tool-call";
+    renderMarkdownInto(tc, op.markdown || "");
+    b.toolCallContainer.appendChild(tc);
+  }
+
+  function opRemoveBubble(op) {
+    const b = ensureBubble(op.id);
+    if (!b) return;
+    if (b.row && b.row.parentNode) b.row.parentNode.removeChild(b.row);
+    state.bubbles.delete(op.id);
+  }
+
+  function applyOp(op) {
+    if (!op || !op.type) return;
+    if (!ensureHost()) return;
+    switch (op.type) {
+      case "reset":           opReset(); break;
+      case "user":            opUser(op); break;
+      case "assistant_begin": opAssistantBegin(op); break;
+      case "reasoning_delta": opReasoningDelta(op); break;
+      case "content_delta":   opContentDelta(op); break;
+      case "assistant_end":   opAssistantEnd(op); break;
+      case "tool_call":       opToolCall(op); break;
+      case "remove_bubble":   opRemoveBubble(op); break;
+      default:
+        console.warn("[hy-chat] unknown op type:", op.type);
+    }
+  }
+
+  function applyDelta(payload) {
+    if (!payload || typeof payload !== "object") return;
+    const seq = typeof payload.seq === "number" ? payload.seq : null;
+    // Dedup: Gradio occasionally re-fires the same component value on
+    // reconnect. Since each delta has a fresh global seq, anything ≤
+    // lastSeq is a re-fire we've already applied.
+    if (seq !== null && seq <= state.lastSeq) return;
+    if (seq !== null) state.lastSeq = seq;
+    const ops = Array.isArray(payload.ops) ? payload.ops : [];
+
+    // ── Stale-epoch drop ────────────────────────────────────────────
+    // The user clicked "+" mid-stream. The reset payload carries a NEW
+    // epoch; we adopt it and apply the reset. Any later payload from
+    // the cancelled generator still carries the OLD epoch and is
+    // dropped here — without this, late content_delta ops would
+    // ``createAssistantBubble`` for the old bubble id and a ghost
+    // bubble would appear in the freshly-cleared chat.
+    const epoch = payload.epoch;
+    if (epoch !== undefined && epoch !== null) {
+      const hasReset = ops.some((op) => op && op.type === "reset");
+      if (hasReset) {
+        state.currentEpoch = epoch;
+      } else if (state.currentEpoch === null) {
+        // First payload of the session: adopt whatever epoch we see.
+        state.currentEpoch = epoch;
+      } else if (epoch !== state.currentEpoch) {
+        return;
+      }
+    }
+
+    for (let i = 0; i < ops.length; i++) {
+      try {
+        applyOp(ops[i]);
+      } catch (err) {
+        console.error("[hy-chat] op failed:", ops[i], err);
+      }
+    }
+    // Notify subscribers (the scroll lock and code-block injector in
+    // app.js) that the chat DOM changed. We dispatch a single CustomEvent
+    // per applied delta — coarser than per-op so subscribers can do their
+    // own coalescing on top.
+    if (state.host) {
+      state.host.dispatchEvent(new CustomEvent("hy-chat:updated", {
+        bubbles: false,
+      }));
+    }
+  }
+
+  // ─── Wire up the delta channel ───────────────────────────────────────��─
+  function startDeltaObserver() {
+    const deltaHost = document.getElementById("hy-chat-delta");
+    if (!deltaHost) {
+      setTimeout(startDeltaObserver, 200);
+      return;
+    }
+    let lastValue = "";
+    function handle() {
+      // Gradio may put the value in textContent or in a nested element
+      // depending on version. Walk the subtree to be defensive.
+      const v = (deltaHost.textContent || "").trim();
+      if (!v || v === lastValue) return;
+      lastValue = v;
+      let payload;
+      try {
+        payload = JSON.parse(v);
+      } catch (err) {
+        console.error("[hy-chat] bad delta JSON:", v.slice(0, 200), err);
+        return;
+      }
+      applyDelta(payload);
+    }
+    new MutationObserver(handle).observe(deltaHost, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+    handle(); // pick up initial value if any
+  }
+
+  function init() {
+    if (!ensureHost()) {
+      setTimeout(init, 200);
+      return;
+    }
+    startDeltaObserver();
+  }
+
+  // Public surface for the rest of the page (app.js).
+  window.HY_CHAT = {
+    init,
+    applyDelta,
+    getHost: ensureHost,
+  };
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", () => setTimeout(init, 200));
+  } else {
+    setTimeout(init, 200);
+  }
+})();

static/css/_chat.css

@@ -0,0 +1,144 @@
+/* ─────────────────────────────────────────────────────────────────────────
+ * Custom chat surface
+ *
+ * Layout
+ * ──────
+ *   #hy-chat-host      → the gr.HTML wrapper component. Owns the
+ *                        viewport-relative height; pure flex container.
+ *   #hy-chat           → our scrollable chat surface. Append-only DOM
+ *                        owned by static/chat.js; one .message-row per
+ *                        bubble.
+ *
+ * The rest of the file is component styling for the renderer's emitted
+ * DOM. The class names (``.message-row``, ``.message``, ``.bot``,
+ * ``.user``, ``.markdown``) are deliberately shared with the rules in
+ * _chatbot.css / _math.css / _thinking.css / _misc.css so those
+ * rulesets apply transparently to our bubbles.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+/* ── Outer wrapper: takes up the available vertical space. ─────────────
+ * We use absolute positioning on #hy-chat so it pins to all four edges
+ * of the host regardless of how many intermediate wrapper divs Gradio
+ * inserts (varies between versions). The host establishes the
+ * positioning context with ``position: relative``. */
+#hy-chat-host {
+    position: relative !important;
+    height: calc(100vh - 200px) !important;
+    padding: 0 !important;
+    margin: 0 !important;
+    background: var(--hy-bg) !important;
+    border: none !important;
+    box-shadow: none !important;
+    min-height: 0 !important;
+    overflow: hidden !important;
+}
+/* Strip styling and positioning from any wrappers Gradio inserts
+ * between #hy-chat-host and #hy-chat — they would otherwise create new
+ * containing blocks and break the absolute-positioned scroll surface. */
+#hy-chat-host > div,
+#hy-chat-host > div > div {
+    position: static !important;
+    padding: 0 !important;
+    margin: 0 !important;
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+    height: auto !important;
+}
+
+/* ── Inner scrollable surface ──────────────────────────────────────────── */
+#hy-chat {
+    position: absolute;
+    inset: 0;
+    overflow-y: auto;
+    overflow-x: hidden;
+    padding: 16px 24px 32px;
+    background: var(--hy-bg);
+    scroll-behavior: auto;  /* programmatic scroll-to-bottom should be instant */
+}
+
+/* ── Message rows ──────────────────────────────────────────────────────── */
+#hy-chat .message-row {
+    display: block;
+    width: 100%;
+    margin: 0 0 4px;
+    padding: 0;
+}
+#hy-chat .message-row.user-row {
+    /* Right-align user messages similar to Gradio's bubble layout. */
+    display: flex;
+    justify-content: flex-end;
+    margin: 12px 0 8px;
+}
+#hy-chat .message-row.bot-row {
+    margin: 0 0 18px;
+}
+
+/* ── Inner message containers ──────────────────────────────────────────── */
+#hy-chat .message {
+    max-width: 95%;
+    background: transparent;
+    border: none;
+    padding: 0;
+}
+#hy-chat .message.user {
+    background: var(--hy-bg-muted, #f5f5f7);
+    border-radius: 18px;
+    padding: 10px 18px !important;
+    max-width: min(720px, 75%);
+}
+.dark #hy-chat .message.user {
+    background: #2a2a2a;
+}
+#hy-chat .message.bot {
+    background: transparent;
+    padding: 4px 0 !important;
+}
+
+/* ── User-text appearance (no markdown rendering — pre-wrap text). ────── */
+#hy-chat .hy-user-text {
+    font-size: 15px;
+    line-height: 1.7;
+    color: var(--hy-text);
+}
+
+/* ── Frozen vs streaming segments inside the assistant bubble ──────────
+ * Both are direct children of .markdown so the existing #hy-chat .bot
+ * .markdown styling cascades into them transparently. The only thing
+ * we add here is to mark the streaming segment so future debugging or
+ * styling can target it (e.g. a subtle pulse to indicate "still
+ * generating" without flickering already-rendered formulas). */
+#hy-chat .hy-frozen,
+#hy-chat .hy-streaming {
+    display: block;
+}
+
+/* ── Tool-call display block (server-rendered Markdown HTML). ─────────── */
+#hy-chat .hy-tool-calls {
+    margin-top: 10px;
+}
+#hy-chat .hy-tool-call + .hy-tool-call {
+    margin-top: 8px;
+}
+
+/* ── Hide the delta channel completely ─────────────────────────────────
+ * The bridge component for delta JSON. Must never occupy layout, must
+ * never trap pointer / focus / scroll events — but its content has to
+ * remain readable to the JS MutationObserver that drives the renderer
+ * (so we cannot use display:none). */
+#hy-chat-delta,
+#hy-chat-delta * {
+    position: absolute !important;
+    width: 0 !important;
+    height: 0 !important;
+    margin: 0 !important;
+    padding: 0 !important;
+    border: 0 !important;
+    overflow: hidden !important;
+    clip: rect(0 0 0 0) !important;
+    clip-path: inset(50%) !important;
+    visibility: hidden !important;
+    opacity: 0 !important;
+    pointer-events: none !important;
+    user-select: none !important;
+}

static/css/_chatbot.css

@@ -0,0 +1,170 @@
+/* ── chatbot container ── */
+#hy-chat {
+    border: none !important;
+    box-shadow: none !important;
+    background: #ffffff !important;
+    --border-color-primary: transparent !important;
+    --color-accent-soft: #ffffff !important;
+    --background-fill-secondary: #ffffff !important;
+}
+.dark #hy-chat {
+    background: #171717 !important;
+    --border-color-primary: transparent !important;
+    --color-accent-soft: #1f1f1f !important;
+    --background-fill-secondary: #171717 !important;
+}
+
+/* ── message panel: uniform style for both user and bot ── */
+#hy-chat .message-row .message-bubble-border,
+#hy-chat .bot .message-bubble-border,
+#hy-chat .user .message-bubble-border,
+#hy-chat [data-testid="bot"] .message-bubble-border,
+#hy-chat [data-testid="user"] .message-bubble-border {
+    border-color: transparent !important;
+    border-width: 0 !important;
+    box-shadow: none !important;
+    outline: none !important;
+    background: #ffffff !important;
+    padding: 4px 16px 4px 0 !important;
+    max-width: 100% !important;
+}
+.dark #hy-chat .message-row .message-bubble-border,
+.dark #hy-chat .bot .message-bubble-border,
+.dark #hy-chat .user .message-bubble-border,
+.dark #hy-chat [data-testid="bot"] .message-bubble-border,
+.dark #hy-chat [data-testid="user"] .message-bubble-border {
+    background: #171717 !important;
+}
+
+/* ── remove user message bubble border (all themes) ── */
+#hy-chat .user,
+#hy-chat .user .message,
+#hy-chat .user .bubble,
+#hy-chat .user > div,
+#hy-chat [data-testid="user"],
+#hy-chat [data-testid="user"] .message,
+#hy-chat [data-testid="user"] .bubble,
+#hy-chat [data-testid="user"] > div,
+#hy-chat .message-row.user-row,
+#hy-chat .message-row.user-row > div,
+#hy-chat .user-message,
+#hy-chat .message.user {
+    border: none !important;
+    border-width: 0 !important;
+    border-color: transparent !important;
+    box-shadow: none !important;
+    outline: none !important;
+}
+#hy-chat .user .message,
+#hy-chat [data-testid="user"] .message,
+#hy-chat .user-message {
+    background: transparent !important;
+    padding: 4px 16px !important;
+}
+.dark #hy-chat .user .message,
+.dark #hy-chat [data-testid="user"] .message,
+.dark #hy-chat .user-message {
+    background: transparent !important;
+}
+
+/* ── user text: match bot text style ── */
+#hy-chat .user .markdown,
+#hy-chat .user .message-content,
+#hy-chat .user p,
+#hy-chat [data-testid="user"] .markdown,
+#hy-chat [data-testid="user"] .message-content,
+#hy-chat [data-testid="user"] p {
+    font-size: 15px !important;
+    line-height: 1.8 !important;
+    color: #222222 !important;
+    letter-spacing: 0.01em !important;
+}
+.dark #hy-chat .user .markdown,
+.dark #hy-chat .user .message-content,
+.dark #hy-chat .user p,
+.dark #hy-chat [data-testid="user"] .markdown,
+.dark #hy-chat [data-testid="user"] .message-content,
+.dark #hy-chat [data-testid="user"] p {
+    color: #e8e8e8 !important;
+}
+
+/* ── bot text styling ── */
+#hy-chat .bot .markdown,
+#hy-chat .bot .message-content,
+#hy-chat [data-testid="bot"] .markdown {
+    font-size: 15px !important;
+    line-height: 1.8 !important;
+    color: #222222 !important;
+    letter-spacing: 0.01em !important;
+}
+.dark #hy-chat .bot .markdown,
+.dark #hy-chat .bot .message-content,
+.dark #hy-chat [data-testid="bot"] .markdown {
+    color: #e8e8e8 !important;
+}
+#hy-chat .bot p { margin: 0.6em 0 !important; }
+#hy-chat .bot strong, #hy-chat .bot b {
+    font-weight: 600 !important;
+    color: #111 !important;
+}
+.dark #hy-chat .bot strong, .dark #hy-chat .bot b {
+    color: #fff !important;
+}
+#hy-chat .bot ul, #hy-chat .bot ol {
+    padding-left: 1.5em !important;
+    margin: 0.5em 0 !important;
+}
+#hy-chat .bot li {
+    margin: 0.3em 0 !important;
+    line-height: 1.8 !important;
+}
+
+/* ── headings ── */
+#hy-chat .bot h1 { font-size: 22px !important; font-weight: 700 !important; color: #111 !important; margin: 1em 0 0.5em !important; }
+#hy-chat .bot h2 { font-size: 19px !important; font-weight: 700 !important; color: #111 !important; margin: 0.9em 0 0.4em !important; }
+#hy-chat .bot h3 { font-size: 17px !important; font-weight: 600 !important; color: #111 !important; margin: 0.8em 0 0.35em !important; }
+#hy-chat .bot h4 { font-size: 15px !important; font-weight: 600 !important; color: #222 !important; margin: 0.7em 0 0.3em !important; }
+.dark #hy-chat .bot h1 { color: #f2f2f2 !important; }
+.dark #hy-chat .bot h2 { color: #ebebeb !important; }
+.dark #hy-chat .bot h3 { color: #e0e0e0 !important; }
+.dark #hy-chat .bot h4 { color: #d4d4d4 !important; }
+
+/* ── tables ── */
+#hy-chat table {
+    border-collapse: collapse !important;
+    width: auto !important;
+    margin: 1em 0 !important;
+    font-size: 14px !important;
+    line-height: 1.6 !important;
+}
+#hy-chat th, #hy-chat td {
+    border: 1px solid #e8e8e8 !important;
+    padding: 10px 20px !important;
+    text-align: left !important;
+}
+#hy-chat th {
+    background: #fafafa !important;
+    font-weight: 600 !important;
+    color: #333 !important;
+}
+#hy-chat td {
+    color: #444 !important;
+    background: #fff !important;
+}
+#hy-chat tr:hover td {
+    background: #fafcff !important;
+}
+.dark #hy-chat th, .dark #hy-chat td {
+    border-color: #2a2a2a !important;
+}
+.dark #hy-chat th {
+    background: #242424 !important;
+    color: #e0e0e0 !important;
+}
+.dark #hy-chat td {
+    color: #d0d0d0 !important;
+    background: #1c1c1c !important;
+}
+.dark #hy-chat tr:hover td {
+    background: #262626 !important;
+}

static/css/_dark.css

@@ -0,0 +1,194 @@
+/* ── Dark mode: sidebar ── */
+.dark .sidebar, .dark [class*="sidebar"] {
+    background: #1a1a1a !important;
+    border: none !important;
+    box-shadow: none !important;
+}
+.dark .sidebar h1, .dark [class*="sidebar"] h1 {
+    color: #e8e8e8 !important;
+}
+.dark .sidebar .block,
+.dark .sidebar .form,
+.dark .sidebar .panel,
+.dark .sidebar > div,
+.dark [class*="sidebar"] .block,
+.dark [class*="sidebar"] .form,
+.dark [class*="sidebar"] .panel,
+.dark [class*="sidebar"] > div {
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+}
+
+/* ── Dark mode: global inputs ── */
+.dark textarea, .dark input[type="text"] {
+    background: #2a2a2a !important;
+    color: #e8e8e8 !important;
+    border-color: #3a3a3a !important;
+}
+.dark textarea::placeholder, .dark input[type="text"]::placeholder {
+    color: #666 !important;
+}
+
+/* ── Dark mode: slider tracks ── */
+.dark .gradio-container input[type="range"]::-moz-range-progress { background-color: #6b9fff !important; }
+.dark .gradio-container input[type="range"]::-moz-range-track { background: #2a2a2a !important; }
+
+/* ── Dark mode: dropdowns ── */
+.dark select, .dark .wrap[data-testid="dropdown"] {
+    background: #2a2a2a !important;
+    color: #e8e8e8 !important;
+    border-color: #3a3a3a !important;
+}
+
+/* ── Dark mode: accordion ── */
+.dark .accordion {
+    background: #1f1f1f !important;
+    border-color: #2a2a2a !important;
+}
+
+/* ── Dark mode: forms & labels ── */
+.dark .form {
+    border-color: #2a2a2a !important;
+}
+.dark label, .dark .label-wrap {
+    color: #c0c0c0 !important;
+}
+.dark .info-text, .dark span[data-testid="block-info"] {
+    color: #808080 !important;
+}
+
+/* ── Dark mode: scrollbars ── */
+.dark *::-webkit-scrollbar {
+    width: 8px !important;
+    height: 8px !important;
+    background: transparent !important;
+}
+.dark *::-webkit-scrollbar-track {
+    background: transparent !important;
+    border: none !important;
+}
+.dark *::-webkit-scrollbar-thumb {
+    background: #3a3a3a !important;
+    border-radius: 4px !important;
+    border: 2px solid transparent !important;
+    background-clip: padding-box !important;
+}
+.dark *::-webkit-scrollbar-thumb:hover {
+    background: #505050 !important;
+    background-clip: padding-box !important;
+}
+.dark *::-webkit-scrollbar-corner {
+    background: transparent !important;
+}
+.dark * {
+    scrollbar-width: thin !important;
+    scrollbar-color: #3a3a3a transparent !important;
+}
+
+/* ── Dark mode: sliders (track + thumb) ── */
+.dark input[type="range"] {
+    -webkit-appearance: none !important;
+    appearance: none !important;
+    background: transparent !important;
+    height: 4px !important;
+    cursor: pointer !important;
+}
+.dark input[type="range"]::-webkit-slider-runnable-track {
+    background: #2f2f2f !important;
+    height: 4px !important;
+    border-radius: 2px !important;
+    border: none !important;
+}
+.dark input[type="range"]::-moz-range-track {
+    background: #2f2f2f !important;
+    height: 4px !important;
+    border-radius: 2px !important;
+    border: none !important;
+}
+.dark input[type="range"]::-webkit-slider-thumb {
+    -webkit-appearance: none !important;
+    appearance: none !important;
+    width: 18px !important;
+    height: 18px !important;
+    border-radius: 50% !important;
+    background: #6b9fff !important;
+    border: 2px solid #1f1f1f !important;
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4) !important;
+    margin-top: -7px !important;
+    cursor: pointer !important;
+}
+.dark input[type="range"]::-moz-range-thumb {
+    width: 18px !important;
+    height: 18px !important;
+    border-radius: 50% !important;
+    background: #6b9fff !important;
+    border: 2px solid #1f1f1f !important;
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4) !important;
+    cursor: pointer !important;
+}
+.dark input[type="range"]::-moz-range-progress {
+    background-color: #4b7fd6 !important;
+    height: 4px !important;
+    border-radius: 2px !important;
+}
+
+/* ── Dark mode: number/spin inputs (slider value boxes) ── */
+.dark input[type="number"] {
+    background: #1f1f1f !important;
+    color: #c8c8c8 !important;
+    border: 1px solid #262626 !important;
+    border-radius: 6px !important;
+    box-shadow: none !important;
+}
+.dark input[type="number"]:focus {
+    border-color: rgba(107, 159, 255, 0.35) !important;
+    outline: none !important;
+}
+.dark input[type="number"]::-webkit-inner-spin-button,
+.dark input[type="number"]::-webkit-outer-spin-button {
+    filter: invert(0.85) !important;
+    opacity: 0.4 !important;
+}
+/* Number-input wrappers (the small editable boxes next to sliders).
+ * Previously also targeted .wrap.svelte-1cl284s; dropped the hash since
+ * Gradio regenerates it. Stable selectors below cover the same elements. */
+.dark .gradio-container [class*="number_input"],
+.dark .gradio-container [data-testid*="number"] input,
+.dark .gradio-container [data-testid*="number"] .wrap,
+.dark .gradio-container .head .wrap,
+.dark .gradio-container .head input {
+    background: #1f1f1f !important;
+    color: #c8c8c8 !important;
+    border-color: #262626 !important;
+    box-shadow: none !important;
+}
+.dark .gradio-container .head,
+.dark .gradio-container .head > div,
+.dark .gradio-container .tabular-nums {
+    background: transparent !important;
+    border-color: #262626 !important;
+}
+
+/* ── Dark mode: slider min/max range labels (e.g. "0", "1", "65536") ── */
+.dark .gradio-container .min,
+.dark .gradio-container .max,
+.dark .head .min,
+.dark .head .max,
+.dark span.tabular-nums {
+    color: #707070 !important;
+}
+
+/* ── Dark mode: reset-to-default arrow button next to inputs ── */
+.dark button[aria-label="Reset to default value"],
+.dark button[title="Reset to default value"] {
+    background: transparent !important;
+    color: #707070 !important;
+    border: none !important;
+    box-shadow: none !important;
+}
+.dark button[aria-label="Reset to default value"]:hover,
+.dark button[title="Reset to default value"]:hover {
+    color: #b0b0b0 !important;
+    background: transparent !important;
+}

static/css/_examples.css

@@ -0,0 +1,142 @@
+/* ─────────────────────────────────────────────────────────────────────────
+ * Empty-state "What can I help you with?" overlay.
+ * Lives outside the Gradio container (appended to <body>) so we don't need
+ * !important to win against framework styles.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+#examples-overlay {
+    position: fixed;
+    left: 0; right: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: 100;
+    background: var(--hy-bg);
+    pointer-events: none;
+    overflow-y: auto;
+}
+
+.examples-wrapper {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    margin: auto;
+    pointer-events: auto;
+    padding: 40px 20px;
+}
+
+.examples-heading {
+    font-size: 22px;
+    font-weight: 600;
+    color: var(--hy-text);
+    margin: 0 0 28px;
+    letter-spacing: -0.01em;
+}
+
+/* 1-2-1 "diamond" layout for exactly 4 example cards.
+ *   row 1: card #1 (centered, spans both columns)
+ *   row 2: card #2 (right-aligned in left col) | card #3 (left-aligned in right col)
+ *   row 3: card #4 (centered, spans both columns)
+ * Using CSS grid with explicit nth-child placements rather than flex-
+ * wrap, because flex-wrap on equal-width children can only produce
+ * 1xN, 2x2, or 4x1 — never 1-2-1. */
+.examples-grid {
+    display: grid;
+    grid-template-columns: minmax(0, 480px) minmax(0, 480px);
+    column-gap: 20px;
+    row-gap: 14px;
+    justify-content: center;
+    width: min(1020px, 100%);
+}
+
+.example-btn:nth-child(1),
+.example-btn:nth-child(4) {
+    grid-column: 1 / span 2;
+    justify-self: center;
+}
+.example-btn:nth-child(2) {
+    grid-column: 1;
+    justify-self: end;
+}
+.example-btn:nth-child(3) {
+    grid-column: 2;
+    justify-self: start;
+}
+
+.example-btn {
+    /* Outer card: flex container that vertically + horizontally centers
+     * its single inner ``.example-btn-text`` child. We CANNOT also be
+     * a ``-webkit-box`` here (that's the inner element's job, see
+     * below) — line-clamp and flex centering need separate elements. */
+    display: flex !important;
+    align-items: center;
+    justify-content: center;
+    overflow: hidden !important;
+    box-sizing: border-box !important;
+
+    width: 460px;
+    /* 14px font * 1.5 line-height = 21px per line. 2 lines = 42px.
+     * + 14px*2 padding-y = 28px. + 1px*2 border = 2px. Total 72px. */
+    height: 72px;
+
+    background: var(--hy-bg);
+    border: 1px solid var(--hy-border);
+    border-radius: 18px;
+    padding: 14px 20px;
+    font-size: 14px;
+    line-height: 1.5;
+    color: var(--hy-text);
+    cursor: pointer;
+    transition: transform 0.15s ease, background 0.2s ease,
+                border-color 0.2s ease, box-shadow 0.2s ease, color 0.2s ease;
+    font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "PingFang SC",
+                 "Hiragino Sans GB", "Microsoft YaHei", "Helvetica Neue", Helvetica,
+                 Arial, sans-serif;
+    user-select: none;
+    text-align: center;
+}
+
+/* Inner text element: owns the 2-line clamp + auto ellipsis. The
+ * ``!important`` triplet defends against framework-level resets that
+ * would otherwise silently change ``display`` and let a 3rd line
+ * bleed into view. */
+.example-btn-text {
+    display: -webkit-box !important;
+    -webkit-line-clamp: 2 !important;
+    -webkit-box-orient: vertical !important;
+    overflow: hidden !important;
+    word-break: break-word;
+    width: 100%;
+    text-align: center;
+}
+
+/* On narrow screens the diamond would overflow horizontally — collapse
+ * to a single centered column instead. */
+@media (max-width: 1020px) {
+    .examples-grid {
+        grid-template-columns: minmax(0, 1fr);
+    }
+    .example-btn:nth-child(1),
+    .example-btn:nth-child(2),
+    .example-btn:nth-child(3),
+    .example-btn:nth-child(4) {
+        grid-column: 1;
+        justify-self: center;
+    }
+    .example-btn {
+        width: 100%;
+        max-width: 520px;
+    }
+}
+.example-btn:hover {
+    background: var(--hy-bg-muted);
+    border-color: var(--hy-border-strong);
+    color: var(--hy-text-strong);
+    box-shadow: var(--hy-shadow);
+    transform: translateY(-1px);
+}
+
+.dark .example-btn:hover {
+    border-color: rgba(107, 159, 255, 0.35);
+    box-shadow: 0 0 8px rgba(107, 159, 255, 0.08);
+}

static/css/_hide.css

@@ -0,0 +1,131 @@
+/* ── hide all avatars ── */
+#hy-chat [class*="avatar"] {
+    display: none !important;
+    width: 0 !important;
+    height: 0 !important;
+    min-width: 0 !important;
+    min-height: 0 !important;
+    overflow: hidden !important;
+    opacity: 0 !important;
+    margin: 0 !important;
+    padding: 0 !important;
+    position: absolute !important;
+    pointer-events: none !important;
+}
+
+/* ── hide Gradio default action buttons & icons ── */
+#hy-chat button[aria-label="Copy message"],
+#hy-chat button[title="Copy message"],
+#hy-chat button[aria-label="Share message"],
+#hy-chat button[title="Share message"],
+#hy-chat button[aria-label="Delete message"],
+#hy-chat button[title="Delete message"],
+#hy-chat button[aria-label="Retry"],
+#hy-chat button[title="Retry"],
+#hy-chat button[aria-label="Undo"],
+#hy-chat button[title="Undo"],
+#hy-chat .message-buttons-bot,
+#hy-chat .message-buttons-user,
+#hy-chat .bot .icon-button-wrapper,
+#hy-chat .user .icon-button-wrapper,
+#hy-chat .bot .icon-button,
+#hy-chat .user .icon-button,
+#hy-chat .likeable {
+    display: none !important;
+}
+
+/*
+ * NOTE: do NOT use a blanket `.message-row button:not(.html-preview-btn)`
+ * rule here — it would also hide our per-code-block "Copy" button that
+ * lives inside .hy-codeblock-header at the top-right of each fenced
+ * code block. The specific aria-label/title selectors above already
+ * cover the message-level action buttons we want to hide.
+ */
+
+/* ── hide stray images/svgs inside messages ── */
+#hy-chat .message-row img:not([class*="markdown"]),
+#hy-chat .message-row svg {
+    display: none !important;
+}
+/* …but keep the SVGs inside our custom code-copy-btn visible.
+ * Specificity is boosted via duplicated #hy-chat to beat the hide rule. */
+#hy-chat#hy-chat .message-row .code-copy-btn,
+#hy-chat#hy-chat .message-row .code-copy-btn svg,
+#hy-chat#hy-chat .message-row .code-copy-btn svg * {
+    display: inline-flex !important;
+}
+#hy-chat#hy-chat .message-row .code-copy-btn svg {
+    display: block !important;
+}
+/* …and keep SVGs inside KaTeX math formulas visible.
+ * KaTeX uses SVGs for radicals, stretchy delimiters, fraction lines, etc. */
+#hy-chat#hy-chat .message-row .katex svg,
+#hy-chat#hy-chat .message-row .katex-display svg {
+    display: inline !important;
+}
+
+/* ── Hide scroll-to-bottom button (too jarring in both themes) ── */
+#hy-chat button.scroll-hide,
+#hy-chat button[aria-label*="scroll" i],
+#hy-chat button[aria-label*="bottom" i],
+#hy-chat .scroll-to-bottom,
+#hy-chat [class*="scroll-button"],
+#hy-chat [class*="scrollButton"],
+#hy-chat button[class*="scroll"] {
+    display: none !important;
+    visibility: hidden !important;
+    opacity: 0 !important;
+    pointer-events: none !important;
+}
+
+/* ── Hide the busy-marker component completely ──
+ * Driven by chat.py: contains either "" (idle) or a single
+ * <span data-hy-streaming="1"> (streaming). It is a pure machine signal
+ * read by static/app.js; it must never occupy any visible layout
+ * regardless of value, and must never trap pointer/scroll/focus events. */
+#hy-busy-marker,
+#hy-busy-marker * {
+    position: absolute !important;
+    width: 0 !important;
+    height: 0 !important;
+    margin: 0 !important;
+    padding: 0 !important;
+    border: 0 !important;
+    overflow: hidden !important;
+    clip: rect(0 0 0 0) !important;
+    clip-path: inset(50%) !important;
+    visibility: hidden !important;
+    opacity: 0 !important;
+    pointer-events: none !important;
+    user-select: none !important;
+}
+
+/* ── Hide all Gradio progress / loading status indicators globally ── */
+.progress-bar-wrap,
+.progress-bar,
+.progress-text,
+.progress,
+.eta-bar,
+[data-testid="loader"],
+.loader,
+.wrap.default.minimal,
+.gradio-container .status-wrap,
+.gradio-container .status,
+.gradio-container .meta-text,
+.gradio-container .meta-text-center,
+.gradio-container [class*="progress"],
+.gradio-container [class*="Progress"],
+.gradio-container .generating,
+#hy-chat .generating,
+#hy-chat .progress,
+#hy-chat .progress-text,
+#hy-chat [class*="progress"],
+#hy-chat [class*="loading"],
+#hy-chat [class*="loader"] {
+    display: none !important;
+    visibility: hidden !important;
+    opacity: 0 !important;
+    pointer-events: none !important;
+    height: 0 !important;
+    width: 0 !important;
+}

static/css/_input.css

@@ -0,0 +1,114 @@
+/* ── input row ── */
+.msg-row {
+    padding: 8px 0 !important;
+    gap: 8px !important;
+    border-top: none !important;
+    background: #fff !important;
+    align-items: center !important;
+    height: 88px !important;
+    min-height: 88px !important;
+    max-height: 88px !important;
+    flex-shrink: 0 !important;
+}
+.dark .msg-row {
+    background: #171717 !important;
+}
+.dark .msg-row *:not(textarea):not(button):not(button *) {
+    background: transparent !important;
+    border-color: transparent !important;
+    box-shadow: none !important;
+    outline: none !important;
+}
+.msg-input textarea {
+    height: 72px !important;
+    min-height: 72px !important;
+    max-height: 72px !important;
+    overflow-y: auto !important;
+    resize: none !important;
+    border-radius: 20px !important;
+    border: 1px solid #e0e0e0 !important;
+    padding: 18px 22px !important;
+    font-size: 15px !important;
+    line-height: 1.5 !important;
+    background: #fff !important;
+    box-shadow: 0 1px 4px rgba(0,0,0,0.06) !important;
+    color: #000 !important;
+}
+.dark .msg-input textarea {
+    background: #2a2a2a !important;
+    border-color: #3a3a3a !important;
+    color: #e8e8e8 !important;
+    box-shadow: 0 1px 4px rgba(0,0,0,0.3) !important;
+}
+.msg-input textarea:focus {
+    border-color: #c0c0c0 !important;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.08) !important;
+    outline: none !important;
+}
+.dark .msg-input textarea:focus {
+    border-color: rgba(107, 159, 255, 0.4) !important;
+    box-shadow: 0 0 0 2px rgba(107, 159, 255, 0.1), 0 2px 8px rgba(0,0,0,0.3) !important;
+}
+
+/* ── new chat (+) button ── */
+.new-chat-btn {
+    width: 42px !important;
+    height: 42px !important;
+    min-width: 42px !important;
+    max-width: 42px !important;
+    border-radius: 50% !important;
+    border: 1px solid #e5e7eb !important;
+    background: #fff !important;
+    color: #666 !important;
+    font-size: 22px !important;
+    font-weight: 300 !important;
+    padding: 0 !important;
+    display: flex !important;
+    align-items: center !important;
+    justify-content: center !important;
+    cursor: pointer !important;
+    flex-shrink: 0 !important;
+}
+.new-chat-btn:hover {
+    background: #f5f5f5 !important;
+    color: #333 !important;
+    border-color: #d0d0d0 !important;
+}
+.dark .new-chat-btn {
+    border-color: #3a3a3a !important;
+    background: #2a2a2a !important;
+    color: #999 !important;
+}
+.dark .new-chat-btn:hover {
+    background: #333 !important;
+    color: #e8e8e8 !important;
+    border-color: #505050 !important;
+}
+
+/* ── buttons ── */
+button.primary { border-radius: 20px !important; font-weight: 500 !important; font-size: 14px !important; padding: 8px 20px !important; }
+button.secondary { border: 1px solid #e5e5ea !important; border-radius: 20px !important; font-size: 14px !important; color: #444 !important; padding: 8px 16px !important; }
+.dark button.secondary { border-color: #3a3a3a !important; color: #c0c0c0 !important; }
+
+/* ── send button ── */
+.send-btn, #send-btn {
+    width: 42px !important;
+    height: 42px !important;
+    min-width: 42px !important;
+    max-width: 42px !important;
+    border-radius: 50% !important;
+    padding: 0 !important;
+    display: flex !important;
+    align-items: center !important;
+    justify-content: center !important;
+    font-size: 18px !important;
+    flex-shrink: 0 !important;
+}
+#send-btn button {
+    width: 42px !important;
+    height: 42px !important;
+    min-width: 42px !important;
+    border-radius: 50% !important;
+    padding: 0 !important;
+    font-size: 18px !important;
+}

static/css/_layout.css

@@ -0,0 +1,41 @@
+/* ── full-viewport layout ── */
+html, body {
+    overflow: hidden !important;
+    height: 100vh !important;
+    background: #fff !important;
+}
+.dark html, .dark body, html.dark, body.dark {
+    background: #171717 !important;
+}
+.gradio-container {
+    height: 100vh !important;
+    overflow: hidden !important;
+    max-width: 100% !important;
+    background: #fff !important;
+}
+.dark .gradio-container, .gradio-container.dark {
+    background: #171717 !important;
+}
+.main {
+    height: 100% !important;
+    overflow: hidden !important;
+    background: #fff !important;
+}
+.dark .main {
+    background: #171717 !important;
+}
+
+/* ── global font ──
+ * font-family is set on #hy-chat only (not #hy-chat *) so that KaTeX's
+ * own math-font declarations (KaTeX_Main, KaTeX_Math, …) are not
+ * overridden.  Children inherit the system stack; KaTeX overrides it
+ * via its own class-based rules. */
+#hy-chat {
+    font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "PingFang SC",
+                 "Hiragino Sans GB", "Microsoft YaHei", "Helvetica Neue", Helvetica,
+                 Arial, sans-serif !important;
+}
+#hy-chat, #hy-chat * {
+    -webkit-font-smoothing: antialiased !important;
+    -moz-osx-font-smoothing: grayscale !important;
+}

static/css/_legacy.css

@@ -0,0 +1,50 @@
+/* ── Form / accordion / label tweaks ──────────────────────────────────────
+ *
+ * Previously these rules targeted Svelte hash classes (e.g. .svelte-d5xbca,
+ * .svelte-xzq5jh, .svelte-e5lyqv, .svelte-jdcl7l) which Gradio re-generates on
+ * every release. We drop the hashes and use stable class/role selectors so a
+ * Gradio bump doesn't silently break our styling.
+ */
+
+/* hide the rectangular border Gradio puts around forms */
+.gradio-container .form {
+    border: none !important;
+}
+
+/* small "Validate & Format" style accordion buttons inside forms */
+.gradio-container .form button.sm,
+.gradio-container .accordion button.sm {
+    background: rgb(229, 231, 235);
+}
+.dark .gradio-container .form button.sm,
+.dark .gradio-container .accordion button.sm {
+    background: #2a2a2a !important;
+    color: #c0c0c0 !important;
+}
+
+/* accordion / dropdown / slider label colors */
+.gradio-container .label-wrap,
+.gradio-container .label-wrap > span {
+    color: #000;
+}
+.dark .gradio-container .label-wrap,
+.dark .gradio-container .label-wrap > span {
+    color: #c0c0c0 !important;
+}
+
+/* bot paragraph color (kept here because it's adjacent to label color logic) */
+#hy-chat .bot p {
+    color: #000;
+}
+.dark #hy-chat .bot p {
+    color: #e8e8e8 !important;
+}
+
+/* prose inside the Gradio container (markdown rendering); use attribute
+ * selector that matches any container-version class instead of a pinned one */
+[class*="gradio-container"] .prose * {
+    color: #000;
+}
+.dark [class*="gradio-container"] .prose * {
+    color: #e8e8e8 !important;
+}

static/css/_math.css

@@ -0,0 +1,132 @@
+/* ─────────────────────────────────────────────────────────────────────────
+ * KaTeX math rendering
+ *
+ * The chatbot CSS sets line-height: 1.8 + letter-spacing: 0.01em on
+ * .bot .markdown.  These cascade into KaTeX, where SVGs for stretchy
+ * operators (like \not=) use height: inherit + width: 100%.  An inflated
+ * line-height turns those SVGs into solid-colour rectangles.  We reset
+ * typographic properties on all KaTeX descendants to restore correct
+ * glyph and symbol layout.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+/* ── Restore KaTeX's own font ──
+ * _layout.css sets font-family on #hy-chat; KaTeX children inherit it.
+ * Override here so KaTeX uses its own math fonts for correct glyphs.  */
+#hy-chat .katex {
+    font: normal 1.21em KaTeX_Main, "Times New Roman", serif !important;
+    text-indent: 0 !important;
+}
+
+/* ── Reset inherited typography ──
+ * High-specificity selectors ensure we beat the #hy-chat .bot .markdown
+ * rule that sets line-height: 1.8 and letter-spacing: 0.01em. */
+#hy-chat .bot .markdown .katex,
+#hy-chat .bot .markdown .katex *,
+#hy-chat .bot .markdown .katex-display,
+#hy-chat .bot .markdown .katex-display *,
+#hy-chat .katex,
+#hy-chat .katex *,
+#hy-chat .katex-display,
+#hy-chat .katex-display * {
+    letter-spacing: normal !important;
+    word-spacing: normal !important;
+    line-height: 1.2 !important;
+}
+
+/* ── SVG rendering ──
+ * KaTeX uses SVGs for radicals (√), stretchy delimiters, fraction lines,
+ * and negation slashes.  Ensure they inherit the current text colour and
+ * are not distorted by the parent's line-height. */
+#hy-chat .katex svg {
+    fill: currentColor;
+    stroke: none;
+}
+#hy-chat .katex svg path {
+    fill: currentColor;
+}
+
+/* ── SVG overlay fix ──
+ * Constrain overlay containers (negation slashes, accents) so an
+ * inflated line-height can never stretch SVGs into black blocks. */
+#hy-chat .katex .rlap,
+#hy-chat .katex .llap,
+#hy-chat .katex .clap {
+    line-height: 0 !important;
+}
+#hy-chat .katex .stretchy,
+#hy-chat .katex .halfarrow-left,
+#hy-chat .katex .halfarrow-right,
+#hy-chat .katex .brace-left,
+#hy-chat .katex .brace-right {
+    overflow: hidden !important;
+}
+#hy-chat .katex .rule,
+#hy-chat .katex .mfrac .frac-line,
+#hy-chat .katex .overline .overline-line,
+#hy-chat .katex .underline .underline-line,
+#hy-chat .katex .hline {
+    overflow: hidden !important;
+}
+
+/* ── Text colour ──
+ * Explicit colour in both themes so KaTeX text and SVG fills (via
+ * currentColor) always match the surrounding prose. */
+#hy-chat .katex,
+#hy-chat .katex-display {
+    color: var(--hy-text, #222222) !important;
+}
+
+/* ── Display math (block) ── */
+#hy-chat .katex-display {
+    margin: 1em 0 !important;
+    padding: 0.4em 0 !important;
+    overflow-x: auto !important;
+    overflow-y: hidden !important;
+    -webkit-overflow-scrolling: touch;
+}
+#hy-chat .katex-display > .katex {
+    text-align: center !important;
+}
+
+/* Subtle scrollbar for wide equations */
+#hy-chat .katex-display::-webkit-scrollbar {
+    height: 3px;
+}
+#hy-chat .katex-display::-webkit-scrollbar-track {
+    background: transparent;
+}
+#hy-chat .katex-display::-webkit-scrollbar-thumb {
+    background: #d0d0d0;
+    border-radius: 2px;
+}
+
+/* ── Inline math ── */
+#hy-chat p .katex,
+#hy-chat li .katex,
+#hy-chat td .katex {
+    font-size: 1.05em;
+    vertical-align: baseline;
+}
+
+/* ── KaTeX error fallback: show raw LaTeX legibly ── */
+#hy-chat .katex-error {
+    color: var(--hy-text-muted, #666) !important;
+    font-family: "SF Mono", "Fira Code", "JetBrains Mono", monospace !important;
+    font-size: 0.88em !important;
+    background: var(--hy-bg-muted, #f5f5f7) !important;
+    padding: 1px 5px !important;
+    border-radius: 3px !important;
+}
+
+/* ── Dark mode ── */
+.dark #hy-chat .katex,
+.dark #hy-chat .katex-display {
+    color: var(--hy-text, #e8e8e8) !important;
+}
+.dark #hy-chat .katex-display::-webkit-scrollbar-thumb {
+    background: #404040;
+}
+.dark #hy-chat .katex-error {
+    color: var(--hy-text-muted, #909090) !important;
+    background: var(--hy-bg-muted, #2a2a2a) !important;
+}

static/css/_misc.css

@@ -0,0 +1,62 @@
+/* ── inputs global ── */
+textarea, input[type="text"] { border-radius: 10px !important; font-size: 15px !important; }
+
+/* ── code blocks ── */
+#hy-chat pre {
+    background: #f5f5f7 !important;
+    border: 1px solid #ebebeb !important;
+    border-radius: 8px !important;
+    padding: 14px 18px !important;
+    font-size: 13px !important;
+    line-height: 1.6 !important;
+    overflow-x: auto !important;
+    margin: 0.8em 0 !important;
+}
+.dark #hy-chat pre {
+    background: #111 !important;
+    border-color: #2a2a2a !important;
+}
+#hy-chat code {
+    font-family: "SF Mono", "Fira Code", "JetBrains Mono", "Consolas", "Monaco", monospace !important;
+    font-size: 0.9em !important;
+}
+.dark #hy-chat code {
+    color: #d4d4d4 !important;
+}
+#hy-chat :not(pre) > code {
+    background: #f0f0f3 !important;
+    padding: 2px 6px !important;
+    border-radius: 4px !important;
+    color: #333 !important;
+}
+.dark #hy-chat :not(pre) > code {
+    background: #2a2a2a !important;
+    color: #d4d4d4 !important;
+}
+
+/* ── blockquote ── */
+#hy-chat blockquote {
+    border-left: 3px solid #d1d1d6 !important;
+    margin: 0.8em 0 !important;
+    padding: 4px 16px !important;
+    color: #555 !important;
+    background: transparent !important;
+}
+.dark #hy-chat blockquote {
+    border-left-color: #3a3a3a !important;
+    color: #909090 !important;
+}
+
+/* ── hr ── */
+#hy-chat hr {
+    border: none !important;
+    border-top: 1px solid #e5e5ea !important;
+    margin: 1.2em 0 !important;
+}
+.dark #hy-chat hr {
+    border-top-color: #2a2a2a !important;
+}
+
+/* ── slider progress ── */
+.gradio-container input[type="range"]::-moz-range-progress { background-color: #2563eb !important; }
+.gradio-container input[type="range"]::-moz-range-track { background: #e5e7eb !important; }

static/css/_modals.css

@@ -0,0 +1,266 @@
+/* ─────────────────────────────────────────────────────────────────────────
+ * Floating panels: tool-call input area + HTML preview modal.
+ *
+ * #tool-area lives inside the Gradio tree, so it still needs !important to
+ * win the cascade against framework styles.
+ *
+ * .html-preview-* lives directly under <body> (appended by static/app.js)
+ * so it can use plain specificity.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+/* ── tool area (inside Gradio) ─────────────────────────────────────────── */
+#tool-area {
+    position: fixed !important;
+    bottom: 120px !important;
+    left: 50% !important;
+    transform: translateX(-50%) !important;
+    width: min(600px, 55%) !important;
+    z-index: 999 !important;
+    background: var(--hy-bg) !important;
+    border: 1px solid var(--hy-border) !important;
+    border-radius: 12px !important;
+    padding: 16px !important;
+    box-shadow: 0 4px 24px rgba(0, 0, 0, 0.08) !important;
+}
+.dark #tool-area {
+    background: var(--hy-bg-soft) !important;
+    border-color: var(--hy-border) !important;
+    box-shadow: 0 4px 24px rgba(0, 0, 0, 0.5) !important;
+}
+.dark #tool-area *:not(button):not(button *) {
+    background: transparent !important;
+    border-color: var(--hy-border-strong) !important;
+}
+.dark #tool-area textarea,
+.dark #tool-area input[type="text"] {
+    background: var(--hy-bg-muted) !important;
+    color: var(--hy-text) !important;
+    border: 1px solid var(--hy-border-strong) !important;
+}
+.dark #tool-area textarea::placeholder,
+.dark #tool-area input[type="text"]::placeholder {
+    color: var(--hy-text-muted) !important;
+}
+
+/* ── Code-block card (header w/ language label + copy button) ──────────
+ *
+ * Each fenced code block is wrapped by static/app.js:
+ *
+ *   <div class="hy-codeblock">
+ *     <div class="hy-codeblock-header">
+ *       <span class="hy-codeblock-lang">python</span>
+ *       <button class="code-copy-btn">…</button>
+ *     </div>
+ *     <pre><code class="hljs language-…">…</code></pre>
+ *   </div>
+ *
+ * The wrapper owns the rounded border and background so the inner <pre>
+ * can be flush with the header (no double border / gap). */
+#hy-chat .hy-codeblock {
+    margin: 0.9em 0;
+    border: 1px solid var(--hy-border);
+    border-radius: 10px;
+    overflow: hidden;
+    background: #f6f7f9;
+}
+.dark #hy-chat .hy-codeblock {
+    border-color: #2a2a2a;
+    background: #0f1115;
+}
+
+#hy-chat .hy-codeblock-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+    padding: 6px 8px 6px 14px;
+    background: #ececef;
+    border-bottom: 1px solid var(--hy-border);
+    font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text",
+        "Segoe UI", Roboto, sans-serif;
+    font-size: 12px;
+    line-height: 1;
+    color: #6b6b6b;
+    user-select: none;
+}
+.dark #hy-chat .hy-codeblock-header {
+    background: #1a1d22;
+    border-bottom-color: #262a30;
+    color: #9ca3af;
+}
+
+#hy-chat .hy-codeblock-lang {
+    text-transform: lowercase;
+    letter-spacing: 0.02em;
+    font-weight: 500;
+}
+#hy-chat .hy-codeblock-lang:empty::before {
+    content: "text";
+    opacity: 0.7;
+}
+
+/* Strip the standalone <pre> chrome from _misc.css when nested in a
+ * .hy-codeblock — the wrapper provides the border/radius/background. */
+#hy-chat .hy-codeblock pre {
+    margin: 0 !important;
+    border: none !important;
+    border-radius: 0 !important;
+    background: transparent !important;
+    padding: 12px 16px !important;
+}
+
+/* Copy button — lives in the header, simple icon button. */
+#hy-chat .hy-codeblock-header .code-copy-btn {
+    flex-shrink: 0;
+    width: 26px;
+    height: 26px;
+    padding: 0;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    color: inherit;
+    background: transparent;
+    border: none;
+    border-radius: 6px;
+    cursor: pointer;
+    transition: background 0.15s ease, color 0.15s ease;
+}
+#hy-chat .hy-codeblock-header .code-copy-btn svg {
+    display: block;
+    width: 14px;
+    height: 14px;
+}
+#hy-chat .hy-codeblock-header .code-copy-btn:hover {
+    background: rgba(0, 0, 0, 0.06);
+    color: #111;
+}
+#hy-chat .hy-codeblock-header .code-copy-btn:focus {
+    outline: none;
+}
+#hy-chat .hy-codeblock-header .code-copy-btn:focus-visible {
+    outline: 2px solid var(--hy-accent, #2563eb);
+    outline-offset: 1px;
+}
+#hy-chat .hy-codeblock-header .code-copy-btn.copied,
+#hy-chat .hy-codeblock-header .code-copy-btn.copied:hover {
+    color: #0a7f3f;
+    background: transparent;
+}
+.dark #hy-chat .hy-codeblock-header .code-copy-btn:hover {
+    background: rgba(255, 255, 255, 0.08);
+    color: #f5f5f5;
+}
+.dark #hy-chat .hy-codeblock-header .code-copy-btn.copied,
+.dark #hy-chat .hy-codeblock-header .code-copy-btn.copied:hover {
+    color: #4ade80;
+    background: transparent;
+}
+
+/* ── HTML preview play button (under code blocks) ─────────────────────── */
+.html-preview-btn {
+    display: inline-flex;
+    align-items: center;
+    background: none;
+    border: none;
+    padding: 2px 0;
+    margin: 2px 0 6px;
+    cursor: pointer;
+    font-size: 0;
+    line-height: 1;
+    transition: opacity 0.15s ease;
+}
+.html-preview-btn::before {
+    content: "▶ html preview";
+    font-size: 12px;
+    color: var(--hy-accent);
+    font-weight: 400;
+    font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", sans-serif;
+}
+.html-preview-btn:hover {
+    opacity: 0.7;
+}
+
+/* ── HTML preview modal (outside Gradio, under <body>) ────────────────── */
+.html-preview-overlay {
+    position: fixed;
+    inset: 0;
+    z-index: 10000;
+    background: rgba(0, 0, 0, 0.5);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    animation: fadeIn 0.2s ease;
+}
+@keyframes fadeIn {
+    from { opacity: 0; }
+    to   { opacity: 1; }
+}
+
+.html-preview-modal {
+    width: 90vw;
+    height: 85vh;
+    background: var(--hy-bg);
+    border-radius: 12px;
+    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.2);
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    animation: modalSlideUp 0.25s ease;
+}
+.dark .html-preview-modal {
+    background: var(--hy-bg-soft);
+    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6);
+}
+@keyframes modalSlideUp {
+    from { transform: translateY(30px); opacity: 0; }
+    to   { transform: translateY(0); opacity: 1; }
+}
+
+.html-preview-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 12px 20px;
+    border-bottom: 1px solid var(--hy-border);
+    background: var(--hy-bg-soft);
+    flex-shrink: 0;
+}
+.dark .html-preview-header {
+    background: var(--hy-bg-muted);
+}
+
+.html-preview-title {
+    font-size: 14px;
+    font-weight: 600;
+    color: var(--hy-text);
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+.html-preview-title::before {
+    content: "⬡";
+    color: var(--hy-accent);
+}
+
+.html-preview-close {
+    background: none;
+    border: none;
+    font-size: 20px;
+    color: var(--hy-text-muted);
+    cursor: pointer;
+    padding: 4px 8px;
+    border-radius: 6px;
+    line-height: 1;
+    transition: all 0.15s ease;
+}
+.html-preview-close:hover {
+    background: #fee2e2;
+    color: #dc2626;
+}
+
+.html-preview-iframe {
+    flex: 1;
+    border: none;
+    width: 100%;
+    background: var(--hy-bg);
+}

static/css/_perf.css

@@ -0,0 +1,32 @@
+/* ── Long-conversation rendering optimizations ─────────────────────────
+ *
+ * Two complementary tricks that together make the page feel responsive
+ * even after a dozen or more turns:
+ *
+ *   1. ``content-visibility: auto`` on every message row tells the
+ *      browser it MAY skip layout, paint, and rendering for rows that
+ *      are scrolled off-screen. The bottom of the conversation (the
+ *      part the user actually sees while streaming) renders normally;
+ *      everything above gets cheaply substituted with the placeholder
+ *      box defined by ``contain-intrinsic-size``. Result: per-frame
+ *      style recalc / layout / paint cost stays roughly constant
+ *      regardless of how many turns are in the history.
+ *
+ *   2. ``contain: layout style paint`` scopes layout/paint
+ *      invalidations to within each message row. Without it, ANY
+ *      style change inside one message can force the whole chatbot
+ *      to recalc — and during streaming the bottom bubble mutates
+ *      dozens of times a second.
+ *
+ * The intrinsic-size value (``auto 240px``) is a guess at an average
+ * row height. The ``auto`` keyword (Chromium 110+, Safari 18+,
+ * Firefox 132+) lets the browser remember the LAST observed size of
+ * each row and use that as the placeholder when the row is skipped,
+ * which keeps the scrollbar honest and avoids visible jumps when the
+ * user scrolls back up. Browsers that don't support ``auto`` fall back
+ * to the literal 240px, which is "good enough" for placeholders. */
+#hy-chat .message-row {
+    content-visibility: auto;
+    contain-intrinsic-size: auto 240px;
+    contain: layout style paint;
+}

static/css/_thinking.css

@@ -0,0 +1,35 @@
+/* ── thinking toggle ── */
+#hy-chat .thinking-block {
+    background: none !important;
+    border: none !important;
+    padding: 0 !important;
+    margin: 6px 0 10px !important;
+}
+#hy-chat .thinking-block summary {
+    cursor: pointer;
+    font-size: 13px !important;
+    font-weight: 400 !important;
+    color: #8a8a8e !important;
+    padding: 0 !important;
+    list-style: none !important;
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+}
+#hy-chat .thinking-block summary:hover { color: #666 !important; }
+.dark #hy-chat .thinking-block summary { color: #808080 !important; }
+.dark #hy-chat .thinking-block summary:hover { color: #aaa !important; }
+#hy-chat .thinking-block summary::marker,
+#hy-chat .thinking-block summary::-webkit-details-marker { display: none !important; }
+#hy-chat .thinking-block summary::after { content: " ›" !important; font-size: 13px; color: #bbb; }
+#hy-chat .thinking-block[open] summary::after { content: " ⌄" !important; }
+#hy-chat .thinking-block[open] summary { margin-bottom: 8px !important; }
+#hy-chat .thinking-block[open] > :not(summary) {
+    font-size: 13px; color: #666; line-height: 1.7;
+    padding: 12px 16px; background: #f8f8fa !important; border-radius: 8px;
+    max-height: 300px; overflow-y: auto; border-left: 2px solid #e5e5ea !important;
+}
+.dark #hy-chat .thinking-block[open] > :not(summary) {
+    color: #909090 !important; background: #1c1c1c !important;
+    border-left-color: #333 !important;
+}

static/css/_typing.css

@@ -0,0 +1,29 @@
+/* ── typing indicator (waiting for model response) ── */
+.typing-indicator {
+    display: flex;
+    align-items: center;
+    gap: 5px;
+    padding: 4px 0;
+    height: 24px;
+}
+.typing-indicator span {
+    width: 8px;
+    height: 8px;
+    background: var(--body-text-color-subdued, #999);
+    border-radius: 50%;
+    animation: typing-bounce 1.4s infinite ease-in-out both;
+}
+.typing-indicator span:nth-child(1) { animation-delay: 0s; }
+.typing-indicator span:nth-child(2) { animation-delay: 0.2s; }
+.typing-indicator span:nth-child(3) { animation-delay: 0.4s; }
+
+@keyframes typing-bounce {
+    0%, 80%, 100% {
+        transform: scale(0.5);
+        opacity: 0.35;
+    }
+    40% {
+        transform: scale(1);
+        opacity: 1;
+    }
+}

static/css/_variables.css

@@ -0,0 +1,81 @@
+/* ─────────────────────────────────────────────────────────────────────────
+ * Design tokens (custom properties)
+ *
+ * Two layers:
+ *   1. ``--hy-*``  : our own palette — referenced from component CSS.
+ *   2. ``--*-*-*`` : Gradio's built-in tokens — overridden so Gradio's
+ *                    components match the rest of the UI.
+ *
+ * If you want to retheme HY3, change values here and (almost) nowhere else.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+:root, .gradio-container {
+    /* Hy3 palette (light) */
+    --hy-bg:            #ffffff;
+    --hy-bg-soft:       #fafafa;
+    --hy-bg-muted:      #f5f5f7;
+    --hy-text:          #222222;
+    --hy-text-strong:   #111111;
+    --hy-text-muted:    #666666;
+    --hy-border:        #e5e7eb;
+    --hy-border-strong: #d1d1d6;
+    --hy-accent:        #2563eb;
+    --hy-accent-hover:  #1d4ed8;
+    --hy-accent-soft:   #dbeafe;
+    --hy-shadow:        0 1px 4px rgba(0, 0, 0, 0.06);
+
+    /* Gradio framework overrides (light) */
+    --body-background-fill: var(--hy-bg) !important;
+    --block-background-fill: var(--hy-bg) !important;
+    --block-shadow: none !important;
+    --block-border-color: transparent !important;
+    --input-border-width: 1px !important;
+    --input-border-color: var(--hy-border) !important;
+    --color-accent: var(--hy-accent) !important;
+    --color-accent-soft: var(--hy-accent-soft) !important;
+    --button-primary-background-fill: var(--hy-accent) !important;
+    --button-primary-background-fill-hover: var(--hy-accent-hover) !important;
+    --button-primary-text-color: #ffffff !important;
+    --slider-color: var(--hy-accent) !important;
+    --neutral-200: var(--hy-border) !important;
+}
+
+/* Hy3 palette (dark) + matching Gradio overrides */
+.dark {
+    --hy-bg:            #171717;
+    --hy-bg-soft:       #1f1f1f;
+    --hy-bg-muted:      #2a2a2a;
+    --hy-text:          #e8e8e8;
+    --hy-text-strong:   #ffffff;
+    --hy-text-muted:    #909090;
+    --hy-border:        #2a2a2a;
+    --hy-border-strong: #3a3a3a;
+    --hy-accent:        #6b9fff;
+    --hy-accent-hover:  #4b8df8;
+    --hy-accent-soft:   #1a2a3d;
+    --hy-shadow:        0 1px 4px rgba(0, 0, 0, 0.3);
+
+    --body-background-fill: var(--hy-bg) !important;
+    --block-background-fill: var(--hy-bg-soft) !important;
+    --block-shadow: none !important;
+    --block-border-color: var(--hy-border) !important;
+    --input-border-width: 1px !important;
+    --input-border-color: var(--hy-border-strong) !important;
+    --color-accent: var(--hy-accent) !important;
+    --color-accent-soft: var(--hy-accent-soft) !important;
+    --button-primary-background-fill: var(--hy-accent-hover) !important;
+    --button-primary-background-fill-hover: #3a7ce6 !important;
+    --button-primary-text-color: #ffffff !important;
+    --slider-color: var(--hy-accent) !important;
+    --neutral-200: var(--hy-border) !important;
+    --body-text-color: var(--hy-text) !important;
+    --block-label-text-color: #c0c0c0 !important;
+    --block-title-text-color: #e0e0e0 !important;
+    --input-background-fill: var(--hy-bg-muted) !important;
+    --background-fill-secondary: var(--hy-bg-soft) !important;
+    --background-fill-primary: var(--hy-bg) !important;
+    --border-color-primary: var(--hy-border) !important;
+    --panel-background-fill: var(--hy-bg-soft) !important;
+    --checkbox-background-color: var(--hy-bg-muted) !important;
+    --checkbox-label-background-fill: var(--hy-bg-soft) !important;
+}

static/vendor/highlight/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2006, Ivan Sagalaev.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

static/vendor/highlight/github-dark.min.css

@@ -0,0 +1,10 @@
+pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}/*!
+  Theme: GitHub Dark
+  Description: Dark theme as seen on github.com
+  Author: github.com
+  Maintainer: @Hirse
+  Updated: 2021-05-15
+
+  Outdated base version: https://github.com/primer/github-syntax-dark
+  Current colors taken from GitHub's CSS
+*/.hljs{color:#c9d1d9;background:#0d1117}.hljs-doctag,.hljs-keyword,.hljs-meta .hljs-keyword,.hljs-template-tag,.hljs-template-variable,.hljs-type,.hljs-variable.language_{color:#ff7b72}.hljs-title,.hljs-title.class_,.hljs-title.class_.inherited__,.hljs-title.function_{color:#d2a8ff}.hljs-attr,.hljs-attribute,.hljs-literal,.hljs-meta,.hljs-number,.hljs-operator,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-id,.hljs-variable{color:#79c0ff}.hljs-meta .hljs-string,.hljs-regexp,.hljs-string{color:#a5d6ff}.hljs-built_in,.hljs-symbol{color:#ffa657}.hljs-code,.hljs-comment,.hljs-formula{color:#8b949e}.hljs-name,.hljs-quote,.hljs-selector-pseudo,.hljs-selector-tag{color:#7ee787}.hljs-subst{color:#c9d1d9}.hljs-section{color:#1f6feb;font-weight:700}.hljs-bullet{color:#f2cc60}.hljs-emphasis{color:#c9d1d9;font-style:italic}.hljs-strong{color:#c9d1d9;font-weight:700}.hljs-addition{color:#aff5b4;background-color:#033a16}.hljs-deletion{color:#ffdcd7;background-color:#67060c}

static/vendor/highlight/github.min.css

@@ -0,0 +1,18 @@
+/**
+ * Minified by jsDelivr using clean-css v5.3.3.
+ * Original file: /gh/highlightjs/cdn-release@11.10.0/build/styles/github.css
+ *
+ * Do NOT use SRI with dynamically generated files! More information: https://www.jsdelivr.com/using-sri-with-dynamic-files
+ */
+pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}/*!
+  Theme: GitHub
+  Description: Light theme as seen on github.com
+  Author: github.com
+  Maintainer: @Hirse
+  Updated: 2021-05-15
+
+  Outdated base version: https://github.com/primer/github-syntax-light
+  Current colors taken from GitHub's CSS
+*/
+.hljs{color:#24292e;background:#fff}.hljs-doctag,.hljs-keyword,.hljs-meta .hljs-keyword,.hljs-template-tag,.hljs-template-variable,.hljs-type,.hljs-variable.language_{color:#d73a49}.hljs-title,.hljs-title.class_,.hljs-title.class_.inherited__,.hljs-title.function_{color:#6f42c1}.hljs-attr,.hljs-attribute,.hljs-literal,.hljs-meta,.hljs-number,.hljs-operator,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-id,.hljs-variable{color:#005cc5}.hljs-meta .hljs-string,.hljs-regexp,.hljs-string{color:#032f62}.hljs-built_in,.hljs-symbol{color:#e36209}.hljs-code,.hljs-comment,.hljs-formula{color:#6a737d}.hljs-name,.hljs-quote,.hljs-selector-pseudo,.hljs-selector-tag{color:#22863a}.hljs-subst{color:#24292e}.hljs-section{color:#005cc5;font-weight:700}.hljs-bullet{color:#735c0f}.hljs-emphasis{color:#24292e;font-style:italic}.hljs-strong{color:#24292e;font-weight:700}.hljs-addition{color:#22863a;background-color:#f0fff4}.hljs-deletion{color:#b31d28;background-color:#ffeef0}
+/*# sourceMappingURL=/sm/4af24df1ef2dd5fc126923c27abd2503f82240131784ba83446a7a23be61ec0f.map */

static/vendor/katex/LICENSE

@@ -0,0 +1,27 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-2020 Khan Academy and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+----------------------------------------------------------------------
+
+NOTE: The KaTeX font files (under ./fonts/) are NOT covered by this MIT
+license. They are licensed separately under the SIL Open Font License,
+Version 1.1 — see ./fonts/OFL.txt.

static/vendor/katex/auto-render.min.js

@@ -0,0 +1 @@
+!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("katex")):"function"==typeof define&&define.amd?define(["katex"],t):"object"==typeof exports?exports.renderMathInElement=t(require("katex")):e.renderMathInElement=t(e.katex)}("undefined"!=typeof self?self:this,(function(e){return function(){"use strict";var t={757:function(t){t.exports=e}},n={};function r(e){var o=n[e];if(void 0!==o)return o.exports;var i=n[e]={exports:{}};return t[e](i,i.exports,r),i.exports}r.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return r.d(t,{a:t}),t},r.d=function(e,t){for(var n in t)r.o(t,n)&&!r.o(e,n)&&Object.defineProperty(e,n,{enumerable:!0,get:t[n]})},r.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)};var o={};r.d(o,{default:function(){return p}});var i=r(757),a=r.n(i);const l=function(e,t,n){let r=n,o=0;const i=e.length;for(;r<t.length;){const n=t[r];if(o<=0&&t.slice(r,r+i)===e)return r;"\\"===n?r++:"{"===n?o++:"}"===n&&o--,r++}return-1},s=/^\\begin{/;var d=function(e,t){let n;const r=[],o=new RegExp("("+t.map((e=>e.left.replace(/[-/\\^$*+?.()|[\]{}]/g,"\\$&"))).join("|")+")");for(;n=e.search(o),-1!==n;){n>0&&(r.push({type:"text",data:e.slice(0,n)}),e=e.slice(n));const o=t.findIndex((t=>e.startsWith(t.left)));if(n=l(t[o].right,e,t[o].left.length),-1===n)break;const i=e.slice(0,n+t[o].right.length),a=s.test(i)?i:e.slice(t[o].left.length,n);r.push({type:"math",data:a,rawData:i,display:t[o].display}),e=e.slice(n+t[o].right.length)}return""!==e&&r.push({type:"text",data:e}),r};const c=function(e,t){const n=d(e,t.delimiters);if(1===n.length&&"text"===n[0].type)return null;const r=document.createDocumentFragment();for(let e=0;e<n.length;e++)if("text"===n[e].type)r.appendChild(document.createTextNode(n[e].data));else{const o=document.createElement("span");let i=n[e].data;t.displayMode=n[e].display;try{t.preProcess&&(i=t.preProcess(i)),a().render(i,o,t)}catch(o){if(!(o instanceof a().ParseError))throw o;t.errorCallback("KaTeX auto-render: Failed to parse `"+n[e].data+"` with ",o),r.appendChild(document.createTextNode(n[e].rawData));continue}r.appendChild(o)}return r},f=function(e,t){for(let n=0;n<e.childNodes.length;n++){const r=e.childNodes[n];if(3===r.nodeType){let o=r.textContent,i=r.nextSibling,a=0;for(;i&&i.nodeType===Node.TEXT_NODE;)o+=i.textContent,i=i.nextSibling,a++;const l=c(o,t);if(l){for(let e=0;e<a;e++)r.nextSibling.remove();n+=l.childNodes.length-1,e.replaceChild(l,r)}else n+=a}else if(1===r.nodeType){const e=" "+r.className+" ";-1===t.ignoredTags.indexOf(r.nodeName.toLowerCase())&&t.ignoredClasses.every((t=>-1===e.indexOf(" "+t+" ")))&&f(r,t)}}};var p=function(e,t){if(!e)throw new Error("No element provided to render");const n={};for(const e in t)t.hasOwnProperty(e)&&(n[e]=t[e]);n.delimiters=n.delimiters||[{left:"$$",right:"$$",display:!0},{left:"\\(",right:"\\)",display:!1},{left:"\\begin{equation}",right:"\\end{equation}",display:!0},{left:"\\begin{align}",right:"\\end{align}",display:!0},{left:"\\begin{alignat}",right:"\\end{alignat}",display:!0},{left:"\\begin{gather}",right:"\\end{gather}",display:!0},{left:"\\begin{CD}",right:"\\end{CD}",display:!0},{left:"\\[",right:"\\]",display:!0}],n.ignoredTags=n.ignoredTags||["script","noscript","style","textarea","pre","code","option"],n.ignoredClasses=n.ignoredClasses||[],n.errorCallback=n.errorCallback||console.error,n.macros=n.macros||{},f(e,n)};return o=o.default}()}));