Fusion - the Fusion 360 Bridge

{
 "rules": [
  {
   "needles": [
    "skiawindowcontextdx12",
    "unrecoverable d3d12"
   ],
   "category": "fusion_gpu_device_lost",
   "resolution": "Fusion Electronics lost its D3D12 graphics device (SkiaWindowContextDx12): the canvas stops drawing and goes black, and the bridge cannot fix it. This is a graphics driver or display problem, not the router. OK is the only button. Save the open documents, restart Fusion, and update the graphics driver; on the machine in page issue #121 it happened only with DisplayLink (USB) displays attached, so move Fusion to a monitor wired to the GPU or unplug those adapters."
  },
  {
   "needles": [
    "unexpected condition",
    "pusher.cpp"
   ],
   "category": "fusion_unexpected_condition",
   "resolution": "Fusion Electronics asserted inside its own router (seen when a LINE completes a net's last airwire on some boxes, pusher.cpp inLocator). OK is the only button and is informational; the copper already landed. Click OK, then CHECKPOINT the board (fusion_export_eagle_source) before doing anything else, and verify the copper with fusion_routing_state; do not assume the edit was lost or applied."
  },
  {
   "needles": [
    "board file has errors",
    "opened with warnings"
   ],
   "category": "board_opened_with_warnings",
   "resolution": "Fusion opened a board file that has errors, and OK is the only answer: it's a notice, not a question, and nothing is saved or lost. fusion_dismiss_blocking_dialogs clicks OK. Read the board before trusting it. A board converted by a bridge before 1.13.61 can have a stack with no through via: fusion_routing_state lists any invalidViaNets, and fusion_set_layer_count at the same count repairs them."
  },
  {
   "needles": [
    "has errors and cannot be opened",
    "close the empty design file without saving"
   ],
   "category": "lbr_open_error",
   "resolution": "Fusion could not parse the library file. Click OK, close the leftover empty Untitled design WITHOUT saving, and fix the FILE - as of 1.9.128 fusion_open_lbr refuses unparseable libraries up front (lbr_invalid) so this modal should never appear for a bridge-issued open; a raw caller-staged file can still trip it."
  },
  {
   "needles": [
    "uploaded to your fusion hub",
    "packages are being uploaded",
    "being uploaded",
    "lose these changes"
   ],
   "category": "upload_in_progress",
   "resolution": "DATA LOSS RISK. Fusion is still uploading 3D package(s) to the Hub. Do NOT click Yes / do NOT close - you will LOSE the uploaded packages and any unsaved bindings. Click No, then WAIT and poll until the upload finishes before closing or saveAs. See the fusion-cloud-save skill."
  },
  {
   "needles": [
    "cannot be saved while packages",
    "save was cancelled",
    "save cancelled"
   ],
   "category": "save_blocked_by_upload",
   "resolution": "saveAs was refused because 3D packages are still uploading to the Hub (this also throws InternalValidationError). Not fatal: wait for the upload to drain, then retry the saveAs and poll past it. See the fusion-cloud-save skill."
  },
  {
   "needles": [
    "needs to update",
    "update is available",
    "software update",
    "new update"
   ],
   "category": "update_nag",
   "resolution": "Fusion is prompting to update itself. Do NOT auto-confirm (it can start an update mid-automation). Dismiss it on the desktop or let Fusion update, then retry. A pending update is also a common cause of AdomBridge add-in crashes (add-in/host version drift), so clearing it often fixes those too."
  },
  {
   "needles": [
    "select electronics design",
    "multiple electronics design",
    "linked to multiple"
   ],
   "category": "linked_design_picker",
   "resolution": "This file links to multiple Electronics designs. The chooser is a CEF/web modal whose list is NOT keyboard- or Win32-navigable (SendInput reaches only the native Cancel/OK), so it can't be resolved headlessly today — select the design on the desktop. (Headless fix tracked: have the add-in open the specific linked design via the Fusion API, avoiding the picker entirely.)"
  },
  {
   "needles": [
    "recovery",
    "recover unsaved",
    "document recovery"
   ],
   "category": "recovery",
   "resolution": "Document Recovery prompt. Call fusion_dismiss_recovery, or fusion_relocate_recovery BEFORE fusion_start to prevent it."
  },
  {
   "needles": [
    "save changes",
    "save document",
    "do you want to save",
    "unsaved changes",
    "save"
   ],
   "category": "save_changes",
   "resolution": "Unsaved-changes prompt. Use fusion_close_document (closes without the save modal), or fusion_dismiss_blocking_dialogs, which answers No."
  },
  {
   "needles": [
    "what do you want to design",
    "what to design"
   ],
   "category": "what_to_design",
   "resolution": "Fusion's start picker. fusion_dismiss_blocking_dialogs closes it."
  },
  {
   "needles": [
    "create new footprint",
    "create new symbol",
    "create new device",
    "create new package",
    "create new library"
   ],
   "category": "create_confirm",
   "resolution": "Fusion is asking whether to CREATE an artifact we asked to open, which means the name does not exist in the library. Answering 'Yes' invents an empty artifact and hides the real problem, so the bridge answers NO and reports the missing name. Fix the NAME (fusion_show_* refuses up front with `available` listing what the .lbr actually holds)."
  },
  {
   "needles": [
    "caused fusion to close unexpectedly",
    "fusion error report",
    "a software problem has caused",
    "close unexpectedly"
   ],
   "category": "crash_report",
   "resolution": "Fusion CRASHED. The bridge closes this and relaunches Fusion - the add-in only loads at launch, so a relaunch is the only way back to drivable."
  },
  {
   "needles": [
    "session suspended",
    "suspended this session",
    "suspended by:"
   ],
   "category": "session_suspended_regrab",
   "resolution": "This box's Autodesk session was SUSPENDED by another machine taking the seat. The bridge clicks 'Check again' to regrab it (background UIA). Never click 'Shut Down' - that signs this box out."
  },
  {
   "needles": [
    "grid",
    "display style dots lines",
    "finest",
    "altdistance"
   ],
   "category": "settings_dialog_cancel",
   "resolution": "A Fusion electronics SETTINGS dialog (e.g. Grid) is open and blocking. It carries no data - Cancel it (WM_CLOSE / Cancel). Nothing we drive opens these deliberately; if it keeps recurring, something is injecting a stray GRID/settings command or keystroke."
  },
  {
   "needles": [
    "active sessions exceeded",
    "more active sessions",
    "more sessions running than are allowed",
    "sessions running than are allowed"
   ],
   "category": "session_conflict_decision",
   "resolution": "DECISION DIALOG - do NOT auto-pick. This Autodesk seat is already active on another machine; the options SUSPEND or SHUT DOWN Fusion THERE (risking that machine's unsaved work). fire a notify_user and ASK the user which option they want, then click it. (Suspend = pausable/resumable; Shut down = saves the other machine's work to a recovery file.)"
  },
  {
   "needles": [
    "suspend remote session"
   ],
   "category": "session_suspend_confirm",
   "resolution": "Confirmation of a chosen 'suspend the OTHER machine's Fusion'. Only click Continue if the user ALREADY chose suspend; otherwise Go Back and ASK. Never auto-confirm a seat action."
  },
  {
   "needles": [
    "fusion is already open",
    "multiple instances are not supported",
    "launch another fusion instance"
   ],
   "category": "already_open",
   "resolution": "Fusion is ALREADY running - a second launch was attempted. Click CANCEL (never Launch): Fusion is a singleton and the running instance is the one to drive. This usually means a prior fusion_stop/kill did not fully clear the old process before relaunch."
  },
  {
   "needles": [
    "welcome to fusion",
    "signing in - autodesk",
    "sign in - autodesk"
   ],
   "category": "signin_required",
   "resolution": "Autodesk sign-in needed (first run). NOTIFY the user, drive the 'Sign In' button (desktop_ui_click), fetch any email OTP via adom-google, and after the browser shows \"You're signed in\" click its 'Open Product' button - but NEVER auto-enter the password/2FA. See fusion-aps-signin."
  },
  {
   "needles": [
    "error launching streamed application",
    "missing or incomplete",
    "please re-install",
    "re-install the application"
   ],
   "category": "launch_error",
   "resolution": "Launch error from an INCOMPLETE webdeploy folder (missing FusionLauncher.exe.ini). Safe to dismiss (OK/close) - it is only an acknowledgement. Launch the COMPLETE production folder (the hash dir that HAS FusionLauncher.exe.ini); detect_fusion now prefers it."
  },
  {
   "needles": [
    "error",
    "cannot be opened",
    "has errors",
    "failed to",
    "could not",
    "invalid"
   ],
   "category": "operation_error",
   "resolution": "The last operation FAILED - Fusion is showing an Error dialog (the API call may still have returned ok because it opened an EMPTY design). READ the dialog screenshot for the exact message. Common case: '<file>.lbr has errors and cannot be opened' = the library is malformed (re-lint/regenerate; a frequent cause is a single UNNAMED symbol pin - EAGLE <pin name=''> + <connect pin=''> - name the pin from the KiCad pin NUMBER). The bridge already flipped success to False and dismissed the empty design; FIX the source file and retry. Do NOT report success."
  }
 ],
 "sets": {
  "FAILURE": [
   "operation_error"
  ],
  "DECISION": [
   "session_conflict_decision",
   "session_suspend_confirm"
  ],
  "AUTO_DISMISS": [
   "already_open",
   "crash_report",
   "create_confirm",
   "launch_error",
   "settings_dialog_cancel"
  ],
  "RELAUNCH": [
   "crash_report"
  ],
  "LAUNCH": [
   "already_open",
   "launch_error",
   "session_conflict_decision",
   "session_suspend_confirm",
   "signin_required"
  ]
 },
 "generic": {
  "category": "generic_modal_read_screenshot",
  "resolution": "Generic Fusion modal - its body is not Win32-readable, so a screenshot is attached: READ it and ANALYZE before acting. Do NOT blind-dismiss. If it mentions uploading / 'lose these changes' / 'sure you want to close' -> click No and wait for the Hub upload to drain (fusion-cloud-save). If it is the 'Select Electronics Design File' chooser during an open, its list is not keyboard/Win32-navigable; open the specific design by URN or select on the desktop."
 },
 "unknown": {
  "category": "unknown",
  "resolution": "Unrecognized modal - a screenshot is attached: READ it and ANALYZE before acting. Do NOT blindly dismiss (some modals lose work if confirmed wrong). Identify it from the screenshot, then take the work-preserving action."
 }
}