--- name: ai-driven-apps user-invocable: true description: >- How the AI builds, shows, drives, and tests an Adom app. In Adom the AI writes the app, shows it to the user (in their own already-signed-in native browser via Adom Desktop, in pup for the logged-out experience, or in a Hydrogen webview), drives the front-end over a live SSE or WebSocket channel to exercise every path (auto-click buttons, show and hide floaty toolbars, load a different symbol or footprint, click send-to-kicad), reads back state, console, and screenshots, and ralph-loops until the UI is right. Covers state-on-the-server, GET /state, GET /console, the live channel, the CLI driving commands, the three display surfaces and when to use each, and the ralph-test loop. Read BEFORE building or testing any Adom web app. Trigger words: ai-drivable, ai driven app, drive the front-end, drive the ui, live channel, SSE, server-sent events, websocket, GET /state, GET /console, ralph test, ralph loop, auto-click buttons, test the ui, show app in native browser, show app in pup, webview vs pup, native browser auth, logged out testing, ui click. --- # AI-driven apps This is the loop the whole Adom UI system is designed around. The AI is both the builder and the tester; the user watches and steers. An app is only as good as the AI's ability to drive and observe it, so build for that from the first commit. ## The loop 1. **The AI builds the app:** a small server plus a webview UI, made drivable from day one (state on the server, a live channel, a CLI). 2. **The AI shows it to the user** in one of three surfaces (below), chosen for what is being tested. 3. **The AI drives the front-end** over the live channel to exercise every path: click each button, open and close the floating toolbar, load a different symbol or footprint, hit send-to-kicad, and read back state, the console buffer, and screenshots. 4. **The AI ralph-loops:** screenshot, analyze what looks wrong, fix the code, reload, repeat, until the UI is correct and a pleasure to use. 5. **The AI narrates** through toasts and chat so the user can follow along. ## State on the server, observed two ways - **The server owns the truth.** The UI never keeps its own copy of "am I recording?" or "which symbol is loaded?". Buttons fire commands to the server; the server holds state. - **`GET /state`** returns the current state as JSON. The UI reflects it; the AI reads it to check progress without scraping HTML. - **`GET /console`** exposes the app's log: override `console.log/warn/error` to also post to the server, keep a ring buffer, and catch `window.onerror` and `unhandledrejection`. Now the AI reads what the UI is doing without DevTools. ## The live channel - Expose **Server-Sent Events** for one-way push, or a **WebSocket** for two-way. The UI subscribes and updates the instant anything changes; the CLI subscribes too. A 300 to 500ms poll of `GET /state` is the minimum fallback, but the live channel is what makes driving feel instant. - **Because the channel is two-way, the AI drives the front-end from the CLI.** Every user-visible action has a command that does exactly what the click does: ``` mytool ui click "send-to-kicad" # press a button mytool ui toolbar show # reveal the floating toolbar, then `hide` mytool ui load-symbol LM358 # swap the loaded symbol or footprint mytool ui toast "file downloaded" # raise a toast (also the AI's narration channel) ``` Each command drives the real UI through the same path a user click would, so the AI can walk every interaction, assert the resulting state, screenshot it, and move on. This is the test harness and the demo driver in one. - **Acceptance test:** an AI driving the app over the channel and a person clicking the UI produce identical visible results. ## The three display surfaces Pick the surface by what you need to test, and use more than one at once when it helps. | Surface | What it is | Use it for | |---|---|---| | **Native browser** (**nb**) | The user's own Chrome or Edge, driven through Adom Desktop | The real, signed-in experience. The browser is already the user's, so the app opens **logged in with zero friction**. Use it for anything behind a login. | | **pup** | A clean, scriptable Chrome the AI fully owns | The **fresh, logged-out, first-time-user** experience, and automated screenshot loops that should not fight the user's own tabs. | | **Hydrogen webview** | An in-workspace browser tab | Showing a result inside the workbench, next to the code and the chat. | | **hdbw** (HD Browser Window) | Under Hydrogen Desktop: a standalone Tauri browser window HD manages directly (window label `hd-browse-*`, destination id `webview-window`) | A dedicated app window beside the HD shell — bigger than a pane tab, still HD-managed. Note: the in-HD *pane tab* is the wv surface (the `webview` skill routes there inside HD). | ### VS Code's "Simple Browser" is NOT a surface **NEVER show an Adom app in VS Code's built-in "Simple Browser".** It is none of the Adom surfaces: no live channel, no console read-back, no AI drivability, wrong pane semantics. If you are about to paste an app URL into Simple Browser, stop and load the `webview` skill instead. ### Every app's SKILL.md must carry a display section (MANDATE) When you write or update an app's SKILL.md, include a section titled **"Displaying this app (REQUIRED)"** that (a) names the app's own show/open verb if it has one, (b) instructs loading the `webview` skill for manual display (pup / native browser / hdbw per the table above), and (c) states the Simple Browser ban verbatim. Skill discovery from trigger words alone is probabilistic; the app skill IS reliably loaded when the app is named, so it must carry the display rules itself. (Decision John 2026-07-17, after a fresh workspace showed adom-parts-search in Simple Browser.) The native-browser and pup split is the point: open the **logged-in path in the native browser** and the **logged-out path in pup** at the same time, and verify both. Tell the user which surface and why. ## Ralph-testing the UI The visual feedback loop that turns "it runs" into "it is right": edit, reload, drive a step over the channel, screenshot, read the console buffer, analyze, fix, repeat. Drive it in pup (or the native browser), capture each frame to the screenshot log, and loop until the UI looks and behaves correctly. This is how the AI debugs UI with no human in the loop, and it is the proof the app is genuinely drivable. ## Reaching a container app from outside - A webview and a browser window both render **outside** the container, so they cannot reach `http://localhost:` or `http://127.0.0.1:`. Always use the public proxy URL: `https://.adom.cloud/proxy//`. - **Inside a webview, always use relative URLs.** A leading slash bypasses the proxy and hits the wrong origin. Every `fetch`, `href`, `src`, and CSS `url()` must be relative. ## Boundary with app-creator (do not blur it) `adom/app-creator` owns CREATING the app: scaffolding, project layout, server + webview skeleton, wiring the first commit. THIS skill owns everything after: SHOWING the app, DRIVING its front-end, and RALPH-TESTING the UI until it is right. If you are adding "how to build/scaffold" content, it goes in app-creator; if you are adding "how to drive/verify/test the UI", it goes here. Keeping the line crisp is what stops the two skills drifting into contradictory duplicates. ## Related skills `app-creator` (scaffolding the app), `adom-screenshot` (the ralph loop and shotlog), `adom-cli-design` and `ai-hints-in-clis` (the CLI the driving commands live in), `toasts` (the narration channel), `app-shell` (the layout being driven), and `adom-ui-design` (the hub).