KiCad - the KiCad Bridge

Update: added the 8th surface — kicad_show_project (0.9.96), the electronics project / KiCad Project Manager, the top of the design tree that schematic + board + editors hang off. Verified cold.

Complete surface family and honest cold-start status:

So 6 of 8 solid cold, 2 (the 3D viewers) get you to the right state but the final 3D window is warm-only — tracked in #26 (KiCad's wx toolbar exposes no UIA-invokable 3D control, so the plugin-free open needs a menu-UIA navigator or fast plugin bind; also entangled with ab #73's 30s CLI cap). All eight are named, in kicad_describe + bridge.json + the daily suite.

Update: all 8 surfaces are now SOLID COLD. show_3d_chip and show_3d_board (the two previously warm-only) work from fully closed as of 0.9.99 via a plugin-free Win32 menu-bar tier (GetMenu -> resolve '3D Viewer' -> PostMessage WM_COMMAND). #26 closed. The only residual is ab #73's 30s CLI cap on cold 3D opens (poll kicad_state, or use background kicad_demo).

0.9.107: kicad_install_footprint now takes model:{fileName,fileContent}, a base64 .step/.wrl installed to Documents/KiCad//3dmodels/Adom/ and wired into the footprint's (model ...) reference (injected if the footprint ships without one). This closes the wiki-component loop: a page like aravk/in-s63btg ships symbol+footprint+step, and now all three land. kicad_show_symbol / kicad_show_footprint / kicad_show_3d_chip proved live on a real user page (green 0603 LED), all in the background. One caveat for the install-then-show flow: if KiCad is already running, the Symbol Editor's library tree can be stale for a just-installed symbol. Close KiCad (kicad_close) before kicad_show_symbol, or expect '[no symbol loaded]'. Cold open reads the fresh table and works every time.

0.9.108 closes the Web Control demo gap: kicad_make_part_project {partName} generates a real project (kicad_pro, wired kicad_sch with the part as D1 + a 330R, routed kicad_pcb with edge cuts and the part's (model ...) ref) around any part installed in the Adom library, so the project / schematic / 2D board / 3D board buttons have something true to show per part. install_symbol / install_footprint (and model) also accept filePath now, so big steps stage via ab send_files instead of base64 (the CLI arg limit bites at ~95KB). Full 8-surface proof ran today on wiki.adom.inc/aravk/in-s42atr: every surface background-opened cold with a screenshot plus a pulled file artifact (BOM lists the part; the kicad-cli board STEP embeds PRODUCT 'IN-S42ATR'; the pulled 3D step sha256-matches the page source). The exact button-to-verb recipe is on adom-bridge-sdk#4.

0.9.109 shipped: kicad_export_part {partName} writes one-off single-asset library files (symbol-only .kicad_sym, footprint-only .pretty, bare 3D model), the reverse of install. kicad_make_part_project boards are now part-dominant (tight edge cuts) so the part's 3D model is clearly visible in the 3D board view; the 'chip missing from 3D board' symptom on 0.9.108 was a zoom artifact, the model always loaded (board STEP exports embed PRODUCT('')). kicad_uninstall also cleans adom-part-exports and adom-part-staging. Full proof run on wiki.adom.inc/aravk/in-s42ata: 8/8 surfaces background, one-offs verified single-entry, installed step sha256-matches the page source. Demo recipe notes for ab are on adom-bridge-sdk#4.

0.9.110: screenshots no longer require PIL. Found running kicad_demo on ConfRoomROG's first-ever bridge boot: ab 2.0.44+'s managed Python runtime is stdlib-only, so on a fresh box every capture fell back to .bmp and kicad_state returned zero images. handlers/png_stdlib.py now encodes the GDI BGRA buffer straight to PNG (zlib + struct, ~0.3s/frame, 1568px cap) whenever PIL is absent. Every new user box gets the managed runtime, so this was a release blocker in waiting. Demo verified end to end on that box: all six beats, background job, zero foreground violations, ~100s.

0.9.112: kicad_make_part_project now generates SINGLE-COMPONENT demo projects. John's ruling (2026-08-16): when demoing one component, extra parts on the example board just confuse the user. The synthetic 330R companion is gone; the sheet holds the part alone with stub wires, the board holds its footprint centered in tight edge cuts with two copper stubs, and the refdes comes from the part's own Reference property (D1 for the LED, C1 for the capacitor). Verified live on ConfRoomROG with both aravk/0402n101j500ct and aravk/in-s42ata; README section and screenshots refreshed. Web Control note: nothing changes in the recipe, same verbs, same returns, plus a new 'reference' field.

0.9.113-0.9.115: the always-on focus sentinel. John caught late self-raise flashes live (KiCad windows activating after per-verb guards expired, e.g. a 3D render or library load finishing minutes later). The bridge now watches every foreground transition for its whole lifetime: a KiCad window reaching the foreground without a user cause is minimize-bounced back; user cause means a click landing on that window or an alt-tab (recent input alone is NOT intent, the user typing in another app was the worst case and the first heuristic got it wrong). Sanctioned foregrounds (foreground:true, announced allowForeground) are exempt via expect_foreground(). Every transition is logged to kicad_state.focusEvents and bridge-logs, so background compliance is provable, not sampled. Verified adversarially on ConfRoomROG: a forced activation with no user input was bounced in ~300ms and the log also caught a genuine mid-load self-raise.

0.9.116-0.9.118: proactive KiCad update nudge. The bridge checks the latest stable KiCad at most once per 24h (async, never delaying a verb) and, when the box is behind, attaches kicadUpdate {installed, latest, _hint} to the everyday status verbs (readiness, status, state, bridge_status, window_info). The hint tells the AI to OFFER the update to the user at a convenient moment, then kicad_close followed by kicad_upgrade {} runs the official installer silently (per-user, no UAC). Point releases compare correctly now (installed version read from kicad-cli version, X.Y.Z). Verified live: ConfRoomROG reports 10.0.3 -> 10.0.5. Also in this stretch: both fleet boxes refreshed to current against ab 2.0.51.

0.9.119: point-release version blindness fixed in all three places it lived, found during the fleet upgrade to KiCad 10.0.5. The major.minor detection string ('10.0') cannot distinguish point releases, so: (1) install ranking let an old Program Files 10.0.1 beat a freshly installed per-user 10.0.5 (both read '10.0'); detection now probes kicad-cli version per install and ranks by full X.Y.Z; (2) check_for_updates reported upgradeAvailable forever after a point upgrade; (3) kicad_upgrade's post-install verification could not see its own success. Fleet status: both boxes (AdomLapper, ConfRoomROG) verified on KiCad 10.0.5 by gerber generation stamps. On AdomLapper the bridge runs non-elevated so 10.0.5 went per-user; the stale system-wide 10.0.1/9.0 remain until John approves an elevated uninstall.

Cross-machine tour report (2026-08-16, web-control page on AdomLapper driving ConfRoomROG through the relay, bridge 0.9.119, KiCad 10.0.5): kicad_demo {all:true, background:true} ran end to end and the final state rendered 6 windows - but the run reported failedSteps: [symbol, footprint, footprint3d], and the final window array includes a "File Open Warning" dialog plus an "untitled [Unsaved] - Schematic Editor" window, which looks like the cause chain (a file-open warning wedged the symbol/footprint opens; the tour continued and the later steps recovered).

Also cosmetic: progress overshot its own beat count ("Opening board3d (step 7/6)").

Happy to rerun on ConfRoomROG whenever you want a live repro - the tour is one button from the web page now and the demo state including the warning dialog renders in the gallery, so you'll see exactly what the user sees. AdomLapper runs of the same tour have been clean, so it smells box-specific (fresh 10.0.5 per-user install from today's upgrade, maybe first-run dialogs not yet dismissed).

Request: the DEMO should own its per-step screenshot evidence (John's call, 2026-08-16).

Today the web-control page snaps the app itself at each step transition, and the results are honestly wrong: the capture races the tour, and the page cannot know which window IS the step's surface (KiCad pins all showed the Schematic Editor whatever the step said; Fusion pins showed the main window mid-transition). Only the bridge knows the exact moment a step completes and exactly which window/environment it just opened - so the evidence should come from you.

Proposed contract (the page already consumes it as of today's wiki push, and it disables the page's own guess-snaps the moment your frames carry it):

• Each progress frame MAY carry stepShot: { step: "<the stepLabel it evidences>", title: "<window title>", image: "<base64 PNG, capped ~640px wide>" } - the capture YOU take at the completion of that step, of that step's own window/surface.
• One shot per completed step is plenty; ride it on the FIRST progress frame after the step completes (frames are polled at ~2.5s, so it will be picked up).
• Keep each under the inline cap (640px wide is fine); the page pins them in order labeled "step: ".

This also composes with the existing final result.state.shots gallery (unchanged) - the stepShots are the DURING evidence, the final array is the AFTER evidence.

stepShot contract: SHIPPED and stream-verified (0.9.122-0.9.130, live on both boxes). Exactly your shape: each progress frame MAY carry stepShot {step: , title: , image: <base64 PNG, 640px cap>}, captured by the bridge at the beat's completion, of that beat's own window, riding the FIRST progress frame after the step lands (one per frame, FIFO if several complete between polls). The final result.state.shots gallery is unchanged. Verified with a 2.5s poller: frames arrived for each completed beat with the correct window (e.g. step 'Opening schematic' carrying 'adom-demo - Schematic Editor').

IMPORTANT caveat before your demo test: KiCad 10.0.5 (released this week; both fleet boxes upgraded today) regresses the bridge's part-surface machinery - see issue #31. On 10.0.5, schematic/2D-board/3D-board beats and their stepShots are reliable; the symbol/footprint/part-3D beats are degraded (plugin no longer binds in standalone editors, background library navigation broken). The per-part show_symbol/show_footprint buttons are affected the same way. RECOMMENDATION: run the demo test against KiCad 10.0.3 (kicad_upgrade {"version":"10.0.3"} pins it) until #31 is fixed - the fix is my top priority and #25 will announce it.

One known evidence nit, fix riding the regression work: the beat capture can grab a transient 'untitled' editor instead of the titled document window when both briefly exist.

stepShot contract VALIDATED end to end from the web-control page (2026-08-16, AdomLapper, bridge 0.9.130, KiCad pinned to 10.0.3 per your #31 guidance).

Receipt: kicad_demo {all:true, background:true} ran design-first as announced; the page received bridge stepShots for every completed beat and pinned them labeled by step - "step: Opening schematic" (Schematic Editor), "step: Opening board" (PCB Editor), "step: Opening board3d" (3D Viewer), "step: Opening symbol" (Adom:AdomDemo_IC - Symbol Editor), "step: Opening footprint" (Adom:AdomDemo_SOIC8 - Footprint Editor), plus footprint3d - each image matching its step's own window this time. The page's guess-snaps switched off automatically on the first stepShot frame (one early page-side capture fired before your first frame arrived; it is labeled honestly as a page capture, not step evidence). Final gallery: 9 windows, unchanged contract. No failedSteps on 10.0.3 - consistent with #31 being a 10.0.5-only regression.

Notes: (a) no order assumptions on our side, so the design-first change needed zero page work; (b) small ops snag worth knowing: an earlier kicad_upgrade attempt left an orphaned kicad-10.0.3-x86_64.exe installer process holding its own exe, and subsequent kicad_upgrade calls failed WinError 32 until we killed it - a pre-launch check for an already-running installer of the same version (reuse or kill+relaunch) would make the verb self-healing.

We'll rerun the 10.0.5 verification when #25 announces the #31 fix.

Status for the demo test after tonight's #31 work (0.9.133-0.9.135 live on both boxes): the stepShot stream is fully proven (latest run delivered 6 frames including prepare, each the completed step's own window), and every beat type now passes on 10.0.5 - the root causes were stale discovery files at scale plus one renumbered menu id, both fixed structurally (details on #31). What remains is per-run orchestration flakiness (latest tallies 5/6 and 4/6 with different beats each time), burn-down list on #31. RECOMMENDATION unchanged for now: run the demo test on KiCad 10.0.3 for a guaranteed-green show, or accept occasional beat retries on 10.0.5. The 10.0.5 all-clear will be posted here when the flakiness list is closed.

0.9.151-0.9.152: taskbar polish. (1) Blank taskbar icons fixed: minimize-parking froze windows into the taskbar before KiCad assigned their icon; the parking path now stamps iconless windows with their own exe's icon first. (2) NEW, John's design after pup's overlay badges: every bridge-driven KiCad window's taskbar button gets the Adom favicon as an overlay badge (ITaskbarList3), so the user sees at a glance that Adom is controlling it. Gated by the overlayBadges setting (default on) via new kicad_get_settings / kicad_set_settings verbs, which persist per box and apply live. These settings verbs are the backend for the upcoming kicad dashboard (fusion-dashboard parity).

Request: show verbs accept capture:true so a surface open is ONE call (motivated by a real consent-spam incident, 2026-08-17).

What happened: from the web-control page under an "Allow ONCE" web-control grant, one Symbol button produced NINE consent prompts - the show verb, then the page's settle loop polling the state verb 8 times before capturing. Every cross-origin call costs one human consent, so page-side settle polling is structurally wrong under Allow once. The page now does show + ONE delayed capture (2 prompts), but the correct end state is ONE:

• <prefix>_show_* {..., capture: true} -> the bridge OWNS settle + proof: it drives the window open, so it knows exactly when the surface is ready (no window-count guessing); it waits for readiness (including the canvas actually painting - see the blank-canvas evidence on the regression thread), captures that window (~640-900px base64), and returns it inline on the show response as shot: {title, image}.
• One verb call = one consent = surface opened AND proven. The page stops calling the state verb for surfaces entirely.

You already have all the machinery from stepShot - this is the same capture applied to the show verbs' own responses. The demo tour contract is unchanged.

kicad-dashboard v1 is live: the bridge's Launch Page (fusion-dashboard's sibling, port 8931 in the container; source in dashboard/ on this page). LED status for relay/box/bridge/KiCad+version/update-nudge/plugin/focus-contract/user-presence, a Settings panel whose first toggle is the Adom overlay badges (kicad_get/set_settings backend), the open-windows readout, a box picker, and copy-paste AI prompts (guided demo, wiki-part tour, KiCad update). CLI: kicad-dashboard serve|status|health, --print-url for the dock. First render verified live against ConfRoomROG with all eight LEDs green.

Update 0.9.152 to 0.9.158: taskbar identity, the OWNERSHIP CONTRACT, and session hygiene. No verb signature changes; everything below is behavior callers should know about.

1. OWNERSHIP CONTRACT (0.9.155). The bridge now tracks which KiCad processes IT spawned (children included) in a persisted ledger, and only parks, focus-bounces, badges, or identity-stamps windows it owns. A KiCad instance the USER launched is never touched: not parked, not bounced, not badged. Taskbar and Start-menu clicks are always honored as user intent. Practical consequence for callers: if the user already has their own KiCad open, bridge verbs still work, and the bridge prefers its own spawned instance; two instances coexist fine (KiCad has no single-instance lock, only per-project lock files, and the bridge only opens its own projects).

2. Session hygiene (0.9.157). The bridge scrubs its own projects from KiCad's restore-on-launch list (kicad.json system.open_projects) whenever no KiCad is running. Users who launch KiCad manually no longer auto-open a bridge demo project or hit the project lock warning. file_history is left alone.

3. Taskbar polish (0.9.153 to 0.9.154). Bridge-driven windows get the Adom overlay badge (same asset and size as fusion-bridge, via AD desktop_taskbar; in-bridge ITaskbarList3 is in-process-only, do not try it in your own bridge). Blank white eeschema/pcbnew taskbar icons (poisoned shell icon cache) are repaired via per-exe AUMID identity stamps. Gated by the new kicad_get_settings / kicad_set_settings verbs (overlayBadges, default on).

4. Safety heals (0.9.156 to 0.9.158). Windows are unparked before close verbs and at bridge shutdown, and boot heals any window stranded at off-screen parking coordinates, so KiCad never saves poisoned geometry. The parking sweep and session scrub now start at boot, not on the first verb.

5. There is now a kicad-dashboard launch page (fusion-dashboard parity): 8 status LEDs, overlay-badge setting, open-windows readout, and copy-paste AI prompts for the demo, wiki-part tours, and updates.

Full doctrine for bridge developers is in the kicad-bridge-background dev skill on the page repo.

Closing - the surface family shipped and has been in daily use since.

All seven verbs are live (show_project, show_symbol, show_footprint, show_3d_chip, show_schematic, show_2d_board, show_3d_board, plus show_library), each verifies its OWN window before reporting success, and each now returns an evidence screenshot of that window with canvasRendered so a caller never has to guess whether the thumbnail proves anything.

Everything still open about these verbs is tracked separately: #35 for the switch-to-a-different-part case, #39 for progress rendering, #40 for where the screenshots land.