Suggested: a kicad_state verb that returns KiCad's full window state as a base64 screenshot array

Overview Files Skills Discover Packages Releases Dependencies Issues Breadcrumbs Pull Requests1 Activity

Closed feature request

John Lauer · 3mo ago ·closed by John Lauer

From John (2026-08-14), added to the Bridge SDK as a SUGGESTED pattern for every bridge that drives a windowed app.

The problem. A caller that wants to see KiCad today screenshots the first window whose title matches, and gets ONE window — but KiCad has at least two windows (the project manager plus the Symbol/PCB/Schematic editor). A generic title match cannot know the real set; only YOU, the bridge, do (you track your app's parent/child hwnds). So the screenshot a user or AI gets back is a cropped sub-window, not the app's real state. We hit this live in the web-control demo: the KiCad 'proof' screenshot was a single skinny panel instead of the whole app.

The suggestion: expose kicad_state (read-only, non-gated, cheap to poll) that returns KiCad's STATE OF THE UNION:

A screenshot ARRAY of EVERY window KiCad owns right now (all the parent + child/related windows), each captured by its real hwnd, returned as base64: { shots: [{ title, hwnd, image, width, height }] }. Base64 (not just file paths) is what lets a WEB page and an AI that cannot reach the desktop filesystem render them inline. File paths are fine to include too.
Plus the logical state you already know: which document/design/board is open, which editor is focused, whether a modal dialog is blocking, unsaved-changes flag, current tool — whatever a caller needs to decide the next move.

Why it matters. It turns 'drive blind and hope' into 'look, then act': an AI calls kicad_state before and after an action to confirm it landed, and a human demo shows KiCad's true state instead of one window. ab already has the generic pieces (desktop_list_windows + desktop_screenshot_base64 {hwnd}), and the web-control demo now stitches them client-side — but the BRIDGE produces the CORRECT set because it owns the window identities. That is exactly the ab-renders / bridge-knows-its-app boundary.

No rush and not a contract change — a suggestion. If you add it, name it kicad_state for consistency across bridges. Full text: the 'expose a <prefix>_state verb' section of the Bridge SDK (adom-bridge-sdk).

1 Reply

John Lauer · 3mo ago

Implemented in 0.9.87 as kicad_state — read-only, non-gated, and verified live just now:

success: true | running: true | windows: 2
shots[0]: "Device:C [Read Only Library] — Symbol Editor"  base64 PNG 480x270
shots[1]: "KiCad 10.0"                                    base64 PNG 480x351
editors: plugin inventory (kind/frameTitle/hwnd per editor) when a plugin is alive
modalDialogs: [...] + activeVersion

Shape per your spec: shots[] carries EVERY window KiCad owns (found by real hwnd via the process-verified enumerator from #23 — a browser tab can't sneak in), each as inline base64 PNG with width/height plus the host file path. Logical state rides along: the editors inventory, blocking modal dialogs, running flag, active version. Knobs: maxWidth (default 1100) caps image size; includeImages:false gives a cheap logical poll for tight loops. The verb's _hint teaches callers to render ALL shots and to poll before/after an action to confirm it landed.

It's in kicad_describe, the bridge.json verb list, and the daily verb suite (coverage-enforced with a shots-non-empty check). If the SDK wants this as the canonical <prefix>_state example for windowed-app bridges, happy for it to be lifted.

John Lauer closed this · 3mo ago