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

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

@@ -38,6 +38,19 @@ This project follows [Semantic Versioning](https://semver.org/).
   smoke-tested in CI (AUDIT.md §3.2).
 
 ### Changed
+- 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: console-window
-Version: 2.0.0.2
+Version: 2.0.0.3
 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`.
@@ -125,9 +125,9 @@ demonstrates:
 * **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 +145,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()

{console_window-2.0.0.2 → console_window-2.0.0.3}/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`.
@@ -106,9 +106,9 @@ demonstrates:
 * **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 +126,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()

{console_window-2.0.0.2 → console_window-2.0.0.3}/SampleApp.py

@@ -63,12 +63,9 @@ class DemoApp:
         # Configure console window
         win_opts = ConsoleWindowOpts(
             head_line=True,
-            # Pad capacity: add_body()/add_header() discard rows past this (they
-            # are counted in ConsoleWindow.rows_dropped, and the first one of each
-            # fill is warned about), so each pad must be big enough for what the
-            # screens actually draw.
-            body_rows=4000,  # the 'z' stress mode appends 2000 filler rows
-            head_rows=8,  # the help screen's nav-key block is 5 header rows
+            # No row sizing needed: the pads are viewport-sized and rows live in
+            # the model, so the 'z' stress mode's 2000 filler rows need no
+            # option.  max_rows is only a safety ceiling (32767 by default).
             min_cols_rows=(60,10),
             pick_attr=cs.A_REVERSE,
             # Ctrl-C arrives as an ordinary key code (bound to 'quit' below)

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

{console_window-2.0.0.2 → console_window-2.0.0.3}/console_window/backend.py

@@ -26,6 +26,9 @@ class CursesSurface(Surface, Protocol):
     def clear(self) -> None:
         ...
 
+    def erase(self) -> None:
+        ...
+
     def addstr(self, *args: object) -> None:
         ...
 

{console_window-2.0.0.2 → console_window-2.0.0.3}/console_window/opts.py

@@ -8,8 +8,8 @@ from typing import Any, Callable
 class ConsoleWindowOpts:
     __slots__ = ['answer_show_redraws', 'body_cols', 'body_rows', 'ctrl_c_terminates',
                  'demo_mode', 'dialog_abort', 'dialog_return', 'head_line', 'head_rows',
-                 'keys', 'min_cols_rows', 'mod_pick', 'pick_attr', 'pick_mode', 'pick_range',
-                 'pick_size', 'relax_handled_keys', 'return_if_pos_change',
+                 'keys', 'max_rows', 'min_cols_rows', 'mod_pick', 'pick_attr', 'pick_mode',
+                 'pick_range', 'pick_size', 'relax_handled_keys', 'return_if_pos_change',
                  'single_cell_scroll_indicator', 'strip_attrs_in_pick_mode']
 
     # Explicit attribute types: assignments below come from **kwargs, so without
@@ -18,13 +18,14 @@ class ConsoleWindowOpts:
     # are checked.
     answer_show_redraws: bool
     body_cols: int
-    body_rows: int
+    body_rows: int | None  # advisory hint only; see max_rows
     ctrl_c_terminates: bool
     demo_mode: bool
     dialog_abort: str | None
     dialog_return: str
     head_line: bool
-    head_rows: int
+    head_rows: int | None  # advisory hint only; see max_rows
+    max_rows: int | None
     keys: set | list | None
     min_cols_rows: tuple[int, int]
     mod_pick: Callable[[str], str] | None
@@ -49,8 +50,12 @@ class ConsoleWindowOpts:
                 f'ConsoleWindowOpts() got unknown option(s): {", ".join(details)}.')
 
         self.head_line = kwargs.get('head_line', True)
-        self.head_rows = kwargs.get('head_rows', 50)
-        self.body_rows = kwargs.get('body_rows', 200)
+        # Row counts are hints, not limits: the pads are viewport-sized, so an
+        # app never has to pre-size storage.  max_rows is the only ceiling and
+        # applies to both namespaces; pass None to disable it entirely.
+        self.head_rows = kwargs.get('head_rows')
+        self.body_rows = kwargs.get('body_rows')
+        self.max_rows = kwargs.get('max_rows', 32767)
         self.body_cols = kwargs.get('body_cols', 200)
         self.keys = kwargs.get('keys')
         self.pick_mode = kwargs.get('pick_mode', False)

{console_window-2.0.0.2 → console_window-2.0.0.3}/console_window/window.py

@@ -10,6 +10,7 @@ import atexit
 import curses
 import itertools
 import logging
+import sys
 import time
 import warnings
 import weakref
@@ -74,6 +75,11 @@ _SINGLETON_MODE: bool | None = None
 # window, so creating multiple windows does not stack up duplicate handlers.
 _ATEXIT_REGISTERED = False
 
+# Sentinel for "no content-row ceiling" (opts.max_rows is None).  It only has to
+# be larger than any row index a process could allocate; it is never passed to
+# curses, because the pads themselves are viewport-sized.
+_NO_ROW_LIMIT = sys.maxsize
+
 
 def _register_window(win: ConsoleWindow) -> None:
     key = next(_WINDOW_IDS)
@@ -205,8 +211,8 @@ class ConsoleWindow:
             )
             self.opts = ConsoleWindowOpts(
                 head_line=head_line if head_line is not None else True,
-                head_rows=head_rows if head_rows is not None else 50,
-                body_rows=body_rows if body_rows is not None else 200,
+                head_rows=head_rows,
+                body_rows=body_rows,
                 body_cols=body_cols if body_cols is not None else 200,
                 keys=keys,
                 pick_mode=pick_mode if pick_mode is not None else False,
@@ -244,38 +250,46 @@ class ConsoleWindow:
         # they ran, instead of assuming the class default.
         self._scr_timeout_ms = ConsoleWindow.timeout_ms
 
+        # Scheme B: the pads are viewport-sized blit buffers, not content
+        # stores.  `rows` below is the enforced content ceiling (opts.max_rows,
+        # or _NO_ROW_LIMIT when that option is None) and `hint_rows` is the
+        # advisory opts.head_rows/opts.body_rows value, kept for compatibility
+        # and introspection.  pad_rows/pad_cols track the actual allocation.
+        # _sync_pad_geometry() creates/sizes the pads once the terminal
+        # dimensions are known (calc() runs at the end of __init__), so no
+        # oversized placeholder is ever allocated.
+        row_limit = (self.opts.max_rows if self.opts.max_rows is not None
+                     else _NO_ROW_LIMIT)
         self.head = SimpleNamespace(
-            pad=self._backend.newpad(self.opts.head_rows, self.opts.body_cols),
-            rows=self.opts.head_rows,
+            pad=None,
+            rows=row_limit,  # enforced ceiling (NOT the pad height)
+            hint_rows=self.opts.head_rows,
             cols=self.opts.body_cols,
+            pad_rows=0,
+            pad_cols=0,
             row_cnt=0,  # no. head rows added
             texts = [],
             text_attrs = [],  # run-length encoded: [(attr, count), ...] per line
             contexts = [],  # Context object per line (or None)
+            drawn = {},  # row -> [(x, text, attr), ...] written by draw()
             view_cnt=0,  # no. head rows viewable (NOT in body)
-            rows_dropped=0,  # rows discarded because the pad was full (see _add)
+            rows_dropped=0,  # rows discarded because the content cap was reached
         )
         self.body = SimpleNamespace(
-            pad = self._backend.newpad(self.opts.body_rows, self.opts.body_cols),
-            rows= self.opts.body_rows,
+            pad = None,
+            rows= row_limit,  # enforced ceiling (NOT the pad height)
+            hint_rows= self.opts.body_rows,
             cols= self.opts.body_cols,
+            pad_rows=0,
+            pad_cols=0,
             row_cnt = 0,
             texts = [],
             text_attrs = [],  # run-length encoded: [(attr, count), ...] per line
             contexts = [],  # Context object per line (or None)
-            rows_dropped = 0,  # rows discarded because the pad was full (see _add)
+            drawn = {},  # row -> [(x, text, attr), ...] written by draw()
+            rows_dropped = 0,  # rows discarded because the content cap was reached
         )
 
-        # Apply theme background to pads
-        if self._backend.has_colors():
-            theme = Theme.THEMES.get(Theme.get_current(), Theme.THEMES['default'])
-            if 'default_fg' in theme and 'default_bg' in theme:
-                default_fg = theme['default_fg']
-                default_bg = theme['default_bg']
-                if default_fg != -1 or default_bg != -1:
-                    self.head.pad.bkgd(' ', self._backend.color_pair(Theme.DEFAULT_BG))
-                    self.body.pad.bkgd(' ', self._backend.color_pair(Theme.DEFAULT_BG))
-
         # Register this instance so theme broadcasts and process teardown reach
         # it.  Singleton mode also republishes the old ``static_win`` pointer.
         _register_window(self)
@@ -311,7 +325,7 @@ class ConsoleWindow:
         self.passthrough_mode = False  # When True, all printable keys pass through
         self.relax_handled_keys = self.opts.relax_handled_keys  # When True, pass non-nav keys without checking handled_keys
         self._set_screen_dims()
-        self.calc()
+        self.calc()  # also creates the viewport-sized pads
 
     def set_handled_keys(self, keys: object) -> None:
         if hasattr(keys, 'keys'):
@@ -355,12 +369,44 @@ class ConsoleWindow:
     def get_pad_width(self) -> int:
         return min(self.cols-1, self.body_cols)
 
+    @property
+    def max_rows(self) -> int | None:
+        """The enforced per-namespace content ceiling (None = unlimited)."""
+        return self.opts.max_rows
+
+    def _apply_pad_theme(self, pad: CursesSurface) -> None:
+        # A freshly created pad has no background, so re-apply the theme colour
+        # after every reallocation; otherwise a resize leaves the new pad on the
+        # terminal default instead of the configured background.
+        if not self._backend.has_colors():
+            return
+        theme = Theme.THEMES.get(Theme.get_current(), Theme.THEMES['default'])
+        default_fg = theme.get('default_fg', -1)
+        default_bg = theme.get('default_bg', -1)
+        if default_fg != -1 or default_bg != -1:
+            pad.bkgd(' ', self._backend.color_pair(Theme.DEFAULT_BG))
+
+    def _sync_pad_geometry(self) -> None:
+        # Viewport-sized pads: height is the terminal height and width is the
+        # blittable width (cols-1 with the last column reserved), so neither
+        # content length nor opts.body_rows has any effect on pad memory or on
+        # pad clear()/erase() cost.  Called from calc(), i.e. once per frame,
+        # but it only allocates when the terminal dimensions actually changed.
+        height = max(1, self.rows)
+        width = max(1, self.cols - 1)
+        for ns in (self.head, self.body):
+            if ns.pad_rows == height and ns.pad_cols == width:
+                continue
+            ns.pad = self._backend.newpad(height, width)
+            ns.pad_rows, ns.pad_cols = height, width
+            self._apply_pad_theme(cast(CursesSurface, ns.pad))
+
     @property
     def rows_dropped(self) -> int:
-        # Rows handed to add_body()/add_header() after that pad had filled up.
-        # The pads are fixed-size (opts.body_rows/head_rows), so a caller that
-        # adds more rows than that used to lose the excess in silence; this
-        # counter, plus the one-shot warning in _add(), is how that is now
+        # Rows handed to add_body()/add_header() after that namespace reached
+        # opts.max_rows (the only ceiling; None disables it).  body_rows and
+        # head_rows are advisory hints and never drop anything.  This counter,
+        # plus the one-shot warning in _add(), keeps a runaway append loop
         # observable without the library deciding to abort the app.
         return self.head.rows_dropped + self.body.rows_dropped
 
@@ -612,6 +658,7 @@ class ConsoleWindow:
 
     def calc(self) -> bool:
         same = self._set_screen_dims()
+        self._sync_pad_geometry()
         self.head.view_cnt = min(self.rows - self.hor_line_cnt, self.head.row_cnt)
         self.scroll_view_size = self.rows - self.head.view_cnt - self.hor_line_cnt
         self.max_scroll_pos = max(self.body.row_cnt - self.scroll_view_size, 0)
@@ -621,41 +668,47 @@ class ConsoleWindow:
     def _add(self, ns: SimpleNamespace, text: str, attr: int | None = None,
              resume: bool = False, context: Context | None = None,
              *, is_body: bool = False) -> None:
-        if ns.row_cnt < ns.rows:
-            row = max(ns.row_cnt - (1 if resume else 0), 0)
-            if attr is None:
-                attr = curses.A_NORMAL
-            # Apply stripping logic if needed
-            if is_body and self.pick_mode and self.opts.strip_attrs_in_pick_mode:
-                attr = curses.A_NORMAL
-
-            if resume:
-                _, x = ns.pad.getyx()
-                cols = self.get_pad_width() - x
-                if cols > 0:
-                    actual_text = textwidth.truncate(text, cols)
-                    ns.pad.addstr(actual_text, attr)
-                    ns.texts[row] += actual_text
-                    # Append to existing attrs list (counts are code points)
-                    if row < len(ns.text_attrs):
-                        ns.text_attrs[row].append((attr, len(actual_text)))
-                    # Note: context not updated on resume
-            else:
-                # Truncate to the single "usable width" (get_pad_width), matching
-                # the resume branch, draw() and highlight_picked() — not the raw
-                # terminal width, which is one column wider and uncapped by the pad.
-                actual_text = textwidth.truncate(text, self.get_pad_width())
-                ns.pad.addstr(row, 0, actual_text, attr)
-                ns.texts.append(actual_text)  # text only history
-                ns.text_attrs.append([(attr, len(actual_text))])  # run-length encoded
-                ns.contexts.append(context)  # Context metadata (or None)
-                ns.row_cnt += 1
-        else:
+        # Model-only: the row is stored here and painted by _paint_body()/
+        # _paint_head() on the frames where it is actually visible.  `ns.rows`
+        # is ops.max_rows (or the no-limit sentinel), not the pad height and not
+        # the advisory hint, so nothing is dropped unless a ceiling was set.
+        if ns.row_cnt >= ns.rows:
             self._warn_rows_dropped(ns, 'body' if is_body else 'head')
+            return
+
+        if attr is None:
+            attr = curses.A_NORMAL
+        # Apply stripping logic if needed
+        if is_body and self.pick_mode and self.opts.strip_attrs_in_pick_mode:
+            attr = curses.A_NORMAL
+
+        if resume and ns.row_cnt > 0 and ns.texts:
+            row = min(ns.row_cnt - 1, len(ns.texts) - 1)
+            # The old code read the pad cursor with getyx(); the model already
+            # records the row's text, so its display width is the resume column.
+            x = textwidth.string_width(ns.texts[row])
+            cols = self.get_pad_width() - x
+            if cols > 0:
+                actual_text = textwidth.truncate(text, cols)
+                ns.texts[row] += actual_text
+                # Append to existing attrs list (counts are code points)
+                if row < len(ns.text_attrs):
+                    ns.text_attrs[row].append((attr, len(actual_text)))
+                # Note: context not updated on resume
+        else:
+            # Truncate to the single "usable width" (get_pad_width), matching
+            # the resume branch, draw() and highlight_picked() — not the raw
+            # terminal width, which is one column wider and uncapped by the pad.
+            actual_text = textwidth.truncate(text, self.get_pad_width())
+            ns.texts.append(actual_text)  # text only history
+            ns.text_attrs.append([(attr, len(actual_text))])  # run-length encoded
+            ns.contexts.append(context)  # Context metadata (or None)
+            ns.row_cnt += 1
 
     def _warn_rows_dropped(self, ns: SimpleNamespace, which: str) -> None:
-        # The pad is full, so this row is discarded (as it always was).  Counted
-        # always, warned about once per fill episode -- clear() resets both, so
+        # The content cap is reached, so this row is discarded (as it always
+        # was when the pad was the storage).  Counted always, warned about once
+        # per fill episode -- clear() resets both, so
         # a bulk overflow produces exactly one message instead of one per row --
         # and never fatal: the app keeps running and can inspect
         # ConsoleWindow.rows_dropped.  A caller that would rather treat this as
@@ -665,10 +718,10 @@ class ConsoleWindow:
         if ns.rows_dropped != 1:
             return
         warnings.warn(
-            f'console-window: the {which} pad is full ({ns.rows} rows), so '
-            f'further {which} rows are being discarded.  Raise the '
-            f'{which}_rows option (ConsoleWindowOpts({which}_rows=...)) or add '
-            f'fewer rows per frame.',
+            f'console-window: the {which} content limit is full ({ns.rows} '
+            f'rows), so further {which} rows are being discarded.  Raise '
+            f'ConsoleWindowOpts(max_rows=...) or pass max_rows=None to remove '
+            f'the ceiling entirely.',
             # warn() <- _warn_rows_dropped() <- _add() <- add_body()/add_header()
             # <- caller, so 4 is the application's own line.
             stacklevel=4,
@@ -748,6 +801,10 @@ class ConsoleWindow:
 
     def draw(self, y: int, x: int, text: str | bytes, text_attr: int | None = None,
              width: int | None = None, leftpad: bool = False, header: bool = False) -> None:
+        # Scheme B keeps y a *content* row, exactly as before; the row is
+        # painted at y - scroll_pos by _paint_body() on the frames where it is
+        # visible.  The attribute has no home in texts[], so the span is also
+        # recorded in ns.drawn and replayed over the row's normal attribute runs.
         ns = self.head if header else self.body
         text_attr = text_attr if text_attr else curses.A_NORMAL
         if y < 0 or y >= ns.rows or x < 0 or x >= ns.cols:
@@ -762,21 +819,16 @@ class ConsoleWindow:
                 return
             # Pad/truncate to exactly `width` display cells (wide-char safe).
             uni = textwidth.rjust(uni, width) if leftpad else textwidth.ljust(uni, width)
-            text = uni.encode('utf-8')
-        else:
-            text = uni.encode('utf-8')
 
-        try:
-            while y >= len(ns.texts):
-                ns.texts.append('')
-            existing = ns.texts[y]
-            left = textwidth.ljust(textwidth.truncate(existing, x), x)
-            right_start = textwidth.cell_to_index(existing, x + textwidth.string_width(uni))
-            ns.texts[y] = left + uni + existing[right_start:]
-            ns.pad.addstr(y, x, text, text_attr)
-        except curses.error:
-            # curses errors on drawing the last character on the screen; ignore
-            pass
+        while y >= len(ns.texts):
+            ns.texts.append('')
+            ns.text_attrs.append([])
+            ns.contexts.append(None)
+        existing = ns.texts[y]
+        left = textwidth.ljust(textwidth.truncate(existing, x), x)
+        right_start = textwidth.cell_to_index(existing, x + textwidth.string_width(uni))
+        ns.texts[y] = left + uni + existing[right_start:]
+        ns.drawn.setdefault(y, []).append((x, uni, text_attr))
 
 
     def highlight_picked(self) -> None:
@@ -805,24 +857,65 @@ class ConsoleWindow:
     def _body_attrs(self, pos: int) -> list | None:
         return self.body.text_attrs[pos] if pos < len(self.body.text_attrs) else None
 
+    def _pad_row(self, pos: int, header: bool = False) -> int | None:
+        # Map a content row to the pad row that currently holds it.  Returns
+        # None when the row is outside the viewport, which is the common case
+        # for a long body: only the visible page lives in the pad.
+        row = pos if header else pos - self.scroll_pos
+        ns = self.head if header else self.body
+        if row < 0 or row >= ns.pad_rows:
+            return None
+        return row
+
+    def _overlay_spans(self, pad: CursesSurface, pad_row: int, ns: SimpleNamespace,
+                       pos: int) -> None:
+        # Replay the draw() spans for one content row on top of its normal
+        # attribute runs.  Off-screen rows keep their spans in ns.drawn and are
+        # painted when they scroll into view.
+        spans = ns.drawn.get(pos)
+        if not spans:
+            return
+        width = self.get_pad_width()
+        for x, text, attr in spans:
+            if x >= width:
+                continue
+            pad.addstr(pad_row, x, textwidth.truncate(text, width - x), attr)
+
+    def _paint_row(self, pad: CursesSurface, pad_row: int, pos: int, *,
+                   picked: bool) -> None:
+        # One content row -> one pad row, with the pick styling applied here
+        # rather than incrementally: a scrolled viewport moves rows on screen
+        # without changing pick_pos, so highlight state must follow the paint,
+        # not the last pick position.
+        text = self._body_text(pos)
+        if picked and self.mod_pick:
+            text = self.mod_pick(text)
+        text = textwidth.ljust(text, self.get_pad_width())
+        if picked:
+            self._draw_line_with_attrs(pad, pad_row, 0, text,
+                                       self._body_attrs(pos),
+                                       extra_attr=self.opts.pick_attr,
+                                       extra_attr_range=self.opts.pick_range)
+        else:
+            self._draw_line_with_attrs(pad, pad_row, 0, text,
+                                       self._body_attrs(pos), extra_attr=None)
+            self._overlay_spans(pad, pad_row, self.body, pos)
+
     def _redraw_rows(self, rows: Iterable[int]) -> None:
         for row_idx in rows:
-            if row_idx < len(self.body.texts):
-                text = textwidth.ljust(self._body_text(row_idx), self.get_pad_width())
-                self._draw_line_with_attrs(self.body.pad, row_idx, 0, text,
-                                           self._body_attrs(row_idx), extra_attr=None)
+            pad_row = self._pad_row(row_idx)
+            if pad_row is None or row_idx >= len(self.body.texts):
+                continue
+            self._paint_row(cast(CursesSurface, self.body.pad), pad_row,
+                            row_idx, picked=False)
 
     def _draw_picked_rows(self, rows: Iterable[int]) -> None:
         for row_idx in rows:
-            if row_idx < len(self.body.texts):
-                text = self._body_text(row_idx)
-                if self.mod_pick:
-                    text = self.mod_pick(text)
-                text = textwidth.ljust(text, self.get_pad_width())
-                self._draw_line_with_attrs(self.body.pad, row_idx, 0, text,
-                                           self._body_attrs(row_idx),
-                                           extra_attr=self.opts.pick_attr,
-                                           extra_attr_range=self.opts.pick_range)
+            pad_row = self._pad_row(row_idx)
+            if pad_row is None or row_idx >= len(self.body.texts):
+                continue
+            self._paint_row(cast(CursesSurface, self.body.pad), pad_row,
+                            row_idx, picked=True)
 
     def _draw_line_with_attrs(self, pad: CursesSurface, row: int, col_offset: int,
                               text: str, attrs: list | None,
@@ -845,6 +938,13 @@ class ConsoleWindow:
             col = self._draw_attr_run(pad, row, col, text, attr, pos, count,
                                       range_start, range_end, extra_attr)
             pos += count
+        if pos < len(text):
+            # draw() can replace part of a row without rewriting text_attrs[],
+            # so the run list may not cover the whole string.  Paint the tail in
+            # the normal attribute rather than leaving a hole in the row.
+            tail = textwidth.truncate(text[pos:], self.get_pad_width() - col)
+            if tail:
+                pad.addstr(row, col, tail, curses.A_NORMAL)
 
     def _draw_plain_line(self, pad: CursesSurface, row: int, col_offset: int, text: str,
                          extra_attr: int | None,
@@ -1145,23 +1245,59 @@ class ConsoleWindow:
         top = min(round(ind_pos+width/2), self.cols-1)
         return bot, max(top - bot, 1)
 
-    def _refresh_pads(self, indent: int) -> None:
-        if self.body_base < self.rows:
-            if self.pick_mode:
-                self.highlight_picked()
+    def _paint_body(self) -> int:
+        # Paint the visible page into the viewport-sized body pad.  Unlike the
+        # old pad-as-storage model, every frame redraws at most one screenful,
+        # so cost tracks the terminal, not the document.
+        view = min(self.scroll_view_size, self.rows - self.body_base)
+        if view <= 0:
+            return 0
+        pad = cast(CursesSurface, self.body.pad)
+        pad.erase()
+        for row in range(view):
+            pos = self.scroll_pos + row
+            if pos < 0 or pos >= self.body.row_cnt or pos >= len(self.body.texts):
+                continue
+            picked = (self.pick_mode
+                      and self.pick_pos <= pos < self.pick_pos + self.pick_size)
+            self._paint_row(pad, row, pos, picked=picked)
+        if self.pick_mode:
+            # Bookkeeping only: the paint above is stateless, but the
+            # incremental API (and the debug log) still reports the pick that
+            # was last shown and considers any pending full repaint done.
+            self.last_pick_pos = self.pick_pos
+            self._pick_clear_pending = False
+        return view
+
+    def _paint_head(self) -> int:
+        last_row = min(self.head.view_cnt, self.rows) - 1
+        if last_row < 0:
+            return -1
+        pad = cast(CursesSurface, self.head.pad)
+        pad.erase()
+        width = self.get_pad_width()
+        for row in range(last_row + 1):
+            if row >= len(self.head.texts):
+                continue
+            text = textwidth.ljust(self.head.texts[row], width)
+            attrs = self.head.text_attrs[row] if row < len(self.head.text_attrs) else None
+            self._draw_line_with_attrs(pad, row, 0, text, attrs, extra_attr=None)
+            self._overlay_spans(pad, row, self.head, row)
+        return last_row
 
+    def _refresh_pads(self, indent: int) -> None:
+        if self._paint_body() > 0:
             self.body.pad.noutrefresh(
-                self.scroll_pos, 0,
+                0, 0,
                 self.body_base, indent, self.rows-1, self.cols-1
             )
 
-        if self.rows > 0:
-            last_row = min(self.head.view_cnt, self.rows)-1
-            if last_row >= 0:
-                self.head.pad.noutrefresh(
-                    0, 0,
-                    0, indent, last_row, self.cols-1
-                )
+        last_row = self._paint_head()
+        if last_row >= 0:
+            self.head.pad.noutrefresh(
+                0, 0,
+                0, indent, last_row, self.cols-1
+            )
 
 
     def answer(self, prompt: str = 'Type string [then Enter]', seed: str = '', width: int = 80,
@@ -1758,12 +1894,15 @@ class ConsoleWindow:
 
     def clear(self) -> None:
         self.scr.clear()
+        # Viewport-sized pads: clearing costs one screenful, not one high-water
+        # mark, and no shrink/grow decision is needed at a frame boundary.
         self.head.pad.clear()
         self.body.pad.clear()
         self.head.texts, self.body.texts, self.last_pick_pos = [], [], -1
         self._pick_clear_pending = False
         self.head.text_attrs, self.body.text_attrs = [], []
         self.head.contexts, self.body.contexts = [], []
+        self.head.drawn, self.body.drawn = {}, {}
         self.head.row_cnt = self.body.row_cnt = 0
         self.head.rows_dropped = self.body.rows_dropped = 0
 

{console_window-2.0.0.2 → console_window-2.0.0.3}/tests/test_interactive.py

@@ -368,11 +368,15 @@ def test_draw_writes_a_row_and_tracks_row_cnt(make):
     win.draw(2, 1, 'hello')
     assert win.body.row_cnt == 3
     assert win.body.texts[2] == ' hello'
+    # Deferred painting: the span is recorded now and replayed by render().
+    assert win.body.drawn[2] == [(1, 'hello', curses.A_NORMAL)]
+    win.render()
     assert win.body.pad.calls_named('addstr')
 
 
 def test_draw_out_of_bounds_is_a_no_op(make):
-    win, _backend = make(body_rows=10, body_cols=40)
+    # max_rows, not body_rows, is what bounds draw(): body_rows is only a hint.
+    win, _backend = make(max_rows=10, body_cols=40)
     for y, x in ((-1, 0), (0, -1), (999, 0), (0, 999)):
         win.draw(y, x, 'x')
     assert win.body.row_cnt == 0
@@ -383,6 +387,7 @@ def test_draw_header_flag_targets_the_head_pad(make):
     win, _backend = make(head_rows=5)
     win.draw(0, 0, 'HDR', header=True)
     assert win.head.row_cnt == 1
+    win.render()
     assert win.head.pad.calls_named('addstr')
 
 

{console_window-2.0.0.2 → console_window-2.0.0.3}/tests/test_overflow.py

@@ -5,9 +5,11 @@ from console_window.opts import ConsoleWindowOpts
 from console_window.window import ConsoleWindow
 
 
-def _make(head_rows=3, body_rows=5):
+def _make(max_rows=5):
+    # max_rows is the only enforced ceiling; body_rows/head_rows are hints and
+    # deliberately absent here so these tests pin the enforcement path.
     return ConsoleWindow(
-        opts=ConsoleWindowOpts(head_rows=head_rows, body_rows=body_rows),
+        opts=ConsoleWindowOpts(max_rows=max_rows),
         backend=HeadlessBackend(rows=24, cols=80),
         singleton=False,
     )
@@ -24,7 +26,7 @@ def _record(fn):
 
 
 def test_add_body_within_capacity_is_silent():
-    win = _make(body_rows=5)
+    win = _make(max_rows=5)
     try:
         caught = _record(lambda: [win.add_body(f'row {i}') for i in range(5)])
         assert [str(w.message) for w in caught] == []
@@ -34,13 +36,41 @@ def test_add_body_within_capacity_is_silent():
         win.stop_curses()
 
 
+def test_body_rows_is_a_hint_not_a_limit():
+    # The whole point of the viewport-sized pads: an app no longer has to
+    # pre-size storage, so a small (or absent) body_rows never discards rows.
+    win = ConsoleWindow(
+        opts=ConsoleWindowOpts(body_rows=5, head_rows=2, max_rows=None),
+        backend=HeadlessBackend(rows=24, cols=80),
+        singleton=False,
+    )
+    try:
+        caught = _record(lambda: [win.add_body(f'row {i}') for i in range(12)])
+        assert [str(w.message) for w in caught] == []
+        assert win.rows_dropped == 0
+        assert win.body.row_cnt == 12
+        assert win.body.texts == [f'row {i}' for i in range(12)]
+        assert win.max_rows is None
+    finally:
+        win.stop_curses()
+
+
+def test_max_rows_is_the_only_ceiling_and_can_be_removed():
+    assert ConsoleWindowOpts().max_rows == 32767
+    assert ConsoleWindowOpts(max_rows=None).max_rows is None
+    # The old row options survive as hints; they no longer control the ceiling.
+    opts = ConsoleWindowOpts(body_rows=5, head_rows=2)
+    assert (opts.body_rows, opts.head_rows) == (5, 2)
+    assert opts.max_rows == 32767
+
+
 def test_overflowing_the_body_pad_counts_rows_and_warns_once():
-    win = _make(body_rows=5)
+    win = _make(max_rows=5)
     try:
         caught = _record(lambda: [win.add_body(f'row {i}') for i in range(12)])
         assert len(caught) == 1
         assert caught[0].category is UserWarning
-        assert 'body pad is full' in str(caught[0].message)
+        assert 'body content limit is full' in str(caught[0].message)
         # The excess is still discarded -- 7 of the 12 rows -- but no longer in
         # silence.
         assert win.rows_dropped == 7
@@ -53,7 +83,7 @@ def test_overflowing_the_body_pad_counts_rows_and_warns_once():
 
 
 def test_overflow_is_not_fatal_and_clear_rearms_the_warning():
-    win = _make(body_rows=2)
+    win = _make(max_rows=2)
     try:
         caught = _record(lambda: [win.add_body(f'a{i}') for i in range(9)])
         # No exception: the app limped along, exactly as it did before.
@@ -72,7 +102,7 @@ def test_overflow_is_not_fatal_and_clear_rearms_the_warning():
 
 
 def test_head_pad_overflow_is_counted_and_summed():
-    win = _make(head_rows=2, body_rows=2)
+    win = _make(max_rows=2)
     try:
         def draw():
             for i in range(4):
@@ -83,8 +113,8 @@ def test_head_pad_overflow_is_counted_and_summed():
         caught = _record(draw)
         messages = [str(w.message) for w in caught]
         assert len(messages) == 2
-        assert any('head pad is full' in m for m in messages)
-        assert any('body pad is full' in m for m in messages)
+        assert any('head content limit is full' in m for m in messages)
+        assert any('body content limit is full' in m for m in messages)
         assert win.head.rows_dropped == 2
         assert win.body.rows_dropped == 1
         assert win.rows_dropped == 3
@@ -93,12 +123,12 @@ def test_head_pad_overflow_is_counted_and_summed():
 
 
 def test_resume_on_a_full_pad_is_counted_too():
-    win = _make(body_rows=1)
+    win = _make(max_rows=1)
     try:
         win.add_body('only')
         caught = _record(lambda: win.add_body('more', resume=True))
         assert len(caught) == 1
-        assert 'body pad is full' in str(caught[0].message)
+        assert 'body content limit is full' in str(caught[0].message)
         assert win.body.row_cnt == 1
         assert win.rows_dropped == 1
     finally:
@@ -106,7 +136,7 @@ def test_resume_on_a_full_pad_is_counted_too():
 
 
 def test_the_warning_blames_the_callers_line_not_the_library():
-    win = _make(body_rows=1)
+    win = _make(max_rows=1)
     try:
         caught = _record(lambda: [win.add_body('first'), win.add_body('second')])
         assert caught[0].filename.endswith('test_overflow.py')

{console_window-2.0.0.2 → console_window-2.0.0.3}/tests/test_sample_app.py

@@ -113,11 +113,8 @@ def test_stress_mode_pads_the_body_within_pad_capacity():
         app.opts.stress = True
         app.screens[sample.MAIN_ST].draw_screen()
         assert app.win.body.row_cnt > normal
-        # add_body() drops rows past the pad capacity, so it must not exceed it...
-        assert app.win.body.row_cnt <= app.win.body.rows
-        # ...and must not hit it either: the demo's 'z' filler only stays whole
-        # because body_rows was raised for it.  Any drop is counted (and warned
-        # about) rather than passing unnoticed.
+        # Nothing is dropped: the pads are viewport-sized, the 2000 filler rows
+        # live in the model, and the default max_rows ceiling is far above them.
         assert app.win.rows_dropped == 0
     finally:
         app.win.stop_curses()

console_window-2.0.0.3/tests/test_viewport_pad.py

@@ -0,0 +1,152 @@
+"""Scheme B: body/head pads are viewport-sized blit buffers.
+
+These tests pin the properties that make `opts.body_rows` a hint rather than a
+storage limit: pad size tracks the terminal, the visible page is painted into
+pad row 0 on every frame, and `draw()` spans are replayed with their attributes
+even when the row was written long before it scrolled into view.
+"""
+
+import curses
+
+import pytest
+
+import console_window.window as window_mod
+from console_window.backend import HeadlessBackend
+from console_window.opts import ConsoleWindowOpts
+from console_window.window import ConsoleWindow
+
+
+@pytest.fixture(autouse=True)
+def _headless_curses(monkeypatch):
+    # curses.ACS_* are unbound until initscr(); the separator/indicator path
+    # needs them even when rendering through HeadlessBackend.
+    for name in ('ACS_HLINE', 'ACS_VLINE'):
+        if not hasattr(window_mod.curses, name):
+            monkeypatch.setattr(window_mod.curses, name, '-', raising=False)
+
+
+def _window(rows=10, cols=40, **opts):
+    backend = HeadlessBackend(rows=rows, cols=cols)
+    win = ConsoleWindow(opts=ConsoleWindowOpts(**opts), backend=backend, singleton=False)
+    return win, backend
+
+
+def _addstrs(pad):
+    calls = pad.calls_named('addstr')
+    out = []
+    for _name, args, _kw in calls:
+        text = args[2]
+        if isinstance(text, (bytes, bytearray)):
+            text = text.decode('utf-8')
+        out.append((args[0], args[1], text, args[3] if len(args) > 3 else None))
+    return out
+
+
+def _row_texts(pad):
+    return {y: text for y, x, text, _attr in _addstrs(pad) if x == 0}
+
+
+def test_pads_are_viewport_sized_regardless_of_body_rows():
+    win, backend = _window(rows=10, cols=40, body_rows=5000)
+    try:
+        assert len(backend.pads) == 2
+        assert win.body.pad_rows == 10
+        assert win.body.pad_cols == 39
+        assert win.head.pad_rows == 10
+    finally:
+        win.stop_curses()
+
+
+def test_render_paints_the_visible_page_into_pad_row_zero():
+    win, _backend = _window(rows=8, cols=40, head_line=False)
+    try:
+        for i in range(100):
+            win.add_body(f'row {i:03d}')
+        win.scroll_pos = 50
+        win.render()
+
+        rows = _row_texts(win.body.pad)
+        assert 'row 050' in rows[0]
+        assert 'row 057' in rows[7]
+        assert not any('row 000' in text for text in rows.values())
+    finally:
+        win.stop_curses()
+
+
+def test_draw_span_is_replayed_with_its_attribute():
+    win, _backend = _window(rows=6, cols=30, head_line=False)
+    try:
+        win.draw(1, 2, 'X', curses.A_BOLD)
+        win.render()
+
+        assert any(y == 1 and x == 2 and text == 'X' and attr == curses.A_BOLD
+                   for y, x, text, attr in _addstrs(win.body.pad))
+    finally:
+        win.stop_curses()
+
+
+def test_draw_on_an_offscreen_row_survives_until_it_is_scrolled_to():
+    win, _backend = _window(rows=6, cols=30, head_line=False)
+    try:
+        for i in range(40):
+            win.add_body(f'r{i}')
+        win.draw(30, 5, 'ZZ', curses.A_BOLD)
+
+        win.render()
+        assert not any(text == 'ZZ' for _y, _x, text, _a in _addstrs(win.body.pad))
+
+        win.scroll_pos = 30
+        win.render()
+        assert any(y == 0 and x == 5 and text == 'ZZ' and attr == curses.A_BOLD
+                   for y, x, text, attr in _addstrs(win.body.pad))
+    finally:
+        win.stop_curses()
+
+
+def test_resize_reallocates_the_pads_to_the_new_viewport():
+    win, backend = _window(rows=10, cols=40)
+    try:
+        backend.screen._rows = 12
+        backend.screen._cols = 30
+        win.render()
+
+        assert win.rows == 12
+        assert win.body.pad_rows == 12
+        assert win.body.pad_cols == 29
+        assert len(backend.pads) == 4  # two original, two replacements
+    finally:
+        win.stop_curses()
+
+
+def test_pick_highlight_follows_the_viewport_without_moving_the_pick():
+    # The old pad-as-storage model kept the reverse-video row inside the pad, so
+    # scrolling moved it on screen for free.  Painting statelessly must apply
+    # the pick attribute wherever the picked row currently lands.
+    win, _backend = _window(rows=6, cols=30, head_line=False, pick_mode=True)
+    try:
+        for i in range(40):
+            win.add_body(f'row {i}')
+        win.pick_pos = 5
+
+        win.render()
+        assert any(text.startswith('row 5') and attr & curses.A_REVERSE
+                   for y, _x, text, attr in _addstrs(win.body.pad) if y == 5)
+
+        win.scroll_pos = 2
+        win.render()
+        assert any(text.startswith('row 5') and attr & curses.A_REVERSE
+                   for y, _x, text, attr in _addstrs(win.body.pad) if y == 3)
+    finally:
+        win.stop_curses()
+
+
+def test_clear_drops_recorded_draw_spans():
+    win, _backend = _window(rows=6, cols=30, head_line=False)
+    try:
+        win.draw(0, 0, 'X')
+        assert win.body.drawn
+        win.clear()
+        assert win.body.drawn == {}
+        assert win.body.row_cnt == 0
+    finally:
+        win.stop_curses()

{console_window-2.0.0.2 → console_window-2.0.0.3}/tests/test_widechars.py

@@ -79,8 +79,10 @@ def make_window(cols=10, body_cols=10):
     win.cols = cols
     win.body_cols = body_cols
     for name in ('head', 'body'):
+        pad = FakePad()
         setattr(win, name, SimpleNamespace(
-            pad=FakePad(), rows=50, cols=body_cols, row_cnt=0,
+            pad=pad, rows=50, cols=body_cols, row_cnt=0,
+            pad_rows=50, pad_cols=body_cols, drawn={},
             texts=[], text_attrs=[], contexts=[]))
     return win
 
@@ -126,9 +128,10 @@ def test_draw_pads_to_cells():
     win = make_window(cols=8, body_cols=8)
     win.draw(0, 0, CJK, width=6)
 
-    y, x, data, _attr = win.body.pad.calls[-1]
-    text = data.decode('utf-8')
-    assert (y, x) == (0, 0)
+    # draw() now records the span; the viewport painter replays it (with the
+    # same display-cell padding) on the frame where row 0 is visible.
+    x, text, _attr = win.body.drawn[0][-1]
+    assert x == 0
     assert tw.string_width(text) == 6
 
 
@@ -136,7 +139,7 @@ def test_draw_leftpad_pads_on_the_left():
     win = make_window(cols=8, body_cols=8)
     win.draw(0, 0, CJK, width=4, leftpad=True)
 
-    text = win.body.pad.calls[-1][2].decode('utf-8')
+    text = win.body.drawn[0][-1][1]
     assert text == '  ' + CJK
 
 # --- pick-range highlighting ------------------------------------------------