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

{console_window-2.0.0.2 → console_window-2.0.0.4}/.github/workflows/ci.yml

@@ -19,9 +19,9 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install test dependencies
-        run: python -m pip install --upgrade pip pytest
-      - name: Run tests (TTY-free)
-        run: python -m pytest -q
+        run: python -m pip install pytest==9.1.1 pytest-cov==7.1.0
+      - name: Run tests (TTY-free) with coverage floor
+        run: python -m pytest -q --cov=console_window --cov-fail-under=80
 
   lint:
     name: ruff
@@ -31,9 +31,9 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.x"
+          python-version: "3.13"
       - name: Install ruff
-        run: python -m pip install ruff
+        run: python -m pip install ruff==0.17.0
       - name: Lint
         run: ruff check .
 
@@ -45,8 +45,22 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.x"
+          python-version: "3.13"
       - name: Install mypy
-        run: python -m pip install mypy
+        run: python -m pip install mypy==2.4.0
       - name: Type check
         run: python -m mypy
+
+  pylint:
+    name: pylint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install pylint
+        run: python -m pip install pylint==3.3.4
+      - name: Lint
+        run: python -m pylint console_window SampleApp.py runner --disable=C,R

console_window-2.0.0.4/AUDIT.md

@@ -0,0 +1,120 @@
+# `console-window` — Code & Design Audit
+
+**Audited:** 2026-10-22 (working tree on `4f48396`).
+**Scope:** the `console_window` package, its test suite, `SampleApp.py`, `runner`, packaging and CI. Competitive/ecosystem analysis is deliberately excluded (it is covered in [`README.md`](README.md:1)).
+**Method:** full source read of all 14 package modules plus the example and tests; `ruff`, `pylint`, `mypy`, `pytest` and `coverage` run locally; API reachability established by repo-wide call-site search, not by inference.
+
+| Metric | Value |
+| --- | --- |
+| Package size | 4,512 lines / 2,607 statements across 14 modules; stdlib-only, POSIX curses |
+| Example | [`SampleApp.py`](SampleApp.py:1) 520 lines; [`runner`](runner:1) 13 lines |
+| Tests | 302 tests, ~3,670 lines in 21 files — **all pass** (1.4 s) |
+| Coverage (`--source=console_window`) | **90%** overall; engine [`window.py`](console_window/window.py:1) **89%**, [`spinner.py`](console_window/spinner.py:1) **92%**, [`widgets.py`](console_window/widgets.py:1) **86%**, [`screens.py`](console_window/screens.py:1) **83%** |
+| `ruff check .` | clean (`E,F,W,I,B,C4,ANN,RUF,C901`) |
+| `pylint` | **10.00/10** with `C,R` disabled (0 warnings) |
+| Type checking | **mypy** configured for `console_window` and run in CI; clean (14 source files) |
+| CI gates ([`.github/workflows/ci.yml`](.github/workflows/ci.yml:1)) | tests on 3.10-3.13 with `--cov-fail-under=80`; `ruff`, `mypy` and `pylint --disable=C,R` jobs; every tool pinned (`pytest 9.1.1`, `pytest-cov 7.1.0`, `ruff 0.17.0`, `mypy 2.4.0`, `pylint 3.3.4`) |
+| Complexity (ruff `C901`, threshold 12) | worst is [`answer()`](console_window/window.py:1384) at **12**; next are [`parse_fancy_header()`](console_window/header.py:113) and [`perform_actions()`](console_window/screens.py:197) at **11** |
+
+Section numbers in older [`CHANGELOG.md`](CHANGELOG.md:1) entries and in source comments refer to earlier revisions of this document.
+
+## 1. Executive summary
+
+The library is small, dependency-free, and unusually disciplined for a single-author project: a real module split, a headless render backend, 302 fast TTY-free tests, a green linter and type checker, changelog and release metadata, and a worked example that is itself smoke-tested.
+
+There is no data-loss or security defect, and the interactive core is well covered. What is left is a small body of public surface with no consumer outside the test suite; the dialog retry policy is documented as an accepted limitation and every lint finding now states its reason. Highest-risk findings, in order:
+
+1. **Some public API has no consumer.** `ConsoleWindow.set_pick_range()`, `ConsoleWindow.draw()` and the `OptionSpinner.add()` tombstone are reached only from tests (§3.1).
+2. **The dialog retry policy is class-wide and discards input.** `answer()` spends the shared `render_retry_seconds` budget, and resize recovery drains every queued key. Both are now explicit, documented limitations rather than silent surprises (§3.2).
+
+## 2. Architecture as implemented
+
+| Module | Lines | Stmts | Cover | Role |
+| --- | --- | --- | --- | --- |
+| [`window.py`](console_window/window.py:1) | 2193 | 1271 | 89% | The engine: two pads + screen, add/draw/render/prompt/answer/alert/flash, navigation |
+| [`widgets.py`](console_window/widgets.py:1) | 337 | 231 | 86% | `InlineConfirmation`, `IncrementalSearchBar` (pure, no curses drawing) |
+| [`spinner.py`](console_window/spinner.py:1) | 339 | 215 | 92% | `OptionSpinner`: key → option registry, genre inference, scope subtraction, help body |
+| [`screens.py`](console_window/screens.py:1) | 248 | 161 | 83% | `Screen` base, `ScreenStack` router, `HOME_ST`, `BasicHelpScreen` |
+| [`theme.py`](console_window/theme.py:1) | 303 | 100 | 98% | 7 palettes, `set()`/`set_active()`, picker-screen factory |
+| [`textwidth.py`](console_window/textwidth.py:1) | 236 | 167 | 95% | Display-cell arithmetic: width, truncate, justify, wrap, wrap positions |
+| [`header.py`](console_window/header.py:1) | 162 | 110 | 97% | `Span`/`HeaderLine` token API + legacy `[x]`/`KEY:` string parser |
+| [`backend.py`](console_window/backend.py:1) | 282 | 128 | 88% | `Surface`/`RenderBackend` protocols, `CursesBackend`, `HeadlessBackend` |
+| [`geometry.py`](console_window/geometry.py:1) | 82 | 61 | 100% | Pure abut/indicator/pickable-row math |
+| [`opts.py`](console_window/opts.py:1) | 88 | 63 | 100% | `ConsoleWindowOpts` (`__slots__` + kwargs) |
+| [`context.py`](console_window/context.py:1) | 47 | 22 | 100% | Per-row `Context` (`genre`/`pickable`/`abut` + open kwargs) |
+| [`signals.py`](console_window/signals.py:1) | 144 | 63 | 87% | SIGINT policy: captured host handler, per-window setup/teardown, reset |
+| [`keys.py`](console_window/keys.py:1) | 18 | 3 | 100% | `NAVIGATION_KEYS` |
+| [`__init__.py`](console_window/__init__.py:1) | 33 | 12 | 100% | Re-exports + `__all__` |
+
+**Frame cycle.** `main_loop` → `screen.draw_screen()` (`clear()` + `add_header*`/`add_body` into the two pads) → `win.render()` → `fix_positions()` (clamp/scroll/pick, returns `indent`) → gutter/separator/indicator → `pnoutrefresh` both pads → `doupdate()` → `win.prompt()` (key read + built-in navigation) → `handle_key()` → `stack.perform_actions(spin)` (convention dispatch of `<attr>_ACTION`) → `clear()`.
+
+**Two data models, one window.** Layout/scroll/pick live in `SimpleNamespace`s (`self.head`, `self.body`) with parallel lists (`texts`, `text_attrs` run-length encoded, `contexts`, `row_cnt`); `Row Context` carries per-row semantics. `Screen` subclasses add routing and `*_ACTION` dispatch. `OptionSpinner` is the key/option registry, optionally scope-aware per screen with automatic scope subtraction ([`spinner.py:134`](console_window/spinner.py:134)).
+
+**The seam covers the drawing, input and colour paths.** `RenderBackend` abstracts `start`/`newpad`/`doupdate`/`curs_set`/`update_lines_cols`/`is_term_resized`/`has_colors`/`start_color`/`use_default_colors`/`init_pair`/`color_pair`/`stop`, and the dialogs, flash, resize checks and colour init all go through it.
+
+**Two window models over that seam.** `ConsoleWindow(singleton=True)` (the default) restores the historical process-wide screen: every instance shares one screen/backend, `static_scr`/`static_win` are populated, and `ConsoleWindow.stop_curses()` tears the process screen down. `singleton=False` keeps the per-instance model: each window owns its screen and teardown, and `stop_all()` is the multi-window hook. The first construction latches the mode process-wide; mixing values asserts.
+
+**Current shape.** Docstrings are reserved for public entry points whose call shape needs spelling out, while module- and algorithm-level explanation lives in comments; `_selftest.py` is folded into `SampleApp.py`; the pad-overflow contract is counted, warned about once per fill episode, and enforced in this project's suite; and the package version is single-sourced through `dynamic = ["version"]`.
+
+## 3. Findings
+
+### 3.1 🟡 Unreachable public surface
+
+No consumer outside the test suite for:
+
+| Symbol | Where | Note |
+| --- | --- | --- |
+| `ConsoleWindow.set_pick_range()` | [`window.py:609`](console_window/window.py:609) | The `pick_range` feature's only public entry point; called only by [`tests/test_interactive.py`](tests/test_interactive.py:434) |
+| `OptionSpinner.add()` | [`spinner.py:163`](console_window/spinner.py:163) | Retired tombstone that raises `NotImplementedError` pointing at `add_key()`; only [`tests/test_spinner.py`](tests/test_spinner.py:259) calls it, to assert the raise |
+| `ConsoleWindow.draw()` | [`window.py:863`](console_window/window.py:863) | Named as a model-writing entry point in [`README.md`](README.md:52), but no library or example code calls it; only tests do ([`tests/test_interactive.py`](tests/test_interactive.py:368), [`tests/test_overflow.py`](tests/test_overflow.py:152), [`tests/test_viewport_pad.py`](tests/test_viewport_pad.py:79), [`tests/test_widechars.py`](tests/test_widechars.py:129)) |
+
+`OptionSpinner.add()` keeps its old signature so pre-2.0 call sites fail at the call rather than at import, and its `NotImplementedError` names the replacement call. It is otherwise inert, so the only thing keeping it alive is its own regression test.
+
+`draw()` is the inverse case: the README presents it as part of the row-model API while every actual caller is a test, so the documentation promises a path the project never demonstrates.
+
+The former fourth row of this table, `SampleApp.do_key()`, has been **removed**: it had no caller at all because `main_loop` dispatches through `handle_key()`, which already forwards spinner keys itself.
+
+**Fix:** delete what no consumer needs, or promote it deliberately: give each survivor an exercising caller (the example or a documented snippet) alongside its test. For `OptionSpinner.add()`, either set a removal release or keep it explicitly documented as deprecated.
+
+### 3.2 ✅ `answer()` residual: documented limitations
+
+[`answer()`](console_window/window.py:1384) has one unambiguous meaning per outcome (`str` = submitted, `None` = user abort, `TerminalTooSmallError` = environment), and its recovery loop is bounded. Two narrow characteristics remain, and both are now stated where a maintainer will meet them rather than fixed:
+
+* **The retry budget is class-wide.** `answer()` spends the shared `render_retry_seconds` budget ([`window.py:1421`](console_window/window.py:1421), declared at [`window.py:160`](console_window/window.py:160)). The budget is read as `ConsoleWindow.render_retry_seconds`, so it applies to `render()` and `answer()` alike and must be tuned on the class; an instance assignment has no effect. This is accepted because the knob already exists, no consumer has asked for a different dialog budget, and a second option would add public surface for a ~2 s recovery policy. The attribute comment in [`window.py`](console_window/window.py:153) spells this out.
+* **Recovery discards queued keys.** [`_recover_from_resize()`](console_window/window.py:1750) drains **every** queued key, not only `KEY_RESIZE` ([`window.py:1767`](console_window/window.py:1767)). This is accepted because curses exposes no push-back API: preserving keys would mean replaying raw codes read after a failed redraw, where duplicates and partial escape sequences are indistinguishable from real input. The loss is bounded by `render_retry_seconds` (keys typed after recovery are read normally), and both the method docstring and [`answer()`](console_window/window.py:1384)'s docstring state the loss explicitly.
+
+**Resolution:** documented as accepted limitations; no behaviour change. Revisit only if an app needs an independent dialog budget or faithful key replay, which would justify the extra API and input-buffer plumbing.
+
+### 3.3 ✅ Lint findings now carry rationale
+
+`pylint` is **10.00/10** with `C,R` disabled. Each former warning now either states why it is deliberate or has been removed:
+
+* **protected access** — the registry helpers explain that the module owns `_registry_key` ([`window.py:97`](console_window/window.py:97), [`window.py:105`](console_window/window.py:105)); the `stop_curses` descriptor explains why it reaches the private implementations ([`window.py:147`](console_window/window.py:147), [`window.py:149`](console_window/window.py:149)); `Theme.set()` owns the internal default-colour step ([`theme.py:204`](console_window/theme.py:204)); the sample resets `filter_bar._text` because `IncrementalSearchBar` exposes only a read-only `text` property ([`SampleApp.py:402`](SampleApp.py:402)).
+* **unused arguments** — `_paint_alert()`'s dead `row9` parameter was removed (both call sites updated). The headless backend's protocol arguments ([`backend.py:255`](console_window/backend.py:255), [`backend.py:283`](console_window/backend.py:283)) and `DemoScreen.__init__`'s protocol `name` ([`SampleApp.py:244`](SampleApp.py:244)) are kept for signature compatibility and say so inline.
+* **not-callable** — [`screens.py:68`](console_window/screens.py:68) carries a `disable-next` noting that pylint cannot see through `getattr` + `callable()`.
+* **broad exceptions** — [`SampleApp.py:149`](SampleApp.py:149) explains the sample-data fallback; [`SampleApp.py:518`](SampleApp.py:518) explains the top-level demo guard that leaves the terminal usable.
+
+**Resolution:** resolved; no suppression is unexplained, and `pylint --disable=C,R` is clean.
+
+## 4. Prioritized recommendations
+
+**P1 — surface**
+
+1. Delete or promote the unreachable API and the `draw()` documentation mismatch (§3.1). (`SampleApp.do_key()` has already been deleted.)
+
+**P2 — hygiene**
+
+The §3.2 dialog residuals are closed as documented limitations and the §3.3 lint findings are annotated; reopen either only against a concrete consumer requirement.
+
+## 5. Reproduction
+
+```bash
+python3 -m ruff check .
+python3 -m pytest -q
+python3 -m pytest -q --cov=console_window --cov-fail-under=80   # the CI coverage gate
+python3 -m coverage run --source=console_window -m pytest -q && python3 -m coverage report -m
+python3 -m pylint console_window SampleApp.py runner --disable=C,R
+python3 -m mypy
+python3 -m ruff check --select C901 console_window SampleApp.py   # uses the ratchet in pyproject.toml
+python3 -W error::UserWarning -c "import SampleApp"   # exit path for the pad-overflow policy
+```

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

@@ -6,6 +6,18 @@ This project follows [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 
 ### Added
+- 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
+  keeps one pair table per terminal, so installing a palette still affects the
+  shared screen) and that window's pads are repainted. `Theme.set()` remains the
+  process-wide switch and now relabels every live window. Startup, `Theme.set()`
+  and `set_theme()` install colours from the single `Theme.pair_specs()` list,
+  so the three paths cannot drift apart (AUDIT.md §3.1).
+- `reset_ctrl_c()` (also exported from the package root) restores the SIGINT
+  handler that was installed before the first window and clears the Ctrl-C
+  policy latch, for embedding applications that manage SIGINT themselves
+  (AUDIT.md §3.1).
 - `mypy` type checking for the library: `[tool.mypy]` in `pyproject.toml`
   checks `console_window` (`files`, `ignore_missing_imports`,
   `warn_unused_ignores`, `disallow_untyped_defs = false`) and a new `types` job
@@ -38,6 +50,49 @@ This project follows [Semantic Versioning](https://semver.org/).
   smoke-tested in CI (AUDIT.md §3.2).
 
 ### Changed
+- Every `pylint` warning now states why it is deliberate (AUDIT.md §3.3), taking
+  `pylint --disable=C,R` from 9.94/10 to **10.00/10**. Protected-access and
+  protocol-signature findings carry scoped disables with an adjacent reason,
+  `_paint_alert()`'s genuinely unused `row9` parameter was removed, and the
+  `getattr` + `callable()` call site uses `disable-next`. No runtime behaviour
+  changed.
+- The example's application class is now `SampleApp` (was `DemoApp`), matching
+  the module filename and the package name. The screen base class keeps its
+  `DemoScreen` name; only the app class and its construction site changed.
+- `answer()`'s recovery policy is now documented rather than implicit
+  (AUDIT.md §3.2): the retry loop deliberately shares the class-level
+  `render_retry_seconds`/`render_retry_interval` budget with `render()`, and
+  `_recover_from_resize()` deliberately discards every queued key. The budget
+  is read on the class, so tuning it on one instance has no effect, and keys
+  typed during the bounded recovery window are lost because curses offers no
+  push-back API. Both points are stated on the attributes, on `answer()` and on
+  the recovery method; no behaviour changed.
+- The SIGINT policy captures the handler that was installed before the library
+  first took the signal over instead of assuming `signal.default_int_handler`,
+  and restores it when the last live window stops rather than on the first
+  teardown, so one of several windows stopping cannot disarm the others.
+  Stopping every window ends the latch, so a later window can make Ctrl-C an
+  application key again; the latch still prevents a non-terminating window from
+  swallowing Ctrl-C while a terminating one is live (AUDIT.md §3.1).
+- The sample app's `THEMES` screen is now generated by
+  `Theme.create_picker_screen()` instead of duplicating the factory's header and
+  colour swatches. The generated screen applies the host's `opts.theme` before
+  drawing (so an ordinary `OptionSpinner` cycle binding keeps working) and
+  `spin_theme_ACTION()` starts from that option when present. The factory now has
+  direct tests in `tests/test_theme.py` (AUDIT.md §3.3).
+- Body and header pads are now viewport-sized blit buffers rather than content
+  stores. `add_body()`, `add_header()` and `draw()` write the model only, and
+  `render()` paints the visible page into pad row 0, so pad memory and the
+  per-frame `clear()` cost track the terminal instead of the highest row count
+  an app ever reached. `opts.body_rows`/`opts.head_rows` are retained for
+  compatibility but are now **advisory hints only**: no row is discarded for
+  exceeding them. The single ceiling is the new `opts.max_rows` (default
+  `32767`, `None` for unlimited), which is what `rows_dropped` and its warning
+  report. Apps no longer have to pre-size storage for the largest list they
+  might show. `draw()` keeps its content-row coordinates (a row written
+  off-screen appears when scrolled to) and records its span so the attribute it
+  was given survives the deferred paint. Pick highlighting is applied while
+  painting, so it follows the viewport when scrolling without moving the pick.
 - The package version now has a single source of truth: `pyproject.toml`
   declares `dynamic = ["version"]` and flit reads `__version__` from
   `console_window/__init__.py` (AUDIT.md §3.14). The stale manual-build recipe
@@ -60,7 +115,36 @@ This project follows [Semantic Versioning](https://semver.org/).
   (`tests/test_sample_app.py`) to match. The classes inside are still named
   `DemoApp`/`DemoScreen`.
 
+- `OptionSpinner.add()` is now a retired tombstone. Its comment handling sliced
+  the truncated value list with the pre-truncation index, so `comments` was
+  always empty; rather than register a half-configured option it raises
+  `NotImplementedError` naming `add_key()` and showing the replacement call.
+  No in-repo code used it.
+
 ### Fixed
+- `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
+  an over-ceiling `draw()` returned silently while the rest of the overflow
+  contract reported nothing. The stale half of the audit finding (phantom rows,
+  missing contexts, lost attributes) had already been fixed by the
+  viewport-sized-pad model and is now documented in AUDIT.md §3.2.
+- `ScreenStack.act_in()` no longer raises `AttributeError` when the requested
+  action flag is absent; it returns `False` and leaves the options object
+  untouched. Its one-shot, current-screen semantics are now covered by
+  `tests/test_screens.py` and documented in the README (AUDIT.md §3.3).
+- `BasicHelpScreen.draw_screen()` resolves the window from `self.app.win` at
+  draw time instead of using the `app.win` value cached by `Screen.__init__`.
+  Applications that build their `Screen` objects before their `ConsoleWindow`
+  (including `SampleApp`) then get a working help screen instead of
+  `AttributeError: 'NoneType' object has no attribute 'set_pick_mode'` when
+  mixing `BasicHelpScreen` into an existing screen class.
+- `add_fancy_header()` now treats `HeaderLine.bracket_key()` delimiters as
+  markup in every mode except `'Off'`: the brackets are removed and the
+  enclosed span keeps its `KEY` styling. Previously a `HeaderLine` was emitted
+  verbatim, so it rendered identically to `add_header_line()`. The explicit
+  path still shows literal brackets, and declared span roles are preserved
+  rather than re-parsed from the rendered text.
 - Navigation keys are responsive again. Two 2.0.0 hot paths made a full
   redraw of a large list far slower than 1.4.3. `textwidth.truncate()` ran
   three `unicodedata` lookups per character on every row, and

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: console-window
-Version: 2.0.0.2
+Version: 2.0.0.4
 Summary: A robust curses wrapper for creating Text User Interfaces (TUIs).
 Author-email: Joe Defen <joedef@duck.com>
 Requires-Python: >=3.10
@@ -68,8 +68,8 @@ up immediately. The equivalent one-off is `python3 SampleApp.py`.)
 
 The wrapper handles several advanced terminal interaction patterns automatically:
 
-  * **Padded Content Management:** Uses separate `head` and `body` pads, allowing for a static header area while the main content area can be scrolled independently.
-  * **Loud Pad Limits:** The pads are fixed-size (`opts.head_rows` / `opts.body_rows`). Rows added past capacity are still discarded, but no longer quietly: the first discarded row of each fill episode emits a `UserWarning` naming the pad and the option to raise, 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.
+  * **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.
   * **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`.
@@ -106,7 +106,11 @@ demonstrates:
 * **`InlineConfirmation`** — `SPACE` asks you to confirm with `y` before
   "processing" the picked row.
 * **Themes** — a `THEMES` screen of colour samples backed by
-  `Theme.list_all()` / `get_current()` / `set()`.
+  `Theme.list_all()` / `get_current()` / `set()`. The active theme is now
+  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.
 * **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
@@ -116,18 +120,21 @@ demonstrates:
 * **Token-based headers** — `HeaderLine` (`text`, `bracket_key`, `key`, `extend`)
   rendered with `add_header_line()`, rather than string markup.
 * **`Ctrl-C` as an application key** — `ctrl_c_terminates=False` and
-  `keys={0x3, ord('q')}` on the quit action. This works only while no window in
-  the process has requested terminating Ctrl-C: once any window uses the default
-  (`ctrl_c_terminates=True`), terminating Ctrl-C is latched for the process
-  lifetime and cannot be undone.
+  `keys={0x3, ord('q')}` on the quit action. This works only while no live
+  window in the process has requested terminating Ctrl-C: once any window uses
+  the default (`ctrl_c_terminates=True`), terminating Ctrl-C is latched for as
+  long as a window depends on it. The handler that was installed before the
+  first window is captured and restored when the last window stops, and
+  `reset_ctrl_c()` does the same deliberately for an embedding application that
+  manages SIGINT itself.
 * **Full-repaint recovery** — `r` toggles `render(redraw=True)`, the path that
   repaints after terminal corruption.
 * **Multi-row picking** — `p` sets `pick_size` (1–3) via
   `set_pick_mode(True, size)`.
 * **Large-body stress** — `z` appends 2000 non-pickable filler rows to exercise
-  big pads and the scroll indicator. The sample raises `body_rows` to 4000 so
-  that nothing is discarded: `row_cnt` is capped at the pad size and any excess
-  is counted in `ConsoleWindow.rows_dropped`.
+  long bodies and the scroll indicator. No option is needed for them: the pads
+  stay viewport-sized, memory and `clear()` cost do not grow with the row count,
+  and the default `max_rows` ceiling is far above 2000.
 
 ### Running it
 
@@ -145,7 +152,8 @@ from console_window import ConsoleWindow, ConsoleWindowOpts
 
 def main() -> None:
     # ConsoleWindow.__init__ performs the curses setup (no curses.wrapper needed).
-    win = ConsoleWindow(opts=ConsoleWindowOpts(head_line=True, body_rows=200))
+    # No row sizing is required; max_rows is only a safety ceiling.
+    win = ConsoleWindow(opts=ConsoleWindowOpts(head_line=True))
     try:
         while True:
             win.clear()
@@ -168,6 +176,14 @@ For anything beyond a single list, subclass `Screen` and drive it with
 `ScreenStack` — that is what the sample app does, and it is the paradigm the
 library is designed around.
 
+`ScreenStack.perform_actions()` is the normal router: it walks the spinner
+options, honours their scopes, and calls the matching `<attr>_ACTION` method.
+For apps that dispatch an action themselves, `ScreenStack.act_in(action,
+screens=None)` is the low-level single-flag variant: it clears that flag from
+`stack.obj` and returns whether it was set and the current screen matched.
+`ScreenStack.is_curr()` answers the screen test on its own. A missing flag reads
+as `False`, so an options object need not pre-seed every action.
+
 ### Singleton vs. per-instance windows
 
 `ConsoleWindow` supports two process-wide models, selected by the constructor's

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

@@ -49,8 +49,8 @@ up immediately. The equivalent one-off is `python3 SampleApp.py`.)
 
 The wrapper handles several advanced terminal interaction patterns automatically:
 
-  * **Padded Content Management:** Uses separate `head` and `body` pads, allowing for a static header area while the main content area can be scrolled independently.
-  * **Loud Pad Limits:** The pads are fixed-size (`opts.head_rows` / `opts.body_rows`). Rows added past capacity are still discarded, but no longer quietly: the first discarded row of each fill episode emits a `UserWarning` naming the pad and the option to raise, 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.
+  * **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.
   * **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`.
@@ -87,7 +87,11 @@ demonstrates:
 * **`InlineConfirmation`** — `SPACE` asks you to confirm with `y` before
   "processing" the picked row.
 * **Themes** — a `THEMES` screen of colour samples backed by
-  `Theme.list_all()` / `get_current()` / `set()`.
+  `Theme.list_all()` / `get_current()` / `set()`. The active theme is now
+  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.
 * **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
@@ -97,18 +101,21 @@ demonstrates:
 * **Token-based headers** — `HeaderLine` (`text`, `bracket_key`, `key`, `extend`)
   rendered with `add_header_line()`, rather than string markup.
 * **`Ctrl-C` as an application key** — `ctrl_c_terminates=False` and
-  `keys={0x3, ord('q')}` on the quit action. This works only while no window in
-  the process has requested terminating Ctrl-C: once any window uses the default
-  (`ctrl_c_terminates=True`), terminating Ctrl-C is latched for the process
-  lifetime and cannot be undone.
+  `keys={0x3, ord('q')}` on the quit action. This works only while no live
+  window in the process has requested terminating Ctrl-C: once any window uses
+  the default (`ctrl_c_terminates=True`), terminating Ctrl-C is latched for as
+  long as a window depends on it. The handler that was installed before the
+  first window is captured and restored when the last window stops, and
+  `reset_ctrl_c()` does the same deliberately for an embedding application that
+  manages SIGINT itself.
 * **Full-repaint recovery** — `r` toggles `render(redraw=True)`, the path that
   repaints after terminal corruption.
 * **Multi-row picking** — `p` sets `pick_size` (1–3) via
   `set_pick_mode(True, size)`.
 * **Large-body stress** — `z` appends 2000 non-pickable filler rows to exercise
-  big pads and the scroll indicator. The sample raises `body_rows` to 4000 so
-  that nothing is discarded: `row_cnt` is capped at the pad size and any excess
-  is counted in `ConsoleWindow.rows_dropped`.
+  long bodies and the scroll indicator. No option is needed for them: the pads
+  stay viewport-sized, memory and `clear()` cost do not grow with the row count,
+  and the default `max_rows` ceiling is far above 2000.
 
 ### Running it
 
@@ -126,7 +133,8 @@ from console_window import ConsoleWindow, ConsoleWindowOpts
 
 def main() -> None:
     # ConsoleWindow.__init__ performs the curses setup (no curses.wrapper needed).
-    win = ConsoleWindow(opts=ConsoleWindowOpts(head_line=True, body_rows=200))
+    # No row sizing is required; max_rows is only a safety ceiling.
+    win = ConsoleWindow(opts=ConsoleWindowOpts(head_line=True))
     try:
         while True:
             win.clear()
@@ -149,6 +157,14 @@ For anything beyond a single list, subclass `Screen` and drive it with
 `ScreenStack` — that is what the sample app does, and it is the paradigm the
 library is designed around.
 
+`ScreenStack.perform_actions()` is the normal router: it walks the spinner
+options, honours their scopes, and calls the matching `<attr>_ACTION` method.
+For apps that dispatch an action themselves, `ScreenStack.act_in(action,
+screens=None)` is the low-level single-flag variant: it clears that flag from
+`stack.obj` and returns whether it was set and the current screen matched.
+`ScreenStack.is_curr()` answers the screen test on its own. A missing flag reads
+as `False`, so an options object need not pre-seed every action.
+
 ### Singleton vs. per-instance windows
 
 `ConsoleWindow` supports two process-wide models, selected by the constructor's