@gtkx/testing 1.6.0 → 2.0.0-beta.10

package/src/queries.ts

@@ -12,6 +12,7 @@ import { multipleFoundError, notFoundError } from "./errors.js";
 import { getDefaultNormalizer } from "./normalize.js";
 import { type Container, findAll, traverse } from "./traversal.js";
 import {
+    buildInaccessibilityCheck,
     getWidgetAccessibleName,
     getWidgetBusyState,
     getWidgetDescription,
@@ -26,7 +27,6 @@ import {
     getWidgetPressedState,
     getWidgetSelectedState,
     getWidgetValueText,
-    isInaccessible,
     isWidgetChecked,
     isWidgetValueMatch,
     namingLabelText,
@@ -39,7 +39,7 @@ type BuiltinQueries = QueryFamilies<[container: Container]>;
 const roleQueries = nameQueryFamily(
     "Role",
     queryAllByRole,
-    buildQueries<[role: Gtk.AccessibleRole, options?: ByRoleOptions]>(
+    buildQueries<[role: Gtk.AccessibleRole, options?: ByRoleOptions<Gtk.Widget>], Gtk.Widget>(
         queryAllByRole,
         (container, matches, role, options) =>
             multipleFoundError(container, { queryType: "role", role, options }, matches),
@@ -50,7 +50,7 @@ const roleQueries = nameQueryFamily(
 const labelTextQueries = nameQueryFamily(
     "LabelText",
     queryAllByLabelText,
-    buildQueries<[text: Matcher, options?: MatcherOptions]>(
+    buildQueries<[text: Matcher, options?: MatcherOptions<Gtk.Widget>], Gtk.Widget>(
         queryAllByLabelText,
         (container, matches, text) => multipleFoundError(container, { queryType: "labelText", text }, matches),
         (container, text) => notFoundError(container, { queryType: "labelText", text }),
@@ -60,7 +60,7 @@ const labelTextQueries = nameQueryFamily(
 const textQueries = nameQueryFamily(
     "Text",
     queryAllByText,
-    buildQueries<[text: Matcher, options?: MatcherOptions]>(
+    buildQueries<[text: Matcher, options?: MatcherOptions<Gtk.Widget>], Gtk.Widget>(
         queryAllByText,
         (container, matches, text) => multipleFoundError(container, { queryType: "text", text }, matches),
         (container, text) => notFoundError(container, { queryType: "text", text }),
@@ -70,7 +70,7 @@ const textQueries = nameQueryFamily(
 const nameQueries = nameQueryFamily(
     "Name",
     queryAllByName,
-    buildQueries<[name: Matcher, options?: MatcherOptions]>(
+    buildQueries<[name: Matcher, options?: MatcherOptions<Gtk.Widget>], Gtk.Widget>(
         queryAllByName,
         (container, matches, name) => multipleFoundError(container, { queryType: "name", name }, matches),
         (container, name) => notFoundError(container, { queryType: "name", name }),
@@ -80,7 +80,7 @@ const nameQueries = nameQueryFamily(
 const placeholderTextQueries = nameQueryFamily(
     "PlaceholderText",
     queryAllByPlaceholderText,
-    buildQueries<[text: Matcher, options?: MatcherOptions]>(
+    buildQueries<[text: Matcher, options?: MatcherOptions<Gtk.Widget>], Gtk.Widget>(
         queryAllByPlaceholderText,
         (container, matches, text) => multipleFoundError(container, { queryType: "placeholderText", text }, matches),
         (container, text) => notFoundError(container, { queryType: "placeholderText", text }),
@@ -90,7 +90,7 @@ const placeholderTextQueries = nameQueryFamily(
 const displayValueQueries = nameQueryFamily(
     "DisplayValue",
     queryAllByDisplayValue,
-    buildQueries<[value: Matcher, options?: MatcherOptions]>(
+    buildQueries<[value: Matcher, options?: MatcherOptions<Gtk.Widget>], Gtk.Widget>(
         queryAllByDisplayValue,
         (container, matches, value) => multipleFoundError(container, { queryType: "displayValue", value }, matches),
         (container, value) => notFoundError(container, { queryType: "displayValue", value }),
@@ -106,161 +106,65 @@ const builtinQueries = {
     ...displayValueQueries,
 } as BuiltinQueries;
 
-/**
- * Returns the single mapped widget with a matching accessible role and options, or null when none
- * match. Widgets that are not mapped are never matched. Throws when more than one matches.
- */
+/** Queries one mapped widget by accessible role. */
 const queryByRole: BuiltinQueries["queryByRole"] = builtinQueries.queryByRole;
-/**
- * Returns every mapped widget with a matching accessible role and options. Widgets that are not
- * mapped are never matched. Throws when none match.
- */
+/** Gets all mapped widgets with an accessible role. */
 const getAllByRole: BuiltinQueries["getAllByRole"] = builtinQueries.getAllByRole;
-/**
- * Returns the single mapped widget with a matching accessible role and options. Widgets that are not
- * mapped are never matched. Throws when none or more than one matches.
- */
+/** Gets one mapped widget by accessible role. */
 const getByRole: BuiltinQueries["getByRole"] = builtinQueries.getByRole;
-/**
- * Waits for and returns every mapped widget with a matching accessible role and options, retrying
- * until at least one appears or the timeout elapses. Widgets that are not mapped are never matched.
- */
+/** Finds all mapped widgets with an accessible role. */
 const findAllByRole: BuiltinQueries["findAllByRole"] = builtinQueries.findAllByRole;
-/**
- * Waits for and returns the single mapped widget with a matching accessible role and options,
- * retrying until it appears or the timeout elapses. Widgets that are not mapped are never matched.
- * Rejects when none or more than one matches.
- */
+/** Finds one mapped widget by accessible role. */
 const findByRole: BuiltinQueries["findByRole"] = builtinQueries.findByRole;
-/**
- * Returns the single mapped widget with matching associated label text, or null when none match.
- * Widgets that are not mapped are never matched. Throws when more than one matches.
- */
+/** Queries one mapped widget by label text. */
 const queryByLabelText: BuiltinQueries["queryByLabelText"] = builtinQueries.queryByLabelText;
-/**
- * Returns every mapped widget with matching associated label text. Widgets that are not mapped are
- * never matched. Throws when none match.
- */
+/** Gets all mapped widgets with label text. */
 const getAllByLabelText: BuiltinQueries["getAllByLabelText"] = builtinQueries.getAllByLabelText;
-/**
- * Returns the single mapped widget with matching associated label text. Widgets that are not mapped
- * are never matched. Throws when none or more than one matches.
- */
+/** Gets one mapped widget by label text. */
 const getByLabelText: BuiltinQueries["getByLabelText"] = builtinQueries.getByLabelText;
-/**
- * Waits for and returns every mapped widget with matching associated label text, retrying until at
- * least one appears or the timeout elapses. Widgets that are not mapped are never matched.
- */
+/** Finds all mapped widgets with label text. */
 const findAllByLabelText: BuiltinQueries["findAllByLabelText"] = builtinQueries.findAllByLabelText;
-/**
- * Waits for and returns the single mapped widget with matching associated label text, retrying until
- * it appears or the timeout elapses. Widgets that are not mapped are never matched. Rejects when
- * none or more than one matches.
- */
+/** Finds one mapped widget by label text. */
 const findByLabelText: BuiltinQueries["findByLabelText"] = builtinQueries.findByLabelText;
-/**
- * Returns the single mapped widget with matching rendered text content, or null when none match.
- * Widgets that are not mapped are never matched. Throws when more than one matches.
- */
+/** Queries one mapped widget by rendered text. */
 const queryByText: BuiltinQueries["queryByText"] = builtinQueries.queryByText;
-/**
- * Returns every mapped widget with matching rendered text content. Widgets that are not mapped are
- * never matched. Throws when none match.
- */
+/** Gets all mapped widgets with rendered text. */
 const getAllByText: BuiltinQueries["getAllByText"] = builtinQueries.getAllByText;
-/**
- * Returns the single mapped widget with matching rendered text content. Widgets that are not mapped
- * are never matched. Throws when none or more than one matches.
- */
+/** Gets one mapped widget by rendered text. */
 const getByText: BuiltinQueries["getByText"] = builtinQueries.getByText;
-/**
- * Waits for and returns every mapped widget with matching rendered text content, retrying until at
- * least one appears or the timeout elapses. Widgets that are not mapped are never matched.
- */
+/** Finds all mapped widgets with rendered text. */
 const findAllByText: BuiltinQueries["findAllByText"] = builtinQueries.findAllByText;
-/**
- * Waits for and returns the single mapped widget with matching rendered text content, retrying until
- * it appears or the timeout elapses. Widgets that are not mapped are never matched. Rejects when
- * none or more than one matches.
- */
+/** Finds one mapped widget by rendered text. */
 const findByText: BuiltinQueries["findByText"] = builtinQueries.findByText;
-/**
- * Returns the single mapped widget with a matching widget name, or null when none match. Widgets
- * that are not mapped are never matched. Throws when more than one matches.
- */
+/** Queries one mapped widget by GTK name. */
 const queryByName: BuiltinQueries["queryByName"] = builtinQueries.queryByName;
-/**
- * Returns every mapped widget with a matching widget name. Widgets that are not mapped are never
- * matched. Throws when none match.
- */
+/** Gets all mapped widgets with a GTK name. */
 const getAllByName: BuiltinQueries["getAllByName"] = builtinQueries.getAllByName;
-/**
- * Returns the single mapped widget with a matching widget name. Widgets that are not mapped are
- * never matched. Throws when none or more than one matches.
- */
+/** Gets one mapped widget by GTK name. */
 const getByName: BuiltinQueries["getByName"] = builtinQueries.getByName;
-/**
- * Waits for and returns every mapped widget with a matching widget name, retrying until at least one
- * appears or the timeout elapses. Widgets that are not mapped are never matched.
- */
+/** Finds all mapped widgets with a GTK name. */
 const findAllByName: BuiltinQueries["findAllByName"] = builtinQueries.findAllByName;
-/**
- * Waits for and returns the single mapped widget with a matching widget name, retrying until it
- * appears or the timeout elapses. Widgets that are not mapped are never matched. Rejects when none
- * or more than one matches.
- */
+/** Finds one mapped widget by GTK name. */
 const findByName: BuiltinQueries["findByName"] = builtinQueries.findByName;
-/**
- * Returns the single mapped widget with matching placeholder text, or null when none match. Widgets
- * that are not mapped are never matched. Throws when more than one matches.
- */
+/** Queries one mapped widget by placeholder text. */
 const queryByPlaceholderText: BuiltinQueries["queryByPlaceholderText"] = builtinQueries.queryByPlaceholderText;
-/**
- * Returns every mapped widget with matching placeholder text. Widgets that are not mapped are never
- * matched. Throws when none match.
- */
+/** Gets all mapped widgets with placeholder text. */
 const getAllByPlaceholderText: BuiltinQueries["getAllByPlaceholderText"] = builtinQueries.getAllByPlaceholderText;
-/**
- * Returns the single mapped widget with matching placeholder text. Widgets that are not mapped are
- * never matched. Throws when none or more than one matches.
- */
+/** Gets one mapped widget by placeholder text. */
 const getByPlaceholderText: BuiltinQueries["getByPlaceholderText"] = builtinQueries.getByPlaceholderText;
-/**
- * Waits for and returns every mapped widget with matching placeholder text, retrying until at least
- * one appears or the timeout elapses. Widgets that are not mapped are never matched.
- */
+/** Finds all mapped widgets with placeholder text. */
 const findAllByPlaceholderText: BuiltinQueries["findAllByPlaceholderText"] = builtinQueries.findAllByPlaceholderText;
-/**
- * Waits for and returns the single mapped widget with matching placeholder text, retrying until it
- * appears or the timeout elapses. Widgets that are not mapped are never matched. Rejects when none
- * or more than one matches.
- */
+/** Finds one mapped widget by placeholder text. */
 const findByPlaceholderText: BuiltinQueries["findByPlaceholderText"] = builtinQueries.findByPlaceholderText;
-/**
- * Returns the single mapped widget with a matching display value, or null when none match. Widgets
- * that are not mapped are never matched. Throws when more than one matches.
- */
+/** Queries one mapped widget by display value. */
 const queryByDisplayValue: BuiltinQueries["queryByDisplayValue"] = builtinQueries.queryByDisplayValue;
-/**
- * Returns every mapped widget with a matching display value. Widgets that are not mapped are never
- * matched. Throws when none match.
- */
+/** Gets all mapped widgets with a display value. */
 const getAllByDisplayValue: BuiltinQueries["getAllByDisplayValue"] = builtinQueries.getAllByDisplayValue;
-/**
- * Returns the single mapped widget with a matching display value. Widgets that are not mapped are
- * never matched. Throws when none or more than one matches.
- */
+/** Gets one mapped widget by display value. */
 const getByDisplayValue: BuiltinQueries["getByDisplayValue"] = builtinQueries.getByDisplayValue;
-/**
- * Waits for and returns every mapped widget with a matching display value, retrying until at least
- * one appears or the timeout elapses. Widgets that are not mapped are never matched.
- */
+/** Finds all mapped widgets with a display value. */
 const findAllByDisplayValue: BuiltinQueries["findAllByDisplayValue"] = builtinQueries.findAllByDisplayValue;
-/**
- * Waits for and returns the single mapped widget with a matching display value, retrying until it
- * appears or the timeout elapses. Widgets that are not mapped are never matched. Rejects when none
- * or more than one matches.
- */
+/** Finds one mapped widget by display value. */
 const findByDisplayValue: BuiltinQueries["findByDisplayValue"] = builtinQueries.findByDisplayValue;
 
 const buildNormalizer = (options?: MatcherOptions): NormalizerFn => {
@@ -380,25 +284,27 @@ const hasMatchingAccessibleStates = (widget: Gtk.Widget, options: ByRoleOptions)
     hasMatchingDescriptionState(widget, options) &&
     hasMatchingValueState(widget, options);
 
-const isMatchingWidgetType = (widget: Gtk.Widget, options?: MatcherOptions): boolean =>
+const isMatchingWidgetType = <T extends Gtk.Accessible>(
+    widget: Gtk.Widget,
+    options?: MatcherOptions<T>,
+): widget is Gtk.Widget & T =>
     options?.as === undefined || widget instanceof options.as;
 
-const hasMatchingByRoleOptions = (widget: Gtk.Widget, options?: ByRoleOptions): boolean => {
+const hasMatchingAccessibleOptions = (widget: Gtk.Widget, options?: ByRoleOptions): boolean => {
     if (!options) {
         return true;
     }
 
     return (
-        isMatchingWidgetType(widget, options) &&
         hasMatchingAccessibleName(widget, options) &&
         hasMatchingAccessibleStates(widget, options)
     );
 };
 
-function nameQueryFamily<Args extends unknown[]>(
+function nameQueryFamily<Args extends unknown[], Element extends Gtk.Accessible>(
     suffix: string,
-    queryAllBy: QueryAllBy<Args>,
-    built: BuiltQueries<Args>,
+    queryAllBy: QueryAllBy<Args, Element>,
+    built: BuiltQueries<Args, Element>,
 ): Record<string, unknown> {
     const [queryBy, getAllBy, getBy, findAllBy, findBy] = built;
 
@@ -421,22 +327,30 @@ function nameQueryFamily<Args extends unknown[]>(
  * @param options Additional accessible name, state, and value constraints.
  * @returns Every matching widget, or an empty array when none match.
  */
-function queryAllByRole(
+function queryAllByRole<T extends Gtk.Accessible = Gtk.Widget>(
     container: Container,
     role: Gtk.AccessibleRole,
-    options?: ByRoleOptions,
-): Gtk.Widget[] {
-    return findAll(container, (widget) => {
+    options?: ByRoleOptions<T>,
+): T[] {
+    const isInaccessible = buildInaccessibilityCheck();
+
+    const matches = findAll(container, (widget) => {
         if (widget.getAccessibleRole() !== role) {
             return false;
         }
 
+        if (!isMatchingWidgetType(widget, options)) {
+            return false;
+        }
+
         if (!options?.hidden && isInaccessible(widget)) {
             return false;
         }
 
-        return hasMatchingByRoleOptions(widget, options);
+        return hasMatchingAccessibleOptions(widget, options);
     });
+
+    return matches.filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 const collectMnemonicMatch = (
@@ -490,14 +404,18 @@ const collectLabelMatches = (
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-function queryAllByLabelText(container: Container, text: Matcher, options?: MatcherOptions): Gtk.Widget[] {
+function queryAllByLabelText<T extends Gtk.Accessible = Gtk.Widget>(
+    container: Container,
+    text: Matcher,
+    options?: MatcherOptions<T>,
+): T[] {
     const results: Set<Gtk.Widget> = new Set();
 
     for (const widget of traverse(container)) {
         collectLabelMatches(results, widget, text, options);
     }
 
-    return [...results].filter((widget) => isMatchingWidgetType(widget, options));
+    return [...results].filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 /**
@@ -507,12 +425,18 @@ function queryAllByLabelText(container: Container, text: Matcher, options?: Matc
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-function queryAllByText(container: Container, text: Matcher, options?: MatcherOptions): Gtk.Widget[] {
-    return findAll(
+function queryAllByText<T extends Gtk.Accessible = Gtk.Widget>(
+    container: Container,
+    text: Matcher,
+    options?: MatcherOptions<T>,
+): T[] {
+    const matches = findAll(
         container,
         (widget) =>
             isMatchingWidgetType(widget, options) && isTextMatch(getWidgetLabelText(widget), text, widget, options),
     );
+
+    return matches.filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 /**
@@ -522,11 +446,17 @@ function queryAllByText(container: Container, text: Matcher, options?: MatcherOp
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-function queryAllByName(container: Container, name: Matcher, options?: MatcherOptions): Gtk.Widget[] {
-    return findAll(
+function queryAllByName<T extends Gtk.Accessible = Gtk.Widget>(
+    container: Container,
+    name: Matcher,
+    options?: MatcherOptions<T>,
+): T[] {
+    const matches = findAll(
         container,
         (widget) => isMatchingWidgetType(widget, options) && isTextMatch(getWidgetName(widget), name, widget, options),
     );
+
+    return matches.filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 /**
@@ -536,17 +466,19 @@ function queryAllByName(container: Container, name: Matcher, options?: MatcherOp
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-function queryAllByPlaceholderText(
+function queryAllByPlaceholderText<T extends Gtk.Accessible = Gtk.Widget>(
     container: Container,
     text: Matcher,
-    options?: MatcherOptions,
-): Gtk.Widget[] {
-    return findAll(
+    options?: MatcherOptions<T>,
+): T[] {
+    const matches = findAll(
         container,
         (widget) =>
             isMatchingWidgetType(widget, options) &&
             isTextMatch(getWidgetPlaceholderText(widget), text, widget, options),
     );
+
+    return matches.filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 /**
@@ -556,13 +488,19 @@ function queryAllByPlaceholderText(
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-function queryAllByDisplayValue(container: Container, value: Matcher, options?: MatcherOptions): Gtk.Widget[] {
-    return findAll(
+function queryAllByDisplayValue<T extends Gtk.Accessible = Gtk.Widget>(
+    container: Container,
+    value: Matcher,
+    options?: MatcherOptions<T>,
+): T[] {
+    const matches = findAll(
         container,
         (widget) =>
             isMatchingWidgetType(widget, options) &&
             isTextMatch(getWidgetDisplayValue(widget), value, widget, options),
     );
+
+    return matches.filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 export {

package/src/query-helpers.ts

@@ -1,5 +1,5 @@
 import type * as Gtk from "@gtkx/gi/gtk";
-import { camelCase } from "@gtkx/utils";
+import { getProperty } from "@gtkx/gi/gobject";
 import type { Matcher, MatcherOptions } from "./types.js";
 import { buildQueries } from "./build-queries.js";
 import { getElementError } from "./errors.js";
@@ -27,7 +27,13 @@ const queryHelpers: QueryHelpers = {
 };
 
 const readObjectProperty = (widget: Gtk.Widget, property: string): string | null => {
-    const value: unknown = Reflect.get(widget, camelCase(property));
+    let value: unknown;
+
+    try {
+        value = Reflect.apply(getProperty, undefined, [widget, property]);
+    } catch {
+        return null;
+    }
 
     if (typeof value === "string") {
         return value;
@@ -51,18 +57,20 @@ const readObjectProperty = (widget: Gtk.Widget, property: string): string | null
  * @param options Text matching options.
  * @returns Every matching widget, or an empty array when none match.
  */
-function queryAllByObjectProperty(
+function queryAllByObjectProperty<T extends Gtk.Accessible = Gtk.Widget>(
     property: string,
     container: Container,
     text: Matcher,
-    options?: MatcherOptions,
-): Gtk.Widget[] {
-    return findAll(
+    options?: MatcherOptions<T>,
+): T[] {
+    const matches = findAll(
         container,
         (widget) =>
             isMatchingWidgetType(widget, options) &&
             isTextMatch(readObjectProperty(widget, property), text, widget, options),
     );
+
+    return matches.filter((widget): widget is Gtk.Widget & T => isMatchingWidgetType(widget, options));
 }
 
 /**
@@ -76,12 +84,12 @@ function queryAllByObjectProperty(
  * @returns The matching widget, or null when none match.
  * @throws When more than one widget matches.
  */
-function queryByObjectProperty(
+function queryByObjectProperty<T extends Gtk.Accessible = Gtk.Widget>(
     property: string,
     container: Container,
     text: Matcher,
-    options?: MatcherOptions,
-): Gtk.Widget | null {
+    options?: MatcherOptions<T>,
+): T | null {
     const matches = queryAllByObjectProperty(property, container, text, options);
 
     if (matches.length > 1) {

package/src/render.tsx

@@ -1,4 +1,4 @@
-import type { RootElement } from "@gtkx/react";
+import type { CaughtErrorInfo, RootElement } from "@gtkx/react";
 import * as Gtk from "@gtkx/gi/gtk";
 import {
     createReconcilerRoot,
@@ -21,6 +21,7 @@ import { clearScreen, setScreen } from "./screen.js";
 import { captureScreen } from "./screenshot.js";
 import { type Container, roots, TOPLEVELS } from "./traversal.js";
 import { resetClipboard } from "./user-event/index.js";
+import { requireWidget } from "./widget-target.js";
 import { findPresentedWindowFailure, findRenderedWindowFailure, mappedToplevels } from "./window-state.js";
 import { within } from "./within.js";
 
@@ -125,6 +126,10 @@ const resolveContainer = (container: RenderOptions["container"]): ResolvedContai
         return { containerInfo: container, window: null };
     }
 
+    if (container !== undefined) {
+        requireWidget(container);
+    }
+
     const window = createHarnessWindow();
     window.setDecorated(false);
 
@@ -188,7 +193,7 @@ const settleRender = async (
 
 const renderErrorHandlers = <Q extends QueryMap>(options: RenderOptions<Q> | undefined) => ({
     onUncaughtError: handleError,
-    onCaughtError: (error: unknown, errorInfo: ErrorInfo): void => {
+    onCaughtError: (error: unknown, errorInfo: CaughtErrorInfo): void => {
         handleError(error);
         options?.onCaughtError?.(error, errorInfo);
     },

package/src/role-helpers.ts

@@ -3,6 +3,7 @@ import { sortStringsBy } from "@gtkx/utils";
 import { type Container, traverse } from "./traversal.js";
 import { getWidgetAccessibleName, getWidgetLevel } from "./widget-accessible-properties.js";
 import { getTypeTag } from "./widget-getters.js";
+import { requireWidget } from "./widget-target.js";
 
 const ROLE_NAMES_BY_VALUE = enumNamesByValue(Gtk.AccessibleRole);
 
@@ -125,6 +126,7 @@ const logRoles = (container: Container): void => {
  *
  * @param widget The widget to read the level from.
  */
-const computeHeadingLevel = (widget: Gtk.Widget): number | undefined => getWidgetLevel(widget) ?? undefined;
+const computeHeadingLevel = (widget: Gtk.Accessible): number | undefined =>
+    getWidgetLevel(requireWidget(widget)) ?? undefined;
 
 export { computeHeadingLevel, formatRole, formatRoleList, getRoles, prettyRoles, logRoles };

package/src/screenshot.ts

@@ -9,6 +9,7 @@ import { getConfig } from "./config.js";
 import { now } from "./timers.js";
 import { descendants } from "./traversal.js";
 import { waitFor } from "./wait-for.js";
+import { requireWidget } from "./widget-target.js";
 import { activeToplevel, mappedToplevels } from "./window-state.js";
 
 type FrameProbe = {
@@ -31,6 +32,20 @@ type CaptureOutcome =
     { status: "captured"; result: ScreenshotResult } |
     { status: "stalled"; failure: CaptureFailure };
 
+type BackgroundSnapshot = {
+    renderBackground(...args: [context: object, x: number, y: number, width: number, height: number]): void;
+};
+
+type StyledWidget = {
+    getStyleContext(): object;
+};
+
+type RenderSize = {
+    scale: number;
+    width: number;
+    height: number;
+};
+
 const DEFAULT_SCREENSHOT_INTERVAL = 10;
 const PRESENTATION_PROBE_MS = 250;
 
@@ -47,9 +62,7 @@ const OTHER_FAILURE_HINT =
 
 const NOTHING_ON_SCREEN_MESSAGE = "Nothing is on screen to capture: no toplevel window is mapped";
 
-const bytesToBase64 = (bytes: Uint8Array | number[]): string => {
-    return Buffer.from(bytes).toString("base64");
-};
+const bytesToBase64 = (bytes: Uint8Array | number[]): string => Buffer.from(bytes).toString("base64");
 
 const describeWidgetState = (widget: Gtk.Widget): string =>
     `realized=${String(widget.getRealized())} mapped=${String(widget.getMapped())} ` +
@@ -181,16 +194,43 @@ const getChildrenNode = (widget: Gtk.Widget, scale: number): Gsk.RenderNode | nu
     return snapshot.toNode();
 };
 
+const addWindowBackground = (
+    widget: Gtk.Widget,
+    node: Gsk.RenderNode,
+    { scale, width, height }: RenderSize,
+): Gsk.RenderNode => {
+    if (!(widget instanceof Gtk.Window)) {
+        return node;
+    }
+
+    const snapshot = new Gtk.Snapshot();
+    const backgroundSnapshot: BackgroundSnapshot = snapshot;
+    const styledWidget: StyledWidget = widget;
+    snapshot.save();
+    snapshot.scale(scale, scale);
+    backgroundSnapshot.renderBackground(styledWidget.getStyleContext(), 0, 0, width, height);
+    snapshot.restore();
+    snapshot.appendNode(node);
+
+    return snapshot.toNode() ?? node;
+};
+
+const getFallbackNode = (widget: Gtk.Widget, size: RenderSize): Gsk.RenderNode | null => {
+    const content = getChildrenNode(widget, size.scale);
+
+    return content === null ? null : addWindowBackground(widget, content, size);
+};
+
 const getRenderNode = (widget: Gtk.Widget, scale: number, width: number, height: number): Gsk.RenderNode | null => {
-    const presented = getPaintableNode(widget, scale, width, height);
+    const content = getPaintableNode(widget, scale, width, height);
 
-    if (presented) {
-        return presented;
+    if (content) {
+        return content;
     }
 
     allocateRoot(widget);
 
-    return getPaintableNode(widget, scale, width, height) ?? getChildrenNode(widget, scale);
+    return getPaintableNode(widget, scale, width, height) ?? getFallbackNode(widget, { scale, width, height });
 };
 
 const renderToPng = (widget: Gtk.Widget, node: Gsk.RenderNode, width: number, height: number): ScreenshotResult => {
@@ -303,7 +343,8 @@ const captureUntilPaintable = (
  * @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 screenshot = async (target: Gtk.Accessible, options?: ScreenshotOptions): Promise<ScreenshotResult> => {
+    const widget = requireWidget(target);
     const scale = options?.scale ?? 1;
 
     if (!Number.isFinite(scale) || scale <= 0) {

package/src/suggestions.ts

@@ -9,6 +9,7 @@ import {
     getWidgetOwnLabel,
     getWidgetPlaceholderText,
 } from "./widget-accessible-properties.js";
+import { requireWidget } from "./widget-target.js";
 
 /** The query variant a suggestion targets. */
 type Variant = "get" | "getAll" | "query" | "queryAll" | "find" | "findAll";
@@ -75,10 +76,11 @@ const textSuggestion = (queryName: Method, variant: Variant, value: string | nul
  * @returns The best available suggestion, or undefined when no query applies.
  */
 const getSuggestedQuery = (
-    widget: Gtk.Widget,
+    target: Gtk.Accessible,
     variant: Variant = "get",
     method?: Method,
 ): Suggestion | undefined => {
+    const widget = requireWidget(target);
     const builders: Record<Method, () => Suggestion | undefined> = {
         Role: () => roleSuggestion(widget, variant),
         LabelText: () =>