Adom Hydrogen (platform base)

@@ -1,141 +0,0 @@-----name: hydrogen-embedded-ad-description: How Hydrogen (ah) and Adom Bridge (ab) interact via "embedded mode". Use whenever the user asks about the system tray icon, why ab isn't visible, why two desktop apps are installed, the "Embedded · Hydrogen" footer pill, or how to make ab show up standalone. Trigger words — embedded mode, system tray, ab tray, why is adom desktop hidden, where's my tray icon, Hydrogen vs ab, both apps installed, why two installs, ad missing from tray, switch ab to standalone, ab won't show, run ab without Hydrogen, decouple ab from Hydrogen.------# Hydrogen ↔ ab Embedded Mode--There are two desktop apps in the Adom ecosystem: **Hydrogen (ah)** — the user-facing workspace app — and **Adom Bridge (ab)** — the bridge that talks to local apps (KiCad / Fusion 360 / Chrome / files). Hydrogen's installer silently installs ab (it fetches the latest ab from wiki.adom.inc at install time rather than carrying a copy) and runs it in **embedded mode**, where ab is invisible and Hydrogen's tray menu mirrors ab's controls.--This skill explains how the two interact so you can answer "why isn't ab in my tray?", "should I have two installs?", "why did the tray icon disappear?" and similar.--## Two modes--### Standalone ab (no Hydrogen anywhere)--How ab launches when nobody owns it:-- Tray icon visible in Windows notification area-- Main window opens on launch (unless `--start-hidden`)-- Autostart shortcut in `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\AdomDesktop.lnk` → launches on every boot-- Registered in Add/Remove Programs (HKLM `Uninstall\AdomDesktop`)-- Auto-update polls `wiki.adom.inc/api/v1/pages/adom-bridge-cli/files/version.json` every 4h-- Footer shows the user's email + a "Sign in" / "Sign out" link--This is what ab looked like before Hydrogen existed and what it reverts to when Hydrogen vanishes.--### Embedded ab (Hydrogen owns it)--Hydrogen's installer puts ab into embedded mode by:-1. Writing `%LOCALAPPDATA%\Adom Bridge\embedded.json` marker (`{"owner":"hydrogen-desktop", ...}`)-2. Deleting ab's Desktop / Start Menu / Startup `.lnk` shortcuts so the user can't double-launch standalone ab-3. Configuring Hydrogen's own systray to mirror ab's menu (Open ab, Connect All, Disconnect All, Settings, etc.)--When Hydrogen spawns ab with `--embedded --start-hidden --relay-url ws://127.0.0.1:8765 --relay-name hydrogen-desktop`, ab detects embedded mode and:-- **Hides** its system tray (Hydrogen owns the one tray)-- **Suppresses** its autostart shortcut creation-- **Disables** its auto-updater (Hydrogen owns ab's update channel — Hydrogen installs the latest published ab at install time)-- **Hides** its main window on boot (Hydrogen's tray "Open Adom Bridge" menu item opens it on demand)-- **Skips** HKLM Uninstall registration (Hydrogen's installer offers cascade-uninstall of ab)-- Footer shows a read-only email + an "Embedded · Hydrogen" pill--Result: the user only ever sees one app (ah) in the tray + Start Menu, even though two processes (Hydrogen + ab) are running.--## How ab detects "am I embedded?" — 3-signal cascade--ab calls `embedded::detect_embedded_mode()` at boot. First match wins:--1. **CLI flag**: `--embedded` (or `--embedded-mode`) on the command line. Writes the marker file, owner defaults to `hydrogen-desktop`. **This is what Hydrogen spawns ab with.**-2. **Env var**: `ADOM_EMBEDDED=1` (or `true`). Same behavior as the flag.-3. **Marker file**: `%LOCALAPPDATA%\Adom Bridge\embedded.json` exists. ab then probes Hydrogen's **liveness beacon** on `127.0.0.1:9001` (a real port ab listens for — NOT Hydrogen's control API; Hydrogen's actual control API is **47084**):-   - If Hydrogen answers the beacon → embedded mode-   - If Hydrogen doesn't answer → ab treats the marker as stale, deletes it, falls back to standalone--If none of the three signals fire → standalone.--## Lifecycle ownership in embedded mode--Hydrogen's runtime supervisor:-- Reads Hydrogen's session token from `%APPDATA%\hydrogen-desktop\hydrogen-session.txt`-- Spawns ab detached with the embedded flags above-- Polls ab's direct API `/health` every 5s (stable port 24680 since ab 2.0.27; discovery-file first)-- If ab's health probe fails → Hydrogen respawns ab with the same args--Hydrogen's tray menu (mirrors ab's controls so the user gets all the ab verbs without seeing ab's tray):-```-Open Hydrogen-Reload Workspace-── Adom Bridge ──-Open Adom Bridge      → POST 127.0.0.1:24680 desktop/window_show-Connect All            → POST desktop/connect_all-Disconnect All         → POST desktop/disconnect_all-Settings (Adom Bridge)→ POST desktop/window_show-─────-Quit                   → POST desktop/shutdown, 200ms grace, then app.exit(0)-```--Hydrogen's uninstaller PREUNINSTALL hook prompts "Also remove Adom Bridge?" → cascade-uninstalls ab on Yes.--## Runtime transitions--**ab ≥ v1.8.47** re-checks Hydrogen's liveness every 60s during runtime, not just at boot. This is the normal daily cycle for most users, not an edge case:--- Morning: user launches Hydrogen → Hydrogen spawns ab with `--embedded` → ab's tray hides, pill appears-- Evening: user quits Hydrogen → ab's next poll fails the Hydrogen probe → ab reverts to standalone → tray reappears-- Next morning: user launches Hydrogen again → ab's next poll succeeds → ab re-embeds → tray hides--The same ab process can flip mode back and forth indefinitely across an Hydrogen-quit / Hydrogen-relaunch cycle. Transitions:--| Current mode | Hydrogen probe says | What ab does |-|---|---|---|-| Standalone | dead | stay standalone (no-op) |-| Standalone | alive | → **embed**: hide tray, write marker, hide main window, show "Embedded · Hydrogen" pill |-| Embedded | dead | → **unembed**: show tray, delete marker, hide pill (main window left as-is) |-| Embedded | alive | stay embedded (refresh marker heartbeat in `last_seen`) |--Both transitions emit a `mode-changed` event so the frontend can update the footer pill in real time.--**ab ≤ v1.8.46** only checks at boot. If Hydrogen dies while ab is running, ab stays invisible in embedded mode until restart.--## Common questions--### "I don't see ab in my system tray on a Windows box with Hydrogen installed"--Expected. Hydrogen's installer deleted ab's autostart shortcut, so ab doesn't launch on boot. ab only runs when Hydrogen spawns it. Hydrogen's tray includes ab's menu items.--To verify: `tasklist | findstr adom-bridge-cli`. If ab's running, it's just hidden (per embedded mode). If not running, Hydrogen isn't either.--### "I want ab standalone — how do I unembed?"--- Quit Hydrogen-- Delete `%LOCALAPPDATA%\Adom Bridge\embedded.json`-- Launch ab via `%LOCALAPPDATA%\Adom Bridge\adom-bridge.exe`-- ab will detect no marker + no CLI flag → standalone mode → tray reappears--Or uninstall Hydrogen with "Yes, also remove Adom Bridge" → No → Hydrogen is gone, ab's marker is cleared, ab reverts to standalone on next launch. (Note: ab's autostart shortcut was deleted by Hydrogen's installer, so ab still won't auto-launch on boot until you re-run ab's installer to recreate it.)--### "Both Hydrogen and ab are installed — is that normal?"--Yes. Hydrogen's NSIS POSTINSTALL hook resolves the latest ab from wiki.adom.inc, verifies its published sha256, and silently runs that installer with `/S /NOLAUNCH`. If that can't happen (offline at install time), Hydrogen retries it on first launch. ab lives at `%LOCALAPPDATA%\Adom Bridge\`, Hydrogen at `%LOCALAPPDATA%\Hydrogen\`. Two separate exes, two separate Add/Remove Programs entries (well, only Hydrogen's is in Add/Remove if Hydrogen's installer ran the embedded-mode ab which skips HKLM register — ab ≥ v1.8.46).--### "ab's tray suddenly appeared even though Hydrogen is installed"--Hydrogen probably crashed or was closed. ab ≥ v1.8.47's runtime poll noticed Hydrogen is dead and reverted to standalone tray. The fix: relaunch Hydrogen from the Start Menu → ab's next poll detects Hydrogen → tray hides again.--### "Direct API for ab verbs"--ab listens on `127.0.0.1:24680` (stable since ab 2.0.27; legacy installs may still use 47200) for `POST /command` with `{"app":"desktop","command":"<verb>","args":{...}}`. The 7 user-visible verbs Hydrogen's tray uses:-- `window_show`, `window_hide`-- `connect_all`, `disconnect_all`-- `shutdown`-- `embedded_status` (returns `{embedded, owner, source, ...}`)-- `logout`--Port discovery order: `%USERPROFILE%\.adom\direct-api-port` (single line `host:port`, authoritative), then stable 24680, walk 24680-24689, legacy 47200-47209 last. Validate `service == "adom-bridge"` in /health before trusting a port.--## Source-of-truth references--- ab's mode detection: `adom-bridge-cli/src-tauri/src/embedded.rs:detect_embedded_mode()`-- Hydrogen's ab spawn: `hydrogen-desktop/src-tauri/crates/hydrogen-app/src/ad_supervisor.rs:spawn_ad_embedded()`-- Hydrogen's tray menu: `hydrogen-desktop/src-tauri/crates/hydrogen-app/src/tray.rs:install_tray()`-- Hydrogen's NSIS hook (embed-ab on install / offer-uninstall): `hydrogen-desktop/src-tauri/crates/hydrogen-app/installer/hydrogen-install.nsh.template`-- ab's release manifest (what Hydrogen reads at install time to find the latest ab): `wiki.adom.inc/api/v1/pages/adom-bridge-cli/files/version.json`