@nyssance/tauri-hasgard 0.2.1 → 0.3.0

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, ConsoleLogEntry, ConsoleLogOptions, DialogListing, DialogPolicy, DialogRecord, DialogType, DiffChange, DiffOptions, DragOffset, DropFile, FileInput, FilterOptions, FormEntry, FormField, FormsDump, HasgardFixtures, HasgardLaunchConfig, HasgardTarget, HasgardTestConfig, HasgardWorkerFixtures, JsonPrimitive, JsonValue, NativeScreenshot, NativeScreenshotOptions, NetworkRequestEntry, NetworkRequestOptions, QueryDimension, RecorderEntry, RecorderResult, RecorderStatus, RoleQuery, ScrollOptions, Snapshot, SnapshotDiff, SnapshotElement, SnapshotOptions, StorageEntry, StorageListing, StorageOptions, TextQuery, WaitForFunctionOptions, WaitOptions, WatchChanges, WatchNode, WatchOptions, WindowInfo, WindowState } from "./types.js";
-export { byPoint, byRef, bySelector, HasgardApplication, HasgardLocator, HasgardWindow } from "./window.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 { byPoint, byRef, bySelector, HasgardApplication, HasgardFrameLocator, HasgardLocator, HasgardWindow } from "./window.js";

package/dist/index.js

@@ -309,6 +309,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 +602,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)),
@@ -787,6 +850,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 +926,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 +976,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 +1008,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 +1023,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 +1076,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 +1085,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,21 +1119,21 @@ 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}`)])
       );
@@ -979,19 +1141,22 @@ var HasgardLocator = class _HasgardLocator {
   }
   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() {
     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 +1168,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;
     }
@@ -1063,6 +1229,19 @@ var HasgardLocator = class _HasgardLocator {
     }
     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 +1258,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 +1289,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`);
@@ -1206,6 +1385,7 @@ function createHasgardTest(config) {
 }
 export {
   HasgardApplication,
+  HasgardFrameLocator,
   HasgardLocator,
   HasgardProcess,
   HasgardRpcClient,

package/dist/types.d.ts

@@ -33,6 +33,11 @@ export interface SnapshotOptions {
     interactive?: boolean;
     selector?: string;
     depth?: number;
+    /**
+     * Take the snapshot inside this chain of same-origin iframes, one CSS
+     * selector per nesting level, instead of in the top document.
+     */
+    frame?: string[];
 }
 export interface WindowInfo {
     label: string;
@@ -71,6 +76,31 @@ export interface DragOffset {
     x: number;
     y: number;
 }
+/** A held keyboard modifier. Named as the platform reports them on the event. */
+export type KeyModifier = "Alt" | "Control" | "Meta" | "Shift";
+export type MouseButton = "left" | "middle" | "right";
+/** A point inside the element, measured from its top-left corner. */
+export interface ElementPosition {
+    x: number;
+    y: number;
+}
+export interface ClickOptions {
+    /**
+     * Modifiers held for the whole gesture. `Meta` is Command on macOS and the
+     * Windows key elsewhere -- the platform's own accelerator, which is why
+     * multi-select lists usually bind it rather than `Control`.
+     */
+    modifiers?: KeyModifier[];
+    /**
+     * Which button. `right` raises `contextmenu` and `middle` raises `auxclick`;
+     * neither raises `click`, exactly as a real press does not.
+     */
+    button?: MouseButton;
+    /** Presses in one gesture. `2` also raises a single `dblclick` at the end. */
+    clickCount?: number;
+    /** Where inside the element to press. Defaults to its centre. */
+    position?: ElementPosition;
+}
 export interface DropFile {
     name: string;
     /** Base64-encoded file contents. */
@@ -121,6 +151,49 @@ export interface DialogListing {
     dialogs: DialogRecord[];
     policy: DialogPolicy;
 }
+/** How a matched request is answered. */
+export interface RouteOptions {
+    /**
+     * Glob against the full URL. `*` stays inside one path segment, `**` crosses
+     * separators, and the pattern is anchored at both ends -- so `**\/api` does
+     * not also intercept `/v2/api-docs`.
+     */
+    pattern: string;
+    /** Restrict to one HTTP verb. Any verb matches when omitted. */
+    method?: string;
+    /** Stop matching after this many requests, letting later ones through. */
+    times?: number;
+}
+export interface FulfillOptions extends RouteOptions {
+    /** Defaults to 200. */
+    status?: number;
+    body?: string;
+    /** Defaults to `text/plain`. */
+    contentType?: string;
+}
+export interface RouteRule {
+    id: number;
+    pattern: string;
+    method: string | null;
+    action: "fulfill" | "abort";
+    status: number;
+    times: number | null;
+    /** How many requests this rule has already answered. */
+    used: number;
+}
+export interface InterceptedRequest {
+    id: number;
+    timestamp: number;
+    route_id: number;
+    method: string;
+    url: string;
+    action: "fulfill" | "abort";
+    status: number;
+}
+export interface RouteListing {
+    routes: RouteRule[];
+    intercepted: InterceptedRequest[];
+}
 export interface ConsoleLogOptions {
     level?: "log" | "warn" | "error" | "info";
     since?: number;

package/dist/window.d.ts

@@ -1,5 +1,5 @@
 import { HasgardRpcClient } from "./rpc-client.js";
-import type { BoundingBox, ConsoleLogEntry, ConsoleLogOptions, DialogListing, DialogPolicy, DiffOptions, DragOffset, DropFile, FileInput, FilterOptions, FormsDump, HasgardTarget, JsonValue, NativeScreenshot, NativeScreenshotOptions, NetworkRequestEntry, NetworkRequestOptions, QueryDimension, RecorderEntry, RecorderResult, RecorderStatus, RoleQuery, 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, 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;
@@ -44,6 +44,15 @@ export declare class HasgardWindow {
     getByTitle(text: string, query?: TextQuery): HasgardLocator;
     /** Test ids always match exactly, so `save` cannot select `save-draft`. */
     getByTestId(testId: string): HasgardLocator;
+    /**
+     * 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: string): HasgardFrameLocator;
     snapshot(options?: SnapshotOptions): Promise<Snapshot>;
     state(): Promise<WindowState>;
     url(): Promise<string>;
@@ -121,6 +130,36 @@ export declare class HasgardWindow {
         /** Forget the recorded dialogs. Leaves the accept/dismiss policy alone. */
         clear: () => Promise<void>;
     };
+    /**
+     * 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.
+     */
+    readonly routes: {
+        /** Answer matching requests with this response instead of the network. */
+        fulfill: (options: FulfillOptions) => Promise<{
+            id: number;
+        }>;
+        /** Fail matching requests the way a dropped connection does. */
+        abort: (options: RouteOptions) => Promise<{
+            id: number;
+        }>;
+        /** The active rules, their use counts, and every request they answered. */
+        list: () => Promise<RouteListing>;
+        /** Remove every rule and its interception log. */
+        clear: () => Promise<{
+            removed: number;
+        }>;
+    };
     /** This window's operating-system window id, where the platform exposes one. */
     nativeId(): Promise<number>;
     call<T>(method: string, params?: Record<string, JsonValue>): Promise<T>;
@@ -141,12 +180,46 @@ type LocatorQuery = ({
 }) & {
     index?: number;
     filters?: FilterOptions[];
+    frame?: string[];
 };
+/**
+ * The locator factories of a window, scoped to a chain of same-origin iframes.
+ *
+ * Mirrors the window's own factories rather than wrapping a locator, because a
+ * frame is a document to search in, not an element to search under: `#pay`
+ * inside the frame is not a descendant of `#pay` outside it.
+ */
+export declare class HasgardFrameLocator {
+    private readonly windowRef;
+    private readonly frame;
+    constructor(window: HasgardWindow, frame: string[]);
+    /** Descend into a frame nested inside this one. */
+    frameLocator(selector: string): HasgardFrameLocator;
+    locator(selector: string): HasgardLocator;
+    getByRole(role: string, query?: RoleQuery): HasgardLocator;
+    getByText(text: string, query?: TextQuery): HasgardLocator;
+    getByLabel(text: string, query?: TextQuery): HasgardLocator;
+    getByPlaceholder(text: string, query?: TextQuery): HasgardLocator;
+    getByAltText(text: string, query?: TextQuery): HasgardLocator;
+    getByTitle(text: string, query?: TextQuery): HasgardLocator;
+    getByTestId(testId: string): HasgardLocator;
+    /** Snapshot the frame's own document rather than the top one. */
+    snapshot(options?: SnapshotOptions): Promise<Snapshot>;
+    private byDimension;
+}
 export declare class HasgardLocator {
     readonly window: HasgardWindow;
     private readonly query;
     constructor(window: HasgardWindow, query: LocatorQuery);
-    click(): Promise<void>;
+    /**
+     * 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.
+     */
+    click(options?: ClickOptions): Promise<void>;
     fill(value: string): Promise<void>;
     type(text: string): Promise<void>;
     /** Empty the control, firing `input` and `change` as `fill` does. */
@@ -175,7 +248,8 @@ export declare class HasgardLocator {
     /** Flip the checkbox, whatever its current state. */
     toggle(): Promise<void>;
     hover(): Promise<void>;
-    dblclick(): Promise<void>;
+    /** Shorthand for `click({ clickCount: 2 })`; other options still apply. */
+    dblclick(options?: Omit<ClickOptions, "clickCount">): Promise<void>;
     focus(): Promise<void>;
     blur(): Promise<void>;
     /** Scroll this element's own scrollport. */
@@ -215,6 +289,15 @@ export declare class HasgardLocator {
     first(): HasgardLocator;
     last(): HasgardLocator;
     private resolveUnique;
+    /**
+     * 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.
+     */
+    private scoped;
+    private frameParams;
     private withTarget;
     private resolveAll;
     private resolveBase;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyssance/tauri-hasgard",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Playwright Test fixtures for native Tauri Hasgard automation",
   "type": "module",
   "main": "./dist/index.js",