chromeappcap 0.1.0__tar.gz

chromeappcap-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: chromeappcap
+Version: 0.1.0
+Summary: CLI for polished website screenshots
+Author: William Blackie
+Keywords: cli,screenshot,chrome,playwright,automation
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer<1.0,>=0.12
+Requires-Dist: playwright<2.0,>=1.44
+Requires-Dist: Pillow<12.0,>=10.0
+Requires-Dist: pyobjc-framework-Quartz<12.0,>=11.0; sys_platform == "darwin"
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+
+# chromeappcap
+
+Screenshots that look like you meant to share them.
+
+`chromeappcap` is a CLI for polished website/app screenshots with native Chrome app-window capture on macOS and Playwright fallback everywhere else.
+
+## Install
+
+### `pipx` (recommended)
+
+```bash
+pipx install chromeappcap
+```
+
+### `uvx` (zero install)
+
+```bash
+uvx --from git+https://github.com/William-Blackie/chromeappcap.git chromeappcap https://example.com
+```
+
+### local dev
+
+```bash
+git clone https://github.com/William-Blackie/chromeappcap.git
+cd chromeappcap
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+playwright install chromium
+```
+
+Or:
+
+```bash
+make dev-install
+make playwright-install
+```
+
+## Quick Start
+
+```bash
+chromeappcap https://example.com
+```
+
+By default, output is saved in your current shell directory.
+
+## Common Commands
+
+Native app-window capture (macOS):
+
+```bash
+chromeappcap https://example.com --capture-mode app -o native.png
+```
+
+High-quality compressed WebP:
+
+```bash
+chromeappcap https://example.com --capture-mode app --device-scale 2.5 --format webp --compress --quality 85 -o shot.webp
+```
+
+Cross-platform page fallback with no synthetic frame:
+
+```bash
+chromeappcap https://example.com --capture-mode page --no-frame -o raw.png
+```
+
+## Notes
+
+- `--capture-mode auto` prefers app mode on macOS and falls back to page mode.
+- `--capture-mode page` requires Playwright Chromium:
+
+```bash
+playwright install chromium
+```
+
+- macOS app mode requires Screen Recording permission:
+  - `System Settings > Privacy & Security > Screen Recording`
+
+## Help
+
+```bash
+chromeappcap --help
+```

chromeappcap-0.1.0/README.md

@@ -0,0 +1,83 @@
+# chromeappcap
+
+Screenshots that look like you meant to share them.
+
+`chromeappcap` is a CLI for polished website/app screenshots with native Chrome app-window capture on macOS and Playwright fallback everywhere else.
+
+## Install
+
+### `pipx` (recommended)
+
+```bash
+pipx install chromeappcap
+```
+
+### `uvx` (zero install)
+
+```bash
+uvx --from git+https://github.com/William-Blackie/chromeappcap.git chromeappcap https://example.com
+```
+
+### local dev
+
+```bash
+git clone https://github.com/William-Blackie/chromeappcap.git
+cd chromeappcap
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+playwright install chromium
+```
+
+Or:
+
+```bash
+make dev-install
+make playwright-install
+```
+
+## Quick Start
+
+```bash
+chromeappcap https://example.com
+```
+
+By default, output is saved in your current shell directory.
+
+## Common Commands
+
+Native app-window capture (macOS):
+
+```bash
+chromeappcap https://example.com --capture-mode app -o native.png
+```
+
+High-quality compressed WebP:
+
+```bash
+chromeappcap https://example.com --capture-mode app --device-scale 2.5 --format webp --compress --quality 85 -o shot.webp
+```
+
+Cross-platform page fallback with no synthetic frame:
+
+```bash
+chromeappcap https://example.com --capture-mode page --no-frame -o raw.png
+```
+
+## Notes
+
+- `--capture-mode auto` prefers app mode on macOS and falls back to page mode.
+- `--capture-mode page` requires Playwright Chromium:
+
+```bash
+playwright install chromium
+```
+
+- macOS app mode requires Screen Recording permission:
+  - `System Settings > Privacy & Security > Screen Recording`
+
+## Help
+
+```bash
+chromeappcap --help
+```

chromeappcap-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chromeappcap"
+version = "0.1.0"
+description = "CLI for polished website screenshots"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "William Blackie" }]
+keywords = ["cli", "screenshot", "chrome", "playwright", "automation"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: OS Independent",
+  "Environment :: Console",
+  "Topic :: Multimedia :: Graphics :: Capture :: Screen Capture",
+]
+dependencies = [
+  "typer>=0.12,<1.0",
+  "playwright>=1.44,<2.0",
+  "Pillow>=10.0,<12.0",
+  "pyobjc-framework-Quartz>=11.0,<12.0; sys_platform == 'darwin'",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0,<9.0",
+]
+
+[project.scripts]
+chromeappcap = "chromeappcap.cli:run"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]

chromeappcap-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chromeappcap-0.1.0/src/chromeappcap/__init__.py

@@ -0,0 +1,4 @@
+"""chromeappcap package."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

chromeappcap-0.1.0/src/chromeappcap/cli.py

@@ -0,0 +1,730 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import io
+import os
+import re
+import signal
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+import typer
+from PIL import Image, ImageDraw, ImageFilter
+from playwright.async_api import Error as PlaywrightError
+from playwright.async_api import async_playwright
+
+from . import __version__
+
+APP_NAME = "chromeappcap"
+SUPPORTED_FORMATS = {"png", "jpeg", "jpg", "webp"}
+SUPPORTED_CAPTURE_MODES = {"auto", "app", "page"}
+HTTP_SCHEMES = {"http", "https"}
+DEFAULT_CHROME_BINARY_MAC = Path("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome")
+
+
+def warn(message: str) -> None:
+    typer.echo(message, err=True)
+
+
+def normalize_url(raw_url: str) -> str:
+    value = raw_url.strip()
+    parsed = urlparse(value)
+
+    if not parsed.scheme:
+        value = f"https://{value}"
+        parsed = urlparse(value)
+
+    if parsed.scheme not in HTTP_SCHEMES:
+        raise typer.BadParameter("URL must start with http:// or https://")
+    if not parsed.netloc:
+        raise typer.BadParameter("URL is missing a hostname")
+
+    return value
+
+
+def normalize_output_format(input_format: Optional[str], output_path: Path) -> str:
+    if input_format:
+        output_format = input_format.strip().lower()
+        if output_format not in SUPPORTED_FORMATS:
+            allowed = ", ".join(sorted(SUPPORTED_FORMATS))
+            raise typer.BadParameter(f"Invalid --format. Use one of: {allowed}")
+        return "jpeg" if output_format == "jpg" else output_format
+
+    suffix = output_path.suffix.lower().lstrip(".")
+    if suffix in SUPPORTED_FORMATS:
+        return "jpeg" if suffix == "jpg" else suffix
+    return "png"
+
+
+def normalize_capture_mode(mode: str) -> str:
+    value = mode.strip().lower()
+    if value not in SUPPORTED_CAPTURE_MODES:
+        allowed = ", ".join(sorted(SUPPORTED_CAPTURE_MODES))
+        raise typer.BadParameter(f"Invalid --capture-mode. Use one of: {allowed}")
+    return value
+
+
+def ensure_output_extension(path: Path, output_format: str) -> Path:
+    wanted_suffix = ".jpg" if output_format == "jpeg" else f".{output_format}"
+
+    if path.suffix.lower() == wanted_suffix:
+        return path
+    if path.suffix:
+        return path.with_suffix(wanted_suffix)
+    return path.parent / f"{path.name}{wanted_suffix}"
+
+
+def default_output_path(url: str) -> Path:
+    parsed = urlparse(url)
+    hostname = parsed.netloc or "capture"
+    safe_name = re.sub(r"[^a-zA-Z0-9._-]+", "-", hostname).strip("-") or "capture"
+    return Path.cwd() / f"{safe_name}.png"
+
+
+def resolve_output_path(path: Path) -> Path:
+    expanded = path.expanduser()
+    if expanded.is_absolute():
+        return expanded
+    return Path.cwd() / expanded
+
+
+def resolve_capture_order(mode: str) -> list[str]:
+    if mode == "auto":
+        return ["app", "page"] if sys.platform == "darwin" else ["page"]
+    return [mode]
+
+
+def resolve_chrome_binary(custom_path: Optional[Path]) -> Path:
+    if custom_path is not None:
+        candidate = custom_path.expanduser().resolve()
+        if not candidate.exists():
+            raise RuntimeError(f"Chrome binary not found: {candidate}")
+        return candidate
+
+    if DEFAULT_CHROME_BINARY_MAC.exists():
+        return DEFAULT_CHROME_BINARY_MAC
+
+    raise RuntimeError(
+        "Chrome binary not found. Install Google Chrome or pass --chrome-binary /path/to/Google Chrome"
+    )
+
+
+async def capture_page_png(
+    url: str,
+    width: int,
+    height: int,
+    timeout_ms: int,
+    settle_ms: int,
+    full_page: bool,
+    browser_channel: str,
+    headed: bool,
+    device_scale: float,
+) -> bytes:
+    async with async_playwright() as playwright:
+        browser = None
+        try:
+            browser = await playwright.chromium.launch(
+                channel=browser_channel,
+                headless=not headed,
+            )
+        except PlaywrightError:
+            if browser_channel != "chrome":
+                raise
+            warn("Warning: channel='chrome' unavailable, falling back to bundled Chromium.")
+            browser = await playwright.chromium.launch(headless=not headed)
+
+        try:
+            context = await browser.new_context(
+                viewport={"width": width, "height": height},
+                device_scale_factor=device_scale,
+            )
+            try:
+                page = await context.new_page()
+                await page.goto(url, wait_until="networkidle", timeout=timeout_ms)
+                if settle_ms > 0:
+                    await page.wait_for_timeout(settle_ms)
+                return await page.screenshot(type="png", full_page=full_page)
+            finally:
+                await context.close()
+        finally:
+            await browser.close()
+
+
+def macos_visible_chrome_windows(quartz_module: object) -> list[dict[str, int]]:
+    windows = quartz_module.CGWindowListCopyWindowInfo(
+        quartz_module.kCGWindowListOptionOnScreenOnly,
+        quartz_module.kCGNullWindowID,
+    )
+    if windows is None:
+        return []
+
+    owner_names = {"Google Chrome", "Chromium"}
+    visible_windows: list[dict[str, int]] = []
+
+    for window in windows:
+        owner_name = str(window.get(quartz_module.kCGWindowOwnerName, ""))
+        if owner_name not in owner_names:
+            continue
+
+        layer = int(window.get(quartz_module.kCGWindowLayer, 1))
+        if layer != 0:
+            continue
+
+        bounds = window.get(quartz_module.kCGWindowBounds, {}) or {}
+        width = int(bounds.get("Width", 0))
+        height = int(bounds.get("Height", 0))
+        window_id = int(window.get(quartz_module.kCGWindowNumber, 0))
+        owner_pid = int(window.get(quartz_module.kCGWindowOwnerPID, 0))
+
+        if window_id <= 0 or width < 160 or height < 140:
+            continue
+
+        visible_windows.append(
+            {
+                "id": window_id,
+                "width": width,
+                "height": height,
+                "owner_pid": owner_pid,
+            }
+        )
+
+    return visible_windows
+
+
+def rank_app_window_ids(
+    windows: list[dict[str, int]],
+    baseline_ids: set[int],
+    target_width: int,
+    target_height: int,
+    owner_pid: Optional[int] = None,
+) -> list[int]:
+    if not windows:
+        return []
+
+    def score(window: dict[str, int]) -> int:
+        return abs(window["width"] - target_width) + abs(window["height"] - target_height)
+
+    if owner_pid is not None:
+        owned = [window for window in windows if window.get("owner_pid") == owner_pid]
+        if owned:
+            return [window["id"] for window in sorted(owned, key=score)]
+
+    new_windows = [window for window in windows if window["id"] not in baseline_ids]
+    if new_windows:
+        return [window["id"] for window in sorted(new_windows, key=score)]
+
+    if baseline_ids:
+        return []
+
+    return [window["id"] for window in sorted(windows, key=score)]
+
+
+def ensure_macos_screen_recording_access(quartz_module: object) -> None:
+    checker = getattr(quartz_module, "CGPreflightScreenCaptureAccess", None)
+    if checker is None:
+        return
+
+    try:
+        granted = bool(checker())
+    except Exception:
+        return
+
+    if not granted:
+        raise RuntimeError(
+            "Screen Recording permission is not granted for this app/terminal. "
+            "Enable it in System Settings > Privacy & Security > Screen Recording, then retry."
+        )
+
+
+def try_screencapture_window(
+    window_id: int,
+    destination: Path,
+    command_timeout_seconds: float = 4.0,
+) -> Optional[str]:
+    try:
+        result = subprocess.run(
+            ["screencapture", "-x", "-o", "-l", str(window_id), str(destination)],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=command_timeout_seconds,
+        )
+    except subprocess.TimeoutExpired:
+        return "timed out waiting for screencapture"
+
+    if result.returncode != 0:
+        return (result.stderr or result.stdout or "unknown error").strip()
+    if not destination.exists() or destination.stat().st_size == 0:
+        return "empty screenshot"
+
+    return None
+
+
+def capture_app_window_png_mac(
+    url: str,
+    width: int,
+    height: int,
+    timeout_seconds: float,
+    settle_seconds: float,
+    chrome_binary: Optional[Path],
+    device_scale: float,
+) -> bytes:
+    if sys.platform != "darwin":
+        raise RuntimeError("--capture-mode app is currently supported on macOS only")
+
+    try:
+        import Quartz  # type: ignore
+    except ImportError as exc:
+        raise RuntimeError("Missing dependency for app mode: install `pyobjc-framework-Quartz`") from exc
+
+    ensure_macos_screen_recording_access(Quartz)
+
+    binary = resolve_chrome_binary(chrome_binary)
+    baseline_windows = macos_visible_chrome_windows(Quartz)
+    baseline_ids = {window["id"] for window in baseline_windows}
+
+    process: Optional[subprocess.Popen[bytes]] = None
+    with tempfile.NamedTemporaryFile(prefix=f"{APP_NAME}-", suffix=".png", delete=False) as handle:
+        temp_png = Path(handle.name)
+
+    with tempfile.TemporaryDirectory(prefix=f"{APP_NAME}-profile-") as profile_dir:
+        command = [
+            str(binary),
+            f"--app={url}",
+            "--new-window",
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--disable-session-crashed-bubble",
+            "--disable-features=Translate",
+            "--user-data-dir=" + profile_dir,
+            f"--window-size={width},{height}",
+            "--window-position=80,80",
+            f"--force-device-scale-factor={device_scale}",
+        ]
+
+        try:
+            warn("Launching Chrome app window...")
+            process = subprocess.Popen(
+                command,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                start_new_session=True,
+            )
+
+            deadline = time.time() + timeout_seconds
+            last_error: Optional[str] = None
+            settle_applied = False
+
+            while time.time() < deadline:
+                windows = macos_visible_chrome_windows(Quartz)
+                ranked_ids = rank_app_window_ids(
+                    windows,
+                    baseline_ids=baseline_ids,
+                    target_width=width,
+                    target_height=height,
+                    owner_pid=process.pid if process else None,
+                )
+
+                if not ranked_ids:
+                    time.sleep(0.1)
+                    continue
+
+                if settle_seconds > 0 and not settle_applied:
+                    time.sleep(settle_seconds)
+                    settle_applied = True
+
+                for window_id in ranked_ids:
+                    last_error = try_screencapture_window(window_id, temp_png)
+                    if last_error is None:
+                        return temp_png.read_bytes()
+
+                    lower_error = last_error.lower()
+                    if "timed out" in lower_error or "not permitted" in lower_error:
+                        raise RuntimeError(
+                            "Window capture is blocked or stalled. "
+                            f"screencapture error: {last_error}. "
+                            "Check Screen Recording permission and retry."
+                        )
+
+                time.sleep(0.15)
+
+            if last_error is None:
+                raise RuntimeError("Could not find the Chrome app window in time")
+
+            raise RuntimeError(
+                "Could not capture the Chrome app window. "
+                f"Last screencapture error: {last_error}. "
+                "Make sure Screen Recording permission is enabled for your terminal/Codex app."
+            )
+        finally:
+            with contextlib.suppress(Exception):
+                if temp_png.exists():
+                    temp_png.unlink()
+
+            if process is not None and process.poll() is None:
+                with contextlib.suppress(Exception):
+                    os.killpg(process.pid, signal.SIGTERM)
+                    process.wait(timeout=3)
+
+                if process.poll() is None:
+                    with contextlib.suppress(Exception):
+                        os.killpg(process.pid, signal.SIGKILL)
+
+
+def render_synthetic_chrome_frame(image: Image.Image, url: str, radius: int) -> Image.Image:
+    page_rgba = image.convert("RGBA")
+    page_width, page_height = page_rgba.size
+
+    top_bar_height = 46
+    window_height = top_bar_height + page_height
+
+    window = Image.new("RGBA", (page_width, window_height), (255, 255, 255, 255))
+    draw = ImageDraw.Draw(window)
+
+    draw.rectangle((0, 0, page_width, top_bar_height), fill=(244, 245, 247, 255))
+    draw.line(
+        (0, top_bar_height - 1, page_width, top_bar_height - 1),
+        fill=(216, 218, 221, 255),
+        width=1,
+    )
+
+    dot_y = top_bar_height // 2
+    dot_radius = 6
+    dot_x = 18
+    for color in ((255, 95, 86, 255), (255, 189, 46, 255), (39, 201, 63, 255)):
+        draw.ellipse(
+            (
+                dot_x - dot_radius,
+                dot_y - dot_radius,
+                dot_x + dot_radius,
+                dot_y + dot_radius,
+            ),
+            fill=color,
+        )
+        dot_x += 18
+
+    address_left = 110
+    address_right = page_width - 18
+    if address_right > address_left + 40:
+        bar_height = 26
+        bar_top = (top_bar_height - bar_height) // 2
+        draw.rounded_rectangle(
+            (address_left, bar_top, address_right, bar_top + bar_height),
+            radius=bar_height // 2,
+            fill=(231, 234, 238, 255),
+        )
+        address_text = f"{url[:90]}..." if len(url) > 90 else url
+        draw.text((address_left + 12, bar_top + 7), address_text, fill=(84, 88, 92, 255))
+
+    window.paste(page_rgba, (0, top_bar_height))
+
+    safe_radius = max(radius, 0)
+    mask = Image.new("L", window.size, 0)
+    mask_draw = ImageDraw.Draw(mask)
+    mask_draw.rounded_rectangle(
+        (0, 0, page_width - 1, window_height - 1),
+        radius=safe_radius,
+        fill=255,
+    )
+
+    rounded = Image.new("RGBA", window.size, (0, 0, 0, 0))
+    rounded.paste(window, (0, 0), mask)
+
+    border = Image.new("RGBA", window.size, (0, 0, 0, 0))
+    border_draw = ImageDraw.Draw(border)
+    border_draw.rounded_rectangle(
+        (0, 0, page_width - 1, window_height - 1),
+        radius=safe_radius,
+        outline=(45, 48, 52, 70),
+        width=1,
+    )
+    rounded = Image.alpha_composite(rounded, border)
+
+    shadow = Image.new("RGBA", window.size, (0, 0, 0, 0))
+    shadow_draw = ImageDraw.Draw(shadow)
+    shadow_draw.rounded_rectangle(
+        (0, 0, page_width - 1, window_height - 1),
+        radius=safe_radius,
+        fill=(0, 0, 0, 95),
+    )
+    shadow = shadow.filter(ImageFilter.GaussianBlur(14))
+
+    padding = 28
+    framed = Image.new(
+        "RGBA",
+        (page_width + padding * 2, window_height + padding * 2),
+        (0, 0, 0, 0),
+    )
+    framed.paste(shadow, (padding, padding + 6), shadow)
+    framed.paste(rounded, (padding, padding), rounded)
+    return framed
+
+
+def maybe_scale_image(image: Image.Image, scale: float) -> Image.Image:
+    if scale == 1.0:
+        return image
+
+    target_width = max(1, int(image.width * scale))
+    target_height = max(1, int(image.height * scale))
+    return image.resize((target_width, target_height), Image.Resampling.LANCZOS)
+
+
+def save_image(
+    image: Image.Image,
+    output_path: Path,
+    output_format: str,
+    compress: bool,
+    quality: Optional[int],
+) -> None:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if output_format == "png":
+        image.save(
+            output_path,
+            format="PNG",
+            optimize=compress,
+            compress_level=9 if compress else 6,
+        )
+        return
+
+    if output_format == "jpeg":
+        rgb = Image.new("RGB", image.size, (255, 255, 255))
+        alpha = image.getchannel("A") if "A" in image.getbands() else None
+        rgb.paste(image.convert("RGB"), mask=alpha)
+        rgb.save(
+            output_path,
+            format="JPEG",
+            quality=quality if quality is not None else (82 if compress else 92),
+            optimize=compress,
+            progressive=compress,
+        )
+        return
+
+    image.save(
+        output_path,
+        format="WEBP",
+        quality=quality if quality is not None else (80 if compress else 92),
+        method=6 if compress else 4,
+    )
+
+
+def run_capture(
+    url: str,
+    output: Optional[Path],
+    output_format: Optional[str],
+    width: int,
+    height: int,
+    full_page: bool,
+    timeout: float,
+    settle: float,
+    browser_channel: str,
+    headed: bool,
+    frame: bool,
+    corner_radius: int,
+    compress: bool,
+    quality: Optional[int],
+    scale: float,
+    capture_mode: str,
+    chrome_binary: Optional[Path],
+    device_scale: float,
+) -> None:
+    normalized_url = normalize_url(url)
+
+    output_path = output if output is not None else default_output_path(normalized_url)
+    output_path = resolve_output_path(output_path)
+    normalized_format = normalize_output_format(output_format, output_path)
+    destination = ensure_output_extension(output_path, normalized_format)
+
+    if normalized_format == "png" and quality is not None:
+        raise typer.BadParameter("--quality only applies to jpeg/webp output")
+
+    normalized_mode = normalize_capture_mode(capture_mode)
+    capture_order = resolve_capture_order(normalized_mode)
+
+    screenshot_bytes: Optional[bytes] = None
+    used_mode: Optional[str] = None
+    last_error: Optional[Exception] = None
+
+    for mode in capture_order:
+        try:
+            if mode == "app":
+                warn("Capture mode: native Chrome app window")
+                if full_page:
+                    warn("Warning: --full-page is ignored in app mode (window capture is viewport-only).")
+
+                screenshot_bytes = capture_app_window_png_mac(
+                    normalized_url,
+                    width=width,
+                    height=height,
+                    timeout_seconds=timeout,
+                    settle_seconds=settle,
+                    chrome_binary=chrome_binary,
+                    device_scale=device_scale,
+                )
+                used_mode = "app"
+            else:
+                warn("Capture mode: Playwright page screenshot")
+                screenshot_bytes = asyncio.run(
+                    capture_page_png(
+                        normalized_url,
+                        width=width,
+                        height=height,
+                        timeout_ms=int(timeout * 1000),
+                        settle_ms=int(settle * 1000),
+                        full_page=full_page,
+                        browser_channel=browser_channel,
+                        headed=headed,
+                        device_scale=device_scale,
+                    )
+                )
+                used_mode = "page"
+
+            break
+        except (RuntimeError, PlaywrightError, subprocess.SubprocessError, FileNotFoundError) as exc:
+            last_error = exc
+            if normalized_mode == "auto" and mode == "app":
+                warn(f"Warning: app capture failed ({exc}). Falling back to page mode.")
+                continue
+
+            warn(f"Capture failed in {mode} mode: {exc}")
+            raise typer.Exit(code=1) from exc
+
+    if screenshot_bytes is None or used_mode is None:
+        warn(f"Capture failed: {last_error}")
+        raise typer.Exit(code=1)
+
+    with Image.open(io.BytesIO(screenshot_bytes)) as opened:
+        screenshot = opened.convert("RGBA")
+
+    apply_synthetic_frame = frame and used_mode != "app"
+    if frame and used_mode == "app":
+        warn("Note: --frame is ignored in app mode because the native Chrome window is already captured.")
+
+    final_image = screenshot
+    if apply_synthetic_frame:
+        final_image = render_synthetic_chrome_frame(final_image, normalized_url, corner_radius)
+
+    final_image = maybe_scale_image(final_image, scale)
+    save_image(
+        final_image,
+        output_path=destination,
+        output_format=normalized_format,
+        compress=compress,
+        quality=quality,
+    )
+
+    size_kb = destination.stat().st_size / 1024
+    typer.echo(f"Saved {destination} ({size_kb:.1f} KB) [mode={used_mode}]")
+
+
+def main(
+    ctx: typer.Context,
+    url: Optional[str] = typer.Argument(
+        None,
+        help="URL to capture. Example: https://example.com",
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output file path (default: <cwd>/hostname.png)",
+    ),
+    output_format: Optional[str] = typer.Option(
+        None,
+        "--format",
+        "-f",
+        help="Output format: png, jpeg/jpg, webp",
+    ),
+    width: int = typer.Option(1440, min=320, max=6000, help="Capture window/page width"),
+    height: int = typer.Option(900, min=240, max=6000, help="Capture window/page height"),
+    full_page: bool = typer.Option(False, help="Capture full scroll height (page mode only)"),
+    timeout: float = typer.Option(30.0, min=1.0, help="Capture timeout in seconds"),
+    settle: float = typer.Option(0.8, min=0.0, help="Extra settle wait in seconds"),
+    capture_mode: str = typer.Option(
+        "auto",
+        help="Capture mode: auto (prefer app on macOS), app (native Chrome app window), or page",
+    ),
+    chrome_binary: Optional[Path] = typer.Option(None, help="Path to Chrome binary for app mode"),
+    browser_channel: str = typer.Option(
+        "chrome",
+        help="Playwright browser channel (used in page mode)",
+    ),
+    headed: bool = typer.Option(False, help="Open visible browser window in page mode"),
+    device_scale: float = typer.Option(
+        2.0,
+        min=1.0,
+        max=4.0,
+        help="Device scale factor for higher pixel density",
+    ),
+    frame: bool = typer.Option(
+        True,
+        "--frame/--no-frame",
+        help="Enable/disable synthetic Chrome frame (page mode only)",
+    ),
+    corner_radius: int = typer.Option(
+        20,
+        min=0,
+        max=200,
+        help="Rounded corner radius for synthetic frame",
+    ),
+    compress: bool = typer.Option(
+        False,
+        "--compress/--no-compress",
+        help="Enable stronger size compression",
+    ),
+    quality: Optional[int] = typer.Option(
+        None,
+        min=1,
+        max=100,
+        help="Quality for jpeg/webp output",
+    ),
+    scale: float = typer.Option(
+        1.0,
+        min=0.1,
+        max=1.0,
+        help="Downscale output for smaller files (0.1 - 1.0)",
+    ),
+    version: bool = typer.Option(False, "--version", help="Show version and exit"),
+) -> None:
+    if version:
+        typer.echo(__version__)
+        raise typer.Exit(code=0)
+
+    if url is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit(code=0)
+
+    run_capture(
+        url=url,
+        output=output,
+        output_format=output_format,
+        width=width,
+        height=height,
+        full_page=full_page,
+        timeout=timeout,
+        settle=settle,
+        browser_channel=browser_channel,
+        headed=headed,
+        frame=frame,
+        corner_radius=corner_radius,
+        compress=compress,
+        quality=quality,
+        scale=scale,
+        capture_mode=capture_mode,
+        chrome_binary=chrome_binary,
+        device_scale=device_scale,
+    )
+
+
+def run() -> None:
+    typer.run(main)
+
+
+if __name__ == "__main__":
+    run()

chromeappcap-0.1.0/src/chromeappcap.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: chromeappcap
+Version: 0.1.0
+Summary: CLI for polished website screenshots
+Author: William Blackie
+Keywords: cli,screenshot,chrome,playwright,automation
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer<1.0,>=0.12
+Requires-Dist: playwright<2.0,>=1.44
+Requires-Dist: Pillow<12.0,>=10.0
+Requires-Dist: pyobjc-framework-Quartz<12.0,>=11.0; sys_platform == "darwin"
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+
+# chromeappcap
+
+Screenshots that look like you meant to share them.
+
+`chromeappcap` is a CLI for polished website/app screenshots with native Chrome app-window capture on macOS and Playwright fallback everywhere else.
+
+## Install
+
+### `pipx` (recommended)
+
+```bash
+pipx install chromeappcap
+```
+
+### `uvx` (zero install)
+
+```bash
+uvx --from git+https://github.com/William-Blackie/chromeappcap.git chromeappcap https://example.com
+```
+
+### local dev
+
+```bash
+git clone https://github.com/William-Blackie/chromeappcap.git
+cd chromeappcap
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+playwright install chromium
+```
+
+Or:
+
+```bash
+make dev-install
+make playwright-install
+```
+
+## Quick Start
+
+```bash
+chromeappcap https://example.com
+```
+
+By default, output is saved in your current shell directory.
+
+## Common Commands
+
+Native app-window capture (macOS):
+
+```bash
+chromeappcap https://example.com --capture-mode app -o native.png
+```
+
+High-quality compressed WebP:
+
+```bash
+chromeappcap https://example.com --capture-mode app --device-scale 2.5 --format webp --compress --quality 85 -o shot.webp
+```
+
+Cross-platform page fallback with no synthetic frame:
+
+```bash
+chromeappcap https://example.com --capture-mode page --no-frame -o raw.png
+```
+
+## Notes
+
+- `--capture-mode auto` prefers app mode on macOS and falls back to page mode.
+- `--capture-mode page` requires Playwright Chromium:
+
+```bash
+playwright install chromium
+```
+
+- macOS app mode requires Screen Recording permission:
+  - `System Settings > Privacy & Security > Screen Recording`
+
+## Help
+
+```bash
+chromeappcap --help
+```

chromeappcap-0.1.0/src/chromeappcap.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/chromeappcap/__init__.py
+src/chromeappcap/cli.py
+src/chromeappcap.egg-info/PKG-INFO
+src/chromeappcap.egg-info/SOURCES.txt
+src/chromeappcap.egg-info/dependency_links.txt
+src/chromeappcap.egg-info/entry_points.txt
+src/chromeappcap.egg-info/requires.txt
+src/chromeappcap.egg-info/top_level.txt
+tests/test_cli_utils.py
+tests/test_output_paths.py

chromeappcap-0.1.0/src/chromeappcap.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

chromeappcap-0.1.0/src/chromeappcap.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chromeappcap = chromeappcap.cli:run

chromeappcap-0.1.0/src/chromeappcap.egg-info/requires.txt

@@ -0,0 +1,9 @@
+typer<1.0,>=0.12
+playwright<2.0,>=1.44
+Pillow<12.0,>=10.0
+
+[:sys_platform == "darwin"]
+pyobjc-framework-Quartz<12.0,>=11.0
+
+[dev]
+pytest<9.0,>=8.0

chromeappcap-0.1.0/src/chromeappcap.egg-info/top_level.txt

@@ -0,0 +1 @@
+chromeappcap

chromeappcap-0.1.0/tests/test_cli_utils.py

@@ -0,0 +1,40 @@
+from pathlib import Path
+
+import pytest
+import typer
+
+from chromeappcap.cli import (
+    normalize_capture_mode,
+    normalize_output_format,
+    normalize_url,
+    resolve_capture_order,
+)
+
+
+def test_normalize_url_adds_https_when_missing_scheme() -> None:
+    assert normalize_url("example.com") == "https://example.com"
+
+
+def test_normalize_url_rejects_invalid_scheme() -> None:
+    with pytest.raises(typer.BadParameter):
+        normalize_url("ftp://example.com")
+
+
+def test_normalize_output_format_from_flag_and_suffix() -> None:
+    assert normalize_output_format("jpg", Path("shot.any")) == "jpeg"
+    assert normalize_output_format(None, Path("shot.webp")) == "webp"
+    assert normalize_output_format(None, Path("shot")) == "png"
+
+
+def test_normalize_capture_mode_validation() -> None:
+    assert normalize_capture_mode("AUTO") == "auto"
+    with pytest.raises(typer.BadParameter):
+        normalize_capture_mode("banana")
+
+
+def test_resolve_capture_order_page_mode() -> None:
+    assert resolve_capture_order("page") == ["page"]
+
+
+def test_resolve_capture_order_app_mode() -> None:
+    assert resolve_capture_order("app") == ["app"]

chromeappcap-0.1.0/tests/test_output_paths.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+
+from chromeappcap.cli import default_output_path, resolve_output_path
+
+
+def test_default_output_path_uses_invocation_directory(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    output = default_output_path("https://example.com")
+    assert output == tmp_path / "example.com.png"
+
+
+def test_resolve_output_path_makes_relative_paths_cwd_absolute(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    output = resolve_output_path(Path("shots/homepage"))
+    assert output == tmp_path / "shots/homepage"
+
+
+def test_resolve_output_path_keeps_absolute_path(tmp_path):
+    absolute = tmp_path / "x.png"
+    output = resolve_output_path(absolute)
+    assert output == absolute