console-window 1.4.3__tar.gz → 2.0.0__tar.gz

console_window-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    name: tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        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
+
+  lint:
+    name: ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install ruff
+        run: python -m pip install ruff
+      - name: Lint
+        run: ruff check .
+
+  types:
+    name: mypy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install mypy
+        run: python -m pip install mypy
+      - name: Type check
+        run: python -m mypy

console_window-2.0.0/AUDIT.md

@@ -0,0 +1,152 @@
+# `console-window` — Code & Design Audit
+
+**Audited:** 2026-10-15 (`368304d`); **refreshed:** 2026-10-18 (`15125a8`) after removing every finding that has since been resolved. Section references inside older `CHANGELOG.md` entries point at the pre-refresh numbering.
+**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 | 3,988 lines / 2,391 statements across 14 modules; stdlib-only, POSIX curses |
+| Example | [`SampleApp.py`](SampleApp.py:1) 532 lines; [`runner`](runner:1) 13 lines |
+| Tests | 268 tests, ~3,045 lines in 18 files — **all pass** (1.5 s) |
+| Coverage (`--source=console_window`) | **87%** overall; engine [`window.py`](console_window/window.py:1) **88%**, [`theme.py`](console_window/theme.py:1) **69%**, [`screens.py`](console_window/screens.py:1) **67%** |
+| `ruff check .` | clean (`E,F,W,I,B,C4,ANN,RUF,C901`) |
+| `pylint` | 9.92/10 with `C,R` disabled |
+| Type checking | **mypy** configured for `console_window` and run in CI; clean (14 source files) |
+| Complexity (ruff `C901`, threshold 12) | `prompt()` decomposed from 43 to **5**; worst remaining is [`answer()`](console_window/window.py:1167) at **12** |
+
+## 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, 268 fast TTY-free tests, a green linter and type checker, changelog and release metadata, and a worked example that is itself smoke-tested. Resolved findings from the 2026-10-15 audit have been removed from this document; [`CHANGELOG.md`](CHANGELOG.md:1) records them.
+
+The remaining risks are narrower than the ones in the original audit. There is no data-loss or security defect, and the interactive core is no longer an untested hole. What is left is one drawing path outside the overflow contract, a body of unreachable or dead-but-broken public surface, residual process-global state, and CI that cannot reproduce its own inputs. Highest-risk findings, in order:
+
+1. **[`draw()`](console_window/window.py:749) bypasses the pad-overflow policy.** It inflates `row_cnt` without a capacity check and never records row context or attributes, so phantom rows, silently pickable rows and attribute loss can follow (§3.2).
+2. **A meaningful amount of public API is unreachable and one piece is dead-but-broken.** `Theme.create_picker_screen()`, `ScreenStack.act_in()`, `ScreenStack.is_curr()`, `ConsoleWindow.set_pick_range()`, `BasicHelpScreen` and `OptionSpinner.add()` have no consumer outside the test suite; `add()` additionally discards the `comments` field it exists to populate (§3.3).
+3. **Process-global state is still managed asymmetrically.** The active theme is a class global, and the Ctrl-C policy deliberately latches terminating Ctrl-C for the process lifetime without restoring a host application's prior SIGINT handler (§3.1).
+4. **CI is green but shallow.** Tool versions are unpinned, and there is no coverage or `pylint` gate, so the current 87% coverage and 9.92/10 score are not protected (§3.4).
+
+None of these is a data-loss or security defect, and the project's own bar remains high. The work left is concentrated in the list above rather than spread across the package.
+
+## 2. Architecture as implemented
+
+| Module | Lines | Stmts | Cover | Role |
+| --- | --- | --- | --- | --- |
+| [`window.py`](console_window/window.py:1) | 1983 | 1185 | 88% | 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) | 333 | 225 | 87% | `OptionSpinner`: key → option registry, genre inference, scope subtraction, help body |
+| [`screens.py`](console_window/screens.py:1) | 234 | 159 | 67% | `Screen` base, `ScreenStack` router, `HOME_ST`, `BasicHelpScreen` |
+| [`theme.py`](console_window/theme.py:1) | 231 | 71 | 69% | 7 palettes, `set()`/`set_active()`, picker-screen factory |
+| [`textwidth.py`](console_window/textwidth.py:1) | 170 | 129 | 95% | Display-cell arithmetic: width, truncate, justify, wrap, wrap positions |
+| [`header.py`](console_window/header.py:1) | 126 | 88 | 99% | `Span`/`HeaderLine` token API + legacy `[x]`/`KEY:` string parser |
+| [`backend.py`](console_window/backend.py:1) | 279 | 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) | 78 | 59 | 100% | `ConsoleWindowOpts` (`__slots__` + kwargs) |
+| [`context.py`](console_window/context.py:1) | 37 | 17 | 100% | Per-row `Context` (`genre`/`pickable`/`abut` + open kwargs) |
+| [`signals.py`](console_window/signals.py:1) | 49 | 24 | 96% | SIGINT policy globals |
+| [`keys.py`](console_window/keys.py:1) | 18 | 3 | 100% | `NAVIGATION_KEYS` |
+| [`__init__.py`](console_window/__init__.py:1) | 31 | 11 | 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 have been replaced by comments, `_selftest.py` is folded into `SampleApp.py`, the pad-overflow contract is counted + warned + enforced in this project's suite, and the package version is single-sourced through `dynamic = ["version"]`.
+
+## 3. Findings
+
+### 3.1 🟡 Process-global theme, and a one-way Ctrl-C latch
+
+`Theme._current` is a class attribute ([`theme.py:36`](console_window/theme.py:36)) — documented, but it means two windows in one process cannot differ. The Ctrl-C policy is now safe against the interleaving that used to leave a custom handler installed, because terminating Ctrl-C is a one-way process-lifetime latch ([`signals.py:16`](console_window/signals.py:16)): once [`setup_ctrl_c()`](console_window/signals.py:31) sees a terminating request it installs Python's default handler and [`teardown_ctrl_c()`](console_window/signals.py:45) subsequently no-ops.
+
+**Limits:** the active theme remains global, and the latch deliberately restores `signal.default_int_handler` rather than a handler a host application may have installed before the first window. There is no public reset. An embedding application that manages SIGINT itself can therefore lose its handler for the rest of the process.
+
+**Fix:** make the theme per-window (or document one-theme-per-process explicitly), and either capture/restore the previous SIGINT handler or expose a deliberate reset.
+
+### 3.2 🟡 `draw()` bypasses the pad-overflow policy
+
+Overflow through `_add()` is counted (`ns.rows_dropped`, exposed as [`ConsoleWindow.rows_dropped`](console_window/window.py:359)), warned about once per fill episode with a caller-facing `stacklevel`, reset by [`clear()`](console_window/window.py:1759), non-fatal by design, and enforced in this project's own suite via `filterwarnings = ["error::UserWarning"]` ([`pyproject.toml:49`](pyproject.toml:49)).
+
+**The gap:** [`draw()`](console_window/window.py:749) writes a raw row and inflates `ns.row_cnt = max(ns.row_cnt, y+1)` ([`window.py:755`](console_window/window.py:755)) **without any capacity check**, so it can put `row_cnt` past the pad's real row count — after which `calc()` computes `max_scroll_pos` from phantom rows, `highlight_picked()` walks rows that do not exist, and `rows_dropped` reports nothing. `draw()` also never appends to `contexts`/`text_attrs`, so drawn rows fall through to the default-pickable branch in [`_is_pickable()`](console_window/window.py:367) and lose their attributes on the next full redraw.
+
+**Fix:** clamp in `draw()` (or route it through `_add`) and let the same counter warn.
+
+### 3.3 🟡 Unreachable public surface (and dead code in the example)
+
+No consumer outside the test suite for:
+
+| Symbol | Where | Note |
+| --- | --- | --- |
+| `Theme.create_picker_screen()` | [`theme.py:187`](console_window/theme.py:187) | Untested; duplicates the sample app's theme screen; the factory reaches into `app.opts.theme` |
+| `ScreenStack.act_in()` | [`screens.py:181`](console_window/screens.py:181) | Duplicates what `perform_actions()` already does; `getattr` raises on a missing flag |
+| `ScreenStack.is_curr()` | [`screens.py:168`](console_window/screens.py:168) | Only reachable from `act_in()` |
+| `ConsoleWindow.set_pick_range()` | [`window.py:518`](console_window/window.py:518) | The `pick_range` feature's only public entry point; called only by [`tests/test_interactive.py`](tests/test_interactive.py:1) |
+| `BasicHelpScreen` | [`screens.py:227`](console_window/screens.py:227) | Exported in `__all__`, unused; the sample app writes its own help screen |
+| `OptionSpinner.add()` | [`spinner.py:163`](console_window/spinner.py:163) | Dead **and** broken (see below) |
+| `draw()` | [`window.py:749`](console_window/window.py:749) | Used only by [`tests/test_interactive.py`](tests/test_interactive.py:365) and [`tests/test_widechars.py`](tests/test_widechars.py:1) |
+| `add_fancy_header()` string path | [`window.py:685`](console_window/window.py:685) | The sample uses `add_header_line()`; only tests exercise the string path |
+| `demo_mode` / `set_demo_mode()` | [`window.py:325`](console_window/window.py:325) | Only tests toggle it; internal prompt/render code reads `opts.demo_mode` |
+
+`OptionSpinner.add()` truncates `ns.vals` and *then* slices it with the pre-truncation index ([`spinner.py:170`](console_window/spinner.py:170)), so `ns.comments` is always empty — the parameter it exists for is silently dropped. Dead code that cannot be right is worse than no code.
+
+The same is true of two example methods: `DemoApp.do_key()` ([`SampleApp.py:219`](SampleApp.py:219)) is never called (`main_loop` calls [`handle_key()`](SampleApp.py:184), which calls `spin.do_key` directly), and `ThemeScreen.theme_screen()` ([`SampleApp.py:512`](SampleApp.py:512)) is never called and, unlike the live [`theme_screen_ACTION()`](SampleApp.py:426) path and `Theme.create_picker_screen`'s `spin_theme_ACTION`, does not update `app.opts.theme`.
+
+**Fix:** delete what no consumer needs (these are pre-2.0 leftovers), or promote it deliberately: give each survivor a test and a README mention, and fix `OptionSpinner.add()` if it is retained.
+
+### 3.4 🟡 CI is green but shallow, and its inputs are unpinned
+
+[`.github/workflows/ci.yml`](.github/workflows/ci.yml:1) runs `pytest -q` on 3.10-3.13, `ruff check .` and `mypy`, installing `pytest`, `ruff` and `mypy` **unpinned** ([`ci.yml:22`](.github/workflows/ci.yml:22), [`ci.yml:36`](.github/workflows/ci.yml:36), [`ci.yml:50`](.github/workflows/ci.yml:50)) — a new tool release can break the build with no code change, and the same build cannot reproduce yesterday's result. There is no coverage gate and no `pylint` (so the 87% coverage and 9.92/10 figures in this audit are not protected by CI).
+
+### 3.5 🟢 `answer()` residual: class-wide retry budget and key draining
+
+[`answer()`](console_window/window.py:1167) now has one unambiguous meaning per outcome (`str` = submitted, `None` = user abort, `TerminalTooSmallError` = environment), and its recovery loop is bounded. Two narrow issues remain:
+
+* the budget is the class-wide `render_retry_seconds` ([`window.py:1193`](console_window/window.py:1193)) rather than a dialog-specific option;
+* [`_recover_from_resize()`](console_window/window.py:1522) still drains and **discards** every queued key ([`window.py:1528`](console_window/window.py:1528)).
+
+**Fix:** make the dialog retry budget configurable and preserve (or explicitly document the loss of) keys typed during recovery.
+
+### 3.6 🟢 Lint findings lack rationale
+
+`pylint` remains in the high 9s only because its warnings are few, not because they are annotated. Current examples: protected-member access ([`window.py:78`](console_window/window.py:78), [`window.py:84`](console_window/window.py:84), [`theme.py:171`](console_window/theme.py:171)), unused arguments ([`window.py:1742`](console_window/window.py:1742), [`backend.py:252`](console_window/backend.py:252), [`backend.py:278`](console_window/backend.py:278)), global statements and unused handler arguments in [`signals.py:19`](console_window/signals.py:19), a not-callable method ([`screens.py:67`](console_window/screens.py:67)), and broad exceptions in the example ([`SampleApp.py:150`](SampleApp.py:150), [`SampleApp.py:523`](SampleApp.py:523)). Each is plausibly deliberate, but none says why.
+
+**Fix:** add a short rationale comment or a scoped `# pylint: disable=...` at each site, so a future reader can distinguish intent from accident.
+
+## 4. Prioritized recommendations
+
+**P1 — robustness and surface**
+
+1. Clamp `draw()` to the pad and route its overflow through the existing counter (§3.2).
+2. Delete or promote the unreachable API (§3.3), fix or remove `OptionSpinner.add()`, and delete `DemoApp.do_key()` and `ThemeScreen.theme_screen()`.
+3. Pin CI tool versions and add a coverage floor (even a low one, e.g. `--cov-fail-under=80`) so the suite cannot silently shrink (§3.4).
+
+**P2 — honesty and hygiene**
+
+4. Make the active theme per-window (or document one-theme-per-process), and capture/restore the host SIGINT handler or expose a reset (§3.1).
+5. Make the dialog retry budget configurable and stop discarding keys during resize recovery (§3.5).
+6. Add rationale comments or scoped disables for the remaining `pylint` findings (§3.6).
+
+## 5. What is genuinely good (protect it)
+
+* **The test suite is fast and genuinely TTY-free** (268 tests in 1.5 s) and includes headless smoke tests for the example ([`tests/test_sample_app.py`](tests/test_sample_app.py:1)), the interactive core ([`tests/test_interactive.py`](tests/test_interactive.py:1)) and the overflow contract ([`tests/test_overflow.py`](tests/test_overflow.py:1)).
+* **The overflow contract for `_add()` is a model of restraint** — counted, warned once, non-fatal for users, fatal in the project's own suite ([`pyproject.toml:49`](pyproject.toml:49)), and it paid for itself in the same commit by finding the sample app's clipped help screen.
+* **The `prompt()` loop is decomposed and guarded** — the one 160-line, complexity-43 function is now a 12-line intake loop over small helpers (worst `prompt`-family helper: 4), and `C901` at a ratcheted threshold of 12 prevents a new monolith ([`pyproject.toml:62`](pyproject.toml:62)).
+* **`textwidth` and `geometry` are pure and near-fully covered** (95%/100%) — the right place for the fiddly math.
+* **`Context`'s near-miss warning** ([`context.py:30`](console_window/context.py:30)) and **`OptionSpinner`'s conflict detection** ([`spinner.py:127`](console_window/spinner.py:127), [`spinner.py:142`](console_window/spinner.py:142)) turn silent misconfiguration into loud `ValueError`/warning at the exact point of the mistake.
+* **Packaging is correct**: flit module config, static metadata, `__all__` matching the re-exports, and a `runner` that executes the example as `__main__` without an installed package.
+
+## 6. Reproduction
+
+```bash
+python3 -m ruff check .
+python3 -m pytest -q
+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/CHANGELOG.md

@@ -0,0 +1,285 @@
+# Changelog
+
+All notable changes to `console-window` are documented here.
+This project follows [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- `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
+  in CI runs it on every push/PR. Ruff's `ANN` rules were already enforcing
+  annotation *presence*; this enforces that the annotations are true
+  (AUDIT.md §3.4).
+- `[project.urls]` in `pyproject.toml` (Homepage / Repository / Issues /
+  Changelog) so published package metadata carries project links.
+- `ConsoleWindow(..., singleton=True)` restores the historical process-wide
+  window model for applications that relied on it: `static_scr`/`static_win`
+  are populated, every window shares one process screen and backend, and the
+  unbound `ConsoleWindow.stop_curses()` tears it down. The first successful
+  construction latches the mode; constructing another window with a different
+  `singleton` value raises `AssertionError`. Pass `singleton=False` for
+  independent per-instance screens and teardown (the test suite does).
+- `ConsoleWindow.rows_dropped`, counting the rows `add_body()`/`add_header()`
+  discard once that pad has reached `opts.body_rows` / `opts.head_rows`. The
+  first discarded row of each fill episode also emits a `UserWarning` naming the
+  pad and the option to raise. Overflow previously left no trace, so an
+  under-sized pad showed up only as missing content. The behaviour is
+  deliberately non-fatal: the excess is still discarded and the app keeps
+  running, `-W error::UserWarning` turns it into a hard failure for anyone who
+  wants that, and `clear()` re-arms the warning for the next fill.
+- A headless harness for the interactive core: `HeadlessBackend.queue_keys()`
+  feeds ordered key codes to the screen's `getch()`, and the new
+  `tests/test_interactive.py` (43 tests) drives `prompt()` and its navigation,
+  `render()`/`draw()`, the `answer()` dialog and the resize-recovery path
+  without a TTY. Coverage of `window.py` rises from 55% to 84% (missing
+  statements 444 → 161), so the half of the engine users actually feel is now
+  smoke-tested in CI (AUDIT.md §3.2).
+
+### Changed
+- 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
+  at the top of `pyproject.toml` is gone.
+- `OptionSpinner.get_value()` is now a pure read: its `coerce` parameter is
+  gone and initialisation moved to the explicit `OptionSpinner.normalize(attr)`,
+  which `_register()` calls. Apps that read option values through
+  `get_value()` are unaffected because `add_key()` already normalizes the value
+  during registration; code that passed `coerce=True` directly should call
+  `normalize()` instead (AUDIT.md §3.12).
+- Raised the minimum supported Python to **3.10** (was 3.8): `requires-python =
+  ">=3.10"`, the Ruff `target-version` is now `py310`, and the CI matrix drops
+  the 3.8/3.9 legs. The 3.8 floor was never real — [`backend.py`](console_window/backend.py:35)
+  calls `curses.set_escdelay()`, which is new in 3.9, so every
+  `ConsoleWindow()` raised `AttributeError` on 3.8. 3.10 is a deliberate floor
+  rather than the bare 3.9 that `set_escdelay` would have permitted.
+- Renamed `ConsoleWindowDemo.py` to `SampleApp.py`: the old name collided with
+  the library's own `set_demo_mode()` feature. Updated [`runner`](runner:1), the
+  README, the ruff per-file-ignores and the headless smoke tests
+  (`tests/test_sample_app.py`) to match. The classes inside are still named
+  `DemoApp`/`DemoScreen`.
+
+### Fixed
+- Hygiene debt from AUDIT.md §3.14: removed blank lines inside the
+  `index_at_cell()`/`answer()` signatures and the commented-out assignment in
+  `fix_positions()`; replaced `render()`'s `print()`/`except Exception` failure
+  path with `logging` and `curses.error`; made `_BACKSPACE_KEYS` a single
+  module constant; moved `ScreenStack`'s `SimpleNamespace` import to module
+  level; stored navigation help as `NAV_KEY_LINES` so indentation cannot alter
+  it; bounded `_NoopSurface.calls` to `MAX_CALLS`; and restored the hardware
+  cursor in `CursesBackend.stop()`.
+- The window no longer uses identity or sentinel tricks to decide what it is
+  drawing. `_add()` takes an explicit `is_body` keyword from
+  `add_header()`/`add_body()` instead of comparing `id(ns)` with `id(self.body)`,
+  and `_warn_rows_dropped()` receives the pad name. The undocumented
+  `last_pick_pos == -2` "clear every row" sentinel is replaced by the one-shot
+  `_pick_clear_pending` flag, which `set_pick_mode()`/`set_pick_range()` set and
+  `highlight_picked()` consumes; `last_pick_pos` is now only a row index or `-1`.
+  A range change still repaints the picked row when its position is unchanged
+  (AUDIT.md §3.13).
+- The help screen no longer relies on `assert` to guard option rendering.
+  `OptionSpinner._write_option_body()` now renders a dim `<unset: 'attr'>`
+  placeholder when an application has deleted or cleared a registered option,
+  so the row shows the same thing under `python -O` instead of falling through
+  to `None` (AUDIT.md §3.12).
+- `ConsoleWindowOpts` now rejects unknown option names with a `TypeError`
+  instead of silently ignoring them. A typo such as
+  `ConsoleWindowOpts(body_row=5000)` used to leave `body_rows` at its default
+  and surface only later as discarded pad rows; construction now fails, and a
+  `difflib` suggestion points at the intended name (`body_rows`). Multiple
+  unknown keys are all reported (AUDIT.md §3.11).
+- `answer()` no longer loops forever on `curses.error`, and it no longer uses
+  `None` for both "user aborted" and "terminal too small". The recovery loop is
+  bounded by `render_retry_seconds` and then re-raises; both too-small paths
+  raise `TerminalTooSmallError` (ESC on the mid-dialog too-small notice still
+  returns `None`, since that is a real abort). The dialog timeout is now
+  restored in a `finally`, so it is also restored when `answer()` raises.
+- Annotations that `mypy` exposed: `fix_positions()` is declared `-> int`
+  (it returns `indent` and the caller uses it), `_draw_line_with_attrs()` and
+  `_draw_plain_line()` accept `attrs: list | None`, `pick_range` is typed as
+  `list[int] | tuple[int, int] | None`, and `draw()` accepts `str | bytes` to
+  match its decode path. `ConsoleWindowOpts` attributes now have explicit types
+  instead of being `object` values from `**kwargs`, and the full screen/pad API
+  is described by the new `CursesSurface` protocol rather than `object`.
+- Ctrl-C termination is now a process-lifetime latch. The first `ConsoleWindow`
+  created with `ctrl_c_terminates=True` sets SIGINT to the default handler and
+  no later window can install the key-delivery handler, even after that window
+  stops. Previously `teardown_ctrl_c()` decided from whichever policy happened to
+  be current, so window A (`False`, handler installed) → window B (`True`) →
+  stop A left A's handler installed and Ctrl-C could no longer terminate. The
+  latch is deliberately one-way: `ctrl_c_terminates=False` applies only while no
+  terminating window has existed in the process (AUDIT.md §3.6).
+- Aborting a `prompt`-genre spinner option (ESC in the `answer()` dialog) no
+  longer wipes the stored value. `OptionSpinner.do_key()` wrote whatever
+  `answer()` returned straight onto the attribute, and an aborted dialog returns
+  `None`, so cancelling blanked the setting and the next read coerced it back to
+  `''`. The prompt branch now treats `None` as "no change" and returns without
+  touching the attribute (AUDIT.md §3.7).
+- `ConsoleWindow.alert()` now actually scrolls. It used to build a pad sized to
+  the whole message but always refresh it at offset 0, so content taller than the
+  box was silently unreachable despite the "scrollable if needed" comment. The
+  content is now reachable with `j`/`k`, the arrow keys, PageUp/PageDown (and
+  Ctrl-B/Ctrl-F/Space) and Home/End, and the box's left border shows `▲`/`▼`
+  markers when content extends past the fold. The `_height`/`_width` parameters,
+  previously accepted and ignored, now cap the (centred) box; passing `None`
+  keeps the previous full-box, 1-cell-margin geometry.
+- `alert()` no longer reaches around the backend seam: it builds its content pad
+  through `RenderBackend.newpad()` and drives its own key loop rather than calling
+  module-level `curses.newpad()`/`curses.newwin()`/`Textbox`. It therefore runs
+  under `HeadlessBackend` and is covered by the new `alert()` tests in
+  `tests/test_interactive.py`; the `Textbox` monkeypatch in `tests/test_dialogs.py`
+  is gone, along with the now-unused `_textbox_edit_on_enter()` helper (AUDIT.md
+  §3.3).
+- `answer()`, `flash()` and the shared render/dialog helpers no longer call the
+  process-global `curses.doupdate()`/`curs_set()`/`update_lines_cols()`/
+  `is_term_resized()` directly. Four matching methods were added to
+  `RenderBackend`, implemented by `CursesBackend` (delegating to curses) and
+  `HeadlessBackend` (recording no-ops), so the dialogs are backend-driven end to
+  end and the `curs_set`/`doupdate` monkeypatches are gone from `tests/test_dialogs.py`
+  (AUDIT.md §3.3).
+- `ConsoleWindow` startup and `Theme.set()` now (re)initialise the same semantic
+  colour pairs from the single `Theme.SEMANTIC_PAIRS` constant. Startup previously
+  omitted `OLD_SUCCESS`, so it rendered on an uninitialised pair (effectively pair
+  0) until the user changed theme. The magic pair id `8` is now the named
+  `Theme.DEFAULT_BG`. `tests/test_theme.py` pins the shared list, the historic id
+  and that both init paths agree (AUDIT.md §3.9).
+
+### Removed
+- `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
+  `render(redraw=True)`, `Ctrl-C` as an application key, large-body stress and
+  `ConsoleWindow.primary_window()` recovery — were folded into `SampleApp.py`,
+  which is now covered by headless smoke tests (`tests/test_sample_app.py`).
+- All docstrings from the package, the test suite, the demo and the `runner`
+  script (305 in total, across 29 files). Nothing consumed them via `__doc__`,
+  `inspect.getdoc()` or `help()` (verified by grep), so runtime behaviour and the
+  public API are unchanged; statement order, bodies and the blank-line layout
+  around definitions were preserved.
+- The `DWIPE_THEME` environment variable. `Theme.set()` no longer exports it and
+  the startup path reads `Theme.get_current()` instead of `os.environ`, making
+  `Theme` state the single source of truth. The library no longer namespaces its
+  config under a downstream app's name (`dwipe` never read the variable) and no
+  longer leaks the theme value into child processes via the inherited
+  environment.
+- `console_window/ConsoleWindow.py`, the compatibility facade. Its filename
+  shadowed the `ConsoleWindow` class and violated PEP 8 (ruff `N999`). The
+  public API is unchanged for package-root imports (`from console_window import
+  ...`), which is the documented style; only the legacy
+  `from console_window.ConsoleWindow import ...` path is gone. The interactive
+  self-test moved to `python -m console_window._selftest`.
+
+### Fixed
+- Scrolling could not reach non-pickable `DECOR` rows that sit past the last
+  pickable row (or before the first one).  In pick mode the frame's
+  pick-visibility clamp in [`_adjust_scroll_for_abut()`](console_window/window.py:862)
+  reset `scroll_pos` back to `pick_pos` every frame, so the SampleApp's `z`
+  "stress" mode created 2000 filler rows that were unreachable — the view showed
+  the last pickable row plus one screen of filler and the scroll indicator sat
+  near the start.  Movement is now allowed to scroll past the pick (a new
+  `free_scroll` state) while the pick can find no pickable row in the requested
+  direction; the clamp is skipped in that state and restored as soon as a real
+  pick move resynchronises the view.  The blocked-move scroll amount is now the
+  *requested* delta rather than a single row, so page keys and `HOME`/`END`
+  traverse a `DECOR` block too, and the scroll indicator follows the viewport
+  while free-scrolling instead of the parked pick.
+- `SampleApp.py` asked for `head_rows=4`, but the help screen's nav-key block is
+  five header rows, so the last line was being clipped in silence. Raised to 8,
+  and the pad-sizing comment now records what each pad has to hold. The bug was
+  found by the overflow signal above, which this project's own suite now
+  enforces (`filterwarnings = ["error::UserWarning"]` in `pyproject.toml`) so
+  that neither the sample app nor the library's own helpers can quietly regress
+  that way again.
+
+## [2.0.1]
+
+Internal overhaul — modularization and tests. The public API is unchanged and
+fully backward compatible (`from console_window import ...` and
+`from console_window.ConsoleWindow import ...` both continue to work).
+
+### Added
+- Unit-test suite (`tests/`, TTY-free) covering scroll/pick geometry,
+  `IncrementalSearchBar` / `InlineConfirmation`, `OptionSpinner` scope
+  subtraction, public-API compatibility, the `answer()`/`alert()` dialog fixes,
+  `set_demo_mode()` toggle/state handling, `render()`'s retry cap, and the
+  non-destructive `flash()` behaviour (`tests/test_flash.py`).
+- `ConsoleWindow.flash_repaint` (repaint the underlying screen when `flash()`
+  ends) and `ConsoleWindow.flash_poll_ms` (flash key-poll interval).
+- `console_window.textwidth` — a stdlib-only (`unicodedata`-based) display-cell
+  width toolkit (`char_width`, `string_width`, `truncate`, `ljust`/`rjust`,
+  `cell_to_index`, `wrap_ranges`/`wrap_position`/`index_at_cell`, `wrap`),
+  plus `tests/test_textwidth.py` and `tests/test_widechars.py`.
+- `console_window.geometry` — pure scroll/pick math extracted for testing:
+  `cook_abut`, `compute_abut`, `calc_indicator`, `scroll_indicator_row`,
+  `scroll_indicator_col`, `count_pickable_rows`, `find_pickable`.
+- `console_window.backend` — a `RenderBackend` abstraction with `CursesBackend`
+  (real terminal) and `HeadlessBackend` (in-memory), plus `tests/test_backend.py`.
+- `console_window.__version__`.
+- Explicit `__all__` in the package root and compatibility module.
+- `[tool.pytest.ini_options]` in `pyproject.toml`.
+- GitHub Actions CI (`.github/workflows/ci.yml`) running the TTY-free suite on
+  Python 3.8–3.13, plus a Ruff lint job backed by a `[tool.ruff]` config in
+  `pyproject.toml`.
+- Type annotations across the public API (every package module now uses
+  `from __future__ import annotations`), enforced for the package by Ruff's
+  `ANN` rules.
+
+### Changed
+- Split the 3,815-line `console_window/ConsoleWindow.py` into focused modules:
+  `window.py`, `theme.py`, `context.py`, `opts.py`, `widgets.py`, `spinner.py`,
+  `screens.py`, `keys.py`, `signals.py`, `geometry.py`; `ConsoleWindow.py` is now
+  a thin compatibility facade.
+- Theme state unified into `Theme._current` (via `Theme.set_active()`); removed
+  the split between `_current` and `CURRENT_THEME` that made
+  `Theme.get_current()` return `None` after startup.
+- SIGINT handling moved to an explicit `console_window.signals` policy API;
+  removed the action-at-a-distance rebinding of module-level functions.
+- `set_demo_mode()` now tests the resulting state rather than the argument.
+- Removed the process-wide `ConsoleWindow.static_scr`/`static_win` singletons:
+  live windows are tracked in a weak-reference registry, teardown is per-instance
+  (`stop_curses()`), `stop_all()` is the single `atexit` hook, and `Theme.set()`
+  broadcasts to every live window via `_apply_default_colors()`. Multiple windows
+  may now coexist, and one may be constructed without a terminal by passing
+  `backend=HeadlessBackend()` to the constructor.
+- Every package module opts into PEP 563 (`from __future__ import annotations`)
+  so the modern `X | None` annotations remain valid on Python 3.8.
+- `add_fancy_header()` regex logic extracted into named helpers.
+
+### Fixed
+- `answer()` now records the screen read timeout in effect before the dialog and
+  restores that value on every exit path (submit, TAB, ESC, ESC-ESC, too-small
+  abort) instead of resetting to the class default `ConsoleWindow.timeout_ms`.
+- `alert()` recomputes `self.rows`/`self.cols` from `getmaxyx()` before drawing,
+  so a resize immediately before the call no longer causes a misdraw.
+- `flash()` is now non-destructive and interruptible: it polls for a key
+  (`flash_poll_ms`) instead of `time.sleep`ing, so it can be dismissed early —
+  and any key pressed is preserved in `pending_keys` for the next `prompt()`
+  rather than being swallowed. A resize while the message is up redraws it, and
+  on exit the underlying screen is repainted from the pads (`flash_repaint`)
+  instead of being left blank; the pre-flash read timeout is restored on every
+  exit path.
+- Width arithmetic is now **display-cell aware** (wide CJK/emoji = 2 cells,
+  combining marks/ZWJ = 0) throughout the render pipeline: `_add`, `draw`,
+  `highlight_picked`/`_draw_line_with_attrs` (highlight columns map to
+  code-point indices), `add_fancy_header`, `flash`, `alert`, and the `answer()`
+  display/editor (cell-accurate wrapping and cursor placement) — fixing
+  misalignment for the wide characters the demo already uses.
+- `render()` now bounds its transient-error retry loop by wall-clock time
+  (`ConsoleWindow.render_retry_seconds`, default 2 s) instead of a fixed 128
+  iterations, so a reproducible `curses.error` aborts quickly with the
+  diagnostic dump rather than freezing the UI for ~20 s.
+- Demo: the settings spinner keys (`v` view mode, `s` sort, `t` theme) now also
+  work while the HELP screen is open — they are scoped to include `HELP_ST`.
+  (Scoping logic itself was unchanged by the refactor; this was a demo-scope
+  issue.)
+- `ScreenStack.__init__(screen_objects=...)` annotated as `dict | None` (fixes the
+  implicit-`Optional` finding, Ruff RUF013); removed redundant `int(round(...))`
+  casts (RUF046) and trailing whitespace in `widgets.py` (W291); dropped an
+  unused local in `tests/test_spinner.py` (F841).
+- Removed retired `put_body()` references (docstring + `__main__` self-test now
+  use `add_body()`).
+- `Development Status` classifier aligned with the release; version bumped to
+  `2.0.1`.
+
+[2.0.1]: https://github.com/joedefen/console-window