Harden WebUI API lifecycle contracts

Author: ItsMeSamey

README.md

@@ -94,6 +94,34 @@ flowchart LR
   F --> G["WebView window (OS)"]
 ```
 
+## Launch Policy (Deterministic)
+
+`AppOptions` now uses a single deterministic policy object:
+
+```zig
+pub const LaunchPolicy = struct {
+    preferred_transport: enum { native_webview, browser } = .native_webview,
+    fallback_transport: enum { none, browser } = .browser,
+    browser_open_mode: enum { never, on_browser_transport, always } = .on_browser_transport,
+    allow_dual_surface: bool = false,
+    app_mode_required: bool = false,
+};
+```
+
+Decision summary:
+
+| `preferred_transport` | Native backend available | `fallback_transport` | Active transport |
+|---|---|---|---|
+| `native_webview` | yes | any | `native_webview` |
+| `native_webview` | no | `browser` | `browser_fallback` |
+| `native_webview` | no | `none` | `native_webview` (error if render required) |
+| `browser` | any | any | `browser_fallback` |
+
+Browser opening summary:
+- `never`: never auto-launch browser.
+- `on_browser_transport`: launch browser only when active transport resolves to browser.
+- `always`: always launch browser; combine with `allow_dual_surface=true` for explicit dual-surface behavior.
+
 ## API At A Glance
 
 Core flow:
@@ -118,9 +146,11 @@ pub fn main() !void {
 
     var service = try webui.Service.init(gpa.allocator(), rpc_methods, .{
         .app = .{
-            .transport_mode = .native_webview,
-            .browser_fallback_on_native_failure = true,
-            .auto_open_browser = true,
+            .launch_policy = .{
+                .preferred_transport = .native_webview,
+                .fallback_transport = .browser,
+                .browser_open_mode = .on_browser_transport,
+            },
         },
         .window = .{ .title = "WebUI Zig" },
         .rpc = .{ .dispatcher_mode = .threaded },
@@ -167,6 +197,24 @@ Dispatch modes:
 - `threaded` (worker queue)
 - `custom` (hook dispatcher)
 
+Async jobs (push-first):
+- Set `RpcOptions.execution_mode = .queued_async`.
+- `POST <rpc_route>` returns `{ job_id, state, poll_min_ms, poll_max_ms }`.
+- Completion is pushed over WebSocket as `rpc_job_update`.
+- JS bridge waits for push first, then uses bounded polling fallback (`GET /rpc/job?id=...`).
+- Cancel route: `POST /rpc/job/cancel` with `{ "job_id": <id> }`.
+
+Typed APIs:
+- `Window.rpcPollJob(allocator, job_id) !RpcJobStatus`
+- `Window.rpcCancelJob(job_id) !bool`
+- `Service` mirrors both methods.
+
+Runtime introspection and diagnostics:
+- `Window.runtimeRenderState()` / `Service.runtimeRenderState()`
+- `Window.probeCapabilities()` / `Service.probeCapabilities()`
+- `Service.listRuntimeRequirements(allocator)`
+- `App.onDiagnostic(...)` / `Service.onDiagnostic(...)`
+
 ## Close Semantics (No Random Window Closes)
 
 Close is backend-authoritative:
@@ -197,6 +245,24 @@ Build outputs:
 - `zig-out/share/webui/runtime_helpers.embed.js`
 - `zig-out/share/webui/runtime_helpers.written.js`
 
+## Linux Runtime Requirements API
+
+You can query runtime packaging requirements before showing a window:
+
+```zig
+const reqs = try service.listRuntimeRequirements(allocator);
+defer allocator.free(reqs);
+for (reqs) |req| {
+    std.debug.print("{s}: required={any} available={any}\n", .{
+        req.name, req.required, req.available,
+    });
+}
+```
+
+On Linux this reports helper/runtime expectations such as:
+- `webui_linux_webview_host`
+- `webui_linux_browser_host`
+
 ## Build Flags
 
 | Flag | Default | What it does |
@@ -220,6 +286,7 @@ Exported compile-time values:
 
 - `zig build` (install)
 - `zig build test`
+- `zig build dispatcher-stress`
 - `zig build examples`
 - `zig build run`
 - `zig build bridge`
@@ -289,6 +356,6 @@ Manual GUI validation checklist: `docs/manual_gui_checklist.md`.
 
 ## Docs
 
-- `MIGRATION.md`
+- `docs/migration.md`
 - `CHANGELOG.md`
 - `docs/upstream_file_parity.md`

build.zig

@@ -360,6 +360,20 @@ pub fn build(b: *Build) void {
         test_step.dependOn(step);
     }
 
+    const dispatcher_stress_tests = b.addTest(.{
+        .root_module = webui_mod,
+        .filters = &.{"threaded dispatcher stress"},
+    });
+    dispatcher_stress_tests.step.dependOn(runtime_helpers_assets.prepare_step);
+    dispatcher_stress_tests.linkLibrary(webui_lib);
+
+    const dispatcher_stress_step = b.step("dispatcher-stress", "Stress threaded dispatcher concurrency/lifetime paths");
+    var stress_iter: usize = 0;
+    while (stress_iter < 8) : (stress_iter += 1) {
+        const run_stress = b.addRunArtifact(dispatcher_stress_tests);
+        dispatcher_stress_step.dependOn(&run_stress.step);
+    }
+
     const parity_report_tool = b.addExecutable(.{
         .name = "parity_report",
         .root_module = b.createModule(.{

docs/manual_gui_checklist.md

@@ -22,7 +22,7 @@ For each OS, validate at least:
 - Additional installed third-party browsers where available (Arc, Sidekick, Shift, DuckDuckGo, SigmaOS, Lightpanda)
 
 For each browser:
-- Launch example app and confirm browser opens automatically when `auto_open_browser=true`.
+- Launch example app and confirm browser opens when `launch_policy.browser_open_mode` allows browser transport.
 - Confirm app opens with explicit env override:
   - `WEBUI_BROWSER_PATH`
   - `WEBUI_BROWSER`

docs/migration.md

@@ -0,0 +1,124 @@
+# Migration Guide: Launch Policy + Async RPC Jobs
+
+This guide covers the hard API replacement in `AppOptions` and the new async RPC job APIs.
+
+## AppOptions Launch Fields (Hard Replace)
+
+Removed fields:
+- `transport_mode`
+- `auto_open_browser`
+- `browser_fallback_on_native_failure`
+
+Replacement:
+- `launch_policy: LaunchPolicy`
+
+```zig
+pub const LaunchPolicy = struct {
+    preferred_transport: enum { native_webview, browser } = .native_webview,
+    fallback_transport: enum { none, browser } = .browser,
+    browser_open_mode: enum { never, on_browser_transport, always } = .on_browser_transport,
+    allow_dual_surface: bool = false,
+    app_mode_required: bool = false,
+};
+```
+
+## Old -> New Mapping
+
+### Native-first with browser fallback
+
+Before:
+
+```zig
+.app = .{
+    .transport_mode = .native_webview,
+    .browser_fallback_on_native_failure = true,
+    .auto_open_browser = true,
+}
+```
+
+After:
+
+```zig
+.app = .{
+    .launch_policy = .{
+        .preferred_transport = .native_webview,
+        .fallback_transport = .browser,
+        .browser_open_mode = .on_browser_transport,
+    },
+}
+```
+
+### Browser-only mode
+
+Before:
+
+```zig
+.app = .{
+    .transport_mode = .browser_fallback,
+    .auto_open_browser = true,
+}
+```
+
+After:
+
+```zig
+.app = .{
+    .launch_policy = .{
+        .preferred_transport = .browser,
+        .fallback_transport = .browser,
+        .browser_open_mode = .on_browser_transport,
+    },
+}
+```
+
+### Native-only required mode (no browser fallback)
+
+```zig
+.app = .{
+    .launch_policy = .{
+        .preferred_transport = .native_webview,
+        .fallback_transport = .none,
+        .browser_open_mode = .never,
+        .app_mode_required = true,
+    },
+}
+```
+
+## New Introspection APIs
+
+Use these to avoid warning-string parsing:
+- `Window.runtimeRenderState()` / `Service.runtimeRenderState()`
+- `Window.probeCapabilities()` / `Service.probeCapabilities()`
+- `Service.listRuntimeRequirements(allocator)`
+- `App.onDiagnostic(...)` / `Service.onDiagnostic(...)`
+
+## Async RPC Jobs (Push-First + Poll Fallback)
+
+Enable async jobs:
+
+```zig
+try window.bindRpc(rpc_methods, .{
+    .execution_mode = .queued_async,
+    .job_queue_capacity = 1024,
+    .job_poll_min_ms = 200,
+    .job_poll_max_ms = 1000,
+    .push_job_updates = true,
+});
+```
+
+Runtime behavior:
+- `POST <rpc_route>` returns `job_id` immediately.
+- Completion updates are pushed over `/webui/ws` as `rpc_job_update`.
+- If push is unavailable, bridge falls back to bounded polling:
+  - `GET /rpc/job?id=<job_id>`
+  - `POST /rpc/job/cancel`
+
+Typed control APIs:
+- `Window.rpcPollJob(allocator, job_id) !RpcJobStatus`
+- `Window.rpcCancelJob(job_id) !bool`
+- `Service.rpcPollJob(...)` / `Service.rpcCancelJob(...)`
+
+## Notes
+
+- Existing warning log strings may still appear, but typed diagnostics are the authoritative integration surface.
+- For Linux packaging, validate helper/runtime presence through `listRuntimeRequirements`.

src/bridge/generated/runtime_helpers.embed.js

@@ -24,7 +24,14 @@ async function __webuiInvoke(endpoint, name, args) {
     const text = await res.text();
     throw new Error(`RPC ${name} failed: ${res.status} ${text}`);
   }
-  return await res.json();
+  const body = await res.json();
+  if (body && typeof body === "object" && Number.isFinite(Number(body.job_id))) {
+    const jobId = Math.trunc(Number(body.job_id));
+    const pollMin = Number.isFinite(Number(body.poll_min_ms)) ? Math.max(50, Math.trunc(Number(body.poll_min_ms))) : 200;
+    const pollMax = Number.isFinite(Number(body.poll_max_ms)) ? Math.max(pollMin, Math.trunc(Number(body.poll_max_ms))) : 1000;
+    return await __webuiAwaitRpcJob(endpoint, jobId, pollMin, pollMax);
+  }
+  return body;
 }
 
 async function __webuiJson(endpoint, options) {
@@ -57,6 +64,88 @@ function __webuiNormalizeResult(result) {
   return result;
 }
 
+const __webuiRpcJobWaiters = new Map();
+
+async function __webuiFetchRpcJobStatus(endpoint, jobId) {
+  const url = new URL("/rpc/job", globalThis.location ? globalThis.location.href : endpoint);
+  url.searchParams.set("id", String(jobId));
+  return await __webuiJson(url.toString(), { method: "GET" });
+}
+
+async function __webuiAwaitRpcJob(endpoint, jobId, pollMinMs, pollMaxMs) {
+  let stopped = false;
+  let timer = null;
+  let currentDelay = pollMinMs;
+
+  return await new Promise((resolve, reject) => {
+    const cleanup = () => {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      timer = null;
+      __webuiRpcJobWaiters.delete(jobId);
+    };
+
+    const failWithState = (status, fallbackMessage) => {
+      const message = status && typeof status.error_message === "string" && status.error_message.length > 0
+        ? status.error_message
+        : fallbackMessage;
+      reject(new Error(message));
+    };
+
+    const schedulePoll = () => {
+      if (stopped) return;
+      timer = setTimeout(() => {
+        void poll();
+      }, currentDelay);
+      currentDelay = Math.min(pollMaxMs, Math.max(pollMinMs, Math.floor(currentDelay * 1.6)));
+    };
+
+    const poll = async () => {
+      if (stopped) return;
+      try {
+        const status = await __webuiFetchRpcJobStatus(endpoint, jobId);
+        const state = status && typeof status.state === "string" ? status.state : "queued";
+        if (state === "completed") {
+          cleanup();
+          resolve({ value: "value" in status ? status.value : null });
+          return;
+        }
+        if (state === "failed") {
+          cleanup();
+          failWithState(status, `RPC job ${jobId} failed`);
+          return;
+        }
+        if (state === "canceled") {
+          cleanup();
+          failWithState(status, `RPC job ${jobId} canceled`);
+          return;
+        }
+        if (state === "timed_out") {
+          cleanup();
+          failWithState(status, `RPC job ${jobId} timed out`);
+          return;
+        }
+      } catch (_) {
+        // Keep bounded fallback polling on transient transport errors.
+      }
+      schedulePoll();
+    };
+
+    __webuiRpcJobWaiters.set(jobId, {
+      trigger() {
+        if (stopped) return;
+        currentDelay = pollMinMs;
+        if (timer) clearTimeout(timer);
+        timer = null;
+        void poll();
+      },
+    });
+
+    // Push-first: await server push, but always keep a bounded polling fallback.
+    schedulePoll();
+  });
+}
+
 let __webuiWindowRuntimeEmulationEnabled = true;
 let __webuiWindowRuntimeLoaded = false;
 
@@ -310,6 +399,14 @@ function __webuiHandleSocketMessage(raw) {
     __webuiHandleBackendClose(message);
     return;
   }
+  if (message.type === "rpc_job_update") {
+    const id = Number(message.job_id);
+    if (Number.isFinite(id)) {
+      const waiter = __webuiRpcJobWaiters.get(Math.trunc(id));
+      if (waiter && typeof waiter.trigger === "function") waiter.trigger();
+    }
+    return;
+  }
   if (message.type !== "script_task") return;
   if (typeof message.script !== "string") return;
   void __webuiExecuteScriptTask(message);