console-window 2.0.2__tar.gz → 2.1.1__tar.gz

{console_window-2.0.2 → console_window-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: console-window
-Version: 2.0.2
+Version: 2.1.1
 Summary: A robust curses wrapper for creating Text User Interfaces (TUIs).
 Author-email: Joe Defen <joedef@duck.com>
 Requires-Python: >=3.10
@@ -104,9 +104,11 @@ demonstrates:
   skipped by navigation.
 * **`IncrementalSearchBar`** — `/` filters the list as you type, using
   `passthrough_mode` to hand keys to the bar.
-* **`InlineConfirmation`** — `SPACE` asks you to confirm with `y` before
-  "processing" the picked row. The widget is also a curses-free line editor
-  (`initial=''`, caret movement, Delete, and `get_display_string()`).
+* **In-place prompts** — `SPACE` asks you to confirm with `y` before
+  "processing" the picked row through `begin_prompt()` /
+  `handle_prompt_key()`, and `N` edits a note in the header band with the
+  buffered text mode. Both use `PromptLine` underneath; completion callbacks
+  run after passthrough is restored, so they can report with `status()`.
 * **Themes** — a `THEMES` screen of colour samples backed by
   `Theme.list_all()` / `get_current()` / `set()`. The active theme is now
   per-window state: `ConsoleWindowOpts(theme=...)` seeds `window.theme`,
@@ -121,7 +123,13 @@ demonstrates:
   `answer()` returns `None` only when the user aborts; if the terminal cannot
   fit the dialog it raises `TerminalTooSmallError` with the required and actual
   sizes.
-* **`flash()`** — transient, non-destructive status messages.
+* **`status()` and `flash()`** — `status()` is a non-modal one-line message on
+  the separator row; `flash()` is a modal box that clears the screen. The demo
+  uses `status()` for "Processed", "Cancelled" and note-saved feedback.
+* **`BasicTextScreen`** — the HISTORY screen is rebuilt each draw from a
+  `BasicTextScreen` via `set_text()` (headers plus `(text, attr)` lines), and
+  resolves its window at draw time because the screens are constructed before
+  the `ConsoleWindow`.
 * **Token-based headers** — `HeaderLine` (`text`, `bracket_key`, `key`, `extend`)
   rendered with `add_header_line()`, rather than string markup. Both header
   helpers accept `line_attr`, an attribute OR'd into every span, so a whole
@@ -210,6 +218,90 @@ finally:
 Only keys the context actually added are removed on exit, so a pre-existing
 binding is left in place and nested uses are safe.
 
+### Transient status on the separator row
+
+`status()` declares a one-line message that is painted on the separator row —
+the row that also owns the scroll indicator — so the listing stays visible.
+Unlike `flash()`, which clears the whole screen, `status()` never takes over
+the display:
+
+```python
+win.status('Backup tag failed', level='error', timeout=5.0)
+```
+
+The message appears on the next `render()`/`prompt()`; `status()` never renders
+by itself. Levels `'info'`, `'warn'` and `'error'` select an attribute from
+`ConsoleWindow.STATUS_LEVELS` (`info` dim, `warn` bold, `error` bold+reverse);
+an unknown level falls back to `'info'` instead of raising, and `attr=` overrides
+the level for that message only. `timeout=None` keeps the message until it is
+replaced or cleared; any number expires it lazily at draw time. `status('')` and
+`clear_status()` remove it, and `current_status` returns `(text, attr)`.
+
+The exact rendering rule is: the text starts at column 0 of `head.view_cnt` and
+is truncated to leave **one blank cell between it and the scroll indicator**.
+If the window currently has no separator row, the text is still stored and
+`status()` returns `False` (the message is deferred, not lost); a later resize
+reveals it.
+
+### In-place prompts
+
+`PromptLine` is the window-independent state machine: text, an editable buffer,
+an optional hint and completion callbacks. It never runs the callbacks itself;
+`take()` returns `(answer, on_confirm, on_cancel)` after cancelling the widget.
+The window wraps it with a lifecycle that keeps key routing and passthrough
+consistent:
+
+```python
+win.begin_prompt('Overwrite the tag?', mode='y',
+                 on_confirm=lambda answer: apply(answer))
+while win.prompt_active:
+    key = win.prompt(seconds=0.5)
+    if win.handle_prompt_key(key) == 'continue':
+        continue          # swallow every key while a prompt is live
+    break
+win.render()
+```
+
+While `prompt_active` is true, route **every** key through
+`handle_prompt_key()` and swallow a `'continue'` result, so no action key can
+fire underneath a live prompt. `begin_prompt()` turns `passthrough_mode` on and
+`end_prompt()` restores its previous value; completion callbacks run *after*
+the prompt is gone and passthrough is restored, so a callback may safely begin
+the next prompt (the "re-edit, then ENTER or ESC" re-ask path).
+
+The display formats are fixed so applications do not have to reproduce them:
+
+* single-key modes `Y`/`y`: `f'{prompt}  [Press "{mode}" or ESC]'`, e.g.
+  `Really quit?  [Press "y" or ESC]`;
+* every other mode: `f'{prompt}: {buffer}{caret}{rest}'`, e.g. `Value: 5│`.
+
+`get_hint_string(width)` returns the hint (truncated when a width is given), and
+`get_choice_lines()` returns one row per choice, marking the currently resolved
+one: `⮞ alpha` versus `  beta`. Drawing is the application's choice:
+`add_prompt_header()` puts a screen-wide question in the header band, while
+`add_prompt_lines()` appends a bold prompt row and a dim hint row as
+`Context(genre='TRANSIENT', pickable=False)` from the application's own row
+loop. The window never learns which item the prompt belongs to.
+
+### Read-only text screens
+
+`BasicTextScreen` is the small `Screen` for preformatted, scrollable text. It
+resolves `app.win` at draw time, disables pick mode, adds each header before the
+body, and adds each line with `add_body()` and no `Context` (so normal
+navigation scrolls it). Content is normalised by `set_text()`, which is safe
+before or after the first draw:
+
+```python
+screen = BasicTextScreen(app, head='COMPARE',
+                         lines=[('first difference', curses.A_BOLD),
+                                'second difference'])
+screen.set_text(lines=['replacement'])
+```
+
+`lines` items are `str` or `(str, attr)`; `head` may be a `str`, a
+`HeaderLine`, or an iterable of either. There is no pick mode, no action
+handler and no spinner: ESC/back remains the application's `escape_ACTION`.
+
 ### Taking navigation keys for the application
 
 Navigation keys are reserved by default, but an app may take specific ones for

{console_window-2.0.2 → console_window-2.1.1}/README.md

@@ -85,9 +85,11 @@ demonstrates:
   skipped by navigation.
 * **`IncrementalSearchBar`** — `/` filters the list as you type, using
   `passthrough_mode` to hand keys to the bar.
-* **`InlineConfirmation`** — `SPACE` asks you to confirm with `y` before
-  "processing" the picked row. The widget is also a curses-free line editor
-  (`initial=''`, caret movement, Delete, and `get_display_string()`).
+* **In-place prompts** — `SPACE` asks you to confirm with `y` before
+  "processing" the picked row through `begin_prompt()` /
+  `handle_prompt_key()`, and `N` edits a note in the header band with the
+  buffered text mode. Both use `PromptLine` underneath; completion callbacks
+  run after passthrough is restored, so they can report with `status()`.
 * **Themes** — a `THEMES` screen of colour samples backed by
   `Theme.list_all()` / `get_current()` / `set()`. The active theme is now
   per-window state: `ConsoleWindowOpts(theme=...)` seeds `window.theme`,
@@ -102,7 +104,13 @@ demonstrates:
   `answer()` returns `None` only when the user aborts; if the terminal cannot
   fit the dialog it raises `TerminalTooSmallError` with the required and actual
   sizes.
-* **`flash()`** — transient, non-destructive status messages.
+* **`status()` and `flash()`** — `status()` is a non-modal one-line message on
+  the separator row; `flash()` is a modal box that clears the screen. The demo
+  uses `status()` for "Processed", "Cancelled" and note-saved feedback.
+* **`BasicTextScreen`** — the HISTORY screen is rebuilt each draw from a
+  `BasicTextScreen` via `set_text()` (headers plus `(text, attr)` lines), and
+  resolves its window at draw time because the screens are constructed before
+  the `ConsoleWindow`.
 * **Token-based headers** — `HeaderLine` (`text`, `bracket_key`, `key`, `extend`)
   rendered with `add_header_line()`, rather than string markup. Both header
   helpers accept `line_attr`, an attribute OR'd into every span, so a whole
@@ -191,6 +199,90 @@ finally:
 Only keys the context actually added are removed on exit, so a pre-existing
 binding is left in place and nested uses are safe.
 
+### Transient status on the separator row
+
+`status()` declares a one-line message that is painted on the separator row —
+the row that also owns the scroll indicator — so the listing stays visible.
+Unlike `flash()`, which clears the whole screen, `status()` never takes over
+the display:
+
+```python
+win.status('Backup tag failed', level='error', timeout=5.0)
+```
+
+The message appears on the next `render()`/`prompt()`; `status()` never renders
+by itself. Levels `'info'`, `'warn'` and `'error'` select an attribute from
+`ConsoleWindow.STATUS_LEVELS` (`info` dim, `warn` bold, `error` bold+reverse);
+an unknown level falls back to `'info'` instead of raising, and `attr=` overrides
+the level for that message only. `timeout=None` keeps the message until it is
+replaced or cleared; any number expires it lazily at draw time. `status('')` and
+`clear_status()` remove it, and `current_status` returns `(text, attr)`.
+
+The exact rendering rule is: the text starts at column 0 of `head.view_cnt` and
+is truncated to leave **one blank cell between it and the scroll indicator**.
+If the window currently has no separator row, the text is still stored and
+`status()` returns `False` (the message is deferred, not lost); a later resize
+reveals it.
+
+### In-place prompts
+
+`PromptLine` is the window-independent state machine: text, an editable buffer,
+an optional hint and completion callbacks. It never runs the callbacks itself;
+`take()` returns `(answer, on_confirm, on_cancel)` after cancelling the widget.
+The window wraps it with a lifecycle that keeps key routing and passthrough
+consistent:
+
+```python
+win.begin_prompt('Overwrite the tag?', mode='y',
+                 on_confirm=lambda answer: apply(answer))
+while win.prompt_active:
+    key = win.prompt(seconds=0.5)
+    if win.handle_prompt_key(key) == 'continue':
+        continue          # swallow every key while a prompt is live
+    break
+win.render()
+```
+
+While `prompt_active` is true, route **every** key through
+`handle_prompt_key()` and swallow a `'continue'` result, so no action key can
+fire underneath a live prompt. `begin_prompt()` turns `passthrough_mode` on and
+`end_prompt()` restores its previous value; completion callbacks run *after*
+the prompt is gone and passthrough is restored, so a callback may safely begin
+the next prompt (the "re-edit, then ENTER or ESC" re-ask path).
+
+The display formats are fixed so applications do not have to reproduce them:
+
+* single-key modes `Y`/`y`: `f'{prompt}  [Press "{mode}" or ESC]'`, e.g.
+  `Really quit?  [Press "y" or ESC]`;
+* every other mode: `f'{prompt}: {buffer}{caret}{rest}'`, e.g. `Value: 5│`.
+
+`get_hint_string(width)` returns the hint (truncated when a width is given), and
+`get_choice_lines()` returns one row per choice, marking the currently resolved
+one: `⮞ alpha` versus `  beta`. Drawing is the application's choice:
+`add_prompt_header()` puts a screen-wide question in the header band, while
+`add_prompt_lines()` appends a bold prompt row and a dim hint row as
+`Context(genre='TRANSIENT', pickable=False)` from the application's own row
+loop. The window never learns which item the prompt belongs to.
+
+### Read-only text screens
+
+`BasicTextScreen` is the small `Screen` for preformatted, scrollable text. It
+resolves `app.win` at draw time, disables pick mode, adds each header before the
+body, and adds each line with `add_body()` and no `Context` (so normal
+navigation scrolls it). Content is normalised by `set_text()`, which is safe
+before or after the first draw:
+
+```python
+screen = BasicTextScreen(app, head='COMPARE',
+                         lines=[('first difference', curses.A_BOLD),
+                                'second difference'])
+screen.set_text(lines=['replacement'])
+```
+
+`lines` items are `str` or `(str, attr)`; `head` may be a `str`, a
+`HeaderLine`, or an iterable of either. There is no pick mode, no action
+handler and no spinner: ESC/back remains the application's `escape_ACTION`.
+
 ### Taking navigation keys for the application
 
 Navigation keys are reserved by default, but an app may take specific ones for

{console_window-2.0.2 → console_window-2.1.1}/SampleApp.py

@@ -9,12 +9,12 @@ from types import SimpleNamespace
 
 from console_window import (
     BasicHelpScreen,
+    BasicTextScreen,
     ConsoleWindow,
     ConsoleWindowOpts,
     Context,
     HeaderLine,
     IncrementalSearchBar,
-    InlineConfirmation,
     OptionSpinner,
     Screen,
     ScreenStack,
@@ -38,9 +38,12 @@ class SampleApp:
         self.filter_text = ''
         self.selected_items = set()  # Track "selected" items for demo
         self.operation_count = 0
-
-        # Inline confirmation handler
-        self.confirmation = InlineConfirmation()
+        # In-place prompt state.  PromptLine itself lives on the window; these
+        # are the application's product decisions about which row/item a live
+        # prompt belongs to (the window deliberately never learns that).
+        self.prompt_item = None
+        self.note_item = None
+        self.notes = {}
 
         # Incremental search bar
         self.filter_bar = IncrementalSearchBar(
@@ -109,6 +112,8 @@ class SampleApp:
                      genre='action', scope={MAIN_ST})
         spin.add_key('alert_demo', 'l - alert demo',
                      genre='action', scope={MAIN_ST})
+        # In-place, buffered prompt rendered as a header row (see note_ACTION).
+        spin.add_key('note', 'N - add a note', genre='action', scope={MAIN_ST})
         spin.add_key('show_keys', 'K - show keys (demo mode)', genre='action')
 
         # Folded in from the retired dev self-test.
@@ -171,33 +176,19 @@ class SampleApp:
         self.filter_text = original_text.lower() if original_text else ''
         self.win.passthrough_mode = False
 
-    def _start_operation(self):
-        if self.confirmation.identity:
-            item_name = self.confirmation.identity
-            # Mark item as "processed"
-            self.selected_items.add(item_name)
-            self.operation_count += 1
-            # Flash success message
-            self.win.flash(f'✓ Processed {item_name}', duration=1.5)
-        self.confirmation.cancel()
-        self.win.passthrough_mode = False
-
     def handle_key(self, key):
-        # Handle filter bar FIRST (highest priority when active)
+        # A live in-place prompt owns every key.  This is the documented
+        # contract: nothing underneath the prompt (filter, spinner actions)
+        # may fire until the prompt has been dealt with.
+        if self.win.prompt_active:
+            self.win.handle_prompt_key(key)
+            return None
+
+        # Handle filter bar NEXT (highest priority when active)
         if self.filter_bar.is_active:
             if self.filter_bar.handle_key(key):
                 return None  # Key was consumed
 
-        # Handle confirmation mode SECOND (high priority when active)
-        if self.confirmation.active:
-            result = self.confirmation.handle_key(key)
-            if result == 'confirmed':
-                self._start_operation()
-            elif result == 'cancelled':
-                self.confirmation.cancel()
-                self.win.passthrough_mode = False
-            return None  # Key was consumed by confirmation
-
         # Handle ENTER for screen navigation
         if key in (cs.KEY_ENTER, 10):
             if self.stack.curr.num != MAIN_ST:
@@ -303,21 +294,14 @@ class MainScreen(DemoScreen):
             ctx = Context(genre='item', item=item)
             app.win.add_body(line, attr=attr, context=ctx)
 
-            # Show inline confirmation if active for this item.  The wording and
-            # the warning glyph stay here (product decisions); the widget owns
-            # the buffer/caret composition.
-            if app.confirmation.active and \
-               app.confirmation.identity == username:
-                prompt = f'    ⚠️  Process {username}?'
-                if app.confirmation.mode == 'y':
-                    prompt += " - Press 'y' or ESC"
-                elif app.confirmation.mode == 'Y':
-                    prompt += " - Press 'Y' or ESC"
-
-                app.win.add_body(
-                    app.confirmation.get_display_string(prompt=prompt),
+            # Draw the in-place confirmation right after the row it belongs to.
+            # The wording and warning glyph stay here (product decisions); the
+            # window's prompt helper owns the display composition and marks both
+            # rows TRANSIENT/non-pickable for us.
+            if app.win.prompt_active and app.prompt_item == username:
+                app.win.add_prompt_lines(
                     attr=cs.color_pair(Theme.WARNING) | cs.A_BOLD,
-                    context=Context(genre='DECOR')
+                    hint_attr=cs.A_DIM,
                 )
 
         if app.opts.stress:
@@ -361,6 +345,7 @@ class MainScreen(DemoScreen):
         line.text(' ').key('SPC').text(':process')
         # line.text(' ').bracket_key('p').text(f'ick={app.opts.pick_size}')
         line.text(' ').bracket_key('n').text(f'ame={app.opts.name or "-"}')
+        line.text(' ').bracket_key('N').text(':note')
         # line.text(' ').key('r').text('edraw')
         # line.text(' ').key('z').text(':stress')
         # line.text(' ').bracket_key('t').text('hemes')
@@ -384,6 +369,12 @@ class MainScreen(DemoScreen):
 
         app.win.add_header(header, attr=cs.A_DIM | cs.A_UNDERLINE)
 
+        # A buffered note prompt is a screen-wide question, so it lives in the
+        # header band rather than under one row.  add_prompt_header() renders
+        # the library's fixed ': buffer│' format.
+        if app.win.prompt_active and app.note_item:
+            app.win.add_prompt_header()
+
     def filter_ACTION(self):
         app = self.app
         app.filter_bar.start(app.filter_text)
@@ -397,16 +388,68 @@ class MainScreen(DemoScreen):
         app.filter_bar._text = ''  # pylint: disable=protected-access
         app.filter_text = ''
         app.win.pick_pos = 0
+        app.win.status('Filter cleared', timeout=1.0)
 
     def select_ACTION(self):
         app = self.app
-        ctx = app.win.get_picked_context()
-        if ctx and hasattr(ctx, 'item'):
-            item = ctx.item
-            username = item['username']
-            # Start inline confirmation (mode 'y' = press 'y' to confirm)
-            app.confirmation.start('process', username, mode='y')
-            app.win.passthrough_mode = True
+        win = app.win
+        ctx = win.get_picked_context()
+        if not ctx or not hasattr(ctx, 'item'):
+            return
+        username = ctx.item['username']
+        app.prompt_item = username
+
+        def confirm(_answer):
+            app.prompt_item = None
+            app.selected_items.add(username)
+            app.operation_count += 1
+            # Non-modal: the listing stays visible on the next render.
+            win.status(f'✓ Processed {username}', timeout=1.5)
+
+        def cancel():
+            app.prompt_item = None
+            win.status('Cancelled', timeout=1.0)
+
+        # Single-key mode 'y'; the window enables passthrough for us and the
+        # callbacks run after the prompt is gone (so status() is safe here).
+        win.begin_prompt(
+            f'    ⚠️  Process {username}?',
+            mode='y',
+            hint='Marks the row as ✓ Processed',
+            on_confirm=confirm,
+            on_cancel=cancel,
+        )
+
+    def note_ACTION(self):
+        app = self.app
+        win = app.win
+        ctx = win.get_picked_context()
+        if not ctx or not hasattr(ctx, 'item'):
+            win.status('Select an item first', level='warn', timeout=2.0)
+            return
+        username = ctx.item['username']
+        app.note_item = username
+
+        def save(answer):
+            app.note_item = None
+            app.notes[username] = answer
+            win.status(f'✓ Note saved for {username}', level='warn',
+                       timeout=2.0)
+
+        def cancel():
+            app.note_item = None
+            win.status('Note cancelled', timeout=1.5)
+
+        # Buffered text mode.  add_prompt_header() draws it in the header band,
+        # including the caret glyph and the fixed ': ' separator.
+        win.begin_prompt(
+            f'Note for {username}',
+            hint='ENTER to save, ESC to cancel',
+            mode='text',
+            seed=app.notes.get(username, ''),
+            on_confirm=save,
+            on_cancel=cancel,
+        )
 
     def answer_demo_ACTION(self):
         app = self.app
@@ -414,9 +457,9 @@ class MainScreen(DemoScreen):
         response = win.answer('Enter your name (or ESC to cancel): ',
                               height=1)
         if response:
-            win.flash(f'Hello, {response}!', duration=2.0)
+            win.status(f'Hello, {response}!', level='warn', timeout=2.0)
         else:
-            win.flash('Cancelled', duration=1.0)
+            win.status('Cancelled', timeout=1.0)
 
     def alert_demo_ACTION(self):
         ctx = self.app.win.get_picked_context()
@@ -472,32 +515,34 @@ class HelpScreen(DemoScreen, BasicHelpScreen):
 class HistoryScreen(DemoScreen):
     def __init__(self, app):
         super().__init__('HISTORY', app)
+        # Constructed before the ConsoleWindow exists, exactly like the other
+        # screens: BasicTextScreen resolves app.win at draw time.
+        self.text_screen = BasicTextScreen(app)
 
     def draw_screen(self):
         app = self.app
-        app.win.set_pick_mode(False)
-
-        app.win.add_header('OPERATION HISTORY', attr=cs.A_BOLD)
-        app.win.add_header('  Press ESC or ENTER to return',
-                          attr=cs.A_DIM, resume=True)
-
+        lines = [('  Press ESC or ENTER to return', cs.A_DIM), '']
         if app.selected_items:
-            app.win.add_body('')
-            app.win.add_body(f'Total processed items: {len(app.selected_items)}')
-            app.win.add_body('')
+            lines.append(f'Total processed items: {len(app.selected_items)}')
+            lines.append('')
             for username in sorted(app.selected_items):
                 # Find the item details
                 item = next((i for i in app.items
                            if i['username'] == username), None)
                 if item:
-                    line = f'  ✓ {username:<16} uid={item["uid"]:<8} {item["home"]}'
-                    app.win.add_body(line, attr=cs.color_pair(Theme.SUCCESS))
+                    line = (f'  ✓ {username:<16} uid={item["uid"]:<8} '
+                            f'{item["home"]}')
+                    lines.append((line, cs.color_pair(Theme.SUCCESS)))
         else:
-            app.win.add_body('')
-            app.win.add_body('No items have been processed yet.')
-            app.win.add_body('')
-            app.win.add_body('Go back to the main screen and press '
-                           'SPACE on an item to process it.')
+            lines.extend([
+                'No items have been processed yet.',
+                '',
+                'Go back to the main screen and press SPACE on an item '
+                'to process it.',
+            ])
+        # Content is rebuilt each draw; nothing is cached across frames.
+        self.text_screen.set_text(lines, head=['OPERATION HISTORY'])
+        self.text_screen.draw_screen()
 
 
 class ThemeScreen(Theme.create_picker_screen(DemoScreen)):

{console_window-2.0.2 → console_window-2.1.1}/console_window/__init__.py

@@ -1,22 +1,29 @@
 # 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.2"
+__version__ = "2.1.1"
 
 from .context import Context
 from .header import HeaderLine, Span
 from .keys import NAVIGATION_KEYS
 from .opts import ConsoleWindowOpts
-from .screens import HOME_ST, BasicHelpScreen, Screen, ScreenStack
+from .screens import (
+    HOME_ST,
+    BasicHelpScreen,
+    BasicTextScreen,
+    Screen,
+    ScreenStack,
+)
 from .signals import reset_ctrl_c
 from .spinner import OptionSpinner
 from .theme import Theme
-from .widgets import IncrementalSearchBar, InlineConfirmation
+from .widgets import IncrementalSearchBar, InlineConfirmation, PromptLine
 from .window import ConsoleWindow, TerminalTooSmallError
 
 __all__ = [
     'HOME_ST',
     'NAVIGATION_KEYS',
     'BasicHelpScreen',
+    'BasicTextScreen',
     'ConsoleWindow',
     'ConsoleWindowOpts',
     'Context',
@@ -24,6 +31,7 @@ __all__ = [
     'IncrementalSearchBar',
     'InlineConfirmation',
     'OptionSpinner',
+    'PromptLine',
     'Screen',
     'ScreenStack',
     'Span',

{console_window-2.0.2 → console_window-2.1.1}/console_window/screens.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+from collections.abc import Iterable
 from types import SimpleNamespace
 from typing import TYPE_CHECKING, Protocol
 
+from .header import HeaderLine
 from .spinner import OptionSpinner
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
@@ -14,6 +16,12 @@ class _AppLike(Protocol):
     win: ConsoleWindow
 
 
+#: One body row: plain text, or text paired with a curses attribute.
+_LineItem = str | tuple[str, int | None]
+#: One header entry, or a specification of one or more of them.
+_HeadSpec = str | HeaderLine | Iterable[str | HeaderLine] | None
+
+
 # Default home screen constant (applications should define their own)
 HOME_ST = 0
 
@@ -247,3 +255,63 @@ class BasicHelpScreen(Screen):
         if spinner:
             spinner.show_help_nav_keys(win)
             spinner.show_help_body(win)
+
+
+class BasicTextScreen(Screen):
+    """Read-only screen showing preformatted lines under optional headers.
+
+    The window is resolved at draw time: applications may build their Screen
+    objects before the ConsoleWindow exists (BasicHelpScreen relies on the same
+    rule).  ``lines`` items are ``str`` or ``(str, attr)``; ``head`` is a
+    ``str``, a :class:`HeaderLine`, or an iterable of either.  Content is
+    normalised by :meth:`set_text`, so ``draw_screen()`` is a flat loop and
+    nothing is cached across draws.
+
+    There is no pick mode, no action handling and no spinner.  ESC/back stays
+    the application's ``escape_ACTION``, and ``come_from_whitelist`` stays
+    permissive by default.
+    """
+
+    come_from_whitelist = None
+
+    def __init__(self, app: _AppLike, lines: Iterable[_LineItem] = (),
+                 head: _HeadSpec = ()) -> None:
+        super().__init__(app)
+        self._lines: list[tuple[str, int | None]] = []
+        self._heads: list[str | HeaderLine] = []
+        self.set_text(lines, head)
+
+    def set_text(self, lines: Iterable[_LineItem] = (),
+                 head: _HeadSpec = ()) -> None:
+        """Replace the screen's content.  Safe before or after the first draw."""
+        self._lines = [self._normalize_line(item) for item in (lines or ())]
+        self._heads = self._normalize_heads(head)
+
+    @staticmethod
+    def _normalize_line(item: _LineItem) -> tuple[str, int | None]:
+        if isinstance(item, str):
+            return item, None
+        text, attr = item
+        return str(text), attr
+
+    @staticmethod
+    def _normalize_heads(head: _HeadSpec) -> list[str | HeaderLine]:
+        if head is None:
+            return []
+        if isinstance(head, (str, HeaderLine)):
+            return [head]
+        return list(head)
+
+    def draw_screen(self) -> None:
+        win = self.app.win
+        win.set_pick_mode(False)
+        for head_item in self._heads:
+            if isinstance(head_item, HeaderLine):
+                # Keep the declared span roles; add_header() takes plain text.
+                win.add_header_line(head_item)
+            else:
+                win.add_header(head_item)
+        for text, attr in self._lines:
+            # No Context: these are plain, scrollable rows (the same shape
+            # ViewScreen/CompareScreen produced before this helper existed).
+            win.add_body(text, attr=attr)