Availability probes (2 functions)
xsWebviewAvailable probe
Whether the current environment supports webview windows (Windows: WebView2 Runtime installed). Scripts use it to decide desktop-only behaviors.
xsWebviewVersion version
Backend version string (borrowed; NULL when unavailable). Window lifecycle stays host-owned in v1 — the app node manages it.
The app service node
A "class": "app" service node in xs.json = local HTTP service + webview desktop window:
- Startup: a loading splash shows first; the main window opens automatically once the service is ready
- Shutdown: closing the window triggers graceful shutdown (equivalent to Ctrl+C five-phase); with
window.close: "hide"the window is only hidden — a second launch wakes the existing window via single-instance detection - Fallback: environments without WebView2 Runtime degrade to headless automatically
- With single-file packing: after xs pack the product is a double-click desktop exe
Platform & variant degradation matrix
| build variant | platform | WebView2 | behavior |
|---|---|---|---|
| webview extension | Windows | Runtime installed | full functionality: loading window, auto-open on ready, close semantics |
| webview extension | Windows | Runtime missing | per install_fallback: ask prompts / silent installs quietly / headless degrades at once; any install failure lands on headless |
| webview extension | Linux | — (no window backend) | headless: the service runs as usual, the log prints [xs] app 'main': open http://127.0.0.1:<port>/ in a browser |
| no extension | any | — | same headless plus one line webview extension not built in, window ignored; the class: "app" config always parses (one xs.json across variants) |
The frontend is always best-effort: any window-thread failure (creation failure, missing Runtime, user declining the install, UI-thread exception) degrades to a log line and never pushes the engine assembly or shutdown chain onto the fail path — the window is the display layer, the service is the substance. The WebView2 renderer is a separate process; a page crash does not infect xs.
Field-by-field constraints for the nine window descriptor fields (title / width / height / min_width / min_height / url / devtools / close / install_fallback) are in the xs.json field reference · the app node; the port: 0 auto-assignment and stickiness semantics live there too.
docs/Webview扩展与app节点设计.md.