@nyssance/tauri-hasgard 0.1.2 → 0.3.0

package/dist/index.js

@@ -1,3 +1,14 @@
+// src/endpoint.ts
+import { tmpdir } from "os";
+import { join } from "path";
+function endpointPathForPlatform(name, platform, temporaryDirectory) {
+  if (platform === "win32") return `\\\\.\\pipe\\${name}`;
+  return join(temporaryDirectory, `${name}.sock`);
+}
+function hasgardEndpointPath(name) {
+  return endpointPathForPlatform(name, process.platform, tmpdir());
+}
+
 // src/expect.ts
 async function poll(read, matches, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
@@ -49,17 +60,6 @@ function createHasgardExpect(playwrightExpect) {
   });
 }
 
-// src/endpoint.ts
-import { tmpdir } from "os";
-import { join } from "path";
-function endpointPathForPlatform(name, platform, temporaryDirectory) {
-  if (platform === "win32") return `\\\\.\\pipe\\${name}`;
-  return join(temporaryDirectory, `${name}.sock`);
-}
-function hasgardEndpointPath(name) {
-  return endpointPathForPlatform(name, process.platform, tmpdir());
-}
-
 // src/process-manager.ts
 import { spawn } from "child_process";
 import { access, rm } from "fs/promises";
@@ -270,6 +270,8 @@ var HasgardRpcClient = class {
 };
 
 // src/window.ts
+import { readFile } from "fs/promises";
+import { basename } from "path";
 var locks = /* @__PURE__ */ new WeakMap();
 function lockFor(rpc, label) {
   let clientLocks = locks.get(rpc);
@@ -290,11 +292,78 @@ var byPoint = (x, y) => ({ x, y });
 function withWindow(window, params) {
   return params ? { ...params, window } : { window };
 }
+async function readFileInputs(files) {
+  const list = Array.isArray(files) ? files : [files];
+  return Promise.all(
+    list.map(async (entry) => {
+      if (typeof entry !== "string") return entry;
+      const contents = await readFile(entry);
+      return { name: basename(entry), data: contents.toString("base64") };
+    })
+  );
+}
 function targetParams(target) {
   if ("ref" in target) return { ref: target.ref };
-  if ("selector" in target) return { selector: target.selector };
+  if ("selector" in target) {
+    return target.index === void 0 ? { selector: target.selector } : { selector: target.selector, index: target.index };
+  }
   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;
+}
 function expectRecord(value, context) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new Error(`${context} must be an object`);
@@ -313,6 +382,106 @@ function expectNumber(value, context) {
   if (typeof value !== "number") throw new Error(`${context} must be a number`);
   return value;
 }
+function expectArray(value, context) {
+  if (!Array.isArray(value)) throw new Error(`${context} must be an array`);
+  return value;
+}
+function expectNullableString(value, context) {
+  if (value === null) return null;
+  return expectString(value, context);
+}
+function optionalString(value, context) {
+  return value === void 0 ? void 0 : expectString(value, context);
+}
+function parseConsoleLogEntry(value, index) {
+  const entry = expectRecord(value, `console.getLogs[${index}]`);
+  return {
+    id: expectNumber(entry.id, `console.getLogs[${index}].id`),
+    timestamp: expectNumber(entry.timestamp, `console.getLogs[${index}].timestamp`),
+    level: expectString(entry.level, `console.getLogs[${index}].level`),
+    args: expectArray(entry.args, `console.getLogs[${index}].args`),
+    source: expectNullableString(entry.source, `console.getLogs[${index}].source`)
+  };
+}
+function parseNetworkRequestEntry(value, index) {
+  const entry = expectRecord(value, `network.getRequests[${index}]`);
+  return {
+    id: expectNumber(entry.id, `network.getRequests[${index}].id`),
+    timestamp: expectNumber(entry.timestamp, `network.getRequests[${index}].timestamp`),
+    method: expectString(entry.method, `network.getRequests[${index}].method`),
+    url: expectString(entry.url, `network.getRequests[${index}].url`),
+    status: expectNumber(entry.status, `network.getRequests[${index}].status`),
+    duration_ms: expectNumber(entry.duration_ms, `network.getRequests[${index}].duration_ms`),
+    error: expectNullableString(entry.error, `network.getRequests[${index}].error`),
+    request_size: expectNumber(entry.request_size, `network.getRequests[${index}].request_size`),
+    response_size: expectNumber(entry.response_size, `network.getRequests[${index}].response_size`)
+  };
+}
+function parseFormField(value, context) {
+  const field = expectRecord(value, context);
+  const raw = field.value;
+  const parsed = {
+    tag: expectString(field.tag, `${context}.tag`),
+    type: expectNullableString(field.type, `${context}.type`),
+    name: expectString(field.name, `${context}.name`),
+    value: Array.isArray(raw) ? raw.map((option, index) => expectString(option, `${context}.value[${index}]`)) : expectString(raw, `${context}.value`)
+  };
+  if (field.checked !== void 0) parsed.checked = expectBoolean(field.checked, `${context}.checked`);
+  return parsed;
+}
+function parseFormEntry(value, index) {
+  const context = `forms.dump.forms[${index}]`;
+  const form = expectRecord(value, context);
+  const parsed = {
+    id: expectString(form.id, `${context}.id`),
+    name: expectString(form.name, `${context}.name`),
+    action: expectString(form.action, `${context}.action`),
+    method: expectString(form.method, `${context}.method`),
+    fields: expectArray(form.fields, `${context}.fields`).map(
+      (field, fieldIndex) => parseFormField(field, `${context}.fields[${fieldIndex}]`)
+    )
+  };
+  if (form.fieldsTruncated !== void 0) {
+    parsed.fieldsTruncated = expectBoolean(form.fieldsTruncated, `${context}.fieldsTruncated`);
+  }
+  return parsed;
+}
+function parseWatchNode(value, context) {
+  const node = expectRecord(value, context);
+  const parsed = { tag: expectString(node.tag, `${context}.tag`) };
+  const id = optionalString(node.id, `${context}.id`);
+  if (id !== void 0) parsed.id = id;
+  const className = optionalString(node.class, `${context}.class`);
+  if (className !== void 0) parsed.class = className;
+  const text = optionalString(node.text, `${context}.text`);
+  if (text !== void 0) parsed.text = text;
+  const attr = optionalString(node.attr, `${context}.attr`);
+  if (attr !== void 0) parsed.attr = attr;
+  const attrValue = optionalString(node.value, `${context}.value`);
+  if (attrValue !== void 0) parsed.value = attrValue;
+  return parsed;
+}
+function parseWatchNodes(value, context) {
+  return expectArray(value, context).map((node, index) => parseWatchNode(node, `${context}[${index}]`));
+}
+function parseDiffChange(value, index) {
+  const change = expectRecord(value, `diff.changed[${index}]`);
+  return {
+    old: parseSnapshotElement(change.old, index),
+    new: parseSnapshotElement(change.new, index),
+    changes: expectArray(change.changes, `diff.changed[${index}].changes`).map(
+      (entry, entryIndex) => expectString(entry, `diff.changed[${index}].changes[${entryIndex}]`)
+    )
+  };
+}
+function parseRecorderEntry(value, index) {
+  const entry = expectRecord(value, `record.stop.entries[${index}]`);
+  return {
+    ...entry,
+    action: expectString(entry.action, `record.stop.entries[${index}].action`),
+    timestamp: expectNumber(entry.timestamp, `record.stop.entries[${index}].timestamp`)
+  };
+}
 var HasgardApplication = class {
   rpc;
   constructor(rpc) {
@@ -330,11 +499,15 @@ var HasgardApplication = class {
     if (!Array.isArray(value.windows)) throw new Error("windows.list.windows must be an array");
     return value.windows.map((entry, index) => {
       const window = expectRecord(entry, `windows[${index}]`);
-      return {
+      const info = {
         label: expectString(window.label, `windows[${index}].label`),
         url: expectString(window.url, `windows[${index}].url`),
         title: expectString(window.title, `windows[${index}].title`)
       };
+      if (window.native_id !== void 0) {
+        info.nativeId = expectNumber(window.native_id, `windows[${index}].native_id`);
+      }
+      return info;
     });
   }
   async waitForWindow(label, timeoutMs) {
@@ -363,6 +536,33 @@ var HasgardApplication = class {
   window(label) {
     return new HasgardWindow(this.rpc, label);
   }
+  /**
+   * Action recorder. Captures the RPC calls this connection makes into a
+   * replayable scenario — this is not video capture.
+   */
+  recorder = {
+    start: async () => {
+      await this.rpc.call("record.start");
+    },
+    stop: async () => {
+      const value = expectRecord(await this.rpc.call("record.stop"), "record.stop result");
+      return {
+        entries: expectArray(value.entries, "record.stop.entries").map(parseRecorderEntry),
+        count: expectNumber(value.count, "record.stop.count")
+      };
+    },
+    status: async () => {
+      const value = expectRecord(await this.rpc.call("record.status"), "record.status result");
+      return {
+        active: expectBoolean(value.active, "record.status.active"),
+        count: expectNumber(value.count, "record.status.count"),
+        elapsed_ms: expectNumber(value.elapsed_ms, "record.status.elapsed_ms")
+      };
+    },
+    add: async (entry) => {
+      await this.rpc.call("record.add", entry);
+    }
+  };
 };
 var HasgardWindow = class {
   label;
@@ -377,6 +577,42 @@ var HasgardWindow = class {
   getByRole(role, query = {}) {
     return new HasgardLocator(this, { kind: "role", role, query });
   }
+  /**
+   * Locate by visible text. Matching runs in the page against the live DOM, not
+   * against a snapshot's `name`: that field collapses aria-label, alt, `<label>`,
+   * placeholder, and text into one 50-character string, so a button with an
+   * aria-label would never be findable by the text it actually shows.
+   */
+  getByText(text, query = {}) {
+    return new HasgardLocator(this, { kind: "query", by: "text", value: text, query });
+  }
+  getByLabel(text, query = {}) {
+    return new HasgardLocator(this, { kind: "query", by: "label", value: text, query });
+  }
+  getByPlaceholder(text, query = {}) {
+    return new HasgardLocator(this, { kind: "query", by: "placeholder", value: text, query });
+  }
+  getByAltText(text, query = {}) {
+    return new HasgardLocator(this, { kind: "query", by: "alt", value: text, query });
+  }
+  getByTitle(text, query = {}) {
+    return new HasgardLocator(this, { kind: "query", by: "title", value: text, query });
+  }
+  /** Test ids always match exactly, so `save` cannot select `save-draft`. */
+  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)),
@@ -406,9 +642,127 @@ var HasgardWindow = class {
       plugin_version: expectString(value.plugin_version, "state.plugin_version")
     };
   }
+  async url() {
+    return expectString(await this.rpc.call("url", withWindow(this.label)), "url result");
+  }
+  async title() {
+    return expectString(await this.rpc.call("title", withWindow(this.label)), "title result");
+  }
+  /**
+   * Navigate this webview by assigning `location.href`. Unlike Playwright's
+   * `goto`, this does not wait for the load to finish and returns no response —
+   * follow it with `waitFor` or `waitForWindowReady`.
+   */
+  async navigate(url) {
+    await this.rpc.call("navigate", withWindow(this.label, { url }));
+  }
+  /** Scroll the document by a relative amount, or to `top`/`bottom`. */
+  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 diff(options = {}) {
+    const { reference, ...snapshotOptions } = options;
+    const params = { ...snapshotOptions };
+    if (reference) params.reference = reference;
+    const value = expectRecord(await this.rpc.call("diff", withWindow(this.label, params)), "diff result");
+    return {
+      added: expectArray(value.added, "diff.added").map(parseSnapshotElement),
+      removed: expectArray(value.removed, "diff.removed").map(parseSnapshotElement),
+      changed: expectArray(value.changed, "diff.changed").map(parseDiffChange)
+    };
+  }
+  /**
+   * Poll a JavaScript expression in the webview until it returns a truthy
+   * value, and return that value. The expression is polled rather than driven
+   * by DOM mutations, so predicates that flip on a timer or a resolved fetch
+   * are caught too. A predicate that throws rejects instead of being retried.
+   */
+  async waitForFunction(expression, options = {}) {
+    const params = { expression };
+    if (options.timeoutMs !== void 0) params.timeout = options.timeoutMs;
+    if (options.pollMs !== void 0) params.poll = options.pollMs;
+    const value = expectRecord(await this.rpc.call("wait", withWindow(this.label, params)), "wait result");
+    return value.value;
+  }
+  /** Observe DOM mutations until they settle, or reject when nothing changes. */
+  async watch(options = {}) {
+    const params = {};
+    if (options.selector !== void 0) params.selector = options.selector;
+    if (options.timeoutMs !== void 0) params.timeout = options.timeoutMs;
+    if (options.stableMs !== void 0) params.stable = options.stableMs;
+    if (options.requireMutation !== void 0) params.requireMutation = options.requireMutation;
+    const value = expectRecord(await this.rpc.call("watch", withWindow(this.label, params)), "watch result");
+    return {
+      added: parseWatchNodes(value.added, "watch.added"),
+      removed: parseWatchNodes(value.removed, "watch.removed"),
+      modified: parseWatchNodes(value.modified, "watch.modified"),
+      truncated: expectBoolean(value.truncated, "watch.truncated")
+    };
+  }
+  async consoleLogs(options = {}) {
+    const value = await this.rpc.call(
+      "console.getLogs",
+      withWindow(this.label, options)
+    );
+    return expectArray(value, "console.getLogs result").map(parseConsoleLogEntry);
+  }
+  async clearConsole() {
+    await this.rpc.call("console.clear", withWindow(this.label));
+  }
+  async networkRequests(options = {}) {
+    const value = await this.rpc.call(
+      "network.getRequests",
+      withWindow(this.label, options)
+    );
+    return expectArray(value, "network.getRequests result").map(parseNetworkRequestEntry);
+  }
+  async clearNetwork() {
+    await this.rpc.call("network.clear", withWindow(this.label));
+  }
+  /** `localStorage` by default; pass `{ session: true }` for `sessionStorage`. */
+  storage = {
+    get: async (key, options = {}) => {
+      const value = expectRecord(
+        await this.rpc.call("storage.get", withWindow(this.label, { key, ...options })),
+        "storage.get result"
+      );
+      if (!expectBoolean(value.found, "storage.get.found")) return null;
+      return expectString(value.value, "storage.get.value");
+    },
+    set: async (key, value, options = {}) => {
+      await this.rpc.call("storage.set", withWindow(this.label, { key, value, ...options }));
+    },
+    list: async (options = {}) => {
+      const value = expectRecord(
+        await this.rpc.call("storage.list", withWindow(this.label, { ...options })),
+        "storage.list result"
+      );
+      return {
+        entries: expectArray(value.entries, "storage.list.entries").map((entry, index) => {
+          const parsed = expectRecord(entry, `storage.list.entries[${index}]`);
+          return {
+            key: expectString(parsed.key, `storage.list.entries[${index}].key`),
+            value: expectString(parsed.value, `storage.list.entries[${index}].value`)
+          };
+        }),
+        truncated: expectBoolean(value.truncated, "storage.list.truncated")
+      };
+    },
+    clear: async (options = {}) => {
+      await this.rpc.call("storage.clear", withWindow(this.label, { ...options }));
+    }
+  };
+  async forms(selector) {
+    const params = selector ? { selector } : void 0;
+    const value = expectRecord(await this.rpc.call("forms.dump", withWindow(this.label, params)), "forms.dump result");
+    return {
+      forms: expectArray(value.forms, "forms.dump.forms").map(parseFormEntry),
+      truncated: expectBoolean(value.truncated, "forms.dump.truncated")
+    };
+  }
   async evaluate(script) {
     return this.rpc.call("eval", withWindow(this.label, { script }));
   }
@@ -422,6 +776,137 @@ var HasgardWindow = class {
     if (!dataUrl.startsWith(prefix)) throw new Error("screenshot result is not a PNG data URL");
     return Buffer.from(dataUrl.slice(prefix.length), "base64");
   }
+  /**
+   * Capture this window through the native compositor, writing a PNG to
+   * `outputPath`. macOS only.
+   *
+   * Unlike `screenshot`, which renders the DOM inside the page, this records
+   * what the window server actually shows — so it sees native chrome, layered
+   * content, and anything the DOM renderer cannot reproduce.
+   *
+   * The operating-system window id is resolved from this window's label, so
+   * callers do not have to discover it themselves.
+   */
+  async screenshotNative(options) {
+    const windowId = options.windowId ?? await this.nativeId();
+    const value = expectRecord(
+      await this.rpc.call("screenshot_native", {
+        window_id: windowId,
+        output_path: options.outputPath
+      }),
+      "screenshot_native result"
+    );
+    return {
+      output_path: expectString(value.output_path, "screenshot_native.output_path"),
+      window_id: expectNumber(value.window_id, "screenshot_native.window_id"),
+      width: expectNumber(value.width, "screenshot_native.width"),
+      height: expectNumber(value.height, "screenshot_native.height"),
+      scale_factor: expectNumber(value.scale_factor, "screenshot_native.scale_factor"),
+      byte_size: expectNumber(value.byte_size, "screenshot_native.byte_size"),
+      backend: expectString(value.backend, "screenshot_native.backend"),
+      tcc_denied: expectBoolean(value.tcc_denied, "screenshot_native.tcc_denied")
+    };
+  }
+  /**
+   * Scroll the page by wheel.
+   *
+   * The document sees a real `wheel` event first and may cancel it; the scroll
+   * only follows if it does not. Resolves to whether the page cancelled — which
+   * is how you tell "the app intercepted my wheel" from "nothing was
+   * listening". Use the locator method to scroll a nested scrollport.
+   */
+  async wheel(deltaX, deltaY) {
+    const value = expectRecord(await this.call("wheel", { deltaX, deltaY }), "wheel result");
+    return expectBoolean(value.defaultPrevented, "wheel.defaultPrevented");
+  }
+  /**
+   * The page's modal dialogs (`alert`, `confirm`, `prompt`).
+   *
+   * These block the webview until answered, so the bridge always answers them —
+   * dismissing by default, as Playwright does. A test that never touches this
+   * namespace still cannot hang on a `confirm()`, and can read back what the
+   * app tried to ask.
+   */
+  dialogs = {
+    /** Answer every subsequent dialog with OK. `promptText` fills a `prompt`. */
+    accept: async (promptText) => {
+      const params = { action: "accept" };
+      if (promptText !== void 0) params.promptText = promptText;
+      return parseDialogPolicy(await this.call("dialog.handle", params));
+    },
+    /** Answer every subsequent dialog with Cancel. This is the default. */
+    dismiss: async () => parseDialogPolicy(await this.call("dialog.handle", { action: "dismiss" })),
+    /** Every dialog the page has opened so far, oldest first. */
+    list: async () => {
+      const value = expectRecord(await this.call("dialog.list"), "dialog.list result");
+      if (!Array.isArray(value.dialogs)) throw new Error("dialog.list.dialogs must be an array");
+      return {
+        dialogs: value.dialogs.map((entry, index) => parseDialogRecord(entry, index)),
+        policy: parseDialogPolicy(value.policy)
+      };
+    },
+    /** Forget the recorded dialogs. Leaves the accept/dismiss policy alone. */
+    clear: async () => {
+      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();
+    const self = listing.find((entry) => entry.label === this.label);
+    if (!self) throw new Error(`Window '${this.label}' is no longer open`);
+    if (self.nativeId === void 0) {
+      throw new Error(`Window '${this.label}' has no native window id on this platform`);
+    }
+    return self.nativeId;
+  }
   async call(method, params) {
     return this.rpc.call(method, withWindow(this.label, params));
   }
@@ -441,41 +926,214 @@ var HasgardWindow = class {
     }
   }
 };
-var HasgardLocator = 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;
   constructor(window, query) {
     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() {
+    await this.fill("");
+  }
+  /**
+   * Select files on an `<input type="file">` without a native file chooser,
+   * which an embedded webview gives no way to drive.
+   *
+   * Strings are read from the test machine's disk; `DropFile` payloads let you
+   * supply content that never existed as a file. An empty array deselects.
+   */
+  async setInputFiles(files) {
+    const payloads = await readFileInputs(files);
+    await this.withTarget(
+      (target) => this.window.call("setInputFiles", {
+        ...this.scoped(target),
+        files: payloads
+      })
+    );
+  }
+  /**
+   * Scroll this element by wheel.
+   *
+   * The page sees a real `wheel` event first and may cancel it; the scroll only
+   * follows if it does not — the same two steps a physical wheel produces.
+   * Resolves to whether the page cancelled.
+   */
+  async wheel(deltaX, deltaY) {
+    return this.withTarget(async (target) => {
+      const value = expectRecord(
+        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)));
+    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", { ...this.scoped(target), checked: false }));
+  }
+  /** Flip the checkbox, whatever its current state. */
+  async toggle() {
+    await this.withTarget((target) => this.window.call("check", this.scoped(target)));
+  }
+  async hover() {
+    await this.withTarget((target) => this.window.call("hover", this.scoped(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", this.scoped(target)));
+  }
+  async blur() {
+    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", { ...this.scoped(target), ...options })
+    );
+  }
+  async boundingBox() {
+    return this.withTarget(async (target) => {
+      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"),
+        width: expectNumber(value.width, "boundingBox.width"),
+        height: expectNumber(value.height, "boundingBox.height")
+      };
+    });
+  }
+  async isDisabled() {
+    return this.withTarget(async (target) => {
+      const value = expectRecord(await this.window.call("disabled", this.scoped(target)), "disabled result");
+      return expectBoolean(value.disabled, "disabled.disabled");
+    });
+  }
+  async isEnabled() {
+    return !await this.isDisabled();
   }
   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", this.scoped(target)), "html result")
+    );
+  }
+  async getAttribute(name) {
+    const attributes = await this.attributes();
+    return Object.prototype.hasOwnProperty.call(attributes, name) ? attributes[name] : null;
+  }
+  /** Drag this element onto another one in the same window. */
+  async dragTo(target) {
+    if (target.window !== this.window) {
+      throw new Error("dragTo requires both locators to belong to the same window");
+    }
+    await this.window.runExclusive(async () => {
+      const source = await this.resolveUnique();
+      const destination = await target.resolveUnique();
+      await this.window.call("drag", {
+        source: targetParams(source),
+        target: targetParams(destination)
+      });
+    });
+  }
+  /** Drag this element by a pixel offset from its centre. */
+  async dragBy(offset) {
+    await this.withTarget(
+      (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", {
+        ...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}`)])
       );
@@ -483,55 +1141,124 @@ var HasgardLocator = class {
   }
   async isVisible() {
     return this.withTarget(async (target) => {
-      const value = expectRecord(await this.window.call("visible", targetParams(target)), "visible result");
+      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() {
-    if (this.query.kind === "role") return (await this.resolveAll()).length;
-    const value = expectRecord(await this.window.call("count", { selector: this.query.selector }), "count result");
-    return expectNumber(value.count, "count.count");
+    const total = this.query.kind === "selector" && !this.query.filters?.length ? expectNumber(
+      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;
+    const position = absoluteIndex(this.query.index, total);
+    return position >= 0 && position < total ? 1 : 0;
   }
   async waitFor(options) {
-    if (this.query.kind === "selector") {
+    if (this.query.kind === "selector" && this.query.index === void 0 && !this.query.filters?.length) {
       await this.window.call("wait", {
         selector: this.query.selector,
         gone: options.state === "detached",
-        timeout: options.timeoutMs
+        timeout: options.timeoutMs,
+        ...this.frameParams()
       });
       return;
     }
     const deadline = Date.now() + options.timeoutMs;
     while (Date.now() <= deadline) {
-      const found = (await this.resolveAll()).length > 0;
+      const found = await this.count() > 0;
       if (found === (options.state === "attached")) return;
       await new Promise((resolve) => setTimeout(resolve, 50));
     }
-    throw new Error(`Role locator did not become ${options.state} within ${options.timeoutMs}ms`);
+    throw new Error(`Locator did not become ${options.state} within ${options.timeoutMs}ms`);
+  }
+  /**
+   * Narrow this locator to a single match by position. A negative index counts
+   * back from the end, so `last()` stays one round trip.
+   */
+  nth(index) {
+    if (!Number.isInteger(index)) throw new Error("nth requires an integer index");
+    return new _HasgardLocator(this.window, { ...this.query, index });
+  }
+  /**
+   * Narrow this locator to the elements whose text matches.
+   *
+   * Filters accumulate, so `filter({hasText}).filter({hasNotText})` applies
+   * both. Ordering matters against `nth`: filtering happens first, so
+   * `filter({hasText: "x"}).first()` is the first *matching* element, which is
+   * the reading that makes `first()` mean what it says.
+   */
+  filter(options) {
+    if (options.hasText === void 0 && options.hasNotText === void 0) {
+      throw new Error("filter requires hasText or hasNotText");
+    }
+    return new _HasgardLocator(this.window, {
+      ...this.query,
+      filters: [...this.query.filters ?? [], options]
+    });
+  }
+  first() {
+    return this.nth(0);
+  }
+  last() {
+    return this.nth(-1);
   }
   async resolveUnique() {
-    if (this.query.kind === "selector") return bySelector(this.query.selector);
+    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 };
+    }
     const elements = await this.resolveAll();
+    if (this.query.index !== void 0) {
+      const element = elements[absoluteIndex(this.query.index, elements.length)];
+      if (!element) {
+        throw new Error(`Locator has no element at index ${this.query.index} (${elements.length} matched)`);
+      }
+      return byRef(element.ref);
+    }
     if (elements.length !== 1) {
-      throw new Error(`Role locator resolved to ${elements.length} elements; expected exactly one`);
+      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()));
   }
   async resolveAll() {
+    return this.applyFilters(await this.resolveBase());
+  }
+  async resolveBase() {
     if (this.query.kind === "selector") {
-      throw new Error("resolveAll is only valid for role locators");
+      return this.runQuery({ by: "selector", value: this.query.selector });
+    }
+    if (this.query.kind === "query") {
+      const params = { by: this.query.by, value: this.query.value };
+      if (this.query.query.exact !== void 0) params.exact = this.query.query.exact;
+      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;
@@ -541,7 +1268,65 @@ var HasgardLocator = class {
       return query.query.exact ? element.name === expected : element.name.includes(expected);
     });
   }
+  /**
+   * Apply each accumulated filter, one round trip per filter.
+   *
+   * Filters run server-side rather than against a snapshot because the text a
+   * filter matches on is not carried in snapshot entries — deliberately, so
+   * that every unrelated `snapshot` call stays small.
+   */
+  async applyFilters(elements) {
+    const filters = this.query.filters ?? [];
+    let current = elements;
+    for (const filter of filters) {
+      if (current.length === 0) return current;
+      const params = { refs: current.map((element) => element.ref) };
+      if (filter.hasText !== void 0) params.hasText = filter.hasText;
+      if (filter.hasNotText !== void 0) params.hasNotText = filter.hasNotText;
+      if (filter.exact !== void 0) params.exact = filter.exact;
+      current = this.parseElements(await this.window.call("filter", params), "filter");
+    }
+    return current;
+  }
+  async runQuery(params) {
+    return this.parseElements(await this.window.call("query", { ...params, ...this.frameParams() }), "query");
+  }
+  parseElements(raw, source) {
+    const value = expectRecord(raw, `${source} result`);
+    if (!Array.isArray(value.elements)) throw new Error(`${source}.elements must be an array`);
+    return value.elements.map((entry, index) => parseSnapshotElement(entry, index));
+  }
 };
+function parseDialogPolicy(value) {
+  const record = expectRecord(value, "dialog policy");
+  const action = expectString(record.action, "dialog policy.action");
+  if (action !== "accept" && action !== "dismiss") {
+    throw new Error(`dialog policy.action must be "accept" or "dismiss", got ${action}`);
+  }
+  return {
+    action,
+    promptText: record.promptText == null ? null : expectString(record.promptText, "dialog policy.promptText")
+  };
+}
+function parseDialogRecord(value, index) {
+  const entry = expectRecord(value, `dialogs[${index}]`);
+  const type = expectString(entry.type, `dialogs[${index}].type`);
+  if (type !== "alert" && type !== "confirm" && type !== "prompt") {
+    throw new Error(`dialogs[${index}].type must be alert, confirm, or prompt, got ${type}`);
+  }
+  const record = {
+    id: expectNumber(entry.id, `dialogs[${index}].id`),
+    timestamp: expectNumber(entry.timestamp, `dialogs[${index}].timestamp`),
+    type,
+    message: expectString(entry.message, `dialogs[${index}].message`),
+    accepted: expectBoolean(entry.accepted, `dialogs[${index}].accepted`)
+  };
+  if (entry.defaultValue !== void 0) {
+    record.defaultValue = expectString(entry.defaultValue, `dialogs[${index}].defaultValue`);
+  }
+  if (entry.returned !== void 0) record.returned = expectString(entry.returned, `dialogs[${index}].returned`);
+  return record;
+}
 function parseSnapshotElement(value, index) {
   const entry = expectRecord(value, `snapshot.elements[${index}]`);
   const element = {
@@ -600,6 +1385,7 @@ function createHasgardTest(config) {
 }
 export {
   HasgardApplication,
+  HasgardFrameLocator,
   HasgardLocator,
   HasgardProcess,
   HasgardRpcClient,