@nyssance/tauri-hasgard 0.2.1 → 0.4.1

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;
@@ -309,6 +533,58 @@ function targetParams(target) {
   }
   return { x: target.x, y: target.y };
 }
+function clickParams(options) {
+  const params = {};
+  if (options.modifiers !== void 0) params.modifiers = options.modifiers;
+  if (options.button !== void 0) params.button = options.button;
+  if (options.clickCount !== void 0) params.clickCount = options.clickCount;
+  if (options.position !== void 0) params.position = { ...options.position };
+  return params;
+}
+function routeParams(options) {
+  const params = { pattern: options.pattern };
+  if (options.method !== void 0) params.method = options.method;
+  if (options.times !== void 0) params.times = options.times;
+  if ("status" in options && options.status !== void 0) params.status = options.status;
+  if ("body" in options && options.body !== void 0) params.body = options.body;
+  if ("contentType" in options && options.contentType !== void 0) {
+    params.contentType = options.contentType;
+  }
+  return params;
+}
+function parseRouteAction(value, context) {
+  const action = expectString(value, context);
+  if (action !== "fulfill" && action !== "abort") {
+    throw new Error(`${context} must be "fulfill" or "abort", got ${action}`);
+  }
+  return action;
+}
+function parseRouteRule(value, index) {
+  const context = `route.list.routes[${index}]`;
+  const rule = expectRecord(value, context);
+  return {
+    id: expectNumber(rule.id, `${context}.id`),
+    pattern: expectString(rule.pattern, `${context}.pattern`),
+    method: expectNullableString(rule.method, `${context}.method`),
+    action: parseRouteAction(rule.action, `${context}.action`),
+    status: expectNumber(rule.status, `${context}.status`),
+    times: rule.times === null ? null : expectNumber(rule.times, `${context}.times`),
+    used: expectNumber(rule.used, `${context}.used`)
+  };
+}
+function parseInterceptedRequest(value, index) {
+  const context = `route.list.intercepted[${index}]`;
+  const entry = expectRecord(value, context);
+  return {
+    id: expectNumber(entry.id, `${context}.id`),
+    timestamp: expectNumber(entry.timestamp, `${context}.timestamp`),
+    route_id: expectNumber(entry.route_id, `${context}.route_id`),
+    method: expectString(entry.method, `${context}.method`),
+    url: expectString(entry.url, `${context}.url`),
+    action: parseRouteAction(entry.action, `${context}.action`),
+    status: expectNumber(entry.status, `${context}.status`)
+  };
+}
 function absoluteIndex(index, total) {
   return index < 0 ? total + index : index;
 }
@@ -550,6 +826,17 @@ var HasgardWindow = class {
   getByTestId(testId) {
     return new HasgardLocator(this, { kind: "query", by: "testid", value: testId, query: {} });
   }
+  /**
+   * Scope locators to a same-origin `<iframe>`.
+   *
+   * Cross-origin frames are out of reach: the same-origin policy binds injected
+   * script exactly as it binds the page's own, so no bridge can see into a
+   * third-party payment or OAuth frame. Those raise an error naming the origin
+   * problem rather than reporting a missing element.
+   */
+  frameLocator(selector) {
+    return new HasgardFrameLocator(this, [selector]);
+  }
   async snapshot(options = {}) {
     const raw = expectRecord(
       await this.rpc.call("snapshot", withWindow(this.label, options)),
@@ -597,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;
@@ -787,6 +1080,53 @@ var HasgardWindow = class {
       await this.call("dialog.clear");
     }
   };
+  /**
+   * Shape what the page's own requests receive, without a real backend.
+   *
+   * Rules are declarative rather than Playwright's per-request callback: the
+   * bridge only ever answers requests, so it cannot call back into this process
+   * and await a handler while the page sits inside `fetch`. The same constraint
+   * shaped `dialogs`.
+   *
+   * Rules are checked in registration order and the first match wins, so
+   * register the narrow ones before a catch-all. Both `fetch` and
+   * `XMLHttpRequest` are covered; resources the webview loads itself -- the
+   * document, `<img src>`, stylesheets -- are not, since no page script sees
+   * them.
+   */
+  routes = {
+    /** Answer matching requests with this response instead of the network. */
+    fulfill: async (options) => {
+      const value = expectRecord(
+        await this.call("route.add", { ...routeParams(options), action: "fulfill" }),
+        "route.add result"
+      );
+      return { id: expectNumber(value.id, "route.add.id") };
+    },
+    /** Fail matching requests the way a dropped connection does. */
+    abort: async (options) => {
+      const value = expectRecord(
+        await this.call("route.add", { ...routeParams(options), action: "abort" }),
+        "route.add result"
+      );
+      return { id: expectNumber(value.id, "route.add.id") };
+    },
+    /** The active rules, their use counts, and every request they answered. */
+    list: async () => {
+      const value = expectRecord(await this.call("route.list"), "route.list result");
+      return {
+        routes: expectArray(value.routes, "route.list.routes").map((entry, index) => parseRouteRule(entry, index)),
+        intercepted: expectArray(value.intercepted, "route.list.intercepted").map(
+          (entry, index) => parseInterceptedRequest(entry, index)
+        )
+      };
+    },
+    /** Remove every rule and its interception log. */
+    clear: async () => {
+      const value = expectRecord(await this.call("route.clear"), "route.clear result");
+      return { removed: expectNumber(value.removed, "route.clear.removed") };
+    }
+  };
   /** This window's operating-system window id, where the platform exposes one. */
   async nativeId() {
     const listing = await new HasgardApplication(this.rpc).windows();
@@ -816,6 +1156,49 @@ var HasgardWindow = class {
     }
   }
 };
+var HasgardFrameLocator = class _HasgardFrameLocator {
+  windowRef;
+  frame;
+  constructor(window, frame) {
+    this.windowRef = window;
+    this.frame = frame;
+  }
+  /** Descend into a frame nested inside this one. */
+  frameLocator(selector) {
+    return new _HasgardFrameLocator(this.windowRef, [...this.frame, selector]);
+  }
+  locator(selector) {
+    return new HasgardLocator(this.windowRef, { kind: "selector", selector, frame: [...this.frame] });
+  }
+  getByRole(role, query = {}) {
+    return new HasgardLocator(this.windowRef, { kind: "role", role, query, frame: [...this.frame] });
+  }
+  getByText(text, query = {}) {
+    return this.byDimension("text", text, query);
+  }
+  getByLabel(text, query = {}) {
+    return this.byDimension("label", text, query);
+  }
+  getByPlaceholder(text, query = {}) {
+    return this.byDimension("placeholder", text, query);
+  }
+  getByAltText(text, query = {}) {
+    return this.byDimension("alt", text, query);
+  }
+  getByTitle(text, query = {}) {
+    return this.byDimension("title", text, query);
+  }
+  getByTestId(testId) {
+    return this.byDimension("testid", testId, {});
+  }
+  /** Snapshot the frame's own document rather than the top one. */
+  async snapshot(options = {}) {
+    return this.windowRef.snapshot({ ...options, frame: [...this.frame] });
+  }
+  byDimension(by, value, query) {
+    return new HasgardLocator(this.windowRef, { kind: "query", by, value, query, frame: [...this.frame] });
+  }
+};
 var HasgardLocator = class _HasgardLocator {
   window;
   query;
@@ -823,14 +1206,22 @@ var HasgardLocator = class _HasgardLocator {
     this.window = window;
     this.query = query;
   }
-  async click() {
-    await this.withTarget((target) => this.window.call("click", targetParams(target)));
+  /**
+   * Click this element.
+   *
+   * A right or middle click raises `contextmenu`/`auxclick` and no `click`, and
+   * `clickCount: 2` escalates `detail` across the presses before a single
+   * `dblclick` -- both matching what the platform does, so a listener bound to
+   * the wrong event fails here rather than in front of a user.
+   */
+  async click(options = {}) {
+    await this.withTarget((target) => this.window.call("click", { ...this.scoped(target), ...clickParams(options) }));
   }
   async fill(value) {
-    await this.withTarget((target) => this.window.call("fill", { ...targetParams(target), value }));
+    await this.withTarget((target) => this.window.call("fill", { ...this.scoped(target), value }));
   }
   async type(text) {
-    await this.withTarget((target) => this.window.call("type", { ...targetParams(target), text }));
+    await this.withTarget((target) => this.window.call("type", { ...this.scoped(target), text }));
   }
   /** Empty the control, firing `input` and `change` as `fill` does. */
   async clear() {
@@ -847,7 +1238,7 @@ var HasgardLocator = class _HasgardLocator {
     const payloads = await readFileInputs(files);
     await this.withTarget(
       (target) => this.window.call("setInputFiles", {
-        ...targetParams(target),
+        ...this.scoped(target),
         files: payloads
       })
     );
@@ -862,48 +1253,49 @@ var HasgardLocator = class _HasgardLocator {
   async wheel(deltaX, deltaY) {
     return this.withTarget(async (target) => {
       const value = expectRecord(
-        await this.window.call("wheel", { ...targetParams(target), deltaX, deltaY }),
+        await this.window.call("wheel", { ...this.scoped(target), deltaX, deltaY }),
         "wheel result"
       );
       return expectBoolean(value.defaultPrevented, "wheel.defaultPrevented");
     });
   }
   async selectOption(value) {
-    await this.withTarget((target) => this.window.call("select", { ...targetParams(target), value }));
+    await this.withTarget((target) => this.window.call("select", { ...this.scoped(target), value }));
   }
   /** Drive the checkbox to checked. A no-op when it is already checked. */
   async check() {
-    await this.withTarget((target) => this.window.call("check", { ...targetParams(target), checked: true }));
+    await this.withTarget((target) => this.window.call("check", { ...this.scoped(target), checked: true }));
   }
   /** Drive the checkbox to unchecked. A no-op when it is already unchecked. */
   async uncheck() {
-    await this.withTarget((target) => this.window.call("check", { ...targetParams(target), checked: false }));
+    await this.withTarget((target) => this.window.call("check", { ...this.scoped(target), checked: false }));
   }
   /** Flip the checkbox, whatever its current state. */
   async toggle() {
-    await this.withTarget((target) => this.window.call("check", targetParams(target)));
+    await this.withTarget((target) => this.window.call("check", this.scoped(target)));
   }
   async hover() {
-    await this.withTarget((target) => this.window.call("hover", targetParams(target)));
+    await this.withTarget((target) => this.window.call("hover", this.scoped(target)));
   }
-  async dblclick() {
-    await this.withTarget((target) => this.window.call("dblclick", targetParams(target)));
+  /** Shorthand for `click({ clickCount: 2 })`; other options still apply. */
+  async dblclick(options = {}) {
+    await this.click({ ...options, clickCount: 2 });
   }
   async focus() {
-    await this.withTarget((target) => this.window.call("focus", targetParams(target)));
+    await this.withTarget((target) => this.window.call("focus", this.scoped(target)));
   }
   async blur() {
-    await this.withTarget((target) => this.window.call("blur", targetParams(target)));
+    await this.withTarget((target) => this.window.call("blur", this.scoped(target)));
   }
   /** Scroll this element's own scrollport. */
   async scrollBy(options) {
     await this.withTarget(
-      (target) => this.window.call("scroll", { ...targetParams(target), ...options })
+      (target) => this.window.call("scroll", { ...this.scoped(target), ...options })
     );
   }
   async boundingBox() {
     return this.withTarget(async (target) => {
-      const value = expectRecord(await this.window.call("boundingBox", targetParams(target)), "boundingBox result");
+      const value = expectRecord(await this.window.call("boundingBox", this.scoped(target)), "boundingBox result");
       return {
         x: expectNumber(value.x, "boundingBox.x"),
         y: expectNumber(value.y, "boundingBox.y"),
@@ -914,7 +1306,7 @@ var HasgardLocator = class _HasgardLocator {
   }
   async isDisabled() {
     return this.withTarget(async (target) => {
-      const value = expectRecord(await this.window.call("disabled", targetParams(target)), "disabled result");
+      const value = expectRecord(await this.window.call("disabled", this.scoped(target)), "disabled result");
       return expectBoolean(value.disabled, "disabled.disabled");
     });
   }
@@ -923,17 +1315,17 @@ var HasgardLocator = class _HasgardLocator {
   }
   async textContent() {
     return this.withTarget(
-      async (target) => expectString(await this.window.call("text", targetParams(target)), "text result")
+      async (target) => expectString(await this.window.call("text", this.scoped(target)), "text result")
     );
   }
   async inputValue() {
     return this.withTarget(
-      async (target) => expectString(await this.window.call("value", targetParams(target)), "value result")
+      async (target) => expectString(await this.window.call("value", this.scoped(target)), "value result")
     );
   }
   async innerHTML() {
     return this.withTarget(
-      async (target) => expectString(await this.window.call("html", targetParams(target)), "html result")
+      async (target) => expectString(await this.window.call("html", this.scoped(target)), "html result")
     );
   }
   async getAttribute(name) {
@@ -957,41 +1349,46 @@ var HasgardLocator = class _HasgardLocator {
   /** Drag this element by a pixel offset from its centre. */
   async dragBy(offset) {
     await this.withTarget(
-      (target) => this.window.call("drag", { source: targetParams(target), offset: { x: offset.x, y: offset.y } })
+      (target) => this.window.call("drag", { source: this.scoped(target), offset: { x: offset.x, y: offset.y } })
     );
   }
   /** Dispatch a file drop onto this element. `data` is base64-encoded. */
   async dropFiles(files) {
     await this.withTarget(
       (target) => this.window.call("drop", {
-        ...targetParams(target),
+        ...this.scoped(target),
         files
       })
     );
   }
   async attributes() {
     return this.withTarget(async (target) => {
-      const value = expectRecord(await this.window.call("attrs", targetParams(target)), "attrs result");
+      const value = expectRecord(await this.window.call("attrs", this.scoped(target)), "attrs result");
       return Object.fromEntries(
         Object.entries(value).map(([name, attr]) => [name, expectString(attr, `attribute ${name}`)])
       );
     });
   }
   async isVisible() {
-    return this.withTarget(async (target) => {
-      const value = expectRecord(await this.window.call("visible", targetParams(target)), "visible result");
+    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");
     });
   }
   async isChecked() {
     return this.withTarget(async (target) => {
-      const value = expectRecord(await this.window.call("checked", targetParams(target)), "checked result");
+      const value = expectRecord(await this.window.call("checked", this.scoped(target)), "checked result");
       return expectBoolean(value.checked, "checked.checked");
     });
   }
   async count() {
     const total = this.query.kind === "selector" && !this.query.filters?.length ? expectNumber(
-      expectRecord(await this.window.call("count", { selector: this.query.selector }), "count result").count,
+      expectRecord(
+        await this.window.call("count", { selector: this.query.selector, ...this.frameParams() }),
+        "count result"
+      ).count,
       "count.count"
     ) : (await this.resolveAll()).length;
     if (this.query.index === void 0) return total;
@@ -1003,7 +1400,8 @@ var HasgardLocator = class _HasgardLocator {
       await this.window.call("wait", {
         selector: this.query.selector,
         gone: options.state === "detached",
-        timeout: options.timeoutMs
+        timeout: options.timeoutMs,
+        ...this.frameParams()
       });
       return;
     }
@@ -1046,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 };
     }
@@ -1054,15 +1452,30 @@ 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`);
     }
     return byRef(elements[0].ref);
   }
+  /**
+   * Serialize a target together with the frame chain this locator lives in.
+   *
+   * A ref carries its own document, so the bridge ignores `frame` for one; the
+   * chain still travels so that a selector or coordinate target -- which the
+   * bridge must resolve itself -- lands in the right document.
+   */
+  scoped(target) {
+    return { ...targetParams(target), ...this.frameParams() };
+  }
+  frameParams() {
+    return this.query.frame ? { frame: [...this.query.frame] } : {};
+  }
   async withTarget(operation) {
     return this.window.runExclusive(async () => operation(await this.resolveUnique()));
   }
@@ -1079,7 +1492,7 @@ var HasgardLocator = class _HasgardLocator {
       return this.runQuery(params);
     }
     const query = this.query;
-    const snapshot = await this.window.snapshot();
+    const snapshot = await this.window.snapshot(query.frame ? { frame: [...query.frame] } : {});
     return snapshot.elements.filter((element) => {
       if (element.role !== query.role) return false;
       const expected = query.query.name;
@@ -1110,7 +1523,7 @@ var HasgardLocator = class _HasgardLocator {
     return current;
   }
   async runQuery(params) {
-    return this.parseElements(await this.window.call("query", params), "query");
+    return this.parseElements(await this.window.call("query", { ...params, ...this.frameParams() }), "query");
   }
   parseElements(raw, source) {
     const value = expectRecord(raw, `${source} result`);
@@ -1169,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) => {
@@ -1180,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);
@@ -1194,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" });
+        }
       }
     }
   });
@@ -1206,6 +1631,7 @@ function createHasgardTest(config) {
 }
 export {
   HasgardApplication,
+  HasgardFrameLocator,
   HasgardLocator,
   HasgardProcess,
   HasgardRpcClient,