@nyssance/tauri-hasgard 0.2.1 → 0.4.1

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

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

package/dist/process-manager.d.ts

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

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

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

package/dist/process-supervisor.js

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

package/dist/protocol-limits.d.ts

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

package/dist/protocol.d.ts

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

package/dist/protocol.test.d.ts

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

package/dist/types.d.ts

@@ -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,37 @@ 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";
+/** An application postcondition to await before another native press may focus a window. */
+export interface PressOptions {
+    completion?: "webview" | "native";
+    waitFor?: string;
+    timeoutMs?: number;
+}
+export type MouseButton = "left" | "middle" | "right";
+/** A point inside the element, measured from its top-left corner. */
+export interface ElementPosition {
+    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 +157,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, PressOptions, QueryDimension, RecorderEntry, RecorderResult, RecorderStatus, RoleQuery, RouteListing, RouteOptions, ScrollOptions, Snapshot, SnapshotDiff, SnapshotOptions, StorageListing, StorageOptions, TextQuery, WaitForFunctionOptions, WaitOptions, WatchChanges, WatchOptions, WindowInfo, WindowState } from "./types.js";
 export declare const byRef: (ref: string) => HasgardTarget;
 export declare const bySelector: (selector: string) => HasgardTarget;
 export declare const byPoint: (x: number, y: number) => HasgardTarget;
@@ -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>;
@@ -56,7 +65,7 @@ export declare class HasgardWindow {
     navigate(url: string): Promise<void>;
     /** Scroll the document by a relative amount, or to `top`/`bottom`. */
     scrollBy(options: ScrollOptions): Promise<void>;
-    press(key: string): Promise<void>;
+    press(key: string, options?: PressOptions): Promise<void>;
     diff(options?: DiffOptions): Promise<SnapshotDiff>;
     /**
      * Poll a JavaScript expression in the webview until it returns a truthy
@@ -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.4.1",
   "description": "Playwright Test fixtures for native Tauri Hasgard automation",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,12 +18,14 @@
     "NOTICE.md"
   ],
   "scripts": {
-    "build": "bun node_modules/tsup/dist/cli-default.js src/index.ts --format esm --outDir dist --clean && bun node_modules/typescript/bin/tsc -p tsconfig.json --noEmit false --emitDeclarationOnly --declaration true",
-    "dev": "tsup src/index.ts --format esm --dts --outDir dist --watch",
+    "build": "bun node_modules/tsup/dist/cli-default.js src/index.ts src/process-supervisor.js --format esm --outDir dist --clean && bun node_modules/typescript/bin/tsc -p tsconfig.json --noEmit false --emitDeclarationOnly --declaration true",
+    "dev": "bun run --parallel dev:js dev:types",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "dev:js": "tsup src/index.ts src/process-supervisor.js --format esm --outDir dist --watch",
+    "dev:types": "tsc -p tsconfig.json --noEmit false --emitDeclarationOnly --declaration true --watch"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.61.1 <2"