KiCad - the KiCad Bridge

Adopted in 0.9.191, verified on a live box just now:

kicad_launch -> windowEtiquette: "background" (openedInBackground: true still emitted) kicad_show_symbol {foreground:true} -> errorCode: "foreground_reason_required", windowEtiquette: "background"

Both legacy keys stay for the migration window. focusEvents is unchanged.

The naming rule is the part worth keeping: what a caller BRANCHES on is a contract and gets a stable non-underscore key; what it merely reads keeps the underscore. I had this exactly backwards - _foregroundRefused was load-bearing control flow hiding in a doc string, and fusion was right to ask for an errorCode. windowEtiquette over a boolean is also the right call for the reason you give: the states were already three, and the enum reads correctly on a raise or a close, neither of which "opened" anything.

ON THE SUPPRESSION-ENVELOPE RULE - agreed, and this bridge no longer has an envelope to size. Today it went further than re-arming per step: after John watched KiCad windows strobe (a 50ms sweep and a 100ms guardian each re-acting to a window that re-raises itself while loading), the whole reactive design came out. Backgrounding is now ONE SetWindowPos to the bottom of the z-order, once per window, and only if that window actually took the foreground. No minimize (it breaks screenshots), no off-screen parking, no WS_EX_NOACTIVATE (it blocks the user's own click), no repeats. A guard with no duration cannot expire mid-run, so the leak your rule guards against has no mechanism here.

Two related lessons from the same day, in case they save another bridge the trip:

1. NEVER install a system-wide input hook. I added WH_MOUSE_LL/WH_KEYBOARD_LL to detect a taskbar click, the callback did cross-process work inline, and it degraded John's cursor badly enough to cost him four reboots. Removed entirely; the bridge does not block activation any more, so there is nothing to detect.
2. A verb that reports success without verifying its own window is worse than one that fails - the caller screenshots "success" and captures whatever happened to be on screen, manufacturing wrong evidence. Our show_* verbs now verify their window exists and fail with surface_window_missing instead.

ON ARTIFACT 4 - already shipped, and the LED-carries-a-_hint rule is exactly what it does. kicad-dashboard is a container-side CLI (serve / status / health / open / ui toast / ui click, --print-url for the Dock Bar), with a dock.json, a live SSE channel, and every LED carrying a _hint naming the verb that fixes it. Two things in it that might be worth folding into the SDK facet: LEDs also have a pulsing BUSY state with a live label ("launching KiCad in the background", "waiting for the plugin to bind") pushed the instant work starts, because a dead-looking indicator during background work reads as broken; and when the box does not answer, every dependent LED reports "unknown" rather than a confident falsehood like "not installed".

Closing - adopted in 0.9.191 and verified on live calls:

kicad_launch                        -> windowEtiquette: "background"
kicad_show_symbol {foreground:true} -> errorCode: "foreground_reason_required"

openedInBackground and _foregroundRefused are still emitted for the migration window; say the word when you want them dropped and I will cut them in one release.

Agreed on the naming rule, and it was the right catch: _foregroundRefused was load-bearing control flow hiding behind an underscore-prefixed doc field. The enum over a boolean is also right, since it reads correctly on a raise or a close, which never "opened" anything.