@gtkx/testing 0.20.0 → 1.0.0-rc.1

package/README.md

@@ -1,106 +1,173 @@
 <p align="center">
- <img src="https://raw.githubusercontent.com/eugeniodepalo/gtkx/main/logo.svg" alt="GTKX" width="60" height="60">
+  <img src="https://raw.githubusercontent.com/gtkx-org/gtkx/main/logo.svg" alt="GTKX" width="100" />
 </p>
 
 <h1 align="center">GTKX</h1>
 
 <p align="center">
- <strong>Build native GTK4 desktop applications with React and TypeScript.</strong>
+  The React framework for Linux.<br />
+  Build GTK4 and Adwaita apps in TypeScript, with React components and hooks driving GNOME's own widgets. What you ship is a GNOME app.
 </p>
 
 <p align="center">
- <a href="https://www.npmjs.com/package/@gtkx/react"><img src="https://img.shields.io/npm/v/@gtkx/react.svg" alt="npm version"></a>
- <a href="https://github.com/gtkx-org/gtkx/actions"><img src="https://img.shields.io/github/actions/workflow/status/eugeniodepalo/gtkx/ci.yml" alt="CI"></a>
- <a href="https://github.com/gtkx-org/gtkx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MPL--2.0-blue.svg" alt="License"></a>
- <a href="https://github.com/gtkx-org/gtkx/discussions"><img src="https://img.shields.io/badge/discussions-GitHub-blue" alt="GitHub Discussions"></a>
+  <a href="https://www.npmjs.com/package/create-gtkx"><img src="https://img.shields.io/npm/v/create-gtkx?color=cb3837&logo=npm&label=create-gtkx" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/create-gtkx"><img src="https://img.shields.io/npm/dm/create-gtkx?color=cb3837&logo=npm&label=downloads" alt="npm downloads" /></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A524-339933?logo=node.js&logoColor=white" alt="Node >= 24" />
+  <a href="https://github.com/gtkx-org/gtkx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MPL--2.0-blue.svg" alt="License: MPL-2.0" /></a>
+  <a href="https://github.com/gtkx-org/gtkx/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/gtkx-org/gtkx/ci.yml?branch=main&logo=github&label=CI" alt="CI status" /></a>
+  <img src="https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white" alt="TypeScript" />
+</p>
+
+<p align="center">
+  <a href="https://gtkx.dev">Homepage</a> &middot;
+  <a href="https://gtkx.dev/guide/why-gtkx">Documentation</a> &middot;
+  <a href="https://github.com/gtkx-org/gtkx/tree/main/examples">Examples</a> &middot;
+  <a href="https://github.com/gtkx-org/gtkx/blob/main/CONTRIBUTING.md">Contributing</a>
 </p>
 
 ---
 
-GTKX lets you write Linux desktop applications using React. Your components render as native GTK4 widgets through a Rust FFI bridge—no webviews, no Electron, just native performance with the developer experience you already know.
+GTKX generates fully typed bindings for the entire GTK4 and Adwaita surface directly from GObject-Introspection. On top of those bindings you get the React programming model: components and hooks driving GObject instances, with Fast Refresh while you develop.
 
-## Quick Start
+<p align="center">
+  <img src="https://raw.githubusercontent.com/gtkx-org/gtkx/main/examples/tutorial/assets/screenshot.png" alt="The Tasks app: an Adwaita window with a sidebar of smart views and colored lists on the left, and a boxed task list on the right." />
+</p>
 
-```bash
-npx @gtkx/cli create my-app
-cd my-app
-npm run dev
-```
+<p align="center">
+  <em>The Tasks app you build in the <a href="https://gtkx.dev/tutorial/">tutorial</a>.</em>
+</p>
+
+## Demo
 
-## Example
+The intrinsic elements in this snippet render GTK4 widgets, and ordinary React hooks and events drive them:
 
 ```tsx
-import {
-  GtkApplicationWindow,
-  GtkBox,
-  GtkButton,
-  GtkLabel,
-  quit,
-  render,
-} from "@gtkx/react";
-import * as Gtk from "@gtkx/ffi/gtk";
+import * as Gtk from "@gtkx/gi/gtk";
+import { GtkApplication, GtkApplicationWindow, GtkBox, GtkButton, GtkLabel } from "@gtkx/jsx/gtk";
+import { createRoot, quit } from "@gtkx/react";
 import { useState } from "react";
 
-const App = () => {
+const Counter = () => {
   const [count, setCount] = useState(0);
 
   return (
     <GtkApplicationWindow
-      title="Counter"
-      defaultWidth={300}
-      defaultHeight={200}
-      onClose={quit}
+      title="Hello GTKX"
+      defaultWidth={400}
+      defaultHeight={300}
+      onCloseRequest={quit}
     >
       <GtkBox
         orientation={Gtk.Orientation.VERTICAL}
         spacing={20}
+        marginTop={40}
+        marginBottom={40}
+        marginStart={40}
+        marginEnd={40}
         valign={Gtk.Align.CENTER}
+        halign={Gtk.Align.CENTER}
       >
-        <GtkLabel label={`Count: ${count}`} cssClasses={["title-1"]} />
-        <GtkButton label="Increment" onClicked={() => setCount((c) => c + 1)} />
+        <GtkLabel cssClasses={["title-1"]}>Welcome to GTKX!</GtkLabel>
+        <GtkLabel cssClasses={["title-2"]}>{`Count: ${count}`}</GtkLabel>
+        <GtkButton
+          label="Increment"
+          onClicked={() => setCount((c) => c + 1)}
+          cssClasses={["suggested-action", "pill"]}
+        />
       </GtkBox>
     </GtkApplicationWindow>
   );
 };
 
-render(<App />, "com.example.counter");
+const App = () => (
+  <GtkApplication>
+    <Counter />
+  </GtkApplication>
+);
+
+createRoot().render(<App />);
 ```
 
-## Features
+This is the [`hello-world`](https://github.com/gtkx-org/gtkx/tree/main/examples/hello-world) example, with `app.tsx` and `index.tsx` combined into a single snippet. `@gtkx/gi` and `@gtkx/jsx` are per-project bindings generated by the CLI, not packages you install from npm.
 
-- **React 19** — Hooks, concurrent features, and the component model you know
-- **Native GTK4 widgets** — Real native controls, not web components in a webview
-- **Adwaita support** — Modern GNOME styling with Libadwaita components
-- **Declarative animations** — Framer Motion-like API using native Adwaita animations
-- **Hot Module Replacement** — Fast refresh during development
-- **TypeScript first** — Full type safety with auto-generated bindings
-- **CSS-in-JS styling** — Familiar styling patterns adapted for GTK
-- **Testing utilities** — Component testing similar to Testing Library
+## Why GTKX
 
-## Examples
+### A declarative layer for the GNOME stack
+
+GTK4 is mature, and GtkBuilder XML can lay out a static interface, but nothing re-renders that interface when your application state changes, and nothing hot-reloads it as you work. GTKX adds that missing layer, and the tooling around it, on top of the stack you already know:
+
+- a React reconciler that exposes every GObject as a JSX element,
+- a CLI for scaffolding, development, and production builds,
+- a dev server with Fast Refresh that patches your running UI in place,
+- CSS-in-JS styling and high-level list, grid, and dialog components,
+- a Testing Library-style API for querying and driving your widgets in tests,
+- and a Model Context Protocol (MCP) server that exposes your live app to AI agents.
+
+### The full GNOME API surface
+
+React Native and similar frameworks hide the native toolkit so one API can run everywhere. GTKX exposes it: GTK4, Adwaita, and any other GObject-Introspection library on your system. Linux-only by design.
+
+### Why Node.js, and why generated bindings
+
+GTKX runs on Node.js, which puts native modules, the npm ecosystem, and the tooling built for Node.js APIs within reach. GJS is GNOME's own runtime, built on SpiderMonkey rather than V8; node-gtk runs on Node.js but is lightly maintained, on the older nan/V8 ABI rather than N-API, and still centered on GTK3. The [why-gtkx guide](https://gtkx.dev/guide/why-gtkx) covers the comparison in full.
+
+GTKX generates the TypeScript types and the native FFI calls from the same GObject-Introspection data, so the types cannot drift from the calls they back. Codegen covers the whole GTK4 and Adwaita surface.
+
+At runtime, the native Rust core calls straight into the system GTK4, Adwaita, and GLib libraries through libffi, without loading libgirepository at all.
 
-Explore complete applications in the [`examples/`](./examples) directory:
+## Quick start
 
-- **[gtk-demo](./examples/gtk-demo)** — Full replica of the official GTK demo app
-- **[hello-world](./examples/hello-world)** — Minimal application showing a counter
-- **[todo](./examples/todo)** — Full-featured todo application with Adwaita styling and testing
-- **[x-showcase](./examples/x-showcase)** — Showcase of all x.\* virtual components
-- **[browser](./examples/browser)** — Simple browser using WebKitWebView
-- **[deploying](./examples/deploying)** — Example of packaging and distributing a GTKX app
+GTKX is Linux-only and needs Node.js 24 or later. See [Requirements](#requirements).
+
+Scaffold a new app with the `create-gtkx` initializer:
+
+```sh
+npm create gtkx@rc
+```
+
+The same command works with other package managers: `pnpm create gtkx@rc` or `yarn create gtkx@rc`.
+
+Then run your new app:
+
+```sh
+cd my-app
+npm run dev
+```
+
+To go further, follow the [tutorial](https://gtkx.dev/tutorial/).
 
 ## Documentation
 
-Visit [https://gtkx.dev](https://gtkx.dev) for the full documentation.
+The documentation at **[gtkx.dev](https://gtkx.dev)** includes a step-by-step tutorial that builds a complete GNOME app, from scaffolding to packaging and shipping, plus guides and a full API reference.
 
-## Contributing
+**[Read the docs &rarr;](https://gtkx.dev/guide/why-gtkx)**
 
-Contributions are welcome! Please see the [contributing guidelines](./CONTRIBUTING.md) and check out the [good first issues](https://github.com/gtkx-org/gtkx/labels/good%20first%20issue).
+## Requirements
 
-## Community
+GTKX is Linux-only. You need:
+
+- Linux with the GTK4 (4.20 or later), Adwaita (1.8 or later), and GLib development libraries
+- Node.js 24 or later
+
+The `@gtkx/native` addon ships prebuilt for x64 and arm64 glibc Linux; other targets need to build it from the GTKX repository, which requires a Rust toolchain.
+
+## Examples
+
+Explore the [example apps](https://github.com/gtkx-org/gtkx/tree/main/examples):
+
+- [`hello-world`](https://github.com/gtkx-org/gtkx/tree/main/examples/hello-world): the counter above.
+- [`gtk-demo`](https://github.com/gtkx-org/gtkx/tree/main/examples/gtk-demo): a React port of the official GTK4 widget showcase, covering lists, dialogs, gestures, CSS, and OpenGL.
+- [`browser`](https://github.com/gtkx-org/gtkx/tree/main/examples/browser): a WebKitWebView-based web browser.
+- [`tutorial`](https://github.com/gtkx-org/gtkx/tree/main/examples/tutorial): the Tasks app the documentation builds.
+
+## Status
+
+GTKX 1.0 is at the release candidate stage.
+
+## Contributing
 
-- [GitHub Discussions](https://github.com/gtkx-org/gtkx/discussions) — Questions, ideas, and general discussion
-- [Issue Tracker](https://github.com/gtkx-org/gtkx/issues) — Bug reports and feature requests
+Contributions are welcome. See [CONTRIBUTING.md](https://github.com/gtkx-org/gtkx/blob/main/CONTRIBUTING.md), the [Code of Conduct](https://github.com/gtkx-org/gtkx/blob/main/CODE_OF_CONDUCT.md), and the [security policy](https://github.com/gtkx-org/gtkx/blob/main/SECURITY.md). Building the repo needs Node.js 24 or later, pnpm, and a Rust toolchain.
 
 ## License
 
-[MPL-2.0](./LICENSE)
+GTKX is licensed under [MPL-2.0](https://github.com/gtkx-org/gtkx/blob/main/LICENSE).

package/dist/act.d.ts

@@ -0,0 +1,19 @@
+declare global {
+    var IS_REACT_ACT_ENVIRONMENT: boolean | undefined;
+}
+export declare const getIsReactActEnvironment: () => boolean | undefined;
+export declare const setIsReactActEnvironment: (value: boolean | undefined) => void;
+type ActCallback<T> = () => T | PromiseLike<T>;
+type ActImplementation = <T>(callback: ActCallback<T>) => PromiseLike<T>;
+export declare const runWithActEnvironment: <T>(forced: boolean, fn: () => T | PromiseLike<T>) => T | PromiseLike<T>;
+/**
+ * Runs a callback inside React's act environment, flushing pending state
+ * updates and effects, and resolves once the work has settled.
+ *
+ * @param callback Work to run within the act environment.
+ * @returns A promise that resolves with the callback's result after updates flush.
+ */
+export declare const act: ActImplementation;
+export declare const runInAct: (callback: () => unknown) => Promise<void>;
+export {};
+//# sourceMappingURL=act.d.ts.map

package/dist/act.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../src/act.ts"],"names":[],"mappings":"AAEA,OAAO,CAAC,MAAM,CAAC;IACX,IAAI,wBAAwB,EAAE,OAAO,GAAG,SAAS,CAAC;CACrD;AAOD,eAAO,MAAM,wBAAwB,QAAO,OAAO,GAAG,SAAqD,CAAC;AAE5G,eAAO,MAAM,wBAAwB,UAAW,OAAO,GAAG,SAAS,KAAG,IAErE,CAAC;AAEF,KAAK,WAAW,CAAC,CAAC,IAAI,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;AAC/C,KAAK,iBAAiB,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC;AAKzE,eAAO,MAAM,qBAAqB,GAAI,CAAC,UAAU,OAAO,MAAM,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAG,CAAC,GAAG,WAAW,CAAC,CAAC,CAuBzG,CAAC;AAWF;;;;;;GAMG;AACH,eAAO,MAAM,GAAG,EAAE,iBAA+D,CAAC;AAElF,eAAO,MAAM,QAAQ,aAAc,MAAM,OAAO,KAAG,OAAO,CAAC,IAAI,CACC,CAAC"}

package/dist/act.js

@@ -0,0 +1,48 @@
+import { act as reactAct } from "react";
+const getGlobalThis = () => {
+    if (typeof globalThis !== "undefined")
+        return globalThis;
+    throw new Error("unable to locate global object");
+};
+export const getIsReactActEnvironment = () => getGlobalThis().IS_REACT_ACT_ENVIRONMENT;
+export const setIsReactActEnvironment = (value) => {
+    getGlobalThis().IS_REACT_ACT_ENVIRONMENT = value;
+};
+const isThenable = (value) => value !== null && typeof value === "object" && typeof value.then === "function";
+export const runWithActEnvironment = (forced, fn) => {
+    const previousActEnvironment = getIsReactActEnvironment();
+    setIsReactActEnvironment(forced);
+    try {
+        const result = fn();
+        if (isThenable(result)) {
+            return Promise.resolve(result).then((value) => {
+                setIsReactActEnvironment(previousActEnvironment);
+                return value;
+            }, (error) => {
+                setIsReactActEnvironment(previousActEnvironment);
+                throw error;
+            });
+        }
+        setIsReactActEnvironment(previousActEnvironment);
+        return result;
+    }
+    catch (error) {
+        setIsReactActEnvironment(previousActEnvironment);
+        throw error;
+    }
+};
+const withGlobalActEnvironment = (actImplementation) => (callback) => {
+    const settled = runWithActEnvironment(true, () => actImplementation(() => callback()));
+    return Promise.resolve(settled);
+};
+const actImplementation = reactAct;
+/**
+ * Runs a callback inside React's act environment, flushing pending state
+ * updates and effects, and resolves once the work has settled.
+ *
+ * @param callback Work to run within the act environment.
+ * @returns A promise that resolves with the callback's result after updates flush.
+ */
+export const act = withGlobalActEnvironment(actImplementation);
+export const runInAct = (callback) => Promise.resolve(act(() => callback())).then(() => undefined);
+//# sourceMappingURL=act.js.map

package/dist/act.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"act.js","sourceRoot":"","sources":["../src/act.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,IAAI,QAAQ,EAAE,MAAM,OAAO,CAAC;AAMxC,MAAM,aAAa,GAAG,GAAsB,EAAE;IAC1C,IAAI,OAAO,UAAU,KAAK,WAAW;QAAE,OAAO,UAAU,CAAC;IACzD,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;AACtD,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAwB,EAAE,CAAC,aAAa,EAAE,CAAC,wBAAwB,CAAC;AAE5G,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,KAA0B,EAAQ,EAAE;IACzE,aAAa,EAAE,CAAC,wBAAwB,GAAG,KAAK,CAAC;AACrD,CAAC,CAAC;AAKF,MAAM,UAAU,GAAG,CAAI,KAAc,EAA2B,EAAE,CAC9D,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAQ,KAAwB,CAAC,IAAI,KAAK,UAAU,CAAC;AAExG,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAI,MAAe,EAAE,EAA4B,EAAsB,EAAE;IAC1G,MAAM,sBAAsB,GAAG,wBAAwB,EAAE,CAAC;IAC1D,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,EAAE,EAAE,CAAC;QACpB,IAAI,UAAU,CAAI,MAAM,CAAC,EAAE,CAAC;YACxB,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAC/B,CAAC,KAAK,EAAE,EAAE;gBACN,wBAAwB,CAAC,sBAAsB,CAAC,CAAC;gBACjD,OAAO,KAAK,CAAC;YACjB,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;gBACN,wBAAwB,CAAC,sBAAsB,CAAC,CAAC;gBACjD,MAAM,KAAK,CAAC;YAChB,CAAC,CACJ,CAAC;QACN,CAAC;QACD,wBAAwB,CAAC,sBAAsB,CAAC,CAAC;QACjD,OAAO,MAAM,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,wBAAwB,CAAC,sBAAsB,CAAC,CAAC;QACjD,MAAM,KAAK,CAAC;IAChB,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,wBAAwB,GAC1B,CAAC,iBAAoC,EAAE,EAAE,CACzC,CAAI,QAAwB,EAAkB,EAAE;IAC5C,MAAM,OAAO,GAAG,qBAAqB,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,iBAAiB,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IACvF,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AACpC,CAAC,CAAC;AAEN,MAAM,iBAAiB,GAAsB,QAA6B,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,GAAG,GAAsB,wBAAwB,CAAC,iBAAiB,CAAC,CAAC;AAElF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,QAAuB,EAAiB,EAAE,CAC/D,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC","sourcesContent":["import { act as reactAct } from \"react\";\n\ndeclare global {\n    var IS_REACT_ACT_ENVIRONMENT: boolean | undefined;\n}\n\nconst getGlobalThis = (): typeof globalThis => {\n    if (typeof globalThis !== \"undefined\") return globalThis;\n    throw new Error(\"unable to locate global object\");\n};\n\nexport const getIsReactActEnvironment = (): boolean | undefined => getGlobalThis().IS_REACT_ACT_ENVIRONMENT;\n\nexport const setIsReactActEnvironment = (value: boolean | undefined): void => {\n    getGlobalThis().IS_REACT_ACT_ENVIRONMENT = value;\n};\n\ntype ActCallback<T> = () => T | PromiseLike<T>;\ntype ActImplementation = <T>(callback: ActCallback<T>) => PromiseLike<T>;\n\nconst isThenable = <T>(value: unknown): value is PromiseLike<T> =>\n    value !== null && typeof value === \"object\" && typeof (value as PromiseLike<T>).then === \"function\";\n\nexport const runWithActEnvironment = <T>(forced: boolean, fn: () => T | PromiseLike<T>): T | PromiseLike<T> => {\n    const previousActEnvironment = getIsReactActEnvironment();\n    setIsReactActEnvironment(forced);\n    try {\n        const result = fn();\n        if (isThenable<T>(result)) {\n            return Promise.resolve(result).then(\n                (value) => {\n                    setIsReactActEnvironment(previousActEnvironment);\n                    return value;\n                },\n                (error) => {\n                    setIsReactActEnvironment(previousActEnvironment);\n                    throw error;\n                },\n            );\n        }\n        setIsReactActEnvironment(previousActEnvironment);\n        return result;\n    } catch (error) {\n        setIsReactActEnvironment(previousActEnvironment);\n        throw error;\n    }\n};\n\nconst withGlobalActEnvironment =\n    (actImplementation: ActImplementation) =>\n    <T>(callback: ActCallback<T>): PromiseLike<T> => {\n        const settled = runWithActEnvironment(true, () => actImplementation(() => callback()));\n        return Promise.resolve(settled);\n    };\n\nconst actImplementation: ActImplementation = reactAct as ActImplementation;\n\n/**\n * Runs a callback inside React's act environment, flushing pending state\n * updates and effects, and resolves once the work has settled.\n *\n * @param callback Work to run within the act environment.\n * @returns A promise that resolves with the callback's result after updates flush.\n */\nexport const act: ActImplementation = withGlobalActEnvironment(actImplementation);\n\nexport const runInAct = (callback: () => unknown): Promise<void> =>\n    Promise.resolve(act(() => callback())).then(() => undefined);\n"]}

package/dist/bound-queries.d.ts

@@ -0,0 +1,32 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { ReactNode } from "react";
+import type { builtinQueries } from "./queries.js";
+import type { Container } from "./traversal.js";
+import type { BoundCustomQueries, DebugUtilities, QueryMap } from "./types.js";
+/**
+ * The set of built-in queries (getBy, findBy, queryBy, and their All variants)
+ * bound to a specific container.
+ */
+export type BoundQueries = BoundCustomQueries<typeof builtinQueries>;
+/**
+ * The global screen object's shape: built-in queries scoped to the current
+ * toplevels, plus debug utilities.
+ */
+export type Screen = BoundQueries & DebugUtilities;
+/**
+ * The result of a render call: queries scoped to the rendered tree, debug
+ * utilities, and controls for updating or tearing down the render.
+ *
+ * @typeParam Q Custom queries provided at render time, merged with the built-in ones.
+ */
+export type RenderResult<Q extends QueryMap = Record<never, never>> = BoundQueries & BoundCustomQueries<Q> & DebugUtilities & {
+    /** The top-level widget the element was rendered into. */
+    container: Gtk.Widget;
+    /** The root the queries are scoped to (defaults to all toplevels). */
+    baseElement: Container;
+    /** Unmounts the rendered tree and disposes its resources. */
+    unmount: () => Promise<void>;
+    /** Re-renders the tree with a new element, reusing the same root. */
+    rerender: (element: ReactNode) => Promise<void>;
+};
+//# sourceMappingURL=bound-queries.d.ts.map

package/dist/bound-queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bound-queries.d.ts","sourceRoot":"","sources":["../src/bound-queries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,kBAAkB,CAAC,OAAO,cAAc,CAAC,CAAC;AAErE;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG,YAAY,GAAG,cAAc,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,QAAQ,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,YAAY,GAC9E,kBAAkB,CAAC,CAAC,CAAC,GACrB,cAAc,GAAG;IACb,0DAA0D;IAC1D,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC;IACtB,sEAAsE;IACtE,WAAW,EAAE,SAAS,CAAC;IACvB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,EAAE,CAAC,OAAO,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD,CAAC"}

package/dist/bound-queries.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bound-queries.js.map

package/dist/bound-queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bound-queries.js","sourceRoot":"","sources":["../src/bound-queries.ts"],"names":[],"mappings":"","sourcesContent":["import type * as Gtk from \"@gtkx/gi/gtk\";\nimport type { ReactNode } from \"react\";\nimport type { builtinQueries } from \"./queries.js\";\nimport type { Container } from \"./traversal.js\";\nimport type { BoundCustomQueries, DebugUtilities, QueryMap } from \"./types.js\";\n\n/**\n * The set of built-in queries (getBy, findBy, queryBy, and their All variants)\n * bound to a specific container.\n */\nexport type BoundQueries = BoundCustomQueries<typeof builtinQueries>;\n\n/**\n * The global screen object's shape: built-in queries scoped to the current\n * toplevels, plus debug utilities.\n */\nexport type Screen = BoundQueries & DebugUtilities;\n\n/**\n * The result of a render call: queries scoped to the rendered tree, debug\n * utilities, and controls for updating or tearing down the render.\n *\n * @typeParam Q Custom queries provided at render time, merged with the built-in ones.\n */\nexport type RenderResult<Q extends QueryMap = Record<never, never>> = BoundQueries &\n    BoundCustomQueries<Q> &\n    DebugUtilities & {\n        /** The top-level widget the element was rendered into. */\n        container: Gtk.Widget;\n        /** The root the queries are scoped to (defaults to all toplevels). */\n        baseElement: Container;\n        /** Unmounts the rendered tree and disposes its resources. */\n        unmount: () => Promise<void>;\n        /** Re-renders the tree with a new element, reusing the same root. */\n        rerender: (element: ReactNode) => Promise<void>;\n    };\n"]}

package/dist/build-queries.d.ts

@@ -0,0 +1,16 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { type Method } from "./suggestions.js";
+import type { Container } from "./traversal.js";
+export type QueryAllBy<Args extends unknown[]> = (container: Container, ...args: Args) => Gtk.Widget[];
+type MultipleErrorBuilder<Args extends unknown[]> = (container: Container, matches: Gtk.Widget[], ...args: Args) => Error;
+type MissingErrorBuilder<Args extends unknown[]> = (container: Container, ...args: Args) => Error;
+export type BuiltQueries<Args extends unknown[]> = {
+    queryBy: (container: Container, ...args: Args) => Gtk.Widget | null;
+    getAllBy: QueryAllBy<Args>;
+    getBy: (container: Container, ...args: Args) => Gtk.Widget;
+    findAllBy: (container: Container, ...args: Args) => Promise<Gtk.Widget[]>;
+    findBy: (container: Container, ...args: Args) => Promise<Gtk.Widget>;
+};
+export declare const buildQueries: <Args extends unknown[]>(queryName: Method, queryAllBy: QueryAllBy<Args>, getMultipleError: MultipleErrorBuilder<Args>, getMissingError: MissingErrorBuilder<Args>) => BuiltQueries<Args>;
+export {};
+//# sourceMappingURL=build-queries.d.ts.map

package/dist/build-queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-queries.d.ts","sourceRoot":"","sources":["../src/build-queries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,cAAc,CAAC;AAGzC,OAAO,EAAqB,KAAK,MAAM,EAAgB,MAAM,kBAAkB,CAAC;AAChF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAIhD,MAAM,MAAM,UAAU,CAAC,IAAI,SAAS,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,GAAG,CAAC,MAAM,EAAE,CAAC;AAEvG,KAAK,oBAAoB,CAAC,IAAI,SAAS,OAAO,EAAE,IAAI,CAChD,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,EACrB,GAAG,IAAI,EAAE,IAAI,KACZ,KAAK,CAAC;AACX,KAAK,mBAAmB,CAAC,IAAI,SAAS,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,KAAK,CAAC;AAElG,MAAM,MAAM,YAAY,CAAC,IAAI,SAAS,OAAO,EAAE,IAAI;IAC/C,OAAO,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC;IACpE,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IAC3B,KAAK,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,GAAG,CAAC,MAAM,CAAC;IAC3D,SAAS,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1E,MAAM,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;CACxE,CAAC;AAyHF,eAAO,MAAM,YAAY,GAAI,IAAI,SAAS,OAAO,EAAE,aACpC,MAAM,cACL,UAAU,CAAC,IAAI,CAAC,oBACV,oBAAoB,CAAC,IAAI,CAAC,mBAC3B,mBAAmB,CAAC,IAAI,CAAC,KAC3C,YAAY,CAAC,IAAI,CAmCnB,CAAC"}

package/dist/build-queries.js

@@ -0,0 +1,103 @@
+import { getConfig } from "./config.js";
+import { runWithExpensiveErrorDiagnosticsDisabled, suggestionError } from "./errors.js";
+import { getSuggestedQuery } from "./suggestions.js";
+import { waitFor } from "./wait-for.js";
+const extractWaitForOptions = (args) => {
+    const last = args[args.length - 1];
+    if (last && typeof last === "object" && !(last instanceof RegExp)) {
+        const { timeout, interval, onTimeout } = last;
+        return { timeout, interval, onTimeout };
+    }
+    return {};
+};
+const extractSuggestOption = (args) => {
+    const last = args[args.length - 1];
+    if (last && typeof last === "object" && !(last instanceof RegExp)) {
+        return last.suggest;
+    }
+    return undefined;
+};
+const maybeThrowSuggestion = (options) => {
+    const { container, match, queryName, variant, suggest } = options;
+    const shouldSuggest = suggest ?? getConfig().throwSuggestions;
+    if (!shouldSuggest)
+        return;
+    const suggestion = getSuggestedQuery(match, variant);
+    if (suggestion && suggestion.queryName !== queryName) {
+        throw suggestionError(suggestion.toString(), container);
+    }
+};
+const reRunForDiagnostics = (query, container, args, fallback) => {
+    try {
+        query(container, ...args);
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return error;
+    }
+    return fallback;
+};
+const findOptions = (query, container, args) => {
+    const userOptions = extractWaitForOptions(args);
+    const onTimeout = userOptions.onTimeout ?? ((fallback) => reRunForDiagnostics(query, container, args, fallback));
+    return {
+        stackTraceError: new Error("STACK_TRACE_MESSAGE"),
+        onTimeout,
+        timeout: userOptions.timeout,
+        interval: userOptions.interval,
+    };
+};
+const singleFrom = (allQuery, getMultipleError) => (container, ...args) => {
+    const matches = allQuery(container, ...args);
+    if (matches.length > 1)
+        throw getMultipleError(container, matches, ...args);
+    return matches[0] ?? null;
+};
+const allOrThrow = (allQuery, getMissingError) => (container, ...args) => {
+    const matches = allQuery(container, ...args);
+    if (matches.length === 0)
+        throw getMissingError(container, ...args);
+    return matches;
+};
+const wrapSingleWithSuggestion = (query, queryName, variant) => (container, ...args) => {
+    const match = query(container, ...args);
+    if (match) {
+        maybeThrowSuggestion({ container, match, queryName, variant, suggest: extractSuggestOption(args) });
+    }
+    return match;
+};
+const wrapAllWithSuggestion = (query, queryName, variant) => (container, ...args) => {
+    const matches = query(container, ...args);
+    const [first] = matches;
+    if (first !== undefined) {
+        maybeThrowSuggestion({ container, match: first, queryName, variant, suggest: extractSuggestOption(args) });
+    }
+    return matches;
+};
+const requireSingle = (query, getMissingError) => (container, ...args) => {
+    const match = query(container, ...args);
+    if (match === null)
+        throw getMissingError(container, ...args);
+    return match;
+};
+export const buildQueries = (queryName, queryAllBy, getMultipleError, getMissingError) => {
+    const getAllBy = allOrThrow(queryAllBy, getMissingError);
+    const getBy = requireSingle(singleFrom(getAllBy, getMultipleError), getMissingError);
+    const queryByWithSuggestion = wrapSingleWithSuggestion(singleFrom(queryAllBy, getMultipleError), queryName, "query");
+    const getAllByWithSuggestion = wrapAllWithSuggestion(getAllBy, queryName, "getAll");
+    const getByWithSuggestion = (container, ...args) => {
+        const match = getBy(container, ...args);
+        maybeThrowSuggestion({ container, match, queryName, variant: "get", suggest: extractSuggestOption(args) });
+        return match;
+    };
+    const findAllBy = (container, ...args) => waitFor(() => runWithExpensiveErrorDiagnosticsDisabled(() => getAllByWithSuggestion(container, ...args)), findOptions(getAllByWithSuggestion, container, args));
+    const findBy = (container, ...args) => waitFor(() => runWithExpensiveErrorDiagnosticsDisabled(() => getByWithSuggestion(container, ...args)), findOptions(getByWithSuggestion, container, args));
+    return {
+        queryBy: queryByWithSuggestion,
+        getAllBy: getAllByWithSuggestion,
+        getBy: getByWithSuggestion,
+        findAllBy,
+        findBy,
+    };
+};
+//# sourceMappingURL=build-queries.js.map

package/dist/build-queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-queries.js","sourceRoot":"","sources":["../src/build-queries.ts"],"names":[],"mappings":"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","sourcesContent":["import type * as Gtk from \"@gtkx/gi/gtk\";\nimport { getConfig } from \"./config.js\";\nimport { runWithExpensiveErrorDiagnosticsDisabled, suggestionError } from \"./errors.js\";\nimport { getSuggestedQuery, type Method, type Variant } from \"./suggestions.js\";\nimport type { Container } from \"./traversal.js\";\nimport type { MatcherOptions, WaitForOptions } from \"./types.js\";\nimport { waitFor } from \"./wait-for.js\";\n\nexport type QueryAllBy<Args extends unknown[]> = (container: Container, ...args: Args) => Gtk.Widget[];\n\ntype MultipleErrorBuilder<Args extends unknown[]> = (\n    container: Container,\n    matches: Gtk.Widget[],\n    ...args: Args\n) => Error;\ntype MissingErrorBuilder<Args extends unknown[]> = (container: Container, ...args: Args) => Error;\n\nexport type BuiltQueries<Args extends unknown[]> = {\n    queryBy: (container: Container, ...args: Args) => Gtk.Widget | null;\n    getAllBy: QueryAllBy<Args>;\n    getBy: (container: Container, ...args: Args) => Gtk.Widget;\n    findAllBy: (container: Container, ...args: Args) => Promise<Gtk.Widget[]>;\n    findBy: (container: Container, ...args: Args) => Promise<Gtk.Widget>;\n};\n\nconst extractWaitForOptions = (args: unknown[]): WaitForOptions => {\n    const last = args[args.length - 1];\n    if (last && typeof last === \"object\" && !(last instanceof RegExp)) {\n        const { timeout, interval, onTimeout } = last as WaitForOptions;\n        return { timeout, interval, onTimeout };\n    }\n    return {};\n};\n\nconst extractSuggestOption = (args: unknown[]): boolean | undefined => {\n    const last = args[args.length - 1];\n    if (last && typeof last === \"object\" && !(last instanceof RegExp)) {\n        return (last as MatcherOptions).suggest;\n    }\n    return undefined;\n};\n\nconst maybeThrowSuggestion = (options: {\n    container: Container;\n    match: Gtk.Widget;\n    queryName: Method;\n    variant: Variant;\n    suggest: boolean | undefined;\n}): void => {\n    const { container, match, queryName, variant, suggest } = options;\n    const shouldSuggest = suggest ?? getConfig().throwSuggestions;\n    if (!shouldSuggest) return;\n\n    const suggestion = getSuggestedQuery(match, variant);\n    if (suggestion && suggestion.queryName !== queryName) {\n        throw suggestionError(suggestion.toString(), container);\n    }\n};\n\ntype FindQuery<Args extends unknown[]> = (container: Container, ...args: Args) => unknown;\n\nconst reRunForDiagnostics = <Args extends unknown[]>(\n    query: FindQuery<Args>,\n    container: Container,\n    args: Args,\n    fallback: Error,\n): Error => {\n    try {\n        query(container, ...args);\n    } catch (error) {\n        if (error instanceof Error) return error;\n    }\n    return fallback;\n};\n\nconst findOptions = <Args extends unknown[]>(\n    query: FindQuery<Args>,\n    container: Container,\n    args: Args,\n): WaitForOptions => {\n    const userOptions = extractWaitForOptions(args);\n    const onTimeout =\n        userOptions.onTimeout ?? ((fallback: Error) => reRunForDiagnostics(query, container, args, fallback));\n    return {\n        stackTraceError: new Error(\"STACK_TRACE_MESSAGE\"),\n        onTimeout,\n        timeout: userOptions.timeout,\n        interval: userOptions.interval,\n    };\n};\n\ntype SingleQuery<Args extends unknown[]> = (container: Container, ...args: Args) => Gtk.Widget | null;\n\nconst singleFrom =\n    <Args extends unknown[]>(\n        allQuery: QueryAllBy<Args>,\n        getMultipleError: MultipleErrorBuilder<Args>,\n    ): SingleQuery<Args> =>\n    (container, ...args) => {\n        const matches = allQuery(container, ...args);\n        if (matches.length > 1) throw getMultipleError(container, matches, ...args);\n        return matches[0] ?? null;\n    };\n\nconst allOrThrow =\n    <Args extends unknown[]>(\n        allQuery: QueryAllBy<Args>,\n        getMissingError: MissingErrorBuilder<Args>,\n    ): QueryAllBy<Args> =>\n    (container, ...args) => {\n        const matches = allQuery(container, ...args);\n        if (matches.length === 0) throw getMissingError(container, ...args);\n        return matches;\n    };\n\nconst wrapSingleWithSuggestion =\n    <Args extends unknown[]>(query: SingleQuery<Args>, queryName: Method, variant: Variant): SingleQuery<Args> =>\n    (container, ...args) => {\n        const match = query(container, ...args);\n        if (match) {\n            maybeThrowSuggestion({ container, match, queryName, variant, suggest: extractSuggestOption(args) });\n        }\n        return match;\n    };\n\nconst wrapAllWithSuggestion =\n    <Args extends unknown[]>(query: QueryAllBy<Args>, queryName: Method, variant: Variant): QueryAllBy<Args> =>\n    (container, ...args) => {\n        const matches = query(container, ...args);\n        const [first] = matches;\n        if (first !== undefined) {\n            maybeThrowSuggestion({ container, match: first, queryName, variant, suggest: extractSuggestOption(args) });\n        }\n        return matches;\n    };\n\nconst requireSingle =\n    <Args extends unknown[]>(query: SingleQuery<Args>, getMissingError: MissingErrorBuilder<Args>) =>\n    (container: Container, ...args: Args): Gtk.Widget => {\n        const match = query(container, ...args);\n        if (match === null) throw getMissingError(container, ...args);\n        return match;\n    };\n\nexport const buildQueries = <Args extends unknown[]>(\n    queryName: Method,\n    queryAllBy: QueryAllBy<Args>,\n    getMultipleError: MultipleErrorBuilder<Args>,\n    getMissingError: MissingErrorBuilder<Args>,\n): BuiltQueries<Args> => {\n    const getAllBy = allOrThrow(queryAllBy, getMissingError);\n    const getBy = requireSingle(singleFrom(getAllBy, getMultipleError), getMissingError);\n\n    const queryByWithSuggestion = wrapSingleWithSuggestion(\n        singleFrom(queryAllBy, getMultipleError),\n        queryName,\n        \"query\",\n    );\n    const getAllByWithSuggestion = wrapAllWithSuggestion(getAllBy, queryName, \"getAll\");\n    const getByWithSuggestion: (container: Container, ...args: Args) => Gtk.Widget = (container, ...args) => {\n        const match = getBy(container, ...args);\n        maybeThrowSuggestion({ container, match, queryName, variant: \"get\", suggest: extractSuggestOption(args) });\n        return match;\n    };\n\n    const findAllBy = (container: Container, ...args: Args): Promise<Gtk.Widget[]> =>\n        waitFor(\n            () => runWithExpensiveErrorDiagnosticsDisabled(() => getAllByWithSuggestion(container, ...args)),\n            findOptions(getAllByWithSuggestion, container, args),\n        );\n\n    const findBy = (container: Container, ...args: Args): Promise<Gtk.Widget> =>\n        waitFor(\n            () => runWithExpensiveErrorDiagnosticsDisabled(() => getByWithSuggestion(container, ...args)),\n            findOptions(getByWithSuggestion, container, args),\n        );\n\n    return {\n        queryBy: queryByWithSuggestion,\n        getAllBy: getAllByWithSuggestion,\n        getBy: getByWithSuggestion,\n        findAllBy,\n        findBy,\n    };\n};\n"]}

package/dist/cleanup-registry.d.ts

@@ -0,0 +1,4 @@
+export type CleanupFunction = () => void | Promise<void>;
+export declare const addToCleanupQueue: (fn: CleanupFunction) => void;
+export declare const runCleanup: () => Promise<void>;
+//# sourceMappingURL=cleanup-registry.d.ts.map

package/dist/cleanup-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-registry.d.ts","sourceRoot":"","sources":["../src/cleanup-registry.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAIzD,eAAO,MAAM,iBAAiB,OAAQ,eAAe,KAAG,IAEvD,CAAC;AAEF,eAAO,MAAM,UAAU,QAAa,OAAO,CAAC,IAAI,CAK/C,CAAC"}

package/dist/cleanup-registry.js

@@ -0,0 +1,11 @@
+const cleanupQueue = new Set();
+export const addToCleanupQueue = (fn) => {
+    cleanupQueue.add(fn);
+};
+export const runCleanup = async () => {
+    for (const fn of cleanupQueue) {
+        await fn();
+    }
+    cleanupQueue.clear();
+};
+//# sourceMappingURL=cleanup-registry.js.map

package/dist/cleanup-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-registry.js","sourceRoot":"","sources":["../src/cleanup-registry.ts"],"names":[],"mappings":"AAEA,MAAM,YAAY,GAAG,IAAI,GAAG,EAAmB,CAAC;AAEhD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,EAAmB,EAAQ,EAAE;IAC3D,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACzB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,IAAmB,EAAE;IAChD,KAAK,MAAM,EAAE,IAAI,YAAY,EAAE,CAAC;QAC5B,MAAM,EAAE,EAAE,CAAC;IACf,CAAC;IACD,YAAY,CAAC,KAAK,EAAE,CAAC;AACzB,CAAC,CAAC","sourcesContent":["export type CleanupFunction = () => void | Promise<void>;\n\nconst cleanupQueue = new Set<CleanupFunction>();\n\nexport const addToCleanupQueue = (fn: CleanupFunction): void => {\n    cleanupQueue.add(fn);\n};\n\nexport const runCleanup = async (): Promise<void> => {\n    for (const fn of cleanupQueue) {\n        await fn();\n    }\n    cleanupQueue.clear();\n};\n"]}

package/dist/config.d.ts

@@ -1,65 +1,32 @@
 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
-     */
+    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>;
+export 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;
+export 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;
+export declare const configure: (newConfig: Partial<Config> | ConfigFn) => void;
 //# sourceMappingURL=config.d.ts.map