@ralphralphai/playwright 2.4.0 → 2.6.0

package/dist/{upload-FIxKqKb3.cjs → upload-H-EycbCA.cjs}

@@ -70,7 +70,7 @@ function snapshot(value) {
 }
 //#endregion
 //#region package.json
-var version = "2.4.0";
+var version = "2.6.0";
 //#endregion
 //#region src/actions.ts
 const BINDING = "__ralphAction";
@@ -654,8 +654,10 @@ async function captureAriaSnapshot(page, { viewport, scroll }) {
 		boxes: true,
 		depth: MAX_ARIA_DEPTH
 	});
-	const visible = (await Promise.all(snapshot.map((node) => toDocument(page, node, scroll)))).flatMap((node) => {
-		const kept = keepShown(node, viewport.width);
+	const placed = await Promise.all(snapshot.map((node) => toDocument(page, node, scroll)));
+	const clips = await readClips(page, placed);
+	const visible = placed.flatMap((node) => {
+		const kept = keepShown(node, viewport.width, clips, void 0);
 		return kept === void 0 ? [] : [kept];
 	});
 	const described = await Promise.all(visible.map((node) => describe(page, node, {}, false)));
@@ -719,15 +721,134 @@ function isReachable(box, viewportWidth) {
 function isShown(node, viewportWidth) {
 	return node.ref !== void 0 && isReachable(node.box, viewportWidth);
 }
-function keepShown(node, viewportWidth) {
+function edgesOf(box) {
+	return {
+		left: box.x,
+		top: box.y,
+		right: box.x + box.width,
+		bottom: box.y + box.height
+	};
+}
+function intersect(a, b) {
+	if (a === void 0) return b;
+	return {
+		left: Math.max(a.left, b.left),
+		top: Math.max(a.top, b.top),
+		right: Math.min(a.right, b.right),
+		bottom: Math.min(a.bottom, b.bottom)
+	};
+}
+const ROUNDING_SLACK = 1;
+function sticksOut(inner, outer) {
+	return inner.x < outer.x - ROUNDING_SLACK || inner.y < outer.y - ROUNDING_SLACK || inner.x + inner.width > outer.x + outer.width + ROUNDING_SLACK || inner.y + inner.height > outer.y + outer.height + ROUNDING_SLACK;
+}
+function overlaps(a, b) {
+	return Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x) > ROUNDING_SLACK && Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y) > ROUNDING_SLACK;
+}
+function isOutside(box, clip) {
+	return box.x >= clip.right || box.x + box.width <= clip.left || box.y >= clip.bottom || box.y + box.height <= clip.top;
+}
+/**
+* The area each element is clipped to by its ancestors' `overflow`, in
+* document space, by ref.
+*
+* The boxes are not clipped (the rows of a 448px scroll box run thousands of
+* pixels down the page), and reading an element's ancestors is a page round
+* trip. Only an element that may overflow one is read: a root, one sticking
+* out of its parent, or one running into its next sibling. The clipping
+* ancestor itself is often missing from the tree, since Playwright unwraps a
+* nameless wrapper with one child. Every other element takes its parent's
+* clip.
+*/
+async function readClips(page, nodes) {
+	const candidates = [];
+	const visit = (node, parent, next, frame) => {
+		if (node.box !== void 0 && (parent === void 0 || sticksOut(node.box, parent) || next?.box !== void 0 && overlaps(node.box, next.box))) candidates.push({
+			node,
+			frame
+		});
+		const childFrame = node.role === "iframe" && node.box !== void 0 ? intersect(frame, edgesOf(node.box)) : frame;
+		const elements = (node.children ?? []).filter((child) => {
+			return typeof child !== "string";
+		});
+		elements.forEach((child, index) => {
+			visit(child, node.box, elements[index + 1], childFrame);
+		});
+	};
+	nodes.forEach((node, index) => {
+		visit(node, void 0, nodes[index + 1], void 0);
+	});
+	const clips = await Promise.all(candidates.map(async ({ node, frame }) => {
+		const clip = await readClip(page, node);
+		return clip === void 0 || node.ref === void 0 ? [] : [[node.ref, intersect(frame, clip)]];
+	}));
+	return new Map(clips.flat());
+}
+async function readClip(page, node) {
+	if (node.box === void 0 || node.ref === void 0) return;
+	let read;
+	try {
+		read = await page.locator(`aria-ref=${node.ref}`).evaluate((element) => {
+			const clip = {
+				left: -Infinity,
+				top: -Infinity,
+				right: Infinity,
+				bottom: Infinity
+			};
+			let position = getComputedStyle(element).position;
+			for (let ancestor = element.parentElement; ancestor !== null && ancestor !== document.body && ancestor !== document.documentElement; ancestor = ancestor.parentElement) {
+				if (position === "fixed") break;
+				const style = getComputedStyle(ancestor);
+				if (position === "absolute" && style.position === "static" && style.transform === "none") continue;
+				position = style.position;
+				const clipsX = style.overflowX !== "visible";
+				const clipsY = style.overflowY !== "visible";
+				if (!clipsX && !clipsY || style.display === "inline") continue;
+				const rect = ancestor.getBoundingClientRect();
+				const left = rect.left + ancestor.clientLeft;
+				const top = rect.top + ancestor.clientTop;
+				if (clipsX) {
+					clip.left = Math.max(clip.left, left);
+					clip.right = Math.min(clip.right, left + ancestor.clientWidth);
+				}
+				if (clipsY) {
+					clip.top = Math.max(clip.top, top);
+					clip.bottom = Math.min(clip.bottom, top + ancestor.clientHeight);
+				}
+			}
+			const own = element.getBoundingClientRect();
+			return {
+				x: own.x,
+				y: own.y,
+				clip
+			};
+		}, void 0, { timeout: ELEMENT_LOOKUP_TIMEOUT_MS });
+	} catch {
+		return;
+	}
+	const dx = node.box.x - read.x;
+	const dy = node.box.y - read.y;
+	return {
+		left: read.clip.left + dx,
+		top: read.clip.top + dy,
+		right: read.clip.right + dx,
+		bottom: read.clip.bottom + dy
+	};
+}
+function keepShown(node, viewportWidth, clips, inherited) {
 	if (node.role === "iframe" && node.box !== void 0 && (node.box.width < MIN_IFRAME_SIZE || node.box.height < MIN_IFRAME_SIZE)) return;
+	const clip = (node.ref === void 0 ? void 0 : clips.get(node.ref)) ?? inherited;
+	if (clip !== void 0 && node.box !== void 0 && isOutside(node.box, clip)) return;
 	const shown = isShown(node, viewportWidth);
+	const childClip = node.role === "iframe" && node.box !== void 0 ? intersect(clip, edgesOf(node.box)) : clip;
 	const children = (node.children ?? []).flatMap((child) => {
 		if (typeof child === "string") return shown ? [child] : [];
-		const kept = keepShown(child, viewportWidth);
+		const kept = keepShown(child, viewportWidth, clips, childClip);
 		return kept === void 0 ? [] : [kept];
 	});
 	if (!shown && children.length === 0) return;
+	const [only] = children;
+	if (node.role === "generic" && !node.name && (node.children?.length ?? 0) > 1 && children.length === 1 && typeof only !== "string" && only?.ref !== void 0) return only;
 	return node.children === void 0 ? node : {
 		...node,
 		children
@@ -825,6 +946,179 @@ async function describe(page, child, inherited, insideDynamic) {
 	};
 }
 //#endregion
+//#region src/animation_observer.ts
+/** Runs in the page. Keeps native animations and DOM changes observable without app hooks. */
+function observeAnimations() {
+	const paused = /* @__PURE__ */ new Set();
+	const roots = /* @__PURE__ */ new Set();
+	let dirty = true;
+	const observer = new MutationObserver(() => {
+		dirty = true;
+	});
+	const collect = (root, all) => {
+		if (!roots.has(root)) {
+			roots.add(root);
+			observer.observe(root, {
+				subtree: true,
+				childList: true,
+				attributes: true,
+				characterData: true
+			});
+			dirty = true;
+		}
+		root.getAnimations().forEach((animation) => all.add(animation));
+		for (const element of root.querySelectorAll("*")) if (element.shadowRoot) collect(element.shadowRoot, all);
+	};
+	return {
+		sample(finishFinite) {
+			const all = /* @__PURE__ */ new Set();
+			collect(document, all);
+			let changed = dirty;
+			dirty = false;
+			for (const animation of all) {
+				if (animation.playState !== "running") continue;
+				if (finishFinite && animation.playbackRate !== 0 && Number.isFinite(animation.effect?.getComputedTiming().endTime)) animation.finish();
+				else {
+					animation.pause();
+					paused.add(animation);
+				}
+				changed = true;
+			}
+			return changed;
+		},
+		async ready() {
+			await Promise.all([...paused].map((animation) => animation.ready));
+		},
+		resume() {
+			observer.disconnect();
+			for (const animation of paused) if (animation.playState === "paused") animation.play();
+		}
+	};
+}
+//#endregion
+//#region src/capture_freezer.ts
+const PAUSE_LEAD_MS = 100;
+const ANIMATION_QUIET_MS = 150;
+const MAX_ANIMATION_SETTLE_MS = 1500;
+/** One owner of the context-wide clock; captures in different tabs queue here. */
+var CaptureFreezer = class {
+	context;
+	tail = Promise.resolve();
+	closed = false;
+	constructor(context) {
+		this.context = context;
+		context.once("close", () => {
+			this.closed = true;
+		});
+	}
+	install() {
+		if (this.context.pages().some((page) => page.url() !== "about:blank")) throw new Error("Ralph freezeDuringCapture requires the clock before page scripts run. Await ralph.observe(context) before creating or navigating pages in a custom context.");
+		return this.context.clock.install();
+	}
+	async capture(page, signal, capture, deadline = Date.now() + 5e3) {
+		const task = this.tail.then(async () => {
+			signal.throwIfAborted();
+			const animations = /* @__PURE__ */ new Map();
+			try {
+				await this.settleAnimations(page, animations, signal, deadline);
+				await this.pauseClock(page, signal);
+				signal.throwIfAborted();
+				for (let pass = 0; pass < 2; pass++) {
+					await this.sampleAnimations(page, animations, signal, false);
+					await this.waitForAnimationsReady(animations, signal);
+				}
+				return await capture();
+			} finally {
+				try {
+					await this.resumeAnimations(animations);
+				} finally {
+					if (!this.closed) await this.context.clock.resume();
+				}
+			}
+		});
+		this.tail = task.catch(() => void 0);
+		return task;
+	}
+	async settleAnimations(page, animations, signal, deadline) {
+		const now = Date.now();
+		const endsAt = now + Math.min(MAX_ANIMATION_SETTLE_MS, Math.max(0, (deadline - now) / 2));
+		let quietSince = now;
+		while (Date.now() < endsAt) {
+			if (await this.sampleAnimations(page, animations, signal, true)) quietSince = Date.now();
+			if (Date.now() - quietSince >= ANIMATION_QUIET_MS) return;
+			await (0, node_timers_promises.setTimeout)(Math.max(0, Math.min(50, endsAt - Date.now())), void 0, { signal }).catch((error) => {
+				signal.throwIfAborted();
+				throw error;
+			});
+		}
+	}
+	async sampleAnimations(page, animations, signal, finishFinite) {
+		let changed = false;
+		for (const frame of page.frames()) {
+			signal.throwIfAborted();
+			try {
+				let handle = animations.get(frame);
+				if (!handle) {
+					handle = await frame.evaluateHandle(observeAnimations);
+					animations.set(frame, handle);
+				}
+				changed = await handle.evaluate((state, finish) => state.sample(finish), finishFinite) || changed;
+			} catch (error) {
+				if (!frame.isDetached()) throw error;
+			}
+		}
+		signal.throwIfAborted();
+		return changed;
+	}
+	async waitForAnimationsReady(animations, signal) {
+		signal.throwIfAborted();
+		let onAbort;
+		const aborted = new Promise((_, reject) => {
+			onAbort = () => reject(signal.reason);
+			signal.addEventListener("abort", onAbort, { once: true });
+		});
+		try {
+			await Promise.race([Promise.all([...animations].map(async ([frame, handle]) => {
+				if (frame.isDetached()) return;
+				try {
+					await handle.evaluate((state) => state.ready());
+				} catch (error) {
+					if (!frame.isDetached()) throw error;
+				}
+			})), aborted]);
+		} finally {
+			signal.removeEventListener("abort", onAbort);
+		}
+	}
+	async resumeAnimations(animations) {
+		const restored = await Promise.allSettled([...animations.values()].map(async (handle) => {
+			try {
+				await handle.evaluate((state) => state.resume());
+			} catch (error) {
+				if (!destroyedContext(error)) throw error;
+			} finally {
+				await handle.dispose();
+			}
+		}));
+		for (const result of restored) if (result.status === "rejected") throw result.reason;
+	}
+	async pauseClock(page, signal) {
+		for (let attempt = 0;; attempt++) {
+			const time = await page.evaluate(() => Date.now());
+			signal.throwIfAborted();
+			try {
+				await this.context.clock.pauseAt(time + PAUSE_LEAD_MS);
+				return;
+			} catch (error) {
+				if (attempt > 0 || !(error instanceof Error) || !error.message.includes("Cannot fast-forward to the past")) throw error;
+			}
+		}
+	}
+};
+function destroyedContext(error) {
+	return error instanceof Error && /Execution context was destroyed|Cannot find context|Target page, context or browser has been closed|Frame was detached/.test(error.message);
+}
+//#endregion
 //#region src/conditions.ts
 const declared = (declaration = {}) => {
 	const conditions = {};
@@ -886,11 +1180,11 @@ function nodeKey(conditions) {
 */
 const WEBP_QUALITY = 80;
 const WEBP_MAX_DIMENSION = 16383;
-async function takeScreenshot(page, deadline) {
+async function takeScreenshot(page, deadline, frozen = false) {
 	const options = {
 		fullPage: true,
 		scale: "css",
-		animations: "disabled"
+		animations: frozen ? "allow" : "disabled"
 	};
 	const webp = await page.screenshot({
 		...options,
@@ -1119,22 +1413,30 @@ var Recorder = class {
 	/** Starts recording URL changes in every current and future tab of `context`. */
 	observe(context) {
 		if (this.closed) throw new Error("The Ralph recorder has finished.");
-		if (this.contexts.has(context)) return;
+		const existing = this.contexts.get(context);
+		if (existing) return existing.ready;
+		const freezer = this.options.freezeDuringCapture ? new CaptureFreezer(context) : void 0;
+		const ready = freezer?.install() ?? Promise.resolve();
 		const onPage = (page) => this.watchPage(page);
-		this.contexts.set(context, onPage);
+		this.contexts.set(context, {
+			onPage,
+			ready,
+			freezer
+		});
 		this.actions.observe(context);
 		context.on("page", onPage);
 		for (const page of context.pages()) onPage(page);
+		return ready;
 	}
 	async recordNode(page, options) {
-		this.observe(page.context());
+		await this.observe(page.context());
 		const state = this.pages.get(page);
 		if (!state) throw new Error("Cannot record a closed browser page.");
 		if (this.paused) return;
 		await this.enqueueCreateNodeRequest(state, "explicit", options);
 	}
 	async setNodeConditions(page, declaration) {
-		this.observe(page.context());
+		await this.observe(page.context());
 		const state = this.pages.get(page);
 		if (!state) throw new Error("Cannot tag a closed browser page.");
 		const key = Symbol();
@@ -1165,8 +1467,11 @@ var Recorder = class {
 	}
 	/** Stops watching `context` and waits for its queued recordings. */
 	async stopContext(context) {
-		const onPage = this.contexts.get(context);
-		if (onPage) context.off("page", onPage);
+		const observed = this.contexts.get(context);
+		if (observed) {
+			context.off("page", observed.onPage);
+			await observed.ready;
+		}
 		const states = [...this.pages.values()].filter((state) => state.page.context() === context);
 		for (const state of states) state.page.off("framenavigated", state.onNavigation);
 		await Promise.all(states.map((state) => state.tail));
@@ -1282,6 +1587,7 @@ var Recorder = class {
 		};
 		try {
 			check();
+			await wait(this.contexts.get(page.context()).ready);
 			if (request.trigger !== "explicit") await this.waitForPageToSettle(page, deadline, check);
 			check();
 			const conditions = this.declaredConditions(state);
@@ -1294,18 +1600,27 @@ var Recorder = class {
 				warnedNoTracker = true;
 				console.warn("Ralph: this page runs no tracker, so the node conditions the test declares cannot be checked against the tags the app reports. Production events must carry the same tags, or these nodes will match no visitors.");
 			}
-			if (this.options.reduceMotion) {
+			const freezer = this.contexts.get(page.context()).freezer;
+			if (this.options.reduceMotion && !freezer) {
 				check();
 				await wait(waitForAnimations(page, (deadline.endsAt - Date.now()) / 2));
 			}
-			check();
-			const before = await wait(readLayout(page));
-			check();
-			const image = await wait(takeScreenshot(page, deadline.endsAt));
-			check();
-			const after = await wait(readLayout(page));
-			check();
-			const snapshot = await Promise.race([captureAriaSnapshot(page, after).catch(() => void 0), (0, node_timers_promises.setTimeout)(Math.max(0, deadline.endsAt - Date.now()), void 0, { ref: false })]);
+			const capture = async () => {
+				check();
+				const before = await wait(readLayout(page));
+				check();
+				const image = await wait(takeScreenshot(page, deadline.endsAt, !!freezer));
+				check();
+				const after = await wait(readLayout(page));
+				check();
+				return {
+					before,
+					image,
+					after,
+					snapshot: await Promise.race([captureAriaSnapshot(page, after).catch(() => void 0), (0, node_timers_promises.setTimeout)(Math.max(0, deadline.endsAt - Date.now()), void 0, { ref: false })])
+				};
+			};
+			const { before, image, after, snapshot } = freezer ? await freezer.capture(page, deadline.signal, capture, deadline.endsAt) : await capture();
 			checkPage();
 			const recorded = {
 				...request,
@@ -1843,4 +2158,4 @@ Object.defineProperty(exports, "visitAllLinks", {
 	}
 });
 
-//# sourceMappingURL=upload-FIxKqKb3.cjs.map
+//# sourceMappingURL=upload-H-EycbCA.cjs.map