@warlock.js/core 5.33.0 → 5.34.1

package/esm/e2e/owned-process.mjs

@@ -0,0 +1,193 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+import { execFile, spawn } from "node:child_process";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+
+//#region ../../packages/core/src/e2e/owned-process.ts
+const supervisorSource = `
+import { spawn } from 'node:child_process';
+process.on('SIGTERM', () => {});
+process.on('SIGINT', () => {});
+process.on('message', ({command}) => {
+  const child = spawn(command[0], command.slice(1), {cwd:process.cwd(),env:process.env,stdio:'inherit'});
+  child.once('spawn', () => process.send?.({type:'started',pid:child.pid}));
+  child.once('error', error => process.send?.({type:'failure',message:error.message}));
+  child.once('exit', (code,signal) => process.send?.({type:'exit',code,signal}));
+});
+`;
+/** Small OS identity queries; every helper PID is retained as evidence too. */
+function utility(command, args, records) {
+	return new Promise((resolve, reject) => {
+		const child = execFile(command, args, { encoding: "utf8" }, (error, stdout) => {
+			if (record) record.stopped = true;
+			if (error) reject(error);
+			else resolve(stdout);
+		});
+		const record = child.pid ? {
+			role: "process-identity",
+			pid: child.pid,
+			command: [command, ...args],
+			ownerFile: ""
+		} : void 0;
+		if (record) records.push(record);
+	});
+}
+function commandLineOwns(commandLine, ownerFile) {
+	if (commandLine.includes("\0")) return commandLine.split("\0").includes(ownerFile);
+	return commandLine.includes(ownerFile);
+}
+var OwnedProcess = class OwnedProcess {
+	constructor(child, record, records) {
+		this.child = child;
+		this.records = records;
+		this.output = "";
+		this.record = record;
+		records.push(record);
+		const append = (chunk) => {
+			this.output = (this.output + chunk.toString()).slice(-1e6);
+		};
+		child.stdout?.on("data", append);
+		child.stderr?.on("data", append);
+		child.on("message", (message) => {
+			const data = message;
+			if (data.type === "exit") this.finished = {
+				code: data.code ?? null,
+				signal: data.signal ?? null
+			};
+		});
+	}
+	static async start(role, command, directory, env, ownerDirectory, records, onCreated) {
+		const ownerFile = join(ownerDirectory, `owner-${randomUUID()}.mjs`);
+		await writeFile(ownerFile, supervisorSource, { mode: 384 });
+		const child = spawn(process.execPath, [ownerFile], {
+			cwd: directory,
+			env,
+			detached: process.platform !== "win32",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe",
+				"ipc"
+			]
+		});
+		if (!child.pid) {
+			await new Promise((_resolve, reject) => child.once("error", reject));
+			throw new Error(`Could not start ${role}`);
+		}
+		const owned = new OwnedProcess(child, {
+			role,
+			pid: child.pid,
+			command: [...command],
+			ownerFile
+		}, records);
+		onCreated?.(owned);
+		try {
+			await new Promise((resolve, reject) => {
+				const cleanup = () => {
+					clearTimeout(timer);
+					child.removeListener("message", message);
+					child.removeListener("error", failed);
+					child.removeListener("exit", exited);
+				};
+				const failed = (error) => {
+					cleanup();
+					reject(error);
+				};
+				const exited = () => failed(/* @__PURE__ */ new Error(`${role} supervisor exited before startup`));
+				const message = (value) => {
+					const data = value;
+					if (data.type === "started" && typeof data.pid === "number") {
+						owned.record.childPid = data.pid;
+						cleanup();
+						resolve();
+					}
+					if (data.type === "failure") failed(/* @__PURE__ */ new Error(`${role}: ${data.message}`));
+				};
+				const timer = setTimeout(() => failed(/* @__PURE__ */ new Error(`${role} process startup timed out`)), 1e4);
+				child.on("message", message);
+				child.once("error", failed);
+				child.once("exit", exited);
+				child.send({ command }, (error) => {
+					if (error) failed(error);
+				});
+			});
+			return owned;
+		} catch (error) {
+			try {
+				await owned.stop();
+			} catch (cleanup) {
+				throw new AggregateError([error, cleanup], `Process startup and verified cleanup failed: ${String(error)}; ${String(cleanup)}`);
+			}
+			throw error;
+		}
+	}
+	logs() {
+		return this.output;
+	}
+	assertRunning() {
+		if (this.finished || this.child.exitCode !== null || this.child.signalCode !== null) throw new Error(`${this.record.role} exited: ${JSON.stringify(this.finished)}\n${this.output.slice(-8e3)}`);
+	}
+	async wait(timeoutMs, signal) {
+		const deadline = Date.now() + timeoutMs;
+		while (!this.finished && Date.now() < deadline) {
+			signal?.throwIfAborted();
+			await setTimeout$1(25);
+		}
+		if (!this.finished) throw new Error(`${this.record.role} timed out after ${timeoutMs}ms\n${this.output.slice(-8e3)}`);
+		if (this.finished.code !== 0) throw new Error(`${this.record.role} failed: ${JSON.stringify(this.finished)}\n${this.output.slice(-8e3)}`);
+	}
+	async verify() {
+		if (this.child.exitCode !== null || this.child.signalCode !== null) throw new Error(`Refusing cleanup: ${this.record.role} group anchor ${this.record.pid} exited unexpectedly`);
+		let commandLine;
+		if (process.platform === "linux") commandLine = await readFile(`/proc/${this.record.pid}/cmdline`, "utf8");
+		else if (process.platform === "win32") commandLine = await utility("powershell.exe", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			`(Get-CimInstance Win32_Process -Filter 'ProcessId = ${this.record.pid}').CommandLine`
+		], this.records);
+		else commandLine = await utility("/bin/ps", [
+			"-p",
+			String(this.record.pid),
+			"-o",
+			"command="
+		], this.records);
+		if (!commandLineOwns(commandLine, this.record.ownerFile)) throw new Error(`Refusing cleanup: PID ${this.record.pid} command line does not contain its recorded owner file`);
+	}
+	stop() {
+		this.stopping ??= this.stopOwnedGroup().catch((error) => {
+			this.stopping = void 0;
+			throw error;
+		});
+		return this.stopping;
+	}
+	async stopOwnedGroup() {
+		await this.verify();
+		const exited = new Promise((resolve) => this.child.once("exit", () => resolve()));
+		if (process.platform === "win32") await utility("taskkill.exe", [
+			"/PID",
+			String(this.record.pid),
+			"/T",
+			"/F"
+		], this.records);
+		else {
+			process.kill(-this.record.pid, "SIGTERM");
+			await setTimeout$1(250);
+			await this.verify();
+			process.kill(-this.record.pid, "SIGKILL");
+		}
+		await new Promise((resolve, reject) => {
+			const timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`Owned ${this.record.role} PID ${this.record.pid} did not exit`)), 5e3);
+			exited.then(() => {
+				clearTimeout(timer);
+				resolve();
+			});
+		});
+		this.record.stopped = true;
+	}
+};
+
+//#endregion
+export { OwnedProcess, commandLineOwns };
+//# sourceMappingURL=owned-process.mjs.map

package/esm/e2e/owned-process.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"owned-process.mjs","names":["delay"],"sources":["../../../../../../../../packages/core/src/e2e/owned-process.ts"],"sourcesContent":["import { execFile, spawn, type ChildProcess } from \"node:child_process\";\nimport { randomUUID } from \"node:crypto\";\nimport { readFile, writeFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { setTimeout as delay } from \"node:timers/promises\";\nimport type { Command, ProcessEvidence } from \"./types\";\n\n// A group anchor stays alive after the foreground command exits. This lets\n// teardown verify a live, unique command line before BOTH TERM and KILL,\n// including when the app crashed but left descendants behind.\nconst supervisorSource = `\nimport { spawn } from 'node:child_process';\nprocess.on('SIGTERM', () => {});\nprocess.on('SIGINT', () => {});\nprocess.on('message', ({command}) => {\n  const child = spawn(command[0], command.slice(1), {cwd:process.cwd(),env:process.env,stdio:'inherit'});\n  child.once('spawn', () => process.send?.({type:'started',pid:child.pid}));\n  child.once('error', error => process.send?.({type:'failure',message:error.message}));\n  child.once('exit', (code,signal) => process.send?.({type:'exit',code,signal}));\n});\n`;\n\n/** Small OS identity queries; every helper PID is retained as evidence too. */\nfunction utility(command: string, args: string[], records: ProcessEvidence[]): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const child = execFile(command, args, { encoding: \"utf8\" }, (error, stdout) => {\n      if (record) record.stopped = true;\n      if (error) reject(error);\n      else resolve(stdout);\n    });\n    const record: ProcessEvidence | undefined = child.pid\n      ? { role: \"process-identity\", pid: child.pid, command: [command, ...args], ownerFile: \"\" }\n      : undefined;\n    if (record) records.push(record);\n  });\n}\n\nexport function commandLineOwns(commandLine: string, ownerFile: string): boolean {\n  if (commandLine.includes(\"\\0\")) return commandLine.split(\"\\0\").includes(ownerFile);\n  // ps/CIM expose a rendered command line; the random owner path is unique\n  // to this child, never an app name, binary name, PID search, or a port.\n  return commandLine.includes(ownerFile);\n}\n\nexport class OwnedProcess {\n  readonly record: ProcessEvidence;\n  private output = \"\";\n  private finished?: { code: number | null; signal: string | null };\n  private stopping?: Promise<void>;\n  private constructor(\n    private child: ChildProcess,\n    record: ProcessEvidence,\n    private records: ProcessEvidence[],\n  ) {\n    this.record = record;\n    records.push(record);\n    const append = (chunk: Buffer) => {\n      this.output = (this.output + chunk.toString()).slice(-1_000_000);\n    };\n    child.stdout?.on(\"data\", append);\n    child.stderr?.on(\"data\", append);\n    child.on(\"message\", (message: unknown) => {\n      const data = message as { type?: string; code?: number | null; signal?: string | null };\n      if (data.type === \"exit\")\n        this.finished = { code: data.code ?? null, signal: data.signal ?? null };\n    });\n  }\n\n  static async start(\n    role: string,\n    command: Command,\n    directory: string,\n    env: NodeJS.ProcessEnv,\n    ownerDirectory: string,\n    records: ProcessEvidence[],\n    onCreated?: (owned: OwnedProcess) => void,\n  ): Promise<OwnedProcess> {\n    const ownerFile = join(ownerDirectory, `owner-${randomUUID()}.mjs`);\n    await writeFile(ownerFile, supervisorSource, { mode: 0o600 });\n    // detached makes the recorded supervisor PID its process-group ID on POSIX.\n    // https://nodejs.org/download/release/v22.15.0/docs/api/child_process.html#optionsdetached\n    const child = spawn(process.execPath, [ownerFile], {\n      cwd: directory,\n      env,\n      detached: process.platform !== \"win32\",\n      stdio: [\"ignore\", \"pipe\", \"pipe\", \"ipc\"],\n    });\n    if (!child.pid) {\n      await new Promise<never>((_resolve, reject) => child.once(\"error\", reject));\n      throw new Error(`Could not start ${role}`);\n    }\n    const owned = new OwnedProcess(\n      child,\n      { role, pid: child.pid, command: [...command], ownerFile },\n      records,\n    );\n    onCreated?.(owned);\n    try {\n      await new Promise<void>((resolve, reject) => {\n        const cleanup = () => {\n          clearTimeout(timer);\n          child.removeListener(\"message\", message);\n          child.removeListener(\"error\", failed);\n          child.removeListener(\"exit\", exited);\n        };\n        const failed = (error: Error) => {\n          cleanup();\n          reject(error);\n        };\n        const exited = () => failed(new Error(`${role} supervisor exited before startup`));\n        const message = (value: unknown) => {\n          const data = value as { type?: string; pid?: number; message?: string };\n          if (data.type === \"started\" && typeof data.pid === \"number\") {\n            owned.record.childPid = data.pid;\n            cleanup();\n            resolve();\n          }\n          if (data.type === \"failure\") failed(new Error(`${role}: ${data.message}`));\n        };\n        const timer = setTimeout(\n          () => failed(new Error(`${role} process startup timed out`)),\n          10_000,\n        );\n        child.on(\"message\", message);\n        child.once(\"error\", failed);\n        child.once(\"exit\", exited);\n        child.send({ command }, (error) => {\n          if (error) failed(error);\n        });\n      });\n      return owned;\n    } catch (error) {\n      try {\n        await owned.stop();\n      } catch (cleanup) {\n        throw new AggregateError(\n          [error, cleanup],\n          `Process startup and verified cleanup failed: ${String(error)}; ${String(cleanup)}`,\n        );\n      }\n      throw error;\n    }\n  }\n\n  logs(): string {\n    return this.output;\n  }\n\n  assertRunning(): void {\n    if (this.finished || this.child.exitCode !== null || this.child.signalCode !== null) {\n      throw new Error(\n        `${this.record.role} exited: ${JSON.stringify(this.finished)}\\n${this.output.slice(-8000)}`,\n      );\n    }\n  }\n\n  async wait(timeoutMs: number, signal?: AbortSignal): Promise<void> {\n    const deadline = Date.now() + timeoutMs;\n    while (!this.finished && Date.now() < deadline) {\n      signal?.throwIfAborted();\n      await delay(25);\n    }\n    if (!this.finished)\n      throw new Error(\n        `${this.record.role} timed out after ${timeoutMs}ms\\n${this.output.slice(-8000)}`,\n      );\n    if (this.finished.code !== 0)\n      throw new Error(\n        `${this.record.role} failed: ${JSON.stringify(this.finished)}\\n${this.output.slice(-8000)}`,\n      );\n  }\n\n  private async verify(): Promise<void> {\n    if (this.child.exitCode !== null || this.child.signalCode !== null)\n      throw new Error(\n        `Refusing cleanup: ${this.record.role} group anchor ${this.record.pid} exited unexpectedly`,\n      );\n    let commandLine: string;\n    if (process.platform === \"linux\")\n      commandLine = await readFile(`/proc/${this.record.pid}/cmdline`, \"utf8\");\n    else if (process.platform === \"win32\") {\n      // PID is from spawn, interpolated as a number; no user text enters PowerShell.\n      // https://learn.microsoft.com/en-us/windows/win32/cimwin32prov/win32-process\n      commandLine = await utility(\n        \"powershell.exe\",\n        [\n          \"-NoProfile\",\n          \"-NonInteractive\",\n          \"-Command\",\n          `(Get-CimInstance Win32_Process -Filter 'ProcessId = ${this.record.pid}').CommandLine`,\n        ],\n        this.records,\n      );\n    } else\n      commandLine = await utility(\n        \"/bin/ps\",\n        [\"-p\", String(this.record.pid), \"-o\", \"command=\"],\n        this.records,\n      );\n    if (!commandLineOwns(commandLine, this.record.ownerFile))\n      throw new Error(\n        `Refusing cleanup: PID ${this.record.pid} command line does not contain its recorded owner file`,\n      );\n  }\n\n  stop(): Promise<void> {\n    this.stopping ??= this.stopOwnedGroup().catch((error: unknown) => {\n      this.stopping = undefined;\n      throw error;\n    });\n    return this.stopping;\n  }\n\n  private async stopOwnedGroup(): Promise<void> {\n    await this.verify();\n    const exited = new Promise<void>((resolve) => this.child.once(\"exit\", () => resolve()));\n    if (process.platform === \"win32\") {\n      // Windows has no POSIX process groups. /T targets this verified PID's tree.\n      // https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/taskkill\n      await utility(\"taskkill.exe\", [\"/PID\", String(this.record.pid), \"/T\", \"/F\"], this.records);\n    } else {\n      process.kill(-this.record.pid, \"SIGTERM\");\n      await delay(250);\n      await this.verify();\n      process.kill(-this.record.pid, \"SIGKILL\");\n    }\n    await new Promise<void>((resolve, reject) => {\n      const timer = setTimeout(\n        () => reject(new Error(`Owned ${this.record.role} PID ${this.record.pid} did not exit`)),\n        5000,\n      );\n      void exited.then(() => {\n        clearTimeout(timer);\n        resolve();\n      });\n    });\n    this.record.stopped = true;\n  }\n}\n"],"mappings":"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"}

package/esm/e2e/page.d.mts

@@ -0,0 +1,64 @@
+import { CdpConnection } from "./cdp.mjs";
+import { E2EEvidence, E2ESpec, Viewport } from "./types.mjs";
+//#region ../../packages/core/src/e2e/page.d.ts
+type WaitOptions = {
+  selector?: string;
+  text?: string;
+  url?: string;
+  timeoutMs?: number;
+};
+type ViewportReport = {
+  requestedWidth: number;
+  innerWidth: number;
+  documentWidth: number;
+  bodyWidth: number;
+  offenders: {
+    tag: string;
+    id: string;
+    className: string;
+    width: number;
+    scrollWidth: number;
+    right: number;
+    left: number;
+  }[];
+};
+export declare class BrowserPage {
+  private cdp;
+  private origin;
+  private outputDirectory;
+  private evidence;
+  private spec;
+  private viewport;
+  private loads;
+  private pendingRequests;
+  private requestUrls;
+  private lastNetworkActivity;
+  constructor(cdp: CdpConnection, origin: string, outputDirectory: string, evidence: E2EEvidence, spec: E2ESpec);
+  private completeRequest;
+  initialize(): Promise<void>;
+  step<T>(name: string, action: () => Promise<T>): Promise<T>;
+  evaluate<T = unknown>(expression: string, timeoutMs?: number): Promise<T>;
+  private poll;
+  goto(path: string, timeoutMs?: number): Promise<void>;
+  waitFor(options: WaitOptions): Promise<void>;
+  /** Arms the document/URL comparison BEFORE invoking the navigation action,
+   * covering full loads, reloads, hash changes and client-side routing.
+   */
+  waitForNavigation(action: () => Promise<unknown>, options?: {
+    url?: string;
+    timeoutMs?: number;
+  }): Promise<void>;
+  click(selector: string, timeoutMs?: number): Promise<void>;
+  fill(selector: string, value: string): Promise<void>;
+  /** Appends Unicode text through the browser's text-input path. */
+  type(selector: string, text: string): Promise<void>;
+  setViewport(viewport: Viewport): Promise<void>;
+  assertViewport(): Promise<ViewportReport>;
+  screenshot(name: string): Promise<string>;
+  captureViewports(name: string, viewports?: readonly Viewport[]): Promise<void>;
+  waitForNetworkIdle(timeoutMs?: number): Promise<void>;
+  assertHealthy(): void;
+}
+//#endregion
+export {};
+//# sourceMappingURL=page.d.mts.map

package/esm/e2e/page.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/e2e/page.ts"],"mappings":";;;KAaK;EAAgB;EAAmB;EAAe;EAAc;;KAEhE;EACH;EACA;EACA;EACA;EACA;IACE;IACA;IACA;IACA;IACA;IACA;IACA;;;qBAuDS;UAQD;UACA;UACA;UACA;UACA;UAXF;UACA;UACA;UACA;UACA;EAER,YACU,KAAK,eACL,gBACA,yBACA,UAAU,aACV,MAAM;UAgDR;EAMF,cAAc;EAQd,KAAK,GAAG,cAAc,cAAc,QAAQ,KAAK,QAAQ;EAqBzD,SAAS,aAAa,oBAAoB,qBAAqB,QAAQ;UAa/D;EAkBR,KAAK,cAAc,qBAAqB;EAkBxC,QAAQ,SAAS,cAAc;;;;EA0B/B,kBACJ,cAAc,kBACd;IAAW;IAAc;MACxB;EAkBG,MAAM,kBAAkB,qBAAqB;EA2E7C,KAAK,kBAAkB,gBAAgB;;EA4BvC,KAAK,kBAAkB,eAAe;EA0BtC,YAAY,UAAU,WAAW;EAuBjC,kBAAkB,QAAQ;EAoB1B,WAAW,eAAe;EAY1B,iBACJ,cACA,qBAAS,aACR;EAuBG,mBAAmB,qBAAqB;EAgB9C"}

package/esm/e2e/page.mjs

@@ -0,0 +1,376 @@
+import { defaultViewports, errorMessage, matches } from "./types.mjs";
+import { join } from "node:path";
+import { writeFile } from "node:fs/promises";
+import { setTimeout } from "node:timers/promises";
+
+//#region ../../packages/core/src/e2e/page.ts
+/** Runs inside the browser. Two paints plus cross-probe box comparison detect
+* scroll/animation/layout races. The hit test also accepts target descendants.
+*/
+function clickProbe(selector) {
+	return (async () => {
+		const empty = (reason) => ({
+			x: 0,
+			y: 0,
+			width: 0,
+			height: 0,
+			reason
+		});
+		const element = document.querySelector(selector);
+		if (!(element instanceof HTMLElement || element instanceof SVGElement)) return empty("target is missing or is not an HTML/SVG element");
+		element.scrollIntoView({
+			block: "center",
+			inline: "center",
+			behavior: "instant"
+		});
+		await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+		if (!element.isConnected || document.querySelector(selector) !== element) return empty("target was replaced during layout");
+		const box = element.getBoundingClientRect();
+		const x = box.x + box.width / 2;
+		const y = box.y + box.height / 2;
+		const style = getComputedStyle(element);
+		let reason = "";
+		if (box.width <= 0 || box.height <= 0 || style.visibility !== "visible" || style.display === "none" || Number(style.opacity) === 0) reason = "target is hidden or has an empty box";
+		else if (element.matches(":disabled") || element.closest("[inert], [aria-disabled=\"true\"]")) reason = "target is disabled or inert";
+		else if (x < 0 || y < 0 || x >= innerWidth || y >= innerHeight) reason = "target center is outside the viewport";
+		else {
+			const top = document.elementFromPoint(x, y);
+			if (!top || !element.contains(top)) reason = `target is covered by ${top?.tagName ?? "no element"}${top?.id ? "#" + top.id : ""}`;
+		}
+		return {
+			x,
+			y,
+			width: box.width,
+			height: box.height,
+			reason
+		};
+	})();
+}
+function boxesStable(first, second) {
+	return !first.reason && !second.reason && [
+		"x",
+		"y",
+		"width",
+		"height"
+	].every((key) => Math.abs(first[key] - second[key]) < .25);
+}
+var BrowserPage = class {
+	constructor(cdp, origin, outputDirectory, evidence, spec) {
+		this.cdp = cdp;
+		this.origin = origin;
+		this.outputDirectory = outputDirectory;
+		this.evidence = evidence;
+		this.spec = spec;
+		this.viewport = { ...defaultViewports[0] };
+		this.loads = 0;
+		this.pendingRequests = /* @__PURE__ */ new Map();
+		this.requestUrls = /* @__PURE__ */ new Map();
+		this.lastNetworkActivity = Date.now();
+		cdp.on("Page.loadEventFired", () => {
+			this.loads++;
+		});
+		cdp.on("Runtime.consoleAPICalled", ({ type, args }) => evidence.console.push({
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			level: type === "assert" ? "error" : type,
+			text: args.map((arg) => String(arg.value ?? arg.description ?? "")).join(" ")
+		}));
+		cdp.on("Runtime.exceptionThrown", ({ exceptionDetails }) => evidence.console.push({
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			level: "error",
+			text: exceptionDetails.exception?.description ?? exceptionDetails.text
+		}));
+		cdp.on("Log.entryAdded", ({ entry }) => evidence.console.push({
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			level: entry.level,
+			text: entry.text
+		}));
+		cdp.on("Network.requestWillBeSent", ({ requestId, request }) => {
+			this.pendingRequests.set(requestId, request.url);
+			this.requestUrls.set(requestId, request.url);
+			this.lastNetworkActivity = Date.now();
+		});
+		cdp.on("Network.responseReceived", ({ requestId, response }) => {
+			this.requestUrls.set(requestId, response.url);
+			if (response.status >= 400) evidence.networkFailures.push({
+				at: (/* @__PURE__ */ new Date()).toISOString(),
+				url: response.url,
+				status: response.status
+			});
+		});
+		cdp.on("Network.loadingFailed", ({ requestId, errorText, canceled }) => {
+			evidence.networkFailures.push({
+				at: (/* @__PURE__ */ new Date()).toISOString(),
+				url: this.requestUrls.get(requestId) ?? `unknown request ${requestId}`,
+				errorText,
+				canceled
+			});
+			this.completeRequest(requestId);
+		});
+		cdp.on("Network.loadingFinished", ({ requestId }) => this.completeRequest(requestId));
+	}
+	completeRequest(requestId) {
+		this.pendingRequests.delete(requestId);
+		this.requestUrls.delete(requestId);
+		this.lastNetworkActivity = Date.now();
+	}
+	async initialize() {
+		await this.cdp.command("Page.enable", {});
+		await this.cdp.command("Runtime.enable", {});
+		await this.cdp.command("Network.enable", {});
+		await this.cdp.command("Log.enable", {});
+		await this.setViewport(this.spec.viewports?.[0] ?? defaultViewports[0]);
+	}
+	async step(name, action) {
+		const start = performance.now();
+		const entry = {
+			name,
+			startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			durationMs: 0,
+			status: "passed",
+			error: void 0
+		};
+		this.evidence.steps.push(entry);
+		try {
+			return await action();
+		} catch (error) {
+			entry.status = "failed";
+			entry.error = errorMessage(error);
+			throw error;
+		} finally {
+			entry.durationMs = Math.round(performance.now() - start);
+		}
+	}
+	async evaluate(expression, timeoutMs = 1e4) {
+		const response = await this.cdp.command("Runtime.evaluate", {
+			expression,
+			returnByValue: true,
+			awaitPromise: true,
+			silent: true
+		}, timeoutMs);
+		if (response.exceptionDetails) throw new Error(`Browser evaluation failed: ${response.exceptionDetails.exception?.description ?? response.exceptionDetails.text}`);
+		return response.result.value;
+	}
+	async poll(description, check, timeoutMs) {
+		const deadline = Date.now() + timeoutMs;
+		let reason = "condition stayed false";
+		while (Date.now() < deadline) {
+			try {
+				if (await check(Math.max(1, deadline - Date.now()))) return;
+			} catch (error) {
+				reason = errorMessage(error);
+			}
+			await setTimeout(Math.min(50, Math.max(0, deadline - Date.now())));
+		}
+		throw new Error(`${description} timed out after ${timeoutMs}ms: ${reason}`);
+	}
+	async goto(path, timeoutMs = 1e4) {
+		await this.step(`goto ${path}`, async () => {
+			const url = new URL(path, this.origin).href;
+			const before = this.loads;
+			const navigation = await this.cdp.command("Page.navigate", { url }, timeoutMs);
+			if (navigation.errorText) throw new Error(`Navigation failed: ${navigation.errorText}`);
+			await this.poll(`Navigation to ${url}`, (remaining) => this.evaluate(`document.readyState === 'complete' && ${navigation.loaderId ? this.loads > before : "true"}`, remaining), timeoutMs);
+		});
+	}
+	async waitFor(options) {
+		if (options.selector === void 0 && options.text === void 0 && options.url === void 0) throw new Error("waitFor requires a selector, text, or URL");
+		await this.step(`waitFor ${JSON.stringify(options)}`, () => this.poll("waitFor " + JSON.stringify(options), (remaining) => this.evaluate(`(() => {
+      const options = ${JSON.stringify(options)};
+      const element = options.selector ? document.querySelector(options.selector) : document.body;
+      if (!element) return false;
+      if (options.selector) { const box=element.getBoundingClientRect(); const css=getComputedStyle(element); if (!box.width || !box.height || css.visibility !== 'visible') return false; }
+      return (options.text === undefined || (element.innerText ?? element.textContent ?? '').includes(options.text)) &&
+        (options.url === undefined || location.href === new URL(options.url, ${JSON.stringify(this.origin)}).href);
+    })()`, remaining), options.timeoutMs ?? 1e4));
+	}
+	/** Arms the document/URL comparison BEFORE invoking the navigation action,
+	* covering full loads, reloads, hash changes and client-side routing.
+	*/
+	async waitForNavigation(action, options = {}) {
+		await this.step("waitForNavigation", async () => {
+			const before = await this.evaluate("({href:location.href,timeOrigin:performance.timeOrigin})");
+			await action();
+			await this.poll("Navigation", (remaining) => this.evaluate(`document.readyState === 'complete' && (location.href !== ${JSON.stringify(before.href)} || performance.timeOrigin !== ${before.timeOrigin}) && ${options.url ? `location.href === ${JSON.stringify(new URL(options.url, this.origin).href)}` : "true"}`, remaining), options.timeoutMs ?? 1e4);
+		});
+	}
+	async click(selector, timeoutMs = 1e4) {
+		await this.step(`click ${selector}`, async () => {
+			const deadline = Date.now() + timeoutMs;
+			let previous;
+			let reason = "layout has not settled";
+			while (Date.now() < deadline) {
+				const remaining = () => Math.max(1, deadline - Date.now());
+				let box;
+				try {
+					box = await this.evaluate(`(${clickProbe.toString()})(${JSON.stringify(selector)})`, remaining());
+				} catch (error) {
+					reason = errorMessage(error);
+					previous = void 0;
+					await setTimeout(25);
+					continue;
+				}
+				reason = box.reason || "target box is moving";
+				if (previous && boxesStable(previous, box)) {
+					let hovered;
+					try {
+						await this.cdp.command("Input.dispatchMouseEvent", {
+							type: "mouseMoved",
+							x: box.x,
+							y: box.y
+						}, remaining());
+						hovered = await this.evaluate(`(${clickProbe.toString()})(${JSON.stringify(selector)})`, remaining());
+					} catch (error) {
+						reason = errorMessage(error);
+						previous = void 0;
+						await setTimeout(Math.min(25, remaining()));
+						continue;
+					}
+					if (Date.now() < deadline && boxesStable(box, hovered)) {
+						await this.cdp.command("Input.dispatchMouseEvent", {
+							type: "mousePressed",
+							x: hovered.x,
+							y: hovered.y,
+							button: "left",
+							buttons: 1,
+							clickCount: 1
+						}, remaining());
+						await this.cdp.command("Input.dispatchMouseEvent", {
+							type: "mouseReleased",
+							x: hovered.x,
+							y: hovered.y,
+							button: "left",
+							buttons: 0,
+							clickCount: 1
+						}, remaining());
+						return;
+					}
+					reason = hovered.reason || "hover changed the target box";
+					previous = void 0;
+				} else previous = box;
+				await setTimeout(Math.min(50, remaining()));
+			}
+			throw new Error(`Cannot click ${JSON.stringify(selector)} within ${timeoutMs}ms: ${reason}`);
+		});
+	}
+	async fill(selector, value) {
+		await this.step(`fill ${selector}`, async () => {
+			await this.click(selector);
+			await this.evaluate(`(() => {
+        const element=document.querySelector(${JSON.stringify(selector)});
+        if (element !== document.activeElement) throw new Error('Fill target lost focus');
+        if ((element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) && !element.readOnly && !element.disabled) {
+          const prototype=element instanceof HTMLInputElement ? HTMLInputElement.prototype : HTMLTextAreaElement.prototype;
+          const setter=Object.getOwnPropertyDescriptor(prototype,'value')?.set;
+          if (!setter) throw new Error('Fill target has no native value setter');
+          setter.call(element,'');
+        } else if (element instanceof HTMLElement && element.isContentEditable) element.textContent='';
+        else throw new Error('Fill target must be an editable input, textarea or contenteditable');
+        element.dispatchEvent(new Event('input',{bubbles:true}));
+      })()`);
+			await this.evaluate(`document.activeElement === document.querySelector(${JSON.stringify(selector)}) || (() => { throw new Error("Fill target lost focus after input"); })()`);
+			if (value) await this.cdp.command("Input.insertText", { text: value });
+			await this.evaluate("document.activeElement?.dispatchEvent(new Event('change',{bubbles:true}))");
+		});
+	}
+	/** Appends Unicode text through the browser's text-input path. */
+	async type(selector, text) {
+		await this.step(`type ${selector}`, async () => {
+			await this.click(selector);
+			if (await this.evaluate(`(() => { const element=document.querySelector(${JSON.stringify(selector)}); if (element !== document.activeElement || !((element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) && !element.readOnly && !element.disabled || element instanceof HTMLElement && element.isContentEditable)) throw new Error('Type target is not focused and editable'); if(element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) { if (typeof element.selectionStart !== "number") return true; element.setSelectionRange(element.value.length,element.value.length); } else { const range=document.createRange(); range.selectNodeContents(element); range.collapse(false); const selection=getSelection(); selection?.removeAllRanges(); selection?.addRange(range); } return false; })()`)) {
+				await this.cdp.command("Input.dispatchKeyEvent", {
+					type: "keyDown",
+					key: "End",
+					code: "End",
+					windowsVirtualKeyCode: 35
+				});
+				await this.cdp.command("Input.dispatchKeyEvent", {
+					type: "keyUp",
+					key: "End",
+					code: "End",
+					windowsVirtualKeyCode: 35
+				});
+			}
+			await this.cdp.command("Input.insertText", { text });
+		});
+	}
+	async setViewport(viewport) {
+		if (!/^[a-z0-9_-]+$/i.test(viewport.name) || !Number.isInteger(viewport.width) || !Number.isInteger(viewport.height) || viewport.width <= 0 || viewport.height <= 0) throw new Error("Viewport requires a safe name and positive integer width/height");
+		await this.step(`viewport ${viewport.name} ${viewport.width}x${viewport.height}`, async () => {
+			await this.cdp.command("Emulation.setDeviceMetricsOverride", {
+				width: viewport.width,
+				height: viewport.height,
+				deviceScaleFactor: 1,
+				mobile: viewport.mobile ?? false
+			});
+			this.viewport = { ...viewport };
+			await this.evaluate("new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(() => resolve(true))))");
+		});
+	}
+	async assertViewport() {
+		return this.step(`assertViewport ${this.viewport.name}`, async () => {
+			const report = await this.evaluate(`({
+        requestedWidth:${this.viewport.width},innerWidth,documentWidth:document.documentElement.scrollWidth,bodyWidth:document.body?.scrollWidth ?? 0,
+        offenders:[...document.querySelectorAll('*')].map(element=>{const box=element.getBoundingClientRect();return {tag:element.tagName,id:element.id,className:element.getAttribute('class')??'',width:box.width,scrollWidth:element.scrollWidth,right:box.right,left:box.left}})
+          .filter(element=>element.right>${this.viewport.width} || element.left<0 || element.width>${this.viewport.width} || element.scrollWidth>${this.viewport.width})
+          .sort((a,b)=>Math.max(b.width,b.scrollWidth,b.right)-Math.max(a.width,a.scrollWidth,a.right)).slice(0,10)
+      })`);
+			if (report.innerWidth !== report.requestedWidth || report.documentWidth > report.requestedWidth || report.bodyWidth > report.requestedWidth) throw new Error(`Horizontal overflow or expanded viewport at ${this.viewport.name}: ${JSON.stringify(report)}`);
+			return report;
+		});
+	}
+	async screenshot(name) {
+		if (!/^[a-z0-9_-]+$/i.test(name)) throw new Error("Screenshot names must contain only letters, digits, '_' or '-'");
+		return this.step(`screenshot ${name}`, async () => {
+			const file = `${String(this.evidence.screenshots.length + 1).padStart(3, "0")}-${name}-${this.viewport.name}.png`;
+			const { data } = await this.cdp.command("Page.captureScreenshot", { format: "png" });
+			await writeFile(join(this.outputDirectory, file), Buffer.from(data, "base64"));
+			this.evidence.screenshots.push({
+				name,
+				file,
+				viewport: { ...this.viewport }
+			});
+			return join(this.outputDirectory, file);
+		});
+	}
+	async captureViewports(name, viewports = this.spec.viewports ?? defaultViewports) {
+		const failures = [];
+		const original = this.viewport;
+		for (const viewport of viewports) try {
+			await this.setViewport(viewport);
+			try {
+				await this.assertViewport();
+			} finally {
+				await this.screenshot(name);
+			}
+		} catch (error) {
+			failures.push(error);
+		}
+		try {
+			await this.setViewport(original);
+		} catch (error) {
+			failures.push(error);
+		}
+		if (failures.length) throw new AggregateError(failures, failures.map(errorMessage).join("; "));
+	}
+	async waitForNetworkIdle(timeoutMs = 1e4) {
+		await this.step("waitForNetworkIdle", () => this.poll("Network idle", async () => {
+			const pending = [...this.pendingRequests.values()].filter((url) => !this.spec.allowPendingRequests?.some((pattern) => matches(pattern, url)));
+			if (pending.length) throw new Error(`Pending requests: ${pending.join(", ")}`);
+			return Date.now() - this.lastNetworkActivity >= 300;
+		}, timeoutMs));
+	}
+	assertHealthy() {
+		for (const entry of this.evidence.console) if (entry.level === "error") entry.allowed = this.spec.allowConsoleErrors?.some((pattern) => matches(pattern, entry.text)) ?? false;
+		for (const entry of this.evidence.networkFailures) entry.allowed = this.spec.allowNetworkFailures?.some((rule) => matches(rule.url, entry.url) && (rule.status === void 0 || rule.status === entry.status) && (rule.errorText === void 0 || matches(rule.errorText, entry.errorText ?? ""))) ?? false;
+		const consoleErrors = this.evidence.console.filter((entry) => entry.level === "error" && !entry.allowed);
+		const networkErrors = this.evidence.networkFailures.filter((entry) => !entry.allowed);
+		if (consoleErrors.length || networkErrors.length) throw new Error(`Browser health failed: ${consoleErrors.length} console errors, ${networkErrors.length} failed HTTP/network requests\n${JSON.stringify({
+			console: consoleErrors,
+			network: networkErrors
+		})}`);
+	}
+};
+
+//#endregion
+export { BrowserPage, boxesStable };
+//# sourceMappingURL=page.mjs.map