@gtkx/testing 1.0.0-rc.3 → 1.0.0

package/src/role-helpers.ts

@@ -1,7 +1,7 @@
 import * as Gtk from "@gtkx/gi/gtk";
 import { sortStringsBy } from "@gtkx/utils";
 import { type Container, traverse } from "./traversal.js";
-import { getWidgetAccessibleName } from "./widget-accessible-properties.js";
+import { getWidgetAccessibleName, getWidgetLevel } from "./widget-accessible-properties.js";
 
 const ROLE_NAMES_BY_VALUE = enumNamesByValue(Gtk.AccessibleRole);
 
@@ -47,10 +47,11 @@ const formatRoleList = (roles: Iterable<Gtk.AccessibleRole>): string => {
 };
 
 /**
- * Groups every widget in a container's tree by its accessible role name.
+ * Groups every mapped widget in a container's tree by its accessible role name. Widgets that are not
+ * mapped are left out.
  *
  * @param container The scope to traverse.
- * @returns A map from role name to the widgets that have that role.
+ * @returns A map from role name to the mapped widgets that have that role.
  */
 const getRoles = (container: Container): Map<string, Gtk.Widget[]> => {
     const roles: Map<string, Gtk.Widget[]> = new Map();
@@ -80,6 +81,7 @@ const formatWidgetPreview = (widget: Gtk.Widget, name: string | null): string =>
 /**
  * Formats the accessible roles in a container's tree as a readable string,
  * listing each role together with its widgets and their accessible names.
+ * Widgets that are not mapped are left out.
  *
  * @param container The scope to inspect.
  */
@@ -116,4 +118,12 @@ const logRoles = (container: Container): void => {
     console.log(prettyRoles(container));
 };
 
-export { formatRole, formatRoleList, getRoles, prettyRoles, logRoles };
+/**
+ * Returns the heading or hierarchy level GTK reports for a widget, or undefined when it declares
+ * none.
+ *
+ * @param widget The widget to read the level from.
+ */
+const computeHeadingLevel = (widget: Gtk.Widget): number | undefined => getWidgetLevel(widget) ?? undefined;
+
+export { computeHeadingLevel, formatRole, formatRoleList, getRoles, prettyRoles, logRoles };

package/src/role-naming.ts

@@ -0,0 +1,99 @@
+import * as Gtk from "@gtkx/gi/gtk";
+
+const FROM_AUTHOR = 1;
+const FROM_CONTENT = 2;
+const PROHIBITED = 4;
+
+const NAMING: Partial<Record<Gtk.AccessibleRole, number>> = {
+    [Gtk.AccessibleRole.ALERT]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.ALERT_DIALOG]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.APPLICATION]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.ARTICLE]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.BANNER]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.BLOCK_QUOTE]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.BUTTON]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.CAPTION]: PROHIBITED,
+    [Gtk.AccessibleRole.CELL]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.CHECKBOX]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.COLUMN_HEADER]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.COMBO_BOX]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.COMMAND]: PROHIBITED,
+    [Gtk.AccessibleRole.COMMENT]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.COMPOSITE]: PROHIBITED,
+    [Gtk.AccessibleRole.DIALOG]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.DOCUMENT]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.FEED]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.FORM]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.GENERIC]: PROHIBITED,
+    [Gtk.AccessibleRole.GRID]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.GRID_CELL]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.GROUP]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.HEADING]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.IMG]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.INPUT]: PROHIBITED,
+    [Gtk.AccessibleRole.LABEL]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.LANDMARK]: PROHIBITED,
+    [Gtk.AccessibleRole.LEGEND]: PROHIBITED,
+    [Gtk.AccessibleRole.LINK]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.LIST]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.LIST_BOX]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.LIST_ITEM]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.LOG]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.MAIN]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.MARQUEE]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.MATH]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.METER]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.MENU]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.MENU_BAR]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.MENU_ITEM]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.MENU_ITEM_CHECKBOX]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.MENU_ITEM_RADIO]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.NAVIGATION]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.NONE]: PROHIBITED,
+    [Gtk.AccessibleRole.NOTE]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.OPTION]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.PARAGRAPH]: PROHIBITED,
+    [Gtk.AccessibleRole.PRESENTATION]: PROHIBITED,
+    [Gtk.AccessibleRole.PROGRESS_BAR]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.RADIO]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.RADIO_GROUP]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.RANGE]: PROHIBITED,
+    [Gtk.AccessibleRole.REGION]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.ROW]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.ROW_GROUP]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.ROW_HEADER]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.SCROLLBAR]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.SEARCH]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.SEARCH_BOX]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.SECTION]: PROHIBITED,
+    [Gtk.AccessibleRole.SECTION_HEAD]: PROHIBITED,
+    [Gtk.AccessibleRole.SELECT]: PROHIBITED,
+    [Gtk.AccessibleRole.SEPARATOR]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.SLIDER]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.SPIN_BUTTON]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.STATUS]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.STRUCTURE]: PROHIBITED,
+    [Gtk.AccessibleRole.SWITCH]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.TAB]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.TABLE]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TAB_LIST]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TAB_PANEL]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TERMINAL]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TEXT_BOX]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TIME]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TIMER]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TOGGLE_BUTTON]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TOOLBAR]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TOOLTIP]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.TREE]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TREE_GRID]: FROM_AUTHOR,
+    [Gtk.AccessibleRole.TREE_ITEM]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.WIDGET]: FROM_AUTHOR | FROM_CONTENT,
+    [Gtk.AccessibleRole.WINDOW]: FROM_AUTHOR,
+};
+
+const namingFor = (role: Gtk.AccessibleRole): number => NAMING[role] ?? 0;
+const isNameProhibited = (role: Gtk.AccessibleRole): boolean => (namingFor(role) & PROHIBITED) !== 0;
+const isNameFromAuthor = (role: Gtk.AccessibleRole): boolean => (namingFor(role) & FROM_AUTHOR) !== 0;
+
+export { isNameFromAuthor, isNameProhibited };

package/src/screenshot.ts

@@ -1,12 +1,49 @@
+import * as Gdk from "@gtkx/gi/gdk";
+import * as Graphene from "@gtkx/gi/graphene";
 import * as Gsk from "@gtkx/gi/gsk";
 import * as Gtk from "@gtkx/gi/gtk";
-import { mkdtempSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { ScreenshotOptions, ScreenshotResult, WindowSelector } from "./types.js";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { ScreenshotOptions, ScreenshotResult } from "./types.js";
+import { getConfig } from "./config.js";
+import { descendants } from "./traversal.js";
 import { waitFor } from "./wait-for.js";
 
+type FrameProbe = {
+    counter: bigint | null;
+    startedAt: number;
+};
+
+type CaptureFailure = "no-size" | "no-content";
+
+type CaptureState = {
+    probe: FrameProbe;
+    failure: CaptureFailure | null;
+};
+
+type CaptureResult =
+    { status: "captured"; result: ScreenshotResult } |
+    { status: "failed"; failure: CaptureFailure };
+
+type CaptureOutcome =
+    { status: "captured"; result: ScreenshotResult } |
+    { status: "stalled"; failure: CaptureFailure };
+
 const DEFAULT_SCREENSHOT_INTERVAL = 10;
+const PRESENTATION_PROBE_MS = 250;
+
+const NOT_PRESENTING_MESSAGE =
+    "Screenshot failed: the display is not presenting frames to this window, so GTK has no rendered " +
+    "content to capture. The window is hidden, minimized, or its compositor is not presenting it; this " +
+    "is a display problem, not a widget problem.";
+
+const EMPTY_WIDGET_HINT =
+    "The display is presenting frames to this window, so the widget itself is empty: it painted nothing.";
+
+const OTHER_FAILURE_HINT =
+    "The display is presenting frames to this window, so the capture failed for another reason.";
+
+const NOTHING_ON_SCREEN_MESSAGE = "Nothing is on screen to capture: no toplevel window is mapped";
 
 const bytesToBase64 = (bytes: number[]): string => {
     return Buffer.from(bytes).toString("base64");
@@ -16,162 +53,294 @@ const describeWidgetState = (widget: Gtk.Widget): string =>
     `realized=${String(widget.getRealized())} mapped=${String(widget.getMapped())} ` +
     `visible=${String(widget.getVisible())}`;
 
-const captureSnapshot = (widget: Gtk.Widget, scale: number): ScreenshotResult => {
-    const paintable = new Gtk.WidgetPaintable({ widget });
+const getMappedPopovers = (widget: Gtk.Widget): Gtk.Popover[] => {
+    const popovers: Gtk.Popover[] = [];
+
+    for (const descendant of descendants(widget)) {
+        if (descendant instanceof Gtk.Popover && descendant.getMapped()) {
+            popovers.push(descendant);
+        }
+    }
+
+    return popovers;
+};
+
+const appendPopover = (snapshot: Gtk.Snapshot, target: Gtk.Widget, popover: Gtk.Popover): void => {
+    const [hasBounds, bounds] = popover.computeBounds(target);
+    const paintable = new Gtk.WidgetPaintable({ widget: popover });
     const width = paintable.getIntrinsicWidth();
     const height = paintable.getIntrinsicHeight();
 
-    if (width <= 0 || height <= 0) {
-        throw new Error(`Widget has no size: ensure it is realized and visible (${describeWidgetState(widget)})`);
+    if (!hasBounds || width <= 0 || height <= 0) {
+        return;
+    }
+
+    snapshot.save();
+    snapshot.translate(new Graphene.Point({ x: bounds.origin.x, y: bounds.origin.y }));
+    paintable.snapshot(snapshot, width, height);
+    snapshot.restore();
+};
+
+const appendPopovers = (snapshot: Gtk.Snapshot, target: Gtk.Widget): void => {
+    for (const popover of getMappedPopovers(target)) {
+        appendPopover(snapshot, target, popover);
     }
+};
+
+const getSurface = (widget: Gtk.Widget): Gdk.Surface | null => widget.getNative()?.getSurface() ?? null;
+const isSurfaceOnScreen = (widget: Gtk.Widget): boolean => getSurface(widget)?.getMapped() ?? false;
+
+const getFrameClock = (widget: Gtk.Widget): Gdk.FrameClock | null =>
+    widget.getRoot()?.getFrameClock() ?? widget.getFrameClock();
+
+const getFrameCounter = (widget: Gtk.Widget): bigint | null => getFrameClock(widget)?.getFrameCounter() ?? null;
+
+const describePresentation = (widget: Gtk.Widget): string =>
+    `${describeWidgetState(widget)} surfaceMapped=${String(isSurfaceOnScreen(widget))} ` +
+    `frameCounter=${String(getFrameCounter(widget))}`;
+
+const requestFrame = (widget: Gtk.Widget): void => {
+    getFrameClock(widget)?.requestPhase(Gdk.FrameClockPhase.UPDATE);
+};
+
+const startFrameProbe = (widget: Gtk.Widget): FrameProbe => {
+    requestFrame(widget);
 
+    return { counter: getFrameCounter(widget), startedAt: Date.now() };
+};
+
+const updateFrameProbe = (widget: Gtk.Widget, probe: FrameProbe): void => {
+    requestFrame(widget);
+
+    if (probe.counter !== null) {
+        return;
+    }
+
+    const counter = getFrameCounter(widget);
+
+    if (counter !== null) {
+        probe.counter = counter;
+        probe.startedAt = Date.now();
+    }
+};
+
+const hasFrameAdvanced = (widget: Gtk.Widget, probe: FrameProbe): boolean => {
+    const counter = getFrameCounter(widget);
+
+    return counter !== null && probe.counter !== null && counter > probe.counter;
+};
+
+const isPresenting = (widget: Gtk.Widget, probe: FrameProbe): boolean =>
+    isSurfaceOnScreen(widget) && hasFrameAdvanced(widget, probe);
+
+const isPresentationStalled = (widget: Gtk.Widget, probe: FrameProbe): boolean =>
+    Date.now() - probe.startedAt >= PRESENTATION_PROBE_MS && !isPresenting(widget, probe);
+
+const allocateRoot = (widget: Gtk.Widget): void => {
+    const root = widget.getRoot();
+
+    if (!root) {
+        return;
+    }
+
+    const width = root.getWidth();
+    const height = root.getHeight();
+
+    if (width > 0 && height > 0) {
+        root.allocate(width, height, -1, null);
+    }
+};
+
+const isDirectlyPaintable = (child: Gtk.Widget): boolean =>
+    child.getMapped() && child.getWidth() > 0 && !(child instanceof Gtk.Popover);
+
+const getPaintableNode = (widget: Gtk.Widget, scale: number, width: number, height: number): Gsk.RenderNode | null => {
+    const paintable = new Gtk.WidgetPaintable({ widget });
     const snapshot = new Gtk.Snapshot();
     snapshot.scale(scale, scale);
     paintable.snapshot(snapshot, width, height);
-    const renderNode = snapshot.toNode();
+    appendPopovers(snapshot, widget);
 
-    if (!renderNode) {
-        throw new Error(`Widget produced no render content (${describeWidgetState(widget)})`);
+    return snapshot.toNode();
+};
+
+const getChildrenNode = (widget: Gtk.Widget, scale: number): Gsk.RenderNode | null => {
+    const snapshot = new Gtk.Snapshot();
+    snapshot.scale(scale, scale);
+
+    for (let child = widget.getFirstChild(); child !== null; child = child.getNextSibling()) {
+        if (isDirectlyPaintable(child)) {
+            widget.snapshotChild(child, snapshot);
+        }
+    }
+
+    appendPopovers(snapshot, widget);
+
+    return snapshot.toNode();
+};
+
+const getRenderNode = (widget: Gtk.Widget, scale: number, width: number, height: number): Gsk.RenderNode | null => {
+    const presented = getPaintableNode(widget, scale, width, height);
+
+    if (presented) {
+        return presented;
     }
 
-    const display = widget.getDisplay();
+    allocateRoot(widget);
+
+    return getPaintableNode(widget, scale, width, height) ?? getChildrenNode(widget, scale);
+};
+
+const renderToPng = (widget: Gtk.Widget, node: Gsk.RenderNode, width: number, height: number): ScreenshotResult => {
     const renderer = new Gsk.CairoRenderer();
-    renderer.realizeForDisplay(display);
+    renderer.realizeForDisplay(widget.getDisplay());
 
     try {
-        const texture = renderer.renderTexture(renderNode, null);
-        const pngBytes = texture.saveToPngBytes();
-        const data = pngBytes.getData();
+        const viewport = Graphene.Rect.alloc().init(0, 0, width, height);
+        const texture = renderer.renderTexture(node, viewport);
+        const data = texture.saveToPngBytes().getData();
 
         if (!data) {
             throw new Error("Failed to serialize screenshot to PNG");
         }
 
-        return {
-            data: bytesToBase64(data),
-            mimeType: "image/png",
-            width: Math.round(width * scale),
-            height: Math.round(height * scale),
-        };
+        return { data: bytesToBase64(data), mimeType: "image/png", width, height };
     } finally {
         renderer.unrealize();
     }
 };
 
-/**
- * Captures a PNG snapshot of a widget, retrying until it has a paintable size.
- *
- * @param widget The widget to render to an image.
- * @param options Optional scale, timeout, and retry interval.
- * @returns The base64-encoded PNG data along with its mime type and dimensions.
- */
-const screenshot = async (widget: Gtk.Widget, options?: ScreenshotOptions): Promise<ScreenshotResult> => {
-    const scale = options?.scale ?? 1;
+const captureSnapshot = (widget: Gtk.Widget, scale: number): CaptureResult => {
+    const paintable = new Gtk.WidgetPaintable({ widget });
+    const width = paintable.getIntrinsicWidth();
+    const height = paintable.getIntrinsicHeight();
 
-    if (!Number.isFinite(scale) || scale <= 0) {
-        throw new Error(`Screenshot scale must be a positive number, got ${String(scale)}`);
+    if (width <= 0 || height <= 0) {
+        return { status: "failed", failure: "no-size" };
     }
 
-    return waitFor(() => captureSnapshot(widget, scale), {
-        timeout: options?.timeout,
-        interval: options?.interval ?? DEFAULT_SCREENSHOT_INTERVAL,
-    });
-};
-
-const firstToplevelWindow = (windows: Gtk.Widget[]): Gtk.Window => {
-    const [first] = windows;
+    const renderNode = getRenderNode(widget, scale, width, height);
 
-    if (!(first instanceof Gtk.Window)) {
-        throw new TypeError("First toplevel is not a Window");
+    if (!renderNode) {
+        return { status: "failed", failure: "no-content" };
     }
 
-    return first;
+    const scaledWidth = Math.round(width * scale);
+    const scaledHeight = Math.round(height * scale);
+
+    return { status: "captured", result: renderToPng(widget, renderNode, scaledWidth, scaledHeight) };
 };
 
-const windowAtIndex = (windows: Gtk.Widget[], index: number): Gtk.Window => {
-    const indexed = windows[index];
+const failureMessage = (widget: Gtk.Widget, failure: CaptureFailure): string =>
+    failure === "no-size"
+        ? `Widget has no size: ensure it is realized and visible (${describeWidgetState(widget)})`
+        : `Widget produced no render content (${describeWidgetState(widget)})`;
 
-    if (!(indexed instanceof Gtk.Window)) {
-        throw new TypeError(`Window at index ${String(index)} not found`);
-    }
+const notPresentingMessage = (widget: Gtk.Widget): string =>
+    `${NOT_PRESENTING_MESSAGE} (${describePresentation(widget)})`;
 
-    return indexed;
-};
+const stalledMessage = (widget: Gtk.Widget, failure: CaptureFailure): string =>
+    `${notPresentingMessage(widget)}\n\n${failureMessage(widget, failure)}`;
 
-const isWindow = (widget: Gtk.Widget): widget is Gtk.Window => widget instanceof Gtk.Window;
+const presentingHint = (failure: CaptureFailure | null): string =>
+    failure === "no-content" ? EMPTY_WIDGET_HINT : OTHER_FAILURE_HINT;
 
-const hasMatchingTitle = (window: Gtk.Window, selector: string | RegExp): boolean => {
-    const title = window.getTitle() ?? "";
+const timeoutHint = (widget: Gtk.Widget, state: CaptureState): string =>
+    isPresenting(widget, state.probe) ? presentingHint(state.failure) : notPresentingMessage(widget);
 
-    return selector instanceof RegExp ? selector.test(title) : title.includes(selector);
-};
+const explainTimeout = (error: Error, widget: Gtk.Widget, state: CaptureState): Error =>
+    getConfig().getElementError(`${error.message}\n\n${timeoutHint(widget, state)}`);
 
-const describeTitleSelector = (selector: string | RegExp): string =>
-    selector instanceof RegExp ? selector.toString() : `"${selector}"`;
+const attemptCapture = (widget: Gtk.Widget, scale: number, state: CaptureState): CaptureOutcome => {
+    const attempt = captureSnapshot(widget, scale);
 
-const windowByTitle = (windows: Gtk.Widget[], selector: string | RegExp): Gtk.Window => {
-    const found = windows.filter(isWindow).find((window) => hasMatchingTitle(window, selector));
+    if (attempt.status === "captured") {
+        return attempt;
+    }
+
+    state.failure = attempt.failure;
+    updateFrameProbe(widget, state.probe);
 
-    if (!found) {
-        throw new Error(`No window found with title matching ${describeTitleSelector(selector)}`);
+    if (isPresentationStalled(widget, state.probe)) {
+        return { status: "stalled", failure: attempt.failure };
     }
 
-    return found;
+    throw new Error(failureMessage(widget, attempt.failure));
+};
+
+const writeScreenshot = (result: ScreenshotResult, path: string): void => {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, Buffer.from(result.data, "base64"));
 };
 
-const resolveWindow = (selector?: WindowSelector): Gtk.Window => {
-    const windows = Gtk.Window.listToplevels();
+const captureUntilPaintable = (
+    widget: Gtk.Widget,
+    scale: number,
+    options: ScreenshotOptions | undefined,
+): Promise<CaptureOutcome> => {
+    const state: CaptureState = { probe: startFrameProbe(widget), failure: null };
+
+    return waitFor(() => attemptCapture(widget, scale, state), {
+        timeout: options?.timeout,
+        interval: options?.interval ?? DEFAULT_SCREENSHOT_INTERVAL,
+        onTimeout: (error) => explainTimeout(error, widget, state),
+    });
+};
 
-    if (windows.length === 0) {
-        throw new Error("No windows available for screenshot");
+/**
+ * Captures a PNG snapshot of a widget, retrying until it has a paintable size,
+ * and writes the image to `options.path` when one is given, creating any
+ * missing parent directories. Popovers open inside the widget render on their
+ * own surfaces, so they are composited into the image at their on-screen
+ * positions. A display that never presents a frame leaves GTK without a cached
+ * render node, so the widget's contents are then snapshotted directly; when
+ * even that yields nothing, the failure names the display instead of blaming
+ * the widget.
+ *
+ * @param widget The widget to render to an image.
+ * @param options Optional scale, timeout, retry interval, and output path.
+ * @returns The base64-encoded PNG data along with its mime type and dimensions.
+ */
+const screenshot = async (widget: Gtk.Widget, options?: ScreenshotOptions): Promise<ScreenshotResult> => {
+    const scale = options?.scale ?? 1;
+
+    if (!Number.isFinite(scale) || scale <= 0) {
+        throw new Error(`Screenshot scale must be a positive number, got ${String(scale)}`);
     }
 
-    if (selector === undefined) {
-        return firstToplevelWindow(windows);
+    const outcome = await captureUntilPaintable(widget, scale, options);
+
+    if (outcome.status === "stalled") {
+        throw new Error(stalledMessage(widget, outcome.failure));
     }
 
-    if (typeof selector === "number") {
-        return windowAtIndex(windows, selector);
+    if (options?.path) {
+        writeScreenshot(outcome.result, options.path);
     }
 
-    return windowByTitle(windows, selector);
+    return outcome.result;
 };
 
-const saveScreenshotToTempFile = (result: ScreenshotResult): string => {
-    const dir = mkdtempSync(join(tmpdir(), "gtkx-screenshots-"));
-    const filepath = join(dir, "screenshot.png");
-    writeFileSync(filepath, Buffer.from(result.data, "base64"));
+const isWindow = (widget: Gtk.Widget): widget is Gtk.Window => widget instanceof Gtk.Window;
+const isOnScreen = (window: Gtk.Window): boolean => window.getMapped();
+const isActiveWindow = (window: Gtk.Window): boolean => window.isActive();
 
-    return filepath;
-};
+const activeToplevel = (): Gtk.Window => {
+    const toplevels = Gtk.Window.listToplevels().filter((widget) => isWindow(widget));
+    const onScreen = toplevels.filter((window) => isOnScreen(window));
+    const target = onScreen.find((window) => isActiveWindow(window)) ?? onScreen[0];
 
-/**
- * Prints a clickable file URL for a saved screenshot to the console.
- *
- * @param filepath Absolute path of the saved screenshot file.
- */
-const logScreenshotPath = (filepath: string): void => {
-    console.log(`Screenshot saved: file://${filepath}`);
+    if (!target) {
+        throw new Error(NOTHING_ON_SCREEN_MESSAGE);
+    }
+
+    return target;
 };
 
-/**
- * Captures a screenshot of a toplevel window, writes it to a temporary file,
- * logs its path, and returns the image data.
- *
- * @param selector Chooses the window by index, title substring, or regular
- * expression; defaults to the first toplevel.
- * @param options Optional scale, timeout, and retry interval.
- * @returns The base64-encoded PNG data along with its mime type and dimensions.
- */
-const captureAndSaveScreenshot = async (
-    selector?: WindowSelector,
-    options?: ScreenshotOptions,
-): Promise<ScreenshotResult> => {
-    const target = resolveWindow(selector);
-    const result = await screenshot(target, options);
-    logScreenshotPath(saveScreenshotToTempFile(result));
+const captureScreen = async (options?: ScreenshotOptions): Promise<ScreenshotResult> => {
+    const target = activeToplevel();
 
-    return result;
+    return screenshot(target, options);
 };
 
-export { screenshot, logScreenshotPath, captureAndSaveScreenshot };
+export { captureScreen, screenshot };

package/src/suggestions.ts

@@ -20,10 +20,13 @@ type Method = "Role" | "LabelText" | "PlaceholderText" | "Text" | "DisplayValue"
  * `toString` that renders the full call.
  */
 type Suggestion = {
+    /** The query family, such as `Role`. */
     queryName: Method;
     /** The full query function name, such as `getByRole`. */
     queryMethod: string;
+    /** The variant the suggestion was asked for, which prefixes `Suggestion.queryMethod`. */
     variant: Variant;
+    /** Renders the suggested call with its arguments, such as `getByRole(Gtk.AccessibleRole.BUTTON)`. */
     toString: () => string;
 };