console-window 2.0.0.6__tar.gz → 2.0.0.8__tar.gz

{console_window-2.0.0.6 → console_window-2.0.0.8}/CHANGELOG.md

@@ -6,6 +6,19 @@ This project follows [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 
 ### Added
+- `suspend_curses()`/`resume_curses()` on `ConsoleWindow`: leave curses mode
+  with `endwin()` while keeping the window (pads, content model, pick state)
+  alive, then reattach a screen and repaint.  This is the supported way for an
+  app to shell out to a command or an editor and come back.  The pads survive
+  because `endwin()` restores the terminal without destroying the curses
+  SCREEN; `resume_curses()` refreshes the screen handle, backend, dimensions,
+  pad backgrounds and redraw bookkeeping.
+- Singleton-mode compatibility for the pre-2.0 start/stop pair:
+  `stop_curses()` now *suspends* the shared screen and `start_curses()`
+  resumes it, so `stop_curses(); ...; start_curses()` works again (this is what
+  efibootdude's write/reboot paths needed).  `ConsoleWindow.stop_all()` remains
+  the permanent teardown and is the atexit hook; per-instance windows keep
+  `stop_curses()` as a one-way teardown and use suspend/resume explicitly.
 - Per-window themes. `ConsoleWindow.theme` records the theme a window is on,
   `ConsoleWindowOpts(theme=...)` seeds it, and `ConsoleWindow.set_theme()`
   switches it: colours are reinstalled through the window's own backend (curses
@@ -122,6 +135,16 @@ This project follows [Semantic Versioning](https://semver.org/).
   No in-repo code used it.
 
 ### Fixed
+- `win._start_curses()` once again *reattaches* the window.  The 1.4.x
+  compatibility hook is still called in the wild (psistat's "dump event log"
+  path uses `self.window._start_curses()` to return from shell mode), but the
+  2.0 implementation only created and returned a screen, leaving `win.scr` as
+  `None`; the next `clear()`/`render()` then raised
+  `AttributeError: 'NoneType' object has no attribute 'clear'`.  It now resumes
+  a suspended window through `resume_curses()` (singleton mode reattaches every
+  window sharing the screen), so the pads and the content model survive, and
+  `clear()` while suspended resets the content model without dereferencing the
+  missing screen.
 - Starting a window on a terminal with fewer than 256 colours (including tmux's
   stock `TERM=screen`, whose terminfo entry has 8 colours) no longer crashes with
   `ValueError: Color number is greater than COLORS-1`. Theme installation now

{console_window-2.0.0.6 → console_window-2.0.0.8}/PKG-INFO

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

{console_window-2.0.0.6 → console_window-2.0.0.8}/README.md

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

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

{console_window-2.0.0.6 → console_window-2.0.0.8}/console_window/backend.py

@@ -313,6 +313,9 @@ class HeadlessBackend:
 
     def start(self, timeout_ms: int) -> Surface:
         self.screen.timeout(timeout_ms)
+        # A backend that has been (re)started is live again; resume paths rely
+        # on this, so a suspend/resume cycle does not leave ``stopped`` latched.
+        self.stopped = False
         return self.screen
 
     def newpad(self, rows: int, cols: int) -> Surface:

{console_window-2.0.0.6 → console_window-2.0.0.8}/console_window/window.py

@@ -74,6 +74,14 @@ _PASSTHROUGH_EDITING_KEYS = frozenset({
 _WINDOWS: weakref.WeakValueDictionary = weakref.WeakValueDictionary()
 _WINDOW_IDS = itertools.count()
 
+# Windows that have left curses mode (endwin) but are still resumable.  A
+# strong reference is deliberate: the live registry is weak, and a suspended
+# window must survive until resume_curses()/start_curses() reattaches it.  The
+# screen itself is not kept here: in singleton mode the screen's owner stays
+# reachable through ``static_win``/``_static_backend`` (``static_scr`` is None
+# while suspended), and a per-instance window keeps its own backend handle.
+_SUSPENDED: list[ConsoleWindow] = []
+
 # None until the first ConsoleWindow is constructed.  The value is process-wide
 # and deliberately never reset: ConsoleWindow(singleton=...) must agree on every
 # construction or the assertion in __init__ fires.
@@ -136,6 +144,14 @@ class _StopCurses:
     ``ConsoleWindow.stop_curses()``; the per-instance model needs the bound
     window.  A descriptor distinguishes the two call shapes, which a plain
     method with ``self=None`` cannot do without lying to type checkers.
+
+    Semantics depend on the window model:
+
+    * singleton (the pre-2.0 model): ``stop_curses()`` *suspends* the shared
+      screen and ``start_curses()`` resumes it, which keeps the historical
+      stop/start pair working.  Use ``stop_all()`` for a permanent teardown.
+    * per-instance: ``stop_curses()`` is a permanent teardown; use
+      ``suspend_curses()``/``resume_curses()`` to pause and continue.
     """
 
     def __get__(self, obj: ConsoleWindow | None,
@@ -261,6 +277,11 @@ class ConsoleWindow:
         # drawing API is described by CursesSurface, which is only a cast target
         # (curses.window and HeadlessBackend's no-op surface both satisfy it at
         # runtime).  This keeps addstr/border/insstr/... type-checked.
+        if self.singleton and _SUSPENDED:
+            # A suspended shared screen must be resumed before another window
+            # can join it; otherwise the new window would draw into a terminal
+            # that is still in shell mode.
+            ConsoleWindow._resume_singleton()
         if self.singleton and ConsoleWindow.static_scr is not None:
             # Singleton mode: every instance draws through the process screen
             # and the backend that owns it, even if a different backend was
@@ -270,7 +291,7 @@ class ConsoleWindow:
             self._backend = ConsoleWindow._static_backend or self._backend
             self.scr = ConsoleWindow.static_scr
         else:
-            self.scr = self._start_curses()
+            self.scr = self._new_screen()
             if self.singleton:
                 ConsoleWindow.static_scr = self.scr
                 ConsoleWindow._static_backend = self._backend
@@ -345,6 +366,10 @@ class ConsoleWindow:
         # created but unreachable (the view snapped back to the last pickable
         # row every frame).
         self.free_scroll = False
+        # True between suspend_curses() and resume_curses()/start_curses(): the
+        # terminal was handed back (endwin) but the pads and content model stay
+        # valid, so the window can be reattached to a screen later.
+        self.suspended = False
         self.rows, self.cols = 0, 0
         self.body_cols, self.body_rows = self.opts.body_cols, self.opts.body_rows
         self.scroll_view_size = 0  # no. viewable lines of the body
@@ -556,13 +581,112 @@ class ConsoleWindow:
 
         return True
 
-    def _start_curses(self) -> CursesSurface:
+    def _new_screen(self) -> CursesSurface:
+        """Create and initialise a brand-new screen for this window."""
         return self._init_screen(self._backend, self.theme)
 
+    def _start_curses(self) -> CursesSurface:
+        """Re-enter curses for this window and return the live screen.
+
+        Pre-2.0 exposed ``_start_curses()`` as the "come back after
+        ``stop_curses()``" call, and applications (psistat among them) kept
+        calling it on the instance.  It therefore has to *reattach* the
+        window, not merely create a screen: the old implementation returned a
+        fresh screen without storing it, so ``self.scr`` stayed ``None`` and
+        the first ``clear()``/``render()`` after returning from shell mode
+        raised ``AttributeError: 'NoneType' object has no attribute 'clear'``.
+
+        A suspended window resumes through :meth:`resume_curses` (in singleton
+        mode that reattaches every window sharing the screen), so the pads and
+        the content model survive.  ``start_curses()`` remains the class-level
+        entry point for both models.
+        """
+        if self.suspended:
+            scr = self.resume_curses()
+            if scr is not None:
+                return scr
+        if self.scr is not None:
+            return self.scr
+        # Not suspended but screen-less: restart a screen and attach this
+        # window to it.  Singleton mode owns a process-wide screen, so reuse the
+        # class-level starter; per-instance windows create their own.
+        scr = ConsoleWindow.start_curses() if self.singleton else self._new_screen()
+        if self.scr is None:  # start_curses() may have reattached it already
+            backend = (ConsoleWindow._static_backend if self.singleton else None) \
+                or self._backend
+            self._attach_screen(scr, backend)
+        return scr
+
+    def _attach_screen(self, scr: CursesSurface, backend: RenderBackend) -> None:
+        """Point this window at a (re)started screen and force a full repaint.
+
+        Used by resume_curses()/start_curses() after a suspend.  The content
+        model and pads survive ``endwin()``; only the screen handle, the
+        backend that owns it, the dimensions, the pad backgrounds and the
+        redraw bookkeeping have to be refreshed.
+        """
+        self._backend = backend
+        self.scr = scr
+        self.suspended = False
+        _register_window(self)
+        self.calc()  # dimensions + pad reallocation through the new backend
+        self._set_scr_timeout(self._scr_timeout_ms)
+        for ns in (self.head, self.body):
+            self._apply_pad_theme(cast(CursesSurface, ns.pad))
+        self._mark_pads_for_redraw()
+        self._pick_clear_pending = True
+
+    def suspend_curses(self) -> None:
+        """Leave curses mode without destroying this window.
+
+        ``endwin()`` restores the terminal but keeps the curses SCREEN (and
+        therefore the pads) alive, so the next :meth:`resume_curses` can
+        reattach a screen and the next ``render()`` repaints.  In singleton
+        mode all windows share one screen, so this suspends them together.
+        Use :meth:`stop_curses` when the window is finished for good.
+        """
+        if getattr(self, 'singleton', False):
+            ConsoleWindow._suspend_singleton()
+            return
+        scr = getattr(self, 'scr', None)
+        if scr is None or self.suspended:
+            return
+        try:
+            backend = getattr(self, '_backend', None) or CursesBackend()
+            backend.stop(scr)
+        finally:
+            self.scr = cast(CursesSurface, None)
+            self.suspended = True
+            _unregister_window(self)
+            signals.teardown_ctrl_c()
+
+    def resume_curses(self) -> CursesSurface | None:
+        """Re-enter curses after :meth:`suspend_curses`.
+
+        Returns the (new) screen, or None when the window was not suspended.
+        The next ``render()`` repaints from the preserved content model.
+        """
+        if getattr(self, 'singleton', False):
+            return ConsoleWindow._resume_singleton()
+        if not self.suspended:
+            return self.scr
+        backend = getattr(self, '_backend', None) or CursesBackend()
+        scr = self._init_screen(backend, self.theme)
+        self._attach_screen(scr, backend)
+        return scr
+
     @classmethod
     def start_curses(cls, backend: RenderBackend | None = None) -> CursesSurface:
         # Legacy class-level entry point: in singleton mode it shares the one
-        # process screen rather than starting a second terminal session.
+        # process screen rather than starting a second terminal session.  When
+        # windows were suspended by stop_curses()/suspend_curses(), this is the
+        # matching resume: every suspended window is reattached to the screen
+        # (the backend argument is ignored then -- the screen belongs to the
+        # backend that created it).
+        if _SINGLETON_MODE and _SUSPENDED:
+            scr = cls._resume_singleton()
+            if scr is not None:
+                return scr
         if _SINGLETON_MODE and cls.static_scr is not None:
             return cls.static_scr
         screen_backend = backend if backend is not None else CursesBackend()
@@ -573,6 +697,45 @@ class ConsoleWindow:
             cls._static_backend = screen_backend
         return scr
 
+    @classmethod
+    def _suspend_singleton(cls) -> None:
+        """Leave the shared screen, keeping every window resumable."""
+        scr = cls.static_scr
+        if scr is None:
+            return
+        backend = cls._static_backend or CursesBackend()
+        windows = list(_WINDOWS.values())
+        try:
+            backend.stop(scr)
+        finally:
+            cls.static_scr = None
+            for win in windows:
+                win.scr = cast(CursesSurface, None)
+                win.suspended = True
+                _unregister_window(win)
+                signals.teardown_ctrl_c()
+                if win not in _SUSPENDED:
+                    _SUSPENDED.append(win)
+            # static_win is deliberately kept: it is the anchor that
+            # start_curses()/resume_curses() uses to restore the theme and is
+            # replaced by the next singleton window construction.
+
+    @classmethod
+    def _resume_singleton(cls) -> CursesSurface | None:
+        """Re-enter the shared screen and reattach every suspended window."""
+        if not _SUSPENDED:
+            return cls.static_scr
+        backend = cls._static_backend or CursesBackend()
+        anchor = cls.static_win
+        scr = cls._init_screen(backend, anchor.theme if anchor is not None else None)
+        cls.static_scr = scr
+        cls._static_backend = backend
+        windows = list(_SUSPENDED)
+        del _SUSPENDED[:]
+        for win in windows:
+            win._attach_screen(scr, backend)  # pylint: disable=protected-access
+        return scr
+
     @staticmethod
     def _install_theme(backend: RenderBackend, scr: CursesSurface,
                        theme_name: str | None) -> str:
@@ -634,25 +797,31 @@ class ConsoleWindow:
             self._pick_clear_pending = True
 
     def _stop_instance(self) -> None:
-        """Stop this window (and, in singleton mode, the shared screen)."""
+        """Stop this window (and, in singleton mode, suspend the shared screen)."""
         if getattr(self, 'singleton', False):
-            self._stop_singleton()
+            # Backward compatibility: in singleton mode the legacy
+            # stop_curses()/start_curses() pair is a suspend/resume pair, so
+            # stop_curses() leaves the screen resumable.  stop_all() is the
+            # permanent teardown.
+            ConsoleWindow._suspend_singleton()
             return
 
         scr = getattr(self, 'scr', None)
         if scr is None:
+            self.suspended = False
             return
         try:
             backend = getattr(self, '_backend', None) or CursesBackend()
             backend.stop(scr)
         finally:
             self.scr = cast(CursesSurface, None)
+            self.suspended = False
             _unregister_window(self)
             signals.teardown_ctrl_c()
 
     @classmethod
     def _stop_legacy(cls) -> None:
-        """The pre-2.0 ``ConsoleWindow.stop_curses()`` call."""
+        """The pre-2.0 ``ConsoleWindow.stop_curses()`` call (suspends in singleton mode)."""
         assert _SINGLETON_MODE is not False, (
             'ConsoleWindow.stop_curses() without an instance is only valid '
             'in singleton mode; use win.stop_curses() or ConsoleWindow.stop_all()')
@@ -662,24 +831,31 @@ class ConsoleWindow:
 
     @classmethod
     def _stop_singleton(cls) -> None:
-        """Tear down the shared screen and mark every window stopped."""
+        """Tear down the shared screen and forget every window (including suspended)."""
         scr = ConsoleWindow.static_scr
-        if scr is None:
-            return
-        backend = ConsoleWindow._static_backend or CursesBackend()
         windows = list(_WINDOWS.values())
+        suspended = list(_SUSPENDED)
+        del _SUSPENDED[:]
         ConsoleWindow.static_scr = None
         ConsoleWindow.static_win = None
+        backend = ConsoleWindow._static_backend
         ConsoleWindow._static_backend = None
-        for win in windows:
+        for win in windows + suspended:
             win.scr = cast(CursesSurface, None)
+            win.suspended = False
+        if scr is None:
+            # Already in shell mode (all windows suspended); nothing to end,
+            # but the suspended windows still have to be forgotten.
+            for win in windows + suspended:
+                _unregister_window(win)
+            return
         try:
-            backend.stop(scr)
+            (backend or CursesBackend()).stop(scr)
         finally:
             # One teardown per window, matching the per-window setup in
             # _init_screen: the SIGINT handler is only restored once the last
             # live window is gone (AUDIT.md §3.1).
-            for win in windows:
+            for win in windows + suspended:
                 _unregister_window(win)
                 signals.teardown_ctrl_c()
 
@@ -704,6 +880,10 @@ class ConsoleWindow:
 
     @classmethod
     def stop_all(cls) -> None:
+        """Permanently tear down every window (the atexit hook)."""
+        if _SINGLETON_MODE:
+            cls._stop_singleton()
+            return
         for win in cls.active_windows():
             win.stop_curses()
 
@@ -2002,7 +2182,12 @@ class ConsoleWindow:
         pad.refresh(scroll_top, 0, row0 + 1, col0 + 1, row0 + visible_rows, col9 - 1)
 
     def clear(self) -> None:
-        self.scr.clear()
+        # A suspended window has no screen handle until resume_curses()/
+        # start_curses(); the content model still has to be reset so the next
+        # repaint is complete.  Calling clear() while suspended used to raise
+        # AttributeError on self.scr.
+        if self.scr is not 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()

{console_window-2.0.0.6 → console_window-2.0.0.8}/tests/test_backend.py

@@ -259,7 +259,7 @@ def test_theme_broadcast_reaches_all_windows():
         second.stop_curses()
 
 
-def test_singleton_mode_shares_the_process_screen_and_tears_down_globally():
+def test_singleton_mode_shares_the_process_screen():
     # Singleton mode is process-wide, so prove it in a fresh interpreter rather
     # than perturb the per-instance mode this test session has latched.
     code = '''
@@ -276,7 +276,7 @@ assert ConsoleWindow.static_scr is first.scr
 assert second.scr is first.scr
 assert ConsoleWindow.static_win is second
 assert ConsoleWindow.primary_window() is second
-ConsoleWindow.stop_curses()   # the pre-2.0 unbound call
+ConsoleWindow.stop_all()   # permanent teardown
 assert first.scr is None and second.scr is None
 assert ConsoleWindow.static_scr is None and ConsoleWindow.static_win is None
 assert first_backend.stopped is True
@@ -285,6 +285,154 @@ assert ConsoleWindow.active_windows() == []
     subprocess.run([sys.executable, '-c', code], check=True)
 
 
+def test_singleton_stop_curses_suspends_and_start_curses_resumes():
+    # The pre-2.0 stop_curses()/start_curses() pair must keep working: in
+    # singleton mode it is a suspend/resume pair, not a one-way teardown.
+    code = '''
+from console_window.backend import HeadlessBackend
+from console_window.opts import ConsoleWindowOpts
+from console_window.window import ConsoleWindow
+
+first_backend = HeadlessBackend()
+first = ConsoleWindow(opts=ConsoleWindowOpts(body_rows=3, head_rows=2),
+                      backend=first_backend, singleton=True)
+second = ConsoleWindow(opts=ConsoleWindowOpts(body_rows=3, head_rows=2),
+                       backend=HeadlessBackend())
+first.add_body('kept across the suspend')
+old_screen = first.scr
+
+ConsoleWindow.stop_curses()   # the pre-2.0 unbound call: suspend
+assert first_backend.stopped is True
+assert first.scr is None and second.scr is None
+assert first.suspended and second.suspended
+assert ConsoleWindow.static_scr is None
+assert ConsoleWindow.active_windows() == []
+# static_win is kept as the resume anchor.
+assert ConsoleWindow.static_win is second
+
+scr = ConsoleWindow.start_curses()   # matching resume
+assert scr is not None
+assert ConsoleWindow.static_scr is scr
+assert first.scr is scr and second.scr is scr
+assert not first.suspended and not second.suspended
+assert first_backend.stopped is False
+assert ConsoleWindow.active_windows() == [first, second]
+# The content model and pads survived endwin().
+assert first.body.texts == ['kept across the suspend']
+assert first.body.pad is not None
+
+ConsoleWindow.stop_all()   # permanent teardown
+assert first.scr is None and second.scr is None
+assert ConsoleWindow.static_scr is None and ConsoleWindow.static_win is None
+assert ConsoleWindow.active_windows() == []
+'''
+    subprocess.run([sys.executable, '-c', code], check=True)
+
+
+def test_per_instance_suspend_and_resume_curses():
+    backend = HeadlessBackend()
+    win = _make(backend)
+    try:
+        win.add_body('kept across the suspend')
+        win.suspend_curses()
+        assert win.suspended is True
+        assert win.scr is None
+        assert backend.stopped is True
+        assert win not in ConsoleWindow.active_windows()
+
+        scr = win.resume_curses()
+        assert scr is not None
+        assert win.scr is scr
+        assert win.suspended is False
+        assert backend.stopped is False
+        assert win in ConsoleWindow.active_windows()
+        assert win.body.texts == ['kept across the suspend']
+        # A second resume is a no-op that returns the live screen.
+        assert win.resume_curses() is scr
+    finally:
+        win.stop_curses()
+    assert win.scr is None
+    assert win not in ConsoleWindow.active_windows()
+
+
+def test_clear_while_suspended_only_resets_the_content_model():
+    # A suspended window has no screen, but clear() must still work: the next
+    # repaint after resume comes from the content model, not a stale screen.
+    backend = HeadlessBackend()
+    win = _make(backend)
+    try:
+        win.add_body('old row')
+        win.suspend_curses()
+        win.clear()  # regression: raised AttributeError on self.scr
+        assert win.body.texts == []
+        assert win.scr is None
+        win.add_body('new row')
+        scr = win._start_curses()
+        assert win.scr is scr
+        assert win.body.texts == ['new row']
+        win.clear()  # the live screen is cleared again
+        assert scr.calls_named('clear')
+    finally:
+        win.stop_curses()
+
+
+def test_legacy_instance_start_curses_reattaches_after_suspend():
+    # psistat's dump/return path calls self.window._start_curses() (the 1.4.x
+    # hook that was kept as a compatibility method).  It must leave the window
+    # usable, not create a screen and leave self.scr as None.
+    backend = HeadlessBackend()
+    win = _make(backend)
+    try:
+        win.add_body('kept across the dump')
+        win.suspend_curses()
+        assert win.scr is None and win.suspended
+
+        scr = win._start_curses()
+        assert scr is not None
+        assert win.scr is scr
+        assert win.suspended is False
+        assert win in ConsoleWindow.active_windows()
+        assert win.body.texts == ['kept across the dump']
+        win.clear()   # the call that crashed psistat after returning
+        assert scr.calls_named('clear')
+        win.add_body('after clear')
+    finally:
+        win.stop_curses()
+    assert win.scr is None
+
+
+def test_singleton_legacy_instance_start_curses_resumes_shared_screen():
+    # Same compatibility hook, but in the pre-2.0 singleton model, where
+    # stop_curses() suspends the shared screen rather than tearing it down.
+    code = '''
+from console_window.backend import HeadlessBackend
+from console_window.opts import ConsoleWindowOpts
+from console_window.window import ConsoleWindow
+
+backend = HeadlessBackend()
+win = ConsoleWindow(opts=ConsoleWindowOpts(body_rows=3, head_rows=2),
+                    backend=backend, singleton=True)
+win.add_body('kept across the dump')
+win.stop_curses()                 # pre-2.0 call: suspend
+assert win.scr is None and win.suspended
+
+scr = win._start_curses()         # psistat's "come back" call
+assert scr is not None
+assert win.scr is scr
+assert ConsoleWindow.static_scr is scr
+assert win.suspended is False
+assert win in ConsoleWindow.active_windows()
+assert win.body.texts == ['kept across the dump']
+win.clear()
+assert scr.calls_named('clear')
+win.add_body('after clear')
+
+ConsoleWindow.stop_all()          # permanent teardown
+assert win.scr is None and ConsoleWindow.static_scr is None
+'''
+    subprocess.run([sys.executable, '-c', code], check=True)
+
+
 def test_mixing_singleton_modes_asserts():
     code = '''
 from console_window.backend import HeadlessBackend