Altium - the Altium Bridge

@@ -405,14 +405,77 @@ DEMO_PCB = EXAMPLES_DIR + r"\Bluetooth Sentinel\Bluetooth_Sentinel.PcbDoc" DEMO_SCH = EXAMPLES_DIR + r"\Bluetooth Sentinel\Bluetooth_Sentinel.SchDoc"  -def _shot_of_main() -> dict | None:++# ---- background capture (John, 2026-09-01) ----------------------------------------------------+#+# Windows will not render a MINIMIZED window, so a capture of one returns a ~237x39 sliver of the+# title bar — which this bridge used to hand back as "proof" of a successful import. The wiki+# front-end would have displayed that.+#+# The fix John asked for, and it is the right one: make sure the window is in the BACKGROUND but+# NOT minimized, then use ab's window capture (which reads an occluded window fine). The rejected+# alternative was parking the window off-screen: if the user then reaches for Altium manually, they+# find nothing on screen. Never move a window the user might go looking for.++MIN_PROOF_WIDTH = 400  # anything narrower is a minimized-window sliver, not a screenshot+++def _is_minimized(rect: dict) -> bool:+    if not rect:+        return False+    return (rect.get("left", 0) <= -30000 or rect.get("top", 0) <= -30000+            or (rect.get("width", 0) < MIN_PROOF_WIDTH and rect.get("height", 0) < 200))+++def _make_capturable(hwnd: int) -> dict:+    """Restore a minimized window and push it BEHIND the user's windows, then hand the foreground+    straight back. Measured end to end at ~0.6s. Returns what it had to do, so a caller can report+    honestly whether the user's screen was touched."""+    out = {"restored": False, "sentToBack": False, "foregroundReturned": False}+    try:+        before = (caller_identity.ad_callback("desktop_get_foreground", {}, on_behalf=False, timeout=8) or {}).get("hwnd")+        wins = caller_identity.ad_callback("desktop_enum_windows", {"pids": [altium_detect.main_window()["pid"]]},+                                           on_behalf=False, timeout=10) or {}+        rect = next((w.get("rect") for w in (wins.get("windows") or []) if w.get("hwnd") == hwnd), None)+        if isinstance(rect, list) and len(rect) == 4:+            rect = {"left": rect[0], "top": rect[1], "width": rect[2] - rect[0], "height": rect[3] - rect[1]}+        if _is_minimized(rect):+            caller_identity.ad_callback("desktop_set_window_state", {"hwnd": hwnd, "state": "restore"},+                                        on_behalf=False, timeout=10)+            out["restored"] = True+        r = caller_identity.ad_callback("desktop_set_window_state", {"hwnd": hwnd, "state": "bottom"},+                                        on_behalf=False, timeout=10) or {}+        out["sentToBack"] = True+        after = (caller_identity.ad_callback("desktop_get_foreground", {}, on_behalf=False, timeout=8) or {}).get("hwnd")+        if before and after != before:+            caller_identity.ad_callback("desktop_raise_window", {"hwnd": before}, on_behalf=False, timeout=10)+            out["foregroundReturned"] = True+        out["userForeground"] = before+    except Exception as e:+        out["error"] = str(e)+    return out+++def _shot_of_main(prepare: bool = True) -> dict | None:+    """A capture of Altium's main window, or None — never a minimized-window sliver.++    `prepare` restores the window into the BACKGROUND first if it is minimized (see+    `_make_capturable`). A returned frame carries `prepared` so the caller can say what was done."""     mw = altium_detect.main_window()     if not mw or not ad_client.available():         return None+    prepared = _make_capturable(mw["hwnd"]) if prepare else None     r = caller_identity.ad_callback("desktop_screenshot_base64", {"hwnd": mw["hwnd"]})     if isinstance(r, dict) and (r.get("image") or r.get("base64")):+        w, h = r.get("width"), r.get("height")+        if isinstance(w, int) and w < MIN_PROOF_WIDTH:+            # a sliver: Windows had nothing to render. Say so instead of shipping it as evidence.+            return {"title": mw["title"], "hwnd": mw["hwnd"], "proofUnavailable": True,+                    "reason": f"the Altium window is minimized (captured {w}x{h}) — Windows does not "+                              f"render a minimized window, so there is no image to prove anything",+                    "prepared": prepared}         return {"title": mw["title"], "hwnd": mw["hwnd"], "image": r.get("image") or r.get("base64"),-                "width": r.get("width"), "height": r.get("height")}+                "width": w, "height": h, "prepared": prepared}     return None  @@ -495,10 +558,21 @@ def _lib_surface(args, kind: str, default_path: str, label: str, after: list[tup     _attach_dialog_shots(dl)     shot = _shot_of_main()     mw = altium_detect.main_window() or {}-    return {"success": not dl, "surface": label, "path": path, "selected": (sel.get("data") or {}).get("selected"),-            "steps": steps, "title": mw.get("title"), "dialogsDetected": len(dl), "dialogs": dl, "shot": shot,-            "windowEtiquette": "background", "elapsedSec": round(time.time() - t0, 1),-            "_hint": f"{label}: {(sel.get('data') or {}).get('selected')} in {mw.get('document')}. shot.image is the frame."}+    # A surface verb exists to produce PROOF. If there is no image, saying success:true would hand+    # the caller (and the wiki front-end) a confident nothing.+    no_proof = bool(shot and shot.get("proofUnavailable"))+    out = {"success": (not dl) and not no_proof, "surface": label, "path": path,+           "selected": (sel.get("data") or {}).get("selected"),+           "steps": steps, "title": mw.get("title"), "dialogsDetected": len(dl), "dialogs": dl, "shot": shot,+           "windowEtiquette": "background", "elapsedSec": round(time.time() - t0, 1),+           "_hint": f"{label}: {(sel.get('data') or {}).get('selected')} in {mw.get('document')}. shot.image is the frame."}+    if no_proof:+        out["errorCode"] = "proof_unavailable"+        out["error"] = shot.get("reason")+        out["_hint"] = ("The surface was opened and selected correctly — only the CAPTURE failed, because "+                        "the Altium window is minimized. The bridge restores it into the background "+                        "automatically; if it is still minimized, something re-minimized it mid-call.")+    return out   def h_show_library(args):