Adom Hydrogen (platform base)

@@ -1,390 +0,0 @@-----name: hd-bridges-description: >-  Complete reference for the HD bridge ecosystem: the built-in KiCad, Fusion 360,-  and Puppeteer bridges, plus the extensible wiki bridge catalog (e.g. Blender)-  and the full set of Adom Desktop capabilities. How they connect through adom-desktop, the Bridge Manager-  dialog, bridge status polling, and all bridge CLI commands. Use when the AI-  needs to take screenshots, control KiCad/Fusion/browser, transfer files,-  interact with the user's desktop, or check bridge status. Trigger words ---  screenshot, desktop screenshot, list windows, capture screen, kicad, fusion,-  browser, puppeteer, pup, send file, pull file, notify, desktop, bridge,-  bridge manager, bridge status, bridge install.------# Hydrogen Desktop -- Bridge Ecosystem--HD is the bridge between your WSL2 workspace (Docker only under `HD_RUNTIME=docker`) and the user's Windows desktop.-All commands go through the relay at ws://localhost:8765/.-------## Bridge Architecture--HD launches external bridge processes **on demand**. This is an **extensible**-ecosystem, not a fixed list — new bridges ship via the wiki catalog (see-"Extensible bridge catalog" below). The core/first-party bridges:--| Bridge | Display name | Port (default) | Target app | Description |-|--------|-------------|------|------------|-------------|-| `kicad-bridge` | KiCad Bridge | 8771 | KiCad | Control KiCad PCB editor from Adom containers |-| `fusion-bridge` | Fusion 360 Bridge | 8773 | Fusion 360 | Control Fusion 360 CAD/CAM and EAGLE PCB |-| `puppeteer-bridge` | Puppeteer Bridge | 8851 | Chrome for Testing | Chrome automation, screenshots, and recording |--**Bridge ports have conventional defaults** (KiCad **8771**, Fusion **8773**, Pup **8851**), but adom-desktop registers the **live** port at bridge launch and may pick a different one if a default is taken. To find the actual live port, run `adom-desktop status` and look at `desktop.apps.<bridge>.bridgePort` (or `adom-desktop bridge_list`). In practice you don't need the port directly — use the `adom-desktop <verb>` CLI which routes to the right bridge automatically.--Bridges are launched on demand by HD. They are NOT always running. The Bridge-Manager polls status every 15 seconds via Tauri `invoke('get_bridge_status')`.--### What Adom Desktop can do (live capability list)--Bridges are only part of AD. Query the **authoritative, machine-specific** list:--```bash-adom-desktop status   # → .capabilities  and  .desktop.apps-```--On a typical machine `.capabilities` =-`notify, files, kicad, fusion360, shell, usb, screenshot, browser, caption, record`.-Mapping to where each is documented:--| capability | what it is | skill |-|---|---|---|-| `kicad` / `fusion360` / `browser` | the three built-in app bridges | this skill |-| `screenshot` / `record` / `caption` | OS screenshots, screen/tab recording, recording captions | this skill (screenshots/recording); `caption` is recording-caption support |-| `files` | send_files / pull_file | **hd-file-transfer**, **hd-adom-desktop** |-| `notify` | desktop toast notifications | this skill |-| `shell` | run a command on the user's PC (approval-gated) | **hd-adom-desktop** |-| `usb` | USB passthrough to the workspace (e.g. workcell hardware over USBIP) | not yet covered — query `adom-desktop status`; future skill |--> `.desktop.apps` also reports, per app: `bridgeRunning`, `installed`, `running`,-> `version` — use it to check whether the target app (KiCad/Fusion/Chrome) is-> present before driving its bridge.--### Bridge status values--| Status | Meaning | Icon | Color |-|--------|---------|------|-------|-| `running` | Bridge process is alive and connected | `mdi:circle` (filled) | `#00b8b0` (teal) |-| `stopped` | Bridge exists but not running | `mdi:circle-outline` | `#808080` (gray) |-| `not_installed` | Bridge binary not found | `mdi:download` | `#e8a838` (amber) |--### BridgeInfo type--```typescript-interface BridgeInfo {-    name: string           // e.g. "kicad-bridge"-    display_name: string   // e.g. "KiCad Bridge"-    version: string        // e.g. "1.0.0"-    description: string-    port: number           // conventional default; live port via `adom-desktop status`-    status: 'running' | 'stopped' | 'not_installed'-    app_detected: boolean  // true if target app (KiCad, Fusion, Chrome) is found-    app_name: string       // e.g. "KiCad"-    install_url: string    // e.g. "https://www.kicad.org/download/"-    install_method: string // "free_download" or "auto_download"-}-```-------## Bridge Manager Dialog--**Access**: Adom menu (top-left logo) -> Desktop section -> Bridge Manager-**Source**: `src/lib/components/editor/BridgeManager.svelte`--Renders as a panel (not an overlay dialog) with a vertical card list showing-each bridge's status. Auto-refreshes every 15 seconds.--### Features-- Status badges with color-coded icons-- Per-bridge install links when the target app is missing-- "Browse Bridge Catalog" button linking to the wiki (`/apps?tag=hd-bridge`)-- Polls `invoke('get_bridge_status')` on mount and every 15 seconds--> **App missing? You can auto-install it.** When the target app isn't installed,-> the dialog shows an install link — but the AI doesn't have to stop there. For-> KiCad and Node.js you can trigger an **unattended winget install** instead of-> asking the user to download:-> `adom-desktop desktop_install_kicad '{}'` / `adom-desktop desktop_install_node '{}'`.-> (Fusion 360 cannot be installed programmatically — surface the link for that.)--### CSS selectors--| Element | Selector |-|---------|----------|-| Container | `.bridge-manager` |-| Header title | `.bridge-manager .header h2` |-| Subtitle | `.bridge-manager .subtitle` |-| Bridge card grid | `.bridge-grid` |-| Bridge card | `.bridge-card` |-| Running bridge card | `.bridge-card.running` |-| Bridge icon | `.bridge-icon` |-| Bridge name | `.bridge-name` |-| Bridge version | `.bridge-version` |-| Bridge description | `.bridge-description` |-| Bridge status | `.bridge-status` |-| App missing link | `.bridge-app-missing a` |-| Browse catalog button | `.browse-btn` |--### CDP eval examples--```javascript-// Read bridge statuses-JSON.stringify(Array.from(document.querySelectorAll('.bridge-card')).map(function(card) {-  return {-    name: card.querySelector('.bridge-name')?.textContent?.trim(),-    status: card.querySelector('.bridge-status')?.textContent?.trim(),-    running: card.classList.contains('running')-  };-}));--// Click Browse Bridge Catalog-document.querySelector('.browse-btn')?.click();-```--### Opening the Bridge Manager from the Adom menu--```javascript-// Open Adom menu, then click Bridge Manager-document.querySelector('.logo-button')?.click();-setTimeout(function() {-  var items = document.querySelectorAll('.dropdown-link');-  Array.from(items).find(function(e) { return e.textContent.includes('Bridge Manager'); })?.click();-}, 200);-```-------## Prerequisites--Check connection: `adom-desktop ping` -- returns "pong" if HD is connected.-If not connected, the user needs to launch HD on their Windows machine.-------## Screenshots (zero dialogs, instant)--```bash-# Full screen capture-adom-desktop desktop_screenshot_screen--# Resized for Claude vision (default to this)-adom-desktop desktop_screenshot_screen '{"maxWidth": 1500}'--# Specific window by HWND-adom-desktop desktop_screenshot_window '{"hwnd": 12345}'--# List all capturable windows-adom-desktop desktop_list_windows-```--**AI guidance:**-- Default to `maxWidth: 1500` -- Claude vision hard limit is 2000px-- Use `format: "png"` for UI/text (default, lossless)-- Use `format: "jpeg", quality: 80` for photos/3D renders-- Use `format: "webp"` for smaller file sizes-------## Browser Automation (Puppeteer Bridge)--Port: default **8851** (adom-desktop registers the live port; see `adom-desktop status`). Auto-downloads Chrome for Testing if not present.--```bash-# Open browser window-adom-desktop browser_open_window '{"url": "https://example.com"}'--# Screenshot current tab-adom-desktop browser_screenshot '{"sessionId": "default"}'--# Evaluate JavaScript-adom-desktop browser_eval '{"js": "document.title", "sessionId": "default"}'--# Navigate-adom-desktop browser_navigate '{"url": "https://...", "sessionId": "default"}'--# List open windows/tabs-adom-desktop browser_list_windows--# Record tab (CDP screencast, zero dialogs)-adom-desktop browser_record_start '{"sessionId": "default"}'-adom-desktop browser_record_stop '{"sessionId": "default"}'-```-------## KiCad Bridge--Port: default **8771** (adom-desktop registers the live port; see `adom-desktop status`). Requires KiCad to be installed on the user's Windows machine.--```bash-adom-desktop kicad_open_board '{"path": "C:\\path\\to\\board.kicad_pcb"}'-adom-desktop kicad_open_schematic '{"path": "C:\\path\\to\\schematic.kicad_sch"}'-adom-desktop kicad_open_3d_viewer-adom-desktop kicad_run_drc '{"path": "..."}'-adom-desktop kicad_screenshot_all-adom-desktop kicad_window_info-adom-desktop kicad_send_key '{"key": "ctrl+s"}'-adom-desktop kicad_list_versions-adom-desktop kicad_install_symbol '{"path": "/tmp/symbol.kicad_sym", "library": "MyLib"}'-adom-desktop kicad_install_library '{"path": "/tmp/footprints", "name": "MyFootprints"}'-```--**Always run `kicad_window_info` BEFORE any KiCad operation** to check for modal dialogs —-and AFTER any save/DRC/open to catch errors KiCad raised.--### Finding + reading KiCad errors (modal dialogs)-`kicad_window_info` returns `hasModalDialogs` (bool) + a `modalDialogs` array — **this is how-you detect a KiCad error/blocking dialog** (a save-permission error, a file-format warning, a-DRC blocker). Each entry is `{hwnd, ownerHwnd, title}` (e.g. `title:"Error"`):--```bash-adom-desktop kicad_window_info '{}'-# → { editors:[...], hasModalDialogs:true,-#     modalDialogs:[{ "hwnd":200934, "ownerHwnd":6163368, "title":"Error" }], projectManager:{...} }-```-- ⚠️ `modalDialogs` gives the **title + hwnd, NOT the body text**. To read *what the error says*,-  **screenshot the dialog by its hwnd**: `adom-desktop desktop_screenshot_window '{"hwnd":200934}'`-  → read the saved PNG. (Verified live 2026-06-15: a `ctrl+s` on a read-only board surfaced-  `hasModalDialogs:true` + a `title:"Error"` entry; screenshotting its hwnd read *"Insufficient-  permissions to save file …"*.)-- **Dismiss** it before proceeding: `kicad_send_key '{"hwnd":<dialog hwnd>,"key":"return"}'`-  (OK) or `"escape"` (Cancel). A lingering modal blocks every subsequent KiCad action.-- So the loop is: **operate → `kicad_window_info` → if `hasModalDialogs`, screenshot each-  `modalDialogs[].hwnd` to read it → handle/dismiss.** Don't assume an operation succeeded just-  because the verb returned `success:true` — KiCad can still pop a blocking error.-------## Fusion 360 Bridge--Port: default **8773** (adom-desktop registers the live port; see `adom-desktop status`). Requires Fusion 360 to be installed on the user's Windows machine.--```bash-adom-desktop fusion_start-adom-desktop fusion_import_step '{"path": "C:\\path\\to\\model.step"}'-adom-desktop fusion_export_step '{"path": "C:\\path\\to\\output.step"}'-adom-desktop fusion_board_info-adom-desktop fusion_electron_run '{"command": "..."}'-```-------## Extensible bridge catalog (bridges are NOT a fixed set)--Bridges are a growing ecosystem. The three above (KiCad / Fusion 360 / Puppeteer)-are **built into Adom Desktop**. Additional bridges are published to the **wiki-bridge catalog** and installed on demand — for example the **Blender bridge**-(`adom-blender-bridge`), which is NOT built in (it won't appear in `adom-desktop-status` until installed). To use a catalog bridge:--- **Discover:** Bridge Manager → "Browse Bridge Catalog" → wiki `/apps?tag=hd-bridge`.-- **Reserved ports:** the `8900-8999` range is set aside for 3rd-party bridges.-- **Enumerate what's actually live:** `adom-desktop status` → `desktop.apps.*` lists-  every bridge AD currently knows about, with `bridgePort`, `status`, and whether-  the target app was detected. **Treat that as the source of truth** for "what-  bridges exist right now" — this skill's table lists the core ones, but new-  catalog bridges will appear in `status` without being in this table.-- **Invoke any bridge** through the `adom-desktop <verb>` CLI; it routes to the-  right bridge automatically (you rarely need the port directly).--> Maintainer note: keep this skill in sync by periodically running-> `adom-desktop status` against a fully-bridged machine and reconciling the table.-------## File Transfer--```bash-# Send file from the workspace to the Windows desktop-adom-desktop send_files '{"filePaths": ["/home/adom/project/output.pdf"], "saveTo": "C:\\Users\\john\\Downloads"}'--# Pull file from Windows into the workspace-adom-desktop pull_file '{"filePaths": ["C:\\Users\\john\\Downloads\\data.csv"], "saveTo": "/tmp"}'-```-------## Desktop Interaction--```bash-# Toast notification-adom-desktop notify_user '{"title": "Build", "body": "Build complete!", "level": "info"}'--# Open URL in user's browser-adom-desktop desktop_open_url '{"url": "https://..."}'--# Open folder in Explorer-adom-desktop desktop_open_folder '{"path": "C:\\Users\\john\\project"}'--# Execute shell command (requires user approval)-adom-desktop shell_execute '{"command": "dir C:\\Github"}'-```-------## Screen Recording--> **Served by the embedded AD process, NOT HD's built-in bridge.** The-> `desktop_record_*` / `desktop_recorder_*` verbs only exist when the standalone-> AD (spawned `--embedded`) is connected. Verify before using:-> `adom-desktop status` → `.capabilities` must include `record`. If it's absent,-> only HD's built-in bridge is up and these verbs return "unknown desktop-> command". See **hd-recording** for full details.--> **Tab-vs-desktop footgun.** `desktop_record_start` records the **whole screen**-> and requires an explicit `confirmDesktopNotTabRecording:true` guard so you don't-> accidentally capture the entire desktop when you meant one tab. To record a-> single Chrome tab, use `browser_record_start` instead (CDP screencast, served by-> the Puppeteer bridge, no whole-screen capture).--```bash-# Record entire desktop (AD-served; needs the confirm guard, zero dialogs)-adom-desktop desktop_record_start '{"reason": "Demo recording", "confirmDesktopNotTabRecording": true}'-adom-desktop desktop_record_stop--# Record a single browser tab (CDP screencast, zero dialogs) — prefer this for one tab-adom-desktop browser_record_start '{"sessionId": "default"}'-adom-desktop browser_record_stop '{"sessionId": "default"}'-```-------## Ralph Loop Pattern--```bash-# 1. Take screenshot-adom-desktop desktop_screenshot_screen '{"maxWidth": 1500}'-# 2. Read the screenshot (it's saved to /screenshots/)-# 3. Analyze with Claude vision-# 4. Make changes-# 5. Take another screenshot-# 6. Repeat until done-```-------## Browser Profiles--HD can detect all browser profiles installed on the user's machine and open-URLs in specific browsers/profiles.--**Control API endpoints**:-- `GET /browser-profiles` -- detect Chrome, Edge, Brave, Firefox, Opera profiles-- `POST /open-in-profile` -- open URL in a specific browser and profile-- `POST /open-url` -- open URL in the default browser--**Source**: `src/lib/components/BrowserProfileDialog.svelte`-------## Cross-references--- **hd-ui** -- Adom menu layout where Bridge Manager lives-- **hd-networking** -- port architecture (conventional bridge ports + dynamic registration)-- **hd-adom-menu** -- the API Explorer (has bridge-related endpoints)-- **hd-settings** -- HD settings surface-- **hd-self-screenshot** -- host screenshots, window control, and the ralph loop-- **kicad-interaction** -- foundational KiCad desktop interaction rules-- **pup** -- Puppeteer browser control via pup CLI