console-window 2.0.0.4__tar.gz → 2.0.0.6__tar.gz

{console_window-2.0.0.4 → console_window-2.0.0.6}/CHANGELOG.md

@@ -122,6 +122,27 @@ This project follows [Semantic Versioning](https://semver.org/).
   No in-repo code used it.
 
 ### Fixed
+- Starting a window on a terminal with fewer than 256 colours (including tmux's
+  stock `TERM=screen`, whose terminfo entry has 8 colours) no longer crashes with
+  `ValueError: Color number is greater than COLORS-1`. Theme installation now
+  asks the backend for its capabilities through the new
+  `RenderBackend.colors()` / `color_pairs()` seam (captured after
+  `start_color()`), so `theme.py` and `window.py` never read the `curses`
+  globals directly. On 256-colour terminals the theme's literal specs are used
+  unchanged; on 16/88/8-colour terminals each index is mapped to the nearest
+  entry of the standard xterm palette (base colours 0..15, the 6x6x6 cube and
+  the grayscale ramp are modelled), with a contrast guard that moves the
+  foreground if mapping would collapse a pair to `fg == bg`. Below 8 colours, or
+  when colours are unavailable, installation falls back to attributes instead
+  of raising. `use_default_colors()` is now guarded by `except curses.error` and
+  its result is remembered, so `-1` becomes a concrete default (fg 7, bg 0) on
+  terminals that reject it; pair ids at or past `COLOR_PAIRS` are skipped.
+  Startup, `ConsoleWindow.set_theme()` and `Theme.set()` all install through the
+  new `Theme.install()`, and `Theme.set()` no longer calls `curses.init_pair()`
+  directly, so the built-in theme picker gets the same degradation.
+  `HeadlessBackend(colors=...)` now accepts a colour count (plus optional
+  `color_pairs=` and `default_colors=`) so the low-colour paths are covered by
+  `tests/test_low_colour.py`.
 - `draw()` now routes rows at or past the `max_rows` content ceiling through the
   same `rows_dropped` counter and once-per-fill warning as `add_body()` /
   `add_header()`, with the warning attributed to the caller's line. Previously
@@ -240,6 +261,9 @@ This project follows [Semantic Versioning](https://semver.org/).
   and that both init paths agree (AUDIT.md §3.9).
 
 ### Removed
+- `SampleApp.do_key()`, a dead method with no caller: `main_loop` dispatches
+  through `handle_key()`, which already forwards spinner keys to
+  `spin.do_key()`. No behaviour changed (AUDIT.md §3.1).
 - `console_window/_selftest.py`, the TTY-only dev self-test. The old
   `python -m console_window._selftest` entry point is gone; the features it
   demonstrated — multi-row picking, a prompt-style option, forced

{console_window-2.0.0.4 → console_window-2.0.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: console-window
-Version: 2.0.0.4
+Version: 2.0.0.6
 Summary: A robust curses wrapper for creating Text User Interfaces (TUIs).
 Author-email: Joe Defen <joedef@duck.com>
 Requires-Python: >=3.10
@@ -71,6 +71,7 @@ The wrapper handles several advanced terminal interaction patterns automatically
   * **Viewport-Sized Pads:** Separate `head` and `body` pads give the static header band and the independently scrolling body, but the pads are blit buffers sized to the terminal rather than content stores. `add_body()`/`add_header()`/`draw()` write the model, and `render()` paints the visible page into pad row 0, so pad memory and per-frame `clear()` cost stay constant no matter how many rows an app adds. Row counts need no configuration at all: `opts.body_rows` / `opts.head_rows` are advisory hints only, and `opts.max_rows` (default `32767`, `None` for unlimited) is the single content ceiling.
   * **Loud Content Limits:** A row added past `opts.max_rows` is discarded, but no longer quietly: the first discarded row of each fill episode emits a `UserWarning` naming the namespace and the option to change, and every discarded row is counted in `ConsoleWindow.rows_dropped`. It stays non-fatal — run `python -W error::UserWarning` if you would rather it killed the app.
   * **Seamless Resizing:** Automatically detects terminal size changes (`KEY_RESIZE`) and recalculates layout dimensions, with robust error handling to prevent common `curses.error` crashes during resizing.
+  * **Graceful Colour Degradation:** Themes are written against the 256-colour xterm palette, but installation asks the backend how many colours the terminal actually exposes. A 256-colour terminal gets the theme's literal specs; 16-, 88- and 8-colour terminals get the nearest available palette entry, with a contrast guard so a pair never collapses to `fg == bg`; below 8 colours (or with no colour support) the theme falls back to attributes. `-1` is only emitted when `use_default_colors()` succeeds, and `COLOR_PAIRS` is respected. Stock tmux (`TERM=screen`, 8 colours) therefore works instead of raising `ValueError: Color number is greater than COLORS-1`.
   * **Scroll & Pick Synchronization:** The `Window` class manages **scroll position** and a separate **pick position** (highlighted row) simultaneously.
     * When using pick mode, scrolling automatically tracks the highlighted element to keep it visible in `.pick_pos`.
     * To use that value, you must separately be able to associate `.pick_pos` to its value by, say, keeping an array of values for every added line to the `body`. 
@@ -110,7 +111,10 @@ demonstrates:
   per-window state: `ConsoleWindowOpts(theme=...)` seeds `window.theme`,
   `window.set_theme()` switches it (and re-initialises the terminal's colour
   pairs, which curses keeps per terminal rather than per window), and
-  `Theme.set()` remains the process-wide switch.
+  `Theme.set()` remains the process-wide switch. Theme names are semantic:
+  asking for `nord` on an 8-colour terminal installs the closest supported
+  representation rather than raising, and startup, `set_theme()` and
+  `Theme.set()` all share `Theme.install()`.
 * **Dialogs** — `a` calls `answer()` for text input, `l` calls `alert()`, and `n`
   drives `answer()` from an `OptionSpinner` option (`add_key(..., prompt=...)`).
   `answer()` returns `None` only when the user aborts; if the terminal cannot
@@ -215,8 +219,7 @@ Deprecated APIs remain supported **indefinitely**. A deprecation is a request to
 migrate, not a scheduled removal: deprecated functions and parameters keep
 working, and one is removed only when there is significant value in doing so
 (for example, the API is actively harmful or blocks a necessary redesign).
-Deprecated paths emit a `DeprecationWarning` where practical, and every removal
-is recorded in [`CHANGELOG.md`](CHANGELOG.md:1).
+Deprecated paths emit a `DeprecationWarning` where practical.
 
 ## License
 MIT

{console_window-2.0.0.4 → console_window-2.0.0.6}/README.md

@@ -52,6 +52,7 @@ The wrapper handles several advanced terminal interaction patterns automatically
   * **Viewport-Sized Pads:** Separate `head` and `body` pads give the static header band and the independently scrolling body, but the pads are blit buffers sized to the terminal rather than content stores. `add_body()`/`add_header()`/`draw()` write the model, and `render()` paints the visible page into pad row 0, so pad memory and per-frame `clear()` cost stay constant no matter how many rows an app adds. Row counts need no configuration at all: `opts.body_rows` / `opts.head_rows` are advisory hints only, and `opts.max_rows` (default `32767`, `None` for unlimited) is the single content ceiling.
   * **Loud Content Limits:** A row added past `opts.max_rows` is discarded, but no longer quietly: the first discarded row of each fill episode emits a `UserWarning` naming the namespace and the option to change, and every discarded row is counted in `ConsoleWindow.rows_dropped`. It stays non-fatal — run `python -W error::UserWarning` if you would rather it killed the app.
   * **Seamless Resizing:** Automatically detects terminal size changes (`KEY_RESIZE`) and recalculates layout dimensions, with robust error handling to prevent common `curses.error` crashes during resizing.
+  * **Graceful Colour Degradation:** Themes are written against the 256-colour xterm palette, but installation asks the backend how many colours the terminal actually exposes. A 256-colour terminal gets the theme's literal specs; 16-, 88- and 8-colour terminals get the nearest available palette entry, with a contrast guard so a pair never collapses to `fg == bg`; below 8 colours (or with no colour support) the theme falls back to attributes. `-1` is only emitted when `use_default_colors()` succeeds, and `COLOR_PAIRS` is respected. Stock tmux (`TERM=screen`, 8 colours) therefore works instead of raising `ValueError: Color number is greater than COLORS-1`.
   * **Scroll & Pick Synchronization:** The `Window` class manages **scroll position** and a separate **pick position** (highlighted row) simultaneously.
     * When using pick mode, scrolling automatically tracks the highlighted element to keep it visible in `.pick_pos`.
     * To use that value, you must separately be able to associate `.pick_pos` to its value by, say, keeping an array of values for every added line to the `body`. 
@@ -91,7 +92,10 @@ demonstrates:
   per-window state: `ConsoleWindowOpts(theme=...)` seeds `window.theme`,
   `window.set_theme()` switches it (and re-initialises the terminal's colour
   pairs, which curses keeps per terminal rather than per window), and
-  `Theme.set()` remains the process-wide switch.
+  `Theme.set()` remains the process-wide switch. Theme names are semantic:
+  asking for `nord` on an 8-colour terminal installs the closest supported
+  representation rather than raising, and startup, `set_theme()` and
+  `Theme.set()` all share `Theme.install()`.
 * **Dialogs** — `a` calls `answer()` for text input, `l` calls `alert()`, and `n`
   drives `answer()` from an `OptionSpinner` option (`add_key(..., prompt=...)`).
   `answer()` returns `None` only when the user aborts; if the terminal cannot
@@ -196,8 +200,7 @@ Deprecated APIs remain supported **indefinitely**. A deprecation is a request to
 migrate, not a scheduled removal: deprecated functions and parameters keep
 working, and one is removed only when there is significant value in doing so
 (for example, the API is actively harmful or blocks a necessary redesign).
-Deprecated paths emit a `DeprecationWarning` where practical, and every removal
-is recorded in [`CHANGELOG.md`](CHANGELOG.md:1).
+Deprecated paths emit a `DeprecationWarning` where practical.
 
 ## License
 MIT

{console_window-2.0.0.4 → console_window-2.0.0.6}/console_window/__init__.py

@@ -1,6 +1,6 @@
 # Single source of truth for the package version: pyproject.toml declares
 # ``dynamic = ["version"]``, so flit reads this value instead of duplicating it.
-__version__ = "2.0.0.4"
+__version__ = "2.0.0.6"
 
 from .context import Context
 from .header import HeaderLine, Span

{console_window-2.0.0.4 → console_window-2.0.0.6}/console_window/backend.py

@@ -91,11 +91,17 @@ class RenderBackend(Protocol):
     def has_colors(self) -> bool:
         ...
 
+    def colors(self) -> int:
+        """Number of colours the terminal supports (0 when unknown/none)."""
+
+    def color_pairs(self) -> int:
+        """Size of the terminal's colour-pair table."""
+
     def start_color(self) -> None:
         ...
 
-    def use_default_colors(self) -> None:
-        ...
+    def use_default_colors(self) -> bool:
+        """Enable ``-1`` as "terminal default"; return whether it worked."""
 
     def init_pair(self, pair: int, fg: int, bg: int) -> None:
         ...
@@ -108,6 +114,19 @@ class RenderBackend(Protocol):
 
 
 class CursesBackend:
+    # Curses exposes COLORS/COLOR_PAIRS only after start_color(), so the values
+    # are captured there.  Before that, colours()/color_pairs() fall back to the
+    # module globals (valid once initscr() has run) and finally to a conservative
+    # default so a caller never sees a bogus zero-capability terminal merely
+    # because it constructed a second backend for an already-running curses
+    # session.
+    _FALLBACK_COLOR_PAIRS = 64  # the ncurses floor for a colour terminal
+
+    def __init__(self) -> None:
+        self._colors = 0
+        self._color_pairs = 0
+        self._default_colors = False
+
     def start(self, timeout_ms: int) -> Surface:
         scr = curses.initscr()
         curses.set_escdelay(25)  # Reduce ESC key delay from 1000ms to 25ms
@@ -140,11 +159,55 @@ class CursesBackend:
         except curses.error:  # curses not initialised yet
             return False
 
+    def colors(self) -> int:
+        if self._colors > 0:
+            return self._colors
+        try:
+            return max(int(getattr(curses, 'COLORS', 0)), 0)
+        except (AttributeError, curses.error, TypeError, ValueError):
+            return 0
+
+    def color_pairs(self) -> int:
+        if self._color_pairs > 0:
+            return self._color_pairs
+        try:
+            pairs = max(int(getattr(curses, 'COLOR_PAIRS', 0)), 0)
+        except (AttributeError, curses.error, TypeError, ValueError):
+            pairs = 0
+        if pairs > 0:
+            return pairs
+        # A colour-capable terminal always has at least the ncurses minimum;
+        # reporting 0 here would make a theme install silently do nothing.
+        return self._FALLBACK_COLOR_PAIRS if self.colors() > 0 else 0
+
     def start_color(self) -> None:
-        curses.start_color()
+        try:
+            curses.start_color()
+        except curses.error:
+            # No colour support after all: degrade to monochrome instead of
+            # letting the caller crash during startup.
+            self._colors = 0
+            self._color_pairs = 0
+            return
+        try:
+            self._colors = max(int(getattr(curses, 'COLORS', 0)), 0)
+        except (AttributeError, curses.error, TypeError, ValueError):
+            self._colors = 0
+        try:
+            self._color_pairs = max(int(getattr(curses, 'COLOR_PAIRS', 0)), 0)
+        except (AttributeError, curses.error, TypeError, ValueError):
+            self._color_pairs = 0
 
-    def use_default_colors(self) -> None:
-        curses.use_default_colors()
+    def use_default_colors(self) -> bool:
+        try:
+            curses.use_default_colors()
+        except curses.error:
+            # Some terminals reject -1; the theme resolver then substitutes
+            # concrete defaults rather than passing -1 to init_pair().
+            self._default_colors = False
+        else:
+            self._default_colors = True
+        return self._default_colors
 
     def init_pair(self, pair: int, fg: int, bg: int) -> None:
         curses.init_pair(pair, fg, bg)
@@ -216,13 +279,27 @@ class _NoopSurface:
 
 
 class HeadlessBackend:
-    def __init__(self, rows: int = 24, cols: int = 80, colors: bool = False) -> None:
+    def __init__(self, rows: int = 24, cols: int = 80,
+                 colors: bool | int = False,
+                 color_pairs: int | None = None,
+                 default_colors: bool = True) -> None:
         self.rows = rows
         self.cols = cols
         self.screen = _NoopSurface(rows, cols)
         self.pads: list[_NoopSurface] = []
         self.stopped = False
-        self._colors = colors
+        # ``colors`` used to be a bare bool.  It still accepts one (True means a
+        # 256-colour terminal, False means none) but now also accepts the exact
+        # count, so the low-colour degradation paths are unit-testable without a
+        # real terminal.
+        if isinstance(colors, bool):
+            self._colors = 256 if colors else 0
+        else:
+            self._colors = max(int(colors), 0)
+        if color_pairs is None:
+            color_pairs = 64 if 0 < self._colors <= 16 else 256
+        self._color_pairs = max(int(color_pairs), 0)
+        self._default_colors = bool(default_colors)
         # Process-global curses calls the window used to make directly are
         # recorded here instead, so the dialog/render paths are backend-driven
         # and observable headlessly.
@@ -264,13 +341,20 @@ class HeadlessBackend:
         self.screen.queue_keys(*keys)
 
     def has_colors(self) -> bool:
+        return self._colors > 0
+
+    def colors(self) -> int:
         return self._colors
 
+    def color_pairs(self) -> int:
+        return self._color_pairs
+
     def start_color(self) -> None:
         self.start_color_calls += 1
 
-    def use_default_colors(self) -> None:
+    def use_default_colors(self) -> bool:
         self.use_default_colors_calls += 1
+        return self._default_colors
 
     def init_pair(self, pair: int, fg: int, bg: int) -> None:
         self.init_pair_calls.append((pair, fg, bg))

{console_window-2.0.0.4 → console_window-2.0.0.6}/console_window/theme.py

@@ -3,6 +3,138 @@ from __future__ import annotations
 import curses
 from typing import ClassVar
 
+from .backend import CursesBackend, RenderBackend
+
+# --- palette model -----------------------------------------------------------
+# Standard xterm palette model.  0..15 are the ANSI/base colours, 16..231 the
+# 6x6x6 colour cube with the levels below, and 232..255 the grayscale ramp
+# ``8 + 10 * n``.  The RGB values are the conventional xterm ones; exact
+# fidelity is not required because the result only picks the closest entry a
+# low-colour terminal can actually display.
+_ANSI_RGB: tuple[tuple[int, int, int], ...] = (
+    (0, 0, 0),        # 0 black
+    (128, 0, 0),      # 1 red
+    (0, 128, 0),      # 2 green
+    (128, 128, 0),    # 3 yellow
+    (0, 0, 128),      # 4 blue
+    (128, 0, 128),    # 5 magenta
+    (0, 128, 128),    # 6 cyan
+    (192, 192, 192),  # 7 white
+    (128, 128, 128),  # 8 bright black
+    (255, 0, 0),      # 9 bright red
+    (0, 255, 0),      # 10 bright green
+    (255, 255, 0),    # 11 bright yellow
+    (0, 0, 255),      # 12 bright blue
+    (255, 0, 255),    # 13 bright magenta
+    (0, 255, 255),    # 14 bright cyan
+    (255, 255, 255),  # 15 bright white
+)
+_CUBE_LEVELS: tuple[int, ...] = (0, 95, 135, 175, 215, 255)
+
+
+def palette_rgb(index: int) -> tuple[int, int, int]:
+    """Return the conventional xterm RGB value for palette *index*.
+
+    Unknown/negative indices (``-1`` is "terminal default", resolved before
+    this function is called) fall back to black so callers never raise.
+    """
+    if 0 <= index < 16:
+        return _ANSI_RGB[index]
+    if 16 <= index <= 231:
+        offset = index - 16
+        return (
+            _CUBE_LEVELS[offset // 36],
+            _CUBE_LEVELS[(offset // 6) % 6],
+            _CUBE_LEVELS[offset % 6],
+        )
+    if 232 <= index <= 255:
+        level = 8 + 10 * (index - 232)
+        return (level, level, level)
+    return (0, 0, 0)
+
+
+def _rgb_distance(left: tuple[int, int, int],
+                  right: tuple[int, int, int]) -> int:
+    return sum((a - b) ** 2 for a, b in zip(left, right, strict=False))
+
+
+def nearest_palette_index(index: int, colors: int) -> int:
+    """Map 256-colour *index* to the nearest entry a *colors*-terminal has.
+
+    Entries 0..15 are the base palette, so the search is restricted to
+    ``0 .. min(colors, 16) - 1``.  A 256-colour terminal gets *index* back
+    unchanged (exact theme specs, no visual regression).  Returns ``-1`` when
+    the terminal has no usable colours at all.
+    """
+    if colors >= 256:
+        return index
+    limit = max(0, min(int(colors), 16))
+    if limit <= 0:
+        return -1
+    if 0 <= index < limit:
+        return index
+    target = palette_rgb(index)
+    best = 0
+    best_distance = _rgb_distance(target, palette_rgb(0))
+    for candidate in range(1, limit):
+        distance = _rgb_distance(target, palette_rgb(candidate))
+        if distance < best_distance:
+            best = candidate
+            best_distance = distance
+    return best
+
+
+def _contrast_partner(color: int, colors: int) -> int | None:
+    """Return the palette entry furthest from *color*, or None if impossible."""
+    limit = max(0, min(int(colors), 16))
+    if limit <= 1:
+        return None
+    base = palette_rgb(color)
+    best: int | None = None
+    best_distance = -1
+    for candidate in range(limit):
+        if candidate == color:
+            continue
+        distance = _rgb_distance(base, palette_rgb(candidate))
+        if distance > best_distance:
+            best = candidate
+            best_distance = distance
+    return best
+
+
+def resolve_color_pair(fg: int, bg: int, colors: int,
+                       default_colors: bool) -> tuple[int, int] | None:
+    """Resolve a theme's ``(fg, bg)`` to values *colors* can accept.
+
+    ``-1`` is passed through only when :meth:`RenderBackend.use_default_colors`
+    succeeded; otherwise it is replaced with concrete defaults (fg 7, bg 0).
+    On terminals with fewer than 256 colours each index is mapped to the
+    nearest available palette entry.  If the mapping would collapse the pair to
+    ``fg == bg`` the foreground is moved to the most contrasting entry.  Returns
+    ``None`` when no legible pair exists (e.g. a 1-colour terminal), in which
+    case the caller falls back to attributes and installs nothing.
+    """
+    if colors <= 0:
+        return None
+    if fg == -1 and not default_colors:
+        fg = 7
+    if bg == -1 and not default_colors:
+        bg = 0
+    if colors < 256:
+        if fg != -1:
+            fg = nearest_palette_index(fg, colors)
+        if bg != -1:
+            bg = nearest_palette_index(bg, colors)
+    # A pair of terminal defaults is left alone: the terminal guarantees a
+    # legible default combination, and preserving (-1, -1) keeps the 256-colour
+    # path byte-for-byte identical to the theme spec.
+    if fg != -1 and bg != -1 and fg == bg:
+        partner = _contrast_partner(bg, colors)
+        if partner is None:
+            return None
+        fg = partner
+    return fg, bg
+
 
 class Theme:
     # Semantic color-pair IDs.  The pairs themselves are (re)initialized per theme
@@ -159,8 +291,8 @@ class Theme:
         ``DEFAULT_BG`` comes first (the screen and pad background), then the
         semantic roles in ``SEMANTIC_PAIRS`` order.  Startup
         (``ConsoleWindow._init_screen``), :meth:`set` and
-        ``ConsoleWindow.set_theme`` all install colours from this one list, so
-        the paths cannot drift apart.
+        ``ConsoleWindow.set_theme`` all install colours through :meth:`install`
+        from this one list, so the paths cannot drift apart.
         """
         theme = cls.THEMES[cls.resolve(theme_name)]
         specs: list[tuple[int, int, int]] = []
@@ -176,23 +308,59 @@ class Theme:
     def list_all(cls) -> list[str]:
         return list(cls.THEMES.keys())
 
+    @classmethod
+    def install(cls, backend: RenderBackend,
+                theme_name: str | None = None) -> str:
+        """Install *theme_name*'s colours through *backend*, degrading safely.
+
+        This is the single installation path used by startup
+        (``ConsoleWindow._init_screen``), ``ConsoleWindow.set_theme()`` and
+        :meth:`set`.  It consults the backend's colour capability instead of the
+        ``curses`` globals: on a 256-colour terminal the theme's literal specs
+        are used unchanged, while fewer colours are mapped to the nearest
+        available palette entry and ``-1`` is only emitted when the terminal
+        accepted ``use_default_colors()``.  Pair ids beyond ``COLOR_PAIRS`` and
+        pairs with no legible mapping are skipped rather than raising.  Returns
+        the resolved theme name.
+        """
+        name = cls.resolve(theme_name if theme_name is not None
+                           else cls.get_current())
+        colors = int(backend.colors())
+        max_pairs = int(backend.color_pairs())
+        default_colors = bool(backend.use_default_colors()) if colors > 0 else False
+        for pair_id, fg, bg in cls.pair_specs(name):
+            if pair_id >= max_pairs:
+                continue
+            pair = resolve_color_pair(fg, bg, colors, default_colors)
+            if pair is None:
+                continue
+            backend.init_pair(pair_id, pair[0], pair[1])
+        return name
+
     @classmethod
     def set(cls, theme_name: str) -> bool:
         if theme_name not in cls.THEMES:
             return False
 
-        if not curses.has_colors():
-            return False
-
-        cls._current = theme_name
-        theme = cls.THEMES[theme_name]
-
         # Late import to avoid a circular import at module load time.
         from .window import ConsoleWindow
 
-        # Reinitialize every pair this theme defines (DEFAULT_BG first).
-        for pair_id, fg, bg in cls.pair_specs(theme_name):
-            curses.init_pair(pair_id, fg, bg)
+        # Colour pairs are terminal-global, so a live window's backend is the
+        # authoritative seam.  Without one, fall back to curses itself, but go
+        # through CursesBackend so this method never calls curses.init_pair()
+        # directly (that path used to bypass every low-colour guard).
+        win = ConsoleWindow.primary_window()
+        backend = getattr(win, '_backend', None) if win is not None else None
+        if backend is None:
+            backend = CursesBackend()
+            backend.start_color()
+        if not backend.has_colors():
+            return False
+
+        cls._current = theme_name
+        name = cls.install(backend, theme_name)
+        cls._current = name
+        theme = cls.THEMES[name]
 
         # Set the screen/pad background too, even when it is (-1, -1) — i.e.
         # "back to the terminal default" — and broadcast it to *every* live
@@ -200,14 +368,15 @@ class Theme:
         # Theme.set() is the process-wide entry point, so it owns this internal
         # step; exposing a public hook would only invite apps to bypass the
         # pair-table installation above.
-        if 'default_fg' in theme and 'default_bg' in theme:
+        if ('default_fg' in theme and 'default_bg' in theme
+                and cls.DEFAULT_BG < backend.color_pairs()):
             ConsoleWindow._apply_default_colors(  # pylint: disable=protected-access
-                curses.color_pair(cls.DEFAULT_BG))
+                backend.color_pair(cls.DEFAULT_BG))
 
         # A process-wide switch leaves every window reporting the same theme,
         # so per-window state cannot contradict the pair table just installed.
         for win in ConsoleWindow.active_windows():
-            win.theme = theme_name
+            win.theme = name
 
         return True
 

{console_window-2.0.0.4 → console_window-2.0.0.6}/console_window/window.py

@@ -439,9 +439,11 @@ class ConsoleWindow:
         if not self._backend.has_colors():
             return
         theme = Theme.THEMES[Theme.resolve(getattr(self, 'theme', None))]
-        default_fg = theme.get('default_fg', -1)
-        default_bg = theme.get('default_bg', -1)
-        if default_fg != -1 or default_bg != -1:
+        if ('default_fg' in theme and 'default_bg' in theme
+                and Theme.DEFAULT_BG < self._backend.color_pairs()):
+            # Theme.install() has already installed this pair with either the
+            # literal values or the low-colour mapping, so bkgd() never sees a
+            # stale/out-of-range pair.
             pad.bkgd(' ', self._backend.color_pair(Theme.DEFAULT_BG))
 
     def _sync_pad_geometry(self) -> None:
@@ -578,14 +580,18 @@ class ConsoleWindow:
 
         Colour pairs are per-terminal (one table, not one per window), so both
         startup and ``set_theme()`` call this; the caller decides *whose*
-        theme wins.  Returns the resolved theme name.
+        theme wins.  The actual installation (including low-colour mapping and
+        ``-1`` resolution) lives in :meth:`Theme.install`, which ``Theme.set()``
+        uses too, so the two entry points cannot diverge.  Returns the resolved
+        theme name.
         """
-        name = Theme.resolve(theme_name or Theme.get_current())
+        name = Theme.install(backend, theme_name)
         theme = Theme.THEMES[name]
-        for pair_id, fg, bg in Theme.pair_specs(name):
-            backend.init_pair(pair_id, fg, bg)
-        # Can't change pair 0, so the screen background is set directly.
-        if theme.get('default_fg', -1) != -1 or theme.get('default_bg', -1) != -1:
+        # Can't change pair 0, so the screen background is set directly.  The
+        # pair has just been installed above (with mapped values on low-colour
+        # terminals), so this never references a stale or out-of-range pair.
+        if ('default_fg' in theme and 'default_bg' in theme
+                and Theme.DEFAULT_BG < backend.color_pairs()):
             scr.bkgd(' ', backend.color_pair(Theme.DEFAULT_BG))
         return name
 
@@ -599,8 +605,10 @@ class ConsoleWindow:
         # Initialize color support with theme.  Every colour call goes through
         # the backend, so a non-curses backend that reports colours can use it.
         if backend.has_colors():
+            # start_color() is where a curses backend captures COLORS and
+            # COLOR_PAIRS; Theme.install() then enables default colours (and
+            # remembers whether -1 is usable) before resolving each pair.
             backend.start_color()
-            backend.use_default_colors()  # Allow -1 for default terminal colors
             # The window's own theme (per-window since AUDIT.md §3.1) or the
             # process default for a window that has not chosen one yet.
             name = ConsoleWindow._install_theme(backend, scr, theme_name)

console_window-2.0.0.6/tests/test_low_colour.py

@@ -0,0 +1,221 @@
+"""Theme installation on terminals with fewer than 256 colours.
+
+The 256-colour themes used to be handed to ``curses.init_pair()`` verbatim, so
+an 8-colour terminal (including tmux's stock ``TERM=screen``) raised
+``ValueError: Color number is greater than COLORS-1``.  These tests pin the
+degradation contract: install the requested theme, resolve every colour to what
+the terminal supports, and never raise.
+"""
+
+import curses
+
+import pytest
+
+import console_window.backend as backend_mod
+from console_window.backend import CursesBackend, HeadlessBackend
+from console_window.opts import ConsoleWindowOpts
+from console_window.theme import (
+    Theme,
+    nearest_palette_index,
+    palette_rgb,
+    resolve_color_pair,
+)
+from console_window.window import ConsoleWindow
+
+
+def _window(theme_name, backend):
+    opts = ConsoleWindowOpts(theme=theme_name, body_rows=10, head_rows=3)
+    return ConsoleWindow(opts=opts, backend=backend, singleton=False)
+
+
+def _assert_within_capability(backend, colors):
+    assert backend.init_pair_calls, 'the theme installed no colour pairs'
+    for pair_id, fg, bg in backend.init_pair_calls:
+        assert pair_id < backend.color_pairs()
+        assert -1 <= fg < colors
+        assert -1 <= bg < colors
+        # A pair of terminal defaults (-1, -1) is the one legitimate exception:
+        # the terminal picks a legible foreground/background itself.
+        assert fg != bg or (fg == -1 and bg == -1), (pair_id, fg, bg)
+
+
+# --- every bundled theme on every supported colour depth --------------------
+
+@pytest.mark.parametrize('colors', [8, 16, 88, 256])
+@pytest.mark.parametrize('theme_name', Theme.list_all())
+def test_every_theme_installs_within_the_terminals_capability(theme_name, colors,
+                                                              monkeypatch):
+    monkeypatch.setattr(Theme, '_current', theme_name)
+    backend = HeadlessBackend(colors=colors)
+    win = _window(theme_name, backend)
+    try:
+        _assert_within_capability(backend, colors)
+        assert Theme.DEFAULT_BG in {pair for pair, _fg, _bg in backend.init_pair_calls}
+    finally:
+        win.stop_curses()
+
+
+@pytest.mark.parametrize('colors', [1, 2, 4, 7])
+def test_below_eight_colours_degrades_to_attributes_without_raising(colors,
+                                                                    monkeypatch):
+    # There is no legible colour mapping for a 1-colour terminal, so nothing is
+    # installed and drawing falls back to A_BOLD/A_REVERSE instead of raising.
+    monkeypatch.setattr(Theme, '_current', 'nord')
+    backend = HeadlessBackend(colors=colors)
+    win = _window('nord', backend)
+    try:
+        for pair_id, fg, bg in backend.init_pair_calls:
+            assert pair_id < backend.color_pairs()
+            if colors > 1:
+                assert 0 <= fg < colors and 0 <= bg < colors
+                assert fg != bg
+        if colors == 1:
+            assert backend.init_pair_calls == []
+    finally:
+        win.stop_curses()
+
+
+# --- the picker path (Theme.set) -------------------------------------------
+
+def test_theme_set_on_an_eight_colour_window_does_not_raise(monkeypatch):
+    monkeypatch.setattr(Theme, '_current', None)
+    backend = HeadlessBackend(colors=8)
+    win = _window('dark-mono', backend)
+    try:
+        backend.init_pair_calls.clear()
+        assert Theme.set('nord') is True
+        assert win.theme == 'nord'
+        _assert_within_capability(backend, 8)
+    finally:
+        win.stop_curses()
+
+
+def test_window_set_theme_on_an_eight_colour_window_does_not_raise(monkeypatch):
+    monkeypatch.setattr(Theme, '_current', None)
+    backend = HeadlessBackend(colors=8)
+    win = _window('nord', backend)
+    try:
+        assert win.set_theme('solarized-dark') is True
+        assert win.theme == 'solarized-dark'
+        _assert_within_capability(backend, 8)
+    finally:
+        win.stop_curses()
+
+
+# --- 256 colours stay byte-for-byte identical -------------------------------
+
+def test_256_colour_install_uses_the_literal_theme_specs(monkeypatch):
+    monkeypatch.setattr(Theme, '_current', 'nord')
+    backend = HeadlessBackend(colors=256)
+    win = _window('nord', backend)
+    try:
+        assert backend.init_pair_calls == Theme.pair_specs('nord')
+    finally:
+        win.stop_curses()
+
+
+def test_pair_ids_beyond_color_pairs_are_skipped(monkeypatch):
+    monkeypatch.setattr(Theme, '_current', 'nord')
+    backend = HeadlessBackend(colors=256, color_pairs=8)
+    win = _window('nord', backend)
+    try:
+        assert all(pair < 8 for pair, _fg, _bg in backend.init_pair_calls)
+        assert Theme.DEFAULT_BG not in {pair for pair, _fg, _bg
+                                        in backend.init_pair_calls}
+    finally:
+        win.stop_curses()
+
+
+# --- -1 handling ------------------------------------------------------------
+
+def test_use_default_colors_failure_resolves_minus_one(monkeypatch):
+    monkeypatch.setattr(Theme, '_current', 'default')
+    backend = HeadlessBackend(colors=8, default_colors=False)
+    win = _window('default', backend)
+    try:
+        pairs = {pair: (fg, bg) for pair, fg, bg in backend.init_pair_calls}
+        assert all(-1 not in pair for pair in pairs.values())
+        # The theme's (-1, -1) default background becomes concrete elsewhere.
+        assert pairs[Theme.DEFAULT_BG] == (7, 0)
+        # DANGER is (1, -1) in the 'default' theme.
+        assert pairs[Theme.DANGER] == (1, 0)
+    finally:
+        win.stop_curses()
+
+
+def test_curses_backend_reports_use_default_colors_failure(monkeypatch):
+    def _raise():
+        raise curses.error('terminal does not support default colours')
+
+    monkeypatch.setattr(backend_mod.curses, 'use_default_colors', _raise)
+    backend = CursesBackend()
+    assert backend.use_default_colors() is False
+
+
+def test_curses_backend_captures_capabilities_after_start_color(monkeypatch):
+    monkeypatch.setattr(backend_mod.curses, 'start_color', lambda: None)
+    monkeypatch.setattr(backend_mod.curses, 'COLORS', 8, raising=False)
+    monkeypatch.setattr(backend_mod.curses, 'COLOR_PAIRS', 64, raising=False)
+    backend = CursesBackend()
+    backend.start_color()
+    assert backend.colors() == 8
+    assert backend.color_pairs() == 64
+
+
+def test_curses_backend_start_color_failure_degrades(monkeypatch):
+    def _raise():
+        raise curses.error('no colour support')
+
+    monkeypatch.setattr(backend_mod.curses, 'start_color', _raise)
+    backend = CursesBackend()
+    backend.start_color()  # must not raise
+    assert backend.colors() == 0
+
+
+# --- the pure palette mapping ----------------------------------------------
+
+def test_palette_rgb_uses_the_xterm_model():
+    assert palette_rgb(0) == (0, 0, 0)
+    assert palette_rgb(16) == (0, 0, 0)
+    assert palette_rgb(196) == (255, 0, 0)
+    assert palette_rgb(232) == (8, 8, 8)
+    assert palette_rgb(255) == (238, 238, 238)
+    # Unknown indices never raise.
+    assert palette_rgb(-7) == (0, 0, 0)
+    assert palette_rgb(9999) == (0, 0, 0)
+
+
+@pytest.mark.parametrize('index,colors,expected', [
+    (232, 16, 0),    # near-black gray -> black
+    (232, 8, 0),
+    (253, 16, 7),    # gray level 218 -> normal white (192), not bright white
+    (255, 16, 15),   # gray level 238 -> bright white
+    (253, 8, 7),     # ... and normal white is all an 8-colour terminal has
+    (196, 16, 9),    # pure red -> bright red
+    (196, 8, 1),     # ... normal red in 8 colours
+    (196, 256, 196),  # 256 colours: unchanged
+    (1, 8, 1),       # already available
+])
+def test_nearest_palette_index_known_conversions(index, colors, expected):
+    assert nearest_palette_index(index, colors) == expected
+
+
+def test_nearest_palette_index_without_colours_returns_minus_one():
+    assert nearest_palette_index(196, 0) == -1
+
+
+def test_resolve_color_pair_breaks_a_collapsed_pair():
+    # 232 and 16 both map to black on an 8-colour terminal; the foreground must
+    # move so the text stays legible.
+    fg, bg = resolve_color_pair(232, 16, 8, True)
+    assert bg == 0
+    assert fg != bg
+    assert 0 <= fg < 8
+
+
+def test_resolve_color_pair_returns_none_for_a_one_colour_terminal():
+    assert resolve_color_pair(1, 0, 1, True) is None
+
+
+def test_resolve_color_pair_keeps_default_pair_when_supported():
+    assert resolve_color_pair(-1, -1, 256, True) == (-1, -1)

{console_window-2.0.0.4 → console_window-2.0.0.6}/tests/test_theme.py

@@ -67,11 +67,22 @@ def test_startup_initialises_every_semantic_pair(monkeypatch):
         win.stop_curses()
 
 
-def test_theme_set_initialises_the_same_pair_set(colour_recorder, monkeypatch):
+def test_theme_set_initialises_the_same_pair_set(monkeypatch):
+    # Theme.set() must go through the live window's backend, not curses
+    # directly: the old direct path bypassed every low-colour guard.
     monkeypatch.setattr(Theme, '_current', None)
-    assert Theme.set('dark-mono') is True
-    assert set(Theme.SEMANTIC_PAIRS) <= set(colour_recorder)
-    assert Theme.DEFAULT_BG in colour_recorder
+    backend = HeadlessBackend(colors=True)
+    win = ConsoleWindow(opts=ConsoleWindowOpts(body_rows=10, head_rows=3),
+                        backend=backend, singleton=False)
+    try:
+        backend.init_pair_calls.clear()
+        assert Theme.set('dark-mono') is True
+        initialised = {pair for pair, _fg, _bg in backend.init_pair_calls}
+        assert set(Theme.SEMANTIC_PAIRS) <= initialised
+        assert Theme.DEFAULT_BG in initialised
+        assert win.theme == 'dark-mono'
+    finally:
+        win.stop_curses()
 
 
 # --- the shared picker screen ----------------------------------------------