iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/terminal/shell.py

@@ -0,0 +1,273 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The shell behind a `Terminal`: starts it, pipes the two together, and ends it."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from collections.abc import Callable
+from contextlib import suppress
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final
+
+from textual import log
+from textual.message import Message
+
+from chrys import __version__
+from chrys.app.tui.terminal._pty_backend import IS_WINDOWS
+from chrys.app.tui.terminal.pty_process import PtyProcess, spawn_pty_process
+from chrys.app.tui.terminal.shell_integration import ShellLaunch, prepare_shell_launch
+from chrys.foundation.branding import APP_DISPLAY_NAME
+from chrys.foundation.i18n import MessageRef, msg
+from chrys.foundation.platform.runtime_paths import reorder_path_demoting_runtime
+
+if TYPE_CHECKING:
+    from chrys.app.tui.terminal.widget import Terminal
+
+_CLOSE_TASK_TIMEOUT: Final = 2.0
+_DEFAULT_PTY_SIZE: Final = (80, 24)
+
+# How the terminal we run in introduced itself to its programs. The shell is in a different
+# terminal now, and a program that believed these would speak the outer one's private protocols
+# to us. Apple's session variable also makes zsh announce a "restored session" on every start.
+_OUTER_TERMINAL_VARIABLES: Final = (
+    "TERM_PROGRAM",
+    "TERM_PROGRAM_VERSION",
+    "TERM_SESSION_ID",
+    "ITERM_SESSION_ID",
+    "KITTY_WINDOW_ID",
+    "VTE_VERSION",
+    "WT_SESSION",
+    "WT_PROFILE_ID",
+)
+
+_SHELL_FAILED = msg("tui.terminal.shell.failed", fallback="Shell failed: {error}")
+_SHELL_START_FAILED = msg("tui.terminal.shell.start_failed", fallback="Unable to start shell: {error}")
+
+
+@dataclass
+class ShellFinished(Message):
+    """The shell process exited."""
+
+
+def _shell_environment() -> dict[str, str]:
+    env = os.environ.copy()
+    for name in _OUTER_TERMINAL_VARIABLES:
+        env.pop(name, None)
+    env.update(
+        TERM="xterm-256color",
+        COLORTERM="truecolor",
+        CLICOLOR="1",
+        TERM_PROGRAM=APP_DISPLAY_NAME,
+        TERM_PROGRAM_VERSION=__version__,
+        # Lets a program, ours included, tell that it runs inside this app.
+        CHRYS="1",
+        # Output is decoded as UTF-8, which Python on Windows does not write unless told to.
+        PYTHONUTF8="1",
+    )
+    reorder_path_demoting_runtime(env)
+    return env
+
+
+class Shell:
+    """One shell process, shown in one `Terminal`."""
+
+    def __init__(
+        self,
+        terminal: Terminal,
+        working_directory: str,
+        shell_command: str = "",
+        on_error: Callable[[MessageRef], None] | None = None,
+    ) -> None:
+        self.terminal = terminal
+        self.working_directory = working_directory
+        self.shell_command = shell_command or ("pwsh" if IS_WINDOWS else os.environ.get("SHELL", "sh"))
+        self.on_error = on_error
+        self._process: PtyProcess | None = None
+        self._launch: ShellLaunch | None = None
+        self._task: asyncio.Task[None] | None = None
+        self._finished = False
+        self._ready = asyncio.Event()
+        self._requested_size = _DEFAULT_PTY_SIZE
+        self._resize_lock = asyncio.Lock()
+        self._input: asyncio.Queue[str] | None = None
+        self._input_writer: asyncio.Task[None] | None = None
+
+    @property
+    def is_finished(self) -> bool:
+        return self._finished
+
+    @property
+    def pty_size(self) -> tuple[int, int] | None:
+        """The size the shell was last told of; ``None`` while it has been told of none."""
+        return None if self._process is None else self._process.size
+
+    async def wait_for_ready(self) -> None:
+        """Wait until the shell takes input, or has turned out never to."""
+        await self._ready.wait()
+
+    def start(self) -> None:
+        if self._task is not None:
+            raise RuntimeError("The terminal shell has already been started.")
+        self._task = asyncio.create_task(self.run(), name=repr(self))
+
+    # -- talking to the shell ----------------------------------------------------------------------
+
+    async def send(self, command: str, width: int, height: int) -> None:
+        """Run ``command`` as if typed at the prompt of a ``width`` by ``height`` terminal."""
+        await self._ready.wait()
+        if self._process is None:
+            return
+        # The size first: a prompt drawn for another width smears when the command is echoed.
+        await self.resize(width, height)
+        await self.write(f"{command}\r")
+
+    async def interrupt(self) -> None:
+        """Send Ctrl+C."""
+        await self.write("\x03")
+
+    async def write(self, data: str) -> None:
+        """Type ``data`` into the shell at once."""
+        if (process := self._process) is not None:
+            await process.write(data)
+
+    async def write_input_queued(self, data: str) -> None:
+        """Type ``data`` into the shell after whatever is already waiting.
+
+        Keys, pastes and pointer reports come faster than the shell takes them one by one. Queued,
+        everything that piled up during a write goes out as the next.
+        """
+        if self._process is None or not data:
+            return
+        if self._input is None:
+            self._input = asyncio.Queue()
+        self._input.put_nowait(data)
+        if self._input_writer is None or self._input_writer.done():
+            self._input_writer = asyncio.create_task(self._write_queued_input(self._input))
+
+    async def _write_queued_input(self, queue: asyncio.Queue[str]) -> None:
+        while not self._finished:
+            pending = [await queue.get()]
+            # One turn of the loop lets the rest of a burst arrive.
+            await asyncio.sleep(0)
+            with suppress(asyncio.QueueEmpty):
+                while True:
+                    pending.append(queue.get_nowait())
+            await self._settle_size()
+            await self.write("".join(pending))
+
+    async def _settle_size(self) -> None:
+        """Have the shell know the terminal's size before input makes it redraw its prompt."""
+        while True:
+            size = (self.terminal.width, self.terminal.height)
+            await self.resize(*size)
+            if (self.terminal.width, self.terminal.height) == size:
+                return
+
+    async def resize(self, width: int, height: int) -> None:
+        """Tell the shell its terminal has a new size."""
+        async with self._resize_lock:
+            size = self._positive_size(width, height)
+            if (process := self._process) is not None and process.size != size:
+                await process.resize(*size)
+
+    def _positive_size(self, width: int, height: int) -> tuple[int, int]:
+        """The size to use: a hidden widget measures 0x0, which stands for the last real size."""
+        if width > 0 and height > 0:
+            self._requested_size = (width, height)
+        return self._requested_size
+
+    # -- life cycle --------------------------------------------------------------------------------
+
+    def terminate(self) -> None:
+        """End the shell now. `close` also waits for it to be gone."""
+        self._stop_input_writer()
+        if self._finished:
+            return
+        if (process := self._process) is not None:
+            self._process = None
+            process.kill()
+        self._mark_finished()
+
+    async def close(self) -> None:
+        self.terminate()
+        if (task := self._task) is None:
+            return
+        try:
+            if task is not asyncio.current_task() and not task.done():
+                await asyncio.wait_for(task, timeout=_CLOSE_TASK_TIMEOUT)
+        except TimeoutError:
+            task.cancel()
+            with suppress(asyncio.CancelledError):
+                await task
+        except Exception as error:
+            log(f"shell did not close cleanly: {error!r}")
+        finally:
+            if self._task is task:
+                self._task = None
+
+    async def run(self) -> None:
+        """Start the shell and show its output until it ends."""
+        try:
+            await self._run()
+        except Exception as error:
+            log(f"shell failed: {error!r}")
+            self._report(_SHELL_FAILED.bind(error=str(error)))
+        finally:
+            self._stop_input_writer()
+            self._mark_finished(announce=True)
+
+    async def _run(self) -> None:
+        if self._finished:
+            return
+        env = _shell_environment()
+        self._launch = launch = prepare_shell_launch(self.shell_command, env)
+        columns, lines = self._positive_size(self.terminal.width, self.terminal.height)
+        try:
+            process = await spawn_pty_process(
+                launch.argv, env=env, cwd=self.working_directory, columns=columns, lines=lines
+            )
+        except Exception as error:
+            log(f"unable to start shell: {error!r}")
+            self._report(_SHELL_START_FAILED.bind(error=str(error)))
+            return
+        try:
+            if self._finished:
+                # Terminated while it was starting.
+                process.kill()
+                return
+            self._process = process
+            self.terminal.host_repaints = process.repaints_after_resize
+            self.terminal.set_write_to_stdin(self.write_input_queued)
+            self._ready.set()
+            while output := await process.read():
+                try:
+                    await self.terminal.write(output)
+                except Exception as error:
+                    # One chunk the terminal chokes on must not take the shell down with it.
+                    log(f"terminal rejected shell output: {error!r}")
+        finally:
+            self._process = None
+            await process.close()
+
+    def _report(self, error: MessageRef) -> None:
+        if self.on_error is not None:
+            self.on_error(error)
+
+    def _stop_input_writer(self) -> None:
+        if self._input_writer is not None:
+            self._input_writer.cancel()
+            self._input_writer = None
+        self._input = None
+
+    def _mark_finished(self, *, announce: bool = False) -> None:
+        already_finished = self._finished
+        self._finished = True
+        # Whoever waits for the shell to be ready should stop: it never will be.
+        self._ready.set()
+        if self._launch is not None:
+            self._launch.clean_up()
+            self._launch = None
+        if announce and not already_finished:
+            self.terminal.post_message(ShellFinished())

chrys/app/tui/terminal/shell_integration.py

@@ -0,0 +1,199 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Getting a shell to report what it is doing.
+
+Each supported shell is started with hooks of its own kind that print two private OSC reports,
+which the terminal emulator turns into events: the working directory ahead of every prompt
+(OSC 2025) and the command line about to run (OSC 2026). Payloads travel as base64, so no path or
+command can end the sequence early. The hooks load with the shell's start-up files and echo nothing.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path, PurePath
+
+from chrys.app.tui.terminal._pty_backend import IS_WINDOWS
+from chrys.foundation.platform.command_line import split_windows_command_line
+
+_POSIX_REPORTS = r"""
+__chrys_b64() { printf "%s" "$1" | base64 | tr -d "\n"; }
+__chrys_report() { printf "\e]%s;b64:%s\e\\" "$1" "$(__chrys_b64 "$2")"; }
+"""
+
+# zsh reads its start-up files from ZDOTDIR, so ours stand in for the user's and read those first.
+# The user's .zshenv may itself move ZDOTDIR; whatever it leaves is where their .zshrc is.
+_ZSH_ENV = """\
+__chrys_init_dir="$ZDOTDIR"
+ZDOTDIR={user_zdotdir}
+[[ -f "$ZDOTDIR/.zshenv" ]] && source "$ZDOTDIR/.zshenv"
+__chrys_user_zdotdir="$ZDOTDIR"
+ZDOTDIR="$__chrys_init_dir"
+unset __chrys_init_dir
+"""
+
+_ZSH_RC = (
+    """\
+ZDOTDIR="$__chrys_user_zdotdir"
+unset __chrys_user_zdotdir
+[[ -f "$ZDOTDIR/.zshrc" ]] && source "$ZDOTDIR/.zshrc"
+"""
+    + _POSIX_REPORTS
+    + """\
+__chrys_preexec() { __chrys_report 2026 "$1"; }
+__chrys_precmd() { __chrys_report 2025 "$PWD"; }
+precmd_functions+=(__chrys_precmd)
+preexec_functions+=(__chrys_preexec)
+"""
+)
+
+# bash has no preexec. Its DEBUG trap fires before every simple command, so the first one after a
+# prompt stands for the command line, whose full text is the history entry it just became. The
+# user's own prompt commands are simple commands too; ours bracket them, so that the trap can tell
+# them from a command line and they still see the exit status of the last one.
+_BASH_RC = (
+    """\
+[[ -f ~/.bashrc ]] && source ~/.bashrc
+"""
+    + _POSIX_REPORTS
+    + """\
+__chrys_at_prompt=false
+__chrys_read_history() {
+  local entry pattern='^[[:space:]]*([0-9]+)[* ] (.*)$'
+  entry="$(HISTTIMEFORMAT= builtin history 1)"
+  if [[ $entry =~ $pattern ]]; then
+    __chrys_entry_number="${BASH_REMATCH[1]}" __chrys_entry_text="${BASH_REMATCH[2]}"
+  else
+    __chrys_entry_number="" __chrys_entry_text=""
+  fi
+}
+__chrys_preexec() {
+  [[ $BASH_COMMAND == __chrys_prompt_begin ]] && __chrys_at_prompt=false
+  [[ $__chrys_at_prompt == true ]] || return
+  __chrys_at_prompt=false
+  __chrys_read_history
+  if [[ $__chrys_entry_number != "$__chrys_prompt_number" || $__chrys_entry_text == "$BASH_COMMAND"* ]]; then
+    # A new history entry is the line just entered. So is an old one that begins with the command
+    # now starting: the line was a repeat, which the history keeps once.
+    __chrys_report 2026 "$__chrys_entry_text"
+  else
+    # Kept out of the history on purpose, or there is no history. This much of it is certain.
+    __chrys_report 2026 "$BASH_COMMAND"
+  fi
+}
+__chrys_prompt_begin() { return "$?"; }
+__chrys_precmd() {
+  __chrys_report 2025 "$PWD"
+  __chrys_read_history
+  __chrys_prompt_number="$__chrys_entry_number"
+  __chrys_at_prompt=true
+}
+if (( BASH_VERSINFO[0] > 5 || (BASH_VERSINFO[0] == 5 && BASH_VERSINFO[1] >= 1) )); then
+  PROMPT_COMMAND=(__chrys_prompt_begin "${PROMPT_COMMAND[@]}" __chrys_precmd)
+else
+  __chrys_theirs="${PROMPT_COMMAND%"${PROMPT_COMMAND##*[![:space:];]}"}"
+  PROMPT_COMMAND="__chrys_prompt_begin;${__chrys_theirs:+$__chrys_theirs;}__chrys_precmd"
+  unset __chrys_theirs
+fi
+trap '__chrys_preexec' DEBUG
+"""
+)
+
+_FISH_HOOKS = (
+    'function __chrys_report; printf "\\e]%s;b64:%s\\e\\\\" $argv[1] (printf "%s" "$argv[2]" | base64 | tr -d "\\n"); end; '
+    'function __chrys_preexec --on-event fish_preexec; __chrys_report 2026 "$argv"; end; '
+    "function __chrys_prompt --on-event fish_prompt; __chrys_report 2025 (pwd); end"
+)
+
+_POWERSHELL_HOOKS = (
+    "function global:__chrys_report($code, $text) {"
+    " $e = [char]27; $st = [char]92;"
+    " $payload = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($text));"
+    ' return "$e]$code;b64:$payload$e$st"'
+    "};"
+    "function prompt {"
+    " Write-Host -NoNewline (__chrys_report 2025 (Get-Location).Path);"
+    ' return "PS $($executionContext.SessionState.Path.CurrentLocation)> "'
+    "};"
+    "if (Get-Module PSReadLine) {"
+    " Set-PSReadLineOption -AddToHistoryHandler {"
+    "  param($command)"
+    "  [Console]::Write((__chrys_report 2026 $command));"
+    "  return $true"
+    " }"
+    "}"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ShellLaunch:
+    """How to start a shell so that it reports to us."""
+
+    argv: list[str]
+    scratch_directory: str | None = None
+    """Holds start-up files written for this shell. The shell reads them once; whoever started it
+    removes the directory when the shell is gone."""
+
+    def clean_up(self) -> None:
+        if self.scratch_directory is not None:
+            shutil.rmtree(self.scratch_directory, ignore_errors=True)
+
+
+def prepare_shell_launch(command: str, env: dict[str, str]) -> ShellLaunch:
+    """Work out the argv that starts ``command`` with reporting hooks, adjusting ``env`` to match.
+
+    A shell we have no hooks for starts as it is; it works, and reports nothing.
+    """
+    argv = _split_command(command)
+    program, arguments = argv[0], argv[1:]
+    name = PurePath(program).stem.lower()
+    if name.startswith("zsh"):
+        return _launch_zsh(argv, env)
+    if name.startswith("bash"):
+        scratch = _write_scratch("chrys_bash_", {"init.bash": _BASH_RC})
+        rcfile = Path(scratch, "init.bash")
+        # bash wants its long options ahead of any short ones.
+        return ShellLaunch([program, "--rcfile", str(rcfile), *arguments], scratch)
+    if name.startswith("fish"):
+        return ShellLaunch([*argv, "-C", _FISH_HOOKS])
+    if name.startswith(("pwsh", "powershell")):
+        return ShellLaunch([*argv, "-NoExit", "-Command", _POWERSHELL_HOOKS])
+    return ShellLaunch(argv)
+
+
+def _split_command(command: str) -> list[str]:
+    if os.path.exists(command):
+        # A path, spaces and all (C:\Program Files\...), not a command line.
+        return [command]
+    try:
+        argv = split_windows_command_line(command) if IS_WINDOWS else shlex.split(command)
+    except ValueError:
+        argv = []
+    return argv or [command]
+
+
+def _write_scratch(prefix: str, files: dict[str, str]) -> str:
+    """Write shell startup files, removing their directory if any write fails."""
+    scratch = tempfile.mkdtemp(prefix=prefix)
+    try:
+        for name, content in files.items():
+            Path(scratch, name).write_text(content, encoding="utf-8")
+    except BaseException:
+        shutil.rmtree(scratch, ignore_errors=True)
+        raise
+    return scratch
+
+
+def _launch_zsh(argv: list[str], env: dict[str, str]) -> ShellLaunch:
+    # The home the shell will see, which is where it would have looked.
+    user_zdotdir = env.get("ZDOTDIR") or env.get("HOME") or os.path.expanduser("~")
+    scratch = _write_scratch(
+        "chrys_zsh_",
+        {".zshenv": _ZSH_ENV.format(user_zdotdir=shlex.quote(user_zdotdir)), ".zshrc": _ZSH_RC},
+    )
+    env["ZDOTDIR"] = scratch
+    return ShellLaunch(argv, scratch)

chrys/app/tui/terminal/title.py

@@ -0,0 +1,224 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Terminal title helpers for native TUI runs."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+import unicodedata
+from collections.abc import Callable
+
+BASE_TERMINAL_TITLE = ""
+
+_MESSAGE_TITLE_CHARS = 100
+_TEXTUAL_WEB_DRIVER = "textual.drivers.web_driver:WebDriver"
+_TitleWriter = Callable[[str], None]
+_ESC = "\x1b"
+_BEL = "\x07"
+_ST = "\x9c"
+
+
+def set_terminal_title(title: str, *, writer: _TitleWriter | None = None) -> None:
+    """Set the terminal window title with OSC 0 and OSC 2."""
+    if running_under_textual_web_driver():
+        return
+
+    safe_title = _title_safe_text(title)
+    sequence = f"\x1b]0;{safe_title}\x07\x1b]2;{safe_title}\x07"
+    with contextlib.suppress(Exception):
+        if writer is not None:
+            writer(sequence)
+        else:
+            sys.stderr.write(sequence)
+            sys.stderr.flush()
+
+
+def set_app_terminal_title_for_cwd(
+    app: object,
+    cwd: str | os.PathLike[str],
+    *,
+    indicator: str = "",
+) -> None:
+    """Set the terminal title for a Textual app's active workspace directory."""
+    writer = _app_terminal_title_writer(app)
+    if writer is None:
+        return
+    title = terminal_title_for_cwd(cwd)
+    if indicator:
+        title = f"{indicator} {title}" if title else indicator
+    set_terminal_title(title, writer=writer)
+
+
+def set_app_terminal_title_for_current_cwd(app: object) -> None:
+    """Set the terminal title for a Textual app using the current working directory."""
+    writer = _app_terminal_title_writer(app)
+    if writer is None:
+        return
+    set_terminal_title_for_current_cwd(writer=writer)
+
+
+def set_app_terminal_title_for_user_message(app: object, text: str) -> None:
+    """Set the terminal title for a Textual app using a user prompt preview."""
+    writer = _app_terminal_title_writer(app)
+    if writer is None:
+        return
+    set_terminal_title_for_user_message(text, writer=writer)
+
+
+def set_app_terminal_title_for_session_title(app: object, title: str) -> None:
+    """Set the terminal title for a Textual app using the session display title."""
+    writer = _app_terminal_title_writer(app)
+    if writer is None:
+        return
+    set_terminal_title_for_session_title(title, writer=writer)
+
+
+def set_terminal_title_for_cwd(cwd: str | os.PathLike[str], *, writer: _TitleWriter | None = None) -> None:
+    """Set the title to the current directory path."""
+    set_terminal_title(terminal_title_for_cwd(cwd), writer=writer)
+
+
+def set_terminal_title_for_current_cwd(*, writer: _TitleWriter | None = None) -> None:
+    """Set the title using ``os.getcwd()``, or the base title if cwd is unavailable."""
+    try:
+        cwd = os.getcwd()
+    except OSError:
+        set_terminal_title(BASE_TERMINAL_TITLE, writer=writer)
+        return
+    set_terminal_title_for_cwd(cwd, writer=writer)
+
+
+def set_terminal_title_for_user_message(text: str, *, writer: _TitleWriter | None = None) -> None:
+    """Set the title to a prompt preview."""
+    set_terminal_title(terminal_title_for_user_message(text), writer=writer)
+
+
+def set_terminal_title_for_session_title(title: str, *, writer: _TitleWriter | None = None) -> None:
+    """Set the title to the session title."""
+    set_terminal_title(terminal_title_for_session_title(title), writer=writer)
+
+
+def terminal_title_for_cwd(cwd: str | os.PathLike[str]) -> str:
+    """Build the terminal title for a workspace directory."""
+    raw_path = os.fspath(cwd)
+    if not os.path.isdir(raw_path):
+        return BASE_TERMINAL_TITLE
+    path = _title_safe_text(raw_path)
+    if not path:
+        return BASE_TERMINAL_TITLE
+    return path
+
+
+def terminal_title_for_user_message(text: str) -> str:
+    """Build the terminal title for a submitted user message."""
+    fragment = _message_title_fragment(text)
+    return fragment or BASE_TERMINAL_TITLE
+
+
+def terminal_title_for_session_title(title: str) -> str:
+    """Build the terminal title for a session display title."""
+    fragment = _message_title_fragment(title)
+    return fragment or BASE_TERMINAL_TITLE
+
+
+def _message_title_fragment(text: str) -> str:
+    safe_text = _title_safe_text(text)
+    return safe_text[:_MESSAGE_TITLE_CHARS]
+
+
+def _title_safe_text(text: str) -> str:
+    text = _strip_terminal_sequences(text)
+    parts: list[str] = []
+    pending_space = False
+    for ch in text.strip():
+        if ch.isspace():
+            pending_space = bool(parts)
+            continue
+        if unicodedata.category(ch).startswith("C"):
+            continue
+        if pending_space:
+            parts.append(" ")
+            pending_space = False
+        parts.append(ch)
+    return "".join(parts)
+
+
+def _strip_terminal_sequences(text: str) -> str:
+    """Remove ANSI/OSC-style control sequences before title filtering."""
+    result: list[str] = []
+    i = 0
+    while i < len(text):
+        ch = text[i]
+        if ch == _ESC:
+            i = _skip_esc_sequence(text, i)
+            continue
+        if ch == "\x9b":
+            i = _skip_until_csi_final(text, i + 1)
+            continue
+        if ch == "\x9d":
+            i = _skip_until_string_terminator(text, i + 1)
+            continue
+        if ch in {"\x90", "\x98", "\x9e", "\x9f"}:
+            i = _skip_until_string_terminator(text, i + 1)
+            continue
+        result.append(ch)
+        i += 1
+    return "".join(result)
+
+
+def _skip_esc_sequence(text: str, start: int) -> int:
+    next_index = start + 1
+    if next_index >= len(text):
+        return next_index
+
+    introducer = text[next_index]
+    if introducer == "[":
+        return _skip_until_csi_final(text, next_index + 1)
+    if introducer == "]":
+        return _skip_until_string_terminator(text, next_index + 1)
+    if introducer in {"P", "X", "^", "_"}:
+        return _skip_until_string_terminator(text, next_index + 1)
+
+    i = next_index
+    while i < len(text) and 0x20 <= ord(text[i]) <= 0x2F:
+        i += 1
+    if i < len(text) and 0x30 <= ord(text[i]) <= 0x7E:
+        return i + 1
+    return next_index + 1
+
+
+def _skip_until_csi_final(text: str, start: int) -> int:
+    i = start
+    while i < len(text):
+        if 0x40 <= ord(text[i]) <= 0x7E:
+            return i + 1
+        i += 1
+    return i
+
+
+def _skip_until_string_terminator(text: str, start: int) -> int:
+    i = start
+    while i < len(text):
+        if text[i] == _BEL or text[i] == _ST:
+            return i + 1
+        if text[i] == _ESC and i + 1 < len(text) and text[i + 1] == "\\":
+            return i + 2
+        i += 1
+    return i
+
+
+def _app_terminal_title_writer(app: object) -> _TitleWriter | None:
+    # Textual has no public raw terminal writer; keep the private driver
+    # boundary here instead of spreading it through screens.
+    driver = getattr(app, "_driver", None)
+    write = getattr(driver, "write", None)
+    if not callable(write):
+        return None
+    return write
+
+
+def running_under_textual_web_driver() -> bool:
+    """Return true when Chrys is hosted by textual-serve."""
+    return os.environ.get("TEXTUAL_DRIVER") == _TEXTUAL_WEB_DRIVER