webview-uat

Web Client UAT

Input: client acceptance criteria, installed revision, the host under test (machine-local browser, hosted phone app, or both), configured auth and provider state, and a session scratch directory.

Compose generic UAT. The client is one bundle every host mounts, so a criterion is proven in a browser first and in an editor only when the editor host itself changed. Prepare the runtime with the flywheel-uat driver: bun run uat:tui start makes the isolated HOME, clones the effective profile's credentials by the shared credential contract in scripts/uat/harness.ts (auth.json, optional profile.json, and a token-free reference for each Claude login, which a Claude sign-in criterion also uses), sets FLYWHEEL_AUTH_PROFILE, makes a scratch project with git init, and launches the installed binary rather than bun run dev. To test a build that is not your own installed one, install it with its staged install.sh under a scratch HOME with FLYWHEEL_INSTALL_DIR and FLYWHEEL_NO_MODIFY_PATH=1, then pass FLYWHEEL_INSTALLED_BINARY and --installation-home to start. Keep unix socket paths under 104 bytes: pass a short --scratch-root, through a symlink if the session scratch is deep.

Two hosts reach the client. For the machine-local browser, run bun run uat:tui web <handle>. It runs the installed flywheel web in the sandbox project with the sandbox HOME and environment and prints the hub address it opened; drive that address. The command finds or starts the account service, opens the project, and opens the account hub, which leads to the project listener with the project's browser token. Do not substitute a source preview page or bun run dev: they do not prove the installed machine-local browser path or its bundled webview payload. The person's own service holds the fixed hub http://127.0.0.1:41000/, so a sandbox never uses it: every sandbox launch carries the release harness's isolated hub environment, the sandbox's service binds an ephemeral hub port and writes its origin to <handle>/hub-origin, and flywheel web opens that origin. A flywheel web run by hand in the sandbox needs the same FLYWHEEL_INTERNAL_RELEASE_HARNESS, FLYWHEEL_INTERNAL_RELEASE_HUB_PORT=0, and FLYWHEEL_INTERNAL_RELEASE_HUB_RECORD=<handle>/hub-origin, or it refuses to open anything. The sandbox hub remains available while zero projects are open. For the hosted phone app, run the installed TUI in tmux with the same HOME and FLYWHEEL_TEST_SUPPRESS_AUTO_DIALOGS=1. Type /remote, press p, and rebuild the pairing link from the pane, which wraps it across lines; open the link in the browser pane at remote.flywl.sh, then select the machine. A device store is per origin and per installed app, so a Safari tab, a Home Screen app, and the browser pane each pair on their own. Navigating to a fragment on an origin the tab already shows changes the hash and never reloads, so reload the bare origin when the deployed bundle changed.

Set FLYWHEEL_TEST_SUPPRESS_AUTO_DIALOGS=1 on installed TUI launches used for account setup or sibling-terminal checks. Use 0 only for automatic-dialog criteria, as specified in flywheel-uat. This is a TUI launch setting, not a server, browser, or editor setting.

Drive the client through what a person touches. Command panel rows pick on mousedown, not click. Sheets open from the slash button's panel by row label and close through the header's Close button; a sheet that opens another sheet is a distinct path from the panel. The mobile preset emulates a coarse pointer and the desktop preset a fine one, so check both rungs of a control that has them. agent-browser screenshot saves to the current directory, which is the repository, unless it gets a path, so always pass an absolute path in the session scratch directory. The browser pane cannot screenshot while it is hidden; computed styles, bounding rectangles, document.activeElement, and the console still work, and the client reports every failed read through console.warn with the runtime's own error, so read the console before guessing. On macOS, agent-browser press and CDP key events can start a stream of trusted keydowns that does not end until the browser restarts; it starves the page's main thread, so timers, socket handling, and every timing observation after it are false. Drive keys a criterion does not name through the DOM: set the composer value, dispatch an input event, and call click() on the control. When a criterion needs a real key press, restart the browser after it and before any timing evidence. Send one bounded prompt when a criterion needs a turn, wait for the Stop button to leave, and read the transcript blocks by class. Record exact observations.