Add targeted client content replacement

Author: jinzhongjia

README.md

@@ -13,6 +13,7 @@ The current phase provides:
   built-in JavaScript bridge;
 - runtime content and resource-handler replacement through
   `Window.setContent()`;
+- targeted runtime content replacement through `Client.show()`;
 - explicit browser connection waiting and timeout through
   `Window.waitForConnection()`;
 - JavaScript calls to Zig bindings with return values;
@@ -116,6 +117,11 @@ navigates every connected client to it and returns the number notified. An
 invalid replacement leaves the current content unchanged. If client
 notification fails, the prepared replacement remains installed.
 
+`Client.show(&running, content)` installs the same window-wide content but
+navigates only the selected client, matching upstream `webui_show_client()`.
+Other connected pages are not reloaded; later resource requests use the new
+window content.
+
 `Window.onEvent` installs one handler for browser lifecycle, click, and
 navigation events. `Event.data` contains the element ID for clicks, the target
 URL for navigation, and is empty for connected or disconnected events.

docs/PURE_ZIG_REFACTOR.md

@@ -295,7 +295,6 @@ implementations.
 
 | Upstream API | Current gap |
 |---|---|
-| `webui_show_client()` | `Client` cannot replace the content of only one connected browser. |
 | `webui_is_shown()` | There is no window-level connected/shown query. |
 | `webui_set_config(folder_monitor)` | Directory change monitoring and automatic browser reload are not implemented. |
 | `webui_set_default_root_folder()` | There is no application-wide default directory content setting. |
@@ -331,6 +330,7 @@ not implementation gaps:
 |---|---|
 | `webui_new_window()`, `webui_new_window_id()`, `webui_get_new_window_id()` | `App.createWindow()` and application-owned IDs. |
 | `webui_show()`, `webui_start_server()`, `webui_get_url()` | Initial `Content`, runtime `Window.setContent()`, `App.start()`, `Window.open()`, and `Window.url()`. |
+| `webui_show_client()` | `Client.show()` replaces the window content and navigates only the selected client. |
 | `webui_wait()`, `webui_wait_async()` | `Running.wait()` used directly or through `std.Io` concurrency. |
 | `webui_close()`, `webui_destroy()`, `webui_exit()`, `webui_clean()` | `Window.close()`, `Running.stop()`, and `App.deinit()`. |
 | `webui_set_context()`, `webui_get_context()` | Binding and event-handler `user_data`. |
@@ -389,7 +389,6 @@ connection waiting, and caller-provided logging.
 
 ### Dynamic content and client state
 
-- Add targeted `Client.show()` behavior.
 - Add a window connected/shown query.
 - Add an application default directory.
 - Add inline and file-backed window icons.
@@ -485,6 +484,5 @@ zig build -Dtarget=aarch64-macos
 
 Continue capability parity:
 
-1. Add targeted `Client.show()`.
-2. Add a window connected/shown query.
-3. Add an application default directory and window icons.
+1. Add a window connected/shown query.
+2. Add an application default directory and window icons.

src/app.zig

@@ -1092,23 +1092,22 @@ pub const Client = struct {
     state: *WindowState,
     client_id: u64,
 
-    fn sendPacket(
+    fn retainPeer(self: Client, io: std.Io) !Linsang.WebSocketPeer {
+        self.state.mutex.lockUncancelable(io);
+        defer self.state.mutex.unlock(io);
+        const index = self.state.clientIndexById(self.client_id) orelse
+            return error.ConnectionClosed;
+        return self.state.clients.items[index].peer.clone();
+    }
+
+    fn sendPacketToPeer(
         self: Client,
-        io: std.Io,
+        peer: Linsang.WebSocketPeer,
         header: protocol.Header,
         payload: []const u8,
     ) !void {
         if (payload.len > self.state.limits.max_ws_message_size - protocol.header_len)
             return error.MessageTooLarge;
-        self.state.mutex.lockUncancelable(io);
-        const index = self.state.clientIndexById(self.client_id) orelse {
-            self.state.mutex.unlock(io);
-            return error.ConnectionClosed;
-        };
-        var peer = self.state.clients.items[index].peer.clone();
-        self.state.mutex.unlock(io);
-        defer peer.deinit();
-
         var packet: std.ArrayList(u8) = .empty;
         defer packet.deinit(self.state.gpa);
         try protocol.append(&packet, self.state.gpa, header, payload);
@@ -1118,6 +1117,17 @@ pub const Client = struct {
         };
     }
 
+    fn sendPacket(
+        self: Client,
+        io: std.Io,
+        header: protocol.Header,
+        payload: []const u8,
+    ) !void {
+        var peer = try self.retainPeer(io);
+        defer peer.deinit();
+        try self.sendPacketToPeer(peer, header, payload);
+    }
+
     fn send(
         self: Client,
         io: std.Io,
@@ -1140,6 +1150,31 @@ pub const Client = struct {
         return self.state.clientIndexById(self.client_id) != null;
     }
 
+    /// Replace the window content and navigate only this client to it.
+    /// If navigation fails, the replacement remains installed.
+    pub fn show(
+        self: Client,
+        running: *const Running,
+        content: Content,
+    ) !void {
+        if (running.stopped or !running.app.started)
+            return error.NotRunning;
+        if (!running.app.hasWindow(self.state)) return error.UnknownWindow;
+        var peer = try self.retainPeer(running.inner.io);
+        defer peer.deinit();
+
+        try self.state.replaceContent(running.inner.io, content);
+        const target_url = try (Window{ .state = self.state }).url(
+            running,
+            self.state.gpa,
+        );
+        defer self.state.gpa.free(target_url);
+        try self.sendPacketToPeer(peer, .{
+            .token = self.state.token,
+            .command = .navigation,
+        }, target_url);
+    }
+
     pub fn eval(
         self: Client,
         io: std.Io,
@@ -3734,6 +3769,59 @@ test "multi-client limits, targeting, and disconnect lifecycle" {
     try std.testing.expectEqual(protocol.Command.js_quick, second_quick.header.command);
     try std.testing.expectEqualStrings(first_quick.payload, second_quick.payload);
 
+    try std.testing.expectError(
+        error.InvalidExternalUrl,
+        first.show(&running, .{ .external_url = "file:///invalid" }),
+    );
+    try first.run(io, "globalThis.failedShowDidNotNavigate = true");
+    const failed_show_marker = try protocol.decode(try readServerFrame(
+        first_stream,
+        io,
+        &first_response,
+    ));
+    try std.testing.expectEqual(
+        protocol.Command.js_quick,
+        failed_show_marker.header.command,
+    );
+
+    try first.show(&running, .{ .html = "targeted client page" });
+    const targeted_show = try protocol.decode(try readServerFrame(
+        first_stream,
+        io,
+        &first_response,
+    ));
+    const targeted_url = try window.url(&running, gpa);
+    defer gpa.free(targeted_url);
+    try std.testing.expectEqual(
+        protocol.Command.navigation,
+        targeted_show.header.command,
+    );
+    try std.testing.expectEqualStrings(targeted_url, targeted_show.payload);
+
+    try second.run(io, "globalThis.otherClientWasNotNavigated = true");
+    const second_after_show = try protocol.decode(try readServerFrame(
+        second_stream,
+        io,
+        &second_response,
+    ));
+    try std.testing.expectEqual(
+        protocol.Command.js_quick,
+        second_after_show.header.command,
+    );
+    {
+        var target: [capability_len + 2]u8 = undefined;
+        var response: [512]u8 = undefined;
+        _ = try getTestPath(
+            running.inner.address,
+            io,
+            try std.fmt.bufPrint(&target, "/{s}/", .{
+                window.state.capability,
+            }),
+            "targeted client page",
+            &response,
+        );
+    }
+
     try first.navigate(io, "/first");
     const raw_data = [_]u8{ 2, 3, 5 };
     try second.sendRaw(io, "receiveRaw", &raw_data);
@@ -3988,6 +4076,23 @@ test "multi-client limits, targeting, and disconnect lifecycle" {
     try std.testing.expect(second.isConnected(io));
     try std.testing.expect(!app.closed.load(.acquire));
     try std.testing.expectError(error.ConnectionClosed, first_eval.await(io));
+    try std.testing.expectError(
+        error.ConnectionClosed,
+        first.show(&running, .{ .html = "stale client page" }),
+    );
+    {
+        var target: [capability_len + 2]u8 = undefined;
+        var response: [512]u8 = undefined;
+        _ = try getTestPath(
+            running.inner.address,
+            io,
+            try std.fmt.bufPrint(&target, "/{s}/", .{
+                window.state.capability,
+            }),
+            "targeted client page",
+            &response,
+        );
+    }
 
     packet.clearRetainingCapacity();
     try protocol.append(&packet, gpa, .{