iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/widgets/sidebar/panel.py

@@ -0,0 +1,198 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""SidebarPanel — toggleable tabbed sidebar."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from textual.content import Content
+from textual.reactive import reactive
+from textual.widget import Widget
+from textual.widgets import Tab, TabbedContent, TabPane, Tabs
+
+from chrys.app.tui.i18n import render_content
+from chrys.app.tui.widgets.sidebar.buddy import BuddyPanel
+from chrys.app.tui.widgets.sidebar.context import ContextPanel, ContextUsageState
+from chrys.app.tui.widgets.sidebar.debug import DebugPanel
+from chrys.app.tui.widgets.sidebar.tasks import TasksPanel, TodoListState
+from chrys.app.tui.widgets.sidebar.toc import ConversationToc
+from chrys.foundation.i18n import MessageDef, MessageRef, msg
+from chrys.foundation.i18n.formatting import format_message
+
+_SIDEBAR_MESSAGES = msg("tui.sidebar.tab.messages", fallback="Messages")
+_SIDEBAR_TASKS = msg("tui.sidebar.tab.tasks", fallback="Tasks")
+_SIDEBAR_CONTEXT = msg("tui.sidebar.tab.context", fallback="Context")
+_SIDEBAR_DEBUG = msg("tui.sidebar.tab.debug", fallback="Debug")
+_SIDEBAR_BUDDY = msg("tui.sidebar.tab.buddy", fallback="Buddy")
+_SIDEBAR_TAB_MESSAGES: tuple[MessageDef, ...] = (
+    _SIDEBAR_MESSAGES,
+    _SIDEBAR_TASKS,
+    _SIDEBAR_CONTEXT,
+    _SIDEBAR_DEBUG,
+    _SIDEBAR_BUDDY,
+)
+_WORKFLOW_HIDDEN_TABS = ("tab-toc", "tab-tasks", "tab-context")
+
+if TYPE_CHECKING:
+    from textual.app import ComposeResult
+
+    from chrys.app.tui.i18n import LocaleController
+
+
+class SidebarPanel(Widget, can_focus=False):
+    """Toggleable sidebar with tabbed panels."""
+
+    context_usage_state: reactive[ContextUsageState | None] = reactive(None, always_update=True)
+    todo_state: reactive[TodoListState | None] = reactive(None, always_update=True)
+
+    DEFAULT_CSS = """
+    SidebarPanel {
+        width: 30%;
+        min-width: 42;
+        min-height: 3;
+        max-width: 60;
+        border: round $tui-border-primary $border-opacity;
+    }
+    SidebarPanel.-shell-active {
+        border: round $tui-border-warning $border-opacity;
+    }
+    SidebarPanel > TabbedContent {
+        height: 100%;
+    }
+    SidebarPanel TabPane {
+        height: 1fr;
+        padding: 0;
+    }
+    """
+
+    def __init__(self, *, locale_controller: LocaleController | None = None) -> None:
+        super().__init__()
+        self._locale_controller = locale_controller
+        self._visibility_suppressors: set[str] = set()
+        self._display_before_suppression = True
+        self._workflow_mode = False
+        self._tab_strip_focusable = False
+        self._chat_tab = "tab-toc"
+
+    def compose(self) -> ComposeResult:
+        with TabbedContent(initial="tab-toc"):
+            with TabPane(self._localized_content(_SIDEBAR_MESSAGES.bind()), id="tab-toc"):
+                yield ConversationToc(locale_controller=self._locale_controller)
+            with TabPane(self._localized_content(_SIDEBAR_TASKS.bind()), id="tab-tasks"):
+                yield TasksPanel(locale_controller=self._locale_controller).data_bind(
+                    todo_state=SidebarPanel.todo_state
+                )
+            with TabPane(self._localized_content(_SIDEBAR_CONTEXT.bind()), id="tab-context"):
+                yield ContextPanel(locale_controller=self._locale_controller).data_bind(
+                    usage_state=SidebarPanel.context_usage_state
+                )
+            with TabPane(self._localized_content(_SIDEBAR_DEBUG.bind()), id="tab-debug"):
+                yield DebugPanel(locale_controller=self._locale_controller)
+            with TabPane(self._localized_content(_SIDEBAR_BUDDY.bind()), id="tab-buddy"):
+                yield BuddyPanel(locale_controller=self._locale_controller)
+
+    def on_mount(self) -> None:
+        if self._locale_controller is not None:
+            self._locale_controller.register_surface(self)
+        self.query_one(TabbedContent).query_one(Tabs).can_focus = self._tab_strip_focusable
+        self.refresh_localization()
+
+    def set_tab_strip_focusable(self, focusable: bool) -> None:
+        """Let the tab strip take focus only where the main screen lets sidebar focus stay.
+
+        Where the main screen hands sidebar focus straight back to the input bar, a
+        focusable strip is focused twice per click (on mouse down, then by ``Tabs``
+        itself) only to be blurred again, restyling it and repainting the screen each time.
+        """
+        self._tab_strip_focusable = focusable
+        if self.is_mounted:
+            self.query_one(TabbedContent).query_one(Tabs).can_focus = focusable
+
+    def on_unmount(self) -> None:
+        if self._locale_controller is not None:
+            self._locale_controller.unregister_surface(self)
+
+    def refresh_localization(self) -> None:
+        """Relabel tabs and delegate current-text refreshes to owned panels."""
+        if not self.is_mounted:
+            return
+        tabs = self.query_one(TabbedContent).query_one(Tabs)
+        for tab, definition in zip(tabs.query(Tab).results(Tab), _SIDEBAR_TAB_MESSAGES, strict=True):
+            tab.label = self._localized_content(definition.bind())
+        self.context_panel.refresh_localization()
+        self.tasks_panel.refresh_localization()
+        self.toc_panel.refresh_localization()
+        self.buddy_panel.refresh_localization()
+        self.debug_panel.refresh_localization()
+
+    def _localized_content(self, reference: MessageRef) -> Content:
+        controller = self._locale_controller
+        if controller is None:
+            return Content.from_text(format_message(reference), markup=False)
+        return render_content(controller.localizer, reference)
+
+    def toggle(self) -> None:
+        if not self._visibility_suppressors:
+            self.display = not self.display
+
+    def set_workflow_mode(self, workflow: bool) -> None:
+        """Keep chat-only panels out of workflow navigation, retaining the chat selection."""
+        if workflow == self._workflow_mode:
+            return
+        self._workflow_mode = workflow
+        tabs = self.query_one(TabbedContent)
+        if workflow:
+            self._chat_tab = tabs.active
+            if tabs.active in _WORKFLOW_HIDDEN_TABS:
+                tabs.active = "tab-debug"
+            for pane in _WORKFLOW_HIDDEN_TABS:
+                tabs.hide_tab(pane)
+        else:
+            for pane in _WORKFLOW_HIDDEN_TABS:
+                tabs.show_tab(pane)
+            tabs.active = self._chat_tab
+
+    def suppress_visibility(self, owner: Literal["theme-editor", "alternate-screen"], active: bool) -> None:
+        """Restore the user's visibility only after every temporary hide ends."""
+        if active:
+            if owner in self._visibility_suppressors:
+                return
+            if not self._visibility_suppressors:
+                self._display_before_suppression = self.display
+            self._visibility_suppressors.add(owner)
+            self.display = False
+        elif owner in self._visibility_suppressors:
+            self._visibility_suppressors.remove(owner)
+            if not self._visibility_suppressors:
+                self.display = self._display_before_suppression
+
+    @property
+    def is_visible(self) -> bool:
+        return self.display
+
+    @property
+    def debug_panel(self) -> DebugPanel:
+        return self.query_one(DebugPanel)
+
+    @property
+    def context_panel(self) -> ContextPanel:
+        return self.query_one(ContextPanel)
+
+    @property
+    def tasks_panel(self) -> TasksPanel:
+        return self.query_one(TasksPanel)
+
+    @property
+    def toc_panel(self) -> ConversationToc:
+        return self.query_one(ConversationToc)
+
+    @property
+    def buddy_panel(self) -> BuddyPanel:
+        return self.query_one(BuddyPanel)
+
+    def focus_tab(self, tab_id: str) -> None:
+        if self._workflow_mode and tab_id in _WORKFLOW_HIDDEN_TABS:
+            return
+        tc = self.query_one(TabbedContent)
+        tc.active = tab_id

chrys/app/tui/widgets/sidebar/tasks.py

@@ -0,0 +1,198 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""TasksPanel — live session todo checklist."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, ClassVar
+
+from rich.style import Style
+from rich.text import Text
+from textual.containers import VerticalScroll
+from textual.css.query import NoMatches
+from textual.reactive import reactive
+from textual.widget import Widget
+from textual.widgets import Static
+
+from chrys.app.tui.i18n import render_str
+from chrys.app.tui.util.todo_format import todo_checklist_renderable, todo_done_count
+from chrys.app.tui.widgets.sidebar.empty_state import SidebarEmptyStateLabel
+from chrys.foundation.i18n import MessageRef, msg
+from chrys.foundation.i18n.formatting import format_message
+
+_TASKS_TITLE = msg("tui.sidebar.tasks.title", fallback="Todos")
+_TASKS_COUNTER = msg("tui.sidebar.tasks.counter", fallback="Todos ({done}/{total})")
+_TASKS_EMPTY = msg("tui.sidebar.tasks.empty", fallback="No tasks yet")
+
+if TYPE_CHECKING:
+    from textual.app import ComposeResult
+
+    from chrys.app.tui.i18n import LocaleController
+    from chrys.foundation.models.todos import TodoItem
+
+
+@dataclass(frozen=True, slots=True)
+class TodoListState:
+    """View state for the Tasks panel (full-list payload, not a diff)."""
+
+    items: tuple[TodoItem, ...] = ()
+
+
+class TasksPanel(Widget, can_focus=False):
+    """Renders the session todo list with live status markers.
+
+    The checklist lives in a Static (re-rendered at the real content width on
+    every layout) rather than a RichLog: RichLog wraps writes at
+    ``min_width=78`` and never re-wraps, which cropped long items in the
+    narrow sidebar.
+    """
+
+    todo_state: reactive[TodoListState | None] = reactive(None, always_update=True)
+    _MAX_TODO_SYNC_RETRIES = 3
+    COMPONENT_CLASSES: ClassVar[set[str]] = {"tasks--in-progress"}
+
+    DEFAULT_CSS = """
+    TasksPanel {
+        height: 100%;
+        width: 100%;
+        padding: 0 1;
+    }
+    TasksPanel > Static {
+        height: auto;
+    }
+    TasksPanel > .tasks--in-progress {
+        color: $warning;
+    }
+    TasksPanel > .tasks-label {
+        text-style: bold;
+        color: $text-muted;
+    }
+    TasksPanel > #tasks-list {
+        height: 1fr;
+        border: round $tui-border-primary-darken-3 $border-opacity;
+        scrollbar-size: 1 1;
+        overflow-x: hidden;
+        padding: 0 0 0 1;
+        display: none;
+    }
+    TasksPanel #tasks-checklist {
+        width: 100%;
+        height: auto;
+    }
+    TasksPanel > #tasks-empty {
+        height: 1fr;
+        border: round $tui-border-primary-darken-3 $border-opacity;
+        color: $text-muted;
+        content-align: center middle;
+    }
+    SidebarPanel.-shell-active TasksPanel > #tasks-list,
+    SidebarPanel.-shell-active TasksPanel > #tasks-empty {
+        border: round $tui-border-warning-darken-1 $border-opacity;
+    }
+    """
+
+    def __init__(
+        self,
+        *,
+        name: str | None = None,
+        id: str | None = None,
+        classes: str | None = None,
+        disabled: bool = False,
+        locale_controller: LocaleController | None = None,
+    ) -> None:
+        super().__init__(name=name, id=id, classes=classes, disabled=disabled)
+        self._locale_controller = locale_controller
+        self._render_state: TodoListState | None = None
+        self._sync_pending = False
+        self._sync_retries = 0
+        self._theme_style: Style | None = None
+
+    def compose(self) -> ComposeResult:
+        yield Static(Text(self._render_message(_TASKS_TITLE.bind())), classes="tasks-label")
+        with VerticalScroll(id="tasks-list"):
+            yield Static(id="tasks-checklist")
+        yield SidebarEmptyStateLabel(Text(self._render_message(_TASKS_EMPTY.bind())), id="tasks-empty")
+
+    def on_mount(self) -> None:
+        self.app.theme_changed_signal.subscribe(self, self._theme_colors_changed)
+        if self.todo_state is not None:
+            self._render_state = self.todo_state
+        self._request_todo_sync()
+
+    def on_unmount(self) -> None:
+        self.app.theme_changed_signal.unsubscribe(self)
+
+    def _theme_colors_changed(self, _theme: object) -> None:
+        if self._in_progress_style() != self._theme_style:
+            self._request_todo_sync()
+
+    def _in_progress_style(self) -> Style:
+        # Resolve alpha against the live background just as CSS does. Keep only
+        # foreground so a Rich row doesn't acquire a painted background rectangle.
+        resolved = self.get_component_rich_style("tasks--in-progress", default=Style(color="yellow"))
+        return Style(color=resolved.color, bold=True)
+
+    def watch_todo_state(self, state: TodoListState | None) -> None:
+        """Apply routed todo state from the screen."""
+        if state is None:
+            return
+        self._render_state = state
+        self._sync_retries = 0
+        self._sync_todo_state()
+
+    def refresh_localization(self) -> None:
+        """Retranslate the current title/counter and empty-state label."""
+        if not self.is_mounted:
+            return
+        self.query_one("#tasks-empty", Static).update(Text(self._render_message(_TASKS_EMPTY.bind())))
+        if self._render_state is None:
+            self.query_one(".tasks-label", Static).update(Text(self._render_message(_TASKS_TITLE.bind())))
+            return
+        self._sync_todo_state()
+
+    def _render_message(self, reference: MessageRef) -> str:
+        controller = self._locale_controller
+        if controller is None:
+            return format_message(reference)
+        return render_str(controller.localizer, reference)
+
+    def _request_todo_sync(self) -> None:
+        if self._sync_pending:
+            return
+        self._sync_pending = self.call_after_refresh(self._sync_todo_state)
+
+    def _retry_todo_sync(self) -> None:
+        if self._sync_retries >= self._MAX_TODO_SYNC_RETRIES:
+            return
+        self._sync_retries += 1
+        self._request_todo_sync()
+
+    def _sync_todo_state(self) -> None:
+        self._sync_pending = False
+        self._theme_style = self._in_progress_style()
+        state = self._render_state
+        if state is None:
+            return
+        try:
+            label = self.query_one(".tasks-label", Static)
+            scroller = self.query_one("#tasks-list", VerticalScroll)
+            checklist = self.query_one("#tasks-checklist", Static)
+            empty = self.query_one("#tasks-empty", Static)
+        except NoMatches:
+            self._retry_todo_sync()
+            return
+        items = state.items
+        empty.update(Text(self._render_message(_TASKS_EMPTY.bind())))
+        if not items:
+            label.update(Text(self._render_message(_TASKS_TITLE.bind())))
+            checklist.update("")
+            scroller.display = False
+            empty.display = True
+            self._sync_retries = 0
+            return
+        label.update(Text(self._render_message(_TASKS_COUNTER.bind(done=todo_done_count(items), total=len(items)))))
+        checklist.update(todo_checklist_renderable(items, in_progress_style=self._theme_style))
+        scroller.display = True
+        empty.display = False
+        self._sync_retries = 0

chrys/app/tui/widgets/sidebar/toc.py

@@ -0,0 +1,166 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""ConversationToc - Conversation table of contents widget."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rich.segment import Segment
+from rich.style import Style
+from rich.text import Text
+from textual.message import Message
+from textual.strip import Strip
+from textual.widget import Widget
+from textual.widgets import Static, Tree
+
+from chrys.app.tui.i18n import render_str
+from chrys.app.tui.widgets.sidebar.empty_state import SidebarEmptyStateLabel
+from chrys.app.tui.widgets.sidebar.toc_types import _SUMMARY_MAX_LENGTH, TocItem, summarize_prompt
+from chrys.foundation.i18n import MessageRef, msg
+from chrys.foundation.i18n.formatting import format_message
+
+if TYPE_CHECKING:
+    from textual.app import ComposeResult
+
+    from chrys.app.tui.i18n import LocaleController
+
+
+__all__ = ["ConversationToc", "TocItem", "summarize_prompt"]
+
+# Rendered labels include the numeric turn prefix ("12. "), so keep the
+# display cap above the default summary cap instead of silently re-clipping it.
+_MAX_LABEL = _SUMMARY_MAX_LENGTH + 8
+_TREE_TAB_SIZE = 8
+_TOC_EMPTY = msg("tui.sidebar.toc.empty", fallback="Your conversation will appear here")
+
+
+def _tree_label_text(text: str) -> str:
+    """Return text safe for Textual Tree's Rich render path."""
+    return text.expandtabs(_TREE_TAB_SIZE)
+
+
+class _TocTree(Tree[str]):
+    """The tree, with its last column kept clear.
+
+    An entry is one line, cut where the room runs out, and a long one would be cut against the
+    scrollbar. Padding cannot move it away: Textual lays a widget's padding *outside* its
+    scrollbar, so it would take the bar off the panel's edge rather than the text off the bar.
+    """
+
+    def render_line(self, y: int) -> Strip:
+        strip = super().render_line(y)
+        # A line is drawn as wide as the widget, scrollbar included, and the bar covers its end.
+        last = self.scrollable_content_region.width - 1
+        if not 0 < last < strip.cell_length:
+            return strip
+        # The clear cell keeps the row's background and its ``line`` meta, so the highlight runs
+        # through it and a click on it still lands on the row.
+        style = next((segment.style for segment in strip.crop(last, last + 1) if segment.style is not None), None)
+        clear = None if style is None else style.background_style + Style.from_meta(style.meta)
+        return Strip([*strip.crop(0, last), Segment(" ", clear), *strip.crop(last + 1)], strip.cell_length)
+
+
+class ConversationToc(Widget, can_focus=False):
+    """Conversation table of contents widget."""
+
+    DEFAULT_CSS = """
+    ConversationToc {
+        height: 1fr;
+        padding: 0 0 0 1;
+    }
+    ConversationToc > Tree {
+        background: transparent;
+        padding: 0;
+        overflow-x: hidden;
+        scrollbar-size-vertical: 1;
+    }
+    ConversationToc Tree > .tree--cursor {
+        background: $primary 18%;
+    }
+    ConversationToc Tree:focus > .tree--cursor {
+        color: $foreground;
+        background: $primary 28%;
+    }
+    ConversationToc Tree:ansi > .tree--cursor {
+        background: $tui-ansi-turn-background;
+    }
+    ConversationToc Tree:ansi:focus > .tree--cursor {
+        background: $tui-ansi-turn-focus-background;
+    }
+    ConversationToc Tree > .tree--guides {
+        color: $primary 40%;
+    }
+    ConversationToc > .toc-empty {
+        width: 1fr;
+        height: 1fr;
+        content-align: center middle;
+        color: $text-muted;
+    }
+    """
+
+    class TurnSelected(Message):
+        """User selected a conversation turn."""
+
+        def __init__(self, turn_id: str) -> None:
+            super().__init__()
+            self.turn_id = turn_id
+
+    def __init__(self, *, locale_controller: LocaleController | None = None) -> None:
+        super().__init__()
+        self._locale_controller = locale_controller
+        self._items: list[TocItem] = []
+        self._tree: Tree[str] | None = None
+        self._empty_label: Static = SidebarEmptyStateLabel("", classes="toc-empty")
+
+    def compose(self) -> ComposeResult:
+        self._tree = _TocTree("TOC", id="toc-tree")
+        self._tree.show_root = False
+        self._tree.show_guides = True
+        self._tree.display = False
+        yield self._tree
+        self._empty_label = SidebarEmptyStateLabel(Text(self._render_message(_TOC_EMPTY.bind())), classes="toc-empty")
+        yield self._empty_label
+
+    def refresh_localization(self) -> None:
+        """Retranslate the current empty-state text without rebuilding the tree."""
+        if self.is_mounted:
+            self._empty_label.update(Text(self._render_message(_TOC_EMPTY.bind())))
+
+    def _render_message(self, reference: MessageRef) -> str:
+        controller = self._locale_controller
+        if controller is None:
+            return format_message(reference)
+        return render_str(controller.localizer, reference)
+
+    def update_items(self, items: list[TocItem]) -> None:
+        self._items = items
+        self._rebuild_tree()
+
+    def _rebuild_tree(self) -> None:
+        if self._tree is None:
+            return
+        self._tree.clear()
+        self._empty_label.display = not self._items
+        self._tree.display = bool(self._items)
+        for i, item in enumerate(self._items, start=1):
+            raw = _tree_label_text(f"{i}. {item.summary}")
+            if len(raw) > _MAX_LABEL:
+                raw = raw[: _MAX_LABEL - 3] + "..."
+            label = Text(raw, style="dim") if item.compressed else Text(raw)
+            if item.children:
+                node = self._tree.root.add(label, data=item.turn_id)
+                node.expand()
+                node.allow_expand = False
+                for child in item.children:
+                    raw_child = _tree_label_text(child.summary)
+                    if len(raw_child) > _MAX_LABEL - 2:
+                        raw_child = raw_child[: _MAX_LABEL - 5] + "..."
+                    child_label = Text(raw_child, style="dim") if child.compressed else Text(raw_child)
+                    node.add_leaf(child_label, data=child.turn_id)
+            else:
+                self._tree.root.add_leaf(label, data=item.turn_id)
+
+    def on_tree_node_selected(self, event: Tree.NodeSelected[str]) -> None:
+        if event.node.data is not None:
+            self.post_message(self.TurnSelected(event.node.data))

chrys/app/tui/widgets/sidebar/toc_types.py

@@ -0,0 +1,30 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Pure table-of-contents data types shared by chat and sidebar widgets."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class TocItem:
+    """TOC item data structure."""
+
+    turn_id: str
+    summary: str
+    children: list[TocItem] = field(default_factory=list)
+    compressed: bool = False
+    turn_index: int | None = None
+
+
+_SUMMARY_MAX_LENGTH = 120
+
+
+def summarize_prompt(text: str, max_length: int = _SUMMARY_MAX_LENGTH) -> str:
+    if not text:
+        return "(empty)"
+    first_line = text.split("\n", 1)[0]
+    if len(first_line) > max_length:
+        return first_line[: max_length - 3] + "..."
+    return first_line

chrys/app/tui/widgets/syntax_theme.py

@@ -0,0 +1,85 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Theme-adaptive, background-transparent syntax highlighting helpers.
+
+``rich`` ``Syntax`` bakes a Pygments theme background into every token, which
+clashes with the Textual surface and looks like a hard black box on light
+themes. :class:`TransparentPygmentsTheme` strips those backgrounds so the
+widget's own (theme-driven) background shows through, and :func:`transparent_syntax`
+picks a Pygments style that matches the active dark/light theme.
+"""
+
+from __future__ import annotations
+
+from pygments.token import Error, Generic
+from rich.style import Style as RichStyle
+from rich.syntax import PygmentsSyntaxTheme, Syntax
+from textual.highlight import HighlightTheme
+
+
+class NoErrorHighlightTheme(HighlightTheme):
+    """Textual highlight theme that does not style Pygments error tokens."""
+
+    STYLES: dict[tuple[str, ...], str] = {  # noqa: RUF012 - Textual requires a mutable theme mapping.
+        token_type: style
+        for token_type, style in HighlightTheme.STYLES.items()
+        if token_type not in {Error, Generic.Error}
+    }
+
+
+class TransparentPygmentsTheme(PygmentsSyntaxTheme):
+    """``PygmentsSyntaxTheme`` variant that strips **all** ``bgcolor`` values.
+
+    ``PygmentsSyntaxTheme.get_style_for_token`` falls back to the theme's
+    ``background_color`` for every token (even ones that don't define a
+    background), which bleeds the Pygments background into every segment.
+    This subclass removes that fallback so the widget's own background
+    (from the Textual theme) shows through instead.
+    """
+
+    def __init__(self, theme: str) -> None:
+        super().__init__(theme)
+        self._clean_cache: dict[tuple[str, ...], RichStyle] = {}
+
+    def get_style_for_token(self, token_type: tuple[str, ...]) -> RichStyle:
+        try:
+            return self._clean_cache[token_type]
+        except KeyError:
+            style = super().get_style_for_token(token_type)
+            if style.bgcolor is not None:
+                style = RichStyle(
+                    color=style.color,
+                    bold=style.bold,
+                    dim=style.dim,
+                    italic=style.italic,
+                    underline=style.underline,
+                    overline=style.overline,
+                    strike=style.strike,
+                    link=style.link,
+                )
+            self._clean_cache[token_type] = style
+            return style
+
+    def get_background_style(self) -> RichStyle:
+        return RichStyle.null()
+
+
+def transparent_syntax(
+    code: str,
+    language: str,
+    *,
+    dark: bool,
+    line_numbers: bool = False,
+    start_line: int = 1,
+    word_wrap: bool = True,
+) -> Syntax:
+    """Build a ``Syntax`` with a transparent, theme-matched Pygments style."""
+    theme = TransparentPygmentsTheme("native" if dark else "default")
+    return Syntax(
+        code,
+        language,
+        theme=theme,
+        line_numbers=line_numbers,
+        start_line=start_line,
+        word_wrap=word_wrap,
+    )