@nyssance/tauri-hasgard 0.1.2 → 0.2.1

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { createHasgardExpect } from "./expect.js";
 export { hasgardEndpointPath } from "./endpoint.js";
+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 { HasgardFixtures, HasgardLaunchConfig, HasgardTarget, HasgardTestConfig, HasgardWorkerFixtures, JsonPrimitive, JsonValue, RoleQuery, Snapshot, SnapshotElement, SnapshotOptions, WaitOptions, WindowInfo, WindowState } from "./types.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";

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,26 @@ 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 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 +330,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 +447,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 +484,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 +525,31 @@ 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: {} });
+  }
   async snapshot(options = {}) {
     const raw = expectRecord(
       await this.rpc.call("snapshot", withWindow(this.label, options)),
@@ -406,9 +579,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 +713,90 @@ 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");
+    }
+  };
+  /** 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,7 +816,7 @@ var HasgardWindow = class {
     }
   }
 };
-var HasgardLocator = class {
+var HasgardLocator = class _HasgardLocator {
   window;
   query;
   constructor(window, query) {
@@ -457,12 +832,95 @@ var HasgardLocator = class {
   async type(text) {
     await this.withTarget((target) => this.window.call("type", { ...targetParams(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", {
+        ...targetParams(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", { ...targetParams(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 }));
   }
+  /** 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 }));
+  }
+  /** 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 }));
+  }
+  /** Flip the checkbox, whatever its current state. */
+  async toggle() {
     await this.withTarget((target) => this.window.call("check", targetParams(target)));
   }
+  async hover() {
+    await this.withTarget((target) => this.window.call("hover", targetParams(target)));
+  }
+  async dblclick() {
+    await this.withTarget((target) => this.window.call("dblclick", targetParams(target)));
+  }
+  async focus() {
+    await this.withTarget((target) => this.window.call("focus", targetParams(target)));
+  }
+  async blur() {
+    await this.withTarget((target) => this.window.call("blur", targetParams(target)));
+  }
+  /** Scroll this element's own scrollport. */
+  async scrollBy(options) {
+    await this.withTarget(
+      (target) => this.window.call("scroll", { ...targetParams(target), ...options })
+    );
+  }
+  async boundingBox() {
+    return this.withTarget(async (target) => {
+      const value = expectRecord(await this.window.call("boundingBox", targetParams(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", targetParams(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")
@@ -473,6 +931,44 @@ var HasgardLocator = class {
       async (target) => expectString(await this.window.call("value", targetParams(target)), "value result")
     );
   }
+  async innerHTML() {
+    return this.withTarget(
+      async (target) => expectString(await this.window.call("html", targetParams(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: targetParams(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),
+        files
+      })
+    );
+  }
   async attributes() {
     return this.withTarget(async (target) => {
       const value = expectRecord(await this.window.call("attrs", targetParams(target)), "attrs result");
@@ -494,12 +990,16 @@ var HasgardLocator = class {
     });
   }
   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 }), "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",
@@ -509,17 +1009,57 @@ var HasgardLocator = class {
     }
     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);
   }
@@ -527,8 +1067,16 @@ var HasgardLocator = class {
     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();
@@ -541,7 +1089,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), "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 = {

package/dist/types.d.ts

@@ -6,10 +6,17 @@ export type HasgardTarget = {
     ref: string;
 } | {
     selector: string;
+    index?: number;
 } | {
     x: number;
     y: number;
 };
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 export interface SnapshotElement {
     ref: string;
     role: string;
@@ -31,6 +38,8 @@ export interface WindowInfo {
     label: string;
     url: string;
     title: string;
+    /** Operating-system window id. Present only where native capture exists. */
+    nativeId?: number;
 }
 export interface WindowState {
     url: string;
@@ -54,6 +63,202 @@ export interface WaitOptions {
     state: "attached" | "detached";
     timeoutMs: number;
 }
+export interface ScrollOptions {
+    direction: "up" | "down" | "left" | "right" | "top" | "bottom";
+    amount?: number;
+}
+export interface DragOffset {
+    x: number;
+    y: number;
+}
+export interface DropFile {
+    name: string;
+    /** Base64-encoded file contents. */
+    data: string;
+    type?: string;
+}
+/**
+ * A file to hand to the page: either a path on the test machine, which is read
+ * and encoded for you, or an in-memory payload for content that never existed
+ * as a file.
+ */
+export type FileInput = string | DropFile;
+/** Refinement applied to an existing locator. Both may be combined. */
+export interface FilterOptions {
+    /** Keep only elements whose subtree text matches. */
+    hasText?: string;
+    /** Drop elements whose subtree text matches. */
+    hasNotText?: string;
+    /** Require a whole-string match instead of a substring one. */
+    exact?: boolean;
+}
+export type DialogType = "alert" | "confirm" | "prompt";
+/** A modal the page opened while the standing policy decided its outcome. */
+export interface DialogRecord {
+    id: number;
+    timestamp: number;
+    type: DialogType;
+    message: string;
+    /** Whether the policy accepted it. A one-button `alert` is always accepted. */
+    accepted: boolean;
+    /** The page's suggested answer, for `prompt` only. */
+    defaultValue?: string;
+    /** What the page received back, for an accepted `prompt`. */
+    returned?: string;
+}
+/**
+ * How the next dialog will be answered.
+ *
+ * This is a standing policy rather than Playwright's per-event handler: the
+ * bridge must answer synchronously inside the page's `confirm()` call, with no
+ * chance to await a decision from the test process.
+ */
+export interface DialogPolicy {
+    action: "accept" | "dismiss";
+    promptText: string | null;
+}
+export interface DialogListing {
+    dialogs: DialogRecord[];
+    policy: DialogPolicy;
+}
+export interface ConsoleLogOptions {
+    level?: "log" | "warn" | "error" | "info";
+    since?: number;
+    sinceId?: number;
+    last?: number;
+}
+export interface ConsoleLogEntry {
+    id: number;
+    timestamp: number;
+    level: string;
+    args: JsonValue[];
+    source: string | null;
+}
+export interface NetworkRequestOptions {
+    filter?: string;
+    failedOnly?: boolean;
+    sinceId?: number;
+    last?: number;
+}
+export interface NetworkRequestEntry {
+    id: number;
+    timestamp: number;
+    method: string;
+    url: string;
+    status: number;
+    duration_ms: number;
+    error: string | null;
+    request_size: number;
+    response_size: number;
+}
+export interface StorageOptions {
+    /** Read and write `sessionStorage` instead of `localStorage`. */
+    session?: boolean;
+}
+export interface StorageEntry {
+    key: string;
+    value: string;
+}
+export interface StorageListing {
+    entries: StorageEntry[];
+    truncated: boolean;
+}
+export interface FormField {
+    tag: string;
+    type: string | null;
+    name: string;
+    value: string | string[];
+    checked?: boolean;
+}
+export interface FormEntry {
+    id: string;
+    name: string;
+    action: string;
+    method: string;
+    fields: FormField[];
+    fieldsTruncated?: boolean;
+}
+export interface FormsDump {
+    forms: FormEntry[];
+    truncated: boolean;
+}
+export type QueryDimension = "text" | "label" | "placeholder" | "testid" | "alt" | "title";
+export interface TextQuery {
+    /** Full, case-sensitive match. Whitespace is normalized either way. */
+    exact?: boolean;
+}
+export interface WaitForFunctionOptions {
+    timeoutMs?: number;
+    /** How often to re-evaluate the expression. Defaults to 50ms in the bridge. */
+    pollMs?: number;
+}
+export interface WatchOptions {
+    selector?: string;
+    timeoutMs?: number;
+    stableMs?: number;
+    requireMutation?: boolean;
+}
+export interface WatchNode {
+    tag: string;
+    id?: string;
+    class?: string;
+    text?: string;
+    attr?: string;
+    value?: string;
+}
+export interface WatchChanges {
+    added: WatchNode[];
+    removed: WatchNode[];
+    modified: WatchNode[];
+    truncated: boolean;
+}
+export interface DiffOptions extends SnapshotOptions {
+    /** Compare against this snapshot instead of the plugin's last stored one. */
+    reference?: Snapshot;
+}
+export interface DiffChange {
+    old: SnapshotElement;
+    new: SnapshotElement;
+    changes: string[];
+}
+export interface SnapshotDiff {
+    added: SnapshotElement[];
+    removed: SnapshotElement[];
+    changed: DiffChange[];
+}
+export interface NativeScreenshotOptions {
+    /** Absolute path; the parent directory must already exist. */
+    outputPath: string;
+    /**
+     * Operating-system window id. Resolved from the window's own label when
+     * omitted; pass it only to capture a window Hasgard does not own.
+     */
+    windowId?: number;
+}
+export interface NativeScreenshot {
+    output_path: string;
+    window_id: number;
+    width: number;
+    height: number;
+    scale_factor: number;
+    byte_size: number;
+    backend: string;
+    tcc_denied: boolean;
+}
+export interface RecorderEntry {
+    action: string;
+    timestamp: number;
+    [key: string]: JsonValue;
+}
+export interface RecorderStatus {
+    active: boolean;
+    count: number;
+    elapsed_ms: number;
+}
+export interface RecorderResult {
+    entries: RecorderEntry[];
+    count: number;
+}
 export interface HasgardLaunchConfig {
     command: string;
     args: string[];

package/dist/window.d.ts

@@ -1,5 +1,5 @@
 import { HasgardRpcClient } from "./rpc-client.js";
-import type { HasgardTarget, JsonValue, RoleQuery, Snapshot, SnapshotOptions, WaitOptions, WindowInfo, WindowState } from "./types.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";
 export declare const byRef: (ref: string) => HasgardTarget;
 export declare const bySelector: (selector: string) => HasgardTarget;
 export declare const byPoint: (x: number, y: number) => HasgardTarget;
@@ -14,6 +14,16 @@ export declare class HasgardApplication {
     waitForWindow(label: string, timeoutMs: number): Promise<HasgardWindow>;
     waitForWindowReady(label: string, readySelector: string, timeoutMs: number): Promise<HasgardWindow>;
     window(label: string): HasgardWindow;
+    /**
+     * Action recorder. Captures the RPC calls this connection makes into a
+     * replayable scenario — this is not video capture.
+     */
+    readonly recorder: {
+        start: () => Promise<void>;
+        stop: () => Promise<RecorderResult>;
+        status: () => Promise<RecorderStatus>;
+        add: (entry: RecorderEntry) => Promise<void>;
+    };
 }
 export declare class HasgardWindow {
     readonly label: string;
@@ -21,22 +31,116 @@ export declare class HasgardWindow {
     constructor(rpc: HasgardRpcClient, label: string);
     locator(selector: string): HasgardLocator;
     getByRole(role: string, query?: RoleQuery): HasgardLocator;
+    /**
+     * 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: 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;
+    /** Test ids always match exactly, so `save` cannot select `save-draft`. */
+    getByTestId(testId: string): HasgardLocator;
     snapshot(options?: SnapshotOptions): Promise<Snapshot>;
     state(): Promise<WindowState>;
+    url(): Promise<string>;
+    title(): Promise<string>;
+    /**
+     * 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`.
+     */
+    navigate(url: string): Promise<void>;
+    /** Scroll the document by a relative amount, or to `top`/`bottom`. */
+    scrollBy(options: ScrollOptions): Promise<void>;
     press(key: string): Promise<void>;
+    diff(options?: DiffOptions): Promise<SnapshotDiff>;
+    /**
+     * 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.
+     */
+    waitForFunction<T = JsonValue>(expression: string, options?: WaitForFunctionOptions): Promise<T>;
+    /** Observe DOM mutations until they settle, or reject when nothing changes. */
+    watch(options?: WatchOptions): Promise<WatchChanges>;
+    consoleLogs(options?: ConsoleLogOptions): Promise<ConsoleLogEntry[]>;
+    clearConsole(): Promise<void>;
+    networkRequests(options?: NetworkRequestOptions): Promise<NetworkRequestEntry[]>;
+    clearNetwork(): Promise<void>;
+    /** `localStorage` by default; pass `{ session: true }` for `sessionStorage`. */
+    readonly storage: {
+        get: (key: string, options?: StorageOptions) => Promise<string | null>;
+        set: (key: string, value: string, options?: StorageOptions) => Promise<void>;
+        list: (options?: StorageOptions) => Promise<StorageListing>;
+        clear: (options?: StorageOptions) => Promise<void>;
+    };
+    forms(selector?: string): Promise<FormsDump>;
     evaluate<T>(script: string): Promise<T>;
     invoke<T>(command: string, args: Record<string, JsonValue>): Promise<T>;
     screenshot(selector?: string): Promise<Buffer>;
+    /**
+     * 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.
+     */
+    screenshotNative(options: NativeScreenshotOptions): Promise<NativeScreenshot>;
+    /**
+     * 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.
+     */
+    wheel(deltaX: number, deltaY: number): Promise<boolean>;
+    /**
+     * 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.
+     */
+    readonly dialogs: {
+        /** Answer every subsequent dialog with OK. `promptText` fills a `prompt`. */
+        accept: (promptText?: string) => Promise<DialogPolicy>;
+        /** Answer every subsequent dialog with Cancel. This is the default. */
+        dismiss: () => Promise<DialogPolicy>;
+        /** Every dialog the page has opened so far, oldest first. */
+        list: () => Promise<DialogListing>;
+        /** Forget the recorded dialogs. Leaves the accept/dismiss policy alone. */
+        clear: () => Promise<void>;
+    };
+    /** 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>;
     runExclusive<T>(operation: () => Promise<T>): Promise<T>;
 }
-type LocatorQuery = {
+type LocatorQuery = ({
     kind: "selector";
     selector: string;
 } | {
     kind: "role";
     role: string;
     query: RoleQuery;
+} | {
+    kind: "query";
+    by: QueryDimension;
+    value: string;
+    query: TextQuery;
+}) & {
+    index?: number;
+    filters?: FilterOptions[];
 };
 export declare class HasgardLocator {
     readonly window: HasgardWindow;
@@ -45,17 +149,84 @@ export declare class HasgardLocator {
     click(): Promise<void>;
     fill(value: string): Promise<void>;
     type(text: string): Promise<void>;
+    /** Empty the control, firing `input` and `change` as `fill` does. */
+    clear(): Promise<void>;
+    /**
+     * 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.
+     */
+    setInputFiles(files: FileInput | FileInput[]): Promise<void>;
+    /**
+     * 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.
+     */
+    wheel(deltaX: number, deltaY: number): Promise<boolean>;
     selectOption(value: string): Promise<void>;
+    /** Drive the checkbox to checked. A no-op when it is already checked. */
     check(): Promise<void>;
+    /** Drive the checkbox to unchecked. A no-op when it is already unchecked. */
+    uncheck(): Promise<void>;
+    /** Flip the checkbox, whatever its current state. */
+    toggle(): Promise<void>;
+    hover(): Promise<void>;
+    dblclick(): Promise<void>;
+    focus(): Promise<void>;
+    blur(): Promise<void>;
+    /** Scroll this element's own scrollport. */
+    scrollBy(options: ScrollOptions): Promise<void>;
+    boundingBox(): Promise<BoundingBox>;
+    isDisabled(): Promise<boolean>;
+    isEnabled(): Promise<boolean>;
     textContent(): Promise<string>;
     inputValue(): Promise<string>;
+    innerHTML(): Promise<string>;
+    getAttribute(name: string): Promise<string | null>;
+    /** Drag this element onto another one in the same window. */
+    dragTo(target: HasgardLocator): Promise<void>;
+    /** Drag this element by a pixel offset from its centre. */
+    dragBy(offset: DragOffset): Promise<void>;
+    /** Dispatch a file drop onto this element. `data` is base64-encoded. */
+    dropFiles(files: DropFile[]): Promise<void>;
     attributes(): Promise<Record<string, string>>;
     isVisible(): Promise<boolean>;
     isChecked(): Promise<boolean>;
     count(): Promise<number>;
     waitFor(options: WaitOptions): Promise<void>;
+    /**
+     * 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: number): HasgardLocator;
+    /**
+     * 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: FilterOptions): HasgardLocator;
+    first(): HasgardLocator;
+    last(): HasgardLocator;
     private resolveUnique;
     private withTarget;
     private resolveAll;
+    private resolveBase;
+    /**
+     * 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.
+     */
+    private applyFilters;
+    private runQuery;
+    private parseElements;
 }
 export {};

package/package.json

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