vir-tui 2.2.0__tar.gz

vir_tui-2.2.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - run: pip install . ruff pytest
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+      - run: pytest

vir_tui-2.2.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Run test suite
+        run: |
+          pip install pytest
+          PYTHONPATH=src pytest
+
+  build-and-publish:
+    name: Build distribution and publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/vir-tui
+    permissions:
+      id-token: write # Required for OIDC authentication with PyPI
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install build
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

vir_tui-2.2.0/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc

vir_tui-2.2.0/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

vir_tui-2.2.0/CLAUDE.md

@@ -0,0 +1,15 @@
+# vir-tui
+
+- **Domain**: Terminal UI rendering for VirInvictus CLI apps.
+- **Dependencies**: `stdlib` only. No dependencies are allowed in `pyproject.toml`.
+- **Formatting**: ANSI codes.
+
+Read `spec.md` before making changes.
+
+### Consumers
+Any breaking changes to `vir-tui` MUST be cascaded to the following applications that depend on it:
+1. `CalibreQuarry` (tracks `@main`)
+2. `Lattice` (tracks `@main`)
+3. `Bindery` (pins an exact commit by policy — bump the pin deliberately)
+
+- This is a generalized library. Do NOT hardcode domain menus. Pass them via `tui_select`.

vir_tui-2.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon LaRocque
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vir_tui-2.2.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.5
+Name: vir-tui
+Version: 2.2.0
+Summary: A lightweight, terminal UI primitive library for the VirInvictus CLI toolchain.
+Author: Brandon LaRocque
+License-File: LICENSE
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# vir-tui
+
+A lightweight, terminal UI primitive library for the VirInvictus CLI toolchain.
+
+Provides a raw TTY event loop, a grid-based menu renderer, robust cross-platform ANSI colors, input prompt lifecycles, and a fallback progress bar wrapper for CLI applications that run headless but offer an interactive terminal interface.
+
+Powers [CalibreQuarry](https://github.com/VirInvictus/CalibreQuarry) and [Lattice](https://github.com/VirInvictus/Lattice).
+
+`Python · stdlib`
+
+## Features
+
+- **Menus**: full-screen arrow-key `tui_select` (sections, aliases, letter keys) with an automatic numbered text fallback when curses is unavailable; a scrollable, pannable results pager (`tui_page`) with `/` search and `n`/`N` match jumping.
+- **Progress**: `progress_box()` — a session-screen-aware curses progress box with a tqdm-like API and a pipe-safe text fallback.
+- **Sessions**: `interactive_session()` context manager owning the curses screen lifecycle (open, degrade, close, KeyboardInterrupt cleanup).
+- **Formatters**: consistent `success`, `info`, `warn`, `error` styling across apps.
+- **Prompts**: `ask`, `ask_yn`, `confirm`, `prompt_int`, `prompt_float`, `prompt_out`, `prompt_path`, plus `out_note` for "where did my report go" footers.
+- **Capture**: `run_with_capture` wrapper for redirecting stdout/stderr into a temporary scrolling buffer while a background task runs, rendering a header/footer on top.
+
+## Support
+
+If vir-tui's useful to you and you'd like to chip in:
+
+- liberapay · [liberapay.com/bdkl](https://liberapay.com/bdkl/)
+- bitcoin
+  ```
+  bc1qkge6zr45tzqfwfmvma2ylumt6mg7wlwmhr05yv
+  ```
+
+## License
+
+GPL-3.0-or-later.

vir_tui-2.2.0/README.md

@@ -0,0 +1,32 @@
+# vir-tui
+
+A lightweight, terminal UI primitive library for the VirInvictus CLI toolchain.
+
+Provides a raw TTY event loop, a grid-based menu renderer, robust cross-platform ANSI colors, input prompt lifecycles, and a fallback progress bar wrapper for CLI applications that run headless but offer an interactive terminal interface.
+
+Powers [CalibreQuarry](https://github.com/VirInvictus/CalibreQuarry) and [Lattice](https://github.com/VirInvictus/Lattice).
+
+`Python · stdlib`
+
+## Features
+
+- **Menus**: full-screen arrow-key `tui_select` (sections, aliases, letter keys) with an automatic numbered text fallback when curses is unavailable; a scrollable, pannable results pager (`tui_page`) with `/` search and `n`/`N` match jumping.
+- **Progress**: `progress_box()` — a session-screen-aware curses progress box with a tqdm-like API and a pipe-safe text fallback.
+- **Sessions**: `interactive_session()` context manager owning the curses screen lifecycle (open, degrade, close, KeyboardInterrupt cleanup).
+- **Formatters**: consistent `success`, `info`, `warn`, `error` styling across apps.
+- **Prompts**: `ask`, `ask_yn`, `confirm`, `prompt_int`, `prompt_float`, `prompt_out`, `prompt_path`, plus `out_note` for "where did my report go" footers.
+- **Capture**: `run_with_capture` wrapper for redirecting stdout/stderr into a temporary scrolling buffer while a background task runs, rendering a header/footer on top.
+
+## Support
+
+If vir-tui's useful to you and you'd like to chip in:
+
+- liberapay · [liberapay.com/bdkl](https://liberapay.com/bdkl/)
+- bitcoin
+  ```
+  bc1qkge6zr45tzqfwfmvma2ylumt6mg7wlwmhr05yv
+  ```
+
+## License
+
+GPL-3.0-or-later.

vir_tui-2.2.0/VERSION

@@ -0,0 +1 @@
+2.2.0

vir_tui-2.2.0/logo.svg

@@ -0,0 +1,68 @@
+<svg width="100%" viewBox="0 0 680 320" xmlns="http://www.w3.org/2000/svg">
+<style>
+  :root {
+    --bg-opacity: 0.08;
+    --stroke: #8490a0;
+    --text-primary: #5a6270;
+    --text-secondary: #8490a0;
+    --rect-fill: #5a6270;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg-opacity: 0.15;
+      --stroke: #a0acbc;
+      --text-primary: #d0d7e0;
+      --text-secondary: #a0acbc;
+      --rect-fill: #d0d7e0;
+    }
+  }
+  .stroke-color { stroke: var(--stroke); }
+  .fill-color { fill: var(--stroke); fill-opacity: var(--bg-opacity); }
+  .text-p { fill: var(--text-primary); }
+  .text-s { fill: var(--text-secondary); }
+  .rect-f { fill: var(--rect-fill); }
+</style>
+
+<rect x="40" y="40" width="600" height="240" fill="none" class="stroke-color" stroke-width="0.5"/>
+
+<rect x="40" y="40" width="600" height="32" class="fill-color"/>
+<line x1="40" y1="72" x2="640" y2="72" class="stroke-color" stroke-width="0.5"/>
+
+<circle cx="60" cy="56" r="5" fill="none" class="stroke-color" stroke-width="0.5"/>
+<circle cx="78" cy="56" r="5" fill="none" class="stroke-color" stroke-width="0.5"/>
+<circle cx="96" cy="56" r="5" fill="none" class="stroke-color" stroke-width="0.5"/>
+
+<text x="340" y="59" text-anchor="middle" font-family="'SF Mono','Cascadia Code','JetBrains Mono','Fira Code',Consolas,'Liberation Mono',Menlo,monospace" font-size="11" class="text-s" font-weight="400">~/Calibre $ cquarry</text>
+
+<g opacity="0.06">
+  <rect x="80" y="100" width="18" height="24" class="rect-f" rx="1"/>
+  <rect x="102" y="96" width="18" height="28" class="rect-f" rx="1"/>
+  <rect x="124" y="102" width="18" height="22" class="rect-f" rx="1"/>
+  <rect x="146" y="94" width="18" height="30" class="rect-f" rx="1"/>
+  <rect x="168" y="98" width="18" height="26" class="rect-f" rx="1"/>
+  <rect x="190" y="104" width="18" height="20" class="rect-f" rx="1"/>
+  <rect x="212" y="92" width="18" height="32" class="rect-f" rx="1"/>
+  <rect x="234" y="100" width="18" height="24" class="rect-f" rx="1"/>
+
+  <rect x="444" y="98" width="18" height="26" class="rect-f" rx="1"/>
+  <rect x="466" y="92" width="18" height="32" class="rect-f" rx="1"/>
+  <rect x="488" y="102" width="18" height="22" class="rect-f" rx="1"/>
+  <rect x="510" y="96" width="18" height="28" class="rect-f" rx="1"/>
+  <rect x="532" y="104" width="18" height="20" class="rect-f" rx="1"/>
+  <rect x="554" y="94" width="18" height="30" class="rect-f" rx="1"/>
+  <rect x="576" y="100" width="18" height="24" class="rect-f" rx="1"/>
+  <rect x="598" y="96" width="18" height="28" class="rect-f" rx="1"/>
+</g>
+
+<text x="340" y="155" text-anchor="middle" font-family="'SF Mono','Cascadia Code','JetBrains Mono','Fira Code',Consolas,'Liberation Mono',Menlo,monospace" font-size="48" class="text-p" font-weight="500" letter-spacing="-2">CalibreQuarry</text>
+
+<line x1="140" y1="190" x2="540" y2="190" class="stroke-color" stroke-width="0.5"/>
+
+<text x="340" y="212" text-anchor="middle" font-family="'SF Mono','Cascadia Code','JetBrains Mono','Fira Code',Consolas,'Liberation Mono',Menlo,monospace" font-size="11" class="text-s" font-weight="400" letter-spacing="3">CATALOG · AUDIT · SERIES · EXPORT</text>
+
+<rect x="40" y="252" width="600" height="28" class="fill-color"/>
+<line x1="40" y1="252" x2="640" y2="252" class="stroke-color" stroke-width="0.5"/>
+
+<text x="56" y="270" font-family="'SF Mono','Cascadia Code','JetBrains Mono','Fira Code',Consolas,'Liberation Mono',Menlo,monospace" font-size="10" class="text-s" font-weight="400">--catalog  --all-wings  --stats  --audit  --recent  --series  --export  --wings</text>
+
+</svg>

vir_tui-2.2.0/patchnotes.md

@@ -0,0 +1,27 @@
+# 2.2.0 (2026-08-27)
+Phase 3 — consumer-driven primitives, from the cross-app TUI survey (CalibreQuarry, Lattice, Bindery).
+- **Feature**: `text_mode()` — public curses-status accessor (True when running without curses), so hosts stop poking the private `_USE_CURSES` global.
+- **Feature**: `progress_box()` / `ProgressBox` — first-class curses progress widget: session-screen-aware, throttled redraws, tqdm-like `update`/`set_description`/`close`, context-manager support, and a plain-text fallback (carriage-returned line on a tty; silent when piped) instead of starting a screen of its own. Replaces Lattice's hand-mirrored `_TUIPbar`. The `CP_*` color-pair constants are now public for hosts drawing their own widgets.
+- **Feature**: `interactive_session()` context manager owning the open-screen / degrade-to-text / close-screen boilerplate; KeyboardInterrupt is re-raised after cleanup so hosts keep mapping it to exit code 130. Adopts the duplicated `interactive_menu()` scaffolding from CalibreQuarry and Lattice.
+- **Feature**: Prompt primitives — `prompt_float(label, default, lo, hi)` with bounded re-asking, `prompt_path(label, default, must_exist)` with existence loops built in, `confirm(label, default, danger=True)` for destructive gates, and public `out_note(path)` (both consumers had copied the private `_out_note` verbatim).
+- **Feature**: Results-pager search — `/` opens a query prompt, `n`/`N` jump to the next/previous case-insensitive match with wrap-around; hints line updated. Matching logic is the pure `_match_lines()` helper (unit-tested).
+- **Tests**: Suite grew from 3 to 13 tests covering the new primitives (degrade path, KI re-raise, prompt validation loops, match wrap semantics, ProgressBox fallback safety).
+- **Consumers**: `Lattice` 4.17.0 (drops its mirrored progress box), `CalibreQuarry` 3.22.0 (adopts the session CM + prompt primitives), `Bindery` 0.19.1 (vir-tui pin bumped deliberately per its policy).
+
+# 2.1.0 (2026-08-25)
+- **Feature**: Added `session_screen()` accessor exposing the persistent curses screen, so host apps can route their own progress widgets into the session screen instead of starting their own.
+
+# 2.0.0 (2026-08-24)
+- **Breaking**: Gutted hardcoded Lattice/CalibreQuarry domains (`_MAIN_SECTIONS`, `_LIB_SECTIONS`). Consumers must now provide their own tuples to `tui_select`.
+- **Breaking**: Exported public API clean without underscores (e.g. `tui_select`, `ask`, `notify`, `reset_terminal`).
+- **Feature**: `tui_select` now automatically builds text-mode fallback menus dynamically using `aliases` and `letter_keys` kwargs.
+- **Fix**: Reverted `getch()` to `get_wch()` to fix a multibyte character search crash.
+- **Fix**: Enforced `visible_w = max(1, content_w - 4)` in `_tui_page` to prevent slicing crashes on narrow terminals.
+- **Maintenance**: Added `tests/` directory with `pytest` suite for core formatters.
+
+# Patch Notes
+
+## v1.0.0 (2026-08-23)
+
+- **Feature:** Initial extraction from `CalibreQuarry` and `Lattice`.
+- **Feature:** Standalone `GridMenu`, prompt wrappers, and ANSI formatters.

vir_tui-2.2.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vir-tui"
+version = "2.2.0"
+description = "A lightweight, terminal UI primitive library for the VirInvictus CLI toolchain."
+readme = "README.md"
+requires-python = ">=3.14"
+authors = [
+    { name = "Brandon LaRocque" }
+]
+dependencies = []
+
+[tool.ruff]
+lint.extend-ignore = ['F401', 'BLE001', 'S110', 'RUF059', 'I001']

vir_tui-2.2.0/refactor.py

@@ -0,0 +1,59 @@
+import os
+import re
+
+menu_path = '/home/bdkl/.gitrepos/vir-tui/src/vir_tui/menu.py'
+with open(menu_path, 'r') as f:
+    content = f.read()
+
+# 1. Unicode Fix
+content = content.replace("key = stdscr.getch()", "key = stdscr.get_wch()")
+# get_wch returns int for special keys and str for chars.
+# we need to handle that.
+content = content.replace("elif 32 <= key <= 126:", "elif isinstance(key, str) and key.isprintable():")
+
+# 2. Narrow Pager Crash Fix
+content = content.replace("visible_w = content_w - 4", "visible_w = max(1, content_w - 4)")
+
+# 3. Remove hardcoded sections
+start_idx = content.find("_MAIN_SECTIONS = [")
+end_idx = content.find("def _tui_page", start_idx)
+
+if start_idx != -1 and end_idx != -1:
+    # Insert new build_fallback and tui_select wrapper
+    new_code = """def build_fallback(sections, aliases=None, letter_keys=None):
+    aliases = aliases or {}
+    letter_keys = letter_keys or {}
+    mapping = dict(aliases)
+    display = []
+    n = 0
+    for si, (hdr, items) in enumerate(sections):
+        rows = []
+        for ii, label in enumerate(items):
+            clean = " ".join(label.split())
+            letter = letter_keys.get(clean)
+            if letter is not None:
+                key, target = letter
+                rows.append(f"{key}) {clean}")
+                mapping[key] = (si, ii) if target == "self" else target
+            else:
+                n += 1
+                rows.append(f"{n}) {clean}")
+                mapping[str(n)] = (si, ii)
+        display.append((hdr, rows))
+    return display, mapping, n
+
+def tui_select(title, sections, hints="\u2191\u2193 Navigate  \u23ce Select  q Quit", aliases=None, letter_keys=None):
+    if _USE_CURSES:
+        res = _tui_select(title, sections, hints=hints)
+        if res != "fallback":
+            return res
+    # Fallback
+    display, mapping, max_n = build_fallback(sections, aliases, letter_keys)
+    _box_menu(title, display)
+    return _fallback_input(f"  Select [1-{max_n}/q]: ", mapping)
+
+"""
+    content = content[:start_idx] + new_code + content[end_idx:]
+
+with open(menu_path, 'w') as f:
+    f.write(content)

vir_tui-2.2.0/roadmap.md

@@ -0,0 +1,36 @@
+# Roadmap
+
+- [x] Extract `GridMenu`, pagers, and prompts from existing CLI apps.
+- [x] Investigate Windows terminal support (`msvcrt`) for raw TTY.
+
+### Consumer Updates
+When a roadmap item is completed, ensure the following dependent applications are bumped or verified:
+- [x] `CalibreQuarry`
+- [x] `Lattice`
+- [x] `Bindery` (pins vir-tui to an exact commit by policy — bump the pin deliberately)
+
+## Phase 2: Core Generalization & Integration Fixes
+*Based on the post-extraction research report.*
+
+- [x] **Decouple Menus**: Remove hardcoded Lattice sections (`_MAIN_SECTIONS`, `_LIB_SECTIONS`) and aliases from `vir-tui`.
+- [x] **Dynamic Fallback**: Generalize `tui_select` to accept sections, aliases, and letter keys, and automatically build the text fallback menu if curses is unavailable, rather than relying on static Lattice maps.
+- [x] **Unicode Prompt Fix**: Revert `getch()` to `get_wch()` in `_tui_prompt_str` so multibyte characters work again (critical for CalibreQuarry search).
+- [x] **Narrow Pager Crash**: Enforce `visible_w = max(1, content_w - 4)` in `_tui_page` to prevent slicing errors on small windows.
+- [x] **API Standardization**: Clean up `__init__.py` to export public (non-underscored) methods, remove the shadowed `prompts.py` file or merge it cleanly, and ensure consumers aren't relying on private methods like `_Cancelled`.
+- [x] **Test Coverage**: Write `pytest` coverage for formatters, text fallback mapping logic, and pager geometry calculations in the currently empty `tests/` directory.
+
+### Consumer Integration (Post-Phase 2)
+- [x] **Lattice**: Remove the duplicate ~1,267-line `tui.py` in Lattice's codebase and properly delegate to `vir-tui`'s generalized `tui_select`.
+- [x] **CalibreQuarry**: Update imports to use the public `vir-tui` API and pass its aliases/keys into the new generalized `tui_select` to restore its text fallback mode.
+
+## Phase 3: Consumer-Driven Primitives
+*From the 2026-08 cross-app TUI survey (CalibreQuarry, Lattice, Bindery): what hosts still hand-roll, duplicate, or mirror.*
+
+- [x] **ProgressBox**: First-class curses progress widget (`progress_box()` / `ProgressBox`) — session-screen-aware, throttled redraws, tqdm-like `update`/`set_description`/`close`, context-manager support, plain-text fallback without a session. Lattice was mirroring `_TUI_BOX_W` and the `_CP_FRAME`/`_CP_HEADER` pair ids by hand and reimplementing the whole box in `lattice/utils.py`, which breaks silently whenever vir-tui restyles. The `CP_*` color-pair constants are now public for advanced hosts.
+- [x] **interactive_session()**: Context manager owning the open-screen / degrade-to-text / KeyboardInterrupt / close-screen boilerplate that CalibreQuarry and Lattice each duplicated in `interactive_menu()`.
+- [x] **Prompt primitives**: `prompt_float(label, default, lo, hi)` (CalibreQuarry hand-rolled its rating loop; Lattice loops tool/threshold choices), `prompt_path(label, default, must_exist)` (both apps hand-rolled path-existence loops), `confirm(label, default, danger)` (CalibreQuarry's double `ask_yn` destructive gates), and public `out_note(path)` (both consumers duplicated vir-tui's private `_out_note` verbatim).
+- [x] **Pager search**: `/` opens a query prompt and `n`/`N` jump to the next/previous match (case-insensitive, wrapping) in `tui_page` — long audit/catalog reports are the primary artifact of every host.
+- [ ] **Mouse support**: click-to-select in `tui_select`, scroll-wheel paging in `tui_page` (needs `getmask`/`BUTTON*` plumbing and fallback no-ops).
+- [ ] **Type-to-filter**: incremental narrowing in `tui_select` for menus with 15+ items (CalibreQuarry's main menu crossed that line in 3.21.0).
+- [ ] **Theme overrides**: let hosts remap color pairs or box glyphs per app instead of mirroring ids (only needed once a host actually wants a distinct look).
+

vir_tui-2.2.0/spec.md

@@ -0,0 +1,18 @@
+# vir-tui Specification
+
+1. **Domain**: Terminal UI rendering and input capturing for VirInvictus Python CLI applications.
+2. **Dependencies**: `stdlib` only. If `tqdm` is available in the consumer's environment, `vir_tui` re-exports it; otherwise, it exports a minimal stub.
+3. **Architecture**:
+   - `core.py`: ANSI state logic, color formats, `tqdm` handling (the real tqdm is re-exported when installed, a styled fallback otherwise).
+   - `menu.py`: everything interactive —
+     - the curses arrow-key menu (`tui_select`, sections/aliases/letter keys, auto-generated typed-input fallback via `build_fallback`),
+     - the scrollable, pannable results pager (`tui_page`) with `/` search and `n`/`N` match jumping (pure `_match_lines` helper),
+     - boxed prompts (`ask`, `ask_yn`, `confirm`, `prompt_int`, `prompt_float`, `prompt_out`, `prompt_path`) and the `out_note` report footer,
+     - the progress widget (`progress_box()` / `ProgressBox`) drawing into the session screen with a pipe-safe text fallback,
+     - the session lifecycle (`open_screen`/`close_screen`, `interactive_session`, `session_screen`, `text_mode`),
+     - `run_with_capture` for paging a mode's captured stdout/stderr.
+   - Public style constants (`CP_FRAME` … `CP_HINT`) let hosts render their own widgets into the session screen without mirroring private ids.
+
+4. **Guarantees**:
+   - Must fail gracefully and degrade if `sys.stdout` is not a TTY: every widget has a plain-text fallback (menus become numbered typed lists, the pager prints, progress stays silent when piped).
+   - Generic by contract: no host-domain menus or strings; hosts pass their own sections/aliases/letter keys to `tui_select`.

vir_tui-2.2.0/src/vir_tui/__init__.py

@@ -0,0 +1,45 @@
+from .core import (
+    info,
+    success,
+    warn,
+    error,
+    dry_run,
+    print_header,
+    print_summary,
+    color,
+    tqdm,
+)
+from .menu import (
+    CP_FRAME,
+    CP_HEADER,
+    CP_HINT,
+    CP_ITEM,
+    CP_SELECTED,
+    CP_TITLE,
+    ProgressBox,
+    confirm,
+    interactive_session,
+    out_note,
+    progress_box,
+    prompt_float,
+    prompt_path,
+    tui_select,
+    build_fallback,
+    reset_terminal,
+    open_screen,
+    close_screen,
+    session_screen,
+    text_mode,
+    ask,
+    ask_yn,
+    prompt_int,
+    prompt_out,
+    run_with_capture,
+    CancelledError,
+    notify,
+    tui_page,
+    box_menu,
+    fallback_input,
+    _Cancelled,  # for backwards compatibility
+    capture_output,
+)

vir_tui-2.2.0/src/vir_tui/core.py

@@ -0,0 +1,106 @@
+import os
+import sys
+
+try:
+    from tqdm import tqdm
+except ImportError:
+    # Minimal fallback if tqdm is missing
+    class tqdm:
+        def __init__(
+            self,
+            iterable=None,
+            desc=None,
+            disable=False,
+            total=None,
+            unit="it",
+            leave=True,
+            **kwargs,
+        ):
+            self.iterable = iterable
+            self.desc = desc
+            self.disable = disable
+            self.total = total
+            self.unit = unit
+            self.leave = leave
+            self.n = 0
+            if not self.disable and self.desc:
+                print(f"{self.desc}...", file=sys.stderr)
+
+        def __iter__(self):
+            if self.iterable is None:
+                return self
+            for item in self.iterable:
+                yield item
+                self.update(1)
+
+        def update(self, n=1):
+            self.n += n
+
+        def close(self):
+            if not self.disable and self.leave and self.total is not None:
+                print(f"Finished {self.n}/{self.total} {self.unit}", file=sys.stderr)
+
+        def set_description(self, desc):
+            self.desc = desc
+
+        def set_postfix(self, **kwargs):
+            pass
+
+        @staticmethod
+        def write(s, file=None, end="\n"):
+            print(s, file=file or sys.stdout, end=end)
+
+
+# ANSI Colors
+RED = "\033[31m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+CYAN = "\033[36m"
+MAGENTA = "\033[35m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+RESET = "\033[0m"
+
+
+def _use_color() -> bool:
+    return "NO_COLOR" not in os.environ and sys.stdout.isatty()
+
+
+def color(text: str, code: str) -> str:
+    return f"{code}{text}{RESET}" if _use_color() else text
+
+
+def info(msg: str) -> str:
+    return color(f"ℹ {msg}", CYAN)
+
+
+def success(msg: str) -> str:
+    return color(f"✓ {msg}", GREEN)
+
+
+def warn(msg: str) -> str:
+    return color(f"⚠ {msg}", YELLOW)
+
+
+def error(msg: str) -> str:
+    return color(f"✗ {msg}", RED)
+
+
+def dry_run(msg: str) -> str:
+    return f"{color('[DRY]', YELLOW)} {msg}"
+
+
+def print_header(title: str) -> None:
+    tqdm.write(color(f"\n{'=' * 60}", BOLD))
+    tqdm.write(color(f"{title}", BOLD + CYAN))
+    tqdm.write(color(f"{'=' * 60}", BOLD))
+
+
+def print_summary(stats: dict) -> None:
+    tqdm.write(color("\n--- SUMMARY ---", BOLD))
+    for k, v in stats.items():
+        if isinstance(v, int) and v > 0:
+            tqdm.write(f"  {k}: {color(str(v), GREEN)}")
+        else:
+            tqdm.write(f"  {k}: {v}")
+    tqdm.write(color("===============\n", BOLD))