smartcli-toolkit 0.1.0__tar.gz → 0.1.2__tar.gz

{smartcli_toolkit-0.1.0 → smartcli_toolkit-0.1.2}/PKG-INFO

@@ -1,8 +1,28 @@
 Metadata-Version: 2.4
 Name: smartcli-toolkit
-Version: 0.1.0
+Version: 0.1.2
 Summary: Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core).
+Author: dwgx
 License-Expression: MIT
+Project-URL: Homepage, https://github.com/dwgx/SmartCLI
+Project-URL: Repository, https://github.com/dwgx/SmartCLI
+Project-URL: Changelog, https://github.com/dwgx/SmartCLI/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/dwgx/SmartCLI/issues
+Project-URL: PyPI, https://pypi.org/project/smartcli-toolkit/
+Keywords: terminal,tui,pty,ansi,cli,ascii-art,terminal-effects,claude-skill,pyte,conpty
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Terminals
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Environment :: Console
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -66,7 +86,7 @@ works today from a clean clone.
 **Primary — reproduce the full dev environment** (recommended):
 
 ```bash
-git clone <repo-url> SmartCLI
+git clone https://github.com/dwgx/SmartCLI SmartCLI
 cd SmartCLI
 python -m pip install -r requirements.txt
 ```

{smartcli_toolkit-0.1.0 → smartcli_toolkit-0.1.2}/README.md

@@ -44,7 +44,7 @@ works today from a clean clone.
 **Primary — reproduce the full dev environment** (recommended):
 
 ```bash
-git clone <repo-url> SmartCLI
+git clone https://github.com/dwgx/SmartCLI SmartCLI
 cd SmartCLI
 python -m pip install -r requirements.txt
 ```

{smartcli_toolkit-0.1.0 → smartcli_toolkit-0.1.2}/pyproject.toml

@@ -30,7 +30,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "smartcli-toolkit"
-version = "0.1.0"
+version = "0.1.2"
 description = "Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core)."
 readme = "README.md"
 license = "MIT"
@@ -40,6 +40,41 @@ license-files = ["LICENSE"]
 # No match/case and no runtime `X | Y` types are used, so nothing forces higher.
 requires-python = ">=3.9"
 
+authors = [{name = "dwgx"}]
+
+keywords = [
+    "terminal",
+    "tui",
+    "pty",
+    "ansi",
+    "cli",
+    "ascii-art",
+    "terminal-effects",
+    "claude-skill",
+    "pyte",
+    "conpty",
+]
+
+# Real PyPI trove classifiers. NOTE: no `License ::` classifier is listed on
+# purpose — with the PEP 639 SPDX `license = "MIT"` field above, setuptools
+# (77+) treats a license trove classifier as redundant/conflicting and errors
+# out. The SPDX field is the single source of truth for licensing.
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Terminals",
+    "Topic :: Software Development :: Libraries",
+    "Environment :: Console",
+]
+
 # REQUIRED runtime deps (mirror requirements.txt). pyte is a hard top-level
 # import; pywinpty is imported only on the Windows PTY backend path, hence the
 # environment marker. POSIX uses the stdlib `pty` backend (no extra package).
@@ -48,6 +83,13 @@ dependencies = [
     "pywinpty>=2.0; platform_system == 'Windows'",
 ]
 
+[project.urls]
+Homepage = "https://github.com/dwgx/SmartCLI"
+Repository = "https://github.com/dwgx/SmartCLI"
+Changelog = "https://github.com/dwgx/SmartCLI/blob/main/CHANGELOG.md"
+Issues = "https://github.com/dwgx/SmartCLI/issues"
+PyPI = "https://pypi.org/project/smartcli-toolkit/"
+
 [project.optional-dependencies]
 # All guarded imports with pure-stdlib fallbacks — none required to run.
 art = ["pyfiglet>=1.0.0"]        # real FIGlet fonts (else built-in block font)

{smartcli_toolkit-0.1.0 → smartcli_toolkit-0.1.2}/smartcli_core/__init__.py

@@ -9,9 +9,13 @@ Quick start::
 
     with PtySession(cols=100, rows=30) as sess:
         sess.start("python")
-        sess.wait_ready(marker=r">>> $")
+        # NOTE: pyte right-pads every screen line with spaces, so an end-anchored
+        # marker like r">>> $" never matches. Use an unanchored marker (or r">>> *$"
+        # with re.M). wait_ready also races screen-stability, so pass a real marker
+        # for a known first prompt rather than relying on STABLE on startup.
+        sess.wait_ready(marker=r">>> ")
         sess.send_line("print('hello')")
-        reason, snap = sess.wait_ready(marker=r">>> $")
+        reason, snap = sess.wait_ready(marker=r">>> ")
         print(snap.to_text())
 """
 
@@ -50,4 +54,4 @@ __all__ = [
     "KEY_MAP",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

{smartcli_toolkit-0.1.0 → smartcli_toolkit-0.1.2}/smartcli_core/pty_backend.py

@@ -75,6 +75,14 @@ class WinptyBackend(PtyBackend):
     def spawn(self, cmd: Union[str, Sequence[str]], cols: int, rows: int) -> None:
         import winpty  # imported lazily so non-Windows hosts don't require it
 
+        # Reset per-spawn state so a re-used backend (a second spawn on the same
+        # instance) does not inherit the previous child's EOF sentinel or latched
+        # _eof — otherwise read_nonblocking would stop draining at the stale None
+        # and consumers would see premature EOF. A fresh queue drops any leftover.
+        self._queue = queue.Queue()
+        self._eof = False
+        self._reader = None
+
         # winpty.spawn accepts a command string or an argv list; dimensions are
         # (rows, cols).
         self._proc = winpty.PtyProcess.spawn(cmd, dimensions=(rows, cols))

{smartcli_toolkit-0.1.0 → smartcli_toolkit-0.1.2}/smartcli_core/readiness.py

@@ -41,6 +41,7 @@ def wait_until_stable(
     max_wait_ms: int = 8000,
     grace_ms: int = 40,
     min_wait_ms: int = 0,
+    blank_hash: Optional[int] = None,
 ) -> bool:
     """Pump reads until the screen hash is unchanged for ``quiet_ms``.
 
@@ -71,22 +72,32 @@ def wait_until_stable(
     deadline = start + (max_wait_ms / 1000.0)
     last_hash: Optional[int] = None
     stable_since: Optional[float] = None
+    # Readiness gate: never declare stable on a never-painted BLANK screen. Only
+    # engages when the caller passes ``blank_hash`` (the construct-time all-blank
+    # baseline) AND no output has been seen this wait AND the screen still equals
+    # that baseline. Default (blank_hash=None) is byte-for-byte the old behavior,
+    # so an already-drawn screen that is genuinely static still settles.
+    seen_any = False
 
     while True:
         now = time.monotonic()
         data = read_fn()
+        if data:
+            seen_any = True
         h = get_screen_hash_fn()
         elapsed = now - start
+        blank = (not seen_any and blank_hash is not None and h == blank_hash)
 
         if not data and h == last_hash:
             if stable_since is None:
                 stable_since = now
-            elif (now - stable_since) >= quiet and elapsed >= min_wait:
+            elif (now - stable_since) >= quiet and elapsed >= min_wait and not blank:
                 if grace > 0:
                     time.sleep(grace)
                 tail = read_fn()
                 if tail:
                     # late flush: resume waiting
+                    seen_any = True
                     stable_since = None
                     last_hash = get_screen_hash_fn()
                     continue
@@ -156,6 +167,7 @@ def wait_ready(
     min_wait_ms: int = 50,
     grace_ms: int = 40,
     flags: int = 0,
+    blank_hash: Optional[int] = None,
 ) -> Tuple[str, object]:
     """Unified wait: satisfy on ``marker`` OR screen stability, capped by max_wait.
 
@@ -177,10 +189,16 @@ def wait_ready(
     deadline = start + (max_wait_ms / 1000.0)
     last_hash: Optional[int] = None
     stable_since: Optional[float] = None
+    # Readiness gate (see wait_until_stable): a marker match is never gated —
+    # only the stability branch refuses to fire on a never-painted blank screen
+    # when the caller supplies the blank baseline. Default None = old behavior.
+    seen_any = False
 
     while True:
         now = time.monotonic()
         data = read_fn()
+        if data:
+            seen_any = True
         elapsed = now - start
 
         # 1) marker wins immediately (respect min_wait)
@@ -189,14 +207,16 @@ def wait_ready(
 
         # 2) stability
         h = get_screen_hash_fn()
+        blank = (not seen_any and blank_hash is not None and h == blank_hash)
         if not data and h == last_hash:
             if stable_since is None:
                 stable_since = now
-            elif (now - stable_since) >= quiet and elapsed >= min_wait:
+            elif (now - stable_since) >= quiet and elapsed >= min_wait and not blank:
                 if grace > 0:
                     time.sleep(grace)
                 tail = read_fn()
                 if tail:
+                    seen_any = True
                     stable_since = None
                     last_hash = get_screen_hash_fn()
                     continue

{smartcli_toolkit-0.1.0 → smartcli_toolkit-0.1.2}/smartcli_core/session.py

@@ -6,10 +6,12 @@
 
     sess = PtySession(cols=100, rows=30)
     sess.start("python")
-    sess.wait_ready(marker=r">>> $")
+    # Use an unanchored marker: pyte space-pads every line, so r">>> $" never
+    # matches (use r">>> " or r">>> *$" with re.M).
+    sess.wait_ready(marker=r">>> ")
     sess.send_text("print('hi')")
     sess.send_keys(["Enter"])
-    snap = sess.wait_ready(marker=r">>> $")[1]
+    snap = sess.wait_ready(marker=r">>> ")[1]
     print(snap.to_text())
     sess.close()
 
@@ -113,6 +115,10 @@ class PtySession:
         self.rows = rows
         self.backend: PtyBackend = backend or get_default_backend()
         self.model = ScreenModel(cols, rows)
+        # Baseline hash of the freshly-constructed (all-blank) screen. Passed to
+        # the readiness waits so they never declare STABLE on a never-painted
+        # screen during a startup quiet-gap. Recomputed on resize.
+        self._blank_hash = self.model.content_hash()
         self._started = False
 
     # -- lifecycle ---------------------------------------------------------
@@ -142,6 +148,9 @@ class PtySession:
         self.rows = rows
         self.backend.resize(cols, rows)
         self.model.resize(cols, rows)
+        # Blank baseline for the new dimensions (only used by the readiness gate
+        # before any output has been seen).
+        self._blank_hash = ScreenModel(cols, rows).content_hash()
 
     # -- io ----------------------------------------------------------------
 
@@ -200,6 +209,7 @@ class PtySession:
             min_wait_ms=min_wait_ms,
             grace_ms=grace_ms,
             flags=flags,
+            blank_hash=self._blank_hash,
         )
         return reason, snap  # type: ignore[return-value]
 
@@ -220,6 +230,7 @@ class PtySession:
             max_wait_ms=max_wait_ms,
             grace_ms=grace_ms,
             min_wait_ms=min_wait_ms,
+            blank_hash=self._blank_hash,
         )
 
     def wait_for(

{smartcli_toolkit-0.1.0 → smartcli_toolkit-0.1.2}/smartcli_toolkit.egg-info/PKG-INFO

@@ -1,8 +1,28 @@
 Metadata-Version: 2.4
 Name: smartcli-toolkit
-Version: 0.1.0
+Version: 0.1.2
 Summary: Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core).
+Author: dwgx
 License-Expression: MIT
+Project-URL: Homepage, https://github.com/dwgx/SmartCLI
+Project-URL: Repository, https://github.com/dwgx/SmartCLI
+Project-URL: Changelog, https://github.com/dwgx/SmartCLI/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/dwgx/SmartCLI/issues
+Project-URL: PyPI, https://pypi.org/project/smartcli-toolkit/
+Keywords: terminal,tui,pty,ansi,cli,ascii-art,terminal-effects,claude-skill,pyte,conpty
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Terminals
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Environment :: Console
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -66,7 +86,7 @@ works today from a clean clone.
 **Primary — reproduce the full dev environment** (recommended):
 
 ```bash
-git clone <repo-url> SmartCLI
+git clone https://github.com/dwgx/SmartCLI SmartCLI
 cd SmartCLI
 python -m pip install -r requirements.txt
 ```

{smartcli_toolkit-0.1.0 → smartcli_toolkit-0.1.2}/smartcli_toolkit.egg-info/SOURCES.txt

@@ -11,4 +11,7 @@ smartcli_toolkit.egg-info/PKG-INFO
 smartcli_toolkit.egg-info/SOURCES.txt
 smartcli_toolkit.egg-info/dependency_links.txt
 smartcli_toolkit.egg-info/requires.txt
-smartcli_toolkit.egg-info/top_level.txt
+smartcli_toolkit.egg-info/top_level.txt
+tests/test_degenerate_inputs.py
+tests/test_fx_contract.py
+tests/test_readiness.py

smartcli_toolkit-0.1.2/tests/test_degenerate_inputs.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python
+"""test_degenerate_inputs.py — regression locks for the degenerate-input crashes
+found by the fx/tui-ui defect review (all in skill code, not smartcli_core).
+
+Each check reproduces an input that used to raise (ZeroDivisionError / IndexError
+/ ValueError) and asserts it now degrades gracefully instead of crashing. Fast,
+no PTY, no animation loop.
+
+Run:  python tests/test_degenerate_inputs.py   (exit 0 = pass)
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(_ROOT / "skills" / "tui-ui"))
+sys.path.insert(0, str(_ROOT / "skills" / "cmd-art"))
+
+_fails = []
+
+
+def check_no_raise(fn, name):
+    try:
+        fn()
+        print(f"[PASS] {name}")
+    except Exception as e:  # noqa: BLE001 - we are asserting NO exception
+        print(f"[FAIL] {name}  raised {type(e).__name__}: {e}")
+        _fails.append(name)
+
+
+def check(cond, name, detail=""):
+    print(f"{'[PASS]' if cond else '[FAIL]'} {name}  {detail}")
+    if not cond:
+        _fails.append(name)
+
+
+def main() -> int:
+    from ui.field import Ripple
+    from ui.widgets_ext.slider_track import SliderTrack
+    from ui.widgets_ext.braille_chart import BrailleChart
+    from fx.base import Param
+
+    print("=" * 60)
+    print("degenerate-input regression locks")
+    print("=" * 60)
+
+    # field.Ripple degenerate params (were ZeroDivisionError / IndexError)
+    check_no_raise(lambda: Ripple(origin=(0, 0), wavelength=0.0, travel=10.0).sample(1, 1),
+                   "Ripple wavelength=0 does not divide-by-zero")
+    check_no_raise(lambda: Ripple(origin=(0, 0), wavelength=20.0, travel=10.0,
+                                  falloff_radius=0.0).sample(1, 1),
+                   "Ripple falloff_radius=0 does not divide-by-zero")
+    check_no_raise(lambda: Ripple(origin=(0, 0), wavelength=20.0, travel=10.0,
+                                  palette=[]).sample(0, 0),
+                   "Ripple empty palette does not IndexError")
+
+    # SliderTrack empty positions list (was ValueError max()/IndexError)
+    check_no_raise(lambda: SliderTrack(["a", "b"], positions=[]).measure(20, 3),
+                   "SliderTrack positions=[] measure does not crash")
+    check_no_raise(lambda: SliderTrack(["a", "b"], positions=[]).render(20, 3),
+                   "SliderTrack positions=[] render does not crash")
+
+    # BrailleChart NaN in series (was ValueError NaN->int)
+    check_no_raise(lambda: BrailleChart([float("nan"), 1, 2]).render(10, 3),
+                   "BrailleChart NaN in series does not crash")
+
+    # Param int coercion: zero-padded decimals work; hex kept; bad input clean err
+    p = Param("count", "int")
+    check(p.coerce("08") == 8, "Param int '08' -> 8 (not base-0 ValueError)", f"={p.coerce('08')}")
+    check(p.coerce("010") == 10, "Param int '010' -> 10", f"={p.coerce('010')}")
+    check(p.coerce("0x10") == 16, "Param int '0x10' -> 16 (hex preserved)", f"={p.coerce('0x10')}")
+    # sign symmetry: +0x/-0x both honored (a prior fix narrowed this by omitting +)
+    check(p.coerce("+0x10") == 16, "Param int '+0x10' -> 16 (plus-signed hex)", f"={p.coerce('+0x10')}")
+    check(p.coerce("-0x10") == -16, "Param int '-0x10' -> -16 (minus-signed hex)", f"={p.coerce('-0x10')}")
+    try:
+        p.coerce("abc")
+        check(False, "Param int 'abc' raises ValueError", "no error raised")
+    except ValueError as e:
+        check("count" in str(e) and "abc" in str(e),
+              "Param int 'abc' -> clean ValueError naming param+value", f"{e}")
+
+    print("-" * 60)
+    if _fails:
+        print(f"FAIL: {len(_fails)} check(s) failed: {_fails}")
+        return 1
+    print("PASS: all degenerate-input regression locks hold")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

smartcli_toolkit-0.1.2/tests/test_fx_contract.py

@@ -0,0 +1,267 @@
+"""Frame-contract test for the cmd-art fx framework (deterministic, no TTY).
+
+Every :class:`fx.base.Effect` is a PURE frame producer: ``render(ctx) -> str``
+must return a frame of EXACTLY ``ctx.height`` rows, and no row may be wider than
+``ctx.width`` display cells (a row wider than the frame is the "overflows at N
+cols" defect the terminal would wrap; a frame with the wrong row count is
+under/overfill). "Field"-style effects (fire, plasma, donut, ...) fill EVERY
+cell, so for those the width must equal ``ctx.width`` exactly.
+
+The live harness (verify_fx.py) proves effects RUN and keep the alt-screen /
+truecolor invariants, and probe.py checks row count + an *upper* width bound.
+Neither asserts the EXACT per-line cell width for the solid-fill effects, nor
+sweeps degenerate ctx sizes (tiny 1x1/2x2). This test closes that gap by
+rendering each effect at several sizes / frames and asserting the contract with
+the repo's AUTHORITATIVE display-width function (ui.core.width -- wcwidth-backed,
+ANSI-stripping, CJK/emoji aware -- the same measure the engine and pyte use).
+
+Contracts asserted (HARD -> non-zero exit):
+  C1 row count == ctx.height           for ALL effects at ALL sizes.
+  C2 no row wider than ctx.width        for ALL effects at REALISTIC sizes.
+  C3 every row width == ctx.width       for SOLID (full-fill) effects, at
+                                        realistic + narrow + tiny sizes.
+  C4 render() never raises              for ALL effects at tiny (1x1/2x2) sizes.
+  C5 no UNEXPECTED narrow overflow      at (20,8): only the documented
+                                        allowlist below may exceed width.
+
+SOFT (reported, never fails a correct shipped build):
+  * known narrow-width overflow of the sparse text effects (see allowlist),
+  * width defects at the degenerate tiny sizes (1x1/2x2), which some effects
+    legitimately cannot honour (e.g. image2ascii's 2-cell half-block glyph).
+
+Usage: python tests/test_fx_contract.py [name ...]   (default: everything)
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+sys.path.insert(0, str(ROOT / "skills" / "cmd-art"))
+sys.path.insert(0, str(ROOT / "skills" / "tui-ui"))
+
+import fx.registry as registry  # noqa: E402
+from fx.base import FrameCtx  # noqa: E402
+from fx.theme import get_theme  # noqa: E402
+
+# ---- authoritative display-cell width (same fn the engine + pyte agree on) ---
+# Reuse ui.core.width: strips ANSI/SGR then sums per-codepoint wcwidth (wide
+# glyphs = 2, combining/ZWJ = 0). Falling back to a matching local stripper only
+# if the tui-ui skill is somehow unavailable keeps this test self-contained.
+try:
+    from ui.core import width as visible_width  # type: ignore
+except Exception:  # pragma: no cover - tui-ui should always be importable
+    import re
+    import unicodedata
+
+    _ANSI_RE = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]")
+
+    def visible_width(s: str) -> int:  # type: ignore
+        s = _ANSI_RE.sub("", s)
+        w = 0
+        for ch in s:
+            o = ord(ch)
+            if o == 0 or unicodedata.combining(ch) or o in (0x200D, 0xFE0E, 0xFE0F):
+                continue
+            if o < 32 or 0x7F <= o < 0xA0:
+                continue
+            w += 2 if unicodedata.east_asian_width(ch) in ("W", "F") else 1
+        return w
+
+
+# --------------------------------------------------------------------------
+# Test matrix
+# --------------------------------------------------------------------------
+# Realistic frame sizes: the contract is HARD here.
+REALISTIC = [(80, 24), (120, 40), (40, 12)]
+# Narrow but real terminal: HARD row-count + curated overflow allowlist (C5).
+NARROW = [(20, 8)]
+# Degenerate/tiny: HARD row-count + no-crash; width is SOFT (reported only).
+TINY = [(2, 2), (1, 1)]
+
+# Effects whose rows are known to exceed ctx.width at the (20,8) narrow size,
+# because they emit text without clipping to ctx.width. This is a genuine
+# frame-contract weakness in the shipped effect (documented as a FINDING in the
+# report), NOT a test-measurement artifact -- the raw text really is wider than
+# the frame. Listed here so the test still PASSES on today's shipped build while
+# a hard gate guards against any *new* effect regressing the same way.
+KNOWN_NARROW_OVERFLOW = {"decrypt", "typewriter"}
+
+results: list[tuple[str, bool, str]] = []
+findings: list[str] = []
+
+
+def record(name: str, ok: bool, detail: str = "") -> None:
+    results.append((name, ok, detail))
+    print(f"{'PASS' if ok else 'FAIL'}  {name}" + (f"  -- {detail}" if detail else ""))
+
+
+def frames_for(cls) -> list[tuple[float, int]]:
+    """(t, frame_index) samples to render. Animated effects get a few frames to
+    catch frame-dependent raggedness; static effects only ever draw one frame."""
+    if cls.is_animated(cls.param_defaults()):
+        return [(0.0, 0), (0.7, 5), (3.1, 93)]
+    return [(0.7, 0)]
+
+
+def render(cls, w: int, h: int, t: float, fi: int) -> str:
+    """Build the ctx the CLI would and render ONE frame (mirrors probe.py /
+    fx.core.render_once: fresh instance, setup(), render(), teardown())."""
+    eff = cls()
+    eff.setup()
+    try:
+        ctx = FrameCtx(t=t, frame_index=fi, width=w, height=h,
+                       theme=get_theme(cls.preferred_theme),
+                       params=cls.param_defaults())
+        return eff.render(ctx)
+    finally:
+        try:
+            eff.teardown()
+        except Exception:
+            pass
+
+
+def _rows(frame: str) -> list[str]:
+    """Split a frame into its rows -- the AUTHORITATIVE row measure, identical to
+    probe.py's ``frame.split("\\n")``. The contract is "ctx.height rows joined by
+    newlines, NO trailing newline" (see fx.base), so a plain split yields exactly
+    ctx.height rows. We deliberately do NOT strip a trailing newline: sparse
+    effects pad with empty rows, so a frame can legitimately END in "\\n" where
+    that newline is the separator before a final empty row -- stripping it would
+    drop a real row and under-count the frame."""
+    return frame.split("\n")
+
+
+def _is_solid(cls) -> bool:
+    """A SOLID (full-fill) effect writes every cell, so every row is EXACTLY
+    ctx.width. Classified empirically at the canonical 80x24 across its frames:
+    if no row deviates from 80, it is a field/particle effect and must honour
+    the exact-width contract everywhere. Sparse text/banner/image effects (which
+    legitimately leave blank cells) are excluded from the exact-width gate."""
+    for (t, fi) in frames_for(cls):
+        for ln in _rows(render(cls, 80, 24, t, fi)):
+            if visible_width(ln) != 80:
+                return False
+    return True
+
+
+# --------------------------------------------------------------------------
+# Checks
+# --------------------------------------------------------------------------
+def check_rowcount(cls) -> None:
+    """C1: every rendered frame has EXACTLY ctx.height rows, at ALL sizes."""
+    for (w, h) in REALISTIC + NARROW + TINY:
+        for (t, fi) in frames_for(cls):
+            rows = _rows(render(cls, w, h, t, fi))
+            if len(rows) != h:
+                record(f"rowcount {cls.name}", False,
+                        f"{w}x{h} t={t}: {len(rows)} rows != {h}")
+                return
+    record(f"rowcount {cls.name}", True, "exact rows at every size")
+
+
+def check_no_overflow(cls) -> None:
+    """C2: no row wider than ctx.width at REALISTIC sizes (all effects)."""
+    for (w, h) in REALISTIC:
+        for (t, fi) in frames_for(cls):
+            for i, ln in enumerate(_rows(render(cls, w, h, t, fi))):
+                cw = visible_width(ln)
+                if cw > w:
+                    record(f"no-overflow {cls.name}", False,
+                            f"{w}x{h} t={t} row {i}: width {cw} > {w}")
+                    return
+    record(f"no-overflow {cls.name}", True, "no row exceeds width")
+
+
+def check_exact_width(cls) -> None:
+    """C3: SOLID effects fill every cell -> width == ctx.width, at realistic +
+    narrow + tiny sizes. Sparse effects are skipped (SOFT-reported elsewhere)."""
+    if not _is_solid(cls):
+        record(f"exact-width {cls.name}", True, "sparse effect (exact-width n/a)")
+        return
+    for (w, h) in REALISTIC + NARROW + TINY:
+        for (t, fi) in frames_for(cls):
+            for i, ln in enumerate(_rows(render(cls, w, h, t, fi))):
+                cw = visible_width(ln)
+                if cw != w:
+                    record(f"exact-width {cls.name}", False,
+                            f"{w}x{h} t={t} row {i}: width {cw} != {w}")
+                    return
+    record(f"exact-width {cls.name}", True, "every row == width (solid fill)")
+
+
+def check_narrow_allowlist(cls) -> None:
+    """C5: at the narrow (20,8) size, overflow is a HARD failure UNLESS the
+    effect is on the documented KNOWN_NARROW_OVERFLOW allowlist. This is the
+    regression gate that would catch a NEW effect emitting unclipped rows."""
+    for (w, h) in NARROW:
+        for (t, fi) in frames_for(cls):
+            for i, ln in enumerate(_rows(render(cls, w, h, t, fi))):
+                cw = visible_width(ln)
+                if cw > w:
+                    if cls.name in KNOWN_NARROW_OVERFLOW:
+                        findings.append(
+                            f"narrow overflow (known) {cls.name} {w}x{h} "
+                            f"t={t} row {i}: width {cw} > {w}")
+                        record(f"narrow {cls.name}", True,
+                                f"known overflow tolerated (row {i} width {cw}>{w})")
+                        return
+                    record(f"narrow {cls.name}", False,
+                            f"UNEXPECTED overflow {w}x{h} t={t} row {i}: "
+                            f"width {cw} > {w} (not in allowlist)")
+                    return
+    if cls.name in KNOWN_NARROW_OVERFLOW:
+        # allowlisted but no longer overflowing -> the effect was fixed; the
+        # allowlist is now stale (report so it can be tightened).
+        findings.append(f"allowlist stale: {cls.name} no longer overflows at 20x8")
+    record(f"narrow {cls.name}", True, "fits 20x8 (or known)")
+
+
+def check_tiny_no_crash(cls) -> None:
+    """C4: render() must not raise at degenerate 1x1 / 2x2 sizes. Width defects
+    at these sizes are SOFT (some effects legitimately can't honour 1x1)."""
+    for (w, h) in TINY:
+        for (t, fi) in frames_for(cls):
+            try:
+                rows = _rows(render(cls, w, h, t, fi))
+            except Exception as exc:  # a crash IS a hard failure (finding)
+                record(f"tiny-safe {cls.name}", False,
+                        f"raised at {w}x{h} t={t}: {exc!r}")
+                return
+            for i, ln in enumerate(rows):
+                cw = visible_width(ln)
+                if cw != w:
+                    findings.append(
+                        f"tiny width (soft) {cls.name} {w}x{h} row {i}: "
+                        f"width {cw} != {w}")
+    record(f"tiny-safe {cls.name}", True, "no crash at 1x1/2x2")
+
+
+def main(argv: list[str]) -> int:
+    registry.load_all()
+    only = set(argv)
+    effects = [c for c in registry.all_effects() if not only or c.name in only]
+    sizes = REALISTIC + NARROW + TINY
+    for cls in effects:
+        check_rowcount(cls)
+        check_no_overflow(cls)
+        check_exact_width(cls)
+        check_narrow_allowlist(cls)
+        check_tiny_no_crash(cls)
+
+    failed = [r for r in results if not r[1]]
+    if findings:
+        print("\nFINDINGS (soft / documented):")
+        for f in findings:
+            print("  - " + f)
+    checks_per = 5
+    print(f"\n{len(effects)} effects x {len(sizes)} sizes "
+          f"({checks_per} contracts each)")
+    print(f"{len(results) - len(failed)}/{len(results)} checks passed")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
+

smartcli_toolkit-0.1.2/tests/test_readiness.py

@@ -0,0 +1,396 @@
+#!/usr/bin/env python
+"""test_readiness.py — deterministic unit tests for smartcli_core.readiness.
+
+These cover the failure/edge paths that historically broke and are otherwise only
+reachable through flaky real-PTY timing:
+  * TIMEOUT   — a screen that never settles / a marker that never matches.
+  * STABLE    — the content hash repeats long enough to declare stability.
+  * MARKER    — an expected regex is found (beats stability).
+  * late-flush — data arrives after the grace sleep → the wait resumes instead of
+                 declaring done on a half-drawn screen (the ConPTY quiet-gap bug).
+  * min_wait  — stability/marker is NOT declared before the minimum elapsed time.
+
+Determinism: we monkeypatch ``readiness.time.monotonic`` / ``readiness.time.sleep``
+with a virtual clock so ``sleep(x)`` advances virtual time by ``x`` and timeouts
+fire instantly with no real waiting. This patches only the clock BOUNDARY — the
+real decision logic in readiness.py runs unchanged (HARD-LESSONS rule 5: a test
+double for the clock/IO edge, never a patch that hides a bug).
+
+Run:  python tests/test_readiness.py     (exit 0 = pass, 1 = fail)
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# Portable: make the repo root importable regardless of cwd.
+_ROOT = Path(__file__).resolve().parents[1]
+if str(_ROOT) not in sys.path:
+    sys.path.insert(0, str(_ROOT))
+
+from smartcli_core import readiness  # noqa: E402
+
+
+class VirtualClock:
+    """A fake monotonic clock: sleep() advances virtual time; no real waiting."""
+
+    def __init__(self) -> None:
+        self.t = 0.0
+        self.last_sleep = None   # duration of the most recent sleep() (seconds)
+
+    def monotonic(self) -> float:
+        return self.t
+
+    def sleep(self, seconds: float) -> None:
+        # Advance virtual time; also nudge forward on zero-sleep to guarantee
+        # progress so no loop can spin forever in a test.
+        self.last_sleep = seconds
+        self.t += seconds if seconds > 0 else 0.001
+
+
+def _install_clock():
+    clk = VirtualClock()
+    readiness.time.monotonic = clk.monotonic  # type: ignore[assignment]
+    readiness.time.sleep = clk.sleep          # type: ignore[assignment]
+    return clk
+
+
+# scripted-callable helpers ------------------------------------------------
+
+def seq_reader(batches):
+    """read_fn that returns each batch in turn, then b'' forever."""
+    it = iter(batches)
+
+    def _read():
+        return next(it, b"")
+
+    return _read
+
+
+def seq_hashes(values):
+    """hash_fn that returns each value in turn, then repeats the last forever."""
+    state = {"i": 0, "vals": list(values)}
+
+    def _hash():
+        i = state["i"]
+        vals = state["vals"]
+        v = vals[i] if i < len(vals) else vals[-1]
+        if i < len(vals) - 1:
+            state["i"] = i + 1
+        return v
+
+    return _hash
+
+
+def seq_text(values):
+    """text_fn that returns each value in turn, then repeats the last forever."""
+    state = {"i": 0, "vals": list(values)}
+
+    def _text():
+        i = state["i"]
+        vals = state["vals"]
+        v = vals[i] if i < len(vals) else vals[-1]
+        if i < len(vals) - 1:
+            state["i"] = i + 1
+        return v
+
+    return _text
+
+
+_fails = []
+
+
+def check(cond, name, detail=""):
+    tag = "[PASS]" if cond else "[FAIL]"
+    print(f"{tag} {name}  {detail}")
+    if not cond:
+        _fails.append(name)
+
+
+def test_stable_reached():
+    """Hash unchanged + no new bytes for quiet_ms → wait_until_stable True, fast."""
+    _install_clock()
+    ok = readiness.wait_until_stable(
+        read_fn=seq_reader([]),                 # no bytes ever
+        get_screen_hash_fn=seq_hashes([42]),    # constant hash
+        quiet_ms=200, poll_ms=30, max_wait_ms=8000, grace_ms=0, min_wait_ms=0,
+    )
+    check(ok is True, "wait_until_stable: constant screen settles", f"ret={ok}")
+
+
+def test_stable_timeout():
+    """Hash never stops changing → returns False (TIMEOUT) within budget, no hang."""
+    clk = _install_clock()
+    # hash flips forever: 0,1,0,1,... → never quiet
+    flip = {"n": 0}
+
+    def churn_hash():
+        flip["n"] ^= 1
+        return flip["n"]
+
+    ok = readiness.wait_until_stable(
+        read_fn=seq_reader([]),
+        get_screen_hash_fn=churn_hash,
+        quiet_ms=200, poll_ms=30, max_wait_ms=1000, grace_ms=0, min_wait_ms=0,
+    )
+    check(ok is False, "wait_until_stable: churning screen hits TIMEOUT", f"ret={ok}")
+    check(clk.t >= 1.0, "wait_until_stable: respected max_wait ceiling", f"virt_t={clk.t:.2f}s")
+
+
+def test_late_flush_resume():
+    """A late flush delivered ONLY on the post-grace `tail = read_fn()` drain must
+    resume the wait — not let it return True on the half-drawn (pre-flush) screen.
+
+    This targets readiness.py lines 87-93 specifically. The flush is delivered on
+    the exact read that immediately follows a `grace` sleep (grace=40ms, distinct
+    from the 30ms poll sleep), so it can only land on the tail drain — the branch
+    the earlier version of this test never exercised (mutation-proven false-green).
+
+    Proof of resume: (a) the flush was delivered on a tail drain, and (b) the wait
+    kept polling AFTER the flush (reads continued) instead of returning immediately.
+    Under a mutant that drops the resume branch, the function returns True right
+    after the flush drain → no further reads → this test FAILS.
+    """
+    clk = _install_clock()
+    reads = {"n": 0}
+    tail_flush = {"delivered_at": None}
+    reads_after_flush = {"n": 0}
+
+    def read_fn():
+        reads["n"] += 1
+        if tail_flush["delivered_at"] is not None:
+            reads_after_flush["n"] += 1
+            return b""  # quiet again so it can finally re-settle
+        # The tail drain is the read whose immediately-preceding sleep was `grace`
+        # (40ms), not a `poll` (30ms). Deliver the flush there, exactly once.
+        if clk.last_sleep is not None and abs(clk.last_sleep - 0.040) < 1e-9:
+            tail_flush["delivered_at"] = reads["n"]
+            return b"late output"
+        return b""
+
+    def hash_fn():
+        # constant until the flush lands (so quiet accumulates and we reach the
+        # tail drain), then a new value that itself settles.
+        return 2 if tail_flush["delivered_at"] is not None else 1
+
+    ok = readiness.wait_until_stable(
+        read_fn=read_fn,
+        get_screen_hash_fn=hash_fn,
+        quiet_ms=60, poll_ms=30, max_wait_ms=5000, grace_ms=40, min_wait_ms=0,
+    )
+    check(ok is True, "wait_until_stable: resumes after tail-drain flush then settles", f"ret={ok}")
+    check(tail_flush["delivered_at"] is not None,
+          "wait_until_stable: flush landed on the post-grace tail drain",
+          f"at read #{tail_flush['delivered_at']}")
+    # The crux: after the tail-drain flush, the loop must have RESUMED (more reads),
+    # not returned. A mutant dropping the resume branch returns immediately → 0.
+    check(reads_after_flush["n"] > 0,
+          "wait_until_stable: kept polling after the tail-drain flush (resumed, not returned)",
+          f"reads_after_flush={reads_after_flush['n']}")
+
+
+def test_min_wait_guard():
+    """Stability must NOT be declared before min_wait_ms even if screen is quiet."""
+    clk = _install_clock()
+    ok = readiness.wait_until_stable(
+        read_fn=seq_reader([]),
+        get_screen_hash_fn=seq_hashes([7]),     # instantly "quiet"
+        quiet_ms=50, poll_ms=30, max_wait_ms=8000, grace_ms=0, min_wait_ms=500,
+    )
+    check(ok is True, "wait_until_stable: settles after min_wait", f"ret={ok}")
+    check(clk.t >= 0.5, "wait_until_stable: honored min_wait_ms floor", f"virt_t={clk.t:.3f}s (>=0.5)")
+
+
+def test_regex_match():
+    """wait_for_regex finds the marker and returns (True, snapshot)."""
+    _install_clock()
+    matched, snap = readiness.wait_for_regex(
+        read_fn=seq_reader([b">>> "]),
+        get_text_fn=seq_text(["loading...", "loading...", ">>> ready"]),
+        get_snapshot_fn=lambda: "SNAP",
+        pattern=r">>> ", timeout_ms=5000, poll_ms=30, min_wait_ms=0,
+    )
+    check(matched is True, "wait_for_regex: finds marker", f"matched={matched}")
+    check(snap == "SNAP", "wait_for_regex: returns snapshot on match", f"snap={snap}")
+
+
+def test_regex_timeout_returns_snapshot():
+    """wait_for_regex on a never-matching pattern returns (False, snapshot)."""
+    clk = _install_clock()
+    matched, snap = readiness.wait_for_regex(
+        read_fn=seq_reader([]),
+        get_text_fn=seq_text(["nothing here"]),
+        get_snapshot_fn=lambda: "LAST",
+        pattern=r"WILL_NEVER_APPEAR", timeout_ms=800, poll_ms=30, min_wait_ms=0,
+    )
+    check(matched is False, "wait_for_regex: TIMEOUT when no match", f"matched={matched}")
+    check(snap == "LAST", "wait_for_regex: still returns last snapshot on timeout", f"snap={snap}")
+    check(clk.t >= 0.8, "wait_for_regex: respected timeout ceiling", f"virt_t={clk.t:.2f}s")
+
+
+def test_regex_min_wait():
+    """A match present from t=0 must be ignored until min_wait_ms elapses."""
+    clk = _install_clock()
+    matched, _ = readiness.wait_for_regex(
+        read_fn=seq_reader([]),
+        get_text_fn=seq_text([">>> "]),          # matches immediately
+        get_snapshot_fn=lambda: None,
+        pattern=r">>> ", timeout_ms=5000, poll_ms=30, min_wait_ms=300,
+    )
+    check(matched is True, "wait_for_regex: eventually matches past min_wait", f"matched={matched}")
+    check(clk.t >= 0.3, "wait_for_regex: did not match before min_wait", f"virt_t={clk.t:.3f}s (>=0.3)")
+
+
+def test_wait_ready_marker_beats_stability():
+    """wait_ready returns MARKER when the regex hits (even amid churn)."""
+    _install_clock()
+    # screen keeps changing (never stable) but marker appears on 3rd text sample
+    reason, snap = readiness.wait_ready(
+        read_fn=seq_reader([b"a", b"b", b"c"]),
+        get_screen_hash_fn=seq_hashes([1, 2, 3, 4, 5]),   # churning
+        get_text_fn=seq_text(["...", "...", "DONE!"]),
+        get_snapshot_fn=lambda: "S",
+        marker=r"DONE!", quiet_ms=200, poll_ms=30, max_wait_ms=5000, min_wait_ms=0,
+    )
+    check(reason == "MARKER", "wait_ready: marker beats a churning screen", f"reason={reason}")
+
+
+def test_wait_ready_stable():
+    """wait_ready returns STABLE when no marker and screen settles."""
+    _install_clock()
+    reason, _ = readiness.wait_ready(
+        read_fn=seq_reader([]),
+        get_screen_hash_fn=seq_hashes([9]),
+        get_text_fn=seq_text(["idle"]),
+        get_snapshot_fn=lambda: "S",
+        marker=None, quiet_ms=100, poll_ms=30, max_wait_ms=5000, min_wait_ms=0, grace_ms=0,
+    )
+    check(reason == "STABLE", "wait_ready: settles to STABLE with no marker", f"reason={reason}")
+
+
+def test_wait_ready_stable_timing_floor():
+    """wait_ready must NOT declare STABLE before quiet_ms + min_wait_ms elapse.
+
+    Mirrors test_min_wait_guard but for wait_ready's stability branch. Asserts a
+    virtual-time floor, so a mutant that declares STABLE on the first quiet poll
+    (ignoring quiet_ms/min_wait_ms) is caught (the false-green M7 gap).
+    """
+    clk = _install_clock()
+    reason, _ = readiness.wait_ready(
+        read_fn=seq_reader([]),               # instantly quiet
+        get_screen_hash_fn=seq_hashes([5]),   # constant hash
+        get_text_fn=seq_text(["idle"]),
+        get_snapshot_fn=lambda: "S",
+        marker=None, quiet_ms=200, poll_ms=30, max_wait_ms=8000,
+        min_wait_ms=300, grace_ms=0,
+    )
+    check(reason == "STABLE", "wait_ready: eventually STABLE past the floor", f"reason={reason}")
+    # Must have waited at least min_wait (0.3s); a no-quiet mutant returns near t=0.
+    check(clk.t >= 0.3, "wait_ready: honored quiet_ms + min_wait_ms floor before STABLE",
+          f"virt_t={clk.t:.3f}s (>=0.3)")
+
+
+def test_blank_gate_refuses_stable_on_never_painted_screen():
+    """With blank_hash set, a never-painted blank screen must NOT declare STABLE.
+
+    Regression lock for core bug #1: the readiness gate. read_fn never yields
+    bytes and the hash stays at the blank baseline → stability is withheld →
+    TIMEOUT, not a false STABLE on a screen the program hasn't drawn yet.
+    """
+    BLANK = 1000
+    # wait_until_stable form
+    clk = _install_clock()
+    ok = readiness.wait_until_stable(
+        read_fn=seq_reader([]), get_screen_hash_fn=seq_hashes([BLANK]),
+        quiet_ms=200, poll_ms=30, max_wait_ms=1000, grace_ms=40, min_wait_ms=50,
+        blank_hash=BLANK,
+    )
+    check(ok is False, "wait_until_stable: blank_hash gate withholds stable on blank screen", f"ret={ok}")
+    # wait_ready form
+    _install_clock()
+    reason, _ = readiness.wait_ready(
+        read_fn=seq_reader([]), get_screen_hash_fn=seq_hashes([BLANK]),
+        get_text_fn=seq_text([""]), get_snapshot_fn=lambda: "B",
+        marker=r">>> ", quiet_ms=200, poll_ms=30, max_wait_ms=1000,
+        min_wait_ms=50, grace_ms=40, blank_hash=BLANK,
+    )
+    check(reason == "TIMEOUT", "wait_ready: blank_hash gate → TIMEOUT not false STABLE", f"reason={reason}")
+
+
+def test_blank_gate_does_not_harm_drawn_static_screen():
+    """The gate must NOT harm a legitimately-drawn, static screen (hash != blank).
+
+    Regression lock: the naive first attempt broke this exact case. A drawn UI
+    whose hash differs from the blank baseline and then holds steady must still
+    settle to STABLE even with blank_hash supplied.
+    """
+    _install_clock()
+    reason, _ = readiness.wait_ready(
+        read_fn=seq_reader([]), get_screen_hash_fn=seq_hashes([5555]),  # != blank
+        get_text_fn=seq_text(["drawn UI"]), get_snapshot_fn=lambda: "S",
+        marker=None, quiet_ms=100, poll_ms=30, max_wait_ms=5000,
+        min_wait_ms=0, grace_ms=0, blank_hash=1000,
+    )
+    check(reason == "STABLE", "wait_ready: drawn static screen still settles under gate", f"reason={reason}")
+    # And once output has been seen, a return to the blank hash still settles.
+    _install_clock()
+    reads = iter([b"data", b"", b"", b"", b"", b"", b""])
+    reason2, _ = readiness.wait_ready(
+        read_fn=lambda: next(reads, b""), get_screen_hash_fn=seq_hashes([1000]),
+        get_text_fn=seq_text([""]), get_snapshot_fn=lambda: "S",
+        marker=None, quiet_ms=100, poll_ms=30, max_wait_ms=5000,
+        min_wait_ms=0, grace_ms=0, blank_hash=1000,
+    )
+    check(reason2 == "STABLE", "wait_ready: seen_any overrides blank gate", f"reason={reason2}")
+
+
+def test_wait_ready_timeout():
+    """wait_ready returns TIMEOUT when marker never matches and screen churns."""
+    clk = _install_clock()
+    flip = {"n": 0}
+
+    def churn_hash():
+        flip["n"] ^= 1
+        return flip["n"]
+
+    reason, snap = readiness.wait_ready(
+        read_fn=seq_reader([b"x", b"y", b"z"] * 100),   # bytes keep coming
+        get_screen_hash_fn=churn_hash,
+        get_text_fn=seq_text(["busy"]),
+        get_snapshot_fn=lambda: "LASTSNAP",
+        marker=r"NOPE", quiet_ms=200, poll_ms=30, max_wait_ms=1000, min_wait_ms=0,
+    )
+    check(reason == "TIMEOUT", "wait_ready: TIMEOUT when nothing satisfies", f"reason={reason}")
+    check(snap == "LASTSNAP", "wait_ready: returns last snapshot on timeout", f"snap={snap}")
+    check(clk.t >= 1.0, "wait_ready: respected max_wait ceiling", f"virt_t={clk.t:.2f}s")
+
+
+def main() -> int:
+    import time as _real_time
+    t0 = _real_time.perf_counter()
+    print("=" * 60)
+    print("readiness deterministic unit tests (virtual clock, no real waits)")
+    print("=" * 60)
+    for fn in (
+        test_stable_reached, test_stable_timeout, test_late_flush_resume,
+        test_min_wait_guard, test_regex_match, test_regex_timeout_returns_snapshot,
+        test_regex_min_wait, test_wait_ready_marker_beats_stability,
+        test_wait_ready_stable, test_wait_ready_stable_timing_floor,
+        test_blank_gate_refuses_stable_on_never_painted_screen,
+        test_blank_gate_does_not_harm_drawn_static_screen,
+        test_wait_ready_timeout,
+    ):
+        fn()
+    wall = _real_time.perf_counter() - t0
+    print("-" * 60)
+    if _fails:
+        print(f"FAIL: {len(_fails)} check(s) failed: {_fails}")
+        return 1
+    print(f"PASS: all readiness edge paths covered in {wall*1000:.0f} ms wall (deterministic)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+