meltygui 0.1.0__py3-none-any.whl

meltygui/core/diagnostics/perf_trace.py

@@ -0,0 +1,281 @@
+"""Timeline logging for diagnosing cross-thread slowness (symbol index / code
+host load). NOT a profiler: many interacting threads plus GIL-bound parsing make
+sampling misleading, so instead every meaningful unit of work writes one line
+with wall-clock time, frame count, and thread label — the log reads as a single
+interleaved timeline. A gap in frame numbers while a worker line is open = the
+GIL was held; overlapping spans show which threads stacked up.
+
+    12:34:56.789 f001234 [render         ] ensure_index: spawn recompute file=toggles.py
+
+Usage:
+    from meltygui.core.diagnostics.perf_trace import trace, trace_rl, span, once
+
+    trace("warmer build start", files=150)
+    with span("cold compute", file=name):      # logs "... took 812.4ms" on exit
+        ...
+    with span("probe", min_ms=2.0): ...        # silent unless >= 2ms
+    trace_rl("slow-probe", "probe slow", ...)  # at most 1 line/sec per key
+    if once(("host", name)): trace(...)        # once per key per session
+
+Gate: Toggles.symbol_perf_log (missing Toggles => enabled). Sink is LOG_PATH,
+append mode with a session header — append (not truncate) so a jedi-pool child
+process importing this module can't wipe the parent's log mid-run. Never raises:
+a logging failure must not take down the render loop.
+
+Everything here is stdlib-only; project state is read via sys.modules (no
+imports) so this module is importable from anywhere without cycles.
+"""
+import os
+import sys
+import threading
+import time
+from meltygui.core.runtime.paths import debug_log_path
+
+LOG_PATH = debug_log_path("lsd_symbol_perf.log")
+_MAX_CARRYOVER_BYTES = 5 * 1024 * 1024   # start fresh when the file grows past this
+
+_lock = threading.Lock()
+_rl_last: dict = {}       # rate-limit key -> last emit monotonic
+_once_keys: set = set()   # keys already emitted via once()
+
+
+def _enabled() -> bool:
+    try:
+        from meltygui.core.runtime.toggles import Toggles
+        return bool(Toggles.symbol_perf_log)
+    except Exception:
+        return True
+
+
+def enabled() -> bool:
+    """Public gate for callers that do per-frame work BEYOND logging (e.g.
+    the GPU frame timer's query objects) — same toggle as trace()."""
+    return _enabled()
+
+
+def _open_log():
+    """One line-buffered append handle per process, adopted across hotswap /
+    dual-import via sys (the established sharing pattern for process singletons)."""
+    fh = getattr(sys, "_symbol_perf_fh", None)
+    if fh is not None:
+        return fh
+    try:
+        mode = "a"
+        try:
+            if os.path.getsize(LOG_PATH) > _MAX_CARRYOVER_BYTES:
+                mode = "w"
+        except OSError:
+            pass
+        fh = open(LOG_PATH, mode, buffering=1)
+        fh.write(f"\n=== session start pid={os.getpid()} "
+                 f"{time.strftime('%Y-%m-%d %X')} ===\n")
+    except Exception:
+        fh = False   # sentinel: don't retry every call
+    sys._symbol_perf_fh = fh
+    return fh
+
+
+def _frame() -> int:
+    mel = (sys.modules.get("meltygui.core.melty")
+           or sys.modules.get("lsd.gl_gui.melty"))
+    try:
+        return mel.Melty.frame_count if mel is not None else -1
+    except Exception:
+        return -1
+
+
+def _thread_label() -> str:
+    t = threading.current_thread()
+    try:
+        gs = (sys.modules.get("meltygui.core.graphics.gl_state")
+              or sys.modules.get("lsd.gl_gui.gl_state"))
+        if gs is not None and getattr(gs, "_gl_thread", None) is t:
+            return "render"
+    except Exception:
+        pass
+    name = t.name
+    if name == "MainThread":
+        return "main"
+    # ThreadPoolExecutor-0_3 -> pool_3 (Background pool workers)
+    if name.startswith("ThreadPoolExecutor"):
+        return "pool_" + name.rsplit("_", 1)[-1]
+    return name
+
+
+def _fmt_fields(fields: dict) -> str:
+    if not fields:
+        return ""
+    parts = []
+    for k, v in fields.items():
+        if isinstance(v, float):
+            v = f"{v:.1f}"
+        parts.append(f"{k}={v}")
+    return "  " + " ".join(parts)
+
+
+def trace(msg: str, **fields):
+    """One timeline line. Swallows every failure."""
+    if not _enabled():
+        return
+    try:
+        fh = _open_log()
+        if not fh:
+            return
+        now = time.time()
+        ts = time.strftime("%H:%M:%S", time.localtime(now)) + f".{int(now % 1 * 1000):03d}"
+        line = (f"{ts} f{_frame():06d} [{_thread_label():<15}] "
+                f"{msg}{_fmt_fields(fields)}\n")
+        with _lock:
+            fh.write(line)
+    except Exception:
+        pass
+
+
+def trace_rl(key, msg: str, min_interval: float = 1.0, **fields):
+    """Rate-limited trace: at most one line per `min_interval` seconds per key.
+    For per-frame paths that are only interesting when they stay slow."""
+    if not _enabled():
+        return
+    try:
+        now = time.monotonic()
+        last = _rl_last.get(key)
+        if last is not None and now - last < min_interval:
+            return
+        _rl_last[key] = now
+    except Exception:
+        return
+    trace(msg, **fields)
+
+
+def once(key) -> bool:
+    """True the first time `key` is seen this session — for once-only lines."""
+    try:
+        if key in _once_keys:
+            return False
+        _once_keys.add(key)
+        return True
+    except Exception:
+        return False
+
+
+class span:
+    """Context manager logging '<label> took Xms' on exit (only when >= min_ms).
+    Extra context can be attached mid-span via .add(k=v); an exception inside
+    the span is noted on the line and re-raised."""
+
+    __slots__ = ("label", "min_ms", "fields", "t0", "c0")
+
+    def __init__(self, label: str, min_ms: float = 0.0, **fields):
+        self.label = label
+        self.min_ms = min_ms
+        self.fields = fields
+        self.t0 = 0.0
+        self.c0 = 0.0
+
+    def add(self, **fields):
+        self.fields.update(fields)
+
+    def __enter__(self):
+        self.t0 = time.monotonic()
+        self.c0 = time.thread_time()
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        try:
+            dt_ms = (time.monotonic() - self.t0) * 1000.0
+            if dt_ms >= self.min_ms:
+                # cpu ≪ wall on a slow span = this thread was GIL-starved, not
+                # doing the work - the span label is then the victim, not the
+                # culprit (see the 2026-07-31 stall hunts).
+                cpu_ms = (time.thread_time() - self.c0) * 1000.0
+                suffix = " EXC=" + exc_type.__name__ if exc_type is not None else ""
+                trace(f"{self.label} took {dt_ms:.1f}ms (cpu {cpu_ms:.1f}ms){suffix}",
+                      **self.fields)
+        except Exception:
+            pass
+        return False
+
+
+# ── Stall watchdog: what is the render thread blocked on? ──────────────────────
+# Wall≫cpu slow frames (the post-boot 1000ms+ bursts) mean the render thread
+# is WAITING - lock, GIL, GL/present backpressure - and the per-phase spans
+# can't pin on what. This daemon samples Melty's clock; when it sits still
+# past `threshold_s` while the render thread is mid-frame (NOT parked in
+# glfw wait_events - an idle studio is not a stall), it dumps every thread's
+# current call stack to the log. One dump per stall, re-armed when the frame
+# counter moves; a second dump is forced if the stall passes 3x threshold.
+# Cost when healthy: one attribute read per poll (20Hz). Same toggle as trace.
+
+def _render_thread():
+    gs = (sys.modules.get("meltygui.core.graphics.gl_state")
+          or sys.modules.get("lsd.gl_gui.gl_state"))
+    return getattr(gs, "_gl_thread", None) if gs is not None else None
+
+
+def _dump_all_stacks(reason: str):
+    import traceback
+    frames = sys._current_frames()
+    render_t = _render_thread()
+    for t in threading.enumerate():
+        frame = frames.get(t.ident)
+        if frame is None:
+            continue
+        stack = traceback.extract_stack(frame)[-10:]
+        chain = " <- ".join(
+            f"{fs.filename.rsplit('/', 1)[-1]}:{fs.lineno} {fs.name}"
+            for fs in reversed(stack))
+        label = "render" if t is render_t else t.name
+        trace(f"STALL {reason} [{label}] {chain}")
+
+
+def _stall_watchdog(threshold_s: float, poll_s: float):
+    last_count = -1
+    still_since = time.monotonic()
+    dumped = 0
+    while True:
+        time.sleep(poll_s)
+        try:
+            if not _enabled():
+                continue
+            count = _frame()
+            now = time.monotonic()
+            if count != last_count:
+                last_count = count
+                still_since = now
+                dumped = 0
+                continue
+            stalled_s = now - still_since
+            want = 1 if stalled_s >= threshold_s else 0
+            if want and stalled_s >= threshold_s * 3:
+                want = 2
+            if dumped >= want:
+                continue
+            render_t = _render_thread()
+            frame = sys._current_frames().get(render_t.ident) if render_t else None
+            if frame is None:
+                continue
+            # Parked between frames = idle, not a stall. wait_events blocks
+            # there; poll_events/sleep cover some launcher-style loops.
+            names = set()
+            f = frame
+            while f is not None and len(names) < 12:
+                names.add(f.f_code.co_name)
+                f = f.f_back
+            if {"wait_events", "poll_events"} & names:
+                still_since = now
+                continue
+            dumped = want
+            _dump_all_stacks(f"{stalled_s:.2f}s frame={count}")
+        except Exception:
+            pass  # the watchdog must never hurt the app
+
+
+def ensure_stall_watchdog(threshold_s: float = 0.35, poll_s: float = 0.05):
+    """Idempotent, process-lifetime (sys-guarded like the log handle — an
+    in-process studio restart adopts the running one instead of stacking)."""
+    if getattr(sys, "_lsd_stall_watchdog", None) is not None:
+        return
+    t = threading.Thread(target=_stall_watchdog, args=(threshold_s, poll_s),
+                         name="stall-watchdog", daemon=True)
+    sys._lsd_stall_watchdog = t
+    t.start()

meltygui/core/diagnostics/profile_decoration.py

@@ -0,0 +1,88 @@
+import functools
+from typing import Callable, Any
+from collections import deque, defaultdict
+
+from meltygui.core.melty import Melty
+
+
+def profile(func: Callable) -> Callable:
+    """
+    Decorator that profiles a function line-by-line and stores results in Melty.profiles_results.
+
+    Usage:
+        @profile
+        def my_function():
+            # your code here
+            pass
+
+    The profiling results will be available at:
+        Melty.profiles_results['my_function'][-1]  # Most recent call
+
+    Each result is a list of (line_of_code, time_ms) tuples sorted by time.
+
+    Note: Requires line_profiler package. Install with: pip install line_profiler
+    """
+    # Track if we're already profiling this function (for recursive calls)
+    _profiling = False
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        nonlocal _profiling
+
+        # Only profile at the top level to avoid nested profiler conflicts
+        if _profiling:
+            return func(*args, **kwargs)
+
+        try:
+            from line_profiler import LineProfiler
+        except ImportError:
+            # Fallback: just run the function without profiling
+            print("Warning: line_profiler not installed. Install with: pip install line_profiler")
+            return func(*args, **kwargs)
+
+        if func.__name__ not in Melty.profiles_results:
+            # Create a line profiler
+            profiler = LineProfiler()
+            profiler.add_function(func)
+
+            # Profile the function execution
+            _profiling = True
+            try:
+                profiler.enable()
+                result = func(*args, **kwargs)
+                profiler.disable()
+            finally:
+                _profiling = False
+
+            # Extract the line-by-line stats
+            filtered_results = []
+            stats = profiler.get_stats()
+
+            # stats.timings is a dict: {(filename, line_start, func_name): [(lineno, nhits, time), ...]}
+            for key, timings in stats.timings.items():
+                filename, line_start, func_name_inner = key
+
+                # Read the source code
+                import linecache
+
+                for lineno, nhits, time in timings:
+                    if nhits > 0:  # Only include lines that were executed
+                        source_line = linecache.getline(filename, lineno).strip()
+                        if source_line:
+                            # line_profiler time is in units (typically nanoseconds, 1e-09)
+                            # Convert to milliseconds: time * unit * 1000 (to go from seconds to ms)
+                            time_ms = time * stats.unit * 1000
+                            filtered_results.append((source_line, time_ms, lineno))
+
+            # Sort by time (slowest first)
+            filtered_results.sort(key=lambda x: x[1], reverse=True)
+
+            # Store the profile results (deque automatically to max 5 items)
+            Melty.profiles_results[func.__name__] = filtered_results
+
+            return result
+        else:
+            return func(*args, **kwargs)
+
+    return wrapper
+

meltygui/core/diagnostics/resize_trace.py

@@ -0,0 +1,62 @@
+"""Bounded, always-on resize diagnostics; records metadata, never view values.
+
+Each process writes .melty/resize-<pid>.log (JSON lines, two 4 MiB backups).
+No draw-state references are retained and logging failures cannot break a drag.
+"""
+import json
+import logging
+from logging.handlers import RotatingFileHandler
+import os
+from pathlib import Path
+import time
+import traceback
+
+
+def record(stage, window, event=None, error=False, **details):
+    try:
+        from meltygui.core.melty import Melty
+        logger = logging.getLogger(f"meltygui.resize.{os.getpid()}")
+        if not logger.handlers:
+            from meltygui.core.runtime.paths import cache_root
+            path = cache_root()
+            path.mkdir(parents=True, exist_ok=True)
+            handler = RotatingFileHandler(path / f"resize-{os.getpid()}.log",
+                                          maxBytes=4 * 1024 * 1024, backupCount=2)
+            logger.addHandler(handler)
+            logger.setLevel(logging.INFO)
+            logger.propagate = False
+        entry = dict(time=time.time(), frame=Melty.frame_count, stage=stage,
+                     window=str(getattr(window, 'id', None)), identity=id(window),
+                     name=str(getattr(window, 'name', ''))[:200])
+        for key in ('window_pos', 'width', 'height', 'abs_left', 'abs_top',
+                    'min_width', 'min_height', 'closed', 'expanded', 'use_cache',
+                    'freeze_resize', 'size_change', '_frame_pinned',
+                    '_initial_window_size', '_initial_window_pos_resize',
+                    '_resize_from_top_left', '_resize_target_edge_x0', '_resize_target_row_y0'):
+            entry[key] = getattr(window, key, None)
+        for key, axis in (('_resize_target_edge', 'x'), ('_resize_target_row', 'y')):
+            edge = getattr(window, key, None)
+            entry[key] = None if edge is None else (id(edge), edge.get(axis))
+        if event is not None:
+            entry['event'] = {key: getattr(event, key, None)
+                              for key in ('x', 'y', 'dx', 'dy', 'total_dx', 'total_dy')}
+        if error:
+            entry['traceback'] = traceback.format_exc()
+        import meltygui.core.windowing.os_frame as os_frame
+        entry['geometry_mode'] = os_frame._STATE['mode']
+        entry['geometry_generation'] = os_frame._STATE['generation']
+        entry['os_expected'] = list(os_frame._STATE['expected'])
+        entry['os_unapplied'] = list(os_frame._STATE['unapplied'])
+        entry.update(details)
+        logger.info(json.dumps(entry, default=lambda value: f'<{type(value).__name__}>'))
+    except Exception:
+        # Diagnostics must never turn an otherwise valid frame into a failure.
+        pass
+
+
+def edges(window, axis):
+    """Small identity/geometry snapshot; never serialize a draw_state or its data."""
+    registry = getattr(window, '_edge_views' if axis == 'x' else '_row_views', {})
+    return [{"owner": str(key), "closed": getattr(view, 'closed', False),
+             "edges": [(id(edge), edge.get(axis)) for edge in edge_list]}
+            for key, (view, edge_list) in registry.items()]

meltygui/core/diagnostics/screenshot_core.py

@@ -0,0 +1,247 @@
+"""Region screenshot tool — Ctrl+Shift+3 (draw_main's root hotkey) or
+Actions.screenshot arms it; a crosshair follows the cursor on the overlay
+draw list; click-drag a box; on release the pixels inside the box are read
+from the main framebuffer (GL_BACK, after the frame is fully composited — the
+deferred capture queue in screenshot.py), saved as a PNG under the configured
+shot dir, added to the code editor as a tab (its ImageCodec view) WITHOUT
+switching to it, and its path is put on the clipboard.
+
+State is module-level (one tool, never more than one capture in flight);
+`draw(draw_state)` runs from draw_main every frame and is a no-op unless
+armed. While armed the tool owns the mouse: full-screen BLOCKING left-button
+subscriptions at a priority above every window and blocker, so the press
+that starts the box can't land on whatever sits under the cursor. Esc (or
+the hotkey again) cancels.
+
+The crosshair + camera are the CURSOR IMAGE while armed (glfw.create_cursor
+from a PIL render, hotspot at the crosshair centre), not overlay drawing:
+anything drawn in a frame uses the frame-start mouse sample and shows a
+frame later, while the compositor moves the cursor plane with zero latency
+— overlay crosshairs visibly trailed the pointer. The cursor plane is the
+one thing that can sit exactly where the pointer is. Only the drag box
+(anchored at the press) is drawn on the overlay, with a readout pill beside
+it — top-left `x, y` and `w × h` in window points — so the tool doubles as
+a measure tool (drag over a thing, read its rect off the label, Esc).
+"""
+
+import meltygui.core.windowing.window_api as glfw
+import meltygui_imgui as imgui
+from meltygui.hdr_color import pack_color
+
+import meltygui.core.input.mouse_cursor as mouse_cursor
+from meltygui.core.melty import Melty
+from meltygui.core.windowing.glfw_utils import request_render
+from meltygui.core.rendering.core_decoration import Core
+
+# Above every window / blocker (the live lab's blocking handlers use 1024).
+_PRIORITY_DELTA = 4096
+_MIN_BOX_PX = 3          # smaller than this on release = a click, not a box
+_ICON = "\uf030"        # FA camera (baked into the cursor image)
+_BOX_COLOR = (0.35, 0.75, 1.0, 1.0)
+_FILL_COLOR = (0.35, 0.75, 1.0, 0.12)
+_CURSOR_SIZE, _CURSOR_HOT, _CURSOR_ARM, _CURSOR_GAP = 64, 20, 16, 3
+
+
+class RegionScreenshot:
+    armed = False
+    start = None        # (x, y) in points where the drag began; None = no box yet
+    cursor = None       # *cursor* (built once, render thread)
+    cursor_set = False  # our cursor is the window's current cursor
+
+
+def _build_cursor_image():
+    """Crosshair (gap around the hotspot, dark halo under a white hairline)
+    with the FA camera glyph below-right — the same glyph Actions.screenshot
+    wears. Returns (PIL image, hotspot)."""
+    from PIL import Image, ImageDraw, ImageFont
+    from meltygui.core.styling.fonts import _RESOURCES
+    size, hot, arm, gap = _CURSOR_SIZE, _CURSOR_HOT, _CURSOR_ARM, _CURSOR_GAP
+    img = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+    d = ImageDraw.Draw(img)
+    for col, w in (((0, 0, 0, 140), 3), ((255, 255, 255, 230), 1)):
+        for seg in ((hot - arm, hot, hot - gap, hot), (hot + gap, hot, hot + arm, hot),
+                    (hot, hot - arm, hot, hot - gap), (hot, hot + gap, hot, hot + arm)):
+            d.line(seg, fill=col, width=w)
+    font = ImageFont.truetype(str(_RESOURCES / "fontawesome-webfont.ttf"), 22)
+    gx, gy = hot + 9, hot + 7
+    d.text((gx + 1, gy + 1), _ICON, font=font, fill=(0, 0, 0, 150))
+    d.text((gx, gy), _ICON, font=font, fill=(255, 255, 255, 235))
+    return img, hot
+
+
+def _set_tool_cursor(on):
+    """Swap the window cursor to the crosshair/camera image (on) or back to
+    the default (off). GLFW calls belong on the event-pumping thread — the
+    render thread — which is where draw() runs."""
+    if RegionScreenshot.cursor_set == on:
+        return
+    window = glfw.get_current_context()
+    if window is None:
+        return
+    try:
+        if on and RegionScreenshot.cursor is None:
+            img, hot = _build_cursor_image()
+            RegionScreenshot.cursor = glfw.create_cursor(img, hot, hot)
+        glfw.set_cursor(window, RegionScreenshot.cursor if on else None)
+        RegionScreenshot.cursor_set = on
+        # Keep the per-frame shape push (mouse_cursor.apply) from our image.
+        mouse_cursor.note_external_cursor(on)
+    except Exception as e:
+        print(f"region_screenshot: cursor swap failed: {e}")
+
+
+def arm():
+    """Enter capture mode (idempotent)."""
+    RegionScreenshot.armed = True
+    RegionScreenshot.start = None
+    request_render()
+
+
+def cancel():
+    RegionScreenshot.armed = False
+    RegionScreenshot.start = None
+    request_render()
+
+
+def toggle():
+    cancel() if RegionScreenshot.armed else arm()
+
+
+def _open_captured(path):
+    """screenshot.py's on_captured: runs on the render thread inside
+    post_frame — defer the editor work to between frames, like any other
+    external window mutation. The shot becomes an editor TAB without
+    stealing the selection (OpenFiles.open_file only — not open_in_editor,
+    whose jump_to_path the editor adopts as its active tab): the user is
+    mid-work in whatever they were screenshotting. The tab bars repaint so
+    the new tab shows. The saved file's PATH also goes on the clipboard
+    (text, via GLFW's clipboard — the studio is the focused Wayland client,
+    so this is the one clipboard write that always lands)."""
+    from meltygui.core.runtime.extensions import source_window as editor_window_draw_state
+
+    def _land():
+        open_files = getattr(getattr(Melty.vis, "root", None), "open_files", None)
+        if open_files is not None:
+            open_files.open_file(path)
+            # The tab list changed under the editors' bodies: force both
+            # instances through their blit cache so the new tab appears.
+            for inst in (0, 1):
+                win = editor_window_draw_state(inst)
+                if win is not None and Melty.cache is not None and win._tile_id is not None:
+                    Melty.cache.invalidate_up(win._tile_id, force=True, max_depth=4)
+        imgui.set_clipboard_text(str(path))
+        request_render()
+    Melty.post_to_render(_land)
+
+
+def _finish(x0, y0, x1, y1):
+    """Release: queue the framebuffer read of the box (settled a couple of
+    frames so this frame's overlay — crosshair, box — has cleared)."""
+    from meltygui.core.graphics.screenshot import request_region_capture
+    RegionScreenshot.armed = False
+    RegionScreenshot.start = None
+    left, top = min(x0, x1), min(y0, y1)
+    w, h = abs(x1 - x0), abs(y1 - y0)
+    if w < _MIN_BOX_PX or h < _MIN_BOX_PX:
+        # A click, not a box: stay armed so the user can try again.
+        RegionScreenshot.armed = True
+        request_render()
+        return
+    request_region_capture(left, top, w, h, Melty.frame_count,
+                           name="screenshot", on_captured=_open_captured)
+
+
+def box_label_lines(x0, y0, x1, y1):
+    """The readout for a normalized box (x0 <= x1, y0 <= y1), in WINDOW
+    POINTS — the coordinate system every draw_state rect and the capture
+    itself use, so a measurement read off the label maps straight onto
+    `draw_state.abs_left` / `width` values. Line 1 = top-left corner,
+    line 2 = size."""
+    x, y = int(round(x0)), int(round(y0))
+    w, h = int(round(x1 - x0)), int(round(y1 - y0))
+    return (f"{x}, {y}", f"{w} × {h}")
+
+
+def label_rect(x0, y0, x1, y1, label_w, label_h, display_w, display_h, gap):
+    """Where the readout pill goes: below the box, right-aligned to its
+    right edge (outside, so the measured content stays visible). Off the
+    bottom of the display → inside the box's bottom-right corner; past the
+    right edge → slid left to fit; a box that fills the screen → inside,
+    clamped. Returns (left, top)."""
+    left = x1 - label_w
+    top = y1 + gap
+    if top + label_h > display_h:
+        top = y1 - gap - label_h
+        left = x1 - gap - label_w
+    left = max(0.0, min(left, display_w - label_w))
+    top = max(0.0, top)
+    return left, top
+
+
+def _draw_box_label(overlay, x0, y0, x1, y1, display_w, display_h):
+    """Paint the coordinate/size readout next to the drag box (the "measure
+    tool" half of the feature): a dark pill, box-coloured text."""
+    # [tint=(0.35, 0.75, 1.0)]
+    padding = 5
+    # [tint=(0.95, 0.61, 0.07)]
+    gap = 6
+    # [tint=(0.36, 0.68, 0.89)]
+    label_background = (0.05, 0.05, 0.08, 0.85)
+    lines = box_label_lines(x0, y0, x1, y1)
+    sizes = [imgui.calc_text_size(line) for line in lines]
+    text_w = max(size.x for size in sizes)
+    line_h = sizes[0].y
+    label_w = text_w + padding * 2
+    label_h = line_h * len(lines) + padding * 2
+    left, top = label_rect(x0, y0, x1, y1, label_w, label_h, display_w, display_h, gap)
+    overlay.add_rect_filled(left, top, left + label_w, top + label_h,
+                            pack_color(*label_background), rounding=4.0)
+    overlay.add_rect(left, top, left + label_w, top + label_h,
+                     pack_color(*_BOX_COLOR), rounding=4.0, thickness=1.0)
+    text_color = pack_color(*_BOX_COLOR)
+    for index, line in enumerate(lines):
+        overlay.add_text(left + padding, top + padding + line_h * index, text_color, line)
+
+
+def draw(draw_state):
+    """Per-frame body (from draw_main): claim the mouse, track the box, paint
+    the crosshair/box + its coordinate/size readout on the overlay, and fire
+    the capture on release."""
+    if not RegionScreenshot.armed:
+        _set_tool_cursor(False)     # back to the default after cancel / esc
+        return
+    if any(k == glfw.KEY_ESCAPE for k, _ in Core.melty.frame_key_events):
+        cancel()
+        _set_tool_cursor(False)
+        return
+    _set_tool_cursor(True)
+
+    io = imgui.get_io()
+    full = (0.0, 0.0, float(io.display_size.x), float(io.display_size.y))
+    sub = dict(view_id="region_shot", rect=full, priority_delta=_PRIORITY_DELTA)
+    down = draw_state.on_action("left_mouse_down", **sub)
+    drag = draw_state.on_action("left_mouse_drag", **sub)
+    release = draw_state.on_action("left_mouse_drag_release", **sub)
+    draw_state.on_action("left_mouse_up", **sub)     # claimed so nothing under us sees the click
+    draw_state.on_action("left_mouse_click", **sub)
+
+    mx, my = imgui.get_mouse_pos()
+    if down is not None:
+        RegionScreenshot.start = (float(down.x), float(down.y))
+    if release is not None and RegionScreenshot.start is not None:
+        sx, sy = RegionScreenshot.start
+        _finish(sx, sy, float(release.x), float(release.y))
+        return          # nothing painted this frame - the capture reads a clean frame
+    if drag is None and RegionScreenshot.start is not None and not imgui.is_mouse_down(0):
+        RegionScreenshot.start = None   # button went up without the drag activating
+
+    if RegionScreenshot.start is not None:
+        overlay = imgui.get_overlay_draw_list()
+        overlay.channels_set_current(Core.melty.max_layer - 1)
+        sx, sy = RegionScreenshot.start
+        x0, y0, x1, y1 = min(sx, mx), min(sy, my), max(sx, mx), max(sy, my)
+        overlay.add_rect_filled(x0, y0, x1, y1, pack_color(*_FILL_COLOR))
+        overlay.add_rect(x0, y0, x1, y1, pack_color(*_BOX_COLOR), 0.0, 0, 1.0)
+        _draw_box_label(overlay, x0, y0, x1, y1, full[2], full[3])
+        # The box's moving edge tracks the cursor: keep frames coming.
+        request_render()