@nyssance/tauri-hasgard 0.3.0 → 0.4.1

package/README.md

@@ -29,6 +29,50 @@ export const { test, expect } = createHasgardTest({
 
 The fixture passes the selected socket to the application as `TAURI_HASGARD_SOCKET`, so each Playwright worker receives an isolated connection.
 
+On macOS, a managed launch owns a detached process group. Teardown
+waits for that group to exit, including children left behind by a launcher,
+and escalates from SIGTERM to SIGKILL after five seconds. Startup failures also
+clean up, and concurrent `stop()` calls share the same cleanup. A live endpoint
+is rejected rather than unlinked; readiness requires a successful connection.
+If cleanup fails, ownership is retained so `stop()` can be retried; another
+launch is blocked until that cleanup succeeds.
+Diagnostics retain the last 64 Ki characters per output stream with a truncation
+marker. `await process.diagnostics()` exposes those tails and the actual exit
+code or signal. Failed tests attach them; a failed screenshot does not replace
+the original test error. Teardown removes the owned stale socket after its
+process group exits, checking its identity and preserving live or replaced paths.
+
+An independent supervisor owns the application and watches the worker's IPC
+connection. If the worker is killed with SIGKILL, the supervisor still terminates
+the application group and exits. Killing the supervisor itself or children that
+deliberately create a new session or process group are outside this guarantee.
+Attach-only fixtures do not terminate an application they did not launch.
+
+`window.press(key)` uses native OS input and, by default, waits for a trusted
+WebView keyup before the next press may switch windows. For OS shortcuts and
+keys that navigate or close the document, explicitly use
+`window.press(key, { completion: "native" })`; that mode confirms posting only.
+Bare modifiers also use native posting completion. The active input method
+remains in effect: use `fill` for exact text, and `Shift+m` for a shifted key.
+
+To keep keyboard ownership until an application state is observable:
+
+```ts
+await window.press("Tab", {
+  waitFor: "document.activeElement.id === 'save'",
+  timeoutMs: 1_000
+})
+```
+
+The postcondition timeout is capped at ten seconds. Failures retain their
+`HasgardRpcError.data.phase` and `injected` status; never blindly retry an
+already-injected or uncertain press. See [the wire contract](../../docs/protocol.md#native-keyboard-completion).
+
+Requests are limited to 1,048,576 UTF-8 bytes including the trailing newline,
+matching the plugin. Oversized requests fail before transmission. An explicit
+null result is supported; malformed responses are rejected instead of returning
+an invented value.
+
 ## Test
 
 ```ts

package/dist/chunk-N7YDYAKI.js

@@ -0,0 +1,31 @@
+// src/process-group.js
+import { setTimeout as delay } from "timers/promises";
+function signalGroup(pid, signal) {
+  try {
+    process.kill(-pid, signal);
+    return true;
+  } catch (error) {
+    if (error.code === "ESRCH") return false;
+    if (signal === 0 && error.code === "EPERM") return true;
+    throw error;
+  }
+}
+async function waitForExit(pid, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (signalGroup(pid, 0)) {
+    if (Date.now() >= deadline) return false;
+    await delay(25);
+  }
+  return true;
+}
+async function stopProcessGroup(pid) {
+  signalGroup(pid, "SIGTERM");
+  if (!await waitForExit(pid, 5e3)) {
+    signalGroup(pid, "SIGKILL");
+    if (!await waitForExit(pid, 5e3)) throw new Error(`Hasgard process group ${pid} survived SIGKILL`);
+  }
+}
+
+export {
+  stopProcessGroup
+};

package/dist/index.d.ts

@@ -3,5 +3,5 @@ export { createHasgardExpect } from "./expect.js";
 export { createHasgardTest } from "./fixture.js";
 export { HasgardProcess } from "./process-manager.js";
 export { HasgardRpcClient, HasgardRpcError } from "./rpc-client.js";
-export type { BoundingBox, ClickOptions, ConsoleLogEntry, ConsoleLogOptions, DialogListing, DialogPolicy, DialogRecord, DialogType, DiffChange, DiffOptions, DragOffset, DropFile, ElementPosition, FileInput, FilterOptions, FormEntry, FormField, FormsDump, FulfillOptions, HasgardFixtures, HasgardLaunchConfig, HasgardTarget, HasgardTestConfig, HasgardWorkerFixtures, InterceptedRequest, JsonPrimitive, JsonValue, KeyModifier, MouseButton, NativeScreenshot, NativeScreenshotOptions, NetworkRequestEntry, NetworkRequestOptions, QueryDimension, RecorderEntry, RecorderResult, RecorderStatus, RoleQuery, RouteListing, RouteOptions, RouteRule, ScrollOptions, Snapshot, SnapshotDiff, SnapshotElement, SnapshotOptions, StorageEntry, StorageListing, StorageOptions, TextQuery, WaitForFunctionOptions, WaitOptions, WatchChanges, WatchNode, WatchOptions, WindowInfo, WindowState } from "./types.js";
+export type { BoundingBox, ClickOptions, ConsoleLogEntry, ConsoleLogOptions, DialogListing, DialogPolicy, DialogRecord, DialogType, DiffChange, DiffOptions, DragOffset, DropFile, ElementPosition, FileInput, FilterOptions, FormEntry, FormField, FormsDump, FulfillOptions, HasgardFixtures, HasgardLaunchConfig, HasgardTarget, HasgardTestConfig, HasgardWorkerFixtures, InterceptedRequest, JsonPrimitive, JsonValue, KeyModifier, MouseButton, NativeScreenshot, NativeScreenshotOptions, NetworkRequestEntry, NetworkRequestOptions, PressOptions, QueryDimension, RecorderEntry, RecorderResult, RecorderStatus, RoleQuery, RouteListing, RouteOptions, RouteRule, ScrollOptions, Snapshot, SnapshotDiff, SnapshotElement, SnapshotOptions, StorageEntry, StorageListing, StorageOptions, TextQuery, WaitForFunctionOptions, WaitOptions, WatchChanges, WatchNode, WatchOptions, WindowInfo, WindowState } from "./types.js";
 export { byPoint, byRef, bySelector, HasgardApplication, HasgardFrameLocator, HasgardLocator, HasgardWindow } from "./window.js";

package/dist/index.js

@@ -1,3 +1,7 @@
+import {
+  stopProcessGroup
+} from "./chunk-N7YDYAKI.js";
+
 // src/endpoint.ts
 import { tmpdir } from "os";
 import { join } from "path";
@@ -11,20 +15,18 @@ function hasgardEndpointPath(name) {
 
 // src/expect.ts
 async function poll(read, matches, timeoutMs) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+    throw new RangeError("Assertion timeout must be a finite non-negative number");
   const deadline = Date.now() + timeoutMs;
-  let value;
-  let error;
-  while (Date.now() <= deadline) {
+  for (; ; ) {
     try {
-      value = await read();
-      error = void 0;
-      if (matches(value)) return { pass: true, value, error };
-    } catch (caught) {
-      error = caught;
+      const value = await read();
+      if (matches(value) || Date.now() >= deadline) return value;
+    } catch (error) {
+      if (Date.now() >= deadline) throw error;
     }
-    await new Promise((resolve) => setTimeout(resolve, 50));
+    await new Promise((resolve) => setTimeout(resolve, Math.min(50, Math.max(0, deadline - Date.now()))));
   }
-  return { pass: false, value, error };
 }
 function createHasgardExpect(playwrightExpect) {
   return playwrightExpect.extend({
@@ -36,8 +38,8 @@ function createHasgardExpect(playwrightExpect) {
         timeout
       );
       return {
-        pass: result.value === true,
-        message: () => this.isNot ? "expected Hasgard locator not to be visible" : `expected Hasgard locator to be visible within ${timeout}ms${result.error ? `: ${String(result.error)}` : ""}`
+        pass: result === true,
+        message: () => this.isNot ? "expected Hasgard locator not to be visible" : `expected Hasgard locator to be visible within ${timeout}ms`
       };
     },
     async toHaveText(locator, expected, options = {}) {
@@ -53,24 +55,55 @@ function createHasgardExpect(playwrightExpect) {
         timeout
       );
       return {
-        pass: result.value === void 0 ? false : matches(result.value),
-        message: () => this.isNot ? `expected Hasgard locator text not to match ${String(expected)}, received ${String(result.value)}` : `expected Hasgard locator text to match ${String(expected)}, received ${String(result.value)}`
+        pass: matches(result),
+        message: () => this.isNot ? `expected Hasgard locator text not to match ${String(expected)}, received ${String(result)}` : `expected Hasgard locator text to match ${String(expected)}, received ${String(result)}`
       };
     }
   });
 }
 
 // src/process-manager.ts
-import { spawn } from "child_process";
-import { access, rm } from "fs/promises";
+import { fork, spawn } from "child_process";
+import { lstat } from "fs/promises";
 import { createConnection } from "net";
+import { setTimeout as delay } from "timers/promises";
 var HasgardProcess = class {
   child;
   stdout = "";
   stderr = "";
+  starting;
+  stopping;
+  applicationPid;
+  applicationExit;
+  /** Bounded log tails and the supervisor's actual child-close result. */
+  async diagnostics(waitForExitMs = 0) {
+    if (!Number.isFinite(waitForExitMs) || waitForExitMs < 0) throw new RangeError("Invalid diagnostics wait");
+    const deadline = Date.now() + waitForExitMs;
+    while (this.child && !this.applicationExit && Date.now() < deadline)
+      await delay(Math.min(25, deadline - Date.now()));
+    return { pid: this.applicationPid, exit: this.applicationExit, stdout: this.stdout, stderr: this.stderr };
+  }
   async start(config, socketPath) {
-    if (this.child) throw new Error("Hasgard app process is already running");
-    if (process.platform !== "win32") await rm(socketPath, { force: true });
+    if (this.child || this.stopping || this.starting) throw new Error("Hasgard app process is already running");
+    this.starting = this.launch(config, socketPath);
+    try {
+      await this.starting;
+    } finally {
+      this.starting = void 0;
+    }
+  }
+  async launch(config, socketPath) {
+    this.stdout = "";
+    this.stderr = "";
+    this.applicationPid = void 0;
+    this.applicationExit = void 0;
+    if (process.platform !== "win32" && await endpointAcceptsConnections(socketPath)) {
+      throw new Error(`Hasgard endpoint is already in use: ${socketPath}`);
+    }
+    if (process.platform !== "win32") {
+      await this.launchSupervised(config, socketPath);
+      return;
+    }
     const child = spawn(config.command, config.args, {
       cwd: config.cwd,
       env: { ...process.env, ...config.env, TAURI_HASGARD_SOCKET: socketPath },
@@ -79,68 +112,206 @@ var HasgardProcess = class {
     });
     this.child = child;
     child.stdout?.on("data", (data) => {
-      this.stdout += data.toString();
+      this.stdout = appendOutput(this.stdout, data.toString());
     });
     child.stderr?.on("data", (data) => {
-      this.stderr += data.toString();
+      this.stderr = appendOutput(this.stderr, data.toString());
     });
-    await new Promise((resolve, reject) => {
-      child.once("spawn", resolve);
-      child.once("error", reject);
+    try {
+      await new Promise((resolve, reject) => {
+        child.once("spawn", resolve);
+        child.once("error", reject);
+      });
+      await this.waitForSocket(socketPath, config.timeoutMs);
+    } catch (error) {
+      try {
+        await this.stopChild();
+      } catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], "Hasgard launch failed and process cleanup failed");
+      }
+      throw error;
+    }
+  }
+  async launchSupervised(config, socketPath) {
+    const child = fork(new URL("./process-supervisor.js", import.meta.url), [], {
+      detached: true,
+      execArgv: [],
+      stdio: ["ignore", "ignore", "pipe", "ipc"]
+    });
+    this.child = child;
+    child.stderr?.on("data", (data) => {
+      this.stderr = appendOutput(this.stderr, String(data));
     });
     try {
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("Hasgard process supervisor did not start")), config.timeoutMs);
+        const failed = (error) => {
+          clearTimeout(timer);
+          reject(error);
+        };
+        child.once("error", failed);
+        child.once("exit", () => failed(new Error("Hasgard process supervisor exited")));
+        child.on(
+          "message",
+          (message) => {
+            if (message.type === "stdout") this.stdout = appendOutput(this.stdout, message.data);
+            else if (message.type === "stderr") this.stderr = appendOutput(this.stderr, message.data);
+            else if (message.type === "exit") this.applicationExit = { code: message.code, signal: message.signal };
+            else if (message.type === "error") failed(Object.assign(new Error(message.message), { code: message.code }));
+            else if (message.type === "started") {
+              if (!Number.isSafeInteger(message.pid) || message.pid <= 1) {
+                failed(new Error("Invalid supervised application PID"));
+                return;
+              }
+              this.applicationPid = message.pid;
+              clearTimeout(timer);
+              resolve();
+            }
+          }
+        );
+        child.send({ ...config, env: { ...process.env, ...config.env, TAURI_HASGARD_SOCKET: socketPath } }, (error) => {
+          if (error) failed(error);
+        });
+      });
       await this.waitForSocket(socketPath, config.timeoutMs);
+      await this.confirmEndpointOwnership(child, socketPath, config.timeoutMs);
     } catch (error) {
-      await this.stop();
+      try {
+        await this.stopChild();
+      } catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], "Hasgard launch failed and process cleanup failed");
+      }
       throw error;
     }
   }
   async waitForSocket(socketPath, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() <= deadline) {
-      if (this.child?.exitCode !== null && this.child?.exitCode !== void 0) {
+      const child = this.child;
+      if (this.applicationExit) {
+        const { code, signal } = this.applicationExit;
         throw new Error(
-          `Tauri process exited with code ${this.child.exitCode}
+          `Tauri process exited with ${signal ? `signal ${signal}` : `code ${code}`}
 stdout:
 ${this.stdout}
 stderr:
 ${this.stderr}`
         );
       }
-      if (process.platform === "win32") {
-        if (await namedPipeAcceptsConnections(socketPath)) return;
-      } else {
-        try {
-          await access(socketPath);
-          return;
-        } catch (error) {
-          const code = error.code;
-          if (code !== "ENOENT") throw error;
-        }
+      if (child && (child.exitCode !== null || child.signalCode !== null)) {
+        throw new Error(
+          `Tauri process exited with ${child.signalCode ? `signal ${child.signalCode}` : `code ${child.exitCode}`}
+stdout:
+${this.stdout}
+stderr:
+${this.stderr}`
+        );
       }
-      await new Promise((resolve) => setTimeout(resolve, 50));
+      if (await endpointAcceptsConnections(socketPath)) return;
+      await delay(50);
     }
     throw new Error(`Hasgard socket did not appear within ${timeoutMs}ms: ${socketPath}`);
   }
+  async confirmEndpointOwnership(child, path, timeoutMs) {
+    const stat = await lstat(path);
+    if (!stat.isSocket()) throw new Error(`Hasgard endpoint is not a socket: ${path}`);
+    await new Promise((resolve, reject) => {
+      const done = (error) => {
+        clearTimeout(timer);
+        child.off("message", message);
+        child.off("exit", exited);
+        if (error) reject(error);
+        else resolve();
+      };
+      const message = (value) => {
+        if (value.type === "endpoint-owned") done();
+        else if (value.type === "error") done(new Error(value.message));
+      };
+      const exited = () => done(new Error("Hasgard supervisor exited before acknowledging endpoint ownership"));
+      const timer = setTimeout(
+        () => done(new Error("Hasgard supervisor did not acknowledge endpoint ownership")),
+        timeoutMs
+      );
+      child.on("message", message);
+      child.once("exit", exited);
+      child.send({ type: "endpoint", identity: { dev: stat.dev, ino: stat.ino } }, (error) => {
+        if (error) done(error);
+      });
+    });
+  }
   async stop() {
+    if (this.starting) await this.starting;
+    if (this.stopping) return this.stopping;
+    this.stopping = this.stopChild();
+    try {
+      await this.stopping;
+    } finally {
+      this.stopping = void 0;
+    }
+  }
+  async stopChild() {
     const child = this.child;
-    if (!child || child.exitCode !== null) return;
+    if (!child) return;
+    if (process.platform !== "win32") {
+      if (this.applicationPid !== void 0) {
+        await stopProcessGroup(this.applicationPid);
+      }
+      const exited2 = child.exitCode !== null || child.signalCode !== null ? Promise.resolve() : new Promise((resolve) => child.once("exit", () => resolve()));
+      if (child.connected) child.disconnect();
+      const abort2 = new AbortController();
+      try {
+        if (await Promise.race([exited2, delay(11e3, "timeout", { signal: abort2.signal })]) === "timeout") {
+          throw new Error(`Hasgard process supervisor ${child.pid} did not finish cleanup`);
+        }
+      } finally {
+        abort2.abort();
+      }
+      this.child = void 0;
+      this.applicationPid = void 0;
+      if (child.exitCode !== 0 || child.signalCode !== null) {
+        throw new Error(`Hasgard supervisor cleanup failed (${child.signalCode ?? child.exitCode}):
+${this.stderr}`);
+      }
+      return;
+    }
+    if (child.pid === void 0 || child.exitCode !== null || child.signalCode !== null) {
+      this.child = void 0;
+      return;
+    }
     const exited = new Promise((resolve) => child.once("exit", () => resolve()));
     if (process.platform === "win32" && child.pid !== void 0) {
       await terminateWindowsProcessTree(child.pid);
     } else if (child.pid !== void 0) {
       process.kill(-child.pid, "SIGTERM");
     }
-    const timeout = new Promise((resolve) => setTimeout(() => resolve("timeout"), 5e3));
-    if (await Promise.race([exited, timeout]) === "timeout") {
-      if (process.platform === "win32" && child.pid !== void 0) await terminateWindowsProcessTree(child.pid);
-      else if (child.pid !== void 0) process.kill(-child.pid, "SIGKILL");
-      await exited;
+    const abort = new AbortController();
+    const timeout = delay(5e3, "timeout", { signal: abort.signal });
+    try {
+      if (await Promise.race([exited, timeout]) === "timeout") {
+        if (process.platform === "win32" && child.pid !== void 0) await terminateWindowsProcessTree(child.pid);
+        else if (child.pid !== void 0) process.kill(-child.pid, "SIGKILL");
+        await exited;
+      }
+    } finally {
+      abort.abort();
     }
     this.child = void 0;
   }
 };
-async function namedPipeAcceptsConnections(path) {
+function appendOutput(previous, chunk) {
+  const output = previous + chunk;
+  return output.length > 65536 ? `[earlier output truncated]
+${output.slice(-65536)}` : output;
+}
+async function endpointAcceptsConnections(path) {
+  if (process.platform !== "win32") {
+    try {
+      if (!(await lstat(path)).isSocket()) throw new Error(`Hasgard endpoint exists but is not a socket: ${path}`);
+    } catch (error) {
+      if (error.code === "ENOENT") return false;
+      throw error;
+    }
+  }
   return new Promise((resolve, reject) => {
     const socket = createConnection({ path });
     socket.once("connect", () => {
@@ -168,6 +339,32 @@ async function terminateWindowsProcessTree(pid) {
 // src/rpc-client.ts
 import { createConnection as createConnection2 } from "net";
 import { createInterface } from "readline";
+
+// src/protocol.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseRpcResponse(line) {
+  const value = JSON.parse(line);
+  const invalid = () => new Error(`Invalid Hasgard JSON-RPC envelope: ${line}`);
+  if (!isObject(value) || value.jsonrpc !== "2.0" || !Object.hasOwn(value, "id")) throw invalid();
+  if (value.id !== null && (!Number.isSafeInteger(value.id) || value.id < 0)) throw invalid();
+  const hasResult = Object.hasOwn(value, "result");
+  const hasError = Object.hasOwn(value, "error");
+  if (hasResult === hasError) throw invalid();
+  if (hasResult && value.id === null) throw invalid();
+  if (hasError) {
+    const error = value.error;
+    if (!isObject(error) || !Number.isInteger(error.code) || error.code < -2147483648 || error.code > 2147483647 || typeof error.message !== "string")
+      throw invalid();
+  }
+  return value;
+}
+
+// src/protocol-limits.ts
+var MAX_REQUEST_BYTES = 1048576;
+
+// src/rpc-client.ts
 var HasgardRpcError = class extends Error {
   code;
   data;
@@ -191,39 +388,66 @@ var HasgardRpcClient = class {
     if (this.socket) throw new Error("Hasgard RPC client is already connected");
     const socket = createConnection2({ path: this.socketPath });
     this.socket = socket;
-    await new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        socket.destroy();
-        reject(new Error(`Hasgard socket connection timed out after ${timeoutMs}ms: ${this.socketPath}`));
-      }, timeoutMs);
-      socket.once("connect", () => {
-        clearTimeout(timeout);
-        resolve();
-      });
-      socket.once("error", (error) => {
-        clearTimeout(timeout);
-        reject(error);
+    try {
+      await new Promise((resolve, reject) => {
+        const cleanup = () => {
+          clearTimeout(timeout);
+          socket.off("connect", connected);
+          socket.off("error", failed);
+          socket.off("close", closed);
+        };
+        const connected = () => {
+          cleanup();
+          resolve();
+        };
+        const failed = (error) => {
+          cleanup();
+          reject(error);
+        };
+        const closed = () => failed(new Error("Hasgard socket closed while connecting"));
+        const timeout = setTimeout(() => {
+          failed(new Error(`Hasgard socket connection timed out after ${timeoutMs}ms: ${this.socketPath}`));
+          socket.destroy();
+        }, timeoutMs);
+        socket.once("connect", connected);
+        socket.once("error", failed);
+        socket.once("close", closed);
       });
-    });
+    } catch (error) {
+      if (this.socket === socket) this.socket = void 0;
+      socket.destroy();
+      throw error;
+    }
     this.lines = createInterface({ input: socket });
     this.lines.on("line", (line) => this.handleLine(line));
-    socket.on("close", () => this.rejectPending(new Error("Hasgard socket closed")));
-    socket.on("error", (error) => this.rejectPending(error));
+    socket.on("close", () => {
+      if (this.socket !== socket) return;
+      this.rejectPending(new Error("Hasgard socket closed"));
+      this.disconnect();
+    });
+    socket.on("error", (error) => {
+      if (this.socket === socket) this.rejectPending(error);
+    });
   }
   async call(method, params) {
     const socket = this.socket;
-    if (!socket) throw new Error("Hasgard RPC client is not connected");
+    if (!socket || socket.destroyed || !socket.writable) throw new Error("Hasgard RPC client is not connected");
     const id = this.nextId;
     this.nextId += 1;
     const request = params ? { jsonrpc: "2.0", id, method, params } : { jsonrpc: "2.0", id, method };
+    const line = `${JSON.stringify(request)}
+`;
+    const bytes = Buffer.byteLength(line, "utf8");
+    if (bytes > MAX_REQUEST_BYTES) {
+      throw new Error(`Hasgard request is ${bytes} bytes; maximum is ${MAX_REQUEST_BYTES} bytes including newline`);
+    }
     const result = new Promise((resolve, reject) => {
       this.pending.set(id, {
         resolve: (value) => resolve(value),
         reject
       });
     });
-    socket.write(`${JSON.stringify(request)}
-`, (error) => {
+    socket.write(line, (error) => {
       if (!error) return;
       const pending = this.pending.get(id);
       if (!pending) return;
@@ -242,16 +466,16 @@ var HasgardRpcClient = class {
   handleLine(line) {
     let response;
     try {
-      response = JSON.parse(line);
-    } catch {
-      this.rejectPending(new Error(`Invalid Hasgard JSON-RPC response: ${line}`));
+      response = parseRpcResponse(line);
+    } catch (error) {
+      this.rejectPending(error instanceof Error ? error : new Error(String(error)));
       return;
     }
-    if (response.jsonrpc !== "2.0" || !Number.isInteger(response.id)) {
-      this.rejectPending(new Error(`Invalid Hasgard JSON-RPC envelope: ${line}`));
+    if ("error" in response && response.id === null) {
+      this.rejectPending(new HasgardRpcError(response.error.code, response.error.message, response.error.data));
       return;
     }
-    const pending = this.pending.get(response.id);
+    const pending = response.id === null ? void 0 : this.pending.get(response.id);
     if (!pending) {
       this.rejectPending(new Error(`Unexpected Hasgard JSON-RPC response id: ${response.id}`));
       return;
@@ -660,8 +884,14 @@ var HasgardWindow = class {
   async scrollBy(options) {
     await this.rpc.call("scroll", withWindow(this.label, options));
   }
-  async press(key) {
-    await this.rpc.call("press", withWindow(this.label, { key }));
+  async press(key, options) {
+    const params = { key };
+    if (options) {
+      if (options.completion !== void 0) params.completion = options.completion;
+      if (options.waitFor !== void 0) params.waitFor = options.waitFor;
+      if (options.timeoutMs !== void 0) params.timeout = options.timeoutMs;
+    }
+    await this.rpc.call("press", withWindow(this.label, params));
   }
   async diff(options = {}) {
     const { reference, ...snapshotOptions } = options;
@@ -1140,7 +1370,9 @@ var HasgardLocator = class _HasgardLocator {
     });
   }
   async isVisible() {
-    return this.withTarget(async (target) => {
+    return this.window.runExclusive(async () => {
+      const target = await this.resolveUnique(true);
+      if (target === null) return false;
       const value = expectRecord(await this.window.call("visible", this.scoped(target)), "visible result");
       return expectBoolean(value.visible, "visible.visible");
     });
@@ -1212,7 +1444,7 @@ var HasgardLocator = class _HasgardLocator {
   last() {
     return this.nth(-1);
   }
-  async resolveUnique() {
+  async resolveUnique(allowMissing = false) {
     if (this.query.kind === "selector" && !this.query.filters?.length) {
       return this.query.index === void 0 ? bySelector(this.query.selector) : { selector: this.query.selector, index: this.query.index };
     }
@@ -1220,10 +1452,12 @@ var HasgardLocator = class _HasgardLocator {
     if (this.query.index !== void 0) {
       const element = elements[absoluteIndex(this.query.index, elements.length)];
       if (!element) {
+        if (allowMissing) return null;
         throw new Error(`Locator has no element at index ${this.query.index} (${elements.length} matched)`);
       }
       return byRef(element.ref);
     }
+    if (elements.length === 0 && allowMissing) return null;
     if (elements.length !== 1) {
       throw new Error(`Locator resolved to ${elements.length} elements; expected exactly one`);
     }
@@ -1348,6 +1582,7 @@ function createHasgardTest(config) {
   const expect = createHasgardExpect(config.expect);
   const readinessTimeoutMs = config.launch ? config.launch.timeoutMs : 3e4;
   const fixtureTimeoutMs = config.launch ? config.launch.timeoutMs + 3e4 : 3e4;
+  const processes = /* @__PURE__ */ new WeakMap();
   const test = base.extend({
     hasgard: [
       async ({}, use, workerInfo) => {
@@ -1359,6 +1594,7 @@ function createHasgardTest(config) {
           else await process2.waitForSocket(socketPath, workerInfo.project.timeout);
           await rpc.connect(workerInfo.project.timeout);
           const hasgard = new HasgardApplication(rpc);
+          processes.set(hasgard, process2);
           const ping = await hasgard.ping();
           if (ping.status !== "ok") throw new Error(`Unexpected Hasgard ping status: ${ping.status}`);
           await hasgard.waitForWindowReady(config.windowLabel, config.readySelector, readinessTimeoutMs);
@@ -1373,11 +1609,21 @@ function createHasgardTest(config) {
     window: async ({ hasgard }, use, testInfo) => {
       await use(hasgard.window(config.windowLabel));
       if (testInfo.status !== testInfo.expectedStatus) {
-        const screenshot = await hasgard.window(config.windowLabel).screenshot();
-        await testInfo.attach("hasgard-screenshot", {
-          body: screenshot,
-          contentType: "image/png"
-        });
+        const managed = processes.get(hasgard);
+        if (managed && config.launch) {
+          const diagnostics = await managed.diagnostics(250);
+          await testInfo.attach("hasgard-process", {
+            body: JSON.stringify(diagnostics, null, 2),
+            contentType: "application/json"
+          });
+          if (diagnostics.exit) console.error(`Hasgard application exited: ${JSON.stringify(diagnostics)}`);
+        }
+        try {
+          const screenshot = await hasgard.window(config.windowLabel).screenshot();
+          await testInfo.attach("hasgard-screenshot", { body: screenshot, contentType: "image/png" });
+        } catch (error) {
+          await testInfo.attach("hasgard-screenshot-error", { body: String(error), contentType: "text/plain" });
+        }
       }
     }
   });

package/dist/process-group.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/process-manager.d.ts

@@ -3,7 +3,25 @@ export declare class HasgardProcess {
     private child;
     private stdout;
     private stderr;
+    private starting;
+    private stopping;
+    private applicationPid;
+    private applicationExit;
+    /** Bounded log tails and the supervisor's actual child-close result. */
+    diagnostics(waitForExitMs?: number): Promise<{
+        pid: number | undefined;
+        exit: {
+            code: number | null;
+            signal: string | null;
+        } | undefined;
+        stdout: string;
+        stderr: string;
+    }>;
     start(config: HasgardLaunchConfig, socketPath: string): Promise<void>;
+    private launch;
+    private launchSupervised;
     waitForSocket(socketPath: string, timeoutMs: number): Promise<void>;
+    private confirmEndpointOwnership;
     stop(): Promise<void>;
+    private stopChild;
 }

package/dist/process-manager.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/process-supervisor.js

@@ -0,0 +1,154 @@
+import {
+  stopProcessGroup
+} from "./chunk-N7YDYAKI.js";
+
+// src/process-supervisor.js
+import { spawn } from "child_process";
+import { lstatSync, unlinkSync } from "fs";
+import { createConnection } from "net";
+import { setTimeout as delay } from "timers/promises";
+var application;
+var starting = false;
+var stopping;
+var endpoint;
+var initialEndpoint;
+var ownedEndpoint;
+var endpointWatch;
+function identity(path) {
+  try {
+    const stat = lstatSync(path);
+    return { dev: stat.dev, ino: stat.ino, socket: stat.isSocket() };
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+function sameIdentity(first, second) {
+  return first && second && first.dev === second.dev && first.ino === second.ino;
+}
+function captureEndpoint() {
+  if (ownedEndpoint || !endpoint) return;
+  const current = identity(endpoint);
+  if (current?.socket && !sameIdentity(current, initialEndpoint)) {
+    ownedEndpoint = current;
+    clearInterval(endpointWatch);
+  }
+}
+async function removeOwnedEndpoint() {
+  if (!ownedEndpoint || !sameIdentity(identity(endpoint), ownedEndpoint)) return;
+  const accepting = await new Promise((resolve, reject) => {
+    const socket = createConnection({ path: endpoint });
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("error", (error) => {
+      if (error.code === "ECONNREFUSED" || error.code === "ENOENT") resolve(false);
+      else reject(error);
+    });
+    socket.setTimeout(1e3, () => {
+      socket.destroy();
+      reject(new Error("Endpoint cleanup probe timed out"));
+    });
+  });
+  if (!accepting && sameIdentity(identity(endpoint), ownedEndpoint)) {
+    try {
+      unlinkSync(endpoint);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+}
+process.stderr.on("error", (error) => {
+  if (error.code !== "EPIPE") shutdown(1);
+});
+function send(message, stream) {
+  if (!process.connected) return;
+  const writable = process.send(message, (error) => {
+    if (error) {
+      if (error.code !== "ERR_IPC_CHANNEL_CLOSED" && error.code !== "EPIPE")
+        process.stderr.write(`Hasgard supervisor IPC: ${error.message}
+`);
+      if (process.connected) process.disconnect();
+    } else stream?.resume();
+  });
+  if (!writable) stream?.pause();
+}
+process.once("message", (config) => {
+  if (!process.connected || stopping) return;
+  starting = true;
+  try {
+    endpoint = config.env.TAURI_HASGARD_SOCKET;
+    if (typeof endpoint !== "string" || !endpoint) throw new Error("Supervisor requires TAURI_HASGARD_SOCKET");
+    initialEndpoint = identity(endpoint);
+    endpointWatch = setInterval(captureEndpoint, 25);
+    process.on("message", (message) => {
+      if (message.type !== "endpoint") return;
+      const current = identity(endpoint);
+      if (!current?.socket || !sameIdentity(current, message.identity)) {
+        send({ type: "error", message: "Application endpoint changed during readiness" });
+        return;
+      }
+      ownedEndpoint = current;
+      clearInterval(endpointWatch);
+      send({ type: "endpoint-owned" });
+    });
+    application = spawn(config.command, config.args, {
+      cwd: config.cwd,
+      env: config.env,
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    application.stdout.on("data", (chunk) => send({ type: "stdout", data: chunk.toString() }, application.stdout));
+    application.stderr.on("data", (chunk) => send({ type: "stderr", data: chunk.toString() }, application.stderr));
+    application.once("spawn", () => send({ type: "started", pid: application.pid }));
+    application.once("error", (error) => send({ type: "error", message: error.message, code: error.code }));
+    application.once("close", (code, signal) => send({ type: "exit", code, signal }));
+  } catch (error) {
+    send({ type: "error", message: error.message, code: error.code });
+  }
+});
+process.once("disconnect", () => shutdown(0));
+for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) process.on(signal, () => shutdown(0));
+process.on("uncaughtException", (error) => {
+  process.stderr.write(`Hasgard supervisor error: ${error.stack}
+`);
+  shutdown(1);
+});
+process.on("unhandledRejection", (error) => {
+  process.stderr.write(`Hasgard supervisor rejection: ${String(error)}
+`);
+  shutdown(1);
+});
+function shutdown(exitCode) {
+  if (!stopping) stopping = cleanup(exitCode);
+}
+async function cleanup(exitCode) {
+  clearInterval(endpointWatch);
+  const pid = application?.pid;
+  if (!starting || pid === void 0) process.exit(exitCode);
+  let groupStopped = false;
+  let endpointFailures = 0;
+  for (; ; ) {
+    try {
+      let endpointError;
+      try {
+        captureEndpoint();
+      } catch (error) {
+        endpointError = error;
+      }
+      if (!groupStopped) {
+        await stopProcessGroup(pid);
+        groupStopped = true;
+      }
+      if (endpointError) throw endpointError;
+      await removeOwnedEndpoint();
+      process.exit(exitCode);
+    } catch (error) {
+      process.stderr.write(`Hasgard orphan cleanup: ${error.message}
+`);
+      if (groupStopped && ++endpointFailures >= 3) process.exit(1);
+      await delay(1e3);
+    }
+  }
+}

package/dist/protocol-limits.d.ts

@@ -0,0 +1 @@
+export declare const MAX_REQUEST_BYTES = 1048576;

package/dist/protocol.d.ts

@@ -0,0 +1,16 @@
+import type { JsonValue } from "./types.js";
+export type RpcResponse = {
+    jsonrpc: "2.0";
+    id: number;
+    result: JsonValue;
+} | {
+    jsonrpc: "2.0";
+    id: number | null;
+    error: {
+        code: number;
+        message: string;
+        data?: JsonValue;
+    };
+};
+/** Validate the shared Hasgard envelope without inventing missing results. */
+export declare function parseRpcResponse(line: string): RpcResponse;

package/dist/protocol.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -78,6 +78,12 @@ export interface DragOffset {
 }
 /** A held keyboard modifier. Named as the platform reports them on the event. */
 export type KeyModifier = "Alt" | "Control" | "Meta" | "Shift";
+/** An application postcondition to await before another native press may focus a window. */
+export interface PressOptions {
+    completion?: "webview" | "native";
+    waitFor?: string;
+    timeoutMs?: number;
+}
 export type MouseButton = "left" | "middle" | "right";
 /** A point inside the element, measured from its top-left corner. */
 export interface ElementPosition {

package/dist/window.d.ts

@@ -1,5 +1,5 @@
 import { HasgardRpcClient } from "./rpc-client.js";
-import type { BoundingBox, ClickOptions, ConsoleLogEntry, ConsoleLogOptions, DialogListing, DialogPolicy, DiffOptions, DragOffset, DropFile, FileInput, FilterOptions, FormsDump, FulfillOptions, HasgardTarget, JsonValue, NativeScreenshot, NativeScreenshotOptions, NetworkRequestEntry, NetworkRequestOptions, QueryDimension, RecorderEntry, RecorderResult, RecorderStatus, RoleQuery, RouteListing, RouteOptions, ScrollOptions, Snapshot, SnapshotDiff, SnapshotOptions, StorageListing, StorageOptions, TextQuery, WaitForFunctionOptions, WaitOptions, WatchChanges, WatchOptions, WindowInfo, WindowState } from "./types.js";
+import type { BoundingBox, ClickOptions, ConsoleLogEntry, ConsoleLogOptions, DialogListing, DialogPolicy, DiffOptions, DragOffset, DropFile, FileInput, FilterOptions, FormsDump, FulfillOptions, HasgardTarget, JsonValue, NativeScreenshot, NativeScreenshotOptions, NetworkRequestEntry, NetworkRequestOptions, PressOptions, QueryDimension, RecorderEntry, RecorderResult, RecorderStatus, RoleQuery, RouteListing, RouteOptions, ScrollOptions, Snapshot, SnapshotDiff, SnapshotOptions, StorageListing, StorageOptions, TextQuery, WaitForFunctionOptions, WaitOptions, WatchChanges, WatchOptions, WindowInfo, WindowState } from "./types.js";
 export declare const byRef: (ref: string) => HasgardTarget;
 export declare const bySelector: (selector: string) => HasgardTarget;
 export declare const byPoint: (x: number, y: number) => HasgardTarget;
@@ -65,7 +65,7 @@ export declare class HasgardWindow {
     navigate(url: string): Promise<void>;
     /** Scroll the document by a relative amount, or to `top`/`bottom`. */
     scrollBy(options: ScrollOptions): Promise<void>;
-    press(key: string): Promise<void>;
+    press(key: string, options?: PressOptions): Promise<void>;
     diff(options?: DiffOptions): Promise<SnapshotDiff>;
     /**
      * Poll a JavaScript expression in the webview until it returns a truthy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyssance/tauri-hasgard",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Playwright Test fixtures for native Tauri Hasgard automation",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,12 +18,14 @@
     "NOTICE.md"
   ],
   "scripts": {
-    "build": "bun node_modules/tsup/dist/cli-default.js src/index.ts --format esm --outDir dist --clean && bun node_modules/typescript/bin/tsc -p tsconfig.json --noEmit false --emitDeclarationOnly --declaration true",
-    "dev": "tsup src/index.ts --format esm --dts --outDir dist --watch",
+    "build": "bun node_modules/tsup/dist/cli-default.js src/index.ts src/process-supervisor.js --format esm --outDir dist --clean && bun node_modules/typescript/bin/tsc -p tsconfig.json --noEmit false --emitDeclarationOnly --declaration true",
+    "dev": "bun run --parallel dev:js dev:types",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "dev:js": "tsup src/index.ts src/process-supervisor.js --format esm --outDir dist --watch",
+    "dev:types": "tsc -p tsconfig.json --noEmit false --emitDeclarationOnly --declaration true --watch"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.61.1 <2"