provide-uterm 0.5.1__tar.gz

provide_uterm-0.5.1/MANIFEST.in

@@ -0,0 +1,6 @@
+prune .uterm-recordings
+prune .uterm-recordings-proof
+prune .tmp-proof-reel
+prune .tmp-playwright-videos
+prune .tmp-frontend-coverage
+global-exclude *.jsonl

provide_uterm-0.5.1/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: provide-uterm
+Version: 0.5.1
+Summary: Shared terminal I/O primitives for the provide ecosystem
+Author: provide.io llc
+License-Expression: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/provide-io/provide-uterm
+Project-URL: Repository, https://github.com/provide-io/provide-uterm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Terminals
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: provide-telemetry>=0.7
+Requires-Dist: aiosqlite>=0.22
+Requires-Dist: pydantic>=2.0
+Provides-Extra: emulator
+Requires-Dist: pyte>=0.8; extra == "emulator"
+Provides-Extra: ssh
+Requires-Dist: asyncssh>=2.14; extra == "ssh"
+Provides-Extra: client
+Requires-Dist: httpx2>=2.10; extra == "client"
+Provides-Extra: all
+Requires-Dist: pyte>=0.8; extra == "all"
+Requires-Dist: asyncssh>=2.14; extra == "all"
+Requires-Dist: httpx2>=2.10; extra == "all"
+
+# provide-uterm
+
+Core shared package for the [provide-uterm](../../README.md) platform. It
+contains terminal I/O primitives, screen parsing, replay helpers, detection,
+rendering, and small operator-facing utilities used by the split companion
+packages.
+
+## What's in this package
+
+| Module | Purpose |
+|--------|---------|
+| `ansi.py`, `colors/`, `render/` | ANSI processing, color transforms, render helpers |
+| `screen.py`, `detection/` | Screen cleanup, prompt parsing, semantic extraction |
+| `telnet_session.py`, `line_editor.py` | Terminal session and local editing helpers |
+| `replay/`, `session_logger.py` | Recording and replay utilities |
+| Root package exports | Curated shared primitives such as `strip_ansi`, `normalize_colors`, `LineEditor`, and file loaders |
+
+## Installation
+
+```bash
+pip install 'provide-uterm[all]'
+```
+
+See the [main README](../../README.md) for extras and quick start guides.
+
+## Split Packages
+
+| Package | Owns |
+|---------|--------|
+| `provide-uterm` | Shared terminal primitives and root facade exports, plus `provide.uterm.bridge` (HijackableMixin, contracts, schemas) |
+| `provide-uterm-server` | `provide.uterm.server` (incl. `provide.uterm.server.bridge`), `provide.uterm.gateway`, `provide.uterm.tunnel` |
+| `provide-uterm-platform` | `provide.uterm.manager`, `provide.uterm.pty` |
+| `provide-uterm-client` | Client-side session control and MCP tooling |
+
+## Related Packages
+
+This package depends on several companion packages via workspace symlinks. See the [package ecosystem table](../../README.md#package-ecosystem) for the full list.
+
+## License
+
+AGPL-3.0-or-later. Copyright (c) 2025-2026 provide.io llc.

provide_uterm-0.5.1/README.md

@@ -0,0 +1,41 @@
+# provide-uterm
+
+Core shared package for the [provide-uterm](../../README.md) platform. It
+contains terminal I/O primitives, screen parsing, replay helpers, detection,
+rendering, and small operator-facing utilities used by the split companion
+packages.
+
+## What's in this package
+
+| Module | Purpose |
+|--------|---------|
+| `ansi.py`, `colors/`, `render/` | ANSI processing, color transforms, render helpers |
+| `screen.py`, `detection/` | Screen cleanup, prompt parsing, semantic extraction |
+| `telnet_session.py`, `line_editor.py` | Terminal session and local editing helpers |
+| `replay/`, `session_logger.py` | Recording and replay utilities |
+| Root package exports | Curated shared primitives such as `strip_ansi`, `normalize_colors`, `LineEditor`, and file loaders |
+
+## Installation
+
+```bash
+pip install 'provide-uterm[all]'
+```
+
+See the [main README](../../README.md) for extras and quick start guides.
+
+## Split Packages
+
+| Package | Owns |
+|---------|--------|
+| `provide-uterm` | Shared terminal primitives and root facade exports, plus `provide.uterm.bridge` (HijackableMixin, contracts, schemas) |
+| `provide-uterm-server` | `provide.uterm.server` (incl. `provide.uterm.server.bridge`), `provide.uterm.gateway`, `provide.uterm.tunnel` |
+| `provide-uterm-platform` | `provide.uterm.manager`, `provide.uterm.pty` |
+| `provide-uterm-client` | Client-side session control and MCP tooling |
+
+## Related Packages
+
+This package depends on several companion packages via workspace symlinks. See the [package ecosystem table](../../README.md#package-ecosystem) for the full list.
+
+## License
+
+AGPL-3.0-or-later. Copyright (c) 2025-2026 provide.io llc.

provide_uterm-0.5.1/VERSION

@@ -0,0 +1 @@
+0.5.1

provide_uterm-0.5.1/pyproject.toml

@@ -0,0 +1,178 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "provide-uterm"
+dynamic = ["version"]
+description = "Shared terminal I/O primitives for the provide ecosystem"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "AGPL-3.0-or-later"
+authors = [
+  {name = "provide.io llc"},
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Networking",
+    "Topic :: Terminals",
+    "Framework :: FastAPI",
+]
+# pydantic is a RUNTIME dependency, not a dev one: bridge/schemas.py defines the
+# wire-format frame models, and the eager provide/uterm/__init__.py pulls it in
+# on import. It was only ever declared in the dev extra and arrived transitively
+# everywhere else, so the omission stayed invisible until a lock refresh stopped
+# supplying it and CI's isolated `--package` env failed to import pydantic.
+dependencies = ["provide-telemetry>=0.7", "aiosqlite>=0.22", "pydantic>=2.0"]
+
+[project.urls]
+Homepage = "https://github.com/provide-io/provide-uterm"
+Repository = "https://github.com/provide-io/provide-uterm"
+
+[project.optional-dependencies]
+emulator  = ["pyte>=0.8"]
+ssh       = ["asyncssh>=2.14"]
+client    = ["httpx2>=2.10"]
+all       = ["pyte>=0.8", "asyncssh>=2.14", "httpx2>=2.10"]
+
+[tool.setuptools.dynamic]
+version = {file = "VERSION"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"provide.uterm" = [
+    "py.typed",
+]
+
+[dependency-groups]
+dev = [
+    "asyncssh>=2.22.0",
+    "bandit>=1.9",
+    "codespell>=2.4.1",
+    "detect-secrets>=1.5.0",
+    "fastapi>=0.110",
+    "httpx2>=2.10",
+    "hypothesis>=6.151.9",
+    "memray>=1.0; sys_platform != 'win32'",
+    "mutmut>=3.3.1",
+    "mypy>=1.19",
+    "pip-audit>=2.7.0",
+    "pip-licenses>=5.5.0",
+    "pre-commit>=4.0",
+    "pydantic>=2.0",
+    "pyjwt>=2.9",
+    "pyte>=0.8.2",
+    "pytest>=9.0",
+    "pytest-asyncio>=1.3",
+    "pytest-cov>=7.0",
+    "pytest-playwright>=0.7.2",
+    "pytest-randomly>=3.15.0",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.8",
+    "reuse>=6.2.0",
+    "ruff>=0.15",
+    "ty>=0.0.17",
+    "uv>=0.10.7",
+    "uvicorn>=0.24",
+    "vulture>=2.14",
+    "websockets>=16.0",
+    "pyyaml>=6.0",
+    "xenon>=0.9.3",
+    "mcp>=2.0.0",
+]
+
+[tool.pytest.ini_options]
+consider_namespace_packages = true
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore:websockets\\.legacy is deprecated; see .*:DeprecationWarning:websockets\\.legacy",
+    "ignore:websockets\\.server\\.WebSocketServerProtocol is deprecated:DeprecationWarning:uvicorn\\.protocols\\.websockets\\.websockets_impl",
+    "ignore:remove second argument of ws_handler:DeprecationWarning:websockets\\.legacy\\.server",
+]
+markers = [
+    "playwright: browser-based UI tests (deselected by default, run with -m playwright)",
+    "mutant: mutation-testing and mutmut-focused tests (deselected by default)",
+    "memray: memory profiling and allocation stress tests (deselected by default, run with -m memray)",
+    "slow: slow tests >10s (deselected by default)",
+    "docker: Docker-based E2E tests requiring a running Docker daemon (deselected by default, run with -m docker)",
+    "unit: fast unit tests with no I/O or external dependencies",
+]
+addopts = [
+    "--import-mode=importlib",
+    "-v",
+    "--strict-markers",
+    "--strict-config",
+    "--tb=short",
+    "-ra",
+    "-m",
+    "not playwright and not memray and not slow and not docker",
+    # Coverage scoped to this package's source dir. An import name can't be used
+    # (`provide.uterm` is a namespace shared by every package → would pull in
+    # server/client/cloudflare/… and report ~69%). This package-relative path
+    # only resolves when pytest's CWD is the package dir, so the gate MUST be run
+    # from here — CI and scripts/run_all_tests.py invoke it via
+    # `uv run --directory packages/provide-uterm pytest tests`. Waivers below.
+    "--cov=src/provide/uterm",
+    "--cov-branch",
+    "--cov-report=term-missing",
+    "--cov-fail-under=100",
+]
+
+[tool.coverage.run]
+# Measure the whole package source, not an enumerated module allowlist. This
+# keeps newly-added modules in the 100% gate by default. Genuinely
+# out-of-scope modules are listed explicitly in ``omit`` below so the waiver
+# is visible and grep-able (CORE-cov, 2026-05-28 remediation).
+source = ["src/provide/uterm"]
+omit = [
+    "tests/*",
+]
+branch = true
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+skip_covered = false
+# Only the standard explicit waiver remains. The previous broad
+# ``elif msg_type ==`` / ``more_body`` regex escape-hatches were removed
+# (CORE-cov): real branch tests now cover those dispatch fall-throughs, and
+# any genuinely-unreachable branch carries a per-site ``# pragma: no cover``
+# with an inline justification so the waiver is visible and grep-able.
+partial_branches = [
+    "pragma: no branch",
+]
+
+[tool.mutmut]
+max_children = 6
+source_paths = ["src/provide/uterm/"]
+also_copy = ["scripts/"]
+do_not_mutate = [
+    "src/provide/uterm/frontend/",
+    "src/provide/uterm/transports/",
+    "src/provide/uterm/gateway.py",
+    "src/provide/uterm/server/connectors/",
+]
+pytest_add_cli_args = ["--no-cov", "--timeout=30"]
+pytest_add_cli_args_test_selection = [
+    "tests/",
+    "tests_mutation/",
+    "-m",
+    "not playwright",
+    "--ignore=tests/example/test_server_e2e.py",
+    "--ignore=tests/bridge/test_hypothesis.py",
+    "--ignore=tests/e2e",
+]

provide_uterm-0.5.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

provide_uterm-0.5.1/src/provide/uterm/__init__.py

@@ -0,0 +1,172 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+
+"""provide-uterm: shared terminal I/O primitives for the provide ecosystem.
+
+Server, gateway, bridge, manager, and telnet session APIs live in split
+packages and should be imported from their explicit submodules.
+"""
+
+from __future__ import annotations
+
+import pkgutil
+from importlib import import_module
+
+# Allow other installed packages to contribute sub-packages under provide.uterm
+# (e.g. provide-uterm-cloudflare contributes provide.uterm.cloudflare).
+__path__ = pkgutil.extend_path(__path__, __name__)
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("provide-uterm")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+from provide.uterm.terminal_frames import TerminalFrame, TerminalFrameDisconnectedError
+
+from provide.uterm.ansi import (
+    BOLD,
+    CLEAR_SCREEN,
+    DEFAULT_PALETTE,
+    DEFAULT_RGB,
+    RESET,
+    normalize_colors,
+    preview_ansi,
+    register_color_dialect,
+    registered_dialects,
+    unregister_color_dialect,
+    upgrade_to_256,
+    upgrade_to_truecolor,
+)
+from provide.uterm.auth import (
+    AuthorizedKeysFileResolver,
+    NullResolver,
+    ResolvedIdentity,
+    SSHKeyResolver,
+    fingerprint_from_openssh_blob,
+)
+from provide.uterm.colors import (
+    apply_color_mode,
+    downgrade_to_16,
+    downgrade_to_256,
+    rgb_to_16_index,
+    rgb_to_256,
+)
+from provide.uterm.control_channel_builders import (
+    make_identity,
+    make_link_patterns,
+    make_presence_update,
+    make_resume,
+    make_resume_failed,
+    make_resume_ok,
+    make_session_token,
+)
+from provide.uterm.control_channel_patterns import LinkPattern, LinkPatternRegistry
+from provide.uterm.file_io import load_ans, load_palette, load_txt
+from provide.uterm.line_editor import LineEditor
+from provide.uterm.render.segments import (
+    SEGMENT_COLOR_NAMES,
+    Segment,
+    ansi_to_segments,
+    tokens_to_segments,
+)
+from provide.uterm.screen import (
+    clean_screen_for_display,
+    decode_cp437,
+    encode_cp437,
+    extract_action_tags,
+    extract_key_value_pairs,
+    extract_menu_options,
+    extract_numbered_list,
+    normalize_terminal_text,
+    strip_ansi,
+)
+from provide.uterm.ws_bytes import (
+    channel_str_to_bytes,
+    ws_frame_to_channel_str,
+)
+
+__all__ = [
+    "__version__",
+    # ansi
+    "CLEAR_SCREEN",
+    "BOLD",
+    "RESET",
+    "DEFAULT_PALETTE",
+    "DEFAULT_RGB",
+    "normalize_colors",
+    "SEGMENT_COLOR_NAMES",
+    "Segment",
+    "ansi_to_segments",
+    "tokens_to_segments",
+    "preview_ansi",
+    "register_color_dialect",
+    "unregister_color_dialect",
+    "registered_dialects",
+    "upgrade_to_256",
+    "upgrade_to_truecolor",
+    # colors — downgrade counterparts
+    "apply_color_mode",
+    "downgrade_to_16",
+    "downgrade_to_256",
+    "rgb_to_16_index",
+    "rgb_to_256",
+    # file_io
+    "load_ans",
+    "load_txt",
+    "load_palette",
+    # line_editor
+    "LineEditor",
+    # screen
+    "strip_ansi",
+    "normalize_terminal_text",
+    "decode_cp437",
+    "encode_cp437",
+    "extract_action_tags",
+    "clean_screen_for_display",
+    "extract_menu_options",
+    "extract_numbered_list",
+    "extract_key_value_pairs",
+    # ws_bytes — lossless byte ↔ str shim for the inline control channel
+    "channel_str_to_bytes",
+    "ws_frame_to_channel_str",
+    # control_channel_builders — typed builders for ControlChannel protocol messages
+    "make_identity",
+    "make_session_token",
+    "make_resume",
+    "make_resume_ok",
+    "make_resume_failed",
+    "make_link_patterns",
+    "make_presence_update",
+    # control_channel_patterns — server-side link_patterns registry
+    "LinkPattern",
+    "LinkPatternRegistry",
+    # auth — pluggable SSH pubkey → identity
+    "AuthorizedKeysFileResolver",
+    "NullResolver",
+    "ResolvedIdentity",
+    "SSHKeyResolver",
+    # terminal frame lifecycle
+    "TerminalFrame",
+    "TerminalFrameDisconnectedError",
+    "fingerprint_from_openssh_blob",
+    # control-plane namespaces
+    "control_channel_namespace",
+    "control_plane_namespace",
+    "frames",
+    "channels",
+]
+
+from provide.uterm.control import channel as control_channel_namespace
+from provide.uterm.control import plane as control_plane_namespace
+
+
+def __getattr__(name: str) -> object:
+    if name == "frames":
+        return import_module("provide.uterm.frames")
+    if name == "channels":
+        return import_module("provide.uterm.channels")
+    raise AttributeError(name)

provide_uterm-0.5.1/src/provide/uterm/_ansi_dialects.py

@@ -0,0 +1,205 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+"""Built-in BBS color-token dialect handlers for :mod:`provide.uterm.ansi`.
+
+Self-contained ``str -> str`` converters for the extended-token, tilde-code,
+TWGS brace-token, and pipe-code dialects, plus their lookup tables. Split out
+of ``ansi.py`` to keep each module within the per-file line budget; the public
+surface (``normalize_colors`` + the dialect registry) stays in ``ansi.py``,
+which registers these handlers at import time.
+"""
+
+from __future__ import annotations
+
+import re
+
+_EXT_TOKEN_RE = re.compile(r"\{([FBPT])(\d{1,3})\}")
+
+# ---------------------------------------------------------------------------
+# Preview helpers (private)
+# ---------------------------------------------------------------------------
+
+_PREVIEW_COLOR_MAP = {
+    "k": 30,
+    "r": 31,
+    "g": 32,
+    "y": 33,
+    "b": 34,
+    "m": 35,
+    "c": 36,
+    "w": 37,
+}
+
+_TILDE_MAP: dict[str, tuple[str, str]] = {
+    "1": ("+", "g"),
+    "2": ("+", "w"),
+    "3": ("+", "c"),
+    "4": ("+", "r"),
+    "5": ("+", "m"),
+    "6": ("+", "y"),
+    "7": ("-", "w"),
+    "0": ("-", "x"),
+    "r": ("+", "r"),
+    "R": ("+", "r"),
+    "g": ("+", "g"),
+    "G": ("+", "g"),
+    "y": ("+", "y"),
+    "Y": ("+", "y"),
+    "b": ("+", "b"),
+    "B": ("+", "b"),
+    "m": ("+", "m"),
+    "M": ("+", "m"),
+    "c": ("+", "c"),
+    "C": ("+", "c"),
+    "w": ("+", "w"),
+    "W": ("+", "w"),
+    "d": ("-", "w"),
+    "D": ("-", "w"),
+    "E": ("+", "r"),
+}
+
+_BRACE_TOKEN_MAP: dict[str, str] = {
+    "{+c}": "\x1b[1;36m",
+    "{-c}": "\x1b[0;36m",
+    "{+r}": "\x1b[1;31m",
+    "{-r}": "\x1b[0;31m",
+    "{+g}": "\x1b[1;32m",
+    "{-g}": "\x1b[0;32m",
+    "{+y}": "\x1b[1;33m",
+    "{-y}": "\x1b[0;33m",
+    "{+b}": "\x1b[1;34m",
+    "{-b}": "\x1b[0;34m",
+    "{+m}": "\x1b[1;35m",
+    "{-m}": "\x1b[0;35m",
+    "{+w}": "\x1b[1;37m",
+    "{+Bw}": "\x1b[1;37m",
+    "{-w}": "\x1b[0;37m",
+    "{+k}": "\x1b[1;30m",
+    "{-k}": "\x1b[0;30m",
+    "{-x}": "\x1b[0m",
+    "{NK}": "\x1b[0m",
+    "{T}": "\x1b[1m",
+    "{t}": "\x1b[0m",
+}
+
+
+def _emit_color(polarity: str, color_char: str) -> str:
+    if color_char == "x":
+        return "\x1b[0m"
+    code = _PREVIEW_COLOR_MAP.get(color_char)
+    if code is None:
+        return ""
+    if polarity == "+":
+        return f"\x1b[0;1;{code}m"
+    return f"\x1b[0;{code}m"
+
+
+# Pre-build extended token lookups to eliminate per-match f-string creation.
+_EXT_F_LOOKUP = tuple(f"\x1b[38;5;{i}m" for i in range(256))
+_EXT_B_LOOKUP = tuple(f"\x1b[48;5;{i}m" for i in range(256))
+_EXT_P_LOOKUP = tuple(f"\x1b[{(90 + (i % 8)) if (i % 16) >= 8 else (30 + (i % 8))}m" for i in range(16))
+_EXT_T_LOOKUP = tuple(f"\x1b[{(100 + (i % 8)) if (i % 16) >= 8 else (40 + (i % 8))}m" for i in range(16))
+
+
+def _handle_extended_tokens(text: str) -> str:
+    """Convert {F###}/{B###}/{P#}/{T#} extended color tokens to ANSI escapes."""
+    parts: list[str] = []
+    last_end = 0
+    for m in _EXT_TOKEN_RE.finditer(text):
+        parts.append(text[last_end : m.start()])
+        kind = m.group(1)
+        val = int(m.group(2))
+        if kind == "F":
+            parts.append(_EXT_F_LOOKUP[val] if val < 256 else f"\x1b[38;5;{val}m")
+        elif kind == "B":
+            parts.append(_EXT_B_LOOKUP[val] if val < 256 else f"\x1b[48;5;{val}m")
+        elif kind == "P":
+            parts.append(_EXT_P_LOOKUP[val % 16])
+        elif kind == "T":  # pragma: no cover — truecolor reserved for future use
+            parts.append(_EXT_T_LOOKUP[val % 16])
+        last_end = m.end()
+    if last_end == 0:
+        return text  # no matches
+    parts.append(text[last_end:])
+    return "".join(parts)
+
+
+_TILDE_RE = re.compile(r"~(.)")
+
+
+# Pre-build tilde code → ANSI escape lookup to avoid per-match _emit_color calls.
+_TILDE_LOOKUP: dict[str, str] = {}
+for _tc, (_pol, _cc) in _TILDE_MAP.items():
+    _seq = _emit_color(_pol, _cc)
+    if _seq:  # pragma: no cover — _seq always truthy for all defined tilde codes
+        _TILDE_LOOKUP[_tc] = _seq
+
+
+def _handle_tilde_codes(text: str) -> str:
+    parts = _TILDE_RE.split(text)
+    if len(parts) == 1:
+        return text
+    for i in range(1, len(parts), 2):
+        parts[i] = _TILDE_LOOKUP.get(parts[i], f"~{parts[i]}")
+    return "".join(parts)
+
+
+_BRACE_3_RE = re.compile(r"(\{[+\-][a-zA-Z]\}|\{NK\}|\{T\}|\{t\})")
+_BRACE_4_RE = re.compile(r"(\{[+\-]Bw\})")
+
+
+def _handle_brace_tokens(text: str) -> str:
+    """Convert ``{+c}``/``{-x}`` brace tokens to ANSI escapes.
+
+    Includes the TWGS-specific ``{+Bw}`` header token in addition to the
+    single-character color tags.
+    """
+    # Handle 5-char tokens first (longest match first to avoid conflicts)
+    parts4 = _BRACE_4_RE.split(text)
+    if len(parts4) > 1:
+        for i in range(1, len(parts4), 2):
+            parts4[i] = _BRACE_TOKEN_MAP.get(parts4[i], parts4[i])
+        text = "".join(parts4)
+    # Then 3-char and other tokens
+    parts3 = _BRACE_3_RE.split(text)
+    if len(parts3) > 1:
+        for i in range(1, len(parts3), 2):
+            parts3[i] = _BRACE_TOKEN_MAP.get(parts3[i], parts3[i])
+        return "".join(parts3)
+    return text
+
+
+# ---------------------------------------------------------------------------
+# Pipe codes (|00-|23) — most common BBS color format
+# ---------------------------------------------------------------------------
+
+_PIPE_RE = re.compile(r"\|(\d{2})")
+
+# DOS color order → ANSI SGR codes
+_DOS_TO_ANSI_FG = [30, 34, 32, 36, 31, 35, 33, 37]  # |00-|07 (dim)
+_DOS_TO_ANSI_BG = [40, 44, 42, 46, 41, 45, 43, 47]  # |16-|23
+
+
+_PIPE_LOOKUP: dict[str, str] = {}
+for _i in range(24):
+    _key = f"{_i:02d}"
+    if _i <= 7:
+        _PIPE_LOOKUP[_key] = f"\x1b[{_DOS_TO_ANSI_FG[_i]}m"
+    elif _i <= 15:
+        _PIPE_LOOKUP[_key] = f"\x1b[{_DOS_TO_ANSI_FG[_i - 8] + 60}m"
+    else:
+        _PIPE_LOOKUP[_key] = f"\x1b[{_DOS_TO_ANSI_BG[_i - 16]}m"
+
+
+def _handle_pipe_codes(text: str) -> str:
+    # split() with a capturing group keeps the matched group in the result list,
+    # alternating: [text, match, text, match, ...]. We replace matches in-place
+    # via the lookup, avoiding re.sub's per-match string rebuild.
+    parts = _PIPE_RE.split(text)
+    if len(parts) == 1:
+        return text  # no matches — return original without allocation
+    for i in range(1, len(parts), 2):
+        parts[i] = _PIPE_LOOKUP.get(parts[i], f"|{parts[i]}")
+    return "".join(parts)