claude-human 0.2.0__py3-none-any.whl

claude_human/__init__.py

@@ -0,0 +1,4 @@
+"""Tools for a person and an agent to share one Mac: screen capture, typing at the lock screen and
+password panels through a virtual HID keyboard, and a station that hands one window to a phone."""
+
+__version__ = "0.2.0"

claude_human/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

claude_human/cli.py

@@ -0,0 +1,222 @@
+"""The ``claude-human`` command.
+
+    claude-human build-tools [--out DIR] [--only sckshot|vhid] [--identity ID] [--bundle-id ID]
+    claude-human windows
+    claude-human screenshot --out FILE [--window ID | --app NAME] [--max-width N]
+    claude-human state
+    claude-human unlock          (password on stdin)
+    claude-human relock
+    claude-human use-password
+    claude-human approve         (password on stdin)
+    claude-human skill [--dir DIR]
+    claude-human station [--port N] [--app NAME] [--token-file FILE] [--fps N]
+    claude-human prepare [--phase place|input|all] APP STEP...
+
+A password is read only from stdin (or typed at a hidden prompt when stdin is a terminal). There is
+no option that takes one, so it never appears in the process list or the shell history.
+"""
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from . import __version__, paths
+
+TOOLS = ("sckshot", "vhid")
+
+#: The Claude Code skill that ships inside the package.
+SKILL_FILE = Path(__file__).resolve().parent / "skill" / "SKILL.md"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="claude-human",
+                                description="Screen capture and lock screen typing for a Mac a person drives remotely.")
+    p.add_argument("--version", action="version", version=f"claude-human {__version__}")
+    p.add_argument("--sckshot", help="path to the sckshot executable (default: $CLAUDE_HUMAN_SCKSHOT "
+                                     "or <bin dir>/sckshot.app/Contents/MacOS/sckshot)")
+    p.add_argument("--vhid", help="path to vhid_type (default: $CLAUDE_HUMAN_VHID or <bin dir>/vhid_type)")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    b = sub.add_parser("build-tools", help="compile sckshot.app and vhid_type")
+    b.add_argument("--out", help="output folder (default: $CLAUDE_HUMAN_BIN_DIR or ~/.local/share/claude-human/bin)")
+    b.add_argument("--only", choices=TOOLS, action="append", help="build only this tool (repeatable)")
+    b.add_argument("--identity", help='signing identity for sckshot: "auto" (default), "-" for ad-hoc, '
+                                      '"none" to skip signing, or an identity name')
+    b.add_argument("--bundle-id", help="bundle identifier for sckshot.app (default local.claude-human.sckshot)")
+    b.add_argument("--usage-text", help="the Screen Recording usage text shown by macOS")
+    b.add_argument("--pqrs-commit", help="Karabiner-DriverKit-VirtualHIDDevice commit to build vhid_type against")
+
+    sub.add_parser("windows", help="list the ordinary on-screen windows as JSON")
+
+    s = sub.add_parser("screenshot", help="capture the screen or one window with sckshot")
+    s.add_argument("--out", required=True, help="output file (.png, or .jpg/.jpeg for JPEG)")
+    g = s.add_mutually_exclusive_group()
+    g.add_argument("--window", type=int, help="CGWindowID to capture")
+    g.add_argument("--app", help="capture the largest window of this application")
+    s.add_argument("--max-width", type=int, default=0, help="scale down to this width (0 keeps the size)")
+
+    sub.add_parser("state", help="print whether the session is locked and whether a password panel is up")
+
+    u = sub.add_parser("unlock", help="type the password from stdin at the lock screen")
+    u.add_argument("--attempts", type=int, default=2, choices=(1, 2), help="tries before giving up (default 2)")
+    sub.add_parser("relock", help="sleep the display and wait for the session to lock")
+    sub.add_parser("use-password", help="switch a Touch ID panel to its password field (presses Return only)")
+    sub.add_parser("approve", help="type the password from stdin into the password panel on screen")
+
+    st = sub.add_parser("station", help="serve one window (or the display) to a phone, with input")
+    st.add_argument("--port", type=int, default=8789, help="port on 127.0.0.1 (default 8789, 0 for a free one)")
+    st.add_argument("--app", help="pin the token to this application's window (it then cannot list or choose windows)")
+    st.add_argument("--token-file", help="file holding the token (default: $CLAUDE_HUMAN_STATION_TOKEN_FILE or "
+                                         "~/.config/claude-human/station-token, made with mode 0600 if missing). "
+                                         "$CLAUDE_HUMAN_STATION_TOKEN wins over any file")
+    st.add_argument("--fps", type=float, default=8.0, help="default frames per second of a stream")
+
+    pr = sub.add_parser("prepare", help="run a window recipe (open, wait, search, click...) before handing a window over")
+    pr.add_argument("--phase", choices=("place", "input", "all"), default="all",
+                    help="place runs open and wait only, input runs the rest, all runs both (default)")
+    pr.add_argument("app", help="the application the recipe is for")
+    pr.add_argument("steps", nargs="*", help='steps such as "open x-apple.systempreferences:..." "wait 1" "search Login Items"')
+
+    k = sub.add_parser("skill", help="install the Claude Code skill as <dir>/claude-human/SKILL.md")
+    k.add_argument("--dir", default="~/.claude/skills", help="skills folder (default ~/.claude/skills)")
+    return p
+
+
+def install_skill(skills_dir: str | os.PathLike) -> Path:
+    """Copy the packaged SKILL.md to <skills_dir>/claude-human/SKILL.md and return that path."""
+    target = Path(skills_dir).expanduser() / "claude-human" / "SKILL.md"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(SKILL_FILE, target)
+    return target
+
+
+def build_env(args: argparse.Namespace) -> dict:
+    """The environment the build scripts read their settings from."""
+    env = dict(os.environ)
+    for opt, var in (("identity", "CLAUDE_HUMAN_IDENTITY"), ("bundle_id", "CLAUDE_HUMAN_BUNDLE_ID"),
+                     ("usage_text", "CLAUDE_HUMAN_USAGE"), ("pqrs_commit", "CLAUDE_HUMAN_PQRS_COMMIT")):
+        value = getattr(args, opt, None)
+        if value:
+            env[var] = value
+    return env
+
+
+def build_commands(args: argparse.Namespace) -> list[list[str]]:
+    """The build script invocations for ``build-tools``, in order."""
+    out = paths.bin_dir(args.out)
+    targets = {"sckshot": out / "sckshot.app", "vhid": out / paths.VHID_NAME}
+    return [["bash", str(paths.tool_source(t) / "build.sh"), str(targets[t])]
+            for t in TOOLS if not args.only or t in args.only]
+
+
+def station_auth(args: argparse.Namespace):
+    """The TokenAuth for ``claude-human station``, and where its token came from (never the token)."""
+    from .station import auth  # noqa: PLC0415
+    token = os.environ.get(auth.ENV_TOKEN, "").strip()
+    if token:
+        return auth.TokenAuth(token, app=args.app), f"${auth.ENV_TOKEN}"
+    path = args.token_file or os.environ.get(auth.ENV_TOKEN_FILE) or None
+    _tok, where = auth.load_or_create_token(path)
+    return auth.TokenAuth(token_file=where, app=args.app), str(where)
+
+
+def serve_station(args: argparse.Namespace) -> int:
+    from .station import make_server  # noqa: PLC0415
+    a, where = station_auth(args)
+    srv = make_server(a, port=args.port, fps=args.fps)
+    port = srv.server_address[1]
+    print(f"station on http://127.0.0.1:{port}/view (token from {where}"
+          f"{', pinned to ' + args.app if args.app else ''})", flush=True)
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        srv.server_close()
+    return 0
+
+
+def read_password(stream=None) -> str:
+    stream = stream or sys.stdin
+    if stream.isatty():
+        return getpass.getpass("password: ")
+    return stream.readline().rstrip("\r\n")
+
+
+def _report(ok: bool, detail: str) -> int:
+    print(("OK " if ok else "FAIL ") + detail)
+    return 0 if ok else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    cmd = args.command
+
+    if cmd == "build-tools":
+        if sys.platform != "darwin":
+            print("build-tools needs macOS (swiftc, clang++, codesign)", file=sys.stderr)
+            return 2
+        env = build_env(args)
+        for c in build_commands(args):
+            r = subprocess.run(c, env=env)
+            if r.returncode != 0:
+                print(f"failed: {' '.join(c)}", file=sys.stderr)
+                return r.returncode
+        return 0
+
+    if cmd == "skill":
+        print(install_skill(args.dir))
+        return 0
+
+    if cmd == "station":
+        return serve_station(args)
+
+    if cmd == "prepare":
+        from .station import prepare  # noqa: PLC0415
+        log = prepare.run(args.app, args.steps, phase=args.phase)
+        for line in log:
+            print(line)
+        return 0 if prepare.succeeded(log) else 1
+
+    if cmd in ("windows", "screenshot", "state"):
+        from . import screenshot  # noqa: PLC0415 - needs Quartz
+        if cmd == "windows":
+            print(json.dumps(screenshot.windows(), indent=2))
+            return 0
+        if cmd == "state":
+            print(json.dumps({"locked": screenshot.screen_locked(),
+                              "auth_prompt": screenshot.auth_prompt(),
+                              "blocked_by": screenshot.blocked_by()}, indent=2))
+            return 0
+        wid = screenshot.resolve(args.app, args.window)
+        if args.app and wid is None:
+            print(f"no window of {args.app!r} is on screen", file=sys.stderr)
+            return 1
+        try:
+            w, h = screenshot.save(Path(args.out), wid, max_width=args.max_width, sckshot=args.sckshot)
+        except (FileNotFoundError, RuntimeError, subprocess.TimeoutExpired) as e:
+            print(str(e), file=sys.stderr)
+            return 1
+        print(f"{args.out} {w}x{h}")
+        return 0
+
+    from . import unlock  # noqa: PLC0415
+    if cmd == "unlock":
+        return _report(*unlock.unlock(read_password(), helper=args.vhid, attempts=args.attempts))
+    if cmd == "relock":
+        return _report(*unlock.relock())
+    if cmd == "use-password":
+        return _report(*unlock.use_password(helper=args.vhid))
+    if cmd == "approve":
+        return _report(*unlock.approve(read_password(), helper=args.vhid))
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

claude_human/paths.py

@@ -0,0 +1,56 @@
+"""Where the compiled helpers live, and where their sources ship inside the package.
+
+Each path is resolved in this order: an explicit argument, an environment variable, then a default
+under the bin directory. The bin directory is ``CLAUDE_HUMAN_BIN_DIR`` or
+``~/.local/share/claude-human/bin``.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+ENV_BIN_DIR = "CLAUDE_HUMAN_BIN_DIR"
+ENV_SCKSHOT = "CLAUDE_HUMAN_SCKSHOT"
+ENV_VHID = "CLAUDE_HUMAN_VHID"
+
+SCKSHOT_IN_APP = Path("sckshot.app") / "Contents" / "MacOS" / "sckshot"
+VHID_NAME = "vhid_type"
+
+TOOLS = Path(__file__).resolve().parent / "tools"
+
+
+def bin_dir(override: str | os.PathLike | None = None) -> Path:
+    if override:
+        return Path(override).expanduser()
+    env = os.environ.get(ENV_BIN_DIR)
+    if env:
+        return Path(env).expanduser()
+    return Path.home() / ".local" / "share" / "claude-human" / "bin"
+
+
+def sckshot_path(override: str | os.PathLike | None = None) -> Path:
+    """The sckshot executable inside its .app bundle."""
+    if override:
+        return Path(override).expanduser()
+    env = os.environ.get(ENV_SCKSHOT)
+    if env:
+        return Path(env).expanduser()
+    return bin_dir() / SCKSHOT_IN_APP
+
+
+def vhid_path(override: str | os.PathLike | None = None) -> Path:
+    """The vhid_type executable."""
+    if override:
+        return Path(override).expanduser()
+    env = os.environ.get(ENV_VHID)
+    if env:
+        return Path(env).expanduser()
+    return bin_dir() / VHID_NAME
+
+
+def tool_source(name: str) -> Path:
+    """The folder holding a helper's source and build script ("sckshot" or "vhid")."""
+    path = TOOLS / name
+    if not (path / "build.sh").is_file():
+        raise ValueError(f"no build script for {name!r} in {TOOLS}")
+    return path

claude_human/screenshot.py

@@ -0,0 +1,318 @@
+"""What is on a Mac's screen, and its pixels.
+
+This module lists the windows a person works in, finds a window by application name, captures the
+screen or one window as JPEG, and answers three questions about the screen state: is the session
+locked, is a system dialog holding focus, and is a password panel (SecurityAgent) on screen.
+
+Capture runs the ``sckshot`` helper (ScreenCaptureKit) and falls back to CGWindowListCreateImage,
+which is throttled on recent macOS. Quartz comes from ``pyobjc-framework-Quartz`` (the ``macos``
+extra) and is imported only when a function needs it, so the pure helpers work on any platform.
+
+Screen Recording must be granted to whatever captures: to sckshot.app for the fast path, and to the
+Python process (or the terminal or launchd job that runs it) for window titles and the fallback.
+Without the grant macOS returns windows with empty titles, which is the sign to look for.
+"""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import tempfile
+from typing import Any, Iterable
+
+from . import paths
+
+DEFAULT_MAX_WIDTH = 1100
+DEFAULT_QUALITY = 0.55
+
+#: Windows smaller than this are palettes, menus or helpers, not windows a person works in.
+MIN_WINDOW = (200, 150)
+
+#: System processes whose dialogs take exclusive focus. While one is up, synthetic clicks are
+#: accepted and delivered nowhere.
+BLOCKING_APPS = {"universalAccessAuthWarn", "UserNotificationCenter",
+                 "SecurityAgent", "CoreServicesUIAgent"}
+
+#: The owner of macOS credential panels.
+AUTH_OWNERS = {"SecurityAgent"}
+
+#: A credential panel is at least this size (SecurityAgent also keeps tiny offscreen helper windows)
+#: and at most this fraction of the display (the lock screen is a full-display surface).
+AUTH_MIN = 160
+AUTH_MAX_FRACTION = 0.7
+
+
+def _quartz():
+    import Quartz  # noqa: PLC0415 - macOS only, see the module docstring
+    return Quartz
+
+
+def _raw_windows() -> list[dict]:
+    q = _quartz()
+    opts = q.kCGWindowListOptionOnScreenOnly | q.kCGWindowListExcludeDesktopElements
+    return list(q.CGWindowListCopyWindowInfo(opts, q.kCGNullWindowID) or [])
+
+
+# ----------------------------------------------------------------------------- pure helpers
+
+def to_windows(raw: Iterable[dict], min_size: tuple[int, int] = MIN_WINDOW) -> list[dict]:
+    """Turn CGWindowListCopyWindowInfo entries into plain dicts, keeping only ordinary windows.
+
+    Only layer 0 is kept (the normal application layer). Menu bar items, the Dock and the wallpaper
+    live on other layers. The result is sorted by application and title."""
+    out = []
+    for w in raw:
+        b = w.get("kCGWindowBounds") or {}
+        width, height = int(b.get("Width", 0)), int(b.get("Height", 0))
+        if width < min_size[0] or height < min_size[1]:
+            continue
+        if int(w.get("kCGWindowLayer", 0)) != 0:
+            continue
+        out.append({
+            "id": int(w.get("kCGWindowNumber")),
+            "app": str(w.get("kCGWindowOwnerName") or ""),
+            "title": str(w.get("kCGWindowName") or ""),  # empty without Screen Recording
+            "x": int(b.get("X", 0)), "y": int(b.get("Y", 0)),
+            "width": width, "height": height,
+        })
+    out.sort(key=lambda w: (w["app"].lower(), w["title"].lower()))
+    return out
+
+
+def pick_window(wins: list[dict], app: str) -> int | None:
+    """The id of the window that best matches an application name, or None.
+
+    An exact (case-insensitive) name wins over a substring match, and among matches the largest
+    window wins, which is the document window rather than a palette or an alert."""
+    want = app.lower()
+    matches = [w for w in wins if w["app"].lower() == want]
+    if not matches:
+        matches = [w for w in wins if want in w["app"].lower()]
+    if not matches:
+        return None
+    return max(matches, key=lambda w: w["width"] * w["height"])["id"]
+
+
+def find_blocker(raw: Iterable[dict], blocking: set[str] = BLOCKING_APPS) -> str | None:
+    """The owner name of the first window, on any layer, that belongs to a blocking system app."""
+    for w in raw:
+        owner = str(w.get("kCGWindowOwnerName") or "")
+        if owner in blocking:
+            return owner
+    return None
+
+
+def find_auth_panel(raw: Iterable[dict], display: tuple[float, float],
+                    owners: set[str] = AUTH_OWNERS) -> dict | None:
+    """The first visible credential panel among windows listed front to back, or None.
+
+    ``display`` is the main display size in points. A panel is a window of an auth owner, not fully
+    transparent, larger than the helper windows and smaller than the lock screen surface."""
+    cap_w, cap_h = display[0] * AUTH_MAX_FRACTION, display[1] * AUTH_MAX_FRACTION
+    for w in raw:
+        if str(w.get("kCGWindowOwnerName") or "") not in owners:
+            continue
+        if float(w.get("kCGWindowAlpha", 1)) <= 0:
+            continue
+        b = w.get("kCGWindowBounds", {}) or {}
+        ww, hh = float(b.get("Width", 0)), float(b.get("Height", 0))
+        if ww < AUTH_MIN or hh < AUTH_MIN or ww > cap_w or hh > cap_h:
+            continue
+        return {"wid": int(w.get("kCGWindowNumber")),
+                "owner": str(w.get("kCGWindowOwnerName") or ""),
+                "title": str(w.get("kCGWindowName") or "")}
+    return None
+
+
+def sckshot_args(binary: str | os.PathLike, out: str, wid: int | None = None,
+                 max_width: int = 0) -> list[str]:
+    """The command line for one sckshot capture."""
+    args = [str(binary), "--out", str(out), "--max-width", str(int(max_width))]
+    if wid:
+        args += ["--window", str(int(wid))]
+    return args
+
+
+def parse_sckshot_output(stdout: bytes | str) -> tuple[int, int] | None:
+    """The image size from sckshot's "OK <w>x<h>" line, or None."""
+    if isinstance(stdout, str):
+        stdout = stdout.encode()
+    m = re.match(rb"OK (\d+)x(\d+)", stdout.strip())
+    return (int(m.group(1)), int(m.group(2))) if m else None
+
+
+# ----------------------------------------------------------------------------- windows
+
+def windows() -> list[dict]:
+    """Every ordinary on-screen window: ``{id, app, title, x, y, width, height}``."""
+    return to_windows(_raw_windows())
+
+
+def resolve(app: str | None, wid: int | None) -> int | None:
+    """Which window a request means right now.
+
+    A CGWindowID changes every time an application restarts, so storing one and using it later can
+    reach a different window. Pass the application name and the id is looked up again on every
+    call. With no application name, ``wid`` is returned as it is."""
+    if app:
+        return pick_window(windows(), app)
+    return wid
+
+
+def window_rect(wid: int):
+    for w in windows():
+        if w["id"] == wid:
+            return _quartz().CGRectMake(w["x"], w["y"], w["width"], w["height"])
+    return None
+
+
+# ----------------------------------------------------------------------------- screen state
+
+def screen_locked() -> bool:
+    """Whether the session reports itself locked.
+
+    A locked Mac still captures, but drops synthetic input, so a viewer would see a live picture that
+    ignores every tap. Note that a credential panel sets the same bit (see ``auth_prompt``)."""
+    try:
+        d = _quartz().CGSessionCopyCurrentDictionary()
+        return bool(d and d.get("CGSSessionScreenIsLocked"))
+    except Exception:
+        return False
+
+
+def blocked_by() -> str | None:
+    """The name of a system dialog currently holding focus, if one is.
+
+    All windows on all layers are checked, because these dialogs do not live on layer 0."""
+    try:
+        return find_blocker(_raw_windows())
+    except Exception:
+        return None
+
+
+def auth_prompt() -> dict | None:
+    """The credential panel (SecurityAgent) on screen, as ``{wid, owner, title}``, or None.
+
+    When macOS asks for a password to allow a change, it shows a separate floating panel owned by
+    SecurityAgent, not by the application that asked. The panel runs in secure input mode, so it
+    ignores synthetic keys and clicks (``claude_human.unlock.approve`` types into it through the
+    virtual HID keyboard). While it is up, ``CGSSessionScreenIsLocked`` reads True even though the
+    desktop behind it is live and can be captured. The window id is looked up on every call."""
+    try:
+        q = _quartz()
+        disp = q.CGDisplayBounds(q.CGMainDisplayID())
+        raw = q.CGWindowListCopyWindowInfo(q.kCGWindowListOptionOnScreenOnly, q.kCGNullWindowID) or []
+        return find_auth_panel(raw, (disp.size.width, disp.size.height))
+    except Exception:
+        return None
+
+
+# ----------------------------------------------------------------------------- capture
+
+def _sckshot_frame(wid: int | None, max_w: int, binary: str | os.PathLike) -> tuple[bytes, int, int] | None:
+    fd, tmp = tempfile.mkstemp(suffix=".jpg")
+    os.close(fd)
+    try:
+        r = subprocess.run(sckshot_args(binary, tmp, wid, max_w), capture_output=True, timeout=6)
+        if r.returncode != 0 or not os.path.exists(tmp) or os.path.getsize(tmp) == 0:
+            return None
+        with open(tmp, "rb") as fh:
+            data = fh.read()
+        size = parse_sckshot_output(r.stdout)
+        w, h = size if size else (int(max_w), 0)
+        return data, w, h
+    except Exception:
+        return None
+    finally:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+
+
+def _grab_legacy(wid: int | None):
+    """A CGImage through CGWindowListCreateImage, or None.
+
+    The per-window variant returns None on recent macOS, so a window is the whole display cropped to
+    the window's rectangle. When one window is asked for and the rectangle cannot be found (most
+    often because the window is on another desktop), this returns None and never the full screen:
+    returning the full screen would show every other window to someone who was given only one."""
+    q = _quartz()
+    try:
+        full = q.CGWindowListCreateImage(q.CGRectInfinite, q.kCGWindowListOptionOnScreenOnly,
+                                         q.kCGNullWindowID, q.kCGWindowImageNominalResolution)
+        if not wid:
+            return full
+        r = window_rect(wid)
+        if full is None or r is None:
+            return None
+        return q.CGImageCreateWithImageInRect(
+            full, q.CGRectMake(r.origin.x, r.origin.y, r.size.width, r.size.height))
+    except Exception:
+        return None
+
+
+def _downscale(img, max_w: int):
+    q = _quartz()
+    w, h = q.CGImageGetWidth(img), q.CGImageGetHeight(img)
+    if w <= max_w:
+        return img, w, h
+    scale = max_w / float(w)
+    nw, nh = int(w * scale), int(h * scale)
+    ctx = q.CGBitmapContextCreate(None, nw, nh, 8, 0, q.CGColorSpaceCreateDeviceRGB(),
+                                  q.kCGImageAlphaPremultipliedFirst)
+    q.CGContextSetInterpolationQuality(ctx, q.kCGInterpolationMedium)
+    q.CGContextDrawImage(ctx, q.CGRectMake(0, 0, nw, nh), img)
+    return q.CGBitmapContextCreateImage(ctx), nw, nh
+
+
+def _jpeg(img, quality: float) -> bytes:
+    q = _quartz()
+    from CoreFoundation import CFDataCreateMutable  # noqa: PLC0415
+    data = CFDataCreateMutable(None, 0)
+    dest = q.CGImageDestinationCreateWithData(data, "public.jpeg", 1, None)
+    q.CGImageDestinationAddImage(dest, img, {"kCGImageDestinationLossyCompressionQuality": quality})
+    q.CGImageDestinationFinalize(dest)
+    return bytes(data)
+
+
+def capture(wid: int | None = None, *, max_width: int = DEFAULT_MAX_WIDTH,
+            quality: float = DEFAULT_QUALITY,
+            sckshot: str | os.PathLike | None = None) -> tuple[bytes, int, int] | None:
+    """One JPEG of the screen (``wid`` None) or of one window: ``(bytes, width, height)`` or None.
+
+    This does not check the lock state. Use ``frame`` for that."""
+    fr = _sckshot_frame(wid, max_width, paths.sckshot_path(sckshot))
+    if fr is not None:
+        return fr
+    img = _grab_legacy(wid)
+    if img is None:
+        return None
+    img, w, h = _downscale(img, max_width)
+    return _jpeg(img, quality), w, h
+
+
+def frame(wid: int | None = None, **kw: Any) -> tuple[bytes, int, int] | None:
+    """Like ``capture``, but None at once while the session is locked.
+
+    While locked, macOS refuses the capture and the fallback path blocks for about 30 seconds before
+    returning black. A credential panel is the exception: it sets the locked bit while the desktop
+    is live, so a frame is still taken when ``auth_prompt()`` finds one."""
+    if screen_locked() and auth_prompt() is None:
+        return None
+    return capture(wid, **kw)
+
+
+def save(out: str | os.PathLike, wid: int | None = None, *, max_width: int = 0,
+         sckshot: str | os.PathLike | None = None) -> tuple[int, int]:
+    """Write one capture to ``out`` with sckshot (PNG, or JPEG for .jpg/.jpeg). Returns its size.
+
+    Raises FileNotFoundError when sckshot is not built and RuntimeError when the capture fails."""
+    binary = paths.sckshot_path(sckshot)
+    if not binary.exists():
+        raise FileNotFoundError(f"sckshot is not built at {binary} (run: claude-human build-tools)")
+    r = subprocess.run(sckshot_args(binary, str(out), wid, max_width), capture_output=True, timeout=20)
+    size = parse_sckshot_output(r.stdout)
+    if r.returncode != 0 or size is None:
+        raise RuntimeError((r.stderr or r.stdout or b"").decode(errors="replace").strip() or "capture failed")
+    return size