@gtkx/testing 1.0.0-rc.4 → 1.0.0

package/dist/screenshot.js

@@ -1,55 +1,196 @@
+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 { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { getConfig } from "./config.js";
+import { descendants } from "./traversal.js";
 import { waitFor } from "./wait-for.js";
 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) => {
     return Buffer.from(bytes).toString("base64");
 };
 const describeWidgetState = (widget) => `realized=${String(widget.getRealized())} mapped=${String(widget.getMapped())} ` +
     `visible=${String(widget.getVisible())}`;
-const captureSnapshot = (widget, scale) => {
-    const paintable = new Gtk.WidgetPaintable({ widget });
+const getMappedPopovers = (widget) => {
+    const popovers = [];
+    for (const descendant of descendants(widget)) {
+        if (descendant instanceof Gtk.Popover && descendant.getMapped()) {
+            popovers.push(descendant);
+        }
+    }
+    return popovers;
+};
+const appendPopover = (snapshot, target, popover) => {
+    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, target) => {
+    for (const popover of getMappedPopovers(target)) {
+        appendPopover(snapshot, target, popover);
+    }
+};
+const getSurface = (widget) => widget.getNative()?.getSurface() ?? null;
+const isSurfaceOnScreen = (widget) => getSurface(widget)?.getMapped() ?? false;
+const getFrameClock = (widget) => widget.getRoot()?.getFrameClock() ?? widget.getFrameClock();
+const getFrameCounter = (widget) => getFrameClock(widget)?.getFrameCounter() ?? null;
+const describePresentation = (widget) => `${describeWidgetState(widget)} surfaceMapped=${String(isSurfaceOnScreen(widget))} ` +
+    `frameCounter=${String(getFrameCounter(widget))}`;
+const requestFrame = (widget) => {
+    getFrameClock(widget)?.requestPhase(Gdk.FrameClockPhase.UPDATE);
+};
+const startFrameProbe = (widget) => {
+    requestFrame(widget);
+    return { counter: getFrameCounter(widget), startedAt: Date.now() };
+};
+const updateFrameProbe = (widget, probe) => {
+    requestFrame(widget);
+    if (probe.counter !== null) {
+        return;
+    }
+    const counter = getFrameCounter(widget);
+    if (counter !== null) {
+        probe.counter = counter;
+        probe.startedAt = Date.now();
+    }
+};
+const hasFrameAdvanced = (widget, probe) => {
+    const counter = getFrameCounter(widget);
+    return counter !== null && probe.counter !== null && counter > probe.counter;
+};
+const isPresenting = (widget, probe) => isSurfaceOnScreen(widget) && hasFrameAdvanced(widget, probe);
+const isPresentationStalled = (widget, probe) => Date.now() - probe.startedAt >= PRESENTATION_PROBE_MS && !isPresenting(widget, probe);
+const allocateRoot = (widget) => {
+    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) => child.getMapped() && child.getWidth() > 0 && !(child instanceof Gtk.Popover);
+const getPaintableNode = (widget, scale, width, height) => {
+    const paintable = new Gtk.WidgetPaintable({ widget });
     const snapshot = new Gtk.Snapshot();
     snapshot.scale(scale, scale);
     paintable.snapshot(snapshot, width, height);
-    const renderNode = snapshot.toNode();
-    if (!renderNode) {
-        throw new Error(`Widget produced no render content (${describeWidgetState(widget)})`);
+    appendPopovers(snapshot, widget);
+    return snapshot.toNode();
+};
+const getChildrenNode = (widget, scale) => {
+    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, scale, width, height) => {
+    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, node, width, height) => {
     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();
     }
 };
+const captureSnapshot = (widget, scale) => {
+    const paintable = new Gtk.WidgetPaintable({ widget });
+    const width = paintable.getIntrinsicWidth();
+    const height = paintable.getIntrinsicHeight();
+    if (width <= 0 || height <= 0) {
+        return { status: "failed", failure: "no-size" };
+    }
+    const renderNode = getRenderNode(widget, scale, width, height);
+    if (!renderNode) {
+        return { status: "failed", failure: "no-content" };
+    }
+    const scaledWidth = Math.round(width * scale);
+    const scaledHeight = Math.round(height * scale);
+    return { status: "captured", result: renderToPng(widget, renderNode, scaledWidth, scaledHeight) };
+};
+const failureMessage = (widget, failure) => failure === "no-size"
+    ? `Widget has no size: ensure it is realized and visible (${describeWidgetState(widget)})`
+    : `Widget produced no render content (${describeWidgetState(widget)})`;
+const notPresentingMessage = (widget) => `${NOT_PRESENTING_MESSAGE} (${describePresentation(widget)})`;
+const stalledMessage = (widget, failure) => `${notPresentingMessage(widget)}\n\n${failureMessage(widget, failure)}`;
+const presentingHint = (failure) => failure === "no-content" ? EMPTY_WIDGET_HINT : OTHER_FAILURE_HINT;
+const timeoutHint = (widget, state) => isPresenting(widget, state.probe) ? presentingHint(state.failure) : notPresentingMessage(widget);
+const explainTimeout = (error, widget, state) => getConfig().getElementError(`${error.message}\n\n${timeoutHint(widget, state)}`);
+const attemptCapture = (widget, scale, state) => {
+    const attempt = captureSnapshot(widget, scale);
+    if (attempt.status === "captured") {
+        return attempt;
+    }
+    state.failure = attempt.failure;
+    updateFrameProbe(widget, state.probe);
+    if (isPresentationStalled(widget, state.probe)) {
+        return { status: "stalled", failure: attempt.failure };
+    }
+    throw new Error(failureMessage(widget, attempt.failure));
+};
+const writeScreenshot = (result, path) => {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, Buffer.from(result.data, "base64"));
+};
+const captureUntilPaintable = (widget, scale, options) => {
+    const state = { 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),
+    });
+};
 /**
- * Captures a PNG snapshot of a widget, retrying until it has a paintable size.
+ * 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, and retry interval.
+ * @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, options) => {
@@ -57,79 +198,30 @@ const screenshot = async (widget, options) => {
     if (!Number.isFinite(scale) || scale <= 0) {
         throw new Error(`Screenshot scale must be a positive number, got ${String(scale)}`);
     }
-    return waitFor(() => captureSnapshot(widget, scale), {
-        timeout: options?.timeout,
-        interval: options?.interval ?? DEFAULT_SCREENSHOT_INTERVAL,
-    });
-};
-const firstToplevelWindow = (windows) => {
-    const [first] = windows;
-    if (!(first instanceof Gtk.Window)) {
-        throw new TypeError("First toplevel is not a Window");
+    const outcome = await captureUntilPaintable(widget, scale, options);
+    if (outcome.status === "stalled") {
+        throw new Error(stalledMessage(widget, outcome.failure));
     }
-    return first;
-};
-const windowAtIndex = (windows, index) => {
-    const indexed = windows[index];
-    if (!(indexed instanceof Gtk.Window)) {
-        throw new TypeError(`Window at index ${String(index)} not found`);
+    if (options?.path) {
+        writeScreenshot(outcome.result, options.path);
     }
-    return indexed;
+    return outcome.result;
 };
 const isWindow = (widget) => widget instanceof Gtk.Window;
-const hasMatchingTitle = (window, selector) => {
-    const title = window.getTitle() ?? "";
-    return selector instanceof RegExp ? selector.test(title) : title.includes(selector);
-};
-const describeTitleSelector = (selector) => selector instanceof RegExp ? selector.toString() : `"${selector}"`;
-const windowByTitle = (windows, selector) => {
-    const found = windows.filter(isWindow).find((window) => hasMatchingTitle(window, selector));
-    if (!found) {
-        throw new Error(`No window found with title matching ${describeTitleSelector(selector)}`);
-    }
-    return found;
-};
-const resolveWindow = (selector) => {
-    const windows = Gtk.Window.listToplevels();
-    if (windows.length === 0) {
-        throw new Error("No windows available for screenshot");
-    }
-    if (selector === undefined) {
-        return firstToplevelWindow(windows);
+const isOnScreen = (window) => window.getMapped();
+const isActiveWindow = (window) => window.isActive();
+const activeToplevel = () => {
+    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];
+    if (!target) {
+        throw new Error(NOTHING_ON_SCREEN_MESSAGE);
     }
-    if (typeof selector === "number") {
-        return windowAtIndex(windows, selector);
-    }
-    return windowByTitle(windows, selector);
-};
-const saveScreenshotToTempFile = (result) => {
-    const dir = mkdtempSync(join(tmpdir(), "gtkx-screenshots-"));
-    const filepath = join(dir, "screenshot.png");
-    writeFileSync(filepath, Buffer.from(result.data, "base64"));
-    return filepath;
+    return target;
 };
-/**
- * Prints a clickable file URL for a saved screenshot to the console.
- *
- * @param filepath Absolute path of the saved screenshot file.
- */
-const logScreenshotPath = (filepath) => {
-    console.log(`Screenshot saved: file://${filepath}`);
-};
-/**
- * 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, options) => {
-    const target = resolveWindow(selector);
-    const result = await screenshot(target, options);
-    logScreenshotPath(saveScreenshotToTempFile(result));
-    return result;
+const captureScreen = async (options) => {
+    const target = activeToplevel();
+    return screenshot(target, options);
 };
-export { screenshot, logScreenshotPath, captureAndSaveScreenshot };
+export { captureScreen, screenshot };
 //# sourceMappingURL=screenshot.js.map

package/dist/screenshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../src/screenshot.ts"],"names":[],"mappings":"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","sourcesContent":["import * as Gsk from \"@gtkx/gi/gsk\";\nimport * as Gtk from \"@gtkx/gi/gtk\";\nimport { mkdtempSync, writeFileSync } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport type { ScreenshotOptions, ScreenshotResult, WindowSelector } from \"./types.js\";\nimport { waitFor } from \"./wait-for.js\";\n\nconst DEFAULT_SCREENSHOT_INTERVAL = 10;\n\nconst bytesToBase64 = (bytes: number[]): string => {\n    return Buffer.from(bytes).toString(\"base64\");\n};\n\nconst describeWidgetState = (widget: Gtk.Widget): string =>\n    `realized=${String(widget.getRealized())} mapped=${String(widget.getMapped())} ` +\n    `visible=${String(widget.getVisible())}`;\n\nconst captureSnapshot = (widget: Gtk.Widget, scale: number): ScreenshotResult => {\n    const paintable = new Gtk.WidgetPaintable({ widget });\n    const width = paintable.getIntrinsicWidth();\n    const height = paintable.getIntrinsicHeight();\n\n    if (width <= 0 || height <= 0) {\n        throw new Error(`Widget has no size: ensure it is realized and visible (${describeWidgetState(widget)})`);\n    }\n\n    const snapshot = new Gtk.Snapshot();\n    snapshot.scale(scale, scale);\n    paintable.snapshot(snapshot, width, height);\n    const renderNode = snapshot.toNode();\n\n    if (!renderNode) {\n        throw new Error(`Widget produced no render content (${describeWidgetState(widget)})`);\n    }\n\n    const display = widget.getDisplay();\n    const renderer = new Gsk.CairoRenderer();\n    renderer.realizeForDisplay(display);\n\n    try {\n        const texture = renderer.renderTexture(renderNode, null);\n        const pngBytes = texture.saveToPngBytes();\n        const data = pngBytes.getData();\n\n        if (!data) {\n            throw new Error(\"Failed to serialize screenshot to PNG\");\n        }\n\n        return {\n            data: bytesToBase64(data),\n            mimeType: \"image/png\",\n            width: Math.round(width * scale),\n            height: Math.round(height * scale),\n        };\n    } finally {\n        renderer.unrealize();\n    }\n};\n\n/**\n * Captures a PNG snapshot of a widget, retrying until it has a paintable size.\n *\n * @param widget The widget to render to an image.\n * @param options Optional scale, timeout, and retry interval.\n * @returns The base64-encoded PNG data along with its mime type and dimensions.\n */\nconst screenshot = async (widget: Gtk.Widget, options?: ScreenshotOptions): Promise<ScreenshotResult> => {\n    const scale = options?.scale ?? 1;\n\n    if (!Number.isFinite(scale) || scale <= 0) {\n        throw new Error(`Screenshot scale must be a positive number, got ${String(scale)}`);\n    }\n\n    return waitFor(() => captureSnapshot(widget, scale), {\n        timeout: options?.timeout,\n        interval: options?.interval ?? DEFAULT_SCREENSHOT_INTERVAL,\n    });\n};\n\nconst firstToplevelWindow = (windows: Gtk.Widget[]): Gtk.Window => {\n    const [first] = windows;\n\n    if (!(first instanceof Gtk.Window)) {\n        throw new TypeError(\"First toplevel is not a Window\");\n    }\n\n    return first;\n};\n\nconst windowAtIndex = (windows: Gtk.Widget[], index: number): Gtk.Window => {\n    const indexed = windows[index];\n\n    if (!(indexed instanceof Gtk.Window)) {\n        throw new TypeError(`Window at index ${String(index)} not found`);\n    }\n\n    return indexed;\n};\n\nconst isWindow = (widget: Gtk.Widget): widget is Gtk.Window => widget instanceof Gtk.Window;\n\nconst hasMatchingTitle = (window: Gtk.Window, selector: string | RegExp): boolean => {\n    const title = window.getTitle() ?? \"\";\n\n    return selector instanceof RegExp ? selector.test(title) : title.includes(selector);\n};\n\nconst describeTitleSelector = (selector: string | RegExp): string =>\n    selector instanceof RegExp ? selector.toString() : `\"${selector}\"`;\n\nconst windowByTitle = (windows: Gtk.Widget[], selector: string | RegExp): Gtk.Window => {\n    const found = windows.filter(isWindow).find((window) => hasMatchingTitle(window, selector));\n\n    if (!found) {\n        throw new Error(`No window found with title matching ${describeTitleSelector(selector)}`);\n    }\n\n    return found;\n};\n\nconst resolveWindow = (selector?: WindowSelector): Gtk.Window => {\n    const windows = Gtk.Window.listToplevels();\n\n    if (windows.length === 0) {\n        throw new Error(\"No windows available for screenshot\");\n    }\n\n    if (selector === undefined) {\n        return firstToplevelWindow(windows);\n    }\n\n    if (typeof selector === \"number\") {\n        return windowAtIndex(windows, selector);\n    }\n\n    return windowByTitle(windows, selector);\n};\n\nconst saveScreenshotToTempFile = (result: ScreenshotResult): string => {\n    const dir = mkdtempSync(join(tmpdir(), \"gtkx-screenshots-\"));\n    const filepath = join(dir, \"screenshot.png\");\n    writeFileSync(filepath, Buffer.from(result.data, \"base64\"));\n\n    return filepath;\n};\n\n/**\n * Prints a clickable file URL for a saved screenshot to the console.\n *\n * @param filepath Absolute path of the saved screenshot file.\n */\nconst logScreenshotPath = (filepath: string): void => {\n    console.log(`Screenshot saved: file://${filepath}`);\n};\n\n/**\n * Captures a screenshot of a toplevel window, writes it to a temporary file,\n * logs its path, and returns the image data.\n *\n * @param selector Chooses the window by index, title substring, or regular\n * expression; defaults to the first toplevel.\n * @param options Optional scale, timeout, and retry interval.\n * @returns The base64-encoded PNG data along with its mime type and dimensions.\n */\nconst captureAndSaveScreenshot = async (\n    selector?: WindowSelector,\n    options?: ScreenshotOptions,\n): Promise<ScreenshotResult> => {\n    const target = resolveWindow(selector);\n    const result = await screenshot(target, options);\n    logScreenshotPath(saveScreenshotToTempFile(result));\n\n    return result;\n};\n\nexport { screenshot, logScreenshotPath, captureAndSaveScreenshot };\n"]}
+{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../src/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,cAAc,CAAC;AACpC,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,GAAG,MAAM,cAAc,CAAC;AACpC,OAAO,KAAK,GAAG,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAsBxC,MAAM,2BAA2B,GAAG,EAAE,CAAC;AACvC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC,MAAM,sBAAsB,GACxB,iGAAiG;IACjG,oGAAoG;IACpG,6CAA6C,CAAC;AAElD,MAAM,iBAAiB,GACnB,qGAAqG,CAAC;AAE1G,MAAM,kBAAkB,GACpB,4FAA4F,CAAC;AAEjG,MAAM,yBAAyB,GAAG,+DAA+D,CAAC;AAElG,MAAM,aAAa,GAAG,CAAC,KAAe,EAAU,EAAE;IAC9C,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACjD,CAAC,CAAC;AAEF,MAAM,mBAAmB,GAAG,CAAC,MAAkB,EAAU,EAAE,CACvD,YAAY,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,WAAW,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,GAAG;IAChF,WAAW,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;AAE7C,MAAM,iBAAiB,GAAG,CAAC,MAAkB,EAAiB,EAAE;IAC5D,MAAM,QAAQ,GAAkB,EAAE,CAAC;IAEnC,KAAK,MAAM,UAAU,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3C,IAAI,UAAU,YAAY,GAAG,CAAC,OAAO,IAAI,UAAU,CAAC,SAAS,EAAE,EAAE,CAAC;YAC9D,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC9B,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AACpB,CAAC,CAAC;AAEF,MAAM,aAAa,GAAG,CAAC,QAAsB,EAAE,MAAkB,EAAE,OAAoB,EAAQ,EAAE;IAC7F,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAG,SAAS,CAAC,iBAAiB,EAAE,CAAC;IAC5C,MAAM,MAAM,GAAG,SAAS,CAAC,kBAAkB,EAAE,CAAC;IAE9C,IAAI,CAAC,SAAS,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC1C,OAAO;IACX,CAAC;IAED,QAAQ,CAAC,IAAI,EAAE,CAAC;IAChB,QAAQ,CAAC,SAAS,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnF,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,CAAC;AACvB,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,QAAsB,EAAE,MAAkB,EAAQ,EAAE;IACxE,KAAK,MAAM,OAAO,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9C,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,UAAU,GAAG,CAAC,MAAkB,EAAsB,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,UAAU,EAAE,IAAI,IAAI,CAAC;AACxG,MAAM,iBAAiB,GAAG,CAAC,MAAkB,EAAW,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,KAAK,CAAC;AAEpG,MAAM,aAAa,GAAG,CAAC,MAAkB,EAAyB,EAAE,CAChE,MAAM,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;AAEhE,MAAM,eAAe,GAAG,CAAC,MAAkB,EAAiB,EAAE,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,IAAI,IAAI,CAAC;AAEhH,MAAM,oBAAoB,GAAG,CAAC,MAAkB,EAAU,EAAE,CACxD,GAAG,mBAAmB,CAAC,MAAM,CAAC,kBAAkB,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,GAAG;IACpF,gBAAgB,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;AAEtD,MAAM,YAAY,GAAG,CAAC,MAAkB,EAAQ,EAAE;IAC9C,aAAa,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;AACpE,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,MAAkB,EAAc,EAAE;IACvD,YAAY,CAAC,MAAM,CAAC,CAAC;IAErB,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;AACvE,CAAC,CAAC;AAEF,MAAM,gBAAgB,GAAG,CAAC,MAAkB,EAAE,KAAiB,EAAQ,EAAE;IACrE,YAAY,CAAC,MAAM,CAAC,CAAC;IAErB,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QACzB,OAAO;IACX,CAAC;IAED,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAExC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACnB,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC;QACxB,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACjC,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,gBAAgB,GAAG,CAAC,MAAkB,EAAE,KAAiB,EAAW,EAAE;IACxE,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAExC,OAAO,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;AACjF,CAAC,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,MAAkB,EAAE,KAAiB,EAAW,EAAE,CACpE,iBAAiB,CAAC,MAAM,CAAC,IAAI,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAEjE,MAAM,qBAAqB,GAAG,CAAC,MAAkB,EAAE,KAAiB,EAAW,EAAE,CAC7E,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,IAAI,qBAAqB,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1F,MAAM,YAAY,GAAG,CAAC,MAAkB,EAAQ,EAAE;IAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IAE9B,IAAI,CAAC,IAAI,EAAE,CAAC;QACR,OAAO;IACX,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAEhC,IAAI,KAAK,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,mBAAmB,GAAG,CAAC,KAAiB,EAAW,EAAE,CACvD,KAAK,CAAC,SAAS,EAAE,IAAI,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,YAAY,GAAG,CAAC,OAAO,CAAC,CAAC;AAEjF,MAAM,gBAAgB,GAAG,CAAC,MAAkB,EAAE,KAAa,EAAE,KAAa,EAAE,MAAc,EAAyB,EAAE;IACjH,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC7B,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAC5C,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAEjC,OAAO,QAAQ,CAAC,MAAM,EAAE,CAAC;AAC7B,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,MAAkB,EAAE,KAAa,EAAyB,EAAE;IACjF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAE7B,KAAK,IAAI,KAAK,GAAG,MAAM,CAAC,aAAa,EAAE,EAAE,KAAK,KAAK,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC,cAAc,EAAE,EAAE,CAAC;QACtF,IAAI,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAC1C,CAAC;IACL,CAAC;IAED,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAEjC,OAAO,QAAQ,CAAC,MAAM,EAAE,CAAC;AAC7B,CAAC,CAAC;AAEF,MAAM,aAAa,GAAG,CAAC,MAAkB,EAAE,KAAa,EAAE,KAAa,EAAE,MAAc,EAAyB,EAAE;IAC9G,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAEjE,IAAI,SAAS,EAAE,CAAC;QACZ,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,YAAY,CAAC,MAAM,CAAC,CAAC;IAErB,OAAO,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAC5F,CAAC,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,MAAkB,EAAE,IAAoB,EAAE,KAAa,EAAE,MAAc,EAAoB,EAAE;IAC9G,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,iBAAiB,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IAEhD,IAAI,CAAC;QACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QACjE,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,CAAC;QAEhD,IAAI,CAAC,IAAI,EAAE,CAAC;YACR,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC7D,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAC/E,CAAC;YAAS,CAAC;QACP,QAAQ,CAAC,SAAS,EAAE,CAAC;IACzB,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,MAAkB,EAAE,KAAa,EAAiB,EAAE;IACzE,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IACtD,MAAM,KAAK,GAAG,SAAS,CAAC,iBAAiB,EAAE,CAAC;IAC5C,MAAM,MAAM,GAAG,SAAS,CAAC,kBAAkB,EAAE,CAAC;IAE9C,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IACpD,CAAC;IAED,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAE/D,IAAI,CAAC,UAAU,EAAE,CAAC;QACd,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;IACvD,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC;IAC9C,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC;IAEhD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,CAAC,EAAE,CAAC;AACtG,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,MAAkB,EAAE,OAAuB,EAAU,EAAE,CAC3E,OAAO,KAAK,SAAS;IACjB,CAAC,CAAC,0DAA0D,mBAAmB,CAAC,MAAM,CAAC,GAAG;IAC1F,CAAC,CAAC,sCAAsC,mBAAmB,CAAC,MAAM,CAAC,GAAG,CAAC;AAE/E,MAAM,oBAAoB,GAAG,CAAC,MAAkB,EAAU,EAAE,CACxD,GAAG,sBAAsB,KAAK,oBAAoB,CAAC,MAAM,CAAC,GAAG,CAAC;AAElE,MAAM,cAAc,GAAG,CAAC,MAAkB,EAAE,OAAuB,EAAU,EAAE,CAC3E,GAAG,oBAAoB,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;AAE5E,MAAM,cAAc,GAAG,CAAC,OAA8B,EAAU,EAAE,CAC9D,OAAO,KAAK,YAAY,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,kBAAkB,CAAC;AAEtE,MAAM,WAAW,GAAG,CAAC,MAAkB,EAAE,KAAmB,EAAU,EAAE,CACpE,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAErG,MAAM,cAAc,GAAG,CAAC,KAAY,EAAE,MAAkB,EAAE,KAAmB,EAAS,EAAE,CACpF,SAAS,EAAE,CAAC,eAAe,CAAC,GAAG,KAAK,CAAC,OAAO,OAAO,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;AAErF,MAAM,cAAc,GAAG,CAAC,MAAkB,EAAE,KAAa,EAAE,KAAmB,EAAkB,EAAE;IAC9F,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAE/C,IAAI,OAAO,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QAChC,OAAO,OAAO,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAChC,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAEtC,IAAI,qBAAqB,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3D,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;AAC7D,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,MAAwB,EAAE,IAAY,EAAQ,EAAE;IACrE,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC5D,CAAC,CAAC;AAEF,MAAM,qBAAqB,GAAG,CAC1B,MAAkB,EAClB,KAAa,EACb,OAAsC,EACf,EAAE;IACzB,MAAM,KAAK,GAAiB,EAAE,KAAK,EAAE,eAAe,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAE9E,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE;QACvD,OAAO,EAAE,OAAO,EAAE,OAAO;QACzB,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,2BAA2B;QAC1D,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC;KAC7D,CAAC,CAAC;AACP,CAAC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,GAAG,KAAK,EAAE,MAAkB,EAAE,OAA2B,EAA6B,EAAE;IACpG,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,CAAC,CAAC;IAElC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,mDAAmD,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACxF,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,qBAAqB,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAEpE,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,IAAI,OAAO,EAAE,IAAI,EAAE,CAAC;QAChB,eAAe,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,OAAO,CAAC,MAAM,CAAC;AAC1B,CAAC,CAAC;AAEF,MAAM,QAAQ,GAAG,CAAC,MAAkB,EAAwB,EAAE,CAAC,MAAM,YAAY,GAAG,CAAC,MAAM,CAAC;AAC5F,MAAM,UAAU,GAAG,CAAC,MAAkB,EAAW,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;AACvE,MAAM,cAAc,GAAG,CAAC,MAAkB,EAAW,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;AAE1E,MAAM,cAAc,GAAG,GAAe,EAAE;IACpC,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAClF,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC;IAEhF,IAAI,CAAC,MAAM,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC,CAAC;AAEF,MAAM,aAAa,GAAG,KAAK,EAAE,OAA2B,EAA6B,EAAE;IACnF,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;IAEhC,OAAO,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC,CAAC;AAEF,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC","sourcesContent":["import * as Gdk from \"@gtkx/gi/gdk\";\nimport * as Graphene from \"@gtkx/gi/graphene\";\nimport * as Gsk from \"@gtkx/gi/gsk\";\nimport * as Gtk from \"@gtkx/gi/gtk\";\nimport { mkdirSync, writeFileSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport type { ScreenshotOptions, ScreenshotResult } from \"./types.js\";\nimport { getConfig } from \"./config.js\";\nimport { descendants } from \"./traversal.js\";\nimport { waitFor } from \"./wait-for.js\";\n\ntype FrameProbe = {\n    counter: bigint | null;\n    startedAt: number;\n};\n\ntype CaptureFailure = \"no-size\" | \"no-content\";\n\ntype CaptureState = {\n    probe: FrameProbe;\n    failure: CaptureFailure | null;\n};\n\ntype CaptureResult =\n    { status: \"captured\"; result: ScreenshotResult } |\n    { status: \"failed\"; failure: CaptureFailure };\n\ntype CaptureOutcome =\n    { status: \"captured\"; result: ScreenshotResult } |\n    { status: \"stalled\"; failure: CaptureFailure };\n\nconst DEFAULT_SCREENSHOT_INTERVAL = 10;\nconst PRESENTATION_PROBE_MS = 250;\n\nconst NOT_PRESENTING_MESSAGE =\n    \"Screenshot failed: the display is not presenting frames to this window, so GTK has no rendered \" +\n    \"content to capture. The window is hidden, minimized, or its compositor is not presenting it; this \" +\n    \"is a display problem, not a widget problem.\";\n\nconst EMPTY_WIDGET_HINT =\n    \"The display is presenting frames to this window, so the widget itself is empty: it painted nothing.\";\n\nconst OTHER_FAILURE_HINT =\n    \"The display is presenting frames to this window, so the capture failed for another reason.\";\n\nconst NOTHING_ON_SCREEN_MESSAGE = \"Nothing is on screen to capture: no toplevel window is mapped\";\n\nconst bytesToBase64 = (bytes: number[]): string => {\n    return Buffer.from(bytes).toString(\"base64\");\n};\n\nconst describeWidgetState = (widget: Gtk.Widget): string =>\n    `realized=${String(widget.getRealized())} mapped=${String(widget.getMapped())} ` +\n    `visible=${String(widget.getVisible())}`;\n\nconst getMappedPopovers = (widget: Gtk.Widget): Gtk.Popover[] => {\n    const popovers: Gtk.Popover[] = [];\n\n    for (const descendant of descendants(widget)) {\n        if (descendant instanceof Gtk.Popover && descendant.getMapped()) {\n            popovers.push(descendant);\n        }\n    }\n\n    return popovers;\n};\n\nconst appendPopover = (snapshot: Gtk.Snapshot, target: Gtk.Widget, popover: Gtk.Popover): void => {\n    const [hasBounds, bounds] = popover.computeBounds(target);\n    const paintable = new Gtk.WidgetPaintable({ widget: popover });\n    const width = paintable.getIntrinsicWidth();\n    const height = paintable.getIntrinsicHeight();\n\n    if (!hasBounds || width <= 0 || height <= 0) {\n        return;\n    }\n\n    snapshot.save();\n    snapshot.translate(new Graphene.Point({ x: bounds.origin.x, y: bounds.origin.y }));\n    paintable.snapshot(snapshot, width, height);\n    snapshot.restore();\n};\n\nconst appendPopovers = (snapshot: Gtk.Snapshot, target: Gtk.Widget): void => {\n    for (const popover of getMappedPopovers(target)) {\n        appendPopover(snapshot, target, popover);\n    }\n};\n\nconst getSurface = (widget: Gtk.Widget): Gdk.Surface | null => widget.getNative()?.getSurface() ?? null;\nconst isSurfaceOnScreen = (widget: Gtk.Widget): boolean => getSurface(widget)?.getMapped() ?? false;\n\nconst getFrameClock = (widget: Gtk.Widget): Gdk.FrameClock | null =>\n    widget.getRoot()?.getFrameClock() ?? widget.getFrameClock();\n\nconst getFrameCounter = (widget: Gtk.Widget): bigint | null => getFrameClock(widget)?.getFrameCounter() ?? null;\n\nconst describePresentation = (widget: Gtk.Widget): string =>\n    `${describeWidgetState(widget)} surfaceMapped=${String(isSurfaceOnScreen(widget))} ` +\n    `frameCounter=${String(getFrameCounter(widget))}`;\n\nconst requestFrame = (widget: Gtk.Widget): void => {\n    getFrameClock(widget)?.requestPhase(Gdk.FrameClockPhase.UPDATE);\n};\n\nconst startFrameProbe = (widget: Gtk.Widget): FrameProbe => {\n    requestFrame(widget);\n\n    return { counter: getFrameCounter(widget), startedAt: Date.now() };\n};\n\nconst updateFrameProbe = (widget: Gtk.Widget, probe: FrameProbe): void => {\n    requestFrame(widget);\n\n    if (probe.counter !== null) {\n        return;\n    }\n\n    const counter = getFrameCounter(widget);\n\n    if (counter !== null) {\n        probe.counter = counter;\n        probe.startedAt = Date.now();\n    }\n};\n\nconst hasFrameAdvanced = (widget: Gtk.Widget, probe: FrameProbe): boolean => {\n    const counter = getFrameCounter(widget);\n\n    return counter !== null && probe.counter !== null && counter > probe.counter;\n};\n\nconst isPresenting = (widget: Gtk.Widget, probe: FrameProbe): boolean =>\n    isSurfaceOnScreen(widget) && hasFrameAdvanced(widget, probe);\n\nconst isPresentationStalled = (widget: Gtk.Widget, probe: FrameProbe): boolean =>\n    Date.now() - probe.startedAt >= PRESENTATION_PROBE_MS && !isPresenting(widget, probe);\n\nconst allocateRoot = (widget: Gtk.Widget): void => {\n    const root = widget.getRoot();\n\n    if (!root) {\n        return;\n    }\n\n    const width = root.getWidth();\n    const height = root.getHeight();\n\n    if (width > 0 && height > 0) {\n        root.allocate(width, height, -1, null);\n    }\n};\n\nconst isDirectlyPaintable = (child: Gtk.Widget): boolean =>\n    child.getMapped() && child.getWidth() > 0 && !(child instanceof Gtk.Popover);\n\nconst getPaintableNode = (widget: Gtk.Widget, scale: number, width: number, height: number): Gsk.RenderNode | null => {\n    const paintable = new Gtk.WidgetPaintable({ widget });\n    const snapshot = new Gtk.Snapshot();\n    snapshot.scale(scale, scale);\n    paintable.snapshot(snapshot, width, height);\n    appendPopovers(snapshot, widget);\n\n    return snapshot.toNode();\n};\n\nconst getChildrenNode = (widget: Gtk.Widget, scale: number): Gsk.RenderNode | null => {\n    const snapshot = new Gtk.Snapshot();\n    snapshot.scale(scale, scale);\n\n    for (let child = widget.getFirstChild(); child !== null; child = child.getNextSibling()) {\n        if (isDirectlyPaintable(child)) {\n            widget.snapshotChild(child, snapshot);\n        }\n    }\n\n    appendPopovers(snapshot, widget);\n\n    return snapshot.toNode();\n};\n\nconst getRenderNode = (widget: Gtk.Widget, scale: number, width: number, height: number): Gsk.RenderNode | null => {\n    const presented = getPaintableNode(widget, scale, width, height);\n\n    if (presented) {\n        return presented;\n    }\n\n    allocateRoot(widget);\n\n    return getPaintableNode(widget, scale, width, height) ?? getChildrenNode(widget, scale);\n};\n\nconst renderToPng = (widget: Gtk.Widget, node: Gsk.RenderNode, width: number, height: number): ScreenshotResult => {\n    const renderer = new Gsk.CairoRenderer();\n    renderer.realizeForDisplay(widget.getDisplay());\n\n    try {\n        const viewport = Graphene.Rect.alloc().init(0, 0, width, height);\n        const texture = renderer.renderTexture(node, viewport);\n        const data = texture.saveToPngBytes().getData();\n\n        if (!data) {\n            throw new Error(\"Failed to serialize screenshot to PNG\");\n        }\n\n        return { data: bytesToBase64(data), mimeType: \"image/png\", width, height };\n    } finally {\n        renderer.unrealize();\n    }\n};\n\nconst captureSnapshot = (widget: Gtk.Widget, scale: number): CaptureResult => {\n    const paintable = new Gtk.WidgetPaintable({ widget });\n    const width = paintable.getIntrinsicWidth();\n    const height = paintable.getIntrinsicHeight();\n\n    if (width <= 0 || height <= 0) {\n        return { status: \"failed\", failure: \"no-size\" };\n    }\n\n    const renderNode = getRenderNode(widget, scale, width, height);\n\n    if (!renderNode) {\n        return { status: \"failed\", failure: \"no-content\" };\n    }\n\n    const scaledWidth = Math.round(width * scale);\n    const scaledHeight = Math.round(height * scale);\n\n    return { status: \"captured\", result: renderToPng(widget, renderNode, scaledWidth, scaledHeight) };\n};\n\nconst failureMessage = (widget: Gtk.Widget, failure: CaptureFailure): string =>\n    failure === \"no-size\"\n        ? `Widget has no size: ensure it is realized and visible (${describeWidgetState(widget)})`\n        : `Widget produced no render content (${describeWidgetState(widget)})`;\n\nconst notPresentingMessage = (widget: Gtk.Widget): string =>\n    `${NOT_PRESENTING_MESSAGE} (${describePresentation(widget)})`;\n\nconst stalledMessage = (widget: Gtk.Widget, failure: CaptureFailure): string =>\n    `${notPresentingMessage(widget)}\\n\\n${failureMessage(widget, failure)}`;\n\nconst presentingHint = (failure: CaptureFailure | null): string =>\n    failure === \"no-content\" ? EMPTY_WIDGET_HINT : OTHER_FAILURE_HINT;\n\nconst timeoutHint = (widget: Gtk.Widget, state: CaptureState): string =>\n    isPresenting(widget, state.probe) ? presentingHint(state.failure) : notPresentingMessage(widget);\n\nconst explainTimeout = (error: Error, widget: Gtk.Widget, state: CaptureState): Error =>\n    getConfig().getElementError(`${error.message}\\n\\n${timeoutHint(widget, state)}`);\n\nconst attemptCapture = (widget: Gtk.Widget, scale: number, state: CaptureState): CaptureOutcome => {\n    const attempt = captureSnapshot(widget, scale);\n\n    if (attempt.status === \"captured\") {\n        return attempt;\n    }\n\n    state.failure = attempt.failure;\n    updateFrameProbe(widget, state.probe);\n\n    if (isPresentationStalled(widget, state.probe)) {\n        return { status: \"stalled\", failure: attempt.failure };\n    }\n\n    throw new Error(failureMessage(widget, attempt.failure));\n};\n\nconst writeScreenshot = (result: ScreenshotResult, path: string): void => {\n    mkdirSync(dirname(path), { recursive: true });\n    writeFileSync(path, Buffer.from(result.data, \"base64\"));\n};\n\nconst captureUntilPaintable = (\n    widget: Gtk.Widget,\n    scale: number,\n    options: ScreenshotOptions | undefined,\n): Promise<CaptureOutcome> => {\n    const state: CaptureState = { probe: startFrameProbe(widget), failure: null };\n\n    return waitFor(() => attemptCapture(widget, scale, state), {\n        timeout: options?.timeout,\n        interval: options?.interval ?? DEFAULT_SCREENSHOT_INTERVAL,\n        onTimeout: (error) => explainTimeout(error, widget, state),\n    });\n};\n\n/**\n * Captures a PNG snapshot of a widget, retrying until it has a paintable size,\n * and writes the image to `options.path` when one is given, creating any\n * missing parent directories. Popovers open inside the widget render on their\n * own surfaces, so they are composited into the image at their on-screen\n * positions. A display that never presents a frame leaves GTK without a cached\n * render node, so the widget's contents are then snapshotted directly; when\n * even that yields nothing, the failure names the display instead of blaming\n * the widget.\n *\n * @param widget The widget to render to an image.\n * @param options Optional scale, timeout, retry interval, and output path.\n * @returns The base64-encoded PNG data along with its mime type and dimensions.\n */\nconst screenshot = async (widget: Gtk.Widget, options?: ScreenshotOptions): Promise<ScreenshotResult> => {\n    const scale = options?.scale ?? 1;\n\n    if (!Number.isFinite(scale) || scale <= 0) {\n        throw new Error(`Screenshot scale must be a positive number, got ${String(scale)}`);\n    }\n\n    const outcome = await captureUntilPaintable(widget, scale, options);\n\n    if (outcome.status === \"stalled\") {\n        throw new Error(stalledMessage(widget, outcome.failure));\n    }\n\n    if (options?.path) {\n        writeScreenshot(outcome.result, options.path);\n    }\n\n    return outcome.result;\n};\n\nconst isWindow = (widget: Gtk.Widget): widget is Gtk.Window => widget instanceof Gtk.Window;\nconst isOnScreen = (window: Gtk.Window): boolean => window.getMapped();\nconst isActiveWindow = (window: Gtk.Window): boolean => window.isActive();\n\nconst activeToplevel = (): Gtk.Window => {\n    const toplevels = Gtk.Window.listToplevels().filter((widget) => isWindow(widget));\n    const onScreen = toplevels.filter((window) => isOnScreen(window));\n    const target = onScreen.find((window) => isActiveWindow(window)) ?? onScreen[0];\n\n    if (!target) {\n        throw new Error(NOTHING_ON_SCREEN_MESSAGE);\n    }\n\n    return target;\n};\n\nconst captureScreen = async (options?: ScreenshotOptions): Promise<ScreenshotResult> => {\n    const target = activeToplevel();\n\n    return screenshot(target, options);\n};\n\nexport { captureScreen, screenshot };\n"]}

package/dist/traversal.d.ts

@@ -12,9 +12,12 @@ type QueryContainer = Gtk.Widget | Gtk.EventController | Gtk.LayoutManager | Gtk
 type Container = QueryContainer | Gtk.Application | typeof TOPLEVELS;
 /** Container sentinel that widens a query to every toplevel window currently open. */
 declare const TOPLEVELS: unique symbol;
+declare const isOnScreen: (widget: Gtk.Widget) => boolean;
+declare const children: (widget: Gtk.Widget) => Generator<Gtk.Widget>;
 declare const descendants: (widget: Gtk.Widget) => Generator<Gtk.Widget>;
+declare const relationCandidates: (widget: Gtk.Widget) => Gtk.Accessible[];
 declare const roots: (container: Container) => Generator<Gtk.Widget>;
 declare const traverse: (container: Container) => Generator<Gtk.Widget>;
 declare const findAll: (container: Container, isMatch: (node: Gtk.Widget) => boolean) => Gtk.Widget[];
-export { TOPLEVELS, descendants, roots, traverse, findAll, type Container };
+export { TOPLEVELS, children, descendants, findAll, isOnScreen, relationCandidates, roots, traverse, type Container, };
 //# sourceMappingURL=traversal.d.ts.map

package/dist/traversal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"traversal.d.ts","sourceRoot":"","sources":["../src/traversal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,cAAc,CAAC;AAEpC;;;GAGG;AACH,KAAK,cAAc,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,eAAe,GAAG,GAAG,CAAC,aAAa,GAAG,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC;AAC3G;;;;GAIG;AACH,KAAK,SAAS,GAAG,cAAc,GAAG,GAAG,CAAC,WAAW,GAAG,OAAO,SAAS,CAAC;AAErE,sFAAsF;AACtF,QAAA,MAAM,SAAS,EAAE,OAAO,MAAiC,CAAC;AAc1D,QAAA,MAAM,WAAW,GAAc,QAAQ,GAAG,CAAC,MAAM,KAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAIvE,CAAC;AAsBF,QAAA,MAAM,KAAK,GAAc,WAAW,SAAS,KAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAYnE,CAAC;AAEF,QAAA,MAAM,QAAQ,GAAc,WAAW,SAAS,KAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAItE,CAAC;AAEF,QAAA,MAAM,OAAO,GAAI,WAAW,SAAS,EAAE,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,KAAK,OAAO,KAAG,GAAG,CAAC,MAAM,EAUzF,CAAC;AAEF,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,SAAS,EAAE,CAAC"}
+{"version":3,"file":"traversal.d.ts","sourceRoot":"","sources":["../src/traversal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,cAAc,CAAC;AAEpC;;;GAGG;AACH,KAAK,cAAc,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,eAAe,GAAG,GAAG,CAAC,aAAa,GAAG,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC;AAC3G;;;;GAIG;AACH,KAAK,SAAS,GAAG,cAAc,GAAG,GAAG,CAAC,WAAW,GAAG,OAAO,SAAS,CAAC;AAErE,sFAAsF;AACtF,QAAA,MAAM,SAAS,EAAE,OAAO,MAAiC,CAAC;AAI1D,QAAA,MAAM,UAAU,GAAI,QAAQ,GAAG,CAAC,MAAM,KAAG,OAA6B,CAAC;AAkBvE,QAAA,MAAM,QAAQ,GAAc,QAAQ,GAAG,CAAC,MAAM,KAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAOpE,CAAC;AAEF,QAAA,MAAM,WAAW,GAAc,QAAQ,GAAG,CAAC,MAAM,KAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAIvE,CAAC;AAEF,QAAA,MAAM,kBAAkB,GAAI,QAAQ,GAAG,CAAC,MAAM,KAAG,GAAG,CAAC,UAAU,EAS9D,CAAC;AAsBF,QAAA,MAAM,KAAK,GAAc,WAAW,SAAS,KAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAYnE,CAAC;AAEF,QAAA,MAAM,QAAQ,GAAc,WAAW,SAAS,KAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAItE,CAAC;AAEF,QAAA,MAAM,OAAO,GAAI,WAAW,SAAS,EAAE,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,KAAK,OAAO,KAAG,GAAG,CAAC,MAAM,EAUzF,CAAC;AAEF,OAAO,EACH,SAAS,EACT,QAAQ,EACR,WAAW,EACX,OAAO,EACP,UAAU,EACV,kBAAkB,EAClB,KAAK,EACL,QAAQ,EACR,KAAK,SAAS,GACjB,CAAC"}

package/dist/traversal.js

@@ -2,19 +2,38 @@ import * as Gtk from "@gtkx/gi/gtk";
 /** Container sentinel that widens a query to every toplevel window currently open. */
 const TOPLEVELS = Symbol("gtkx.toplevels");
 const isApplication = (container) => container instanceof Gtk.Application;
-const traverseWidgetTree = function* (root) {
-    yield root;
+const isAnyWidget = () => true;
+const isOnScreen = (widget) => widget.getMapped();
+const traverseWidgetTree = function* (root, isIncluded) {
+    if (isIncluded(root)) {
+        yield root;
+    }
     let child = root.getFirstChild();
     while (child) {
-        yield* traverseWidgetTree(child);
+        yield* traverseWidgetTree(child, isIncluded);
+        child = child.getNextSibling();
+    }
+};
+const children = function* (widget) {
+    let child = widget.getFirstChild();
+    while (child) {
+        yield child;
         child = child.getNextSibling();
     }
 };
 const descendants = function* (widget) {
-    const tree = traverseWidgetTree(widget);
+    const tree = traverseWidgetTree(widget, isAnyWidget);
     tree.next();
     yield* tree;
 };
+const relationCandidates = (widget) => {
+    const pool = [...widget.listMnemonicLabels(), ...descendants(widget)];
+    const root = widget.getRoot();
+    if (root instanceof Gtk.Widget) {
+        pool.push(...traverseWidgetTree(root, isAnyWidget));
+    }
+    return [...new Set(pool)];
+};
 const resolveRoot = (container) => {
     if (container instanceof Gtk.Widget) {
         return container;
@@ -42,7 +61,7 @@ const roots = function* (container) {
 };
 const traverse = function* (container) {
     for (const root of roots(container)) {
-        yield* traverseWidgetTree(root);
+        yield* traverseWidgetTree(root, isOnScreen);
     }
 };
 const findAll = (container, isMatch) => {
@@ -54,5 +73,5 @@ const findAll = (container, isMatch) => {
     }
     return results;
 };
-export { TOPLEVELS, descendants, roots, traverse, findAll };
+export { TOPLEVELS, children, descendants, findAll, isOnScreen, relationCandidates, roots, traverse, };
 //# sourceMappingURL=traversal.js.map

package/dist/traversal.js.map

@@ -1 +1 @@
-{"version":3,"file":"traversal.js","sourceRoot":"","sources":["../src/traversal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,cAAc,CAAC;AAcpC,sFAAsF;AACtF,MAAM,SAAS,GAAkB,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAE1D,MAAM,aAAa,GAAG,CAAC,SAAoB,EAAgC,EAAE,CAAC,SAAS,YAAY,GAAG,CAAC,WAAW,CAAC;AAEnH,MAAM,kBAAkB,GAAG,QAAQ,CAAC,EAAE,IAAgB;IAClD,MAAM,IAAI,CAAC;IACX,IAAI,KAAK,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;IAEjC,OAAO,KAAK,EAAE,CAAC;QACX,KAAK,CAAC,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;QACjC,KAAK,GAAG,KAAK,CAAC,cAAc,EAAE,CAAC;IACnC,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,WAAW,GAAG,QAAQ,CAAC,EAAE,MAAkB;IAC7C,MAAM,IAAI,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,CAAC,IAAI,EAAE,CAAC;IACZ,KAAK,CAAC,CAAC,IAAI,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,SAAyB,EAAqB,EAAE;IACjE,IAAI,SAAS,YAAY,GAAG,CAAC,MAAM,EAAE,CAAC;QAClC,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,IAAI,SAAS,YAAY,GAAG,CAAC,eAAe,EAAE,CAAC;QAC3C,OAAO,SAAS,CAAC,SAAS,EAAE,CAAC;IACjC,CAAC;IAED,IAAI,SAAS,YAAY,GAAG,CAAC,aAAa,EAAE,CAAC;QACzC,OAAO,SAAS,CAAC,SAAS,EAAE,CAAC;IACjC,CAAC;IAED,IAAI,SAAS,YAAY,GAAG,CAAC,QAAQ,IAAI,SAAS,YAAY,GAAG,CAAC,UAAU,EAAE,CAAC;QAC3E,OAAO,SAAS,CAAC,QAAQ,EAAE,CAAC;IAChC,CAAC;IAED,OAAO,IAAI,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,KAAK,GAAG,QAAQ,CAAC,EAAE,SAAoB;IACzC,IAAI,SAAS,KAAK,SAAS,IAAI,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC;QACtD,KAAK,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;QAElC,OAAO;IACX,CAAC;IAED,MAAM,IAAI,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IAEpC,IAAI,IAAI,EAAE,CAAC;QACP,MAAM,IAAI,CAAC;IACf,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,QAAQ,GAAG,QAAQ,CAAC,EAAE,SAAoB;IAC5C,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QAClC,KAAK,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,OAAO,GAAG,CAAC,SAAoB,EAAE,OAAsC,EAAgB,EAAE;IAC3F,MAAM,OAAO,GAAiB,EAAE,CAAC;IAEjC,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAChB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACnB,CAAC,CAAC;AAEF,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAkB,CAAC","sourcesContent":["import * as Gtk from \"@gtkx/gi/gtk\";\n\n/**\n * A scope that resolves to a single root widget: the widget itself, the widget a controller or\n * layout manager is attached to, or a list item's or header's child.\n */\ntype QueryContainer = Gtk.Widget | Gtk.EventController | Gtk.LayoutManager | Gtk.ListItem | Gtk.ListHeader;\n/**\n * A scope that queries and traversal can run against: a widget, an event\n * controller, a layout manager, a list item or header, an application, or the\n * sentinel representing all current toplevel windows.\n */\ntype Container = QueryContainer | Gtk.Application | typeof TOPLEVELS;\n\n/** Container sentinel that widens a query to every toplevel window currently open. */\nconst TOPLEVELS: unique symbol = Symbol(\"gtkx.toplevels\");\n\nconst isApplication = (container: Container): container is Gtk.Application => container instanceof Gtk.Application;\n\nconst traverseWidgetTree = function* (root: Gtk.Widget): Generator<Gtk.Widget> {\n    yield root;\n    let child = root.getFirstChild();\n\n    while (child) {\n        yield* traverseWidgetTree(child);\n        child = child.getNextSibling();\n    }\n};\n\nconst descendants = function* (widget: Gtk.Widget): Generator<Gtk.Widget> {\n    const tree = traverseWidgetTree(widget);\n    tree.next();\n    yield* tree;\n};\n\nconst resolveRoot = (container: QueryContainer): Gtk.Widget | null => {\n    if (container instanceof Gtk.Widget) {\n        return container;\n    }\n\n    if (container instanceof Gtk.EventController) {\n        return container.getWidget();\n    }\n\n    if (container instanceof Gtk.LayoutManager) {\n        return container.getWidget();\n    }\n\n    if (container instanceof Gtk.ListItem || container instanceof Gtk.ListHeader) {\n        return container.getChild();\n    }\n\n    return null;\n};\n\nconst roots = function* (container: Container): Generator<Gtk.Widget> {\n    if (container === TOPLEVELS || isApplication(container)) {\n        yield* Gtk.Window.listToplevels();\n\n        return;\n    }\n\n    const root = resolveRoot(container);\n\n    if (root) {\n        yield root;\n    }\n};\n\nconst traverse = function* (container: Container): Generator<Gtk.Widget> {\n    for (const root of roots(container)) {\n        yield* traverseWidgetTree(root);\n    }\n};\n\nconst findAll = (container: Container, isMatch: (node: Gtk.Widget) => boolean): Gtk.Widget[] => {\n    const results: Gtk.Widget[] = [];\n\n    for (const node of traverse(container)) {\n        if (isMatch(node)) {\n            results.push(node);\n        }\n    }\n\n    return results;\n};\n\nexport { TOPLEVELS, descendants, roots, traverse, findAll, type Container };\n"]}
+{"version":3,"file":"traversal.js","sourceRoot":"","sources":["../src/traversal.ts"],"names":[],"mappings":"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","sourcesContent":["import * as Gtk from \"@gtkx/gi/gtk\";\n\n/**\n * A scope that resolves to a single root widget: the widget itself, the widget a controller or\n * layout manager is attached to, or a list item's or header's child.\n */\ntype QueryContainer = Gtk.Widget | Gtk.EventController | Gtk.LayoutManager | Gtk.ListItem | Gtk.ListHeader;\n/**\n * A scope that queries and traversal can run against: a widget, an event\n * controller, a layout manager, a list item or header, an application, or the\n * sentinel representing all current toplevel windows.\n */\ntype Container = QueryContainer | Gtk.Application | typeof TOPLEVELS;\n\n/** Container sentinel that widens a query to every toplevel window currently open. */\nconst TOPLEVELS: unique symbol = Symbol(\"gtkx.toplevels\");\n\nconst isApplication = (container: Container): container is Gtk.Application => container instanceof Gtk.Application;\nconst isAnyWidget = (): boolean => true;\nconst isOnScreen = (widget: Gtk.Widget): boolean => widget.getMapped();\n\nconst traverseWidgetTree = function* (\n    root: Gtk.Widget,\n    isIncluded: (widget: Gtk.Widget) => boolean,\n): Generator<Gtk.Widget> {\n    if (isIncluded(root)) {\n        yield root;\n    }\n\n    let child = root.getFirstChild();\n\n    while (child) {\n        yield* traverseWidgetTree(child, isIncluded);\n        child = child.getNextSibling();\n    }\n};\n\nconst children = function* (widget: Gtk.Widget): Generator<Gtk.Widget> {\n    let child = widget.getFirstChild();\n\n    while (child) {\n        yield child;\n        child = child.getNextSibling();\n    }\n};\n\nconst descendants = function* (widget: Gtk.Widget): Generator<Gtk.Widget> {\n    const tree = traverseWidgetTree(widget, isAnyWidget);\n    tree.next();\n    yield* tree;\n};\n\nconst relationCandidates = (widget: Gtk.Widget): Gtk.Accessible[] => {\n    const pool: Gtk.Accessible[] = [...widget.listMnemonicLabels(), ...descendants(widget)];\n    const root = widget.getRoot();\n\n    if (root instanceof Gtk.Widget) {\n        pool.push(...traverseWidgetTree(root, isAnyWidget));\n    }\n\n    return [...new Set(pool)];\n};\n\nconst resolveRoot = (container: QueryContainer): Gtk.Widget | null => {\n    if (container instanceof Gtk.Widget) {\n        return container;\n    }\n\n    if (container instanceof Gtk.EventController) {\n        return container.getWidget();\n    }\n\n    if (container instanceof Gtk.LayoutManager) {\n        return container.getWidget();\n    }\n\n    if (container instanceof Gtk.ListItem || container instanceof Gtk.ListHeader) {\n        return container.getChild();\n    }\n\n    return null;\n};\n\nconst roots = function* (container: Container): Generator<Gtk.Widget> {\n    if (container === TOPLEVELS || isApplication(container)) {\n        yield* Gtk.Window.listToplevels();\n\n        return;\n    }\n\n    const root = resolveRoot(container);\n\n    if (root) {\n        yield root;\n    }\n};\n\nconst traverse = function* (container: Container): Generator<Gtk.Widget> {\n    for (const root of roots(container)) {\n        yield* traverseWidgetTree(root, isOnScreen);\n    }\n};\n\nconst findAll = (container: Container, isMatch: (node: Gtk.Widget) => boolean): Gtk.Widget[] => {\n    const results: Gtk.Widget[] = [];\n\n    for (const node of traverse(container)) {\n        if (isMatch(node)) {\n            results.push(node);\n        }\n    }\n\n    return results;\n};\n\nexport {\n    TOPLEVELS,\n    children,\n    descendants,\n    findAll,\n    isOnScreen,\n    relationCandidates,\n    roots,\n    traverse,\n    type Container,\n};\n"]}

package/dist/types.d.ts

@@ -50,13 +50,19 @@ type MatcherOptions<T extends Gtk.Widget = Gtk.Widget> = {
     /** Restricts matches to instances of this widget class, and narrows the query's return type to it. */
     as?: WidgetType<T> | undefined;
 } & WaitForOptions;
-/** Constraints on a widget's numeric range value used by role queries. */
+/**
+ * Constraints on a widget's numeric range value used by role queries. The numbers come from the
+ * accessibility tree and match within 0.001, the resolution GTK keeps them to.
+ */
 type ByRoleValue = {
     /** The current value. */
     now?: number | undefined;
     /** The lower bound of the value's range. */
     min?: number | undefined;
-    /** The upper bound of the value's range. */
+    /**
+     * The highest value the widget can reach, which on a paged widget such as a scrollbar is its
+     * adjustment's upper bound less one page.
+     */
     max?: number | undefined;
     /** Matcher for the value's textual representation. */
     text?: Matcher | undefined;
@@ -81,7 +87,7 @@ type ByRoleOptions<T extends Gtk.Widget = Gtk.Widget> = MatcherOptions<T> & {
     description?: Matcher | undefined;
     /** Constraints on the widget's range value, each checked only when given. */
     value?: ByRoleValue | undefined;
-    /** When true, include widgets excluded from the accessibility tree. */
+    /** When true, include widgets excluded from the accessibility tree. Widgets that are not mapped stay excluded. */
     hidden?: boolean | undefined;
 };
 /** A React component that wraps rendered content, receiving it as its children. */
@@ -157,8 +163,11 @@ type DebugUtilities = {
     debug: (element?: Container | Container[], options?: PrettyWidgetOptions) => void;
     /** Prints the accessible roles found in the scope, with the widgets carrying each one. */
     logRoles: () => void;
-    /** Captures a window, writes the image to a temporary file, and logs its path. */
-    screenshot: (selector?: WindowSelector, options?: ScreenshotOptions) => Promise<ScreenshotResult>;
+    /**
+     * Captures what is on screen, which is the active toplevel window: GTK4 exposes no position for
+     * a toplevel, so windows cannot be composited into a single image.
+     */
+    screenshot: (options?: ScreenshotOptions) => Promise<ScreenshotResult>;
 };
 /** A captured screenshot: base64-encoded image data, its MIME type, and pixel dimensions. */
 type ScreenshotResult = {
@@ -171,23 +180,25 @@ type ScreenshotResult = {
     /** Image height in pixels, after the scale factor is applied. */
     height: number;
 };
-/** Options for capturing a screenshot: the poll timeout and interval, plus a rendering scale factor. */
+/**
+ * Options for capturing a screenshot: the poll timeout and interval, a rendering scale factor, and
+ * a file to write the PNG to.
+ */
 type ScreenshotOptions = Pick<WaitForOptions, "timeout" | "interval"> & {
     /** Device scale factor applied when rendering. */
-    scale?: number;
+    scale?: number | undefined;
+    /** File the PNG is written to, with its parent directories created as needed. */
+    path?: string | undefined;
 };
-/**
- * Selects the window to screenshot by index, or by title (exact string or regular expression);
- * undefined targets the default window.
- */
-type WindowSelector = number | string | RegExp | undefined;
 /**
  * Options for {@link renderHook}: an optional wrapper and the initial props (required unless the
  * props type permits undefined).
  */
 type RenderHookOptions<Props> = {
+    /** Component wrapped around the one calling the hook, such as a context provider. */
     wrapper?: WrapperComponent;
 } & (undefined extends Props ? {
+    /** Props the hook is invoked with until `rerender` is given new ones. */
     initialProps?: Props;
 } : {
     initialProps: Props;
@@ -197,8 +208,9 @@ type RenderHookOptions<Props> = {
  * props and to unmount.
  */
 type RenderHookResult<Result, Props> = {
-    /** Holds the most recent value returned by the hook under `current`. */
+    /** Stable object the hook's return value is written to on every render. */
     result: {
+        /** The hook's latest return value. */
         current: Result;
     };
     /** Re-invokes the hook, keeping the previous props when none are given. */
@@ -206,5 +218,5 @@ type RenderHookResult<Result, Props> = {
     /** Unmounts the component that calls the hook. */
     unmount: () => Promise<void>;
 };
-export { type MatcherFunction, type Matcher, type NormalizerFn, type NormalizerOptions, type WaitForOptions, type MatcherOptions, type ByRoleValue, type ByRoleOptions, type WidgetType, type WrapperComponent, type QueryMap, type BoundCustomQueries, type QueryFamilies, type RenderOptions, type DebugUtilities, type ScreenshotResult, type ScreenshotOptions, type WindowSelector, type RenderHookOptions, type RenderHookResult, };
+export { type MatcherFunction, type Matcher, type NormalizerFn, type NormalizerOptions, type WaitForOptions, type MatcherOptions, type ByRoleValue, type ByRoleOptions, type WidgetType, type WrapperComponent, type QueryMap, type BoundCustomQueries, type QueryFamilies, type RenderOptions, type DebugUtilities, type ScreenshotResult, type ScreenshotOptions, type RenderHookOptions, type RenderHookResult, };
 //# sourceMappingURL=types.d.ts.map