zfinix/aster/aster-ui-demo

Demo UI work in the real surface

Never build a standalone HTML mockup to show a UI idea. Users judge UI by clicking the real product, and a mockup cannot answer the only questions that matter: does it work, does it match the surrounding design, does it survive real data.

The workflow

1. Build it for real. Implement the change in the actual frontend source,

even when the user only asked to "see it first". For this repo that means editors/vscode/webview/ (shared webview used by both the VS Code panel and the browser harness) or desktop/ for Tauri surfaces.

1. Serve it in the browser harness. From editors/vscode/, run

bun run dev:web (builds the webview, then runs out/devhost/main.js, a real browser-runnable host with a stubbed vscode API). The devhost is a long-lived server: never run it directly through run_command, or the tool hangs until the process is killed. Fire and forget through a shell:

``sh bash -lc "cd editors/vscode && bun run dev:web > /tmp/devhost.log 2>&1 &" ``

Note the port (default 4327). If the port does not come up, read /tmp/devhost.log in a later round instead of chaining a wait onto the start command.

1. Click through it yourself first. Use browser automation to exercise the

feature before the user sees it: open the panel, trigger the feature, resize narrow (300px) to check layout. Fix what breaks.

1. Open it for the user. Use open_preview on the harness URL so they can

click through the running app. State plainly that it is the real surface, running in a browser host.

1. Run the real checks before calling it done: bun run test (vitest) in

editors/vscode/, and make check or scoped cargo test -p aster-cli for Rust changes.

Reporting

Reference real files with line numbers, describe behavior the user can trigger by clicking, and note anything the browser harness cannot reproduce (native menus, real extension API calls) so the user knows what still needs testing in the actual editor.

Why not mockups

A mockup gets one reaction ("looks fine") and then the work is thrown away. The real build gets the same reaction plus every real bug found before the feature ships. The mockup path only wastes the turn it saves.