@gtkx/testing 0.21.0 → 1.0.0-rc.2

package/dist/config.d.ts

@@ -1,65 +1,33 @@
 import type { Container } from "./traversal.js";
 /**
- * Configuration options for the testing library.
+ * Global configuration for the testing harness, controlling query behavior,
+ * error formatting, and the timeouts used by async utilities and actionability
+ * checks.
  */
-export type Config = {
-    /**
-     * Whether to show role suggestions in error messages when elements are not found.
-     * @default true
-     */
-    showSuggestions: boolean;
-    /**
-     * Custom error factory for query failures.
-     * Allows customizing how errors are constructed.
-     */
-    getElementError: (message: string, container: Container) => Error;
-    /**
-     * Default timeout in milliseconds for async utilities (waitFor, findBy* queries).
-     * @default 1000
-     */
+type Config = {
+    throwSuggestions: boolean;
+    /** Builds the error thrown when a query fails, given a message and optional container. */
+    getElementError: (message: string, container?: Container) => Error;
+    /** Default timeout in milliseconds for async utilities such as waitFor. */
     asyncUtilTimeout: number;
+    /** Timeout in milliseconds for waiting on a widget to become actionable. */
+    actionabilityTimeout: number;
 };
 /**
- * Returns the current testing library configuration.
- *
- * @returns The current configuration object
- *
- * @example
- * ```tsx
- * import { getConfig } from "@gtkx/testing";
- *
- * const config = getConfig();
- * console.log(config.showSuggestions);
- * ```
+ * Function form of a configuration update: receives the current config and
+ * returns the fields to override.
  */
-export declare const getConfig: () => Readonly<Config>;
+type ConfigFn = (existingConfig: Config) => Partial<Config>;
 /**
- * Configures the testing library behavior.
- *
- * Accepts either a partial configuration object or a function that receives
- * the current configuration and returns updates.
- *
- * @param newConfig - Partial configuration or updater function
- *
- * @example
- * ```tsx
- * import { configure } from "@gtkx/testing";
- *
- * // Disable role suggestions
- * configure({ showSuggestions: false });
- *
- * // Use updater function
- * configure((current) => ({
- *   showSuggestions: !current.showSuggestions,
- * }));
- * ```
+ * Returns the current global testing configuration.
  */
-export declare const configure: (newConfig: Partial<Config> | ((current: Config) => Partial<Config>)) => void;
+declare const getConfig: () => Config;
 /**
- * Resets configuration to defaults.
- * Primarily used for testing.
+ * Merges the given overrides into the global testing configuration.
  *
- * @internal
+ * @param newConfig Either a partial config object or a function that receives
+ * the current config and returns the fields to override.
  */
-export declare const resetConfig: () => void;
+declare const configure: (newConfig: Partial<Config> | ConfigFn) => void;
+export { getConfig, configure, type Config, type ConfigFn };
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG;IACjB;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,KAAK,KAAK,CAAC;IAElE;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC5B,CAAC;AAcF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,QAAO,QAAQ,CAAC,MAAM,CAE3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,SAAS,GAAI,WAAW,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,KAAG,IAG/F,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QAAO,IAE9B,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;GAIG;AACH,KAAK,MAAM,GAAG;IACV,gBAAgB,EAAE,OAAO,CAAC;IAE1B,0FAA0F;IAC1F,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,KAAK,KAAK,CAAC;IAEnE,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,CAAC;IAEzB,4EAA4E;IAC5E,oBAAoB,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF;;;GAGG;AACH,KAAK,QAAQ,GAAG,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAe5D;;GAEG;AACH,QAAA,MAAM,SAAS,QAAO,MAErB,CAAC;AAEF;;;;;GAKG;AACH,QAAA,MAAM,SAAS,GAAI,WAAW,OAAO,CAAC,MAAM,CAAC,GAAG,QAAQ,KAAG,IAG1D,CAAC;AAMF,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAE,CAAC"}

package/dist/config.js

@@ -1,60 +1,31 @@
-const defaultGetElementError = (message, _container) => {
-    return new Error(message);
-};
 const defaultConfig = {
-    showSuggestions: true,
+    throwSuggestions: false,
     getElementError: defaultGetElementError,
     asyncUtilTimeout: 1000,
+    actionabilityTimeout: 500,
 };
-let currentConfig = { ...defaultConfig };
+const currentConfig = { ...defaultConfig };
+function defaultGetElementError(message) {
+    return new GtkxElementError(message);
+}
 /**
- * Returns the current testing library configuration.
- *
- * @returns The current configuration object
- *
- * @example
- * ```tsx
- * import { getConfig } from "@gtkx/testing";
- *
- * const config = getConfig();
- * console.log(config.showSuggestions);
- * ```
+ * Returns the current global testing configuration.
  */
-export const getConfig = () => {
+const getConfig = () => {
     return currentConfig;
 };
 /**
- * Configures the testing library behavior.
- *
- * Accepts either a partial configuration object or a function that receives
- * the current configuration and returns updates.
- *
- * @param newConfig - Partial configuration or updater function
+ * Merges the given overrides into the global testing configuration.
  *
- * @example
- * ```tsx
- * import { configure } from "@gtkx/testing";
- *
- * // Disable role suggestions
- * configure({ showSuggestions: false });
- *
- * // Use updater function
- * configure((current) => ({
- *   showSuggestions: !current.showSuggestions,
- * }));
- * ```
+ * @param newConfig Either a partial config object or a function that receives
+ * the current config and returns the fields to override.
  */
-export const configure = (newConfig) => {
+const configure = (newConfig) => {
     const updates = typeof newConfig === "function" ? newConfig(currentConfig) : newConfig;
-    currentConfig = { ...currentConfig, ...updates };
-};
-/**
- * Resets configuration to defaults.
- * Primarily used for testing.
- *
- * @internal
- */
-export const resetConfig = () => {
-    currentConfig = { ...defaultConfig };
+    Object.assign(currentConfig, updates);
 };
+class GtkxElementError extends Error {
+    name = "GtkxElementError";
+}
+export { getConfig, configure };
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAyBA,MAAM,sBAAsB,GAAG,CAAC,OAAe,EAAE,UAAqB,EAAS,EAAE;IAC7E,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC,CAAC;AAEF,MAAM,aAAa,GAAW;IAC1B,eAAe,EAAE,IAAI;IACrB,eAAe,EAAE,sBAAsB;IACvC,gBAAgB,EAAE,IAAI;CACzB,CAAC;AAEF,IAAI,aAAa,GAAW,EAAE,GAAG,aAAa,EAAE,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAqB,EAAE;IAC5C,OAAO,aAAa,CAAC;AACzB,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,SAAmE,EAAQ,EAAE;IACnG,MAAM,OAAO,GAAG,OAAO,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACvF,aAAa,GAAG,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,EAAE,CAAC;AACrD,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAS,EAAE;IAClC,aAAa,GAAG,EAAE,GAAG,aAAa,EAAE,CAAC;AACzC,CAAC,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AA0BA,MAAM,aAAa,GAAW;IAC1B,gBAAgB,EAAE,KAAK;IACvB,eAAe,EAAE,sBAAsB;IACvC,gBAAgB,EAAE,IAAI;IACtB,oBAAoB,EAAE,GAAG;CAC5B,CAAC;AAEF,MAAM,aAAa,GAAW,EAAE,GAAG,aAAa,EAAE,CAAC;AAEnD,SAAS,sBAAsB,CAAC,OAAe;IAC3C,OAAO,IAAI,gBAAgB,CAAC,OAAO,CAAC,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,SAAS,GAAG,GAAW,EAAE;IAC3B,OAAO,aAAa,CAAC;AACzB,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,SAAS,GAAG,CAAC,SAAqC,EAAQ,EAAE;IAC9D,MAAM,OAAO,GAAG,OAAO,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACvF,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC,CAAC;AAEF,MAAM,gBAAiB,SAAQ,KAAK;IACvB,IAAI,GAAG,kBAAkB,CAAC;CACtC;AAED,OAAO,EAAE,SAAS,EAAE,SAAS,EAA8B,CAAC","sourcesContent":["import type { Container } from \"./traversal.js\";\n\n/**\n * Global configuration for the testing harness, controlling query behavior,\n * error formatting, and the timeouts used by async utilities and actionability\n * checks.\n */\ntype Config = {\n    throwSuggestions: boolean;\n\n    /** Builds the error thrown when a query fails, given a message and optional container. */\n    getElementError: (message: string, container?: Container) => Error;\n\n    /** Default timeout in milliseconds for async utilities such as waitFor. */\n    asyncUtilTimeout: number;\n\n    /** Timeout in milliseconds for waiting on a widget to become actionable. */\n    actionabilityTimeout: number;\n};\n\n/**\n * Function form of a configuration update: receives the current config and\n * returns the fields to override.\n */\ntype ConfigFn = (existingConfig: Config) => Partial<Config>;\n\nconst defaultConfig: Config = {\n    throwSuggestions: false,\n    getElementError: defaultGetElementError,\n    asyncUtilTimeout: 1000,\n    actionabilityTimeout: 500,\n};\n\nconst currentConfig: Config = { ...defaultConfig };\n\nfunction defaultGetElementError(message: string): Error {\n    return new GtkxElementError(message);\n}\n\n/**\n * Returns the current global testing configuration.\n */\nconst getConfig = (): Config => {\n    return currentConfig;\n};\n\n/**\n * Merges the given overrides into the global testing configuration.\n *\n * @param newConfig Either a partial config object or a function that receives\n * the current config and returns the fields to override.\n */\nconst configure = (newConfig: Partial<Config> | ConfigFn): void => {\n    const updates = typeof newConfig === \"function\" ? newConfig(currentConfig) : newConfig;\n    Object.assign(currentConfig, updates);\n};\n\nclass GtkxElementError extends Error {\n    override name = \"GtkxElementError\";\n}\n\nexport { getConfig, configure, type Config, type ConfigFn };\n"]}

package/dist/editable.d.ts

@@ -0,0 +1,8 @@
+import * as Gtk from "@gtkx/gi/gtk";
+type EditableTarget = Gtk.Editable | Gtk.TextView;
+declare const EDITABLE_ROLES: Set<Gtk.AccessibleRole>;
+declare const isEditable: (widget: unknown) => widget is EditableTarget;
+declare const getEditableDelegate: (widget: Gtk.Widget) => Gtk.Widget | null;
+declare const readEditableText: (widget: EditableTarget) => string;
+export { EDITABLE_ROLES, isEditable, getEditableDelegate, readEditableText, type EditableTarget };
+//# sourceMappingURL=editable.d.ts.map

package/dist/editable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editable.d.ts","sourceRoot":"","sources":["../src/editable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,cAAc,CAAC;AAEpC,KAAK,cAAc,GAAG,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;AAElD,QAAA,MAAM,cAAc,EAAE,GAAG,CAAC,GAAG,CAAC,cAAc,CAI1C,CAAC;AAEH,QAAA,MAAM,UAAU,GAAI,QAAQ,OAAO,KAAG,MAAM,IAAI,cACoB,CAAC;AAErE,QAAA,MAAM,mBAAmB,GAAI,QAAQ,GAAG,CAAC,MAAM,KAAG,GAAG,CAAC,MAAM,GAAG,IAM9D,CAAC;AASF,QAAA,MAAM,gBAAgB,GAAI,QAAQ,cAAc,KAAG,MAMlD,CAAC;AAEF,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,KAAK,cAAc,EAAE,CAAC"}

package/dist/editable.js

@@ -0,0 +1,26 @@
+import * as Gtk from "@gtkx/gi/gtk";
+const EDITABLE_ROLES = new Set([
+    Gtk.AccessibleRole.TEXT_BOX,
+    Gtk.AccessibleRole.SEARCH_BOX,
+    Gtk.AccessibleRole.SPIN_BUTTON,
+]);
+const isEditable = (widget) => widget instanceof Gtk.Editable || widget instanceof Gtk.TextView;
+const getEditableDelegate = (widget) => {
+    if (!(widget instanceof Gtk.Editable)) {
+        return null;
+    }
+    return widget.getDelegate();
+};
+const readTextViewBufferText = (widget) => {
+    const buffer = widget.getBuffer();
+    const [start, end] = buffer.getBounds();
+    return buffer.getText(start, end, true);
+};
+const readEditableText = (widget) => {
+    if (widget instanceof Gtk.TextView) {
+        return readTextViewBufferText(widget);
+    }
+    return widget.getText();
+};
+export { EDITABLE_ROLES, isEditable, getEditableDelegate, readEditableText };
+//# sourceMappingURL=editable.js.map

package/dist/editable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editable.js","sourceRoot":"","sources":["../src/editable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,cAAc,CAAC;AAIpC,MAAM,cAAc,GAA4B,IAAI,GAAG,CAAqB;IACxE,GAAG,CAAC,cAAc,CAAC,QAAQ;IAC3B,GAAG,CAAC,cAAc,CAAC,UAAU;IAC7B,GAAG,CAAC,cAAc,CAAC,WAAW;CACjC,CAAC,CAAC;AAEH,MAAM,UAAU,GAAG,CAAC,MAAe,EAA4B,EAAE,CAC7D,MAAM,YAAY,GAAG,CAAC,QAAQ,IAAI,MAAM,YAAY,GAAG,CAAC,QAAQ,CAAC;AAErE,MAAM,mBAAmB,GAAG,CAAC,MAAkB,EAAqB,EAAE;IAClE,IAAI,CAAC,CAAC,MAAM,YAAY,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC;AAChC,CAAC,CAAC;AAEF,MAAM,sBAAsB,GAAG,CAAC,MAAoB,EAAU,EAAE;IAC5D,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;IAClC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;IAExC,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;AAC5C,CAAC,CAAC;AAEF,MAAM,gBAAgB,GAAG,CAAC,MAAsB,EAAU,EAAE;IACxD,IAAI,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjC,OAAO,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,MAAM,CAAC,OAAO,EAAE,CAAC;AAC5B,CAAC,CAAC;AAEF,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,mBAAmB,EAAE,gBAAgB,EAAuB,CAAC","sourcesContent":["import * as Gtk from \"@gtkx/gi/gtk\";\n\ntype EditableTarget = Gtk.Editable | Gtk.TextView;\n\nconst EDITABLE_ROLES: Set<Gtk.AccessibleRole> = new Set<Gtk.AccessibleRole>([\n    Gtk.AccessibleRole.TEXT_BOX,\n    Gtk.AccessibleRole.SEARCH_BOX,\n    Gtk.AccessibleRole.SPIN_BUTTON,\n]);\n\nconst isEditable = (widget: unknown): widget is EditableTarget =>\n    widget instanceof Gtk.Editable || widget instanceof Gtk.TextView;\n\nconst getEditableDelegate = (widget: Gtk.Widget): Gtk.Widget | null => {\n    if (!(widget instanceof Gtk.Editable)) {\n        return null;\n    }\n\n    return widget.getDelegate();\n};\n\nconst readTextViewBufferText = (widget: Gtk.TextView): string => {\n    const buffer = widget.getBuffer();\n    const [start, end] = buffer.getBounds();\n\n    return buffer.getText(start, end, true);\n};\n\nconst readEditableText = (widget: EditableTarget): string => {\n    if (widget instanceof Gtk.TextView) {\n        return readTextViewBufferText(widget);\n    }\n\n    return widget.getText();\n};\n\nexport { EDITABLE_ROLES, isEditable, getEditableDelegate, readEditableText, type EditableTarget };\n"]}

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { Container } from "./traversal.js";
+import type { ByRoleOptions, Matcher } from "./types.js";
+type QueryDescriptor = {
+    queryType: "role";
+    role: Gtk.AccessibleRole;
+    options?: ByRoleOptions | undefined;
+} | {
+    queryType: "text";
+    text: Matcher;
+} | {
+    queryType: "labelText";
+    text: Matcher;
+} | {
+    queryType: "name";
+    name: Matcher;
+} | {
+    queryType: "placeholderText";
+    text: Matcher;
+} | {
+    queryType: "displayValue";
+    value: Matcher;
+};
+declare const runWithExpensiveErrorDiagnosticsDisabled: <T>(callback: () => T) => T;
+declare const notFoundError: (container: Container, descriptor: QueryDescriptor) => Error;
+declare const multipleFoundError: (container: Container, descriptor: QueryDescriptor, matches: Gtk.Widget[]) => Error;
+declare const suggestionError: (suggestion: string, container: Container) => Error;
+declare const timeoutError: (timeout: number, lastError: Error | null) => Error;
+export { runWithExpensiveErrorDiagnosticsDisabled, notFoundError, multipleFoundError, suggestionError, timeoutError, type QueryDescriptor, };
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAe,OAAO,EAAE,MAAM,YAAY,CAAC;AAKtE,KAAK,eAAe,GACd;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,GAAG,CAAC,cAAc,CAAC;IAAC,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAA;CAAE,GACtF;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GACpC;IAAE,SAAS,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GACzC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GACpC;IAAE,SAAS,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC/C;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAkGlD,QAAA,MAAM,wCAAwC,GAAI,CAAC,EAAE,UAAU,MAAM,CAAC,KAAG,CASxE,CAAC;AAYF,QAAA,MAAM,aAAa,GAAI,WAAW,SAAS,EAAE,YAAY,eAAe,KAAG,KAS1E,CAAC;AAWF,QAAA,MAAM,kBAAkB,GAAI,WAAW,SAAS,EAAE,YAAY,eAAe,EAAE,SAAS,GAAG,CAAC,MAAM,EAAE,KAAG,KAetG,CAAC;AAEF,QAAA,MAAM,eAAe,GAAI,YAAY,MAAM,EAAE,WAAW,SAAS,KAAG,KAKnE,CAAC;AAEF,QAAA,MAAM,YAAY,GAAI,SAAS,MAAM,EAAE,WAAW,KAAK,GAAG,IAAI,KAAG,KAKhE,CAAC;AAEF,OAAO,EACH,wCAAwC,EACxC,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,KAAK,eAAe,GACvB,CAAC"}

package/dist/errors.js

@@ -0,0 +1,135 @@
+import { getConfig } from "./config.js";
+import { prettyWidget } from "./pretty-widget.js";
+import { formatRole, prettyRoles } from "./role-helpers.js";
+const roleOptionFormatters = [
+    (o) => (o.name ? `name ${formatTextMatcher(o.name)}` : null),
+    (o) => (o.checked === undefined ? null : `checked=${String(o.checked)}`),
+    (o) => (o.pressed === undefined ? null : `pressed=${String(o.pressed)}`),
+    (o) => (o.selected === undefined ? null : `selected=${String(o.selected)}`),
+    (o) => (o.expanded === undefined ? null : `expanded=${String(o.expanded)}`),
+    (o) => (o.level === undefined ? null : `level=${String(o.level)}`),
+    (o) => (o.busy === undefined ? null : `busy=${String(o.busy)}`),
+    (o) => (o.description ? `description ${formatTextMatcher(o.description)}` : null),
+    (o) => (o.value ? `value ${formatByRoleValue(o.value)}` : null),
+    (o) => (o.hidden === undefined ? null : `hidden=${String(o.hidden)}`),
+];
+const expensiveErrorDiagnostics = { isDisabled: false };
+const formatTextMatcher = (text) => {
+    if (typeof text === "function") {
+        return "custom function";
+    }
+    if (text instanceof RegExp) {
+        return text.toString();
+    }
+    return `'${String(text)}'`;
+};
+const formatByRoleValue = (value) => {
+    const parts = [];
+    if (value.now !== undefined) {
+        parts.push(`now=${String(value.now)}`);
+    }
+    if (value.min !== undefined) {
+        parts.push(`min=${String(value.min)}`);
+    }
+    if (value.max !== undefined) {
+        parts.push(`max=${String(value.max)}`);
+    }
+    if (value.text !== undefined) {
+        parts.push(`text ${formatTextMatcher(value.text)}`);
+    }
+    return parts.join(", ");
+};
+const roleOptionParts = (options) => {
+    const parts = [];
+    for (const formatter of roleOptionFormatters) {
+        const part = formatter(options);
+        if (part !== null) {
+            parts.push(part);
+        }
+    }
+    return parts;
+};
+const formatByRoleDescription = (role, options) => {
+    const parts = [`role '${formatRole(role).toUpperCase()}'`];
+    if (options) {
+        parts.push(...roleOptionParts(options));
+    }
+    return parts.join(" and ");
+};
+const formatQueryDescription = (descriptor) => {
+    switch (descriptor.queryType) {
+        case "role": {
+            return formatByRoleDescription(descriptor.role, descriptor.options);
+        }
+        case "text": {
+            return `text ${formatTextMatcher(descriptor.text)}`;
+        }
+        case "labelText": {
+            return `label text ${formatTextMatcher(descriptor.text)}`;
+        }
+        case "name": {
+            return `name ${formatTextMatcher(descriptor.name)}`;
+        }
+        case "placeholderText": {
+            return `placeholder text ${formatTextMatcher(descriptor.text)}`;
+        }
+        case "displayValue": {
+            return `display value ${formatTextMatcher(descriptor.value)}`;
+        }
+    }
+};
+const runWithExpensiveErrorDiagnosticsDisabled = (callback) => {
+    const isPrevious = expensiveErrorDiagnostics.isDisabled;
+    expensiveErrorDiagnostics.isDisabled = true;
+    try {
+        return callback();
+    }
+    finally {
+        expensiveErrorDiagnostics.isDisabled = isPrevious;
+    }
+};
+const buildElementError = (container, headLines) => {
+    const config = getConfig();
+    const lines = expensiveErrorDiagnostics.isDisabled
+        ? headLines
+        : [...headLines, "", prettyWidget(container, { highlight: false })];
+    return config.getElementError(lines.join("\n"), container);
+};
+const notFoundError = (container, descriptor) => {
+    const description = formatQueryDescription(descriptor);
+    const headLines = [`Unable to find an element with ${description}`];
+    if (!expensiveErrorDiagnostics.isDisabled && descriptor.queryType === "role") {
+        headLines.push("", "Here are the accessible roles:", "", prettyRoles(container));
+    }
+    return buildElementError(container, headLines);
+};
+const allByVariantHint = (descriptor) => {
+    const variant = descriptor.queryType === "role" ? "getAllByRole" : "getAllBy*";
+    return ("(If this is intentional, use the *AllBy* variant of the query, " +
+        `e.g. queryAllBy*/getAllBy*/findAllBy*, such as ${variant}.)`);
+};
+const multipleFoundError = (container, descriptor, matches) => {
+    const description = formatQueryDescription(descriptor);
+    const headLines = [
+        `Found ${String(matches.length)} elements with ${description}, but expected only one`,
+        "",
+        allByVariantHint(descriptor),
+    ];
+    if (!expensiveErrorDiagnostics.isDisabled) {
+        const renderedMatches = matches.map((widget) => prettyWidget(widget, { highlight: false }));
+        headLines.push("", "Here are the matching elements:", "", ...renderedMatches);
+    }
+    return buildElementError(container, headLines);
+};
+const suggestionError = (suggestion, container) => {
+    const config = getConfig();
+    const message = `A better query is available, try this:\n${suggestion}\n`;
+    return config.getElementError(message, container);
+};
+const timeoutError = (timeout, lastError) => {
+    const baseMessage = `Timed out after ${String(timeout)}ms`;
+    const message = lastError ? `${baseMessage}.\n\n${lastError.message}` : baseMessage;
+    return getConfig().getElementError(message);
+};
+export { runWithExpensiveErrorDiagnosticsDisabled, notFoundError, multipleFoundError, suggestionError, timeoutError, };
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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","sourcesContent":["import type * as Gtk from \"@gtkx/gi/gtk\";\nimport type { Container } from \"./traversal.js\";\nimport type { ByRoleOptions, ByRoleValue, Matcher } from \"./types.js\";\nimport { getConfig } from \"./config.js\";\nimport { prettyWidget } from \"./pretty-widget.js\";\nimport { formatRole, prettyRoles } from \"./role-helpers.js\";\n\ntype QueryDescriptor =\n    | { queryType: \"role\"; role: Gtk.AccessibleRole; options?: ByRoleOptions | undefined } |\n    { queryType: \"text\"; text: Matcher } |\n    { queryType: \"labelText\"; text: Matcher } |\n    { queryType: \"name\"; name: Matcher } |\n    { queryType: \"placeholderText\"; text: Matcher } |\n    { queryType: \"displayValue\"; value: Matcher };\n\nconst roleOptionFormatters: ((options: ByRoleOptions) => string | null)[] = [\n    (o) => (o.name ? `name ${formatTextMatcher(o.name)}` : null),\n    (o) => (o.checked === undefined ? null : `checked=${String(o.checked)}`),\n    (o) => (o.pressed === undefined ? null : `pressed=${String(o.pressed)}`),\n    (o) => (o.selected === undefined ? null : `selected=${String(o.selected)}`),\n    (o) => (o.expanded === undefined ? null : `expanded=${String(o.expanded)}`),\n    (o) => (o.level === undefined ? null : `level=${String(o.level)}`),\n    (o) => (o.busy === undefined ? null : `busy=${String(o.busy)}`),\n    (o) => (o.description ? `description ${formatTextMatcher(o.description)}` : null),\n    (o) => (o.value ? `value ${formatByRoleValue(o.value)}` : null),\n    (o) => (o.hidden === undefined ? null : `hidden=${String(o.hidden)}`),\n];\n\nconst expensiveErrorDiagnostics = { isDisabled: false };\n\nconst formatTextMatcher = (text: Matcher): string => {\n    if (typeof text === \"function\") {\n        return \"custom function\";\n    }\n\n    if (text instanceof RegExp) {\n        return text.toString();\n    }\n\n    return `'${String(text)}'`;\n};\n\nconst formatByRoleValue = (value: ByRoleValue): string => {\n    const parts: string[] = [];\n\n    if (value.now !== undefined) {\n        parts.push(`now=${String(value.now)}`);\n    }\n\n    if (value.min !== undefined) {\n        parts.push(`min=${String(value.min)}`);\n    }\n\n    if (value.max !== undefined) {\n        parts.push(`max=${String(value.max)}`);\n    }\n\n    if (value.text !== undefined) {\n        parts.push(`text ${formatTextMatcher(value.text)}`);\n    }\n\n    return parts.join(\", \");\n};\n\nconst roleOptionParts = (options: ByRoleOptions): string[] => {\n    const parts: string[] = [];\n\n    for (const formatter of roleOptionFormatters) {\n        const part = formatter(options);\n\n        if (part !== null) {\n            parts.push(part);\n        }\n    }\n\n    return parts;\n};\n\nconst formatByRoleDescription = (role: Gtk.AccessibleRole, options?: ByRoleOptions): string => {\n    const parts = [`role '${formatRole(role).toUpperCase()}'`];\n\n    if (options) {\n        parts.push(...roleOptionParts(options));\n    }\n\n    return parts.join(\" and \");\n};\n\nconst formatQueryDescription = (descriptor: QueryDescriptor): string => {\n    switch (descriptor.queryType) {\n        case \"role\": {\n            return formatByRoleDescription(descriptor.role, descriptor.options);\n        }\n        case \"text\": {\n            return `text ${formatTextMatcher(descriptor.text)}`;\n        }\n        case \"labelText\": {\n            return `label text ${formatTextMatcher(descriptor.text)}`;\n        }\n        case \"name\": {\n            return `name ${formatTextMatcher(descriptor.name)}`;\n        }\n        case \"placeholderText\": {\n            return `placeholder text ${formatTextMatcher(descriptor.text)}`;\n        }\n        case \"displayValue\": {\n            return `display value ${formatTextMatcher(descriptor.value)}`;\n        }\n    }\n};\n\nconst runWithExpensiveErrorDiagnosticsDisabled = <T>(callback: () => T): T => {\n    const isPrevious = expensiveErrorDiagnostics.isDisabled;\n    expensiveErrorDiagnostics.isDisabled = true;\n\n    try {\n        return callback();\n    } finally {\n        expensiveErrorDiagnostics.isDisabled = isPrevious;\n    }\n};\n\nconst buildElementError = (container: Container, headLines: string[]): Error => {\n    const config = getConfig();\n\n    const lines = expensiveErrorDiagnostics.isDisabled\n        ? headLines\n        : [...headLines, \"\", prettyWidget(container, { highlight: false })];\n\n    return config.getElementError(lines.join(\"\\n\"), container);\n};\n\nconst notFoundError = (container: Container, descriptor: QueryDescriptor): Error => {\n    const description = formatQueryDescription(descriptor);\n    const headLines = [`Unable to find an element with ${description}`];\n\n    if (!expensiveErrorDiagnostics.isDisabled && descriptor.queryType === \"role\") {\n        headLines.push(\"\", \"Here are the accessible roles:\", \"\", prettyRoles(container));\n    }\n\n    return buildElementError(container, headLines);\n};\n\nconst allByVariantHint = (descriptor: QueryDescriptor): string => {\n    const variant = descriptor.queryType === \"role\" ? \"getAllByRole\" : \"getAllBy*\";\n\n    return (\n        \"(If this is intentional, use the *AllBy* variant of the query, \" +\n        `e.g. queryAllBy*/getAllBy*/findAllBy*, such as ${variant}.)`\n    );\n};\n\nconst multipleFoundError = (container: Container, descriptor: QueryDescriptor, matches: Gtk.Widget[]): Error => {\n    const description = formatQueryDescription(descriptor);\n\n    const headLines = [\n        `Found ${String(matches.length)} elements with ${description}, but expected only one`,\n        \"\",\n        allByVariantHint(descriptor),\n    ];\n\n    if (!expensiveErrorDiagnostics.isDisabled) {\n        const renderedMatches = matches.map((widget) => prettyWidget(widget, { highlight: false }));\n        headLines.push(\"\", \"Here are the matching elements:\", \"\", ...renderedMatches);\n    }\n\n    return buildElementError(container, headLines);\n};\n\nconst suggestionError = (suggestion: string, container: Container): Error => {\n    const config = getConfig();\n    const message = `A better query is available, try this:\\n${suggestion}\\n`;\n\n    return config.getElementError(message, container);\n};\n\nconst timeoutError = (timeout: number, lastError: Error | null): Error => {\n    const baseMessage = `Timed out after ${String(timeout)}ms`;\n    const message = lastError ? `${baseMessage}.\\n\\n${lastError.message}` : baseMessage;\n\n    return getConfig().getElementError(message);\n};\n\nexport {\n    runWithExpensiveErrorDiagnosticsDisabled,\n    notFoundError,\n    multipleFoundError,\n    suggestionError,\n    timeoutError,\n    type QueryDescriptor,\n};\n"]}

package/dist/fire-event.d.ts

@@ -1,29 +1,12 @@
-import { Value } from "@gtkx/ffi/gobject";
-import type * as Gtk from "@gtkx/ffi/gtk";
+import type * as GObject from "@gtkx/gi/gobject";
 /**
- * Emits a GTK signal on a widget or event controller.
+ * Emits a GObject signal on a widget or object inside React's act environment,
+ * so any resulting state updates are flushed before the promise resolves.
  *
- * Low-level utility for triggering signals directly. Prefer {@link userEvent}
- * for common interactions like clicking and typing.
- *
- * @param element - The widget or event controller to emit the signal on
- * @param signalName - GTK signal name (e.g., "clicked", "activate", "drag-begin")
- * @param args - Additional signal arguments as GValues
- *
- * @example
- * ```tsx
- * import { fireEvent } from "@gtkx/testing";
- * import { Value } from "@gtkx/ffi/gobject";
- *
- * // Emit signal on widget
- * await fireEvent(widget, "clicked");
- *
- * // Emit signal on gesture controller
- * const gesture = widget.observeControllers().getObject(0) as Gtk.GestureDrag;
- * await fireEvent(gesture, "drag-begin", Value.newFromDouble(100), Value.newFromDouble(100));
- * ```
- *
- * @see {@link userEvent} for high-level user interactions
+ * @param element The GObject instance to emit the signal on.
+ * @param signalName Name of the signal to emit.
+ * @param args Arguments passed to the signal handlers.
  */
-export declare const fireEvent: (element: Gtk.Widget | Gtk.EventController, signalName: string, ...args: Value[]) => Promise<void>;
+declare const fireEvent: (element: GObject.Object, signalName: string, ...args: unknown[]) => Promise<void>;
+export { fireEvent };
 //# sourceMappingURL=fire-event.d.ts.map

package/dist/fire-event.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fire-event.d.ts","sourceRoot":"","sources":["../src/fire-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC3G,OAAO,KAAK,KAAK,GAAG,MAAM,eAAe,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,SAAS,GAClB,SAAS,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,eAAe,EACzC,YAAY,MAAM,EAClB,GAAG,MAAM,KAAK,EAAE,KACjB,OAAO,CAAC,IAAI,CASd,CAAC"}
+{"version":3,"file":"fire-event.d.ts","sourceRoot":"","sources":["../src/fire-event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,OAAO,MAAM,kBAAkB,CAAC;AAGjD;;;;;;;GAOG;AACH,QAAA,MAAM,SAAS,GAAU,SAAS,OAAO,CAAC,MAAM,EAAE,YAAY,MAAM,EAAE,GAAG,MAAM,OAAO,EAAE,KAAG,OAAO,CAAC,IAAI,CAItG,CAAC;AAEF,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/fire-event.js

@@ -1,35 +1,16 @@
-import { signalEmitv, signalLookup, typeFromName, Value } from "@gtkx/ffi/gobject";
-import { tick } from "./timing.js";
+import { runInAct } from "./act.js";
 /**
- * Emits a GTK signal on a widget or event controller.
+ * Emits a GObject signal on a widget or object inside React's act environment,
+ * so any resulting state updates are flushed before the promise resolves.
  *
- * Low-level utility for triggering signals directly. Prefer {@link userEvent}
- * for common interactions like clicking and typing.
- *
- * @param element - The widget or event controller to emit the signal on
- * @param signalName - GTK signal name (e.g., "clicked", "activate", "drag-begin")
- * @param args - Additional signal arguments as GValues
- *
- * @example
- * ```tsx
- * import { fireEvent } from "@gtkx/testing";
- * import { Value } from "@gtkx/ffi/gobject";
- *
- * // Emit signal on widget
- * await fireEvent(widget, "clicked");
- *
- * // Emit signal on gesture controller
- * const gesture = widget.observeControllers().getObject(0) as Gtk.GestureDrag;
- * await fireEvent(gesture, "drag-begin", Value.newFromDouble(100), Value.newFromDouble(100));
- * ```
- *
- * @see {@link userEvent} for high-level user interactions
+ * @param element The GObject instance to emit the signal on.
+ * @param signalName Name of the signal to emit.
+ * @param args Arguments passed to the signal handlers.
  */
-export const fireEvent = async (element, signalName, ...args) => {
-    const gtype = typeFromName(element.constructor.glibTypeName);
-    const signalId = signalLookup(signalName, gtype);
-    const instanceValue = Value.newFromObject(element);
-    signalEmitv([instanceValue, ...args], signalId, 0);
-    await tick();
+const fireEvent = async (element, signalName, ...args) => {
+    await runInAct(() => {
+        element.emit(signalName, ...args);
+    });
 };
+export { fireEvent };
 //# sourceMappingURL=fire-event.js.map

package/dist/fire-event.js.map

@@ -1 +1 @@
-{"version":3,"file":"fire-event.js","sourceRoot":"","sources":["../src/fire-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE3G,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,EAC1B,OAAyC,EACzC,UAAkB,EAClB,GAAG,IAAa,EACH,EAAE;IACf,MAAM,KAAK,GAAG,YAAY,CAAE,OAAO,CAAC,WAA8B,CAAC,YAAY,CAAC,CAAC;IACjF,MAAM,QAAQ,GAAG,YAAY,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAEjD,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC,OAAkB,CAAC,CAAC;IAE9D,WAAW,CAAC,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IAEnD,MAAM,IAAI,EAAE,CAAC;AACjB,CAAC,CAAC"}
+{"version":3,"file":"fire-event.js","sourceRoot":"","sources":["../src/fire-event.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEpC;;;;;;;GAOG;AACH,MAAM,SAAS,GAAG,KAAK,EAAE,OAAuB,EAAE,UAAkB,EAAE,GAAG,IAAe,EAAiB,EAAE;IACvG,MAAM,QAAQ,CAAC,GAAG,EAAE;QAChB,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACP,CAAC,CAAC;AAEF,OAAO,EAAE,SAAS,EAAE,CAAC","sourcesContent":["import type * as GObject from \"@gtkx/gi/gobject\";\nimport { runInAct } from \"./act.js\";\n\n/**\n * Emits a GObject signal on a widget or object inside React's act environment,\n * so any resulting state updates are flushed before the promise resolves.\n *\n * @param element The GObject instance to emit the signal on.\n * @param signalName Name of the signal to emit.\n * @param args Arguments passed to the signal handlers.\n */\nconst fireEvent = async (element: GObject.Object, signalName: string, ...args: unknown[]): Promise<void> => {\n    await runInAct(() => {\n        element.emit(signalName, ...args);\n    });\n};\n\nexport { fireEvent };\n"]}

package/dist/frame-sync.d.ts

@@ -0,0 +1,4 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+declare const scheduleAfterLayout: (widget: Gtk.Widget | null, callback: () => void) => void;
+export { scheduleAfterLayout };
+//# sourceMappingURL=frame-sync.d.ts.map

package/dist/frame-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-sync.d.ts","sourceRoot":"","sources":["../src/frame-sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,cAAc,CAAC;AAsCzC,QAAA,MAAM,mBAAmB,GAAI,QAAQ,GAAG,CAAC,MAAM,GAAG,IAAI,EAAE,UAAU,MAAM,IAAI,KAAG,IAU9E,CAAC;AAEF,OAAO,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/frame-sync.js

@@ -0,0 +1,37 @@
+import * as GLib from "@gtkx/gi/glib";
+const CLOCK_STALL_FALLBACK_MS = 500;
+const once = (callback) => {
+    let isCalled = false;
+    return () => {
+        if (isCalled) {
+            return;
+        }
+        isCalled = true;
+        callback();
+    };
+};
+const runWhenSized = (widget, finish) => {
+    let tickId = 0;
+    const fallback = setTimeout(() => {
+        widget.removeTickCallback(tickId);
+        finish();
+    }, CLOCK_STALL_FALLBACK_MS);
+    tickId = widget.addTickCallback(() => {
+        if (widget.getWidth() === 0) {
+            return GLib.SOURCE_CONTINUE;
+        }
+        clearTimeout(fallback);
+        finish();
+        return GLib.SOURCE_REMOVE;
+    });
+};
+const scheduleAfterLayout = (widget, callback) => {
+    const finish = once(callback);
+    if (widget?.getFrameClock() == null || widget.getWidth() > 0) {
+        queueMicrotask(finish);
+        return;
+    }
+    runWhenSized(widget, finish);
+};
+export { scheduleAfterLayout };
+//# sourceMappingURL=frame-sync.js.map

package/dist/frame-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-sync.js","sourceRoot":"","sources":["../src/frame-sync.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAEtC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAEpC,MAAM,IAAI,GAAG,CAAC,QAAoB,EAAgB,EAAE;IAChD,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,OAAO,GAAG,EAAE;QACR,IAAI,QAAQ,EAAE,CAAC;YACX,OAAO;QACX,CAAC;QAED,QAAQ,GAAG,IAAI,CAAC;QAChB,QAAQ,EAAE,CAAC;IACf,CAAC,CAAC;AACN,CAAC,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,MAAkB,EAAE,MAAkB,EAAQ,EAAE;IAClE,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,EAAE;QAC7B,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,EAAE,CAAC;IACb,CAAC,EAAE,uBAAuB,CAAC,CAAC;IAE5B,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE;QACjC,IAAI,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC,eAAe,CAAC;QAChC,CAAC;QAED,YAAY,CAAC,QAAQ,CAAC,CAAC;QACvB,MAAM,EAAE,CAAC;QAET,OAAO,IAAI,CAAC,aAAa,CAAC;IAC9B,CAAC,CAAC,CAAC;AACP,CAAC,CAAC;AAEF,MAAM,mBAAmB,GAAG,CAAC,MAAyB,EAAE,QAAoB,EAAQ,EAAE;IAClF,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;IAE9B,IAAI,MAAM,EAAE,aAAa,EAAE,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC;QAC3D,cAAc,CAAC,MAAM,CAAC,CAAC;QAEvB,OAAO;IACX,CAAC;IAED,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACjC,CAAC,CAAC;AAEF,OAAO,EAAE,mBAAmB,EAAE,CAAC","sourcesContent":["import type * as Gtk from \"@gtkx/gi/gtk\";\nimport * as GLib from \"@gtkx/gi/glib\";\n\nconst CLOCK_STALL_FALLBACK_MS = 500;\n\nconst once = (callback: () => void): (() => void) => {\n    let isCalled = false;\n\n    return () => {\n        if (isCalled) {\n            return;\n        }\n\n        isCalled = true;\n        callback();\n    };\n};\n\nconst runWhenSized = (widget: Gtk.Widget, finish: () => void): void => {\n    let tickId = 0;\n\n    const fallback = setTimeout(() => {\n        widget.removeTickCallback(tickId);\n        finish();\n    }, CLOCK_STALL_FALLBACK_MS);\n\n    tickId = widget.addTickCallback(() => {\n        if (widget.getWidth() === 0) {\n            return GLib.SOURCE_CONTINUE;\n        }\n\n        clearTimeout(fallback);\n        finish();\n\n        return GLib.SOURCE_REMOVE;\n    });\n};\n\nconst scheduleAfterLayout = (widget: Gtk.Widget | null, callback: () => void): void => {\n    const finish = once(callback);\n\n    if (widget?.getFrameClock() == null || widget.getWidth() > 0) {\n        queueMicrotask(finish);\n\n        return;\n    }\n\n    runWhenSized(widget, finish);\n};\n\nexport { scheduleAfterLayout };\n"]}

package/dist/index.d.ts

@@ -1,21 +1,26 @@
-export type { Config } from "./config.js";
+import "./register-test-hooks.js";
+export { act } from "./act.js";
+export type { BoundQueries, RenderResult, Screen } from "./bound-queries.js";
+export type { Config, ConfigFn } from "./config.js";
 export { configure, getConfig } from "./config.js";
 export { fireEvent } from "./fire-event.js";
+export type { TextExpectation } from "./matchers.js";
+export { matchers, registerMatchers } from "./matchers.js";
 export type { PrettyWidgetOptions } from "./pretty-widget.js";
-export { prettyWidget } from "./pretty-widget.js";
-export { findAllByLabelText, findAllByName, findAllByRole, findAllByText, findByLabelText, findByName, findByRole, findByText, queryAllByLabelText, queryAllByName, queryAllByRole, queryAllByText, queryByLabelText, queryByName, queryByRole, queryByText, } from "./queries.js";
-export { cleanup, render } from "./render.js";
+export { logWidget, prettyWidget } from "./pretty-widget.js";
+export { findAllByDisplayValue, findAllByLabelText, findAllByName, findAllByPlaceholderText, findAllByRole, findAllByText, findByDisplayValue, findByLabelText, findByName, findByPlaceholderText, findByRole, findByText, getAllByDisplayValue, getAllByLabelText, getAllByName, getAllByPlaceholderText, getAllByRole, getAllByText, getByDisplayValue, getByLabelText, getByName, getByPlaceholderText, getByRole, getByText, getDefaultNormalizer, queryAllByDisplayValue, queryAllByLabelText, queryAllByName, queryAllByPlaceholderText, queryAllByRole, queryAllByText, queryByDisplayValue, queryByLabelText, queryByName, queryByPlaceholderText, queryByRole, queryByText, } from "./queries.js";
 export { renderHook } from "./render-hook.js";
-export type { RoleInfo } from "./role-helpers.js";
-export { getRoles, logRoles, prettyRoles } from "./role-helpers.js";
+export { cleanup, render } from "./render.js";
+export { formatRole, getRoles, logRoles, prettyRoles } from "./role-helpers.js";
 export { screen } from "./screen.js";
-export type { ScreenshotOptions } from "./screenshot.js";
-export { screenshot } from "./screenshot.js";
-export { tick } from "./timing.js";
+export { captureAndSaveScreenshot, logScreenshotPath, screenshot } from "./screenshot.js";
+export type { Method, Suggestion, Variant } from "./suggestions.js";
+export { getSuggestedQuery } from "./suggestions.js";
 export type { Container } from "./traversal.js";
-export type { BoundQueries, ByRoleOptions, NormalizerOptions, RenderHookOptions, RenderHookResult, RenderOptions, RenderResult, ScreenshotResult, TextMatch, TextMatchFunction, TextMatchOptions, WaitForOptions, WrapperComponent, } from "./types.js";
-export type { PointerInput, TabOptions } from "./user-event.js";
-export { userEvent } from "./user-event.js";
+export type { ByRoleOptions, ByRoleValue, Matcher, MatcherFunction, MatcherOptions, NormalizerFn, NormalizerOptions, RenderHookOptions, RenderHookResult, RenderOptions, ScreenshotOptions, ScreenshotResult, WaitForOptions, WindowSelector, WrapperComponent, } from "./types.js";
+export type { DragOffset, DragOptions, DropContent, DropOptions, PointerInput, ScrollDelta, TabOptions, TypeOptions, UserEvent, } from "./user-event/index.js";
+export { userEvent } from "./user-event/index.js";
 export { waitFor, waitForElementToBeRemoved } from "./wait-for.js";
+export { getWidgetErrorMessage, getWidgetInvalidState, getWidgetNodeText, } from "./widget-accessible-properties.js";
 export { within } from "./within.js";
 //# sourceMappingURL=index.d.ts.map