console-window 2.0.0.5__tar.gz → 2.0.0.7__tar.gz

{console_window-2.0.0.5 → console_window-2.0.0.7}/CHANGELOG.md

@@ -6,6 +6,19 @@ This project follows [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 
 ### Added
+- `suspend_curses()`/`resume_curses()` on `ConsoleWindow`: leave curses mode
+  with `endwin()` while keeping the window (pads, content model, pick state)
+  alive, then reattach a screen and repaint.  This is the supported way for an
+  app to shell out to a command or an editor and come back.  The pads survive
+  because `endwin()` restores the terminal without destroying the curses
+  SCREEN; `resume_curses()` refreshes the screen handle, backend, dimensions,
+  pad backgrounds and redraw bookkeeping.
+- Singleton-mode compatibility for the pre-2.0 start/stop pair:
+  `stop_curses()` now *suspends* the shared screen and `start_curses()`
+  resumes it, so `stop_curses(); ...; start_curses()` works again (this is what
+  efibootdude's write/reboot paths needed).  `ConsoleWindow.stop_all()` remains
+  the permanent teardown and is the atexit hook; per-instance windows keep
+  `stop_curses()` as a one-way teardown and use suspend/resume explicitly.
 - Per-window themes. `ConsoleWindow.theme` records the theme a window is on,
   `ConsoleWindowOpts(theme=...)` seeds it, and `ConsoleWindow.set_theme()`
   switches it: colours are reinstalled through the window's own backend (curses
@@ -122,6 +135,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

{console_window-2.0.0.5 → console_window-2.0.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: console-window
-Version: 2.0.0.5
+Version: 2.0.0.7
 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
@@ -191,15 +195,36 @@ as `False`, so an options object need not pre-seed every action.
 
 * **`singleton=True` (default)** — the historical process-wide model. Every
   window draws through one shared screen, `ConsoleWindow.static_scr` and
-  `ConsoleWindow.static_win` are populated, and the unbound
-  `ConsoleWindow.stop_curses()` tears that screen down. Calling
-  `win.stop_curses()` on any singleton window does the same. A second window
-  reuses the first window's screen and backend.
+  `ConsoleWindow.static_win` are populated, and a second window reuses the
+  first window's screen and backend. `stop_curses()` here *suspends* the shared
+  screen and `start_curses()` resumes it (the pre-2.0 pair, kept working);
+  `ConsoleWindow.stop_all()` is the permanent teardown and the `atexit` hook.
 * **`singleton=False`** — per-instance windows. Each window owns its screen,
-  pads and teardown; `win.stop_curses()` stops only that window,
+  pads and teardown; `win.stop_curses()` stops only that window for good,
   `ConsoleWindow.stop_all()` stops every live window, and the unbound
   `ConsoleWindow.stop_curses()` is an error.
 
+### Pausing to run another program
+
+To shell out (an editor, a package manager, `efibootmgr`, a confirmation
+prompt) and then come back, suspend instead of stopping:
+
+```python
+win.suspend_curses()          # endwin(): the terminal is yours again
+try:
+    ... prints, input(), subprocess.run(...) ...
+finally:
+    win.resume_curses()       # reattaches a screen; the next render() repaints
+```
+
+`endwin()` restores the terminal without destroying the curses SCREEN, so the
+pads, the content model and the pick state all survive; resume refreshes the
+screen handle, backend, dimensions, pad backgrounds and redraw bookkeeping.
+In singleton mode `suspend_curses()` suspends every window that shares the
+screen, and `resume_curses()` reattaches all of them. The legacy pair works the
+same way there: `ConsoleWindow.stop_curses(); ...; ConsoleWindow.start_curses()`.
+Only `stop_all()` is a permanent teardown.
+
 The first successful construction latches the mode for the whole process.
 Mixing the two values raises `AssertionError` rather than silently changing what
 teardown means. Use `singleton=False` in tests and in applications that create

{console_window-2.0.0.5 → console_window-2.0.0.7}/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
@@ -172,15 +176,36 @@ as `False`, so an options object need not pre-seed every action.
 
 * **`singleton=True` (default)** — the historical process-wide model. Every
   window draws through one shared screen, `ConsoleWindow.static_scr` and
-  `ConsoleWindow.static_win` are populated, and the unbound
-  `ConsoleWindow.stop_curses()` tears that screen down. Calling
-  `win.stop_curses()` on any singleton window does the same. A second window
-  reuses the first window's screen and backend.
+  `ConsoleWindow.static_win` are populated, and a second window reuses the
+  first window's screen and backend. `stop_curses()` here *suspends* the shared
+  screen and `start_curses()` resumes it (the pre-2.0 pair, kept working);
+  `ConsoleWindow.stop_all()` is the permanent teardown and the `atexit` hook.
 * **`singleton=False`** — per-instance windows. Each window owns its screen,
-  pads and teardown; `win.stop_curses()` stops only that window,
+  pads and teardown; `win.stop_curses()` stops only that window for good,
   `ConsoleWindow.stop_all()` stops every live window, and the unbound
   `ConsoleWindow.stop_curses()` is an error.
 
+### Pausing to run another program
+
+To shell out (an editor, a package manager, `efibootmgr`, a confirmation
+prompt) and then come back, suspend instead of stopping:
+
+```python
+win.suspend_curses()          # endwin(): the terminal is yours again
+try:
+    ... prints, input(), subprocess.run(...) ...
+finally:
+    win.resume_curses()       # reattaches a screen; the next render() repaints
+```
+
+`endwin()` restores the terminal without destroying the curses SCREEN, so the
+pads, the content model and the pick state all survive; resume refreshes the
+screen handle, backend, dimensions, pad backgrounds and redraw bookkeeping.
+In singleton mode `suspend_curses()` suspends every window that shares the
+screen, and `resume_curses()` reattaches all of them. The legacy pair works the
+same way there: `ConsoleWindow.stop_curses(); ...; ConsoleWindow.start_curses()`.
+Only `stop_all()` is a permanent teardown.
+
 The first successful construction latches the mode for the whole process.
 Mixing the two values raises `AssertionError` rather than silently changing what
 teardown means. Use `singleton=False` in tests and in applications that create

{console_window-2.0.0.5 → console_window-2.0.0.7}/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.5"
+__version__ = "2.0.0.7"
 
 from .context import Context
 from .header import HeaderLine, Span

{console_window-2.0.0.5 → console_window-2.0.0.7}/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.
@@ -236,6 +313,9 @@ class HeadlessBackend:
 
     def start(self, timeout_ms: int) -> Surface:
         self.screen.timeout(timeout_ms)
+        # A backend that has been (re)started is live again; resume paths rely
+        # on this, so a suspend/resume cycle does not leave ``stopped`` latched.
+        self.stopped = False
         return self.screen
 
     def newpad(self, rows: int, cols: int) -> Surface:
@@ -264,13 +344,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.5 → console_window-2.0.0.7}/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