Publish showcase_core.py from marimo

showcase_core.py

@@ -0,0 +1,346 @@
+"""Build the capability gallery: one screenshot per thing the harness can do.
+
+Run it on a real desktop (or under Xvfb) and it writes ``gallery/<id>.png`` for every
+capability registered in this file, plus ``gallery/index.json`` and a gallery page.
+
+The screenshots are of the harness's *actual* behaviour, not mock-ups:
+
+* **terminal shots** are captured stdout/stderr from a real command, rendered to an image
+* **desktop shots** are real screen captures taken while the harness acts on a real
+  X11/Windows desktop (element boxes, the resolved click point, and the app's own
+  reaction are drawn or visible)
+
+Nothing here is faked: if a command fails, its real failure is what gets pictured.
+
+    python showcase.py                 # everything
+    python showcase.py --only clarify  # one capability by id substring
+    python showcase.py --list          # list ids without rendering
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import textwrap
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Optional
+
+ROOT = Path(__file__).resolve().parent
+GALLERY = ROOT / "gallery"
+PY = sys.executable
+MONO_TTFS = (
+    "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf",          # Debian/Ubuntu
+    "C:/Windows/Fonts/consola.ttf",                                  # Windows (Consolas)
+    "C:/Windows/Fonts/lucon.ttf",                                    # Windows (Lucida)
+    "/System/Library/Fonts/Menlo.ttc",                               # macOS
+    "/Library/Fonts/Menlo.ttc",
+)
+MONO_BOLD_TTFS = (
+    "/usr/share/fonts/truetype/dejavu/DejaVuSansMono-Bold.ttf",
+    "C:/Windows/Fonts/consolab.ttf",
+    "/System/Library/Fonts/Menlo.ttc",
+)
+SCREEN_W, SCREEN_H = 1280, 800
+TERM_COLS = 108
+TERM_BG = (13, 17, 23)
+TERM_FG = (201, 209, 217)
+TERM_GREEN = (63, 185, 80)
+TERM_RED = (248, 81, 73)
+TERM_DIM = (139, 148, 158)
+
+CATALOG: list["Shot"] = []
+
+
+@dataclass
+class Shot:
+    """One capability, and the evidence that it works."""
+
+    id: str
+    category: str
+    title: str
+    shows: list[str]                 # the public callables this picture demonstrates
+    note: str = ""                  # one line the card can print under the image
+    kind: str = "terminal"          # "terminal" | "desktop"
+    argv: list[str] | None = None   # for terminal shots: the command to run
+    env: Optional[dict] = None      # extra environment for the command
+    code: str | None = None         # for terminal shots: a python snippet to run
+    scene: str | None = None        # for desktop shots: a named scene below
+    make: Optional[Callable] = None  # for desktop shots: builds the picture
+    prepare: Optional[Callable] = None  # for terminal shots: set the scene up first
+
+
+def shot(**kwargs):
+    def wrap(fn=None):
+        s = Shot(**kwargs)
+        CATALOG.append(s)
+        return fn
+    return wrap
+
+
+# --------------------------------------------------------------------------- #
+# rendering
+# --------------------------------------------------------------------------- #
+
+def _fonts(size=15, bold=False):
+    from PIL import ImageFont
+
+    for path in (MONO_BOLD_TTFS if bold else MONO_TTFS):
+        try:
+            return ImageFont.truetype(path, size)
+        except Exception:
+            continue
+    return ImageFont.load_default()      # last resort: still produces a picture
+
+
+def _wrap(text: str, cols: int) -> list[str]:
+    out: list[str] = []
+    for line in text.replace("\t", "    ").splitlines():
+        if not line:
+            out.append("")
+            continue
+        out.extend(textwrap.wrap(line, cols, drop_whitespace=False,
+                                 replace_whitespace=False) or [""])
+    return out
+
+
+def terminal_image(title: str, output: str, subtitle: str = "") -> "Image.Image":
+    """Render captured output as a terminal-window screenshot."""
+    from PIL import Image, ImageDraw
+
+    body_font, title_font = _fonts(15), _fonts(14, bold=True)
+    lines = _wrap(output.rstrip("\n") or "(no output)", TERM_COLS)
+    wrapped_title = _wrap(title, 78)
+    sub = _wrap(subtitle, 96) if subtitle else []
+    line_h, pad = 21, 18
+    head_h = 46 + 20 * len(wrapped_title) + 19 * len(sub)
+    height = head_h + line_h * len(lines) + 26
+
+    image = Image.new("RGB", (1240, height), TERM_BG)
+    draw = ImageDraw.Draw(image)
+    draw.rectangle([0, 0, 1240, 34], fill=(22, 27, 34))
+    for i, colour in enumerate([(255, 95, 86), (255, 189, 46), (39, 201, 63)]):
+        draw.ellipse([18 + i * 22, 12, 30 + i * 22, 24], fill=colour)
+    y = 46
+    for line in wrapped_title:
+        draw.text((24, y), line, font=title_font, fill=(230, 237, 243))
+        y += 20
+    for line in sub:
+        draw.text((24, y), line, font=_fonts(13), fill=TERM_DIM)
+        y += 19
+    y = head_h
+    for line in lines:
+        colour = TERM_FG
+        stripped = line.strip()
+        if stripped.startswith("$ ") or stripped.startswith("python -m"):
+            colour = TERM_GREEN
+        elif any(word in stripped for word in ("result: failure", "ERROR", "FAILED",
+                                               "refused", "Traceback", "Error:")):
+            colour = TERM_RED
+        elif stripped.startswith("result: success") or stripped.startswith("score: correct"):
+            colour = TERM_GREEN
+        draw.text((24, y), line, font=body_font, fill=colour)
+        y += line_h
+    return image
+
+
+def run_argv(argv: list[str], *, extra_env: dict | None = None) -> tuple[int, str]:
+    env = dict(os.environ, **(extra_env or {}))
+    proc = subprocess.run(argv, capture_output=True, text=True, timeout=900, env=env)
+    text = proc.stdout + (("\n" + proc.stderr) if proc.stderr.strip() else "")
+    return proc.returncode, text
+
+
+def _header(display: str) -> str:
+    return (f"$ {display}" + chr(10))
+
+
+# --------------------------------------------------------------------------- #
+# the desktop: a real X server, real capture, real input
+# --------------------------------------------------------------------------- #
+
+DISPLAY_PROC = None
+
+
+def _display_works() -> bool:
+    return subprocess.run(["xdpyinfo"], capture_output=True).returncode == 0
+
+
+def ensure_display() -> str:
+    """Give the process a real display, starting Xvfb on Linux when there is none.
+
+    Verified rather than assumed: a stale ``DISPLAY`` pointing at a dead server is
+    worse than no display at all, because every scene then fails on ``tk.Tk()``.
+    """
+    global DISPLAY_PROC
+    if platform.system() in ("Windows", "Darwin"):
+        return os.environ.get("DISPLAY", "(native)")
+    if os.environ.get("DISPLAY") and _display_works():
+        return os.environ["DISPLAY"]
+    if shutil.which("Xvfb") is None:
+        return "(none)"
+    os.environ["DISPLAY"] = ":99"
+    Path.home().joinpath(".Xauthority").touch()
+    os.environ["XAUTHORITY"] = str(Path.home() / ".Xauthority")
+    DISPLAY_PROC = subprocess.Popen(
+        ["Xvfb", ":99", "-screen", "0", f"{SCREEN_W}x{SCREEN_H}x24", "-ac", "-nolisten", "tcp"],
+        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, start_new_session=True,
+    )
+    for _ in range(80):
+        if _display_works():
+            break
+        time.sleep(0.25)
+    return os.environ["DISPLAY"]
+
+
+SCENES: dict[str, str] = {}
+
+
+def scene(name: str, source: str) -> str:
+    """Register a Tk app used as the desktop a capability is demonstrated on."""
+    SCENES[name] = source
+    return name
+
+
+def open_scene(name: str, tmp: Path) -> subprocess.Popen:
+    """Launch a scene on the real display and wait until its window is mapped."""
+    marker = tmp / f"{name}.marker"
+    source = SCENES[name].replace("__MARKER__", str(marker))
+    script = tmp / f"{name}.py"
+    script.write_text(source)
+    proc = subprocess.Popen([PY, str(script)], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    ready = Path(str(marker) + ".ready")
+    deadline = time.time() + 25
+    while time.time() < deadline and not ready.exists():
+        if proc.poll() is not None:
+            raise RuntimeError(f"scene {name!r} exited early: {proc.stderr.read().decode()[:400]}")
+        time.sleep(0.2)
+    if not ready.exists():
+        raise RuntimeError(f"scene {name!r} never mapped a window")
+    time.sleep(0.6)                      # let the toolkit finish painting
+    return proc
+
+
+def close_scene(proc: subprocess.Popen) -> None:
+    proc.terminate()
+    try:
+        proc.wait(timeout=10)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait(timeout=5)
+    time.sleep(0.5)
+
+
+def grab() -> "Image.Image":
+    from tiny_computer_agent import GrabScreen
+    return GrabScreen(monitor=1).capture().frame
+
+
+def annotate(image, elements, *, click=None, title=""):
+    """Draw what the harness *saw* (boxes + labels) and where it clicked."""
+    from PIL import ImageDraw
+    out = image.convert("RGB").copy()
+    draw = ImageDraw.Draw(out)
+    font = _fonts(13, bold=True)
+    for e in elements:
+        x, y, w, h = e.x, e.y, max(e.width, 1), max(e.height, 1)
+        colour = (255, 138, 0) if e.kind != "grid" else (90, 120, 200)
+        draw.rectangle([x, y, x + w, y + h], outline=colour, width=2)
+        tag = f"{e.label}"[:34]
+        tw = draw.textlength(tag, font=font)
+        draw.rectangle([x, max(0, y - 17), x + tw + 8, y], fill=colour)
+        draw.text((x + 4, max(0, y - 16)), tag, font=font, fill=(16, 16, 16))
+    if click is not None:
+        cx, cy = click
+        draw.line([cx - 22, cy, cx + 22, cy], fill=(255, 0, 60), width=2)
+        draw.line([cx, cy - 22, cx, cy + 22], fill=(255, 0, 60), width=2)
+        draw.ellipse([cx - 9, cy - 9, cx + 9, cy + 9], outline=(255, 0, 60), width=3)
+    if title:
+        draw.rectangle([0, 0, out.width, 30], fill=(20, 22, 28))
+        draw.text((12, 8), title, font=_fonts(15, bold=True), fill=(255, 255, 255))
+    return out
+
+
+def save(image, sid: str) -> Path:
+    GALLERY.mkdir(exist_ok=True)
+    target = GALLERY / f"{sid}.png"
+    image.save(target, optimize=True)
+    return target
+
+
+# --------------------------------------------------------------------------- #
+# rendering a shot
+# --------------------------------------------------------------------------- #
+
+def render_terminal(s: "Shot", tmp: Optional[Path] = None) -> "Image.Image":
+    """Run the shot's command for real and picture what it printed."""
+    cleanup = s.prepare(tmp) if s.prepare is not None else None
+    try:
+        return _terminal_body(s)
+    finally:
+        if cleanup is not None:
+            cleanup()
+
+
+def _terminal_body(s: "Shot") -> "Image.Image":
+    if s.argv is not None:
+        argv = [str(a).replace("{py}", PY) for a in s.argv]
+        _, text = run_argv(argv, extra_env=s.env)
+        shown = " ".join("python" if a == PY else str(a) for a in s.argv)
+    else:
+        argv = [PY, "-c", s.code]
+        _, text = run_argv(argv, extra_env=s.env)
+        shown = "python -c  # " + (s.note or s.title)
+    return terminal_image(s.title, text, shown)
+
+
+def render_desktop(s: "Shot", tmp: Path) -> "Image.Image":
+    """Run the shot's desktop scene for real and picture the harness acting on it."""
+    if s.make is None:
+        raise RuntimeError(f"desktop shot {s.id!r} has no make() callable")
+    if not os.environ.get("DISPLAY"):
+        raise RuntimeError(f"desktop shot {s.id!r} needs a display")
+    return s.make(tmp)
+
+
+def overlay_lines(image, lines, *, title=""):
+    """A dark strip of text under a picture - for the episode trace next to the pixels."""
+    from PIL import ImageDraw
+    out = image.convert("RGB").copy()
+    draw = ImageDraw.Draw(out)
+    font = _fonts(15)
+    strip = 24 * len(lines) + 14
+    draw.rectangle([0, out.height - strip, out.width, out.height], fill=(13, 17, 23))
+    y = out.height - strip + 7
+    for line in lines:
+        draw.text((12, y), line, font=font, fill=TERM_FG)
+        y += 24
+    if title:
+        draw.rectangle([0, 0, out.width, 30], fill=(20, 22, 28))
+        draw.text((12, 8), title, font=_fonts(15, bold=True), fill=(255, 255, 255))
+    return out
+
+
+def side_by_side(left, right, *, title="", gap_label=("before", "after")):
+    """Two frames of the same window, split down the middle."""
+    from PIL import Image, ImageDraw
+    width, height = left.width + right.width + 4, max(left.height, right.height) + 34
+    out = Image.new("RGB", (width, height), (13, 17, 23))
+    draw = ImageDraw.Draw(out)
+    out.paste(left, (0, 34))
+    out.paste(right, (left.width + 4, 34))
+    draw.rectangle([left.width, 34, left.width + 4, height], fill=(255, 255, 255))
+    draw.rectangle([0, 0, width, 30], fill=(20, 22, 28))
+    draw.text((12, 8), title, font=_fonts(15, bold=True), fill=(255, 255, 255))
+    draw.text((12, 16 + left.height), gap_label[0], font=_fonts(14, bold=True), fill=TERM_DIM)
+    draw.text((left.width + 16, 16 + left.height), gap_label[1], font=_fonts(14, bold=True), fill=TERM_DIM)
+    return out
+
+
+def crop(image, box):
+    return image.convert("RGB").crop(box)