enginehall 2.0.0__py3-none-any.whl

pcba/adapters/altium_vcs.py

@@ -0,0 +1,197 @@
+"""Altium 365 working copies, read with git (Class C helper of the Altium drive; no Altium needed).
+
+An Altium 365 project lives in a git working copy whose remote is the workspace's server. Altium
+commits and pushes it with its own credentials when a person chooses Save to Server; nothing
+here pushes. What this module does is the part that kept costing time:
+
+- tell which changed files carry a change and which Altium only re-saved: exporting, binding an
+  OutJob or opening a project rewrites schematics, libraries, OutJobs and BOM documents byte for
+  byte, and every save to the server then needed those unticked or restored by hand;
+- list project entries outside the project folder or missing on disk (a probe document once
+  ended up in a real project; Altium 365 warns about external files);
+- restore files Altium only re-saved (`git checkout`), once the project is closed.
+
+Schematics are compared record by record with the engine's own parser; text formats (project,
+OutJob, BOM document) line by line with line endings and trailing blanks ignored. Other binary
+documents (PCB, libraries, drawings) cannot be compared here and are reported as `binary`.
+"""
+
+from __future__ import annotations
+
+import configparser
+import os
+import re
+import subprocess
+import tempfile
+from pathlib import Path
+
+TEXT_SUFFIXES = {".prjpcb", ".outjob", ".bomdoc", ".dsnwrk", ".prjpcbstructure", ".txt", ".csv"}
+RECORD_SUFFIXES = {".schdoc"}
+ALTIUM_365_HOST = re.compile(r"(^|\.)365\.altium\.com$", re.I)
+
+
+class VcsError(RuntimeError):
+    """The folder is not a git working copy, or git failed."""
+
+
+def _git(folder: Path, *args: str, binary: bool = False):
+    try:
+        done = subprocess.run(["git", "-C", str(folder), *args], capture_output=True, check=False)
+    except FileNotFoundError as exc:  # pragma: no cover - git missing
+        raise VcsError("git is not installed") from exc
+    if done.returncode != 0:
+        raise VcsError(f"git {' '.join(args[:2])} failed: {done.stderr.decode('utf-8', 'replace').strip()[:300]}")
+    return done.stdout if binary else done.stdout.decode("utf-8", "replace")
+
+
+def _host(url: str) -> str:
+    """The remote's host only: never a user name or token that a URL may carry."""
+    match = re.match(r"^[a-z]+://(?:[^@/]*@)?([^/:]+)", url.strip(), re.I)
+    return match.group(1) if match else ""
+
+
+def working_copy(project: str | Path) -> dict:
+    """Branch, remote host, whether it is an Altium 365 working copy, ahead/behind, and whether
+    it sits inside another git working copy (Altium then warns on every save)."""
+    folder = Path(project).parent
+    if not (folder / ".git").exists():
+        raise VcsError(f"{folder} is not a git working copy (an Altium 365 project has one)")
+    head = _git(folder, "status", "--porcelain=v1", "-b").splitlines()[0]
+    match = re.match(r"## (\S+?)(?:\.\.\.(\S+))?(?: \[(.*)\])?$", head)
+    branch, upstream, counts = (match.group(1), match.group(2), match.group(3) or "") if match else ("?", None, "")
+    ahead = int(re.search(r"ahead (\d+)", counts).group(1)) if "ahead" in counts else 0
+    behind = int(re.search(r"behind (\d+)", counts).group(1)) if "behind" in counts else 0
+    try:
+        host = _host(_git(folder, "remote", "get-url", "origin"))
+    except VcsError:
+        host = ""
+    parent = folder.parent
+    nested = False
+    while parent != parent.parent:
+        if (parent / ".git").exists():
+            nested = True
+            break
+        parent = parent.parent
+    return {"folder": str(folder), "branch": branch, "upstream": upstream, "ahead": ahead, "behind": behind,
+            "remote_host": host, "altium_365": bool(ALTIUM_365_HOST.search(host)), "nested_in_repository": nested}
+
+
+def _normalise_text(data: bytes) -> list[str]:
+    text = data.decode("latin-1")
+    return [line.rstrip() for line in text.replace("\r\n", "\n").replace("\r", "\n").split("\n")]
+
+
+# Fields Altium rewrites on every save of an unchanged sheet. Measured on Altium Designer Develop
+# 26.10: a re-saved schematic differed only in the UniqueID of its parameter records (RECORD=41),
+# 104 of 640 records; part identities (RECORD=1) and everything else stayed.
+VOLATILE = {"41": {"UniqueID"}}
+
+
+def _records(data: bytes, suffix: str):
+    from pcba.parsers.altium.records import load_any_records
+
+    with tempfile.TemporaryDirectory() as tmp:
+        path = Path(tmp) / f"doc{suffix}"
+        path.write_bytes(data)
+        records = load_any_records(path)
+    return [{k: v for k, v in r.items() if k not in VOLATILE.get(r.get("RECORD", ""), ())} for r in records]
+
+
+def classify(folder: Path, path: str) -> str:
+    """`content` (a real change), `resave` (Altium rewrote the same content), `binary` (cannot be
+    compared here), `new`, or `deleted`."""
+    target = folder / path
+    if not target.exists():
+        return "deleted"
+    try:
+        old = _git(folder, "show", f"HEAD:{path}", binary=True)
+    except VcsError:
+        return "new"
+    new = target.read_bytes()
+    if old == new:
+        return "resave"
+    suffix = target.suffix.lower()
+    if suffix in TEXT_SUFFIXES:
+        return "resave" if _normalise_text(old) == _normalise_text(new) else "content"
+    if suffix in RECORD_SUFFIXES:
+        try:
+            return "resave" if _records(old, suffix) == _records(new, suffix) else "content"
+        except Exception:  # noqa: BLE001 - an unreadable document is reported, not guessed
+            return "binary"
+    return "binary"
+
+
+def changes(project: str | Path) -> list[dict]:
+    """Every changed tracked file of the working copy, classified. Untracked files are listed as
+    `untracked` (Altium's outputs and reports land next to the project)."""
+    folder = Path(project).parent
+    out = []
+    entries = iter(_git(folder, "status", "--porcelain=v1", "-z", "--untracked-files=all").split("\0"))
+    for line in entries:
+        if len(line) < 4:
+            continue
+        code, path = line[:2], line[3:]
+        if code[0] in "RC":
+            next(entries, None)  # a rename or copy is followed by its source path
+        if code == "??":
+            out.append({"path": path, "status": "untracked"})
+        else:
+            out.append({"path": path, "status": classify(folder, path), "git": code.strip()})
+    return out
+
+
+def project_entries(project: str | Path) -> list[dict]:
+    """The documents a `.PrjPcb` lists, each resolved against the project folder: whether the file
+    exists and whether it lies inside the folder."""
+    project = Path(project)
+    parser = configparser.ConfigParser(interpolation=None, strict=False)
+    data = project.read_bytes()
+    try:
+        text = data.decode("utf-8-sig")   # Altium writes the project with a byte-order mark
+    except UnicodeDecodeError:
+        text = data.decode("latin-1")
+    parser.read_string(text)
+    folder = project.parent.resolve()
+    out = []
+    for section in parser.sections():
+        if not re.fullmatch(r"(Document|GeneratedDocument)\d+", section):
+            continue
+        rel = parser.get(section, "DocumentPath", fallback="").strip()
+        if not rel:
+            continue
+        resolved = (folder / rel.replace("\\", os.sep)).resolve()
+        out.append({"entry": section, "path": rel, "exists": resolved.exists(),
+                    "inside": resolved == folder or folder in resolved.parents})
+    return out
+
+
+def status(project: str | Path) -> dict:
+    """Working copy, changed files by kind, and project entries that do not belong in a commit."""
+    copy = working_copy(project)
+    changed = changes(project)
+    entries = project_entries(project)
+    by_kind: dict[str, list[str]] = {}
+    for c in changed:
+        by_kind.setdefault(c["status"], []).append(c["path"])
+    problems = {
+        "outside_folder": [e["path"] for e in entries if not e["inside"]],
+        "missing_on_disk": [e["path"] for e in entries if not e["exists"]],
+    }
+    return {**copy, "changes": changed, "by_kind": by_kind,
+            "to_commit": by_kind.get("content", []) + by_kind.get("binary", []) + by_kind.get("new", [])
+            + by_kind.get("deleted", []),
+            "resave_only": by_kind.get("resave", []),
+            **{k: v for k, v in problems.items() if v}}
+
+
+def restore(project: str | Path, files: list[str]) -> list[str]:
+    """`git checkout` of tracked files (Altium must have the project closed: it would save its
+    in-memory copy back). Returns the files restored."""
+    folder = Path(project).parent
+    tracked = set(filter(None, _git(folder, "ls-files", "-z").split("\0")))  # -z: names unquoted
+    unknown = [f for f in files if f not in tracked]
+    if unknown:
+        raise VcsError(f"not tracked in the working copy: {unknown}")
+    if files:
+        _git(folder, "checkout", "--", *files)
+    return list(files)

pcba/adapters/altium_win32.py

@@ -0,0 +1,457 @@
+"""Win32 plumbing for the Altium adapter: processes, windows, dialogs, clicks, screenshots.
+
+Stdlib only (`ctypes`), so the engine keeps its single runtime dependency. Every function here
+is a thin, named wrapper around one Win32 idea; the policy (when to close a dialog, what to
+click) lives in `altium_drive`.
+
+Facts this code depends on, all measured against Altium Designer Develop 26.10:
+
+- Altium's own dialogs are VCL forms (`TMessageForm`, `TChangeManagementForm`, …) whose buttons
+  are `TXPBitBtn` windows. `BM_CLICK` is ignored by them; a posted `WM_LBUTTONDOWN`/`UP` pair at
+  the button's centre works without focus or the mouse.
+- A runtime error in a script raises a standard `#32770` message box whose `Static` text is
+  readable; a parse error raises one and then a `TMessageForm` whose text is painted, not
+  readable — so dialogs are captured as images before they are closed.
+- The main instance is the process that owns the `TDocumentForm` window. After a restart with
+  `-R…` on the command line, the main instance's own command line carries `-R` too, so the
+  command line cannot tell a launcher from the instance.
+- `PrintWindow(PW_RENDERFULLCONTENT)` captures Altium's DirectX views (`SchView`,
+  `View_Graphical`) correctly, including when they are covered by other windows.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import struct
+import time
+import sys
+import zlib
+from dataclasses import dataclass
+from pathlib import Path
+
+if sys.platform == "win32":  # pragma: no cover - exercised only on Windows with Altium
+    import ctypes.wintypes as wt
+
+    user32 = ctypes.WinDLL("user32", use_last_error=True)
+    gdi32 = ctypes.WinDLL("gdi32", use_last_error=True)
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    WNDENUMPROC = ctypes.WINFUNCTYPE(wt.BOOL, wt.HWND, wt.LPARAM)
+
+    def _dpi_aware() -> None:
+        """Per-monitor DPI awareness, or window rectangles come back scaled and a capture
+        holds only part of a high-DPI view."""
+        try:
+            user32.SetProcessDpiAwarenessContext(ctypes.c_void_p(-4))  # PER_MONITOR_AWARE_V2
+        except (AttributeError, OSError):
+            # Older Windows builds lack the call; captures then fall back to system DPI scaling.
+            return
+
+    _dpi_aware()
+
+    class PROCESSENTRY32W(ctypes.Structure):
+        _fields_ = [
+            ("dwSize", wt.DWORD),
+            ("cntUsage", wt.DWORD),
+            ("th32ProcessID", wt.DWORD),
+            ("th32DefaultHeapID", ctypes.c_void_p),
+            ("th32ModuleID", wt.DWORD),
+            ("cntThreads", wt.DWORD),
+            ("th32ParentProcessID", wt.DWORD),
+            ("pcPriClassBase", ctypes.c_long),
+            ("dwFlags", wt.DWORD),
+            ("szExeFile", ctypes.c_wchar * 260),
+        ]
+
+    class BITMAPINFOHEADER(ctypes.Structure):
+        _fields_ = [
+            ("biSize", wt.DWORD),
+            ("biWidth", wt.LONG),
+            ("biHeight", wt.LONG),
+            ("biPlanes", wt.WORD),
+            ("biBitCount", wt.WORD),
+            ("biCompression", wt.DWORD),
+            ("biSizeImage", wt.DWORD),
+            ("biXPelsPerMeter", wt.LONG),
+            ("biYPelsPerMeter", wt.LONG),
+            ("biClrUsed", wt.DWORD),
+            ("biClrImportant", wt.DWORD),
+        ]
+
+
+WM_CLOSE = 0x0010
+WM_LBUTTONDOWN = 0x0201
+WM_LBUTTONUP = 0x0202
+MK_LBUTTON = 0x0001
+SMTO_ABORTIFHUNG = 0x0002
+PW_RENDERFULLCONTENT = 2
+TH32CS_SNAPPROCESS = 0x00000002
+
+DIALOG_CLASSES = ("TMessageForm", "#32770")
+MAIN_WINDOW_CLASS = "TDocumentForm"
+
+
+@dataclass(frozen=True, slots=True)
+class Window:
+    hwnd: int
+    pid: int
+    cls: str
+    title: str
+
+
+def _text(hwnd) -> str:
+    n = user32.GetWindowTextLengthW(hwnd)
+    buf = ctypes.create_unicode_buffer(n + 1)
+    user32.GetWindowTextW(hwnd, buf, n + 1)
+    return buf.value
+
+
+def _class(hwnd) -> str:
+    buf = ctypes.create_unicode_buffer(256)
+    user32.GetClassNameW(hwnd, buf, 256)
+    return buf.value
+
+
+def processes(image: str = "X2.EXE") -> list[int]:
+    """Process ids whose executable name matches `image` (case-insensitive)."""
+    snap = kernel32.CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0)
+    entry = PROCESSENTRY32W()
+    entry.dwSize = ctypes.sizeof(PROCESSENTRY32W)
+    found = []
+    try:
+        ok = kernel32.Process32FirstW(snap, ctypes.byref(entry))
+        while ok:
+            if entry.szExeFile.lower() == image.lower():
+                found.append(int(entry.th32ProcessID))
+            ok = kernel32.Process32NextW(snap, ctypes.byref(entry))
+    finally:
+        kernel32.CloseHandle(snap)
+    return found
+
+
+def top_windows(pids: set[int] | None = None, visible_only: bool = True) -> list[Window]:
+    out: list[Window] = []
+
+    def callback(hwnd, _lparam):
+        if visible_only and not user32.IsWindowVisible(hwnd):
+            return True
+        pid = wt.DWORD()
+        user32.GetWindowThreadProcessId(hwnd, ctypes.byref(pid))
+        if pids is None or pid.value in pids:
+            out.append(Window(int(hwnd), int(pid.value), _class(hwnd), _text(hwnd)))
+        return True
+
+    user32.EnumWindows(WNDENUMPROC(callback), 0)
+    return out
+
+
+def children(hwnd: int) -> list[Window]:
+    out: list[Window] = []
+
+    def callback(child, _lparam):
+        out.append(Window(int(child), 0, _class(child), _text(child)))
+        return True
+
+    user32.EnumChildWindows(hwnd, WNDENUMPROC(callback), 0)
+    return out
+
+
+def is_visible(hwnd: int) -> bool:
+    return bool(user32.IsWindowVisible(hwnd))
+
+
+def main_instances() -> set[int]:
+    """X2 processes that own Altium's main window (not launchers)."""
+    pids = set(processes())
+    return {w.pid for w in top_windows(pids) if w.cls == MAIN_WINDOW_CLASS}
+
+
+def launchers() -> set[int]:
+    """X2 processes that are not the main instance: forwarding launchers, possibly hung."""
+    pids = set(processes())
+    return pids - main_instances()
+
+
+def cpu_seconds(pid: int) -> float:
+    """Kernel plus user CPU time of a process, in seconds (0.0 if it cannot be read)."""
+    PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+    handle = kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
+    if not handle:
+        return 0.0
+    try:
+        times = [ctypes.c_ulonglong() for _ in range(4)]
+        if not kernel32.GetProcessTimes(handle, *(ctypes.byref(t) for t in times)):
+            return 0.0
+        return (times[2].value + times[3].value) / 1e7
+    finally:
+        kernel32.CloseHandle(handle)
+
+
+def kill(pid: int) -> bool:
+    PROCESS_TERMINATE = 0x0001
+    handle = kernel32.OpenProcess(PROCESS_TERMINATE, False, pid)
+    if not handle:
+        return False
+    try:
+        return bool(kernel32.TerminateProcess(handle, 1))
+    finally:
+        kernel32.CloseHandle(handle)
+
+
+def is_enabled(hwnd: int) -> bool:
+    return bool(user32.IsWindowEnabled(hwnd))
+
+
+def dialogs(pids: set[int]) -> list[Window]:
+    """Modal windows of the main instance, whatever toolkit drew them.
+
+    Altium mixes VCL message forms, standard `#32770` boxes and WPF windows (`HwndWrapper[…]`,
+    e.g. "Unsaved Changes"). The reliable signal is that a modal disables the main window, so
+    every other enabled top-level window is then a dialog; the known message-box classes count
+    regardless.
+    """
+    windows = top_windows(pids)
+    blocked = any(w.cls == MAIN_WINDOW_CLASS and not is_enabled(w.hwnd) for w in windows)
+    found = []
+    for w in windows:
+        if w.cls in DIALOG_CLASSES:
+            found.append(w)
+        elif blocked and w.cls not in (MAIN_WINDOW_CLASS, "TApplication") and is_enabled(w.hwnd):
+            found.append(w)
+    return found
+
+
+def dialog_text(hwnd: int) -> str:
+    """Readable text of a standard message box; empty for painted VCL forms."""
+    return "\n".join(c.title for c in children(hwnd) if c.cls == "Static" and c.title)
+
+
+def close(hwnd: int) -> bool:
+    result = wt.DWORD()
+    return bool(
+        user32.SendMessageTimeoutW(hwnd, WM_CLOSE, 0, 0, SMTO_ABORTIFHUNG, 3000, ctypes.byref(result))
+    )
+
+
+def click_button(form: Window, caption: str) -> bool:
+    """Click a button inside `form` by caption, ignoring `&` accelerators."""
+    for child in children(form.hwnd):
+        if child.title.replace("&", "") == caption.replace("&", ""):
+            rect = wt.RECT()
+            user32.GetClientRect(child.hwnd, ctypes.byref(rect))
+            lparam = ((rect.bottom // 2) << 16) | (rect.right // 2)
+            user32.PostMessageW(child.hwnd, WM_LBUTTONDOWN, MK_LBUTTON, lparam)
+            user32.PostMessageW(child.hwnd, WM_LBUTTONUP, 0, lparam)
+            return True
+    return False
+
+
+def _print_window(hwnd: int) -> tuple[int, int, bytes, bool]:
+    """Top-down BGRA pixels of a window rendered with PrintWindow (works while it is covered), and
+    whether PrintWindow said it drew. The only GDI capture code here: `_pixels` and `capture` differ
+    only in what they make of an undrawn window."""
+    rect = wt.RECT()
+    user32.GetWindowRect(hwnd, ctypes.byref(rect))
+    width, height = rect.right - rect.left, rect.bottom - rect.top
+    if width <= 0 or height <= 0:
+        raise OSError("window has no area to capture")
+    hdc = user32.GetWindowDC(hwnd)
+    mdc = gdi32.CreateCompatibleDC(hdc)
+    bmp = gdi32.CreateCompatibleBitmap(hdc, width, height)
+    default = gdi32.SelectObject(mdc, bmp)
+    selected = True
+    try:
+        rendered = bool(user32.PrintWindow(hwnd, mdc, PW_RENDERFULLCONTENT))
+        # GetDIBits needs the bitmap out of every DC, and DeleteObject refuses a selected bitmap
+        # (DeleteDC does not free it either), so the DC gets its default bitmap back first.
+        gdi32.SelectObject(mdc, default)
+        selected = False
+        info = BITMAPINFOHEADER(ctypes.sizeof(BITMAPINFOHEADER), width, -height, 1, 32, 0, 0, 0, 0, 0, 0)
+        buf = ctypes.create_string_buffer(width * height * 4)
+        if gdi32.GetDIBits(mdc, bmp, 0, height, buf, ctypes.byref(info), 0) != height:
+            raise OSError(f"GetDIBits could not read the capture of window {hwnd}")
+    finally:
+        if selected:
+            gdi32.SelectObject(mdc, default)
+        gdi32.DeleteObject(bmp)
+        gdi32.DeleteDC(mdc)
+        user32.ReleaseDC(hwnd, hdc)
+    return width, height, buf.raw, rendered
+
+
+def _pixels(hwnd: int) -> tuple[int, int, bytes]:
+    """BGRA pixels of a window, or OSError when PrintWindow drew nothing: a check box is never
+    read from an empty bitmap."""
+    width, height, raw, rendered = _print_window(hwnd)
+    if not rendered:
+        raise OSError(f"PrintWindow rendered nothing for window {hwnd}")
+    return width, height, raw
+
+
+def checkbox_state(width: int, height: int, bgra: bytes) -> bool | None:
+    """A check box's state from its rendering, or None when the capture shows nothing: a drawn check
+    box always has its square's frame and caption, so a capture of one colour is no reading, and is
+    never taken for "unchecked"."""
+    if len(set(bgra[0::4])) < 2 and len(set(bgra[1::4])) < 2 and len(set(bgra[2::4])) < 2:
+        return None
+    return tick_drawn(width, height, bgra)
+
+
+def tick_drawn(width: int, height: int, bgra: bytes) -> bool:
+    """Whether a check box's square (the left `height` x `height` pixels) holds a tick: pixels
+    that stand out from the square's own background, so it works in light and dark themes."""
+    inner = [sum(bgra[(y * width + x) * 4:(y * width + x) * 4 + 3]) // 3
+             for y in range(4, height - 4) for x in range(4, min(width, height) - 4)]
+    if not inner:
+        return False
+    background = sorted(inner)[len(inner) // 2]
+    return sum(1 for v in inner if abs(v - background) > 80) > 6
+
+
+def set_check(form: Window, caption: str, checked: bool, timeout: float = 2.0) -> bool:
+    """Set a check box inside `form` (found by caption) to `checked`; True once it shows so.
+
+    Altium's owner-drawn check boxes (TXPCheckBox) answer BM_GETCHECK with 0 whatever their state,
+    so the state is read from the rendered control: a tick in its square."""
+    for child in children(form.hwnd):
+        if child.title.replace("&", "") != caption.replace("&", ""):
+            continue
+
+        def state(hwnd=child.hwnd) -> bool | None:
+            try:
+                return checkbox_state(*_pixels(hwnd))
+            except OSError:
+                return None
+
+        if state() is None:
+            return False  # unreadable: the caller cancels rather than trust an unknown option
+        if state() != checked:
+            click_button(form, caption)
+            deadline = time.monotonic() + timeout
+            while state() != checked and time.monotonic() < deadline:
+                time.sleep(0.1)
+        return state() == checked
+    return False
+
+
+WTS_SESSION_INFO_EX = 25  # WTSSessionInfoEx
+WTS_SESSIONSTATE_LOCK = 0
+
+
+def session_locked() -> bool | None:
+    """Whether this process's Windows session is locked, from WTSSessionInfoEx; None when Windows
+    does not say. A locked session draws nothing, so a capture of it is an empty canvas."""
+    try:
+        wtsapi32 = ctypes.WinDLL("wtsapi32", use_last_error=True)
+    except OSError:
+        return None
+    buffer = ctypes.c_void_p()
+    size = wt.DWORD()
+    # WTS_CURRENT_SERVER_HANDLE (0), WTS_CURRENT_SESSION (-1)
+    if not wtsapi32.WTSQuerySessionInformationW(None, wt.DWORD(0xFFFFFFFF), WTS_SESSION_INFO_EX,
+                                                ctypes.byref(buffer), ctypes.byref(size)):
+        return None
+    try:
+        if not buffer.value or size.value < 16:
+            return None
+        # WTSINFOEXW: Level (DWORD), then WTSINFOEX_LEVEL1_W: SessionId, SessionState, SessionFlags.
+        level, _session, _state, flags = struct.unpack_from("<IIIi", ctypes.string_at(buffer.value, 16))
+        if level != 1:
+            return None
+        return flags == WTS_SESSIONSTATE_LOCK
+    finally:
+        wtsapi32.WTSFreeMemory(buffer)
+
+
+def maximize(hwnd: int) -> None:
+    SW_MAXIMIZE = 3
+    if not user32.IsZoomed(hwnd):
+        user32.ShowWindow(hwnd, SW_MAXIMIZE)
+
+
+def main_window(main_pid: int) -> int | None:
+    for window in top_windows({main_pid}):
+        if window.cls == MAIN_WINDOW_CLASS:
+            return window.hwnd
+    return None
+
+
+def find_view(main_pid: int, document: str | None = None) -> int | None:
+    """The visible graphical view (schematic or PCB) of Altium's main window.
+
+    With `document` (a file name), only the view inside that document's container counts, and
+    only when that container is the visible one: a capture reads what is on screen, and another
+    editor (an OutJob, a report) can cover a view that Windows still calls visible.
+    """
+    for window in top_windows({main_pid}):
+        if window.cls != MAIN_WINDOW_CLASS:
+            continue
+        owner = None
+        for child in children(window.hwnd):
+            if child.cls == "TViewComponent":
+                owner = child
+            if child.cls in ("SchView", "View_Graphical") and is_visible(child.hwnd):
+                if document is None:
+                    return child.hwnd
+                title = (owner.title if owner else "").rstrip(" *")
+                if owner is not None and title.lower() == document.lower() and is_visible(owner.hwnd):
+                    return child.hwnd
+    return None
+
+
+# --- PNG ---------------------------------------------------------------------------------
+
+
+def encode_png(width: int, height: int, rows_rgb: list[bytes]) -> bytes:
+    """Minimal 8-bit RGB PNG encoder (stdlib zlib)."""
+
+    def chunk(tag: bytes, data: bytes) -> bytes:
+        crc = zlib.crc32(tag + data) & 0xFFFFFFFF
+        return struct.pack(">I", len(data)) + tag + data + struct.pack(">I", crc)
+
+    raw = b"".join(b"\x00" + row for row in rows_rgb)
+    header = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
+    return (
+        b"\x89PNG\r\n\x1a\n"
+        + chunk(b"IHDR", header)
+        + chunk(b"IDAT", zlib.compress(raw, 6))
+        + chunk(b"IEND", b"")
+    )
+
+
+def bgra_to_rows(data: bytes, width: int, height: int, step: int = 1) -> list[bytes]:
+    rows = []
+    stride = width * 4
+    for y in range(0, height, step):
+        row = data[y * stride : (y + 1) * stride]
+        if step > 1:
+            row = b"".join(row[i : i + 4] for i in range(0, len(row), 4 * step))
+        rgb = bytearray(len(row) // 4 * 3)
+        rgb[0::3] = row[2::4]
+        rgb[1::3] = row[1::4]
+        rgb[2::3] = row[0::4]
+        rows.append(bytes(rgb))
+    return rows
+
+
+def capture(hwnd: int, path: Path, max_width: int = 1800) -> dict:
+    """Render a window with PrintWindow and write it as PNG, downsampled to `max_width`. An undrawn
+    window is still written; `rendered` and `content` tell the caller what it holds."""
+    width, height, raw, rendered = _print_window(hwnd)
+    step = max(1, -(-width // max_width))
+    rows = bgra_to_rows(raw, width, height, step)
+    out_width = len(rows[0]) // 3 if rows else 0
+    Path(path).write_bytes(encode_png(out_width, len(rows), rows))
+    return {"path": str(path), "width": out_width, "height": len(rows), "rendered": rendered,
+            "content": content_fraction(rows)}
+
+
+def content_fraction(rows: list[bytes]) -> float:
+    """Share of sampled pixels that differ from the most common colour. A view Windows did not
+    draw (locked session, lost GPU device) comes back as one flat colour, close to 0."""
+    from collections import Counter
+
+    pixels = [row[i:i + 3] for row in rows[::4] for i in range(0, len(row), 12)]
+    if not pixels:
+        return 0.0
+    common = Counter(pixels).most_common(1)[0][1]
+    return round(1 - common / len(pixels), 4)