Fusion - the Fusion 360 Bridge

@@ -18,6 +18,13 @@ So the old verbs are gone. `fusion_search_cloud_files` and `fusion_walk_cloud_tr **hard-blocked** and return a refusal that carries live APS state and points at `fusion_aps_search`. APS is not an optimization here, it is the only cloud-search path. +These are the team's Fusion cloud files, the folders and projects APS indexes (a Molecule project+expanded, with its schematic, board and 3D previews). Walking this panel folder by folder through+Fusion's Data API took **30+ minutes** on a real hub; `fusion_aps_search` queries the same files,+same account, in about **2 seconds**.++![The team's Fusion cloud files that APS indexes and searches](fz-cloud-files.png)+ ## It never costs money  Two independent guarantees, both enforced in code:

@@ -28,6 +28,14 @@ Measured on a real assembly:  The kit-aware counts match Fusion's own **Manage -> BOM**. +Below is a real Adom mechanical assembly, the 4040 T Plate, open in the Design workspace (captured+with Fusion in the **background**). It is an aluminum T-plate with 5 BHCS M8x16 on top and 5 T Nut+Eco 4040 M8 underneath. Running `fusion_assembly_bom` on it returns exactly that kit-aware list, **3+parts across 11 instances** (plate x1, BHCS_M8x16 x5, T Nut Eco 4040 M8 x5), which is what a flat+occurrence walk would over-count.++![The 4040 T Plate mechanical assembly open in Fusion's Design workspace](fz-bom.png)+ ## `fusion_assembly_bom`  Structured, kit-aware BOM for the active assembly. Recurses organizational subassemblies, but

@@ -24,6 +24,14 @@ adom-desktop fusion_aps_open '{"query":"BQ25792"}'    # resolves + opens the pro adom-desktop fusion_show_schematic '{}'               # switch to the schematic editor ``` +Below is a real Adom board's schematic, the BME690 environmental-sensor Molecule, open in the Fusion+Electronics schematic editor after exactly those two calls. The parts are live and net-connected: the+BME690 sensor, its decoupling caps, the I2C pull-ups, and the JP1 breakout header, with the layer set+(Nets, Busses, Pins) on the right. This whole capture was taken with Fusion in the **background**, it+never came to the foreground.++![BME690 Molecule schematic in the Fusion Electronics schematic editor](fz-schematic.png)+ ## `fusion_show_schematic`  Switches the active electronics design into the schematic editor. Pairs with

@@ -76,6 +76,17 @@ Fusion sign-in and [APS](aps-cloud-search.md) are both Autodesk logins. They can warm browser SSO session**. So APS consent runs right after a Fusion sign-in while that session is warm, and `fusion_readiness` reports APS state on every launch. The user should authenticate once. +## Active sessions++An Autodesk seat allows a limited number of concurrent sessions. When the account is already signed+in elsewhere, Fusion blocks startup with an **Active Sessions Exceeded** dialog listing the other+machines. It is a hard modal, nothing proceeds until it is answered, so the bridge treats it like any+blocking dialog: read it, then **suspend the stale session** ("Suspend Fusion on the computer+selected below and continue on this computer") rather than blind-clicking a default that could sign+you out of a machine mid-work.++![Fusion's Active Sessions Exceeded dialog listing the other signed-in machine](fz-sessions.png)+ ## Automatic updates  Fusion ships updates constantly and nags with an "Update Now / Update Later" panel and a countdown.

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯

@@ -1,6 +1,6 @@ --- name: fusion-driving-description: How to SAFELY drive Fusion 360 through the Adom bridge across many steps without losing work - the discipline of reading the screenshot/owned-popup ARRAY after every mutating op and ANALYZING any dialog BEFORE the next step, never blind-dismissing, and never fullscreen-capturing (it forces foreground and disrupts the user). Includes the blocking-dialog catalog with the CORRECT response for each, and how the bridge now returns the dialog array + an analyze-this hint automatically. Read this BEFORE running any multi-step Fusion automation (attaching 3D, saving libraries, closing docs, modeling scripts). Trigger words - drive fusion, fusion dialog, blocking dialog, are you sure you want to close, packages are being uploaded, save was cancelled, ownedPopupCount, screenshot array, owned popups, fusion notification, lower right error, dismiss dialog, fusion modal, fusion_screenshot_all, fusion_window_info, fusion_check_dialogs, fullscreen capture fusion, analyze before proceeding.+description: How to SAFELY drive Fusion 360 through the Adom bridge across many steps without losing work - the discipline of reading the screenshot/owned-popup ARRAY after every mutating op and ANALYZING any dialog BEFORE the next step, never blind-dismissing, and never fullscreen-capturing (it forces foreground and disrupts the user). Includes the blocking-dialog catalog with the CORRECT response for each, and how the bridge now returns the dialog array + an analyze-this hint automatically. Read this BEFORE running any multi-step Fusion automation (attaching 3D, saving libraries, closing docs, modeling scripts). Trigger words - drive fusion, fusion dialog, blocking dialog, are you sure you want to close, packages are being uploaded, save was cancelled, ownedPopupCount, screenshot array, owned popups, fusion notification, lower right error, dismiss dialog, fusion modal, fusion_screenshot_all, fusion_window_info, fusion_check_dialogs, fullscreen capture fusion, analyze before proceeding, foreground vs background, does driving fusion foreground it, run fusion in the background, background screenshot, foreground fusion, focus steal, capture fusion without raising it, drive fusion while user works. ---  # Driving Fusion 360 safely (read the popup array, never fly blind)@@ -20,6 +20,47 @@ lose these changes. Are you sure you want to close?"* The automation was sleepin `dismiss_blocking_dialogs` loop, which clicked straight through it - **closing the library before it ever saved. All 10 attaches were lost.** Every rule below is the fix for one beat of that failure. +## Background by default: what foregrounds Fusion, and what does not++The whole bridge is built so you can drive Fusion **while it stays in the background** and the user+keeps working in their foreground app. This is deliberate, and it works. The add-in runs *inside*+Fusion on its main thread and manipulates the document, view and workspace through the Fusion API,+which changes state **without activating or raising the window**. Captures use `PrintWindow`/WGC,+which grab the exact window even when it is occluded or minimized. So opening designs, switching to+the schematic/board/3D view, running scripts, exporting, and screenshotting are **all background**.++> ⚠️ Learned the hard way (2026-07-24): an AI refused to grab Fusion screenshots because it+> *believed* driving Fusion for a screenshot would foreground it and disrupt the user. **It does+> not.** Driving Fusion through the add-in + hwnd capture never raises the window. Do not repeat that+> mistake, and do not tell the user Fusion has to come to the front to be captured.++**Background (safe, never disturbs the user):**+- **Open files:** `fusion_aps_open`, `fusion_open_lbr`, `handle_open_cloud_file` / `_by_urn`.+- **Change view or workspace via the add-in:** schematic, 2D board, 3D PCB, Design/Manage,+  `fusion_show_2d_board`, `fusion_show_3d_board`. These switch through the API and do NOT raise the+  window.+- **Run the add-in:** `fusion_run_modeling_script`, `fusion_execute_text_command` / `electron_run`,+  every export, BOM, parameters, `fusion_attach_3d_package`, `fusion_close_document`.+- **Capture by hwnd:** `fusion_screenshot_all`, `fusion_screenshot_fusion`,+  `desktop_screenshot_window {hwnd}` (PrintWindow/WGC, occlusion-independent, works minimized).+- **Dismiss a dialog in the background:** `fusion_close_window {hwnd}` (WM_CLOSE via PostMessage, no+  focus steal).++**Foreground (raises Fusion / steals focus, use only deliberately):**+- **`fusion_start`** - launching Fusion brings it up. This is the one legitimate foregrounding action+  (it is the boot).+- **`fusion_send_key`, `fusion_click_fusion`** - OS-level input injection calls `SetForegroundWindow`+  to deliver the key/click, which yanks Fusion to the front (caught 2026-06-29). Prefer the add-in+  API or `close_window` over synthetic input for anything you can express that way.+- **`desktop_screenshot_screen`** (whole-desktop capture) - screen-DC capture forces the target+  toward the foreground AND often grabs the wrong window. Never use it on Fusion (see Rule 2).+- Any explicit OS window activation (`SetForegroundWindow`, focus/raise verbs).++**The rule:** anything expressed through the **add-in API** or an **hwnd-targeted capture** is+background; only **synthetic input** (`send_key`/`click`), **whole-screen capture**, and the+**initial launch** foreground Fusion. Reach for the API path first; fall back to input injection only+when there is no API for it, and expect that to surface the window.+ ## Rule 1 - after EVERY mutating op, READ the popup array. Then analyze. Then proceed.  A mutating op = anything that changes Fusion's state: `fusion_run_modeling_script`,