Overhaul profile path API

Author: ItsMeSamey

MIGRATION.md

@@ -76,7 +76,7 @@ Profile-path notes:
 
 Repository cleanup notes:
 - Active example sources are under `examples/` (used directly by `zig build run`/`zig build examples`).
-- Legacy bridge asset compatibility arguments were removed from the build-time JS asset generator.
+- Bridge asset generation uses a single strict build-time path.
 
 ## Pinned Struct Move Safety
 

README.md

@@ -65,11 +65,11 @@ zig build -l
 zig build -h
 ```
 
-## Cleanup Notes
+## Repository Hygiene
 
-- Removed stale compatibility handling from JS asset generation (`js_asset_gen` no longer accepts legacy extra args).
-- Collapsed duplicated `Service` move-invariant guard calls to a single guard boundary (`Service.window()` + `App` entrypoints).
-- Async RPC jobs remain push-first; fallback polling now starts only when needed (or after a short grace window) to reduce extra requests.
+- Removed duplicate render-path logic in `Window.showHtml` / `Window.showFile`.
+- Removed unnecessary lifecycle unload signaling to reduce extra runtime traffic.
+- Profile launch semantics are strict and rule-based (`profile_rules`, first-match wins).
 
 ## Add To Your Project
 

docs/migration.md

@@ -213,7 +213,7 @@ Typed control APIs:
 - Existing warning log strings may still appear, but typed diagnostics are the authoritative integration surface.
 - For Linux packaging, validate helper/runtime presence through `listRuntimeRequirements`.
 - Active examples are tracked under `examples/` and built from those paths directly.
-- Legacy JS asset generator compatibility arguments were removed; the build path is now strict and deterministic.
+- JS asset generation is strict and deterministic in the active build path.
 
 ## Pinned Struct Move Safety
 

examples/shared/demo_runner.zig

@@ -419,7 +419,7 @@ fn hintFor(comptime kind: ExampleKind) []const u8 {
         .public_network => "Public listen policy enabled for LAN testing.",
         .multi_client => "Open multiple clients and verify independent RPC sessions.",
         .chatgpt_api => "RPC transport pattern suitable for chat-like workflows.",
-        .custom_web_server => "Custom server integration shape with bridge-compatible routes.",
+        .custom_web_server => "Custom server integration shape with bridge RPC routes.",
         .react => "Component-style RPC calls using the generated bridge contract.",
         else => "Window style/control and transport demo.",
     };

src/bridge/generated/runtime_helpers.embed.js

@@ -579,18 +579,11 @@ async function __webuiExecuteScriptTask(task) {
 })();
 
 (function __webuiInstallLifecycleHooks() {
-  if (typeof globalThis === "undefined" || typeof globalThis.addEventListener !== "function") return;
-  globalThis.addEventListener("beforeunload", () => {
-    // beforeunload also fires on reload/navigation, so do not signal hard-close here.
-    __webuiNotifyLifecycle("window_unloading");
-  });
-
-  if (typeof globalThis !== "undefined") {
-    globalThis.__webuiNotifyLifecycle = __webuiNotifyLifecycle;
-    globalThis.__webuiWindowControl = __webuiWindowControl;
-    globalThis.__webuiWindowStyle = __webuiWindowStyle;
-    globalThis.__webuiGetWindowStyle = __webuiGetWindowStyle;
-    globalThis.__webuiGetWindowCapabilities = __webuiGetWindowCapabilities;
-  }
+  if (typeof globalThis === "undefined") return;
+  globalThis.__webuiNotifyLifecycle = __webuiNotifyLifecycle;
+  globalThis.__webuiWindowControl = __webuiWindowControl;
+  globalThis.__webuiWindowStyle = __webuiWindowStyle;
+  globalThis.__webuiGetWindowStyle = __webuiGetWindowStyle;
+  globalThis.__webuiGetWindowCapabilities = __webuiGetWindowCapabilities;
 })();
 

src/bridge/generated/runtime_helpers.written.js

@@ -579,17 +579,10 @@ async function __webuiExecuteScriptTask(task) {
 })();
 
 (function __webuiInstallLifecycleHooks() {
-  if (typeof globalThis === "undefined" || typeof globalThis.addEventListener !== "function") return;
-  globalThis.addEventListener("beforeunload", () => {
-    // beforeunload also fires on reload/navigation, so do not signal hard-close here.
-    __webuiNotifyLifecycle("window_unloading");
-  });
-
-  if (typeof globalThis !== "undefined") {
-    globalThis.__webuiNotifyLifecycle = __webuiNotifyLifecycle;
-    globalThis.__webuiWindowControl = __webuiWindowControl;
-    globalThis.__webuiWindowStyle = __webuiWindowStyle;
-    globalThis.__webuiGetWindowStyle = __webuiGetWindowStyle;
-    globalThis.__webuiGetWindowCapabilities = __webuiGetWindowCapabilities;
-  }
+  if (typeof globalThis === "undefined") return;
+  globalThis.__webuiNotifyLifecycle = __webuiNotifyLifecycle;
+  globalThis.__webuiWindowControl = __webuiWindowControl;
+  globalThis.__webuiWindowStyle = __webuiWindowStyle;
+  globalThis.__webuiGetWindowStyle = __webuiGetWindowStyle;
+  globalThis.__webuiGetWindowCapabilities = __webuiGetWindowCapabilities;
 })();

src/bridge/runtime_helpers.source.js

@@ -579,17 +579,10 @@ async function __webuiExecuteScriptTask(task) {
 })();
 
 (function __webuiInstallLifecycleHooks() {
-  if (typeof globalThis === "undefined" || typeof globalThis.addEventListener !== "function") return;
-  globalThis.addEventListener("beforeunload", () => {
-    // beforeunload also fires on reload/navigation, so do not signal hard-close here.
-    __webuiNotifyLifecycle("window_unloading");
-  });
-
-  if (typeof globalThis !== "undefined") {
-    globalThis.__webuiNotifyLifecycle = __webuiNotifyLifecycle;
-    globalThis.__webuiWindowControl = __webuiWindowControl;
-    globalThis.__webuiWindowStyle = __webuiWindowStyle;
-    globalThis.__webuiGetWindowStyle = __webuiGetWindowStyle;
-    globalThis.__webuiGetWindowCapabilities = __webuiGetWindowCapabilities;
-  }
+  if (typeof globalThis === "undefined") return;
+  globalThis.__webuiNotifyLifecycle = __webuiNotifyLifecycle;
+  globalThis.__webuiWindowControl = __webuiWindowControl;
+  globalThis.__webuiWindowStyle = __webuiWindowStyle;
+  globalThis.__webuiGetWindowStyle = __webuiGetWindowStyle;
+  globalThis.__webuiGetWindowCapabilities = __webuiGetWindowCapabilities;
 })();

src/root.zig

@@ -1606,13 +1606,30 @@ const WindowState = struct {
     fn reconcileChildExit(self: *WindowState, allocator: std.mem.Allocator) void {
         const pid = self.launched_browser_pid orelse return;
 
+        // IMPORTANT:
+        // In browser/web modes, the PID we track can be a short-lived launcher process
+        // (or helper) rather than the long-lived browser tab/window process.
+        // We must not close the backend just because that PID exits.
+        // Only native-webview-first mode treats tracked process death as a terminal close.
+        const should_close_on_pid_exit = self.launch_policy.first == .native_webview;
+
         if (self.launched_browser_lifecycle_linked and core_runtime.linkedChildExited(pid)) {
-            self.markClosedFromTrackedBrowserExit(allocator, "child-exited");
+            if (should_close_on_pid_exit) {
+                self.markClosedFromTrackedBrowserExit(allocator, "child-exited");
+            } else {
+                self.clearTrackedBrowserState(allocator);
+                self.emit(.window_state, "browser-detached", "child-exited");
+            }
             return;
         }
 
         if (!core_runtime.isProcessAlive(pid)) {
-            self.markClosedFromTrackedBrowserExit(allocator, "browser-exited");
+            if (should_close_on_pid_exit) {
+                self.markClosedFromTrackedBrowserExit(allocator, "browser-exited");
+            } else {
+                self.clearTrackedBrowserState(allocator);
+                self.emit(.window_state, "browser-detached", "browser-exited");
+            }
         }
     }
 
@@ -2548,6 +2565,15 @@ pub const Window = struct {
     index: usize,
     id: usize,
 
+    fn refreshRenderedContentLocked(self: *Window, win_state: *WindowState) !void {
+        try win_state.ensureBrowserRenderState(self.app.allocator, self.app.options);
+        if (win_state.isNativeWindowActive()) {
+            if (win_state.last_url) |url| {
+                _ = win_state.backend.showContent(.{ .url = url }) catch {};
+            }
+        }
+    }
+
     pub fn showHtml(self: *Window, html: []const u8) !void {
         self.app.enforcePinnedMoveInvariant(.app);
         if (html.len == 0) return error.EmptyHtml;
@@ -2564,12 +2590,7 @@ pub const Window = struct {
         }
         win_state.shown = true;
 
-        try win_state.ensureBrowserRenderState(self.app.allocator, self.app.options);
-        if (win_state.isNativeWindowActive()) {
-            if (win_state.last_url) |url| {
-                _ = win_state.backend.showContent(.{ .url = url }) catch {};
-            }
-        }
+        try self.refreshRenderedContentLocked(win_state);
 
         self.emitRuntimeDiagnostics();
         self.emit(.navigation, "show-html", html);
@@ -2601,12 +2622,7 @@ pub const Window = struct {
         }
         win_state.shown = true;
 
-        try win_state.ensureBrowserRenderState(self.app.allocator, self.app.options);
-        if (win_state.isNativeWindowActive()) {
-            if (win_state.last_url) |url| {
-                _ = win_state.backend.showContent(.{ .url = url }) catch {};
-            }
-        }
+        try self.refreshRenderedContentLocked(win_state);
 
         self.emitRuntimeDiagnostics();
         self.emit(.navigation, "show-file", path);
@@ -3020,6 +3036,9 @@ pub const Service = struct {
         const state = win.state();
         state.state_mutex.lock();
         defer state.state_mutex.unlock();
+        // Reconcile tracked process state every loop.
+        // `reconcileChildExit()` is mode-aware and only turns PID exit into app close
+        // for native-webview-first mode. Browser/web modes only detach PID tracking.
         state.reconcileChildExit(self.app.allocator);
         return state.close_requested.load(.acquire);
     }
@@ -3755,7 +3774,6 @@ fn handleLifecycleRoute(
     if (!std.mem.eql(u8, path_only, "/webui/lifecycle")) return false;
 
     var parsed = std.json.parseFromSlice(std.json.Value, allocator, body, .{}) catch null;
-    var logged_event = false;
     const client_token = httpHeaderValue(headers, "x-webui-client-id") orelse default_client_token;
     state.state_mutex.lock();
     _ = state.findOrCreateClientSessionLocked(client_token) catch null;
@@ -3770,19 +3788,11 @@ fn handleLifecycleRoute(
                         state.requestLifecycleCloseFromFrontend();
                         state.state_mutex.unlock();
                     }
-                    if (state.rpc_state.log_enabled) {
-                        std.debug.print("[webui.lifecycle] event={s}\n", .{event_value.string});
-                        logged_event = true;
-                    }
                 }
             }
         }
     }
 
-    if (state.rpc_state.log_enabled and !logged_event) {
-        std.debug.print("[webui.lifecycle] body={s}\n", .{body});
-    }
-
     try writeHttpResponse(stream, 200, "application/json; charset=utf-8", "{\"ok\":true}");
     return true;
 }
@@ -5120,7 +5130,7 @@ test "window_closing lifecycle event is ignored while tracked browser pid is ali
     try std.testing.expect(!should_close);
 }
 
-test "non-linked tracked browser pid death requests close" {
+test "non-linked tracked browser pid death detaches without close in web mode" {
     if (builtin.os.tag != .linux) return error.SkipZigTest;
 
     var gpa = std.heap.GeneralPurposeAllocator(.{}){};
@@ -5152,20 +5162,27 @@ test "non-linked tracked browser pid death requests close" {
     win.state().state_mutex.unlock();
 
     var closed = false;
+    var detached = false;
     var attempts: usize = 0;
     while (attempts < 120) : (attempts += 1) {
         win.state().state_mutex.lock();
         win.state().reconcileChildExit(gpa.allocator());
         const requested = win.state().close_requested.load(.acquire);
+        const tracked_pid = win.state().launched_browser_pid;
         win.state().state_mutex.unlock();
         if (requested) {
             closed = true;
             break;
         }
+        if (tracked_pid == null) {
+            detached = true;
+            break;
+        }
         std.Thread.sleep(5 * std.time.ns_per_ms);
     }
 
-    try std.testing.expect(closed);
+    try std.testing.expect(!closed);
+    try std.testing.expect(detached);
 }
 
 test "window style apply updates persisted state" {