app.py

#!/usr/bin/env python3
"""6-String Optimizer HF Space — mystery shell + optimize/spectrum/physics-audio."""

from __future__ import annotations

import logging
import os
import re
import time
import traceback
from collections.abc import Callable, Iterator
from pathlib import Path

import gradio as gr
import plotly.graph_objects as go

from demo_core import (
    BOOT_QUOTE_STRING,
    BURST_BOOSTS,
    CLAIMS_MD,
    FIGURES_INTRO_MD,
    GITHUB_URL,
    HF_SPACE_URL,
    ONBOARDING_MD,
    OPTIMIZATION_PRESETS,
    PHYSICS_AUDIO_URL,
    PROG_ACTIONS,
    QVPIC_URL,
    SAMPLE_GUITAR_NOTE,
    SIMULATION_BANNER_MD,
    SLIDER_TOOLTIPS,
    STRING_NAMES,
    TERM_KEY_ACTIONS,
    THEORY_MD,
    THEORY_KATEX_HTML,
    KATEX_CDN,
    WALLPAPER_URL,
    WHAT_IS_THIS_MD,
    WINDOWS,
    export_optimization_plots,
    run_comparison_stream,
    synthesize_modal_comparison,
    tension_calculator_table,
    tension_single_string,
    STANDARD_TUNING,
    DEFAULT_SCALE_LENGTH_IN,
    default_run_params,
    friendly_error,
    format_eta_status,
    get_build_label,
    get_run_mode_params,
    estimate_runtime_sec,
    INTRO_WALKTHROUGH_HTML,
    KNOWN_LIMITATIONS_BODY,
    LOCAL_RUN_MD,
    PlotStreamConfig,
    RUN_MODES,
    TRAJECTORY_VIEW_CHOICES,
    WEBGL_PROBE_JS,
    default_trajectory_view,
    resolve_trajectory_mode,
    webgl_status_markdown,
    get_overview_composite_path,
    get_preset_params,
    get_sample_guitar_path,
    is_hf_space,
    render_smith_chart_preview,
    run_analysis,
    run_optimization_stream,
    analyze_audio_signal,
    terminal_directory_help,
    terminal_figures_index,
    terminal_guided_onboarding,
    terminal_keypad_map,
    terminal_optimizer_help,
    terminal_physics_overview,
    terminal_probe_scope,
    terminal_results_snapshot,
    terminal_string_catalog,
)

STRING_TABLE_MD = (
    "### Six-string hierarchy\n\n"
    "| String | Stagnation window | Burst boost | Role |\n"
    "|--------|-------------------|-------------|------|\n"
    + "\n".join(
        f"| **{n}** | {w} steps | {b:.2f}× | Monitors plateau · fires macro-burst |"
        for n, w, b in zip(STRING_NAMES, WINDOWS, BURST_BOOSTS)
    )
    + "\n\nVU meters in **OPTIMIZE** and **STRINGS** light up when a layer's tension triggers a burst."
)


def _figures_grid_html() -> str:
    """Physics-audio reference figures on the Figures page."""
    overview = get_overview_composite_path()
    smith = render_smith_chart_preview()
    overview_src = overview.as_uri() if overview.is_file() else WALLPAPER_URL
    smith_src = Path(smith).as_uri()
    items = (
        (overview_src, "Reconstruction pyramid overview"),
        (smith_src, "Smith chart Γ-mismatch preview"),
        (WALLPAPER_URL, "Physics-audio composite (GitHub)"),
        (f"{GITHUB_URL}/tree/main/physics_audio/training_evaluation/viz.py", "viz.py source"),
    )
    imgs = "".join(
        f'<figure class="vqc-screencast-video-wrap">'
        f'<img class="vqc-screencast-video" src="{url}" alt="{label}" loading="lazy" />'
        f'<figcaption>{label}</figcaption></figure>'
        for url, label in items[:2]
    )
    return f'<div class="vqc-screencast-wrap">{imgs}</div>'


def _figures_links_md() -> str:
    return (
        f"[Overview composite]({WALLPAPER_URL}) · "
        f"[Physics audio]({PHYSICS_AUDIO_URL}) · "
        f"[viz.py]({GITHUB_URL}/blob/main/physics_audio/training_evaluation/viz.py) — "
        "full Smith chart + pyramid plots run locally via `run_real_audio.py`."
    )


_DEFAULTS = default_run_params()

logger = logging.getLogger(__name__)


def _patch_gradio_client_bool_schema() -> None:
    """Avoid gradio_client crash when JSON schema contains bare bool nodes."""
    try:
        from gradio_client import utils as client_utils

        if getattr(client_utils, "_vqc_bool_patch", False):
            return

        orig_get_type = client_utils.get_type

        def get_type(schema):  # noqa: ANN001
            if isinstance(schema, bool):
                return "boolean"
            return orig_get_type(schema)

        client_utils.get_type = get_type
        client_utils._vqc_bool_patch = True
        logger.info("Patched gradio_client bool JSON-schema handling")
    except Exception:
        logger.warning("Could not patch gradio_client", exc_info=True)


_patch_gradio_client_bool_schema()

_VQC_ACCENT = "#c9a227"  # mystery gold — primary accent
_VQC_HF_RUNNING = "#1ed760"
_VQC_FIELD_FILL = "rgba(18, 10, 28, 0.52)"
_VQC_TAB_GREEN_BG = "#1a3d2a"
_VQC_TAB_GREEN_BG_HOVER = "#1f4d34"
_VQC_TAB_GREEN_BORDER = "#33ff66"
_VQC_TAB_GREEN_TEXT = "#86efac"
_VQC_TAB_GREEN_TEXT_HOVER = "#bbf7d0"
_VQC_TAB_ORANGE_BG = "#3d2a5c"
_VQC_TAB_ORANGE_BORDER = "#6a4c93"
_VQC_TAB_ORANGE_TEXT = "#d4b8ff"
_VQC_MATRIX_GREEN = "#33ff66"
_VQC_MATRIX_GREEN_BG = "#0a1f12"
_VQC_LOGO_GOLD = "#FFB000"
_VQC_HOME_KEY_BG = "#000000"

FIGURES_INTRO_MD_LOCAL = FIGURES_INTRO_MD

OPTICS_LOGO_HTML = """
<div class="vqc-optics-logo" role="img" aria-label="6-String Signal Analyzer">
  <span class="vqc-optics-brand">6-STRING</span>
  <span class="vqc-optics-panel-title">Signal Analyzer · S³ Burst</span>
  <span class="vqc-optics-subtitle">OPTIMIZE · SPECTRUM · PHYSICS-AUDIO · CLI</span>
</div>
"""

SIGNAL_SCANNER_HTML = f"""
<div class="myst-signal-scan" role="img" aria-label="Phosphor signal scan">
  <div class="myst-signal-scanlines" aria-hidden="true"></div>
  <div class="myst-signal-beam" aria-hidden="true"></div>
  <pre class="myst-signal-body">PHOSPHOR SIGNAL SCAN — SIX-STRING BURST
{'─' * 72}
High E → Low E   windows 400 → 2400
Rosenbrock S³    stereographic trajectory
Demo guitar G3   {SAMPLE_GUITAR_NOTE}
Smith chart Γ    physics-audio mismatch jumps
{'─' * 72}
▸ OPTIMIZE tab → ▶ RUN OPTIMIZATION
▸ SPECTRUM tab → ▶ DEMO GUITAR (G3)
▸ {GITHUB_URL}
{'─' * 72}
press any keypad to exit</pre>
</div>
"""

_OPTICS_TERM_BAR = "─" * 48
_OPTICS_TERM_CHAR_DELAY_S = 0.014
_OPTICS_TERM_NEWLINE_DELAY_S = 0.048
_OPTICS_TERM_UPLINK_DELAY_S = 0.22
_OPTICS_TERM_CURSOR = "▌"
_OPTICS_TERM_RELEASE_DELAY_S = 0.25
_BOOT_QUOTE_CHAR_DELAY_S = 0.1
_BOOT_POST_QUOTE_DELAY_S = 3.0
_BOOT_DOT_INTERVAL_S = 0.5
_BOOT_DOT_COUNT = 6
_BOOT_TERM_LINES = 14
_BOOT_TERM_COLS = 56


def _strip_md_plain(text: str) -> str:
    """Flatten markdown blockquotes and emphasis for terminal readout."""
    plain = re.sub(r"^>\s*", "", text.strip(), flags=re.MULTILINE)
    plain = re.sub(r"\*\*([^*]+)\*\*", r"\1", plain)
    plain = re.sub(r"`([^`]+)`", r"\1", plain)
    return plain.strip()


def _optics_terminal_frame(title: str, body: str) -> str:
    return f"{title}\n{_OPTICS_TERM_BAR}\n{body}"


TERM_KEYPAD_PROG_COLS = 12
TERM_KEYPAD_PROG_ROWS = 2
TERM_KEYPAD_COUNT = TERM_KEYPAD_PROG_COLS * TERM_KEYPAD_PROG_ROWS
TERM_KEYPAD_DEFINED: dict[int, str] = {
    index: action for index, (action, _desc) in TERM_KEY_ACTIONS.items()
}
TERM_KEYPAD_HOME_KEY = "key01"
TERM_KEYPAD_DESCRIPTIONS: dict[int, str] = {
    index: desc for index, (_action, desc) in TERM_KEY_ACTIONS.items()
}
TERM_MENU_ACTIONS: tuple[str, ...] = (
    "home",
    "status",
    "scope",
    "directory",
    "results",
    "build",
    "help",
    "scan",
)
TERM_UI_MENU = "menu"
TERM_UI_PAGE = "page"
TERM_NAV_KEYS: tuple[str, ...] = (
    "dpad_select",
    "dpad_up",
    "dpad_down",
    "dpad_left",
    "dpad_right",
    "clear",
)
TERM_DPAD_HOLD_KEYS: tuple[str, ...] = (
    "dpad_select",
    "dpad_up",
    "dpad_down",
    "dpad_left",
    "dpad_right",
)
TERM_NAV_DEFINED: dict[str, str] = {
    "dpad_select": "Enter — confirm menu item",
    "dpad_up": "Up — previous menu item",
    "dpad_down": "Down — next menu item",
    "dpad_left": "Left — previous menu item",
    "dpad_right": "Right — next menu item",
    "clear": "Clear — blank display",
}
TERM_KEYPAD_CONTROL_ORDER: tuple[str, ...] = (
    *TERM_NAV_KEYS,
    *(f"key{i:02d}" for i in range(1, TERM_KEYPAD_COUNT + 1)),
)


def _optics_assigned_keypad_lines() -> str:
    """Only keys with real functions — omit latch-only / unassigned slots."""
    lines = []
    for index in sorted(TERM_KEYPAD_DEFINED):
        tag = "01 Home" if index == 1 else f"{index:02d}"
        lines.append(f"  [{tag}]  {TERM_KEYPAD_DESCRIPTIONS[index]}")
    for nav_key in TERM_NAV_KEYS:
        if nav_key in TERM_NAV_DEFINED:
            tag = "CLR" if nav_key == "clear" else nav_key.removeprefix("dpad_").upper()
            lines.append(f"  [{tag}]  {TERM_NAV_DEFINED[nav_key]}")
    return "\n".join(lines)


def _optics_terminal_home() -> str:
    return _optics_terminal_frame("PROGRAMMABLE KEYPAD", terminal_keypad_map())


def _default_term_ui_state() -> dict:
    return {"mode": TERM_UI_MENU, "index": 0, "scan": False}


def _optics_terminal_menu(menu_index: int) -> str:
    lines = [
        "▲▼ ◀▶ move highlight · enter confirm · 01 Home",
        "",
    ]
    for index, (_action, keypad_key, label, _stream) in enumerate(_term_menu_items()):
        mark = "▶" if index == menu_index else " "
        lines.append(f"{keypad_key:02d} --- [{mark}] {label}")
    return _optics_terminal_frame("SELECTION MENU", "\n".join(lines))


def _term_menu_label(action: str) -> str:
    labels = {
        "home": "Home — Keypad Map",
        "status": "Status — Live Constants",
        "scope": "Scope — Space vs Local Suite",
        "directory": "Directory — Repo Layout",
        "results": "Results — Six-String Snapshot",
        "build": "Build — Deploy Stamp",
        "help": "Help — D-pad Navigation",
        "scan": "Scan — Phosphor Display",
    }
    return labels.get(action, action)


def _term_menu_keypad_index(action: str) -> int:
    for index, (key, _desc) in TERM_KEY_ACTIONS.items():
        if key == action:
            return index
    return 1


def _term_menu_items() -> tuple[tuple[str, int, str, Callable[[], Iterator[str]]], ...]:
    items = []
    for action in TERM_MENU_ACTIONS:
        stream_fn = TERM_KEYPAD_STREAMERS.get(action)
        if stream_fn is None:
            continue
        items.append(
            (
                action,
                _term_menu_keypad_index(action),
                _term_menu_label(action),
                stream_fn,
            )
        )
    return tuple(items)


def _term_menu_index_for_action(action: str) -> int:
    for index, (key, _keypad, _label, _stream) in enumerate(_term_menu_items()):
        if key == action:
            return index
    return 0


def _term_menu_step(menu_index: int, delta: int) -> int:
    count = len(_term_menu_items())
    return (menu_index + delta) % count


def _optics_terminal_status() -> str:
    on_hf = is_hf_space()
    env = "Hugging Face Space" if on_hf else "Local Gradio"
    return _optics_terminal_frame(
        "SYSTEM STATUS",
        "\n".join(
            [
                f"Environment : {env}",
                f"Space       : {HF_SPACE_URL}",
                f"Steps (HF)  : {_DEFAULTS['total_steps']:,}",
                f"Demo guitar : {get_sample_guitar_path().name}",
                "Pipeline    : S³ optimize → spectrum → Smith chart viz",
                f"Physics     : {PHYSICS_AUDIO_URL}",
                f"Template    : mystery shell · qvpic signal style",
                "",
                "05 Results · 09 Strings · 10 Physics · Run below.",
            ]
        ),
    )


def _optics_terminal_scope() -> str:
    return _optics_terminal_frame("PROBE SCOPE", terminal_probe_scope())


def _optics_terminal_directory() -> str:
    return _optics_terminal_frame("REPO DIRECTORY", terminal_directory_help())


def _optics_terminal_results() -> str:
    return _optics_terminal_frame("RESULTS SNAPSHOT", terminal_results_snapshot())


def _optics_terminal_strings() -> str:
    return _optics_terminal_frame("STRING CATALOG", terminal_string_catalog())


def _optics_terminal_physics() -> str:
    return _optics_terminal_frame("PHYSICS AUDIO", terminal_physics_overview())


def _optics_terminal_tour() -> str:
    return _optics_terminal_frame("GUIDED TOUR", terminal_guided_onboarding())


def _optics_terminal_figures() -> str:
    return _optics_terminal_frame("FIGURES INDEX", terminal_figures_index())


def _optics_terminal_build() -> str:
    build = get_build_label().replace("`", "")
    return _optics_terminal_frame(
        "BUILD / LAST UPDATED",
        "\n".join(
            [
                build,
                "",
                "Mystery shell + 6-string optimizer core.",
                f"Repo: {GITHUB_URL}",
                f"Space: {HF_SPACE_URL}",
            ]
        ),
    )


def _optics_terminal_help() -> str:
    return _optics_terminal_frame("KEYPAD REFERENCE", terminal_optimizer_help())


def _stream_optics_terminal_text(full_text: str) -> Iterator[str]:
    """Reveal terminal text one character at a time — typewriter / uplink effect."""
    shown = ""
    for ch in full_text:
        shown += ch
        yield shown + _OPTICS_TERM_CURSOR
        time.sleep(_OPTICS_TERM_NEWLINE_DELAY_S if ch == "\n" else _OPTICS_TERM_CHAR_DELAY_S)
    yield shown


def _optics_terminal_uplink_banner(mode: str) -> str:
    stamp = time.strftime("%H:%M:%S", time.gmtime())
    return f"> UPLINK {mode.upper()} @ {stamp} UTC…\n"


def _optics_terminal_stream(builder: Callable[[], str], *, mode: str) -> Iterator[str]:
    """Stream a keyed readout: uplink banner, then body character-by-character."""
    banner = _optics_terminal_uplink_banner(mode)
    yield banner + _OPTICS_TERM_CURSOR
    time.sleep(_OPTICS_TERM_UPLINK_DELAY_S)
    yield from _stream_optics_terminal_text(banner + builder())


def _stream_optics_terminal_home() -> Iterator[str]:
    yield from _optics_terminal_stream(_optics_terminal_home, mode="home")


def _stream_optics_terminal_status() -> Iterator[str]:
    yield from _optics_terminal_stream(_optics_terminal_status, mode="status")


def _stream_optics_terminal_scope() -> Iterator[str]:
    yield from _optics_terminal_stream(_optics_terminal_scope, mode="scope")


def _stream_optics_terminal_directory() -> Iterator[str]:
    yield from _optics_terminal_stream(_optics_terminal_directory, mode="directory")


def _stream_optics_terminal_results() -> Iterator[str]:
    yield from _optics_terminal_stream(_optics_terminal_results, mode="results")


def _stream_optics_terminal_strings() -> Iterator[str]:
    yield from _optics_terminal_stream(_optics_terminal_strings, mode="strings")


def _stream_optics_terminal_physics() -> Iterator[str]:
    yield from _optics_terminal_stream(_optics_terminal_physics, mode="physics")


def _stream_optics_terminal_tour() -> Iterator[str]:
    yield from _optics_terminal_stream(_optics_terminal_tour, mode="tour")


def _stream_optics_terminal_figures() -> Iterator[str]:
    yield from _optics_terminal_stream(_optics_terminal_figures, mode="figures")


def _stream_scan_stub() -> Iterator[str]:
    """Menu placeholder — real scan uses CSS toggle via key 08 / d-pad."""
    return iter(())


def _stream_optics_terminal_build() -> Iterator[str]:
    yield from _optics_terminal_stream(_optics_terminal_build, mode="build")


def _stream_optics_terminal_help() -> Iterator[str]:
    yield from _optics_terminal_stream(_optics_terminal_help, mode="help")


def _stream_optics_terminal_menu(menu_index: int = 0) -> Iterator[str]:
    yield from _optics_terminal_stream(
        lambda: _optics_terminal_menu(menu_index),
        mode="menu",
    )


def _stream_optics_terminal_clear(current: str) -> Iterator[str]:
    """Erase display in paced chunks — inverse of the typewriter feed."""
    text = current or ""
    if not text:
        yield ""
        return
    chunk = max(1, len(text) // 36)
    for end in range(len(text), -1, -chunk):
        yield text[:end] + (_OPTICS_TERM_CURSOR if end else "")
        time.sleep(0.01)
    yield ""


TERM_KEYPAD_STREAMERS: dict[str, Callable[[], Iterator[str]]] = {}


def _term_key_id(index: int) -> str:
    return f"key{index:02d}"


def _term_keypad_label(index: int) -> str:
    """Home key is '01 Home'; 08 shows matrix glyph hint."""
    if index == 1:
        return "01 Home"
    if index == 8:
        return "08~"
    return f"{index:02d}"


def _term_key_is_defined_prog(key: str) -> bool:
    """True for assigned prog keys (02–24) that have a real function."""
    for index in TERM_KEYPAD_DEFINED:
        if index == 1:
            continue
        if _term_key_id(index) == key:
            return True
    return False


def _term_key_btn_classes(key: str, active: str) -> list[str]:
    """Black/white idle caps; matrix-green latch on active keys (never home)."""
    classes = ["vqc-optics-key"]
    if key in TERM_NAV_KEYS:
        classes.append("vqc-optics-dpad-key")
    if key == TERM_KEYPAD_HOME_KEY:
        classes.append("vqc-optics-key-home")
    elif key.startswith("dpad_"):
        classes.append("vqc-optics-key-dpad")
    if key == "clear":
        classes.append("vqc-optics-key-clear")
    if _term_key_is_defined_prog(key):
        classes.append("vqc-optics-key-defined")
    if key == active and key != TERM_KEYPAD_HOME_KEY:
        classes.append("active")
    return classes


def _term_keypad_btn_updates(active: str) -> tuple:
    return tuple(
        gr.update(elem_classes=_term_key_btn_classes(key_id, active))
        for key_id in TERM_KEYPAD_CONTROL_ORDER
    )


def _term_keypad_outputs(terminal_text: str, active: str, ui_state: dict | None = None) -> tuple:
    state = _default_term_ui_state() if ui_state is None else ui_state
    scanning = bool(state.get("scan"))
    return (
        gr.update(
            value=terminal_text,
            visible=not scanning,
            elem_classes=["vqc-optics-terminal-wrap", "vqc-optics-terminal"],
        ),
        gr.update(visible=scanning),
        *_term_keypad_btn_updates(active),
        active,
        state,
    )


def _term_yield_stream_then_release(
    stream: Iterator[str],
    *,
    active: str,
    ui_state: dict,
    release_delay: float | None = None,
) -> Iterator[tuple]:
    """Stream terminal text, latch while typing, release latch after a short pause."""
    delay = _OPTICS_TERM_RELEASE_DELAY_S if release_delay is None else release_delay
    last_partial = ""
    for partial in stream:
        last_partial = partial
        yield _term_keypad_outputs(partial, active, ui_state)
    time.sleep(delay)
    yield _term_keypad_outputs(last_partial, "", ui_state)


def _term_stream_with_latch(
    stream_fn: Callable[[], Iterator[str]],
    *,
    active: str,
    ui_state: dict,
) -> Iterator[tuple]:
    """Stream terminal text and latch matrix-green active state on the pressed key."""
    yield from _term_yield_stream_then_release(stream_fn(), active=active, ui_state=ui_state)


def _make_term_stream_click(
    active_key: str,
    stream_fn: Callable[[], Iterator[str]],
    *,
    menu_action: str | None = None,
):
    def handler(ui_state: dict) -> Iterator[tuple]:
        state = dict(ui_state) if ui_state else _default_term_ui_state()
        if menu_action is not None:
            state.update(
                {
                    "mode": TERM_UI_PAGE,
                    "index": _term_menu_index_for_action(menu_action),
                    "scan": menu_action == "scan",
                }
            )
        else:
            state["scan"] = False
        yield from _term_stream_with_latch(stream_fn, active=active_key, ui_state=state)

    return handler


def _make_term_clear_click(active_key: str):
    def handler(current: str, ui_state: dict) -> Iterator[tuple]:
        state = dict(ui_state) if ui_state else _default_term_ui_state()
        state["scan"] = False
        yield from _term_yield_stream_then_release(
            _stream_optics_terminal_clear(current),
            active=active_key,
            ui_state=state,
        )

    return handler


def _make_term_momentary_click(active_key: str, *, release_delay: float):
    """Brief latch flash — momentary, no maintained state."""

    def handler(current: str, ui_state: dict) -> Iterator[tuple]:
        state = dict(ui_state) if ui_state else _default_term_ui_state()
        yield _term_keypad_outputs(current, active_key, state)
        time.sleep(release_delay)
        yield _term_keypad_outputs(current, "", state)

    return handler


def _make_term_dpad_click(active_key: str):
    """D-pad click — navigate menu, confirm with SEL, brief matrix-green latch."""

    def handler(_current: str, ui_state: dict) -> Iterator[tuple]:
        state = dict(ui_state) if ui_state else _default_term_ui_state()
        mode = state.get("mode", TERM_UI_MENU)
        menu_index = int(state.get("index", 0))
        nav_delta = {
            "dpad_up": -1,
            "dpad_left": -1,
            "dpad_down": 1,
            "dpad_right": 1,
        }

        if active_key in nav_delta:
            if mode == TERM_UI_PAGE:
                menu_state = {"mode": TERM_UI_MENU, "index": menu_index, "scan": False}
                text = _optics_terminal_menu(menu_index)
            else:
                new_index = _term_menu_step(menu_index, nav_delta[active_key])
                menu_state = {"mode": TERM_UI_MENU, "index": new_index, "scan": False}
                text = _optics_terminal_menu(new_index)
            yield _term_keypad_outputs(text, active_key, menu_state)
            time.sleep(_OPTICS_TERM_RELEASE_DELAY_S)
            yield _term_keypad_outputs(text, "", menu_state)
            return

        if active_key == "dpad_select":
            if mode == TERM_UI_MENU:
                action, _keypad, _label, stream_fn = _term_menu_items()[menu_index]
                if action == "scan":
                    page_state = {
                        "mode": TERM_UI_PAGE,
                        "index": menu_index,
                        "scan": True,
                    }
                    yield _term_keypad_outputs("", "dpad_select", page_state)
                    time.sleep(_OPTICS_TERM_RELEASE_DELAY_S)
                    yield _term_keypad_outputs("", "", page_state)
                    return
                page_state = {
                    "mode": TERM_UI_PAGE,
                    "index": menu_index,
                    "scan": False,
                }
                yield from _term_yield_stream_then_release(
                    stream_fn(),
                    active="dpad_select",
                    ui_state=page_state,
                )
                return
            menu_state = {"mode": TERM_UI_MENU, "index": menu_index, "scan": False}
            text = _optics_terminal_menu(menu_index)
            yield _term_keypad_outputs(text, active_key, menu_state)
            time.sleep(_OPTICS_TERM_RELEASE_DELAY_S)
            yield _term_keypad_outputs(text, "", menu_state)

    return handler


def _make_term_latch_click(active_key: str):
    """Undefined keypad slots — latch matrix-green only, terminal unchanged."""

    def handler(current: str, ui_state: dict) -> tuple:
        state = dict(ui_state) if ui_state else _default_term_ui_state()
        state["scan"] = False
        return _term_keypad_outputs(current, active_key, state)

    return handler


def _make_activate_signal_scan(active_key: str, *, menu_action: str = "scan"):
    """Toggle CSS phosphor scan — one yield, no server animation loop."""

    def handler(ui_state: dict) -> Iterator[tuple]:
        state = dict(ui_state) if ui_state else _default_term_ui_state()
        state.update(
            {
                "mode": TERM_UI_PAGE,
                "index": _term_menu_index_for_action(menu_action),
                "scan": True,
            }
        )
        yield _term_keypad_outputs("", active_key, state)
        time.sleep(_OPTICS_TERM_RELEASE_DELAY_S)
        yield _term_keypad_outputs("", "", state)

    return handler


def _make_term_home_momentary():
    """Home — momentary return to the selection menu."""

    def handler(current_active: str, ui_state: dict) -> Iterator[tuple]:
        menu_state = {"mode": TERM_UI_MENU, "index": 0, "scan": False}
        menu_text = _optics_terminal_menu(0)
        yield _term_keypad_outputs(menu_text, current_active, menu_state)
        time.sleep(_OPTICS_TERM_RELEASE_DELAY_S)
        yield _term_keypad_outputs(menu_text, "", menu_state)

    return handler


def _boot_quote_prefix() -> str:
    """Pad so the quote types out near the middle of the terminal panel."""
    v_pad = max(0, (_BOOT_TERM_LINES - 1) // 2)
    h_pad = max(0, (_BOOT_TERM_COLS - len(BOOT_QUOTE_STRING)) // 2)
    return "\n" * v_pad + (" " * h_pad)


def _stream_term_boot() -> Iterator[tuple]:
    """One-shot startup: centered quote, dot countdown, then selection menu."""
    boot_state = _default_term_ui_state()
    shown = _boot_quote_prefix()
    yield _term_keypad_outputs(shown, "", boot_state)

    for ch in BOOT_QUOTE_STRING:
        shown += ch
        yield _term_keypad_outputs(shown + _OPTICS_TERM_CURSOR, "", boot_state)
        time.sleep(_BOOT_QUOTE_CHAR_DELAY_S)

    yield _term_keypad_outputs(shown, "", boot_state)
    time.sleep(_BOOT_POST_QUOTE_DELAY_S)

    for _ in range(_BOOT_DOT_COUNT):
        shown += "."
        yield _term_keypad_outputs(shown, "", boot_state)
        time.sleep(_BOOT_DOT_INTERVAL_S)

    menu_text = _optics_terminal_menu(0)
    yield _term_keypad_outputs(menu_text, "", boot_state)


def _register_term_keypad_streamers() -> None:
    TERM_KEYPAD_STREAMERS.update(
        {
            "home": _stream_optics_terminal_home,
            "status": _stream_optics_terminal_status,
            "scope": _stream_optics_terminal_scope,
            "directory": _stream_optics_terminal_directory,
            "results": _stream_optics_terminal_results,
            "build": _stream_optics_terminal_build,
            "help": _stream_optics_terminal_help,
            "scan": _stream_scan_stub,
            "strings": _stream_optics_terminal_strings,
            "physics": _stream_optics_terminal_physics,
            "tour": _stream_optics_terminal_tour,
            "figures": _stream_optics_terminal_figures,
        }
    )


_register_term_keypad_streamers()


def _external_tab_html(label: str, url: str, tab_id: str) -> str:
    """External Source bookmark — opens in a new tab."""
    return (
        f'<a href="{url}" class="vqc-source-tab" data-tab="{tab_id}" '
        f'target="_blank" rel="noopener noreferrer">{label}</a>'
    )


def _source_tab_btn_update(*, active: bool) -> gr.Update:
    """Animations tab — orange only when that page is open; otherwise green."""
    if active:
        return gr.update(interactive=False, elem_classes=["vqc-source-tab", "active"])
    return gr.update(interactive=True, elem_classes=["vqc-source-tab"], variant="secondary")


def _home_tab_update(*, on_demo_page: bool) -> gr.Update:
    """Live demo tab: orange on demo page, green link back from Animations."""
    if on_demo_page:
        return gr.update(interactive=False, elem_classes=["vqc-source-tab", "active"], variant="secondary")
    return gr.update(interactive=True, elem_classes=["vqc-source-tab"], variant="secondary")


def _close_links_panels() -> tuple:
    """Hide Links-bar panels (Claims, New here?, Theory) and reset tab highlights."""
    off = _source_tab_btn_update(active=False)
    return (
        gr.update(visible=False),
        off,
        False,
        gr.update(visible=False),
        off,
        False,
        gr.update(visible=False),
        off,
        False,
    )


def _toggle_theory(is_open: bool) -> tuple:
    show = not is_open
    off = _source_tab_btn_update(active=False)
    return (
        gr.update(visible=show),
        _source_tab_btn_update(active=show),
        show,
        gr.update(visible=False),
        off,
        False,
        gr.update(visible=False),
        off,
        False,
    )


def _minimize_theory() -> tuple:
    return gr.update(visible=False), _source_tab_btn_update(active=False), False


def _dismiss_welcome() -> tuple:
    return gr.update(visible=False), True


def _apply_preset(preset_key: str) -> tuple:
    p = get_preset_params(preset_key)
    meta = OPTIMIZATION_PRESETS.get(preset_key, OPTIMIZATION_PRESETS["standard"])
    est = estimate_runtime_sec(int(p["total_steps"]), int(p["steps_per_update"]))
    note = f"Preset: {meta['label']} — {meta['description']} (~{est:.0f}s est.)"
    return (
        p["total_steps"],
        p["steps_per_update"],
        p["learning_rate"],
        p["burst_factor_max"],
        p["use_fisher_modulation"],
        note,
    )


def _apply_run_mode(mode: str) -> tuple:
    p = get_run_mode_params(mode)
    spec = RUN_MODES.get(mode, RUN_MODES["quick"])
    note = f"Run mode: {spec['label']} — {spec['description']} ({spec['eta_hint']})"
    return (
        p["total_steps"],
        p["steps_per_update"],
        p["learning_rate"],
        p["burst_factor_max"],
        p["use_fisher_modulation"],
        p.get("compare_adam", False),
        p["audio_duration"],
        note,
        _runtime_hint(p["total_steps"], p["steps_per_update"], p.get("compare_adam", False)),
    )


def _runtime_hint(total_steps: float, steps_per_update: float, compare: bool) -> str:
    est = estimate_runtime_sec(int(total_steps), int(max(1, steps_per_update)), compare=bool(compare))
    suffix = " (×2 with RiemannianAdam compare)" if compare else ""
    return (
        f"**Estimated optimize time:** ~{est:.0f}s on HF cpu-basic"
        f" — approximate, varies with server load{suffix}"
    )


def _has_opt_history(history: dict | None) -> bool:
    return bool(history and history.get("step"))


def _trajectory_panel_visibility(
    run_mode: str,
    history: dict | None,
    traj_view: str,
    webgl_ok: bool,
    *,
    running: bool = False,
) -> tuple:
    """Hide WebGL 3D column during Quick runs; 2D stays visible live."""
    resolved = resolve_trajectory_mode(traj_view, webgl_ok)
    if run_mode == "quick" and resolved == "3d":
        if running or not _has_opt_history(history):
            return gr.update(visible=False), gr.update(visible=True)
    return gr.update(visible=True), gr.update(visible=False)


def _plot_3d_on_run_start(run_mode: str, traj_view: str, webgl_ok: bool) -> tuple:
    return _trajectory_panel_visibility(run_mode, None, traj_view, webgl_ok, running=True)


def _plot_3d_on_run_finish(run_mode: str, history: dict | None, traj_view: str, webgl_ok: bool) -> tuple:
    return _trajectory_panel_visibility(run_mode, history, traj_view, webgl_ok, running=False)


def _plot_3d_for_mode(run_mode: str, history: dict | None, traj_view: str, webgl_ok: bool) -> tuple:
    return _trajectory_panel_visibility(run_mode, history, traj_view, webgl_ok, running=False)


def _apply_run_mode_with_3d(mode: str, history: dict | None, traj_view: str, webgl_ok: bool) -> tuple:
    return _apply_run_mode(mode) + _plot_3d_for_mode(mode, history, traj_view, webgl_ok)


def _on_webgl_probe(probe: str) -> tuple:
    ok = str(probe).strip() != "0"
    if is_hf_space():
        view = "2d"
    elif not ok:
        view = "2d"
    else:
        view = "auto"
    return ok, gr.update(value=view), webgl_status_markdown(ok, view)


def _on_trajectory_view_change(view: str, webgl_ok: bool) -> str:
    return webgl_status_markdown(webgl_ok, view)


def _nav_to_page(page: str) -> tuple:
    """Switch between demo and animations screens; refresh Source tab highlights."""
    on_demo = page == "demo"
    closed = _close_links_panels()
    return (
        gr.update(visible=on_demo),
        gr.update(visible=not on_demo),
        _home_tab_update(on_demo_page=on_demo),
        _source_tab_btn_update(active=not on_demo),
        *closed,
        _home_tab_update(on_demo_page=on_demo),
        _source_tab_btn_update(active=not on_demo),
        page,
    )


def _toggle_newhere(is_open: bool) -> tuple:
    """Expand/collapse the beginner guide; close other link panels."""
    show = not is_open
    off = _source_tab_btn_update(active=False)
    return (
        gr.update(visible=show),
        _source_tab_btn_update(active=show),
        show,
        gr.update(visible=False),
        off,
        False,
        gr.update(visible=False),
        off,
        False,
    )


def _toggle_claims(is_open: bool) -> tuple:
    """Expand/collapse claims; close other link panels."""
    show = not is_open
    off = _source_tab_btn_update(active=False)
    return (
        gr.update(visible=show),
        _source_tab_btn_update(active=show),
        show,
        gr.update(visible=False),
        off,
        False,
        gr.update(visible=False),
        off,
        False,
    )


def _minimize_newhere() -> tuple:
    return (
        gr.update(visible=False),
        _source_tab_btn_update(active=False),
        False,
    )


def _minimize_claims() -> tuple:
    return (
        gr.update(visible=False),
        _source_tab_btn_update(active=False),
        False,
    )


def _build_vqc_theme() -> gr.themes.Base:
    """Dark transparent theme — mystery gold/purple (HF-safe)."""
    return (
        gr.themes.Base(
            primary_hue=gr.themes.colors.amber,
            secondary_hue=gr.themes.colors.purple,
            neutral_hue=gr.themes.colors.zinc,
        )
        .set(
            body_background_fill="transparent",
            body_background_fill_dark="transparent",
            background_fill_primary="transparent",
            background_fill_primary_dark="transparent",
            background_fill_secondary="transparent",
            background_fill_secondary_dark="transparent",
            block_background_fill=_VQC_FIELD_FILL,
            block_background_fill_dark=_VQC_FIELD_FILL,
            panel_background_fill=_VQC_FIELD_FILL,
            panel_background_fill_dark=_VQC_FIELD_FILL,
            input_background_fill=_VQC_FIELD_FILL,
            input_background_fill_dark=_VQC_FIELD_FILL,
            body_text_color="#e8e0f8",
            body_text_color_dark="#e8e0f8",
            block_label_text_color="#c9b8ff",
            block_label_text_color_dark="#c9b8ff",
            block_title_text_color="#f0e6ff",
            block_title_text_color_dark="#f0e6ff",
            border_color_primary="rgba(255, 255, 255, 0.12)",
            border_color_primary_dark="rgba(255, 255, 255, 0.12)",
            button_primary_background_fill="#c9a227",
            button_primary_background_fill_dark="#c9a227",
            button_primary_text_color="#ffffff",
            button_primary_text_color_dark="#ffffff",
            button_secondary_background_fill="rgba(28, 22, 48, 0.92)",
            button_secondary_background_fill_dark="rgba(28, 22, 48, 0.92)",
            button_secondary_text_color="#e8e0f8",
            button_secondary_text_color_dark="#e8e0f8",
            checkbox_label_background_fill="transparent",
            checkbox_label_background_fill_dark="transparent",
            checkbox_label_background_fill_hover="transparent",
            checkbox_label_background_fill_hover_dark="transparent",
            slider_color=_VQC_ACCENT,
            slider_color_dark=_VQC_ACCENT,
            link_text_color=_VQC_ACCENT,
            link_text_color_dark=_VQC_ACCENT,
            link_text_color_hover="#d4b8ff",
            link_text_color_hover_dark="#d4b8ff",
            link_text_color_active=_VQC_ACCENT,
            link_text_color_active_dark=_VQC_ACCENT,
            link_text_color_visited=_VQC_ACCENT,
            link_text_color_visited_dark=_VQC_ACCENT,
        )
    )


# Wallpaper: #vqc-wallpaper (body child) + body::before fallback — cover, fixed to viewport.
WALLPAPER_HEAD = f"""
<style id="vqc-wallpaper-style">
#vqc-wallpaper {{
    position: fixed !important;
    top: 0 !important;
    left: 0 !important;
    width: 100vw !important;
    height: 100vh !important;
    z-index: -9999 !important;
    pointer-events: none !important;
    background-color: #0a0818 !important;
    background-image: url('{WALLPAPER_URL}') !important;
    background-size: cover !important;
    background-position: center center !important;
    background-repeat: no-repeat !important;
}}
</style>
<script>
(function() {{
    function mountWallpaper() {{
        if (document.getElementById('vqc-wallpaper')) return;
        var wp = document.createElement('div');
        wp.id = 'vqc-wallpaper';
        wp.setAttribute('aria-hidden', 'true');
        document.body.insertBefore(wp, document.body.firstChild);
    }}
    if (document.body) mountWallpaper();
    document.addEventListener('DOMContentLoaded', mountWallpaper);
    window.addEventListener('load', mountWallpaper);
}})();
</script>
<script>
(function() {{
    var KEY = '6string-optimizer-welcome-seen';
    function collapseLimitations() {{
        var acc = document.querySelector('.vqc-limitations-acc');
        if (!acc) return;
        var btn = acc.querySelector('button.label-wrap, summary, [aria-expanded]');
        if (btn && btn.getAttribute('aria-expanded') === 'true') btn.click();
    }}
    function markWelcomeSeen() {{
        try {{ localStorage.setItem(KEY, '1'); }} catch (e) {{}}
        collapseLimitations();
    }}
    function bindWelcomeTriggers() {{
        document.querySelectorAll('.vqc-welcome-seen-trigger').forEach(function(el) {{
            if (el.dataset.vqcWelcomeBound) return;
            el.dataset.vqcWelcomeBound = '1';
            el.addEventListener('click', markWelcomeSeen);
        }});
    }}
    function initReturningUser() {{
        try {{
            if (localStorage.getItem(KEY) === '1') collapseLimitations();
        }} catch (e) {{}}
        bindWelcomeTriggers();
    }}
    var obs = new MutationObserver(initReturningUser);
    function startReturningUX() {{
        initReturningUser();
        if (document.body) obs.observe(document.body, {{ childList: true, subtree: true }});
    }}
    if (document.readyState === 'loading') {{
        document.addEventListener('DOMContentLoaded', startReturningUX);
    }} else {{
        startReturningUX();
    }}
}})();
</script>
<script>
(function() {{
    function markWebGLFailed() {{
        try {{ localStorage.setItem('6string-webgl-failed', '1'); }} catch (e) {{}}
        var status = document.querySelector('.vqc-webgl-status');
        if (status) {{
            status.innerHTML = '⚠ <strong>WebGL error detected</strong> — switch <strong>Trajectory view</strong> to <strong>2D (WebGL-safe)</strong>.';
        }}
    }}
    function scanPlotlyWebGLErrors() {{
        var plots = document.querySelectorAll('.vqc-plot3d-panel, .js-plotly-plot');
        plots.forEach(function(plot) {{
            var text = plot.innerText || '';
            if (text.indexOf('WebGL is not supported') >= 0) markWebGLFailed();
        }});
    }}
    setInterval(scanPlotlyWebGLErrors, 2500);
    var obs = new MutationObserver(scanPlotlyWebGLErrors);
    function start() {{
        scanPlotlyWebGLErrors();
        if (document.body) obs.observe(document.body, {{ childList: true, subtree: true }});
    }}
    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start);
    else start();
}})();
</script>
{KATEX_CDN}
"""

MOBILE_CSS = """
@media (max-width: 900px) {
  .gradio-container .vqc-optics-prog-row,
  .gradio-container .vqc-optics-dpad-row {
    flex-wrap: wrap !important;
    gap: 0.35rem !important;
  }
  .gradio-container .vqc-optics-prog-row button,
  .gradio-container .vqc-optics-dpad-row button {
    min-height: 2.6rem !important;
    font-size: 0.72rem !important;
    flex: 1 1 18% !important;
  }
  .gradio-container .vqc-optics-dial-row {
    flex-direction: column !important;
  }
  .gradio-container .vqc-nav-spreadsheet-row {
    flex-wrap: wrap !important;
  }
  .gradio-container .vqc-optics-terminal-wrap textarea {
    font-size: 0.7rem !important;
  }
  .gradio-container .vqc-screencast-wrap {
    grid-template-columns: 1fr !important;
  }
  .gradio-container .vqc-welcome-panel {
    padding: 0.5rem !important;
  }
}
@media (max-width: 480px) {
  .gradio-container .vqc-optics-brand {
    font-size: 1.1rem !important;
  }
  .gradio-container .vqc-receiver-preset {
    font-size: 0.65rem !important;
    padding: 0.35rem 0.4rem !important;
  }
}
"""

HFB_CSS = f"""
:root, :root .dark {{
    --body-background-fill: transparent !important;
    --background-fill-primary: transparent !important;
    --background-fill-secondary: transparent !important;
    --block-background-fill: {_VQC_FIELD_FILL} !important;
    --panel-background-fill: {_VQC_FIELD_FILL} !important;
    --input-background-fill: {_VQC_FIELD_FILL} !important;
    --body-text-color: #e8e0f8 !important;
    --block-label-text-color: #c9b8ff !important;
    --block-title-text-color: #f0e6ff !important;
    --border-color-primary: rgba(255, 255, 255, 0.12) !important;
    --link-text-color: {_VQC_ACCENT} !important;
    --link-text-color-hover: #d4b8ff !important;
    --link-text-color-active: {_VQC_ACCENT} !important;
    --link-text-color-visited: {_VQC_ACCENT} !important;
    color-scheme: dark;
}}
html {{
    background-color: #0a0818 !important;
    min-height: 100% !important;
}}
body {{
    background: transparent !important;
    background-color: transparent !important;
    color: #e8e0f8 !important;
    min-height: 100vh !important;
    width: 100% !important;
    overflow-x: hidden !important;
    position: relative !important;
}}
body::before {{
    content: "" !important;
    position: fixed !important;
    top: 0 !important;
    left: 0 !important;
    width: 100vw !important;
    height: 100vh !important;
    z-index: -9998 !important;
    pointer-events: none !important;
    background-color: #0a0818 !important;
    background-image: url('{WALLPAPER_URL}') !important;
    background-size: cover !important;
    background-position: center center !important;
    background-repeat: no-repeat !important;
}}
#root, .app {{
    background: transparent !important;
    background-color: transparent !important;
    min-height: 0 !important;
    height: auto !important;
    width: 100% !important;
}}
.gradio-container {{
    position: relative !important;
    width: 100% !important;
    max-width: 100% !important;
    min-height: 0 !important;
    height: auto !important;
    background: transparent !important;
    background-color: transparent !important;
}}
footer {{
    background: transparent !important;
}}
.gradio-container .main,
.gradio-container .wrap,
.gradio-container .contain,
.gradio-container .tabs,
.gradio-container .tabitem,
.gradio-container .form,
.gradio-container .column,
.gradio-container .row,
.gradio-container .gr-group,
.gradio-container label.wrap,
.gradio-container .label-wrap {{
    background: transparent !important;
    background-color: transparent !important;
    box-shadow: none !important;
}}
.gradio-container .block {{
    width: 100% !important;
    max-width: 100% !important;
    box-sizing: border-box !important;
    background-color: {_VQC_FIELD_FILL} !important;
    border: 1px solid rgba(255, 255, 255, 0.08) !important;
    border-radius: 10px !important;
    backdrop-filter: blur(4px);
    -webkit-backdrop-filter: blur(4px);
}}
.gradio-container .markdown,
.gradio-container .prose,
.gradio-container .markdown p,
.gradio-container .markdown h1,
.gradio-container .markdown h2,
.gradio-container .markdown li {{
    color: #e8e0f8 !important;
}}
.gradio-container .vqc-source-tabs-row {{
    display: flex !important;
    flex-wrap: wrap !important;
    align-items: center !important;
    gap: 0.45rem 0.65rem !important;
    margin: 0.35rem 0 0.1rem 0 !important;
    background: transparent !important;
    border: none !important;
    box-shadow: none !important;
}}
.gradio-container .vqc-source-nav-row {{
    margin: 0 0 0.1rem 0 !important;
}}
.gradio-container .vqc-links-panel {{
    margin: 0 0 0.35rem 0 !important;
    padding: 0.65rem 0.85rem !important;
}}
.gradio-container .vqc-links-panel .markdown h3 {{
    margin: 0 !important;
    font-size: 1rem !important;
    color: #f0e6ff !important;
}}
.gradio-container .intro-walkthrough {{
    position: relative;
    margin: 0.5rem 0 0.75rem 0;
    padding: 0.55rem 0.65rem 0.7rem 0.65rem;
    border: 1px solid rgba(255, 176, 0, 0.35);
    border-radius: 8px;
    background: rgba(10, 10, 10, 0.55);
    font-family: "Courier New", monospace;
    font-size: 0.82rem;
    color: #ffb000;
    overflow: hidden;
}}
.gradio-container .intro-step {{
    opacity: 0;
    transform: translateY(6px);
    padding: 0.15rem 0;
    animation: intro-step-cycle 20s infinite;
}}
.gradio-container .intro-step span {{
    color: #ff8800;
    margin-right: 0.35rem;
}}
.gradio-container .intro-step-1 {{ animation-delay: 0s; }}
.gradio-container .intro-step-2 {{ animation-delay: 5s; }}
.gradio-container .intro-step-3 {{ animation-delay: 10s; }}
.gradio-container .intro-step-4 {{ animation-delay: 15s; }}
.gradio-container .intro-progress {{
    position: absolute;
    bottom: 0;
    left: 0;
    height: 2px;
    width: 0;
    background: linear-gradient(90deg, #ffb000, #ff6600);
    animation: intro-progress-bar 20s linear infinite;
}}
@keyframes intro-step-cycle {{
    0%, 18% {{ opacity: 1; transform: translateY(0); }}
    22%, 100% {{ opacity: 0; transform: translateY(-4px); }}
}}
@keyframes intro-progress-bar {{
    0% {{ width: 0; }}
    100% {{ width: 100%; }}
}}
.gradio-container .vqc-utility-row {{
    align-items: center !important;
    gap: 0.65rem !important;
    margin: 0.25rem 0 0.35rem 0 !important;
}}
.gradio-container .vqc-utility-row > .block,
.gradio-container .vqc-utility-row > .form {{
    background: transparent !important;
    border: none !important;
    box-shadow: none !important;
}}
.gradio-container button.vqc-utility-btn {{
    flex: 0 0 auto !important;
    opacity: 0.85 !important;
}}
.gradio-container .vqc-utility-hint {{
    font-size: 0.78rem !important;
    color: #a89cc8 !important;
    margin: 0 !important;
}}
.gradio-container .vqc-run-mode-radio label {{
    line-height: 1.35 !important;
}}
.gradio-container .vqc-webgl-status {{
    margin: 0.2rem 0 0.45rem 0 !important;
    padding: 0.45rem 0.65rem !important;
    border-radius: 8px !important;
    border: 1px solid rgba(255, 176, 0, 0.25) !important;
    background: rgba(10, 10, 10, 0.4) !important;
    font-size: 0.84rem !important;
    color: #c9b8ff !important;
}}
.gradio-container .vqc-webgl-status:empty {{
    display: none !important;
}}
.gradio-container .vqc-trajectory-view-radio label {{
    line-height: 1.3 !important;
}}
.gradio-container .vqc-panel-header-row {{
    display: flex !important;
    align-items: center !important;
    justify-content: space-between !important;
    gap: 0.5rem !important;
    width: 100% !important;
    margin: 0 0 0.35rem 0 !important;
}}
.gradio-container .vqc-panel-header-row > .block,
.gradio-container .vqc-panel-header-row > .form {{
    background: transparent !important;
    border: none !important;
    box-shadow: none !important;
    padding: 0 !important;
    margin: 0 !important;
    flex: 1 1 auto !important;
    width: auto !important;
}}
.gradio-container button.vqc-panel-minimize {{
    flex: 0 0 auto !important;
    min-width: 2.1rem !important;
    padding: 0.2rem 0.6rem !important;
    border-radius: 999px !important;
    border: 1px solid {_VQC_TAB_GREEN_BORDER} !important;
    background: {_VQC_TAB_GREEN_BG} !important;
    color: {_VQC_TAB_GREEN_TEXT} !important;
    -webkit-text-fill-color: {_VQC_TAB_GREEN_TEXT} !important;
    font-weight: 700 !important;
    font-size: 0.85rem !important;
    line-height: 1 !important;
    box-shadow: none !important;
    opacity: 0.8 !important;
    cursor: pointer !important;
}}
.gradio-container button.vqc-panel-minimize:hover {{
    border-color: {_VQC_TAB_ORANGE_BORDER} !important;
    background: {_VQC_TAB_ORANGE_BG} !important;
    color: {_VQC_TAB_ORANGE_TEXT} !important;
    -webkit-text-fill-color: {_VQC_TAB_ORANGE_TEXT} !important;
}}
.gradio-container .vqc-source-tabs-row > .block,
.gradio-container .vqc-source-tabs-row > .form,
.gradio-container .vqc-source-tabs-row .block,
.gradio-container .vqc-source-tabs-row .form {{
    background: transparent !important;
    border: none !important;
    box-shadow: none !important;
    padding: 0 !important;
    margin: 0 !important;
    min-width: 0 !important;
    width: auto !important;
    flex: 0 0 auto !important;
}}
.gradio-container .vqc-source-tabs-row .html-container {{
    padding: 0 !important;
    margin: 0 !important;
}}
.gradio-container .vqc-source-tabs-row button.vqc-source-tab.secondary,
.gradio-container .vqc-source-tabs-row button.vqc-source-tab.secondary:hover,
.gradio-container .vqc-source-tabs-row button.vqc-source-tab.secondary:focus {{
    border: none !important;
    outline: none !important;
    background: transparent !important;
    box-shadow: none !important;
}}
.gradio-container .vqc-source-label {{
    color: #e8e0f8 !important;
    font-size: 0.92rem !important;
    font-weight: 600 !important;
    margin-right: 0.15rem !important;
    line-height: 1.2 !important;
}}
.gradio-container .vqc-source-tab,
.gradio-container .vqc-source-tabs-row button.vqc-source-tab,
.gradio-container .vqc-source-tabs-row button.vqc-source-tab span,
.gradio-container .vqc-nav-cell a.vqc-source-tab {{
    display: inline !important;
    padding: 0 !important;
    border: none !important;
    border-radius: 0 !important;
    background: transparent !important;
    background-color: transparent !important;
    box-shadow: none !important;
    color: {_VQC_MATRIX_GREEN} !important;
    -webkit-text-fill-color: {_VQC_MATRIX_GREEN} !important;
    text-decoration: underline !important;
    text-decoration-color: {_VQC_MATRIX_GREEN} !important;
    text-underline-offset: 0.18em !important;
    font-weight: 600 !important;
    font-size: 0.92rem !important;
    line-height: 1.35 !important;
    letter-spacing: normal !important;
    text-transform: none !important;
    white-space: nowrap !important;
    min-height: unset !important;
    height: auto !important;
    width: auto !important;
    margin: 0 !important;
    opacity: 1 !important;
    text-shadow: 0 0 6px rgba(51, 255, 102, 0.25) !important;
    transition: color 0.15s ease, text-decoration-color 0.15s ease, opacity 0.15s ease;
}}
.gradio-container a.vqc-source-tab:hover,
.gradio-container .vqc-source-tabs-row button.vqc-source-tab:not(.active):hover,
.gradio-container .vqc-source-tabs-row button.vqc-source-tab:not(.active):hover span {{
    color: #7dff9a !important;
    -webkit-text-fill-color: #7dff9a !important;
    text-decoration-color: #7dff9a !important;
    background: transparent !important;
    text-decoration: underline !important;
}}
.gradio-container .vqc-source-tabs-row button.vqc-source-tab {{
    cursor: pointer !important;
    font-family: inherit !important;
}}
.gradio-container .vqc-source-tabs-row button.vqc-source-tab:disabled:not(.active),
.gradio-container .vqc-source-tabs-row button.vqc-source-tab[disabled]:not(.active),
.gradio-container .vqc-source-tabs-row button.vqc-source-tab.secondary:disabled:not(.active),
.gradio-container .vqc-source-tabs-row button.vqc-source-tab:disabled:not(.active) span,
.gradio-container .vqc-source-tabs-row button.vqc-source-tab[disabled]:not(.active) span {{
    cursor: pointer !important;
    color: {_VQC_MATRIX_GREEN} !important;
    -webkit-text-fill-color: {_VQC_MATRIX_GREEN} !important;
    text-decoration-color: {_VQC_MATRIX_GREEN} !important;
    background: transparent !important;
    text-decoration: underline !important;
}}
.gradio-container .vqc-source-tab.active,
.gradio-container .vqc-source-tabs-row button.vqc-source-tab.active,
.gradio-container .vqc-source-tabs-row button.vqc-source-tab.active span,
.gradio-container .vqc-source-tab.active:hover,
.gradio-container .vqc-source-tabs-row button.vqc-source-tab.active:hover,
.gradio-container .vqc-source-tabs-row button.vqc-source-tab.active:hover span,
.gradio-container a.vqc-source-tab.active {{
    color: {_VQC_LOGO_GOLD} !important;
    -webkit-text-fill-color: {_VQC_LOGO_GOLD} !important;
    text-decoration-color: {_VQC_LOGO_GOLD} !important;
    background: transparent !important;
    text-decoration: underline !important;
    text-decoration-thickness: 2px !important;
    cursor: default !important;
    opacity: 1 !important;
    text-shadow: 0 0 8px rgba(201, 162, 39, 0.45) !important;
}}
.gradio-container .vqc-source-tabs-row button.vqc-source-tab.active:disabled,
.gradio-container .vqc-source-tabs-row button.vqc-source-tab.active[disabled],
.gradio-container .vqc-source-tabs-row button.vqc-source-tab.active:disabled span,
.gradio-container .vqc-source-tabs-row button.vqc-source-tab.active[disabled] span {{
    color: {_VQC_LOGO_GOLD} !important;
    -webkit-text-fill-color: {_VQC_LOGO_GOLD} !important;
    text-decoration-color: {_VQC_LOGO_GOLD} !important;
    background: transparent !important;
    text-decoration: underline !important;
    text-decoration-thickness: 2px !important;
    cursor: default !important;
}}
.gradio-container .vqc-source-tabs-row button.vqc-source-tab.active::before {{
    content: none !important;
    display: none !important;
}}
.gradio-container a:hover:not(.vqc-source-tab),
.gradio-container .markdown a:hover:not(.vqc-source-tab),
.gradio-container .prose a:hover:not(.vqc-source-tab) {{
    color: #d4b8ff !important;
    -webkit-text-fill-color: #d4b8ff !important;
}}
.gradio-container .vqc-build-label {{
    color: #a89ec8 !important;
    font-size: 0.9rem;
    margin: 0 0 0.5rem 0;
}}
.gradio-container .vqc-animations-page .markdown h2 {{
    font-size: 1.35rem !important;
    margin: 0.15rem 0 0.35rem 0 !important;
}}
.gradio-container .vqc-animations-page .markdown p {{
    font-size: 0.92rem !important;
    margin: 0.15rem 0 0.35rem 0 !important;
    line-height: 1.45 !important;
}}
.gradio-container .vqc-animations-page,
.gradio-container .vqc-animations-page > .block,
.gradio-container .vqc-animations-page .html-container {{
    width: 100% !important;
    max-width: 100% !important;
}}
.gradio-container .vqc-screencast-wrap {{
    display: grid !important;
    grid-template-columns: repeat(2, minmax(0, 1fr)) !important;
    gap: 0.75rem !important;
    width: 100% !important;
    max-width: 100% !important;
    margin: 0.25rem 0 0.5rem 0 !important;
    padding: 0 !important;
    box-sizing: border-box !important;
}}
.gradio-container .vqc-screencast-video {{
    width: 100% !important;
    min-width: 0 !important;
    height: auto !important;
    aspect-ratio: 16 / 9 !important;
    max-height: min(36vh, 360px) !important;
    object-fit: contain !important;
    border-radius: 8px !important;
    display: block !important;
    background: rgba(10, 8, 24, 0.35) !important;
}}
.gradio-container .vqc-optics-panel {{
    background: linear-gradient(165deg, #2a1838 0%, #1a1028 38%, #120c18 100%) !important;
    border: 3px solid #6a4c93 !important;
    border-radius: 14px !important;
    box-shadow:
        inset 0 2px 8px rgba(255, 220, 150, 0.08),
        inset 0 -4px 14px rgba(0, 0, 0, 0.55),
        0 8px 22px rgba(0, 0, 0, 0.45) !important;
    padding: 0 1rem 1rem !important;
    margin: 0.5rem 0 0.75rem 0 !important;
    gap: 0 !important;
}}
.gradio-container .vqc-optics-panel > .gap {{
    display: none !important;
    height: 0 !important;
    margin: 0 !important;
    padding: 0 !important;
}}
.gradio-container .vqc-optics-panel > .block,
.gradio-container .vqc-optics-panel .block {{
    background: transparent !important;
    border: none !important;
    box-shadow: none !important;
}}
.gradio-container .vqc-optics-panel-header {{
    display: flex !important;
    flex-wrap: wrap !important;
    align-items: center !important;
    gap: 0.75rem 1.1rem !important;
    margin: 0 0 0 0 !important;
    padding: 0.7rem 0.85rem 1.35rem !important;
    border: none !important;
    border-bottom: 1px solid rgba(106, 76, 147, 0.55) !important;
    border-radius: 10px 10px 0 0 !important;
    background: linear-gradient(180deg, #1f1428 0%, #0f0a14 100%) !important;
    box-shadow: inset 0 0 18px rgba(0, 0, 0, 0.65) !important;
    width: 100% !important;
    min-height: 5.25rem !important;
}}
.gradio-container .vqc-optics-panel-header > .block,
.gradio-container .vqc-optics-panel-header > .form,
.gradio-container .vqc-optics-panel-header .block,
.gradio-container .vqc-optics-panel-header .form {{
    background: transparent !important;
    border: none !important;
    box-shadow: none !important;
    padding: 0 !important;
    margin: 0 !important;
    min-width: 0 !important;
}}
.gradio-container .vqc-optics-panel-header > .block:first-child,
.gradio-container .vqc-optics-panel-header > .form:first-child {{
    flex: 0 0 auto !important;
    width: auto !important;
}}
.gradio-container .vqc-optics-panel-nav {{
    flex: 1 1 18rem !important;
    display: flex !important;
    flex-direction: column !important;
    gap: 0.28rem !important;
    justify-content: center !important;
    min-width: 0 !important;
    width: auto !important;
}}
.gradio-container .vqc-optics-panel-nav > .block,
.gradio-container .vqc-optics-panel-nav > .form {{
    background: transparent !important;
    border: none !important;
    box-shadow: none !important;
    padding: 0 !important;
    margin: 0 !important;
    width: 100% !important;
}}
.gradio-container .vqc-optics-panel-nav .vqc-source-tabs-row {{
    margin: 0 !important;
}}
.gradio-container .vqc-nav-spreadsheet-row {{
    display: grid !important;
    grid-template-columns: 4.75rem repeat(5, minmax(4.5rem, 1fr)) !important;
    gap: 0.2rem 0.45rem !important;
    align-items: center !important;
    width: 100% !important;
    margin: 0 !important;
    padding: 0 !important;
}}
.gradio-container .vqc-nav-spreadsheet-row > .block,
.gradio-container .vqc-nav-spreadsheet-row > .form,
.gradio-container .vqc-nav-spreadsheet-row > .column {{
    background: transparent !important;
    border: none !important;
    box-shadow: none !important;
    padding: 0 !important;
    margin: 0 !important;
    min-width: 0 !important;
    width: 100% !important;
}}
.gradio-container .vqc-nav-row-label {{
    justify-self: end !important;
    align-self: center !important;
    text-align: right !important;
    padding-right: 0.15rem !important;
}}
.gradio-container .vqc-nav-cell,
.gradio-container .vqc-nav-cell > .block,
.gradio-container .vqc-nav-cell > .form {{
    display: flex !important;
    align-items: center !important;
    justify-content: center !important;
    text-align: center !important;
    min-height: 1.55rem !important;
    width: 100% !important;
    margin: 0 auto !important;
    padding: 0.1rem 0.2rem !important;
}}
.gradio-container .vqc-nav-cell .html-container,
.gradio-container .vqc-nav-cell .html-container p {{
    margin: 0 !important;
    padding: 0 !important;
    text-align: center !important;
    width: 100% !important;
}}
.gradio-container .vqc-nav-cell-empty {{
    visibility: hidden !important;
}}
.gradio-container .vqc-optics-logo {{
    display: flex !important;
    flex-direction: column !important;
    align-items: flex-start !important;
    gap: 0.1rem !important;
    min-width: 10.5rem !important;
    padding-right: 0.65rem !important;
    border-right: 1px solid rgba(107, 79, 29, 0.45) !important;
}}
.gradio-container .vqc-optics-brand {{
    font-size: 0.62rem !important;
    letter-spacing: 0.28em !important;
    color: {_VQC_LOGO_GOLD} !important;
    font-weight: 700 !important;
}}
.gradio-container .vqc-optics-panel-title {{
    font-size: 1.15rem !important;
    letter-spacing: 0.12em !important;
    color: #f5e6c8 !important;
    font-weight: 700 !important;
    text-transform: uppercase !important;
    text-shadow: 0 0 10px rgba(255, 180, 80, 0.35) !important;
}}
.gradio-container .vqc-optics-subtitle {{
    font-size: 0.68rem !important;
    letter-spacing: 0.22em !important;
    color: #9a8458 !important;
}}
.gradio-container .vqc-optics-terminal-caption {{
    font-size: 0.58rem !important;
    letter-spacing: 0.18em !important;
    color: #3dff7a !important;
    text-shadow: 0 0 8px rgba(61, 255, 122, 0.45) !important;
    margin-top: 0.1rem !important;
}}
.gradio-container .vqc-optics-panel .vqc-optics-terminal textarea,
.gradio-container .vqc-optics-panel .vqc-optics-terminal input {{
    background: rgba(2, 10, 4, 0.1) !important;
    border: 2px inset #1a4d2a !important;
    color: #33ff66 !important;
    -webkit-text-fill-color: #33ff66 !important;
    font-family: "Courier New", Courier, monospace !important;
    font-size: 0.78rem !important;
    line-height: 1.45 !important;
    text-shadow: 0 0 6px rgba(51, 255, 102, 0.35) !important;
    box-shadow:
        inset 0 0 18px rgba(0, 40, 12, 0.65),
        0 0 12px rgba(51, 255, 102, 0.08) !important;
    border-radius: 6px !important;
    caret-color: #33ff66 !important;
}}
.gradio-container .vqc-optics-panel .vqc-optics-terminal .label-wrap span {{
    color: #3dff7a !important;
    letter-spacing: 0.14em !important;
    text-shadow: 0 0 6px rgba(61, 255, 122, 0.35) !important;
}}
.gradio-container .vqc-optics-panel .vqc-optics-terminal-wrap {{
    background: rgba(2, 10, 4, 0.1) !important;
    border: 1px solid #1a4d2a !important;
    border-radius: 10px !important;
    padding: 0.5rem 0.6rem 0.45rem !important;
    margin: 0.55rem 0 0.55rem 0 !important;
}}
.gradio-container .vqc-animations-nav-row {{
    margin: 0.35rem 0 0.65rem 0 !important;
}}
.gradio-container .vqc-optics-panel .vqc-optics-terminal textarea {{
    min-height: 13.5rem !important;
    white-space: pre !important;
    overflow-x: hidden !important;
}}
.gradio-container .myst-signal-scan {{
    position: relative !important;
    width: 100% !important;
    min-height: 14rem !important;
    margin: 0.55rem 0 !important;
    padding: 0.65rem 0.75rem !important;
    background: rgba(2, 10, 4, 0.45) !important;
    border: 2px inset #1a4d2a !important;
    border-radius: 6px !important;
    overflow: hidden !important;
    box-sizing: border-box !important;
}}
.gradio-container .myst-signal-scanlines {{
    position: absolute !important;
    inset: 0 !important;
    pointer-events: none !important;
    background: repeating-linear-gradient(
        0deg,
        transparent 0px,
        transparent 2px,
        rgba(51, 255, 102, 0.04) 2px,
        rgba(51, 255, 102, 0.04) 4px
    ) !important;
    animation: myst-scan-drift 12s linear infinite !important;
}}
.gradio-container .myst-signal-beam {{
    position: absolute !important;
    left: 0 !important;
    right: 0 !important;
    height: 18% !important;
    pointer-events: none !important;
    background: linear-gradient(
        180deg,
        transparent 0%,
        rgba(51, 255, 102, 0.12) 45%,
        rgba(51, 255, 102, 0.22) 50%,
        rgba(51, 255, 102, 0.12) 55%,
        transparent 100%
    ) !important;
    animation: myst-scan-beam 4s ease-in-out infinite !important;
}}
.gradio-container .myst-signal-body {{
    position: relative !important;
    z-index: 1 !important;
    margin: 0 !important;
    color: #33ff66 !important;
    font-family: "Courier New", Courier, monospace !important;
    font-size: 0.78rem !important;
    line-height: 1.45 !important;
    text-shadow: 0 0 6px rgba(51, 255, 102, 0.35) !important;
    white-space: pre-wrap !important;
    animation: myst-phosphor-flicker 3.5s ease-in-out infinite !important;
}}
@keyframes myst-scan-drift {{
    0% {{ transform: translateY(-8%); }}
    100% {{ transform: translateY(8%); }}
}}
@keyframes myst-scan-beam {{
    0%, 100% {{ top: -20%; }}
    50% {{ top: 85%; }}
}}
@keyframes myst-phosphor-flicker {{
    0%, 100% {{ opacity: 1; }}
    48% {{ opacity: 0.92; }}
    50% {{ opacity: 0.78; }}
    52% {{ opacity: 0.95; }}
}}
.gradio-container .vqc-optics-keypad {{
    background: linear-gradient(180deg, #16120c 0%, #0a0806 100%) !important;
    border: 2px inset #3d3020 !important;
    border-radius: 10px !important;
    padding: 0.42rem 0.38rem 0.48rem !important;
    margin: 0 0 0.65rem 0 !important;
    box-shadow: inset 0 2px 10px rgba(0, 0, 0, 0.55) !important;
}}
.gradio-container .vqc-optics-keypad > .block,
.gradio-container .vqc-optics-keypad .block {{
    background: transparent !important;
    border: none !important;
    box-shadow: none !important;
    padding: 0 !important;
    margin: 0 !important;
}}
.gradio-container .vqc-optics-dpad-group {{
    margin: 0 0 0.28rem 0 !important;
    padding: 0 0 0.12rem 0 !important;
}}
.gradio-container .vqc-optics-panel .vqc-optics-dpad-row,
.gradio-container .vqc-optics-panel .vqc-optics-prog-row {{
    gap: 0.2rem !important;
    margin: 0 0 0.2rem 0 !important;
    justify-content: stretch !important;
    width: 100% !important;
}}
.gradio-container .vqc-optics-keypad button.vqc-optics-key,
.gradio-container .vqc-optics-keypad button.vqc-optics-key span {{
    font-family: "Courier New", Courier, monospace !important;
    font-size: 1.44rem !important;
    font-weight: 700 !important;
    line-height: 1.1 !important;
}}
.gradio-container .vqc-optics-keypad button.vqc-optics-key {{
    flex: 1 1 0 !important;
    min-width: 0 !important;
    max-width: none !important;
    min-height: 3rem !important;
    height: 3rem !important;
    max-height: 3rem !important;
    aspect-ratio: auto !important;
    background: #000000 !important;
    border: none !important;
    border-radius: 8px !important;
    color: #ffffff !important;
    -webkit-text-fill-color: #ffffff !important;
    letter-spacing: 0.03em !important;
    padding: 0.28rem 0.1rem !important;
    box-shadow: none !important;
}}
.gradio-container .vqc-optics-panel .vqc-optics-dpad-row button.vqc-optics-key-dpad,
.gradio-container .vqc-optics-panel .vqc-optics-dpad-row button.vqc-optics-key-dpad span {{
    font-family: system-ui, -apple-system, "Segoe UI", sans-serif !important;
    font-size: 1.44rem !important;
    font-weight: 700 !important;
    line-height: 1 !important;
}}
.gradio-container .vqc-optics-panel .vqc-optics-dpad-row button.vqc-optics-key-dpad:active,
.gradio-container .vqc-optics-panel .vqc-optics-dpad-row button.vqc-optics-key-dpad:active span {{
    background: {_VQC_MATRIX_GREEN} !important;
    color: #000000 !important;
    -webkit-text-fill-color: #000000 !important;
    box-shadow: 0 0 12px rgba(51, 255, 102, 0.45) !important;
}}
.gradio-container .vqc-optics-panel button.vqc-optics-key-clear {{
    text-transform: lowercase !important;
    letter-spacing: 0.06em !important;
}}
.gradio-container .vqc-optics-panel button.vqc-optics-key-home,
.gradio-container .vqc-optics-panel button.vqc-optics-key-home:hover {{
    background: {_VQC_HOME_KEY_BG} !important;
    box-shadow: none !important;
}}
.gradio-container .vqc-optics-panel button.vqc-optics-key-home,
.gradio-container .vqc-optics-panel button.vqc-optics-key-home:hover,
.gradio-container .vqc-optics-panel button.vqc-optics-key-home span {{
    color: {_VQC_MATRIX_GREEN} !important;
    -webkit-text-fill-color: {_VQC_MATRIX_GREEN} !important;
    font-size: 1.44rem !important;
    font-weight: 700 !important;
    text-shadow: 0 0 6px rgba(51, 255, 102, 0.35) !important;
}}
.gradio-container .vqc-optics-panel button.vqc-optics-key-home:hover {{
    background: #141414 !important;
}}
.gradio-container .vqc-optics-panel button.vqc-optics-key-defined:not(.active),
.gradio-container .vqc-optics-panel button.vqc-optics-key-defined:not(.active) span {{
    color: {_VQC_MATRIX_GREEN} !important;
    -webkit-text-fill-color: {_VQC_MATRIX_GREEN} !important;
    text-shadow: 0 0 6px rgba(51, 255, 102, 0.35) !important;
}}
.gradio-container .vqc-optics-panel button.vqc-optics-key-defined:not(.active):hover,
.gradio-container .vqc-optics-panel button.vqc-optics-key-defined:not(.active):hover span {{
    color: #7dff9a !important;
    -webkit-text-fill-color: #7dff9a !important;
}}
.gradio-container .vqc-optics-panel button.vqc-optics-key:not(.active):not(.vqc-optics-key-home):not(.vqc-optics-key-defined):hover {{
    background: #141414 !important;
    color: #ffffff !important;
    -webkit-text-fill-color: #ffffff !important;
}}
.gradio-container .vqc-optics-panel button.vqc-optics-key-defined:not(.active):hover {{
    background: #141414 !important;
}}
.gradio-container .vqc-optics-panel button.vqc-optics-key.active,
.gradio-container .vqc-optics-panel button.vqc-optics-key.active:hover {{
    background: {_VQC_MATRIX_GREEN} !important;
    box-shadow: 0 0 12px rgba(51, 255, 102, 0.45) !important;
}}
.gradio-container .vqc-optics-panel button.vqc-optics-key.active,
.gradio-container .vqc-optics-panel button.vqc-optics-key.active:hover,
.gradio-container .vqc-optics-panel button.vqc-optics-key.active span {{
    color: #000000 !important;
    -webkit-text-fill-color: #000000 !important;
    text-shadow: none !important;
    -webkit-text-stroke: none !important;
}}
.gradio-container .vqc-optics-panel .label-wrap span,
.gradio-container .vqc-optics-panel label span {{
    color: #e8d4a8 !important;
    font-size: 0.78rem !important;
    letter-spacing: 0.06em !important;
    text-transform: uppercase !important;
    font-weight: 700 !important;
}}
.gradio-container .vqc-optics-panel .info {{
    color: #9a8458 !important;
    font-size: 0.72rem !important;
    font-style: italic !important;
}}
.gradio-container .vqc-optics-panel input[type="text"],
.gradio-container .vqc-optics-panel textarea {{
    background: #120c06 !important;
    border: 2px inset #5c4a1f !important;
    color: #ffb347 !important;
    font-family: "Courier New", Courier, monospace !important;
    border-radius: 6px !important;
    box-shadow: inset 0 0 10px rgba(255, 140, 40, 0.12) !important;
}}
.gradio-container .vqc-optics-panel input[type="number"] {{
    background: #120c06 !important;
    border: 2px inset #5c4a1f !important;
    color: #ffb347 !important;
    font-family: "Courier New", Courier, monospace !important;
    font-weight: 700 !important;
    text-align: center !important;
    border-radius: 4px !important;
    box-shadow: inset 0 0 12px rgba(255, 140, 40, 0.18) !important;
    min-width: 4.2rem !important;
}}
.gradio-container .vqc-optics-panel input[type="range"] {{
    height: 6px !important;
    background: linear-gradient(90deg, #1a1208, #3d2e14, #1a1208) !important;
    border: 1px solid #5c4a1f !important;
    border-radius: 999px !important;
    box-shadow: inset 0 1px 3px rgba(0, 0, 0, 0.6) !important;
}}
.gradio-container .vqc-optics-panel input[type="range"]::-webkit-slider-thumb {{
    -webkit-appearance: none !important;
    width: 24px !important;
    height: 24px !important;
    border-radius: 50% !important;
    background: radial-gradient(circle at 32% 28%, #fff2cc 0%, #c9a227 38%, #5c4212 72%, #2a1f08 100%) !important;
    border: 2px solid #1a1208 !important;
    box-shadow: 0 2px 5px rgba(0, 0, 0, 0.55), inset 0 -2px 4px rgba(0, 0, 0, 0.35) !important;
    cursor: pointer !important;
}}
.gradio-container .vqc-optics-panel input[type="range"]::-moz-range-thumb {{
    width: 24px !important;
    height: 24px !important;
    border-radius: 50% !important;
    background: radial-gradient(circle at 32% 28%, #fff2cc 0%, #c9a227 38%, #5c4212 72%, #2a1f08 100%) !important;
    border: 2px solid #1a1208 !important;
    box-shadow: 0 2px 5px rgba(0, 0, 0, 0.55) !important;
    cursor: pointer !important;
}}
.gradio-container .vqc-optics-panel .vqc-optics-dial-wrap {{
    background: rgba(0, 0, 0, 0.22) !important;
    border: 1px solid #4a3818 !important;
    border-radius: 10px !important;
    padding: 0.55rem 0.65rem 0.45rem !important;
    margin: 0 !important;
}}
.gradio-container .vqc-optics-panel .vqc-optics-tune-row {{
    gap: 0.65rem !important;
    margin-bottom: 0.55rem !important;
}}
.gradio-container .vqc-optics-panel .vqc-optics-dial-row {{
    gap: 0.65rem !important;
    align-items: stretch !important;
}}
.gradio-container .vqc-optics-panel fieldset {{
    background: rgba(0, 0, 0, 0.18) !important;
    border: 1px solid #4a3818 !important;
    border-radius: 10px !important;
    padding: 0.45rem 0.55rem !important;
}}
.gradio-container .vqc-optics-panel .vqc-band-switch button {{
    border: 1px solid #6b4f1d !important;
    background: #1a1208 !important;
    color: #c9a227 !important;
    border-radius: 6px !important;
    font-size: 0.78rem !important;
    letter-spacing: 0.05em !important;
    box-shadow: inset 0 1px 2px rgba(0, 0, 0, 0.45) !important;
}}
.gradio-container .vqc-optics-panel .vqc-band-switch button.selected,
.gradio-container .vqc-optics-panel .vqc-band-switch button[aria-checked="true"] {{
    background: linear-gradient(180deg, #8b6914 0%, #4a3818 100%) !important;
    color: #fff2cc !important;
    box-shadow: 0 0 10px rgba(255, 160, 60, 0.35) !important;
}}
.gradio-container .vqc-optics-presets-label {{
    color: #c9a227 !important;
    font-size: 0.78rem !important;
    letter-spacing: 0.08em !important;
    text-transform: uppercase !important;
    margin: 0.45rem 0 0.35rem 0 !important;
    text-align: center !important;
}}
.gradio-container .vqc-optics-panel button.vqc-receiver-preset {{
    background: linear-gradient(180deg, #3d2e14 0%, #1f1608 100%) !important;
    border: 2px solid #6b4f1d !important;
    color: #f5e6c8 !important;
    border-radius: 8px !important;
    font-size: 0.78rem !important;
    letter-spacing: 0.04em !important;
    box-shadow: inset 0 1px 0 rgba(255, 220, 150, 0.15), 0 2px 4px rgba(0, 0, 0, 0.4) !important;
}}
.gradio-container .vqc-optics-panel button.vqc-receiver-preset:hover {{
    background: linear-gradient(180deg, #6b4f1d 0%, #3d2e14 100%) !important;
    color: #fff8e8 !important;
}}
.gradio-container .vqc-optics-panel .vqc-slm-toggle label {{
    color: #c9a227 !important;
    font-size: 0.76rem !important;
}}
.gradio-container .markdown blockquote {{
    border-left-color: rgba(255, 180, 80, 0.5) !important;
    background: transparent !important;
}}
.gradio-container .accordion,
.gradio-container details,
.gradio-container summary {{
    background-color: {_VQC_FIELD_FILL} !important;
    color: #e8e0f8 !important;
    border-radius: 10px;
}}
.gradio-container .image-container img,
.gradio-container .gr-image img,
.gradio-container video,
.gradio-container .plot-container {{
    background-color: transparent !important;
    opacity: 1 !important;
}}
.gradio-container button,
.gradio-container .gr-button {{
    opacity: 1 !important;
}}
.gradio-container input[type="range"] {{
    opacity: 1 !important;
}}
.gradio-container .vqc-full-width {{
    width: 100% !important;
}}
.gradio-container .main,
.gradio-container .wrap {{
    width: 100% !important;
    max-width: 100% !important;
    min-height: 0 !important;
    height: auto !important;
}}
.gradio-container .contain {{
    width: 100% !important;
    max-width: 100% !important;
    margin: 0 auto !important;
    min-height: 0 !important;
    height: auto !important;
}}
.gradio-container .vqc-animation-panel,
.gradio-container .vqc-figure-panel,
.gradio-container .vqc-plot3d-panel {{
    width: 100% !important;
    max-width: 100% !important;
    min-height: 0 !important;
}}
.gradio-container .vqc-animation-panel video,
.gradio-container .vqc-animation-panel .image-container,
.gradio-container .vqc-animation-panel img,
.gradio-container .vqc-figure-panel .image-container,
.gradio-container .vqc-figure-panel img {{
    width: 100% !important;
    max-width: 100% !important;
    object-fit: contain;
}}
.gradio-container .vqc-plot3d-panel .plot-container {{
    width: 100% !important;
    min-height: 360px;
}}
.gradio-container .vqc-plot3d-hint {{
    min-height: 280px !important;
    display: flex !important;
    align-items: center !important;
    justify-content: center !important;
    padding: 1rem 1.25rem !important;
    margin: 0 !important;
    border: 1px dashed rgba(255, 176, 0, 0.35) !important;
    border-radius: 10px !important;
    background: rgba(10, 10, 10, 0.45) !important;
    color: #c9b8ff !important;
    font-size: 0.88rem !important;
    line-height: 1.45 !important;
    text-align: center !important;
}}
.gradio-container .vqc-plot3d-hint p {{
    margin: 0 !important;
    color: #c9b8ff !important;
}}
.gradio-container .gr-video .empty,
.gradio-container .gr-image .empty,
.gradio-container .gr-image .icon-wrap {{
    min-height: 80px !important;
    background: transparent !important;
}}
footer {{ visibility: hidden; }}
{MOBILE_CSS}
"""


def _run_optimize(
    total_steps: float,
    steps_per_update: float,
    learning_rate: float,
    burst_factor_max: float,
    use_fisher_modulation: bool,
    compare_adam: bool,
    run_mode: str,
    trajectory_view: str,
    webgl_ok: bool,
    progress: gr.Progress = gr.Progress(track_tqdm=False),
):
    plot_cfg = PlotStreamConfig.for_run_mode(run_mode or "quick")
    traj_mode = resolve_trajectory_mode(trajectory_view, webgl_ok)
    webgl_fallback = trajectory_view == "3d" and not webgl_ok
    stream_fn = run_comparison_stream if compare_adam else run_optimization_stream
    try:
        yield from stream_fn(
            total_steps=int(total_steps),
            steps_per_update=int(steps_per_update),
            learning_rate=float(learning_rate),
            burst_factor_max=float(burst_factor_max),
            use_fisher_modulation=bool(use_fisher_modulation),
            plot_cfg=plot_cfg,
            trajectory_mode=traj_mode,
            trajectory_webgl_fallback=webgl_fallback,
            progress_cb=progress,
        )
    except Exception as exc:
        logger.exception("Optimization failed")
        empty = go.Figure()
        yield empty, empty, empty, empty, friendly_error("optimize", exc), {}


def _run_spectrum(
    audio_file,
    duration: float,
    use_sample: bool = False,
    progress: gr.Progress = gr.Progress(track_tqdm=False),
):
    try:
        path = audio_file if audio_file else None
        fig_wave, fig_spec, fig_partials, fig_energy, metrics = analyze_audio_signal(
            path,
            duration=float(duration),
            use_sample=use_sample,
            progress_cb=progress,
        )
        return fig_wave, fig_spec, fig_partials, fig_energy, metrics
    except Exception as exc:
        logger.exception("Audio analysis failed")
        empty = go.Figure()
        return empty, empty, empty, empty, friendly_error("spectrum", exc)


def _run_demo_guitar(duration: float, progress: gr.Progress = gr.Progress(track_tqdm=False)):
    return _run_spectrum(None, duration, use_sample=True, progress=progress)


def _run_physics_preview(progress: gr.Progress = gr.Progress(track_tqdm=False)):
    try:
        progress(0.2, desc="Rendering Smith chart preview…")
        smith = render_smith_chart_preview()
        overview = get_overview_composite_path()
        progress(0.8, desc="Loading overview composite…")
        metrics, smith_path, overview_path = run_analysis(0.85)
        progress(1.0, desc="Done")
        return metrics, smith_path or smith, overview_path
    except Exception as exc:
        logger.exception("Physics preview failed")
        return friendly_error("physics", exc), None, None


def build_app() -> gr.Blocks:
    with gr.Blocks(
        title="6-String Optimizer — Signal Analyzer",
        analytics_enabled=False,
        theme=_build_vqc_theme(),
        head=WALLPAPER_HEAD,
        css=HFB_CSS,
        fill_width=True,
    ) as demo:
        current_page = gr.State("demo")
        newhere_open = gr.State(False)
        claims_open = gr.State(False)
        theory_open = gr.State(False)
        welcome_dismissed = gr.State(False)
        with gr.Column(visible=True, elem_classes=["vqc-links-panel", "vqc-welcome-panel"]) as panel_welcome:
            with gr.Row(elem_classes=["vqc-panel-header-row"]):
                gr.Markdown("### Welcome — What is this project?")
                welcome_dismiss_btn = gr.Button(
                    "Dismiss ✕",
                    elem_classes=["vqc-panel-minimize", "vqc-welcome-seen-trigger"],
                    scale=0,
                    variant="secondary",
                )
            gr.Markdown(WHAT_IS_THIS_MD)
            gr.HTML(INTRO_WALKTHROUGH_HTML)
            gr.Markdown(LOCAL_RUN_MD)
            with gr.Accordion(
                "Known limitations (HF free tier)",
                open=True,
                elem_classes=["vqc-limitations-acc"],
            ):
                gr.Markdown(KNOWN_LIMITATIONS_BODY)
            with gr.Row():
                welcome_tour_btn = gr.Button(
                    "Start guided tour (keypad 11)",
                    variant="secondary",
                    size="sm",
                    elem_classes=["vqc-welcome-seen-trigger"],
                )
                welcome_skip_btn = gr.Button(
                    "Skip — go to workspace",
                    variant="primary",
                    size="sm",
                    elem_classes=["vqc-welcome-seen-trigger"],
                )
        with gr.Column(visible=False, elem_classes=["vqc-links-panel"]) as panel_theory:
            with gr.Row(elem_classes=["vqc-panel-header-row"]):
                gr.Markdown("### Theory — How it works")
                theory_minimize_btn = gr.Button(
                    "▲",
                    elem_classes=["vqc-panel-minimize"],
                    scale=0,
                    variant="secondary",
                )
            gr.Markdown(THEORY_MD)
            gr.HTML(THEORY_KATEX_HTML)
        with gr.Column(visible=False, elem_classes=["vqc-links-panel"]) as panel_claims:
            with gr.Row(elem_classes=["vqc-panel-header-row"]):
                gr.Markdown("### How this Space maps to the 6-string optimizer")
                claims_minimize_btn = gr.Button(
                    "▲",
                    elem_classes=["vqc-panel-minimize"],
                    scale=0,
                    variant="secondary",
                )
            gr.Markdown(CLAIMS_MD)
        with gr.Column(visible=False, elem_classes=["vqc-links-panel"]) as panel_newhere:
            with gr.Row(elem_classes=["vqc-panel-header-row"]):
                gr.Markdown("### New here? 60-second guide (six-string signal analyzer)")
                newhere_minimize_btn = gr.Button(
                    "▲",
                    elem_classes=["vqc-panel-minimize"],
                    scale=0,
                    variant="secondary",
                )
            gr.Markdown(ONBOARDING_MD)
        with gr.Column(visible=True) as page_demo:
            with gr.Group(elem_classes=["vqc-optics-panel"]):
                with gr.Row(elem_classes=["vqc-optics-panel-header"]):
                    gr.HTML(OPTICS_LOGO_HTML)
                    with gr.Column(elem_classes=["vqc-optics-panel-nav"], scale=1):
                        with gr.Row(elem_classes=["vqc-nav-spreadsheet-row"]):
                            gr.HTML('<span class="vqc-source-label vqc-nav-row-label">Source:</span>')
                            with gr.Column(elem_classes=["vqc-nav-cell"], scale=1, min_width=72):
                                tab_demo_btn = gr.Button(
                                    "Workspace",
                                    elem_classes=["vqc-source-tab", "active"],
                                    interactive=False,
                                    scale=0,
                                    variant="secondary",
                                )
                            with gr.Column(elem_classes=["vqc-nav-cell"], scale=1, min_width=72):
                                tab_anim_btn = gr.Button(
                                    "Figures",
                                    elem_classes=["vqc-source-tab"],
                                    scale=0,
                                    variant="secondary",
                                )
                            with gr.Column(elem_classes=["vqc-nav-cell"], scale=1, min_width=72):
                                tab_claims_btn = gr.Button(
                                    "Claims",
                                    elem_classes=["vqc-source-tab"],
                                    scale=0,
                                    variant="secondary",
                                )
                            with gr.Column(elem_classes=["vqc-nav-cell"], scale=1, min_width=72):
                                tab_newhere_btn = gr.Button(
                                    "New here?",
                                    elem_classes=["vqc-source-tab"],
                                    scale=0,
                                    variant="secondary",
                                )
                            with gr.Column(elem_classes=["vqc-nav-cell"], scale=1, min_width=72):
                                tab_theory_btn = gr.Button(
                                    "Theory",
                                    elem_classes=["vqc-source-tab"],
                                    scale=0,
                                    variant="secondary",
                                )
                        with gr.Row(elem_classes=["vqc-nav-spreadsheet-row"]):
                            gr.HTML('<span class="vqc-source-label vqc-nav-row-label">Links:</span>')
                            with gr.Column(elem_classes=["vqc-nav-cell"], scale=1, min_width=72):
                                gr.HTML(_external_tab_html("GitHub", GITHUB_URL, "github"))
                            with gr.Column(elem_classes=["vqc-nav-cell"], scale=1, min_width=72):
                                gr.HTML(_external_tab_html("qvpic", QVPIC_URL, "qvpic"))
                            with gr.Column(elem_classes=["vqc-nav-cell"], scale=1, min_width=72):
                                gr.HTML('<span class="vqc-nav-cell-empty" aria-hidden="true">&nbsp;</span>')
                            with gr.Column(elem_classes=["vqc-nav-cell"], scale=1, min_width=72):
                                gr.HTML('<span class="vqc-nav-cell-empty" aria-hidden="true">&nbsp;</span>')
                            with gr.Column(elem_classes=["vqc-nav-cell"], scale=1, min_width=72):
                                gr.HTML('<span class="vqc-nav-cell-empty" aria-hidden="true">&nbsp;</span>')
                optics_terminal = gr.Textbox(
                    label="Matrix status display — selection menu · d-pad nav",
                    value="",
                    lines=14,
                    max_lines=24,
                    interactive=False,
                    elem_classes=["vqc-optics-terminal-wrap", "vqc-optics-terminal"],
                )
                term_signal_scan = gr.HTML(SIGNAL_SCANNER_HTML, visible=False, elem_classes=["myst-signal-host"])
                term_active_key = gr.State("")
                term_ui_state = gr.State(_default_term_ui_state())
                term_all_btns: dict[str, gr.Button] = {}
                _dpad_row_labels = {
                    "dpad_select": "enter",
                    "dpad_up": "▲",
                    "dpad_down": "▼",
                    "dpad_left": "◀",
                    "dpad_right": "▶",
                    "clear": "clear",
                }

                with gr.Column(elem_classes=["vqc-optics-keypad"]):
                    with gr.Row(elem_classes=["vqc-optics-dpad-row"], equal_height=True):
                        for nav_key in TERM_NAV_KEYS:
                            term_all_btns[nav_key] = gr.Button(
                                _dpad_row_labels[nav_key],
                                elem_classes=_term_key_btn_classes(nav_key, ""),
                                scale=1,
                                variant="secondary",
                            )
                    with gr.Row(elem_classes=["vqc-optics-prog-row"], equal_height=True):
                        for index in range(1, 13):
                            key_id = _term_key_id(index)
                            term_all_btns[key_id] = gr.Button(
                                _term_keypad_label(index),
                                elem_classes=_term_key_btn_classes(key_id, ""),
                                scale=1,
                                variant="secondary",
                            )
                    with gr.Row(elem_classes=["vqc-optics-prog-row"], equal_height=True):
                        for index in range(13, 25):
                            key_id = _term_key_id(index)
                            term_all_btns[key_id] = gr.Button(
                                _term_keypad_label(index),
                                elem_classes=_term_key_btn_classes(key_id, ""),
                                scale=1,
                                variant="secondary",
                            )
                term_keypad_outputs = [
                    optics_terminal,
                    term_signal_scan,
                    *[term_all_btns[key_id] for key_id in TERM_KEYPAD_CONTROL_ORDER],
                    term_active_key,
                    term_ui_state,
                ]
                gr.Markdown(SIMULATION_BANNER_MD)
                run_mode = gr.Radio(
                    choices=[
                        ("⭐ Quick Demo (~20s) — recommended first visit", "quick"),
                        ("Standard HF (~45s) — balanced public demo", "standard"),
                        ("Full Research (12k) — best run locally; may timeout on HF", "research"),
                    ],
                    value="quick",
                    label="Run mode",
                    info="Quick Demo throttles 3D trajectory redraws and subsamples points for faster streaming.",
                    elem_classes=["vqc-run-mode-radio"],
                )
                runtime_hint = gr.Markdown(
                    _runtime_hint(_DEFAULTS["total_steps"], _DEFAULTS["steps_per_update"], False),
                )
                with gr.Row(elem_classes=["vqc-optics-dial-row"]):
                    total_steps = gr.Slider(
                        1000, 30000, value=_DEFAULTS["total_steps"], step=500,
                        label="Total steps", elem_classes=["vqc-optics-dial-wrap"],
                        info=SLIDER_TOOLTIPS["total_steps"],
                    )
                    steps_per_update = gr.Slider(
                        20, 200, value=_DEFAULTS["steps_per_update"], step=10,
                        label="Steps / update", elem_classes=["vqc-optics-dial-wrap"],
                        info=SLIDER_TOOLTIPS["steps_per_update"],
                    )
                    learning_rate = gr.Slider(
                        0.005, 0.08, value=_DEFAULTS["learning_rate"], step=0.005,
                        label="Learning rate", elem_classes=["vqc-optics-dial-wrap"],
                        info=SLIDER_TOOLTIPS["learning_rate"],
                    )
                    burst_factor_max = gr.Slider(
                        2.0, 12.0, value=_DEFAULTS["burst_factor_max"], step=0.5,
                        label="Burst factor max", elem_classes=["vqc-optics-dial-wrap"],
                        info=SLIDER_TOOLTIPS["burst_factor_max"],
                    )
                    use_fisher = gr.Checkbox(
                        label="Fisher-Rao modulation",
                        value=_DEFAULTS["use_fisher_modulation"],
                        info=SLIDER_TOOLTIPS["use_fisher"],
                    )
                    compare_adam = gr.Checkbox(
                        label="Compare vs RiemannianAdam (side-by-side loss)",
                        value=False,
                        info="Runs both optimizers from identical S³ init — ~2× wall time.",
                    )
                    audio_duration = gr.Slider(
                        1.0, 6.0, value=_DEFAULTS["audio_duration"], step=0.5,
                        label="Audio duration (s)", elem_classes=["vqc-optics-dial-wrap"],
                        info=SLIDER_TOOLTIPS["audio_duration"],
                    )
                gr.HTML('<p class="vqc-optics-presets-label">Optimization presets — one click loads dials</p>')
                with gr.Row():
                    preset_standard_btn = gr.Button(
                        "Standard Burst", variant="secondary", size="sm",
                        elem_classes=["vqc-receiver-preset"],
                    )
                    preset_fisher_btn = gr.Button(
                        "Fisher-Rao", variant="secondary", size="sm",
                        elem_classes=["vqc-receiver-preset"],
                    )
                    preset_aggressive_btn = gr.Button(
                        "Aggressive", variant="secondary", size="sm",
                        elem_classes=["vqc-receiver-preset"],
                    )
                preset_note = gr.Textbox(
                    label="Preset / status", lines=1, interactive=False,
                    value=OPTIMIZATION_PRESETS["standard"]["description"],
                )
                with gr.Row(elem_classes=["vqc-utility-row"]):
                    reset_btn = gr.Button(
                        "↺ RESET workspace",
                        variant="secondary",
                        size="sm",
                        elem_classes=["vqc-utility-btn"],
                    )
                    gr.Markdown(
                        "*Resets dials to **Quick Demo** — does not clear plot history.*",
                        elem_classes=["vqc-utility-hint"],
                    )
                gr.HTML(
                    '<p class="vqc-optics-presets-label">'
                    f"Audio: bundled demo guitar — {SAMPLE_GUITAR_NOTE}"
                    "</p>"
                )
                with gr.Row():
                    demo_guitar_btn = gr.Button(
                        "▶ DEMO GUITAR (G3)",
                        variant="primary",
                        size="sm",
                        elem_classes=["vqc-receiver-preset"],
                    )
                    run_opt_btn = gr.Button(
                        "▶ RUN OPTIMIZATION",
                        variant="secondary",
                        size="sm",
                        elem_classes=["vqc-receiver-preset"],
                    )
                    cancel_opt_btn = gr.Button(
                        "■ CANCEL",
                        variant="stop",
                        size="sm",
                        elem_classes=["vqc-receiver-preset"],
                    )
                    physics_btn = gr.Button(
                        "Smith + Overview",
                        variant="secondary",
                        size="sm",
                        elem_classes=["vqc-receiver-preset"],
                    )
            # Shared cancels list — stops in-flight terminal streams on new keypress.
            term_cancels: list = []

            def _bind_term_event(btn: gr.Button, fn, *, inputs: list) -> None:
                term_cancels.append(
                    btn.click(
                        fn,
                        inputs=inputs,
                        outputs=term_keypad_outputs,
                        cancels=term_cancels,
                    )
                )

            scan_key = _term_key_id(8)
            _bind_term_event(
                term_all_btns[scan_key],
                _make_activate_signal_scan(scan_key),
                inputs=[term_ui_state],
            )
            _bind_term_event(
                term_all_btns["clear"],
                _make_term_clear_click("clear"),
                inputs=[optics_terminal, term_ui_state],
            )
            for hold_key in TERM_DPAD_HOLD_KEYS:
                _bind_term_event(
                    term_all_btns[hold_key],
                    _make_term_dpad_click(hold_key),
                    inputs=[optics_terminal, term_ui_state],
                )
            _bind_term_event(
                term_all_btns[TERM_KEYPAD_HOME_KEY],
                _make_term_home_momentary(),
                inputs=[term_active_key, term_ui_state],
            )
            for index in range(1, TERM_KEYPAD_COUNT + 1):
                key_id = _term_key_id(index)
                if index == 1 or index == 8:
                    continue
                if index in TERM_KEYPAD_DEFINED:
                    action = TERM_KEYPAD_DEFINED[index]
                    _bind_term_event(
                        term_all_btns[key_id],
                        _make_term_stream_click(
                            key_id,
                            TERM_KEYPAD_STREAMERS[action],
                            menu_action=action,
                        ),
                        inputs=[term_ui_state],
                    )
                else:
                    _bind_term_event(
                        term_all_btns[key_id],
                        _make_term_latch_click(key_id),
                        inputs=[optics_terminal, term_ui_state],
                    )

            opt_history_state = gr.State(None)
            webgl_ok_state = gr.State(True)
            webgl_probe = gr.Textbox(value="1", visible=False, elem_classes=["vqc-webgl-probe"])

            with gr.Tabs():
                with gr.Tab("OPTIMIZE"):
                    gr.Markdown(
                        "Watch the **stereographic Rosenbrock path** toward [1,1,1] — "
                        "colored by loss. **Burst events** (vertical ticks on loss plot) fire when "
                        "a virtual string's stagnation tension triggers a plateau escape."
                    )
                    trajectory_view = gr.Radio(
                        choices=TRAJECTORY_VIEW_CHOICES,
                        value=default_trajectory_view(),
                        label="Trajectory view",
                        info="2D is recommended on HF free tier. Choose 3D only if WebGL works in your browser.",
                        elem_classes=["vqc-trajectory-view-radio"],
                    )
                    webgl_status = gr.Markdown(
                        webgl_status_markdown(True, default_trajectory_view()),
                        elem_classes=["vqc-webgl-status"],
                    )
                    with gr.Row():
                        with gr.Column(
                            visible=False,
                            scale=1,
                            elem_classes=["vqc-plot3d-col"],
                        ) as plot_3d_col:
                            plot_3d = gr.Plot(
                                label="S³ Trajectory",
                                elem_classes=["vqc-plot3d-panel"],
                            )
                        with gr.Column(
                            visible=True,
                            scale=1,
                            elem_classes=["vqc-plot3d-hint-col"],
                        ) as plot_3d_hint_col:
                            plot_3d_hint = gr.Markdown(
                                "**S³ trajectory (Quick Demo + 3D)** — hidden during the run to cut "
                                "Plotly payload. **2D (WebGL-safe)** mode streams live projections here. "
                                "Full 3D path unlocks when optimization completes.",
                                elem_classes=["vqc-plot3d-hint"],
                            )
                        plot_loss = gr.Plot(label="Loss envelope")
                    with gr.Row():
                        plot_vu = gr.Plot(label="Six-string VU meters")
                        plot_twist = gr.Plot(label="Twist accumulation")
                    opt_status = gr.Textbox(label="Optimization status", lines=4)
                    with gr.Row():
                        dl_traj = gr.DownloadButton("↓ Trajectory PNG", variant="secondary")
                        dl_loss = gr.DownloadButton("↓ Loss PNG", variant="secondary")
                        dl_vu = gr.DownloadButton("↓ VU PNG", variant="secondary")
                with gr.Tab("SPECTRUM"):
                    gr.Markdown(
                        f"Upload WAV/MP3 or use bundled **{get_sample_guitar_path().name}** — {SAMPLE_GUITAR_NOTE}"
                    )
                    audio_input = gr.Audio(
                        label="Audio input",
                        type="filepath",
                        value=str(get_sample_guitar_path()),
                    )
                    analyze_btn = gr.Button("▶ ANALYZE UPLOAD", variant="secondary")
                    with gr.Row():
                        plot_wave = gr.Plot(label="Waveform")
                        plot_spec = gr.Plot(label="STFT spectrogram")
                    with gr.Row():
                        plot_partials = gr.Plot(label="Harmonic partial tracks")
                        plot_string_energy = gr.Plot(label="Per-string partial energy")
                    spec_metrics = gr.Textbox(label="Signal metrics", lines=12)
                    gr.Markdown("**Modal synthesis** — lite before/after from estimated partials (physics-audio preview)")
                    with gr.Row():
                        synth_btn = gr.Button("▶ SYNTHESIZE MODALS", variant="primary", size="sm")
                        inharm_b = gr.Slider(
                            0.0001, 0.002, value=0.0005, step=0.0001,
                            label="Inharmonicity B", info="Modal detuning coefficient B in f_k = k f₀ √(1 + Bk²)",
                        )
                    with gr.Row():
                        audio_before = gr.Audio(label="Original (before)", type="filepath")
                        audio_after = gr.Audio(label="Modal synthesis (after)", type="filepath")
                    synth_overlay = gr.Plot(label="Waveform overlay")
                    synth_metrics = gr.Textbox(label="Synthesis metrics", lines=8)
                with gr.Tab("STRINGS"):
                    gr.Markdown(STRING_TABLE_MD)
                    strings_vu_live = gr.Plot(label="Live VU — run OPTIMIZE to populate")
                    strings_note = gr.Textbox(
                        label="Status",
                        value="Press ▶ RUN OPTIMIZATION — meters mirror OPTIMIZE tab in real time.",
                        interactive=False,
                        lines=2,
                    )
                with gr.Tab("TENSION"):
                    gr.Markdown(
                        "Complementary **string tension calculator** for guitarists — "
                        "uses frequency–length–gauge approximation (not the S³ optimizer)."
                    )
                    tension_scale = gr.Slider(
                        24.0, 27.0, value=DEFAULT_SCALE_LENGTH_IN, step=0.1,
                        label="Scale length (inches)",
                        info="25.5\" = Fender Strat scale · 24.75\" = Gibson",
                    )
                    tension_string = gr.Dropdown(
                        choices=list(STANDARD_TUNING.keys()),
                        value="G",
                        label="String",
                    )
                    tension_gauge = gr.Slider(
                        0.008, 0.056, value=0.017, step=0.001,
                        label="Gauge override (in)",
                    )
                    tension_freq = gr.Slider(
                        70, 400, value=196.0, step=0.5,
                        label="Frequency override (Hz)",
                    )
                    tension_calc_btn = gr.Button("Calculate tension", variant="secondary")
                    tension_table_md = gr.Markdown(tension_calculator_table())
                    tension_result = gr.Textbox(label="Single-string result", lines=6)
                with gr.Tab("PHYSICS"):
                    with gr.Row(equal_height=True):
                        with gr.Column(scale=1):
                            physics_metrics = gr.Textbox(label="Physics-audio metrics", lines=14)
                        with gr.Column(scale=2):
                            figure_smith = gr.Image(
                                label="Smith chart Γ preview",
                                type="filepath",
                                elem_classes=["vqc-figure-panel"],
                            )
                    figure_overview = gr.Image(
                        label="Overview composite (pyramid)",
                        type="filepath",
                        elem_classes=["vqc-figure-panel"],
                    )

            def _export_traj(history):
                p, _, _ = export_optimization_plots(history)
                return p

            def _export_loss(history):
                _, p, _ = export_optimization_plots(history)
                return p

            def _export_vu(history):
                _, _, p = export_optimization_plots(history)
                return p

            def _run_synth(audio_file, duration, b, progress=gr.Progress(track_tqdm=False)):
                try:
                    path = audio_file if audio_file else None
                    use_sample = not (path and Path(path).is_file())
                    o, s, fig, m = synthesize_modal_comparison(
                        path, duration=float(duration), use_sample=use_sample,
                        inharmonicity_b=float(b), progress_cb=progress,
                    )
                    return o, s, fig, m
                except Exception as exc:
                    logger.exception("Modal synthesis failed")
                    return None, None, go.Figure(), friendly_error("synthesis", exc)

            def _reset_workspace(traj_view, webgl_ok):
                p = get_run_mode_params("quick")
                spec = RUN_MODES["quick"]
                plot_col, hint_col = _plot_3d_for_mode("quick", None, traj_view, webgl_ok)
                return (
                    p["total_steps"],
                    p["steps_per_update"],
                    p["learning_rate"],
                    p["burst_factor_max"],
                    p["use_fisher_modulation"],
                    p.get("compare_adam", False),
                    p["audio_duration"],
                    "quick",
                    f"Reset to Quick Demo — {spec['description']}",
                    _runtime_hint(p["total_steps"], p["steps_per_update"], False),
                    "Ready — try ▶ DEMO GUITAR or Quick Demo optimize.",
                    None,
                    plot_col,
                    hint_col,
                )

            def _update_tension_table(scale):
                return tension_calculator_table(float(scale))

            def _calc_tension(string_name, scale, gauge, freq):
                return tension_single_string(
                    string_name, float(scale), float(gauge), float(freq),
                )

            opt_cancels: list = []
            opt_event = (
                run_opt_btn.click(
                    _plot_3d_on_run_start,
                    [run_mode, trajectory_view, webgl_ok_state],
                    [plot_3d_col, plot_3d_hint_col],
                )
                .then(
                    _run_optimize,
                    [
                        total_steps, steps_per_update, learning_rate, burst_factor_max,
                        use_fisher, compare_adam, run_mode, trajectory_view, webgl_ok_state,
                    ],
                    [plot_3d, plot_loss, plot_vu, plot_twist, opt_status, opt_history_state],
                )
                .then(
                    lambda vu, st: (vu, st),
                    [plot_vu, opt_status],
                    [strings_vu_live, strings_note],
                )
                .then(
                    _plot_3d_on_run_finish,
                    [run_mode, opt_history_state, trajectory_view, webgl_ok_state],
                    [plot_3d_col, plot_3d_hint_col],
                )
            )
            opt_cancels.append(opt_event)
            cancel_opt_btn.click(None, None, None, cancels=opt_cancels)

            dl_traj.click(_export_traj, [opt_history_state], [dl_traj])
            dl_loss.click(_export_loss, [opt_history_state], [dl_loss])
            dl_vu.click(_export_vu, [opt_history_state], [dl_vu])

            preset_outputs = [
                total_steps, steps_per_update, learning_rate,
                burst_factor_max, use_fisher, preset_note,
            ]
            preset_standard_btn.click(
                lambda: _apply_preset("standard"), outputs=preset_outputs,
            )
            preset_fisher_btn.click(
                lambda: _apply_preset("fisher_rao"), outputs=preset_outputs,
            )
            preset_aggressive_btn.click(
                lambda: _apply_preset("aggressive"), outputs=preset_outputs,
            )

            run_mode_outputs = [
                total_steps, steps_per_update, learning_rate, burst_factor_max,
                use_fisher, compare_adam, audio_duration, preset_note, runtime_hint,
                plot_3d_col, plot_3d_hint_col,
            ]
            run_mode.change(
                _apply_run_mode_with_3d,
                [run_mode, opt_history_state, trajectory_view, webgl_ok_state],
                run_mode_outputs,
            )

            trajectory_view.change(
                _on_trajectory_view_change,
                [trajectory_view, webgl_ok_state],
                [webgl_status],
            )

            def _hint_on_dial_change(ts, spu, cmp):
                return _runtime_hint(ts, spu, cmp)

            for dial in (total_steps, steps_per_update):
                dial.release(_hint_on_dial_change, [total_steps, steps_per_update, compare_adam], [runtime_hint])
            compare_adam.change(_hint_on_dial_change, [total_steps, steps_per_update, compare_adam], [runtime_hint])

            reset_outputs = [
                total_steps, steps_per_update, learning_rate, burst_factor_max,
                use_fisher, compare_adam, audio_duration, run_mode, preset_note,
                runtime_hint, opt_status, opt_history_state, plot_3d_col, plot_3d_hint_col,
            ]
            reset_btn.click(
                _reset_workspace,
                [trajectory_view, webgl_ok_state],
                outputs=reset_outputs,
            )

            demo_guitar_btn.click(
                _run_demo_guitar,
                [audio_duration],
                [plot_wave, plot_spec, plot_partials, plot_string_energy, spec_metrics],
            )
            analyze_btn.click(
                _run_spectrum,
                [audio_input, audio_duration],
                [plot_wave, plot_spec, plot_partials, plot_string_energy, spec_metrics],
            )
            physics_btn.click(
                _run_physics_preview,
                [],
                [physics_metrics, figure_smith, figure_overview],
            )
            synth_btn.click(
                _run_synth,
                [audio_input, audio_duration, inharm_b],
                [audio_before, audio_after, synth_overlay, synth_metrics],
            )
            tension_scale.change(_update_tension_table, [tension_scale], [tension_table_md])
            tension_calc_btn.click(
                _calc_tension,
                [tension_string, tension_scale, tension_gauge, tension_freq],
                [tension_result],
            )

            welcome_outputs = [panel_welcome, welcome_dismissed]
            welcome_dismiss_btn.click(_dismiss_welcome, outputs=welcome_outputs)
            welcome_skip_btn.click(_dismiss_welcome, outputs=welcome_outputs)
            welcome_tour_btn.click(_dismiss_welcome, outputs=welcome_outputs).then(
                lambda: (gr.update(visible=True), _source_tab_btn_update(active=True), True),
                outputs=[panel_newhere, tab_newhere_btn, newhere_open],
            )

        with gr.Column(visible=False, elem_classes=["vqc-animations-page"]) as page_animations:
            with gr.Row(elem_classes=["vqc-source-tabs-row", "vqc-animations-nav-row"]):
                gr.HTML('<span class="vqc-source-label">Source:</span>')
                anim_tab_demo_btn = gr.Button(
                    "Workspace",
                    elem_classes=["vqc-source-tab"],
                    scale=0,
                    variant="secondary",
                )
                anim_tab_anim_btn = gr.Button(
                    "Figures",
                    elem_classes=["vqc-source-tab", "active"],
                    interactive=False,
                    scale=0,
                    variant="secondary",
                )
            gr.Markdown("## Reference figures")
            gr.Markdown(FIGURES_INTRO_MD_LOCAL)
            gr.HTML(_figures_grid_html())
            gr.Markdown(_figures_links_md())

        theory_outputs = [
            panel_theory, tab_theory_btn, theory_open,
            panel_newhere, tab_newhere_btn, newhere_open,
            panel_claims, tab_claims_btn, claims_open,
        ]
        newhere_outputs = [
            panel_newhere, tab_newhere_btn, newhere_open,
            panel_claims, tab_claims_btn, claims_open,
            panel_theory, tab_theory_btn, theory_open,
        ]
        claims_outputs = [
            panel_claims, tab_claims_btn, claims_open,
            panel_newhere, tab_newhere_btn, newhere_open,
            panel_theory, tab_theory_btn, theory_open,
        ]
        nav_outputs = [
            page_demo,
            page_animations,
            tab_demo_btn,
            tab_anim_btn,
            panel_newhere,
            tab_newhere_btn,
            newhere_open,
            panel_claims,
            tab_claims_btn,
            claims_open,
            panel_theory,
            tab_theory_btn,
            theory_open,
            anim_tab_demo_btn,
            anim_tab_anim_btn,
            current_page,
        ]
        tab_demo_btn.click(lambda: _nav_to_page("demo"), outputs=nav_outputs)
        tab_anim_btn.click(lambda: _nav_to_page("animations"), outputs=nav_outputs)
        anim_tab_demo_btn.click(lambda: _nav_to_page("demo"), outputs=nav_outputs)
        anim_tab_anim_btn.click(lambda: _nav_to_page("animations"), outputs=nav_outputs)
        tab_theory_btn.click(_toggle_theory, inputs=[theory_open], outputs=theory_outputs)
        tab_newhere_btn.click(_toggle_newhere, inputs=[newhere_open], outputs=newhere_outputs)
        tab_claims_btn.click(_toggle_claims, inputs=[claims_open], outputs=claims_outputs)
        theory_minimize_btn.click(_minimize_theory, outputs=theory_outputs[:3])
        newhere_minimize_btn.click(_minimize_newhere, outputs=newhere_outputs[:3])
        claims_minimize_btn.click(_minimize_claims, outputs=claims_outputs[:3])
        demo.load(_stream_term_boot, outputs=term_keypad_outputs)
        demo.load(
            _on_webgl_probe,
            inputs=[webgl_probe],
            outputs=[webgl_ok_state, trajectory_view, webgl_status],
            js=WEBGL_PROBE_JS,
        )

        gr.Markdown(
            "6-String Optimizer — mystery shell + physics-audio · "
            f"[GitHub]({GITHUB_URL}) · [Space]({HF_SPACE_URL})"
        )
    return demo


demo = build_app()


def main() -> None:
    logging.basicConfig(level=logging.INFO)

    try:
        demo.get_api_info()
        logger.info("Gradio API info check passed")
    except Exception:
        logger.exception("Gradio API info check failed")

    on_hf = bool(os.environ.get("SPACE_ID"))
    port = int(os.environ.get("GRADIO_SERVER_PORT", "7860"))

    launch_kwargs: dict = {
        "server_name": "0.0.0.0",
        "server_port": port,
        "show_error": True,
        "show_api": False,
        "inbrowser": False,
        "share": False if on_hf else True,
    }

    demo.queue(default_concurrency_limit=2).launch(**launch_kwargs)


if __name__ == "__main__":
    main()