Adom Desktop - KiCad Bridge

kicad_demo now returns the SAME shape as fusion_demo (stage, done, narrate, screenshots[{label,path}], steps, _hint), so the AI that HD's installer runs speaks one vocabulary for both bridges. The verb now CAPTURES its own screenshots per beat (labels schematic/board_2d/board_3d match Fusion's) instead of asking the caller to hunt window titles. A beat that cannot open no longer fails the demo: it narrates the skip and moves on ('never end a demo on an error screen'). The not-installed path narrates KiCad's honest advantage — free, open source, no trial clock or feature tier — and installs it on acceptance.

The bridge no longer takes over the user's screen. navigate_symbol.ps1 previously did an Alt-key foreground trick, SetForegroundWindow, SetCursorPos (moving the user's physical mouse) and SendKeys typing — so if you were working, it typed on top of you. It now sets the search box via UIA ValuePattern (no focus) with a WM_SETTEXT fallback and commits with PostMessage. kicad_send_key and kicad_click now PostMessage directly to the target window by default: no focus theft, no cursor movement, and keys can never leak into the user's active app. Modifier chords and canvas clicks that genuinely need real input return errorCode foreground_required with a hint to WARN the user (~5s) and opt in via allowForeground. launch_editor.ps1 de-foregrounded (UIA Invoke needs no focus).

kicad_demo: a first-class, narrated six-step showcase (symbol, its footprint, that part in 3D, a schematic, the 2D board, the 3D board). Generates every asset in code (ships no sample files) and borrows KiCad's own bundled 3D models. If KiCad is missing it OFFERS to install it: kicad_demo {installKiCad:true} installs silently then runs the tour. Each step returns say/pointOut/window so the AI can narrate and screenshot.

Runtime zip slimmed 31%: removed skills/ (already shipped by the container pkg), demo/, README/CONTRIBUTING/plugin-prompt docs, hero fonts and all images. Keeps code, certs/cacert.pem, .ps1 UIA scripts, templates/blank-board.kicad_pcb and the runtime SKILL.md. No functional change.

kicad_export_molecule: one-shot desktop half of the Adom molecule pipeline (STEP export + silkscreen top/bottom renders + sibling sch/pro discovery + exact container next-steps for step2glb -> adom-molecule). capabilities.py grounds schematic-IPC as a KiCad 11 feature (kipy get_schematic).

Publishing hygiene (SDK re-audit #84): runtime zip is now a Release /download/ asset (not a /files blob); manifest repointed + updateManifestUrl added. enable_software_opengl now fetches Mesa llvmpipe from the Release /download/ asset instead of a /files blob.

Legacy-footprint placement + robust background FP-editor 3D. (1) place_footprint now accepts legacy (module ...) footprints (KiCad<=5 / EAGLE-imported / most chip-fetcher parts): the wrapper is normalized to (footprint ...) so the part splices into a preview board cleanly. (2) The Footprint Editor's 3D viewer opens through the embedded plugin instead of an Alt+3 keystroke: the FP editor is a frame inside the pcbnew process, so the bridge resolves that frame index and posts the live-resolved '3D Viewer' menu id to it — no focus theft, and it fixes an UnboundLocalError (VK_MENU) that broke the path entirely. (3) kicad_click rejects out-of-range coords when relative=True instead of clicking far off-screen (which could hit another window's controls and crash KiCad).

Full winvm verb battery hardening. (1) open_3d_viewer: the PCB '3D Viewer' menu command id drifts across KiCad builds (20563 on one, 20568 on KiCad 10 as shipped to winvm) — the bridge now resolves it LIVE from the plugin's get_menu_ids by matching the menu text, instead of trusting a hardcoded constant, so it works on any build. (2) export_pdf: KiCad 10's kicad-cli now requires --layers for PDF (it errored with none); we now default a full-board layer set for PDF as well as SVG, and accept the layers arg as either a JSON list or a comma string.

3D viewer background fix. The 3D viewer is an in-process child window pcbnew creates and re-raises repeatedly while it renders the board (several seconds) — unlike a launched editor that self-activates just once, so the 6s restore expired mid-render and the viewer ended up on top. open_3d_viewer and place_footprint now get a 16s persistent focus-restore that covers the render, keeping the user's window on top throughout. Verified via desktop_list_windows z-order.

Real fix for KiCad windows opening in the foreground. Root cause: open_board/schematic/place_footprint launch a fresh pcbnew/eeschema via subprocess.Popen, and a newly-launched GUI process activates its own window ASYNCHRONOUSLY — a beat after the handler returns and after the one-shot focus restore, so KiCad won. Now: (1) launches pass a STARTUPINFO with SW_SHOWNOACTIVATE so the new window opens without activating, and (2) the dispatcher runs a persistent background restore for ~6s that re-puts the user's window on top whenever KiCad steals foreground during its async startup. Applies to every window-spawning verb.

UIA background fallback refinement: the substring control search now prefers a control that actually supports InvokePattern (for invoke) or ValuePattern (for setvalue), instead of the first name match. KiCad exposes both a non-invokable 'Footprint Editor' label and the invokable toolbar button under the same name; the old search grabbed the label and returned not_invokable.

Bridge-side UIA background fallback. New handlers/uia.py shells to PowerShell's System.Windows.Automation to Invoke the 'Footprint Editor' / '3D Viewer' controls by accessible name — programmatic UIA Invoke means no foreground, no focus steal, no cursor movement. Wired as Tier 1.5 in open_footprint_editor/open_3d_viewer, between the embedded-plugin WM_COMMAND path and the now-opt-in disruptive fallbacks. KiCad (wxWidgets) exposes an invokable UIA tree, so this reliably opens editors in the background when the plugin path isn't loaded. It's the bridge's own subprocess, not AD's gated run_script.

Truly background operation — never steal focus or move the cursor mid-verb. The open handlers no longer call SetForegroundWindow/BringWindowToTop: _force_foreground now only makes a window visible without activating it (SW_SHOWNOACTIVATE). The two inherently-disruptive fallbacks are now OPT-IN and off by default: the launcher-icon click (which moved the user's mouse via SetCursorPos) requires allowCursorClick, and the Alt+3 3D-viewer keystroke (which needs pcbnew foregrounded) requires allowFocusSteal. Default is the background plugin/WM_COMMAND path. The dispatcher's focus capture+restore now wraps EVERY GUI verb (clicks and key sends included), not just window-raisers.

Latency fixes for two verbs that could hit the 30s client timeout. open_editors now uses the existing budgeted port-prober (3s wall-clock cap + per-port dedup) instead of probing each stale discovery file at 1s — a pile of dead-process files no longer stalls it for 30s when no KiCad is live. The footprint/symbol editor window-appearance poll loops were trimmed from 10s to 6s per tier (they break the instant the window appears). And the read-only reporters (open_editors, screenshot_all, window_info) were removed from the dialog settle-poll set since they don't spawn windows.

Background-open guarantee: the bridge must never steal the user's focus. The dispatcher now captures the user's foreground window before any window-raising verb (open_board/schematic/symbol/footprint/3d, place/install) and restores it afterward via the AttachThreadInput technique so the cross-process focus hand-back reliably sticks. KiCad windows open behind the user's active work. Documented as a non-negotiable rule in the kicad-bridge-dev skill.

Three reliability fixes. (1) Self-heal detection: if the startup cache is empty but KiCad is actually installed (e.g. installed after the bridge booted, via a kicad_upgrade whose client call timed out), the not-installed pre-check now does a live re-detect and refreshes the cache instead of wrongly reporting 'not installed' until a manual respawn. (2) install_library is idempotent: an already-registered library returns success (no-op), not an error. (3) Footprint Editor 3D viewer opens via the Alt+3 accelerator (universal across KiCad versions) with legacy WM_COMMAND fallbacks — the hardcoded 20500 was a KiCad-9 id that silently failed on KiCad 10.

Dialog coverage settle-poll: KiCad's error/parse dialogs are asynchronous and often transient (they appear a beat after the spawning verb's handler returns and auto-close within seconds), so a single post-verb scan raced them. Window-spawning verbs (opens/place/install/screenshot_all) now poll for up to ~3s, catching a late dialog, screenshotting it, and expiring it.

Hardening for constant dialog coverage: the sweep's window-title reads now use InternalGetWindowText (no cross-thread WM_GETTEXT) and dialog body reads use SendMessageTimeout with SMTO_ABORTIFHUNG, so a modal error dialog blocking KiCad's UI thread can no longer hang the scan that is meant to detect it.

Constant error-dialog coverage. Root cause of silent verb failures: the dialog scan was entirely PID-gated, so a KiCad #32770 error box owned by an untracked pcbnew/eeschema/orphan process (e.g. 'Cannot enumerate ...Templates (Access denied)') was invisible and silently blocked the next verb. Added a global EnumWindows finder for #32770/error-title dialogs merged into the scan, and a dispatcher-level auto-sweep that runs after every GUI-affecting verb: it screenshots each dialog, reads its body, expires it so the next verb is unblocked, and attaches _autoDialogs + a _dialogHint to the response so the AI is always shown what KiCad popped.

Hardened first-run wizard handling. The dialog auto-sweep now loops and re-scans (the wizard's Cancel spawns a Confirmation box that a single pass missed), the dismisser clicks Cancel/Finish/Skip and sends Escape for wizards that have no OK button, and ensure_win_user_config now seeds a minimal kicad_common.json (and resolves APPDATA/USERPROFILE robustly, fixing the same stripped-env issue as LOCALAPPDATA) so a freshly installed KiCad never shows the 'Welcome to KiCad' setup wizard. Seeding also runs right after kicad_upgrade so the first GUI open is clean.

kicad_diagnostics now enumerates running KiCad processes via the ctypes EnumProcesses API in-process, replacing a tasklist subprocess that timed out dumping the full process table on a busy VM.

Added kicad_diagnostics, a read-only self-inspection verb so an agent can debug the bridge without ever calling AD's approval-gated run_script/shell. It reports the environment the BRIDGE process actually sees (a stripped LOCALAPPDATA here explains a per-user KiCad going undetected), a full KiCad-detection breakdown (every base path scanned and the version dirs/kicad.exe found), running KiCad processes, and current config/user dir state; optional probePaths and readFile args stat/list any path or peek a small config/output file. Works even when KiCad is absent (bypasses the not-installed pre-check).

Three fixes surfaced by a full verb test on ADOMBASELINE. (1) install_symbol: the top-level symbol extractor only matched 2-space indentation, so every TAB-indented .kicad_sym (modern KiCad, generator kicad_symbol_editor) yielded 'No symbols found'; it now matches any indentation. (2) export_svg: kicad-cli requires --layers for SVG and errored 'At least one layer must be specified'; a sensible full-board layer set is now the default. (3) open_footprint_editor: added a tier that opens the Footprint Editor from a running pcbnew (menu id 20572), so it works when a board is open without needing the kicad.exe project manager (whose first-run wizard otherwise blocked it).

Two fixes found during a full on-VM verb test. (1) close_windows.py used pathlib.Path without importing it, so the dialog auto-sweep crashed with 'name Path is not defined' — this cascaded: window_info/dismiss_dialogs/screenshot_all failed and blocking dialogs then prevented the symbol/footprint editors and 3D viewer from opening. (2) install_symbol failed 'config/user directory not found' on a never-launched KiCad; the shared adom_library._get_paths now bootstraps the config dir the same way install_footprint does.

Critical fix: a per-user (/currentuser, no-UAC) kicad_upgrade install lands in %LOCALAPPDATA%\Programs\KiCad, but AD provisions the bridge Python with a stripped environment where LOCALAPPDATA is unset — so the bridge could not detect the KiCad it had just installed and every verb failed 'not installed'. Detection now derives the LocalAppData root from LOCALAPPDATA, USERPROFILE, and Path.home().

SDK re-audit follow-ups (issue #64): migrated dev + publish skills to the SKILLPACK layout (real skills//SKILL.md with user-invocable:false and DEVELOPER-only descriptions, retiring the dead dev-skills/ convention). Scoped kicad_send_key to single keys delivered to an exact hwnd (dialog Enter/Escape) and pointed modifier chords at AD's desktop_press_key across the verb catalog and skills.

Adopt the AD v1.9.79 generic bridge contract. Completed the detect block with installVerb (kicad_upgrade) and hostAppOptionalVerbs so AD's readiness probe uses this bridge's declaration. Added a timeouts block declaring real budgets for slow verbs (upgrade 900s, DRC/ERC/STEP 300s, gerber 210s, 3D viewer 300s) so they aren't cut off at the old flat 130s. Set statusVerb to kicad_status and added the alias handler AD polls after a non-terminal timeout. Not-installed responses now use the generic host_app_not_installed errorCode plus a hostApp field (legacy kicad_not_installed retained in errorCodeLegacy).

Auto-dismiss the KiCad first-run Welcome wizard and older-version conversion notice. Full README overhaul with a screenshot per window (schematic, symbol, footprint, 2D board, 3D board) captured on a GPU-less Hyper-V VM via the Mesa software-OpenGL fallback, a control-surfaces SVG diagram, and install/dialog/software-OpenGL sections.

New LAST-RESORT fallback verb kicad_enable_software_opengl: deploys Mesa llvmpipe (CPU software OpenGL) into KiCad's bin so KiCad renders on a GPU-less host (Hyper-V/RDP/headless). Slow; never suggested proactively; for worst-case only.

Skills updated with this session's learnings: kicad-interaction now documents the reliable process-based dialog scan + auto-expire + kicad_dismiss_dialogs + Cairo software-canvas self-heal; SKILL.md documents the NsisMultiUser install scope (/allusers vs /currentuser, no-UAC per-user install), the fresh-machine config bootstrap, and elevation diagnostics.

Dialog detection is now RELIABLE: scans EVERY window owned by a running KiCad process (matched by PID, not title/owner — the old way missed the OpenGL notice), classifies dialogs by #32770 class, auto-expires benign ones, screenshots each expired dialog for the AI, and forces the Cairo software canvas on GPU-less hosts.

When the bridge dismisses the 'could not use OpenGL' notice (proof the host has no usable GPU), it now persists graphics.canvas_type=2 (Cairo software) to kicad_common.json so KiCad renders without OpenGL on VMs/RDP/servers. Reported via forcedSoftwareCanvas; close+reopen editors to apply.

Bridge now DETECTS blocking dialogs, returns hints, AND expires the benign ones programmatically: window_info auto-clicks OK on the OpenGL/software-render notice (the modal that stalls editors on GPU-less VMs/RDP), and a new kicad_dismiss_dialogs verb force-clears benign (or all) dialogs.

install_library/install_footprint now bootstrap %APPDATA%/kicad// + seed lib tables from the install template when KiCad has never been launched (fresh machine), instead of failing 'config directory not found'.

Root-cause fix for silent install: KiCad 10's NsisMultiUser installer requires an explicit scope in silent mode — bare /S exits rc=666660 (invalid command-line parameters). kicad_upgrade now passes /allusers /S when elevated or /currentuser /S otherwise (per-user install: no admin, no UAC), accepts {scope}, and detect paths include %LocalAppData%\Programs\KiCad.

kicad_upgrade now reports elevated=true/false (IsUserAnAdmin) so a failed install distinguishes 'AD not elevated' from other causes.

kicad_upgrade reuses an already-downloaded installer in Temp (valid MZ + size) instead of re-fetching ~1GB; pass reDownload:true to force. Makes retrying after a failed install (e.g. UAC not approved) near-instant.

Correct the kicad dependency (>=10.0 -> >=7.0; the bridge supports 7/8/9/10 per its own description). Add download/install progress logging to kicad_upgrade + raise the read timeout to 300s so a slow/stuck install is diagnosable via bridge_log_read.

Bundle certs/cacert.pem (certifi roots) and load it in the SSL context — fixes CERTIFICATE_VERIFY_FAILED on AD's portable Python where the Windows cert enumeration was insufficient.

kicad_upgrade/check_for_updates now build an SSL context that loads the Windows ROOT/CA trust store, fixing CERTIFICATE_VERIFY_FAILED when AD's provisioned portable Python has no CA bundle. Verification stays on.

Fix: kicad_upgrade (and check_for_updates) were blocked by the kicad-not-installed pre-check, so a fresh machine could never bootstrap KiCad. Also refresh the detection cache after a successful install so subsequent verbs see KiCad without a bridge restart.

kicad_describe entries now carry hint/related/pitfalls; every verb returns a rich _hint (fix_keyboard). Resolves discussion #14.