KiCad - the KiCad Bridge

@@ -41,7 +41,8 @@ use kicad_core::libraries::{self, LibCtx}; use kicad_core::windows_model as wm; use kicad_core::windows_model::{DialogAction, WindowKind}; use kicad_core::{ab, bridge_log, kicad_common, pcm};-use kicad_platform::{native, unsupported, WindowInfo};+use kicad_core::window_memory::{self, Restore};+use kicad_platform::{native, unsupported, Placement, WindowInfo};  // ── Catalog ─────────────────────────────────────────────────────────────────── @@ -52,9 +53,10 @@ pub static VERBS: &[Verb] = &[         mechanism: Mechanism::Window, risk: "process", timeout_sec: 130,         input: "{\"project\"?: \"C:/.../x.kicad_pro\", \"waitSeconds\"?: 15, \"traceMasks\"?: \"KICAD_...\"}",         example: "kicad_launch {}",-        hint: "Idempotent: no-op with a hint if KiCad is already up. Opens in the BACKGROUND (no focus steal). Optional project: path to a .kicad_pro.",+        hint: "Idempotent: no-op with a hint if KiCad is already up. Opens in the BACKGROUND (no focus steal). Optional project: path to a .kicad_pro. Each window is put back on the monitor the user last had it on (placementRestored says what moved); a rect on a monitor that is no longer connected is left alone.",         related: &["kicad_open_editors", "kicad_window_info", "kicad_readiness", "kicad_upgrade"],-        pitfalls: &["first launch on a fresh install can show a setup wizard; kicad_window_info self-heals benign dialogs"],+        pitfalls: &["first launch on a fresh install can show a setup wizard; kicad_window_info self-heals benign dialogs",+            "placement memory is per window KIND (hwnds do not survive a restart) and lives in ~/.adom/kicad-bridge-placement.json; a box that has never run KiCad under the bridge has none, so the first launch lands wherever Windows puts it"],     },     Verb {         name: "kicad_open_board",@@ -267,7 +269,7 @@ pub static VERBS: &[Verb] = &[         mechanism: Mechanism::Window, risk: "write", timeout_sec: 200,         input: "{\"footprints\"?: [\"Lib:Name\", ...], \"force\"?: bool, \"confirmRestart\"?: bool}",         example: "kicad_rescan_libraries {\"footprints\":[\"Adom:LQFP-48_STM32G431\"]}",-        hint: "Wiki #51: install N parts, call this once, then show them all. Pass footprints so the reply can say what KiCad can load now; without the list nothing is verified. A restart (force) refuses while any KiCad runs unless confirmRestart:true, because the native build cannot yet tell a user-launched KiCad from its own (the ownership ledger arrives with phase 4).",+        hint: "Wiki #51: install N parts, call this once, then show them all. A restart closes KiCad gracefully first (so it saves its own geometry) and puts every window back on the monitor the user had it on (wiki #48; closeHow and placementRestored report both). Pass footprints so the reply can say what KiCad can load now; without the list nothing is verified. A restart (force) refuses while any KiCad runs unless confirmRestart:true, because the native build cannot yet tell a user-launched KiCad from its own (the ownership ledger arrives with phase 4).",         related: &["kicad_install_footprint", "kicad_show_footprint", "kicad_list_footprints"],         pitfalls: &["KiCad 10 caches footprint libraries per process; the tree refresh reveals parts installed after the editor started (measured 2026-09-07), a full restart is only for the cases it does not."],     },@@ -610,6 +612,71 @@ fn first_of_kind(kind: WindowKind) -> Option<u64> {     windows_of_kind(kind).first().map(|w| w.hwnd) } +/// Wiki #48: learn where the user keeps each KiCad window, per window KIND, so a restart can+/// put it back. Called before anything the bridge does that destroys geometry (a restart, a+/// close) and whenever the inventory is in hand anyway. Minimized and parked windows teach+/// nothing, so they are skipped.+pub(crate) fn remember_placement() -> usize {+    let now = utc_stamp();+    let mut mem = window_memory::load();+    let mut learned = 0;+    for w in kicad_windows() {+        let kind = w.kind();+        if matches!(kind, WindowKind::Dialog | WindowKind::Other) {+            continue;+        }+        // placement() reports the NORMAL rect plus the maximized flag, which is what has to+        // come back; the enumerated rect is the fallback where that call is unavailable.+        let place = native().placement(w.hwnd).unwrap_or(Placement {+            x: w.rect.0, y: w.rect.1, width: w.rect.2, height: w.rect.3, maximized: w.maximized,+        });+        if window_memory::observe(&mut mem, kind.as_str(), &place, w.minimized, &now) {+            learned += 1;+        }+    }+    if learned > 0 {+        if let Err(e) = window_memory::save(&mem) {+            eprintln!("[placement] could not save the placement memory: {e}");+        }+    }+    learned+}++/// Wiki #48: put each window back where the user had it, without activating it. A fresh+/// KiCad process places every window on the PRIMARY display, which is how a multi-monitor+/// user's PCB Editor kept coming back to the laptop panel. Returns one row per window so the+/// caller's reply can say what moved and what was left alone.+pub(crate) fn restore_placement() -> Vec<Value> {+    let mem = window_memory::load();+    if mem.is_empty() {+        return Vec::new();+    }+    let mut out = Vec::new();+    for w in kicad_windows() {+        let kind = w.kind();+        let Some(remembered) = mem.get(kind.as_str()) else { continue };+        let r = &remembered.place;+        let current = match native().placement(w.hwnd) {+            Ok(p) => p,+            Err(e) => {+                out.push(json!({"window": kind.as_str(), "hwnd": w.hwnd, "moved": false, "error": e}));+                continue;+            }+        };+        let on_monitor = native().on_a_monitor((r.x, r.y, r.width, r.height)).unwrap_or(false);+        match window_memory::decide(r, &current, on_monitor) {+            Restore::Skip(why) => out.push(json!({"window": kind.as_str(), "hwnd": w.hwnd, "moved": false, "why": why})),+            Restore::Move(p) => match native().set_placement(w.hwnd, &p) {+                Ok(()) => out.push(json!({"window": kind.as_str(), "hwnd": w.hwnd, "moved": true,+                    "to": {"x": p.x, "y": p.y, "width": p.width, "height": p.height, "maximized": p.maximized},+                    "rememberedAt": remembered.at})),+                Err(e) => out.push(json!({"window": kind.as_str(), "hwnd": w.hwnd, "moved": false, "error": e})),+            },+        }+    }+    out+}+ fn find_project_manager() -> Option<u64> {     kicad_windows().iter().find(|w| wm::is_project_manager(&w.title, w.owner)).map(|w| w.hwnd) }@@ -1424,11 +1491,15 @@ pub(crate) fn launch(state: &mut State, args: &Value) -> Value {     }     let log_path = log.as_ref().map(|p| norm(p));     if !windows.is_empty() {+        // Wiki #48 ask 2: a cold spawn on a box that has run KiCad before lands on the monitor+        // the user last used, not on whatever Windows defaults to.+        sleep_ms(1200);+        let restored = restore_placement();         return json!({             "success": true, "launched": true, "pid": pid, "mechanism": "spawn",             "windows": windows.iter().take(10).map(|w| w.title.clone()).collect::<Vec<_>>(),             "output": format!("KiCad launched; {} window(s) up.", windows.len()),-            "logPath": log_path,+            "logPath": log_path, "placementRestored": restored,             "_hint": "Launched in the BACKGROUND (no focus steal). First run on a fresh install may show a setup wizard; kicad_window_info self-heals benign dialogs; kicad_screenshot_all shows every window if something looks stuck.",             "_next": ["kicad_window_info", "kicad_open_editors", "kicad_open_board"],         });@@ -1713,7 +1784,13 @@ fn open_symbol_editor_inner(info: &KicadInfo, args: &Value, symbol_name: &str, l         });     }     let title = title_of(frame);-    let stale = symbol_on_disk(info, symbol_name) && !rescan;+    // Wiki #54, #71 (the 0.9.287 staleVeto, ported): an editor THIS call opened indexed the+    // libraries after the library file was last written, so its cache cannot be stale. Saying+    // library_cache_stale there sends the caller to rescan:true, which only closes and reopens+    // an already fresh editor and burns the budget again. The verdict is navigation_failed.+    let on_disk = symbol_on_disk(info, symbol_name);+    let editor_is_ours = mechanism != "existing";+    let stale = on_disk && !rescan && !editor_is_ours;     if stale {         let ctx = lib_ctx(info);         let paths = libraries::adom_paths(&ctx);@@ -1733,6 +1810,11 @@ fn open_symbol_editor_inner(info: &KicadInfo, args: &Value, symbol_name: &str, l         "error": format!("Symbol Editor open but '{symbol_name}' didn't load in the background after two attempts (title: {})", if title.is_empty() { "unknown".into() } else { title.clone() }),         "_hint": "Two background attempts did not confirm, so a third is unlikely to help - check that the symbol really exists in this library. The keystroke fallback (allowFocusSteal) is not in the native build; pass foreground:true with a foregroundReason to bring the editor to the user and let them load it.",     });+    if on_disk && editor_is_ours {+        v["symbolInLibraryFile"] = json!(true);+        v["staleVeto"] = json!(format!("this call opened the Symbol Editor itself ({mechanism}), so it indexed the libraries after the library file was last written: the index cannot be stale, and rescan:true would close and reopen an already fresh editor"));+        v["_hint"] = json!("The symbol IS in the Adom library file and this call opened the editor itself, so the index is fresh: this is a navigation failure, not a stale cache, and rescan:true cannot help. Read navigation.steps and navigation.treeCandidates (zero candidates means Enter reached no window, worth reporting with the trace), then pass foreground:true with a foregroundReason to hand the editor to the user.");+    }     merge(&mut v, wm::resolved_fields(&title, library_name, "Symbol Editor"));     v }@@ -2151,6 +2233,9 @@ fn close_one(st: &mut CloseState, w: &Win) -> Option<bool> { fn close_kicad(_state: &mut State, args: &Value) -> Value {     let force = args.get("force").and_then(Value::as_bool).unwrap_or(false);     let discard = args.get("discardChanges").and_then(Value::as_bool).unwrap_or(false);+    // Wiki #48: a close is the last moment these windows exist, so learn where they are+    // before the geometry is gone. A kill in particular denies KiCad its own save.+    remember_placement();     if force {         return match force_kill_kicad() {             Ok(k) if !k.is_empty() => json!({"success": true, "output": format!("Force-killed: {}", k.join(", ")), "data": {"forceKilled": k}}),@@ -2974,10 +3059,25 @@ fn rescan_libraries(state: &mut State, args: &Value) -> Value {             "runningPids": running.iter().map(|p| p.pid).collect::<Vec<_>>(),             "_hint": "Ask the user whether KiCad may be restarted, then call again with force:true and confirmRestart:true. Without force the verb refreshes the open editors' trees in place, which is enough for footprints installed after the editor started."});     }+    // Wiki #48: a fresh process places every window on the primary display, so the user's+    // monitor choice is captured here, while the windows still exist, and restored below.+    let remembered = remember_placement();+    let mut close_how = "nothing was running";     if !running.is_empty() {-        let closed = dispatch(state, "kicad_close", &json!({"force": true})).unwrap_or_else(|| json!({}));+        // Wiki #48 ask 3: graceful first, so KiCad writes its own geometry and its own files;+        // the kill is the fallback for a window that will not go.+        let mut closed = dispatch(state, "kicad_close", &json!({})).unwrap_or_else(|| json!({}));+        close_how = "graceful";         if !closed["success"].as_bool().unwrap_or(false) {-            return json!({"success": false, "errorCode": "restart_close_failed", "close": closed});+            if closed["errorCode"] == json!("unsaved_changes") {+                return json!({"success": false, "errorCode": "restart_close_failed", "close": closed,+                    "_hint": "KiCad is asking whether to save the user's work, so nothing was closed or killed. Ask them, then save (or call kicad_close {\"discardChanges\": true}) before restarting."});+            }+            closed = dispatch(state, "kicad_close", &json!({"force": true})).unwrap_or_else(|| json!({}));+            close_how = "force-kill after the graceful close failed";+            if !closed["success"].as_bool().unwrap_or(false) {+                return json!({"success": false, "errorCode": "restart_close_failed", "close": closed, "closeHow": close_how});+            }         }         std::thread::sleep(std::time::Duration::from_secs(4));     }@@ -2989,8 +3089,12 @@ fn rescan_libraries(state: &mut State, args: &Value) -> Value {         std::thread::sleep(std::time::Duration::from_millis(750));         invalidate();         if !kicad_windows().is_empty() {+            sleep_ms(1200); // let the fresh windows settle before moving them+            let restored = restore_placement();+            let moved = restored.iter().filter(|r| r["moved"] == json!(true)).count();             return json!({"success": true, "restarted": true, "ready": true, "method": "process-restart",-                "_hint": "Library caches rebuilt. Every part installed before this call is now visible; show verbs will not trigger another restart until the next install-while-open."});+                "placementRemembered": remembered, "placementRestored": restored, "closeHow": close_how,+                "_hint": format!("Library caches rebuilt. Every part installed before this call is now visible; show verbs will not trigger another restart until the next install-while-open. Placement: {moved} window(s) put back where the user had them (wiki #48), without activating anything.")});         }     }     json!({"success": false, "restarted": true, "ready": false, "errorCode": "restart_no_window",