enginehall 2.0.0__py3-none-any.whl

pcba/adapters/altium_outjob.py

@@ -0,0 +1,247 @@
+"""OutJobs the Altium drive writes: what Altium generates (Gerber, drill, pick-and-place, BOM,
+STEP, netlist) and what it publishes to PDF (schematic prints, Draftsman drawings, 3D prints).
+
+Pure text: each writer renders INI that Altium accepts and runs with the bridge's `outjob_run`;
+nothing here talks to Altium. The configuration strings are Altium's own, taken from the OutJobs
+it writes. `pcba.mcp.altium_server` plans and runs them. Class C like the rest of the drive.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+from pcba.adapters import altium_ops
+
+OUTPUT_TYPES = {
+    "gerber": ("Gerber", "Gerber Files", "Fabrication"),
+    "drill": ("NC Drill", "NC Drill Files", "Fabrication"),
+    "pick_place": ("Pick Place", "Pick and Place", "Assembly"),
+    "bom": ("SimpleBOM", "Bill of Materials", "Report"),
+    "step": ("ExportSTEP", "STEP", "Export"),
+    "netlist": ("ProtelNetlist", "Protel Netlist", "Netlist"),
+}
+
+# Gerber layers to plot, as Altium's V7 layer ids (the encoding of its own example OutJobs):
+# 0x0100nnnn signal (1 = top, 0xFFFF = bottom), 0x0101nnnn internal planes, 0x0102nnnn mechanical,
+# 0x0103nnnn overlay (6, 7), paste (8, 9), solder mask (10, 11), keep-out (13), drill drawing (24).
+# Without an explicit list Altium plots only layers that hold primitives, which leaves out the
+# solder-mask and paste layers that pads imply.
+GERBER_LAYERS = (
+    [0x01000001, 0x0100FFFF] + [0x01000000 + i for i in range(2, 9)]       # top, bottom, mid 1-7
+    + [0x01010000 + i for i in range(1, 9)]                               # planes 1-8
+    + [0x01030000 + i for i in (6, 7, 8, 9, 10, 11, 13)]                  # overlays, paste, mask, keep-out
+    + [0x01020000 + i for i in (1, 13, 15)]                               # mechanical 1, 13, 15
+)
+GERBER_PLOT = ("Plot.Set=SerializeLayerHash.Version~2,ClassName~TLayerToBoolean,"
+               + ",".join(f"{i}~1" for i in GERBER_LAYERS))
+GERBER_DEFAULT = (
+    "AddToAllLayerClasses.Set= |AddToAllPlots.Set=SerializeLayerHash.Version~2,ClassName~TLayerToBoolean|"
+    "CentrePlots=False|"
+    "DrillDrawingSymbol=GraphicsSymbol|DrillDrawingSymbolSize=500000|EmbeddedApertures=True|FilmBorderSize=10000000|"
+    "FilmXSize=200000000|FilmYSize=160000000|FlashAllFills=False|FlashPadShapes=True|G54OnApertureChange=False|"
+    "GenerateDRCRulesFile=True|GenerateReliefShapes=True|GerberUnit=Metric|IncludeUnconnectedMidLayerPads=False|"
+    "LeadingAndTrailingZeroesMode=SuppressLeadingZeroes|MaxApertureSize=2500000|MinusApertureTolerance=50|"
+    "MirrorDrillDrawingPlots=False|MirrorDrillGuidePlots=False|NumberOfDecimals=5|OptimizeChangeLocationCommands=True|"
+    "OriginPosition=Relative|Panelize=False|" + GERBER_PLOT + "|PlotPositivePlaneLayers=False|"
+    "PlotUsedDrillDrawingLayerPairs=True|"
+    "PlotUsedDrillGuideLayerPairs=False|PlusApertureTolerance=50|Record=GerberView|SoftwareArcs=False|Sorted=False"
+)
+DRILL_DEFAULT = (
+    "BoardEdgeRoutToolDia=2000000|GenerateBoardEdgeRout=False|GenerateDrilledSlotsG85=False|GenerateEIADrillFile=False|"
+    "GenerateSeparatePlatedNonPlatedFiles=True|NumberOfDecimals=5|NumberOfUnits=2|OptimizeChangeLocationCommands=True|"
+    "OriginPosition=Relative|Record=DrillView|Units=Metric|ZeroesMode=SuppressTrailingZeroes"
+)
+CONFIG = {
+    "gerber": GERBER_DEFAULT,
+    "drill": DRILL_DEFAULT,
+    "pick_place": "Record=PickPlaceView|Units=Metric|GenerateCSVFormat=True|GenerateTextFormat=False",
+}
+
+
+def _job_outputs(text: str) -> list[tuple[str, str]]:
+    """What an OutJob generates: its OutputType, OutputDocumentPath and OutputEnabled entries, which
+    Altium keeps as written when it normalises a job (a restored or hand-edited job differs here)."""
+    keys = ("OutputType", "OutputDocumentPath", "OutputEnabled")
+    found = []
+    for line in text.splitlines():
+        key, _, value = line.strip().partition("=")
+        if key.startswith(keys) and key.rstrip("0123456789") in keys:
+            found.append((key, value))
+    return sorted(found)
+
+
+def _write_job(path: Path, lines: list[str]) -> None:
+    """Write an OutJob only when its settings changed since the drive last wrote it.
+
+    Altium normalises an OutJob it saves (defaults, absolute paths, section order), so the file
+    never equals the drive's text again; rewriting it on every run made each output run a change of
+    an Altium 365 working copy. The hash of the text last written is kept in
+    `<project folder>/.pcba/outjobs.json`; the bridge no longer saves OutJobs at all."""
+    text = "\r\n".join(lines)
+    digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
+    store = path.parent / ".pcba" / "outjobs.json"
+    try:
+        known = json.loads(store.read_text(encoding="utf-8")) if store.is_file() else {}
+    except (OSError, ValueError):
+        known = {}
+    if path.is_file() and known.get(path.name) == digest and \
+            _job_outputs(path.read_text(encoding="utf-8", errors="replace")) == _job_outputs(text):
+        return
+    path.write_text(text, encoding="utf-8", newline="")
+    known[path.name] = digest
+    store.parent.mkdir(exist_ok=True)
+    store.write_text(json.dumps(known, indent=1, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def write_outjob(path: Path, outputs: list[str]) -> None:
+    """Write an OutJob (INI text) Altium accepts: one Folder Structure container."""
+    lines = ["[OutputJobFile]", "Version=1.0", "", "[OutputGroup1]", "Name=", "Description=",
+             "TargetOutputMedium=Folder Structure", "VariantName=[No Variations]", "VariantScope=0",
+             "OutputMedium1=Folder Structure", "OutputMedium1_Type=GeneratedFiles"]
+    for index, key in enumerate(outputs, 1):
+        kind, name, category = OUTPUT_TYPES[key]
+        lines += [f"OutputType{index}={kind}", f"OutputName{index}={name}", f"OutputCategory{index}={category}",
+                  f"OutputDocumentPath{index}=", f"OutputVariantName{index}=", f"OutputEnabled{index}=1",
+                  f"OutputEnabled{index}_OutputMedium1=1", f"OutputDefault{index}=0"]
+        if key in CONFIG:
+            lines += [f"Configuration{index}_Name1=OutputConfigurationParameter1",
+                      f"Configuration{index}_Item1={CONFIG[key]}"]
+    lines += ["", "[GeneratedFilesSettings]", "RelativeOutputPath1=\\", "OpenOutputs1=0", "AddToProject1=0",
+              "TimestampFolder1=0", "UseOutputName1=1", ""]
+    _write_job(path, lines)
+
+
+SCH_PRINT_VIEW = ("Record=SchPrintView|ShowNoERC=True|ShowParamSet=True|ShowProbe=True|ShowBlanket=True|ShowNote=True|"
+                  "ShowNoteCollapsed=True|ExpandDesignator=True|ExpandNetLabel=False|ExpandPort=False|ExpandSheetNum=False|"
+                  "ExpandDocNum=False|PrintArea=0|PrintAreaRect.X1=0|PrintAreaRect.Y1=0|PrintAreaRect.X2=0|PrintAreaRect.Y2=0")
+SCH_PAGE = ("Record=PageOptions|CenterHorizontal=True|CenterVertical=True|PrintScale=1.00|XCorrection=1.00|"
+            "YCorrection=1.00|PrintKind=1|BorderSize=5000000|LeftOffset=0|BottomOffset=0|Orientation=2|PaperLength=1000|"
+            "PaperWidth=1000|Scale=100|PaperSource=7|PrintQuality=-4|MediaType=1|DitherType=10|PrintScaleMode=1")
+
+
+PAPERS = ("A4", "A3", "A2", "Letter", "Tabloid")
+
+
+def write_pdf_outjob(path: Path, pdf: Path, paper: str | None = None) -> None:
+    """An OutJob that publishes every schematic sheet to one PDF, without opening it or asking. Each page
+    is the sheet's own size, or with `paper` that paper (landscape), the sheet scaled to fit."""
+    page = SCH_PAGE + (f"|PaperKind={paper}" if paper else "")
+    lines = ["[OutputJobFile]", "Version=1.0", "", "[OutputGroup1]", "Name=", "Description=", "TargetOutputMedium=PDF",
+             "VariantName=[No Variations]", "VariantScope=0", "OutputMedium1=PDF", "OutputMedium1_Type=Publish",
+             "OutputType1=Schematic Print", "OutputName1=Schematic Prints", "OutputCategory1=Documentation",
+             "OutputDocumentPath1=[Project Physical Documents]", "OutputVariantName1=", "OutputEnabled1=1",
+             "OutputEnabled1_OutputMedium1=1", "OutputDefault1=0", f"PageOptions1={page}",
+             "Configuration1_Name1=OutputConfigurationParameter1", f"Configuration1_Item1={SCH_PRINT_VIEW}",
+             "", "[PublishSettings]", f"OutputFilePath1={pdf}", "ReleaseManaged1=0", "OutputBasePath1=",
+             "OutputPathMedia1=", "OutputPathMediaValue1=", "OutputPathOutputer1=", "OutputPathOutputerPrefix1=",
+             "OutputPathOutputerValue1=", f"OutputFileName1={pdf.name}", "OutputFileNameMulti1=",
+             "UseOutputNameForMulti1=0", "OutputFileNameSpecial1=", "OpenOutput1=0", "PromptOverwrite1=0",
+             "PublishMethod1=0", "ZoomLevel1=50", f"FitSCHPrintSizeToDoc1={0 if paper else 1}",
+             "FitPCBPrintSizeToDoc1=0", "GenerateNetsInfo1=1", "MarkPins1=1", "MarkNetLabels1=1",
+             "MarkPortsId1=1", "GenerateTOC=1", "ShowComponentParameters1=1", ""]
+    _write_job(path, lines)
+
+
+DWF_PAGE = ("Record=PageOptions|CenterHorizontal=True|CenterVertical=True|PrintScale=1.00|XCorrection=1.00|"
+            "YCorrection=1.00|PrintKind=1|BorderSize=5000000|LeftOffset=0|BottomOffset=0|Orientation=2|PaperLength=1000|"
+            "PaperWidth=1000|Scale=100|PaperSource=7|PrintQuality=-3|MediaType=1|DitherType=10|PrintScaleMode=1|"
+            "PaperKind=A4|PaperIndex=9")
+
+
+def drawing_medium(doc: Path) -> str:
+    """The Publish medium of one Draftsman document; the bridge publishes any medium named PDF..."""
+    return f"PDF {doc.stem}"
+
+
+def write_drawings_outjob(path: Path, drawings: list[tuple[Path, Path]]) -> None:
+    """An OutJob that publishes each Draftsman document (.PCBDwf) to its own PDF: one Publish medium
+    per drawing, the drawing's own sheet size (FitPCBPrintSizeToDoc), no viewer, no prompt."""
+    lines = ["[OutputJobFile]", "Version=1.0", "", "[OutputGroup1]", "Name=", "Description=",
+             f"TargetOutputMedium={drawing_medium(drawings[0][0])}", "VariantName=[No Variations]", "VariantScope=0"]
+    for m, (doc, _) in enumerate(drawings, 1):
+        lines += [f"OutputMedium{m}={drawing_medium(doc)}", f"OutputMedium{m}_Type=Publish"]
+    for n, (doc, _) in enumerate(drawings, 1):
+        lines += [f"OutputType{n}=PCBDrawing", f"OutputName{n}={doc.stem}", f"OutputCategory{n}=Documentation",
+                  f"OutputDocumentPath{n}={doc.name}", f"OutputVariantName{n}=", f"OutputEnabled{n}=1"]
+        lines += [f"OutputEnabled{n}_OutputMedium{m}={1 if m == n else 0}" for m in range(1, len(drawings) + 1)]
+        lines += [f"OutputDefault{n}=0", f"PageOptions{n}={DWF_PAGE}"]
+    lines += ["", "[PublishSettings]"]
+    for m, (_, pdf) in enumerate(drawings, 1):
+        lines += [f"OutputFilePath{m}={pdf}", f"ReleaseManaged{m}=0", f"OutputBasePath{m}=", f"OutputPathMedia{m}=",
+                  f"OutputPathMediaValue{m}=", f"OutputPathOutputer{m}=", f"OutputPathOutputerPrefix{m}=",
+                  f"OutputPathOutputerValue{m}=", f"OutputFileName{m}={pdf.name}", f"OutputFileNameMulti{m}=",
+                  f"UseOutputNameForMulti{m}=0", f"OutputFileNameSpecial{m}=", f"OpenOutput{m}=0",
+                  f"PromptOverwrite{m}=0", f"PublishMethod{m}=0", f"ZoomLevel{m}=50", f"FitSCHPrintSizeToDoc{m}=1",
+                  f"FitPCBPrintSizeToDoc{m}=1", f"GenerateNetsInfo{m}=0", f"MarkPins{m}=0", f"MarkNetLabels{m}=0",
+                  f"MarkPortsId{m}=0", f"GenerateTOC{m}=0", f"ShowComponentParameters{m}=0"]
+    lines.append("")
+    _write_job(path, lines)
+
+
+# Altium's 3D view configuration for prints (board core and prepreg, mask, copper, silk, component
+# bodies and their STEP models; white workspace), as Altium writes it into an OutJob's PCB 3D Print.
+# Altium's own example hides STEP models (SHOWCOMPONENTSTEPMODELS FALSE), which drew a board with
+# manufacturer models as bare pads.
+PCB3D_VIEW_CONFIG = (r"RECORD\3Board\2CFGALL.CONFIGURATIONKIND\33"
+                     r"\2CFGALL.CONFIGURATIONDESC\3Enter%20description%20of%20new%20view%20configuration"
+                     r"\2CFG3D.POSITIVETOPSOLDERMASK\3TRUE\2CFG3D.POSITIVEBOTTOMSOLDERMASK\3TRUE"
+                     r"\2CFG3D.SHOWCOMPONENTBODIES\3TRUE\2CFG3D.SHOWCOMPONENTDEFAULTMODELS\3FALSE"
+                     r"\2CFG3D.SHOWCOMPONENTSTEPMODELS\3TRUE\2CFG3D.SHOWBOARDCORE\3TRUE\2CFG3D.SHOWBOARDPREPREG\3TRUE"
+                     r"\2CFG3D.SHOWTOPSILKSCREEN\3TRUE\2CFG3D.SHOWBOTSILKSCREEN\3TRUE\2CFG3D.WORKSPACECOLOR\316777215"
+                     r"\2CFG3D.BOARDCORECOLOR\30\2CFG3D.BOARDPREPREGCOLOR\30\2CFG3D.TOPSOLDERMASKCOLOR\33307556"
+                     r"\2CFG3D.BOTSOLDERMASKCOLOR\33307556\2CFG3D.COPPERCOLOR\32402753"
+                     r"\2CFG3D.TOPSILKSCREENCOLOR\316448250\2CFG3D.BOTSILKSCREENCOLOR\316448250"
+                     r"\2CFG3D.WORKSPACELUMINANCEVARIATION\330\2CFG3D.WORKSPACECOLOROPACITY\31.000000"
+                     r"\2CFG3D.BOARDCORECOLOROPACITY\30.500000\2CFG3D.BOARDPREPREGCOLOROPACITY\30.500000"
+                     r"\2CFG3D.TOPSOLDERMASKCOLOROPACITY\30.600000\2CFG3D.BOTSOLDERMASKCOLOROPACITY\30.600000"
+                     r"\2CFG3D.COPPERCOLOROPACITY\31.000000\2CFG3D.TOPSILKSCREENCOLOROPACITY\31.000000"
+                     r"\2CFG3D.BOTSILKSCREENCOLOROPACITY\31.000000\2CFG3D.BOARDTHICKNESSSCALING\31.000000")
+PCB3D_PAGE = ("Record=PageOptions|CenterHorizontal=True|CenterVertical=True|PrintScale=1.61|XCorrection=1.00|"
+              "YCorrection=1.00|PrintKind=1|BorderSize=5000000|LeftOffset=0|BottomOffset=0|Orientation=2|"
+              "PaperLength=1000|PaperWidth=1000|Scale=100|PaperSource=7|PrintQuality=-4|MediaType=1|DitherType=10|"
+              "PrintScaleMode=1|PaperKind=A4")
+# Camera orientation as Altium's quaternion (w, x, y, z): straight views look along Z; the angled
+# views tilt and turn the board, the bottom one also turned over about X. The last field scales
+# the zoom so an angled board fits the page.
+PCB3D_VIEWS = (
+    ("Top", (1, 0, 0, 0), True, 1.0),
+    ("Bottom", (1, 0, 0, 0), False, 1.0),
+    ("Top angled", (0.897718250751495, -0.291343718767166, -0.308464288711548, 0.118618682026863), True, 0.68),
+    ("Bottom angled", (0.2913437, 0.8977183, 0.1186187, 0.3084643), False, 0.68),
+)
+
+
+def write_3d_outjob(path: Path, pdf: Path, origin: tuple[int, int], outline: list[tuple[int, int]]) -> None:
+    """An OutJob that publishes Altium's own 3D renderings of the board (PCB 3D Print: top, bottom
+    and two angled views) to one PDF. The camera follows the board outline (Altium internal units,
+    outline relative to the board origin)."""
+    xs = [pt[0] for pt in outline]
+    ys = [pt[1] for pt in outline]
+    margin = 14 * altium_ops.UNITS_PER_MM
+    view_x, view_y = max(xs) - min(xs) + margin, max(ys) - min(ys) + margin
+    look_x, look_y = origin[0] + (min(xs) + max(xs)) / 2, origin[1] + (min(ys) + max(ys)) / 2
+    lines = ["[OutputJobFile]", "Version=1.0", "", "[OutputGroup1]", "Name=", "Description=", "TargetOutputMedium=PDF",
+             "VariantName=[No Variations]", "VariantScope=0", "OutputMedium1=PDF", "OutputMedium1_Type=Publish"]
+    for n, (name, (w, x, y, z), top, zoom) in enumerate(PCB3D_VIEWS, 1):
+        item = (f"Record=Pcb3DPrintView|ResX=300|ResY=300|ViewX={view_x:.0f}|ViewY={view_y:.0f}|LookAtX={look_x:.0f}|"
+                f"LookAtY={look_y:.0f}|LookAtZ=0|QuatX={x}|QuatY={y}|QuatZ={z}|QuatW={w}|"
+                f"Zoom={1018 * zoom / view_x:.6E}|"
+                f"UnitsPercent=True|UnitsDPI=True|LockResAspect=True|ViewConfigType=.config_3d|"
+                f"CustomCamera={zoom != 1.0}|ViewFromTop={top}|ViewConfig={PCB3D_VIEW_CONFIG}")
+        lines += [f"OutputType{n}=PCB 3D Print", f"OutputName{n}=PCB 3D Print {name}",
+                  f"OutputCategory{n}=Documentation", f"OutputDocumentPath{n}=", f"OutputVariantName{n}=",
+                  f"OutputEnabled{n}=1",
+                  # Not a flag: the output's position within the medium (0 = not in it), so the
+                  # views become pages 1 to 4 of the PDF, as Altium writes it in its own OutJobs.
+                  f"OutputEnabled{n}_OutputMedium1={n}", f"OutputDefault{n}=0", f"PageOptions{n}={PCB3D_PAGE}",
+                  f"Configuration{n}_Name1=OutputConfigurationParameter1", f"Configuration{n}_Item1={item}"]
+    lines += ["", "[PublishSettings]", f"OutputFilePath1={pdf}", "ReleaseManaged1=0", "OutputBasePath1=",
+              "OutputPathMedia1=", "OutputPathMediaValue1=", "OutputPathOutputer1=", "OutputPathOutputerPrefix1=",
+              "OutputPathOutputerValue1=", f"OutputFileName1={pdf.name}", "OutputFileNameMulti1=",
+              "UseOutputNameForMulti1=0", "OutputFileNameSpecial1=", "OpenOutput1=0", "PromptOverwrite1=0",
+              "PublishMethod1=0", "ZoomLevel1=50", "FitSCHPrintSizeToDoc1=1", "FitPCBPrintSizeToDoc1=1",
+              "GenerateNetsInfo1=0", "MarkPins1=0", "MarkNetLabels1=0", "MarkPortsId1=0", "GenerateTOC=0",
+              "ShowComponentParameters1=0", ""]
+    _write_job(path, lines)

pcba/adapters/altium_uia.py

@@ -0,0 +1,304 @@
+"""Windows UI Automation for Altium's dialogs, through ctypes vtable calls (no comtypes).
+
+Altium draws its prompts with three toolkits: VCL forms (`TMessageForm`, readable only in part
+through Win32), standard `#32770` message boxes, and WPF windows (`HwndWrapper[…]`: "Unsaved
+Changes", "Confirm Save to Server", "Version Control", "Save … to Server"). Win32 sees nothing
+inside a WPF window: no child windows, no text. UI Automation sees all three, so this module is
+how the drive reads a dialog (title, text, buttons, check boxes, edit fields) and answers it by
+the caption of a button instead of cancelling it.
+
+Stdlib only, like `altium_win32`: the engine keeps its single runtime dependency. Each call
+creates and releases its own COM objects; nothing is cached across dialogs.
+
+Vtable indices are those of UIAutomationClient.h (Windows 10 SDK): IUIAutomation,
+IUIAutomationElement, IUIAutomationElementArray and the Invoke, Value, Toggle and
+LegacyIAccessible patterns. Measured against Altium Designer Develop 26.10.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+import uuid
+from dataclasses import dataclass, field
+
+CONTROL = {
+    50000: "button", 50002: "checkbox", 50004: "edit", 50005: "hyperlink", 50007: "listitem",
+    50008: "list", 50020: "text", 50024: "treeitem", 50025: "custom", 50029: "dataitem",
+    50032: "window", 50033: "pane", 50028: "datagrid", 50036: "table",
+}
+TREESCOPE_DESCENDANTS = 4
+INVOKE, VALUE, TOGGLE, LEGACY = 10000, 10002, 10015, 10018
+TOGGLE_ON = 1
+
+
+@dataclass(slots=True)
+class Element:
+    """One UI Automation element of a dialog, as plain data."""
+
+    kind: str
+    name: str
+    automation_id: str = ""
+    cls: str = ""
+    enabled: bool = True
+    checked: bool | None = None
+    value: str | None = None
+    rect: tuple[int, int, int, int] = (0, 0, 0, 0)
+
+
+@dataclass(slots=True)
+class Dialog:
+    """What a person sees in a dialog: its title, the sentences, and what can be pressed."""
+
+    title: str
+    framework: str
+    texts: list[str] = field(default_factory=list)
+    buttons: list[str] = field(default_factory=list)
+    checkboxes: list[dict] = field(default_factory=list)
+    edits: list[dict] = field(default_factory=list)
+    items: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        out = {"title": self.title, "framework": self.framework, "texts": self.texts, "buttons": self.buttons}
+        for key in ("checkboxes", "edits", "items"):
+            if getattr(self, key):
+                out[key] = getattr(self, key)
+        return out
+
+
+def caption(text: str) -> str:
+    """A caption as the drive compares it: no `&` accelerator, typographic quotes made plain
+    (Altium writes "Don’t Save" with U+2019), whitespace collapsed, lower case."""
+    plain = text.replace("&", "").replace("’", "'").replace("‘", "'").replace("…", "...")
+    return " ".join(plain.split()).lower()
+
+
+def summarise(title: str, framework: str, elements: list[Element]) -> Dialog:
+    """Turn UI Automation elements into what a person reads. WPF repeats each button's and check
+    box's caption as a text element inside it; those repeats are dropped from `texts`."""
+    d = Dialog(title=title, framework=framework)
+    labels = {caption(e.name) for e in elements if e.kind in ("button", "checkbox") and e.name}
+    for e in elements:
+        if e.kind == "button" and e.name:
+            if e.name not in d.buttons:
+                d.buttons.append(e.name)
+        elif e.kind == "checkbox":
+            d.checkboxes.append({"name": e.name, "checked": e.checked})
+        elif e.kind == "edit":
+            d.edits.append({"name": e.name, "id": e.automation_id, "value": e.value})
+        elif e.kind == "text" and e.name.strip() and caption(e.name) not in labels:
+            if e.name.strip() not in d.texts:
+                d.texts.append(e.name.strip())
+        elif e.kind in ("listitem", "dataitem", "treeitem") and e.name:
+            d.items.append({"kind": e.kind, "name": e.name})
+    return d
+
+
+if sys.platform == "win32":  # pragma: no cover - exercised only on Windows with Altium
+    import ctypes.wintypes as wt
+
+    ole32 = ctypes.OleDLL("ole32")
+    oleaut32 = ctypes.WinDLL("oleaut32")
+    HRESULT = ctypes.c_long
+
+    class GUID(ctypes.Structure):
+        _fields_ = [("Data1", ctypes.c_ulong), ("Data2", ctypes.c_ushort), ("Data3", ctypes.c_ushort),
+                    ("Data4", ctypes.c_ubyte * 8)]
+
+        @classmethod
+        def of(cls, text: str) -> GUID:
+            g = cls()
+            ctypes.memmove(ctypes.byref(g), uuid.UUID(text).bytes_le, 16)
+            return g
+
+    CLSID_CUIAutomation = GUID.of("ff48dba4-60ef-4201-aa87-54103eef594e")
+    IID_IUIAutomation = GUID.of("30cbe57d-d9d0-452a-ab13-7ac5ac4825ee")
+    IID = {
+        INVOKE: GUID.of("fb377fbe-8ea6-46d5-9c73-6499642d3059"),
+        VALUE: GUID.of("a94cd8b1-0844-4cd6-9d2d-640537ab39e9"),
+        TOGGLE: GUID.of("94cf8058-9b8d-4ab9-8bfd-4cd0a33c8c70"),
+        LEGACY: GUID.of("828055ad-355b-4435-86d5-3b51c14a9b1b"),
+    }
+
+    def _call(ptr, index: int, *argtypes):
+        vtbl = ctypes.cast(ptr, ctypes.POINTER(ctypes.POINTER(ctypes.c_void_p))).contents
+        fn = ctypes.WINFUNCTYPE(HRESULT, ctypes.c_void_p, *argtypes)(vtbl[index])
+
+        def invoke(*args):
+            hr = fn(ptr, *args)
+            if hr < 0:
+                raise OSError(f"UI Automation call {index} failed: HRESULT 0x{hr & 0xFFFFFFFF:08X}")
+            return hr
+        return invoke
+
+    def _release(ptr) -> None:
+        if ptr:
+            vtbl = ctypes.cast(ptr, ctypes.POINTER(ctypes.POINTER(ctypes.c_void_p))).contents
+            ctypes.WINFUNCTYPE(ctypes.c_ulong, ctypes.c_void_p)(vtbl[2])(ptr)
+
+    def _out_ptr(ptr, index: int, *args, argtypes=()) -> ctypes.c_void_p:
+        out = ctypes.c_void_p()
+        _call(ptr, index, *argtypes, ctypes.POINTER(ctypes.c_void_p))(*args, ctypes.byref(out))
+        return out
+
+    def _bstr(ptr, index: int) -> str:
+        out = _out_ptr(ptr, index)
+        if not out.value:
+            return ""
+        try:
+            return ctypes.wstring_at(out.value)
+        finally:
+            oleaut32.SysFreeString(out)
+
+    def _int(ptr, index: int) -> int:
+        out = ctypes.c_int()
+        _call(ptr, index, ctypes.POINTER(ctypes.c_int))(ctypes.byref(out))
+        return out.value
+
+    def _rect(ptr) -> tuple[int, int, int, int]:
+        r = wt.RECT()
+        _call(ptr, 43, ctypes.POINTER(wt.RECT))(ctypes.byref(r))   # get_CurrentBoundingRectangle
+        return (r.left, r.top, r.right, r.bottom)
+
+    def _pattern(el, pattern: int) -> ctypes.c_void_p:
+        out = ctypes.c_void_p()
+        _call(el, 14, ctypes.c_int, ctypes.POINTER(GUID), ctypes.POINTER(ctypes.c_void_p))(
+            pattern, ctypes.byref(IID[pattern]), ctypes.byref(out))   # GetCurrentPatternAs
+        return out
+
+    class _Session:
+        """One COM apartment and one IUIAutomation object for the duration of a `with` block."""
+
+        def __enter__(self):
+            try:
+                ole32.CoInitializeEx(None, 0x2)   # apartment threaded; S_FALSE if already initialised
+            except OSError:
+                pass   # RPC_E_CHANGED_MODE: the thread already has an apartment, which is fine
+            self.uia = ctypes.c_void_p()
+            ole32.CoCreateInstance(ctypes.byref(CLSID_CUIAutomation), None, 1,
+                                   ctypes.byref(IID_IUIAutomation), ctypes.byref(self.uia))
+            self.owned: list = []
+            return self
+
+        def __exit__(self, *exc):
+            for ptr in self.owned:
+                _release(ptr)
+            _release(self.uia)
+
+        def root(self, hwnd: int):
+            el = _out_ptr(self.uia, 6, hwnd, argtypes=(wt.HWND,))   # ElementFromHandle
+            self.owned.append(el)
+            return el
+
+        def descendants(self, el) -> list:
+            cond = _out_ptr(self.uia, 21)                             # CreateTrueCondition
+            self.owned.append(cond)
+            arr = _out_ptr(el, 6, TREESCOPE_DESCENDANTS, cond, argtypes=(ctypes.c_int, ctypes.c_void_p))
+            self.owned.append(arr)
+            if not arr.value:
+                return []
+            out = []
+            for i in range(_int(arr, 3)):                             # get_Length
+                item = _out_ptr(arr, 4, i, argtypes=(ctypes.c_int,))   # GetElement
+                self.owned.append(item)
+                out.append(item)
+            return out
+
+    def _element(el) -> Element:
+        kind = CONTROL.get(_int(el, 21), "other")
+        e = Element(kind=kind, name=_bstr(el, 23), automation_id=_bstr(el, 29), cls=_bstr(el, 30),
+                    enabled=bool(_int(el, 28)), rect=_rect(el))
+        if kind == "checkbox":
+            try:
+                toggle = _pattern(el, TOGGLE)
+                if toggle.value:
+                    try:
+                        e.checked = _int(toggle, 4) == TOGGLE_ON         # get_CurrentToggleState
+                    finally:
+                        _release(toggle)
+            except OSError:
+                pass  # no Toggle pattern on this control: its state stays unknown (None)
+        if kind == "edit":
+            try:
+                value = _pattern(el, VALUE)
+                if value.value:
+                    try:
+                        e.value = _bstr(value, 4)                        # get_CurrentValue
+                    finally:
+                        _release(value)
+            except OSError:
+                pass  # no Value pattern on this control: its text stays unknown (None)
+        return e
+
+    def elements(hwnd: int) -> list[Element]:
+        """Every element below a top-level window, in UI Automation's order."""
+        with _Session() as s:
+            return [_element(el) for el in s.descendants(s.root(hwnd))]
+
+    def describe(hwnd: int) -> Dialog:
+        """Read a dialog the way a person would: title, sentences, buttons, check boxes, fields."""
+        with _Session() as s:
+            root = s.root(hwnd)
+            return summarise(_bstr(root, 23), _bstr(root, 40), [_element(el) for el in s.descendants(root)])
+
+    def _find(s: _Session, hwnd: int, kind: str, name: str | None, index: int = 0):
+        wanted = caption(name or "")
+        hits = []
+        for el in s.descendants(s.root(hwnd)):
+            if CONTROL.get(_int(el, 21)) != kind:
+                continue
+            if name is None or caption(_bstr(el, 23)) == wanted:
+                hits.append(el)
+        return hits[index] if len(hits) > index else None
+
+    def press(hwnd: int, label: str) -> bool:
+        """Press the button named `label` (compared with `caption()`). Invoke pattern first; the
+        legacy default action for owner-drawn buttons."""
+        with _Session() as s:
+            el = _find(s, hwnd, "button", label)
+            if el is None:
+                return False
+            for pattern, method in ((INVOKE, 3), (LEGACY, 4)):     # Invoke / DoDefaultAction
+                try:
+                    p = _pattern(el, pattern)
+                except OSError:
+                    continue
+                if p.value:
+                    try:
+                        _call(p, method)()
+                        return True
+                    finally:
+                        _release(p)
+            return False
+
+    def set_checked(hwnd: int, name: str, checked: bool) -> bool | None:
+        """Set a check box by name; returns its final state, None if it was not found."""
+        with _Session() as s:
+            el = _find(s, hwnd, "checkbox", name)
+            if el is None:
+                return None
+            p = _pattern(el, TOGGLE)
+            if not p.value:
+                return None
+            try:
+                for _ in range(3):
+                    if (_int(p, 4) == TOGGLE_ON) == checked:
+                        return checked
+                    _call(p, 3)()                                          # Toggle
+                return (_int(p, 4) == TOGGLE_ON)
+            finally:
+                _release(p)
+
+else:  # pragma: no cover - the adapter refuses non-Windows platforms before reaching here
+
+    def elements(hwnd: int) -> list[Element]:
+        raise OSError("UI Automation needs Windows")
+
+    def describe(hwnd: int) -> Dialog:
+        raise OSError("UI Automation needs Windows")
+
+    def press(hwnd: int, label: str) -> bool:
+        raise OSError("UI Automation needs Windows")
+
+    def set_checked(hwnd: int, name: str, checked: bool) -> bool | None:
+        raise OSError("UI Automation needs Windows")