@gtkx/cli 1.0.0-rc.4 → 1.1.0

package/src/mcp/handlers.ts

@@ -8,11 +8,10 @@ import {
     ServerRequestParamsSchemas,
     widgetNotFoundError,
 } from "@gtkx/mcp/internal";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
 import type { WidgetRegistry } from "./widget-registry.js";
 import { serializeWidget } from "./serialize-widget.js";
 import { loadTestingModule, type TestingModule } from "./testing-loader.js";
+import { readWidgetProperties } from "./widget-properties.js";
 
 type HandlerContext = {
     app: Gtk.Application;
@@ -21,6 +20,11 @@ type HandlerContext = {
 
 type ValidatedHandler = (ctx: HandlerContext, params: unknown) => Promise<unknown>;
 type WidgetTarget = { testing: TestingModule; widget: Gtk.Widget };
+type WidgetParams = { widgetId?: string | undefined };
+type TargetedHandler<Params> = (ctx: HandlerContext, target: WidgetTarget, params: Params) => Promise<unknown>;
+type QueryParams = ServerRequestParams<"widget.query">;
+type QueryBy = QueryParams["by"];
+type QueryRunner = (testing: TestingModule, app: Gtk.Application, params: QueryParams) => Promise<Gtk.Widget[]>;
 
 const HANDLERS: Record<ServerInitiatedMethod, ValidatedHandler> = {
     "app.getWindows": validated(ServerRequestParamsSchemas["app.getWindows"], ({ registry }) =>
@@ -43,20 +47,22 @@ const HANDLERS: Record<ServerInitiatedMethod, ValidatedHandler> = {
         };
     }),
     "widget.query": validated(ServerRequestParamsSchemas["widget.query"], handleQuery),
-    "widget.getProps": validated(ServerRequestParamsSchemas["widget.getProps"], async ({ registry }, params) => {
-        const { testing, widget } = await widgetTarget(registry, params.widgetId);
-
-        return serializeWidget(widget, (target) => registry.getOrCreateId(target), testing);
-    }),
-    "widget.click": validated(ServerRequestParamsSchemas["widget.click"], async ({ registry }, params) => {
-        const { testing, widget } = await widgetTarget(registry, params.widgetId);
+    "widget.getProps": targeted(
+        ServerRequestParamsSchemas["widget.getProps"],
+        ({ registry }, { testing, widget }, params) =>
+            Promise.resolve({
+                ...(params.properties !== undefined && {
+                    properties: readWidgetProperties(widget, params.properties, registry),
+                }),
+                ...serializeWidget(widget, (target) => registry.getOrCreateId(target), testing, params.maxDepth),
+            }),
+    ),
+    "widget.click": targeted(ServerRequestParamsSchemas["widget.click"], async (_ctx, { testing, widget }) => {
         await testing.userEvent.click(widget);
 
         return { success: true };
     }),
-    "widget.type": validated(ServerRequestParamsSchemas["widget.type"], async ({ registry }, params) => {
-        const { testing, widget } = await widgetTarget(registry, params.widgetId);
-
+    "widget.type": targeted(ServerRequestParamsSchemas["widget.type"], async (_ctx, { testing, widget }, params) => {
         if (params.clear) {
             await testing.userEvent.clear(widget);
         }
@@ -65,16 +71,43 @@ const HANDLERS: Record<ServerInitiatedMethod, ValidatedHandler> = {
 
         return { success: true };
     }),
-    "widget.fireEvent": validated(ServerRequestParamsSchemas["widget.fireEvent"], async ({ registry }, params) => {
-        const { testing, widget } = await widgetTarget(registry, params.widgetId);
-        const signalArgs = (params.args ?? []).map((arg) => extractSignalArg(arg));
-        await testing.fireEvent(widget, params.signal, ...signalArgs);
-
-        return { success: true };
-    }),
+    "widget.fireEvent": targeted(
+        ServerRequestParamsSchemas["widget.fireEvent"],
+        async (_ctx, { testing, widget }, params) => {
+            const signalArgs = (params.args ?? []).map((arg) => extractSignalArg(arg));
+            const isRealized = widget.getRealized();
+            const isMapped = widget.getMapped();
+            const isSensitive = widget.getSensitive();
+            await testing.fireEvent(widget, params.signal, ...signalArgs);
+
+            return {
+                signal: params.signal,
+                isRealized,
+                isMapped,
+                isSensitive,
+                note: emissionNote(isRealized, isMapped),
+            };
+        },
+    ),
     "widget.screenshot": validated(ServerRequestParamsSchemas["widget.screenshot"], handleScreenshot),
 };
 
+const QUERY_RUNNERS: Record<QueryBy, QueryRunner> = {
+    role: runRoleQuery,
+    text: runTextQuery,
+    name: runNameQuery,
+    labelText: runLabelTextQuery,
+};
+
+const SEARCHED_BY: Record<QueryBy, string> = {
+    role: "the accessible role, narrowed by any options given",
+    text: "the text the widget renders",
+    name:
+        "the widget name (gtk_widget_get_name, which reports the GType name such as \"GtkButton\" when no name " +
+        "was set), the accessible label, and the text the widget renders",
+    labelText: "the accessible label, the labelled-by relation, and the label whose mnemonic targets the widget",
+};
+
 function validated<Params>(
     schema: ParamsSchema<Params>,
     handler: (ctx: HandlerContext, params: Params) => Promise<unknown>,
@@ -90,6 +123,14 @@ function validated<Params>(
     };
 }
 
+function targeted<Params extends WidgetParams>(
+    schema: ParamsSchema<Params>,
+    handler: TargetedHandler<Params>,
+): ValidatedHandler {
+    return validated(schema, async (ctx, params) =>
+        handler(ctx, await widgetTarget(ctx.registry, params.widgetId), params));
+}
+
 const widgetTarget = async (registry: WidgetRegistry, widgetId: string | undefined): Promise<WidgetTarget> => ({
     testing: await loadTestingModule(),
     widget: requireWidget(registry, widgetId),
@@ -115,6 +156,21 @@ const extractSignalArg = (arg: unknown): unknown => {
     return isTypedArg ? (arg as { value: unknown }).value : arg;
 };
 
+const emissionNote = (isRealized: boolean, isMapped: boolean): string => {
+    if (isRealized && isMapped) {
+        return (
+            "The signal was emitted. Default handlers that animate, such as a button activate, settle " +
+            "asynchronously, so read the widget again rather than assuming the effect has landed."
+        );
+    }
+
+    return (
+        "The signal was emitted on a widget that is not realized and mapped, so a default handler that " +
+        "requires a drawn widget does nothing. Present the containing window or open the containing " +
+        "popover first, then fire the signal again."
+    );
+};
+
 const resolveRole = (value: string | number): Gtk.AccessibleRole | undefined => {
     if (typeof value === "number") {
         return value;
@@ -133,42 +189,56 @@ const matchesOrEmpty = async (find: () => Promise<Gtk.Widget[]>): Promise<Gtk.Wi
     }
 };
 
-async function handleQuery(
-    { app, registry }: HandlerContext,
-    params: ServerRequestParams<"widget.query">,
-): Promise<unknown> {
-    const testing = await loadTestingModule();
-    let widgets: Gtk.Widget[] = [];
+function runRoleQuery(testing: TestingModule, app: Gtk.Application, params: QueryParams): Promise<Gtk.Widget[]> {
+    const roleValue = resolveRole(params.value);
 
-    switch (params.by) {
-        case "role": {
-            const roleValue = resolveRole(params.value);
+    if (roleValue === undefined) {
+        throw invalidRequestError(
+            `Unknown accessible role "${String(params.value)}"; use the lowercase role shown in the ` +
+            "widget tree, e.g. \"button\", \"list\", \"list_item\", or \"checkbox\".",
+        );
+    }
 
-            if (roleValue === undefined) {
-                throw invalidRequestError(
-                    `Unknown accessible role "${String(params.value)}"; use the lowercase role shown in the ` +
-                    "widget tree, e.g. \"button\", \"list\", \"list_item\", or \"checkbox\".",
-                );
-            }
+    return matchesOrEmpty(() => testing.findAllByRole(app, roleValue, params.options));
+}
 
-            widgets = await matchesOrEmpty(() => testing.findAllByRole(app, roleValue, params.options));
-            break;
-        }
-        case "text": {
-            widgets = await matchesOrEmpty(() => testing.findAllByText(app, String(params.value), params.options));
-            break;
-        }
-        case "name": {
-            widgets = await matchesOrEmpty(() => testing.findAllByName(app, String(params.value), params.options));
-            break;
-        }
-        case "labelText": {
-            widgets = await matchesOrEmpty(() => testing.findAllByLabelText(app, String(params.value), params.options));
-            break;
-        }
-    }
+function runTextQuery(testing: TestingModule, app: Gtk.Application, params: QueryParams): Promise<Gtk.Widget[]> {
+    return matchesOrEmpty(() => testing.findAllByText(app, String(params.value), params.options));
+}
 
-    return { widgets: widgets.map((w) => serializeWidget(w, (widget) => registry.getOrCreateId(widget), testing, 0)) };
+function runLabelTextQuery(testing: TestingModule, app: Gtk.Application, params: QueryParams): Promise<Gtk.Widget[]> {
+    return matchesOrEmpty(() => testing.findAllByLabelText(app, String(params.value), params.options));
+}
+
+async function runNameQuery(
+    testing: TestingModule,
+    app: Gtk.Application,
+    params: QueryParams,
+): Promise<Gtk.Widget[]> {
+    const matches = await Promise.all([
+        matchesOrEmpty(() => testing.findAllByName(app, String(params.value), params.options)),
+        runLabelTextQuery(testing, app, params),
+        runTextQuery(testing, app, params),
+    ]);
+
+    return [...new Set(matches.flat())];
+}
+
+const emptyQueryHint = (params: QueryParams): string =>
+    `Nothing matched by:"${params.by}" value:"${String(params.value)}", which compared ${SEARCHED_BY[params.by]}. ` +
+    "Call gtkx_get_widget_tree to see what is mounted; by:\"name\" is the widest match, and by:\"role\" accepts " +
+    "options.name to match the accessible name of a known role.";
+
+async function handleQuery({ app, registry }: HandlerContext, params: QueryParams): Promise<unknown> {
+    const testing = await loadTestingModule();
+    const widgets = await QUERY_RUNNERS[params.by](testing, app, params);
+    const resolveId = (widget: Gtk.Widget): string => registry.getOrCreateId(widget);
+
+    return {
+        widgets: widgets.map((widget) => serializeWidget(widget, resolveId, testing, 0)),
+        searched: SEARCHED_BY[params.by],
+        ...(widgets.length === 0 && { hint: emptyQueryHint(params) }),
+    };
 }
 
 const defaultScreenshotTarget = (registry: WidgetRegistry): Gtk.Widget => {
@@ -187,12 +257,9 @@ async function handleScreenshot(
 ): Promise<unknown> {
     const testing = await loadTestingModule();
     const target = params.windowId ? requireWidget(registry, params.windowId) : defaultScreenshotTarget(registry);
-    const result = await testing.screenshot(target);
+    const result = await testing.screenshot(target, { path: params.path });
 
     if (params.path) {
-        mkdirSync(dirname(params.path), { recursive: true });
-        writeFileSync(params.path, Buffer.from(result.data, "base64"));
-
         return { data: result.data, mimeType: result.mimeType, savedPath: params.path };
     }
 
@@ -210,4 +277,4 @@ const dispatch = async (method: string, params: unknown, ctx: HandlerContext): P
     return HANDLERS[method](ctx, params);
 };
 
-export { dispatch, type HandlerContext };
+export { dispatch };

package/src/mcp/index.ts

@@ -7,6 +7,7 @@ type McpClientController = {
 
 const { start: startMcpClient, stop: stopMcpClient } = createMcpClientController();
 
+/* eslint-disable-next-line unicorn/consistent-boolean-name -- the boolean reports whether connecting succeeded */
 async function connectQuietly(client: McpClient): Promise<boolean> {
     try {
         await client.connect();

package/src/mcp/serialize-widget.ts

@@ -1,41 +1,92 @@
 import type * as Gtk from "@gtkx/gi/gtk";
-import type { SerializedWidget } from "@gtkx/mcp/internal";
+import { DEFAULT_SUBTREE_DEPTH, MAX_SUBTREE_WIDGETS, type SerializedWidget } from "@gtkx/mcp/internal";
 
 type WidgetIdResolver = (widget: Gtk.Widget) => string;
 
 type WidgetFormatting = {
     formatRole(role: Gtk.AccessibleRole): string;
-    getWidgetNodeText(widget: Gtk.Widget): string | null;
+    getTypeTag(widget: Gtk.Widget): string;
+    getWidgetText(widget: Gtk.Widget): string | null;
+};
+
+type PendingWidget = {
+    depth: number;
+    node: SerializedWidget;
+    widget: Gtk.Widget;
+};
+
+type Expansion = {
+    budget: number;
+    maxDepth: number;
+    pending: PendingWidget[];
+    resolveId: WidgetIdResolver;
+    testing: WidgetFormatting;
+};
+
+const getChildren = (widget: Gtk.Widget): Gtk.Widget[] => {
+    const children: Gtk.Widget[] = [];
+    let child = widget.getFirstChild();
+
+    while (child) {
+        children.push(child);
+        child = child.getNextSibling();
+    }
+
+    return children;
+};
+
+const createNode = (widget: Gtk.Widget, expansion: Expansion): SerializedWidget => ({
+    id: expansion.resolveId(widget),
+    type: expansion.testing.getTypeTag(widget),
+    role: expansion.testing.formatRole(widget.getAccessibleRole()),
+    name: widget.getName() || null,
+    text: expansion.testing.getWidgetText(widget),
+    isSensitive: widget.getSensitive(),
+    isVisible: widget.getVisible(),
+    cssClasses: widget.getCssClasses(),
+    children: [],
+});
+
+const expandNode = (expansion: Expansion, parent: PendingWidget): void => {
+    const children = getChildren(parent.widget);
+    const canDescend = parent.depth < expansion.maxDepth;
+    const shownCount = canDescend ? Math.min(children.length, expansion.budget) : 0;
+    expansion.budget -= shownCount;
+
+    for (const child of children.slice(0, shownCount)) {
+        const node = createNode(child, expansion);
+        parent.node.children.push(node);
+        expansion.pending.push({ depth: parent.depth + 1, node, widget: child });
+    }
+
+    if (shownCount < children.length) {
+        parent.node.hiddenChildren = children.length - shownCount;
+    }
 };
 
 const serializeWidget = (
     widget: Gtk.Widget,
     resolveId: WidgetIdResolver,
     testing: WidgetFormatting,
-    maxDepth = Infinity,
+    maxDepth = DEFAULT_SUBTREE_DEPTH,
 ): SerializedWidget => {
-    const children: SerializedWidget[] = [];
+    const expansion: Expansion = {
+        budget: MAX_SUBTREE_WIDGETS - 1,
+        maxDepth,
+        pending: [],
+        resolveId,
+        testing,
+    };
 
-    if (maxDepth > 0) {
-        let child = widget.getFirstChild();
+    const root = createNode(widget, expansion);
+    let parent: PendingWidget | undefined = { depth: 0, node: root, widget };
 
-        while (child) {
-            children.push(serializeWidget(child, resolveId, testing, maxDepth - 1));
-            child = child.getNextSibling();
-        }
+    while (parent !== undefined) {
+        expandNode(expansion, parent);
+        parent = expansion.pending.shift();
     }
 
-    return {
-        id: resolveId(widget),
-        type: widget.constructor.name,
-        role: testing.formatRole(widget.getAccessibleRole()),
-        name: widget.getName() || null,
-        text: testing.getWidgetNodeText(widget),
-        isSensitive: widget.getSensitive(),
-        isVisible: widget.getVisible(),
-        cssClasses: widget.getCssClasses(),
-        children,
-    };
+    return root;
 };
 
-export { serializeWidget, type WidgetFormatting };
+export { serializeWidget };

package/src/mcp/testing-loader.ts

@@ -1,4 +1,6 @@
-type TestingModule = typeof import("@gtkx/testing");
+type TestingPublicModule = typeof import("@gtkx/testing");
+type TestingInternalModule = typeof import("@gtkx/testing/internal");
+type TestingModule = TestingPublicModule & Pick<TestingInternalModule, "getTypeTag">;
 type TestingModuleLoader = () => Promise<TestingModule>;
 
 type TestingModuleCache = {
@@ -14,8 +16,14 @@ type TestingModuleState = {
 
 const { setLoader: setTestingModuleLoader, load: loadTestingModule } = createTestingModuleCache();
 
-function defaultLoader(): Promise<TestingModule> {
-    return import("@gtkx/testing");
+function mergeTestingModule(publicApi: TestingPublicModule, internals: TestingInternalModule): TestingModule {
+    return { ...publicApi, getTypeTag: internals.getTypeTag };
+}
+
+async function defaultLoader(): Promise<TestingModule> {
+    const [publicApi, internals] = await Promise.all([import("@gtkx/testing"), import("@gtkx/testing/internal")]);
+
+    return mergeTestingModule(publicApi, internals);
 }
 
 function missingTestingPackageError(cause: unknown): Error {
@@ -70,4 +78,11 @@ function createTestingModuleCache(): TestingModuleCache {
     };
 }
 
-export { setTestingModuleLoader, loadTestingModule, type TestingModule, type TestingModuleLoader };
+export {
+    setTestingModuleLoader,
+    loadTestingModule,
+    mergeTestingModule,
+    type TestingInternalModule,
+    type TestingModule,
+    type TestingPublicModule,
+};

package/src/mcp/widget-properties.ts

@@ -0,0 +1,153 @@
+import * as GObject from "@gtkx/gi/gobject";
+import * as Gtk from "@gtkx/gi/gtk";
+import { propertyNotFoundError, type SerializedProperty } from "@gtkx/mcp/internal";
+import {
+    type ExternalObject,
+    getHandle,
+    getInstanceType,
+    type Handle,
+    TYPE_ENUM,
+    TYPE_FLAGS,
+    typeIsA,
+    typeName,
+} from "@gtkx/runtime";
+import { fromValue, getValueType } from "@gtkx/runtime/internal";
+import { camelCase, errorMessage, kebabCase } from "@gtkx/utils";
+import type { WidgetRegistry } from "./widget-registry.js";
+
+type PropertyRepresentation = Omit<SerializedProperty, "type">;
+type NativeProperty = { type: bigint; handle: ExternalObject<Handle> };
+
+const SCALAR_TYPES: Set<string> = new Set(["string", "number", "boolean"]);
+
+const canonicalName = (name: string): string => kebabCase(name).replaceAll("_", "-");
+const widgetTypeName = (widget: Gtk.Widget): string => typeName(getInstanceType(widget)) ?? widget.constructor.name;
+const byName = (left: string, right: string): number => left.localeCompare(right);
+
+const isScalar = (value: unknown): value is string | number | boolean | null =>
+    value === null || SCALAR_TYPES.has(typeof value);
+
+function prototypesFor(widget: Gtk.Widget): object[] {
+    const prototypes: object[] = [];
+    let prototype = Object.getPrototypeOf(widget) as object | null;
+
+    while (prototype !== null && prototype !== Object.prototype) {
+        prototypes.push(prototype);
+        prototype = Object.getPrototypeOf(prototype) as object | null;
+    }
+
+    return prototypes;
+}
+
+function getAccessor(widget: Gtk.Widget, member: string): PropertyDescriptor | undefined {
+    for (const prototype of prototypesFor(widget)) {
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, member);
+
+        if (descriptor !== undefined) {
+            return descriptor;
+        }
+    }
+
+    return undefined;
+}
+
+function getReadableNames(prototype: object): string[] {
+    const descriptors = Object.entries(Object.getOwnPropertyDescriptors(prototype));
+
+    return descriptors.filter(([, descriptor]) => descriptor.get !== undefined).map(([member]) => kebabCase(member));
+}
+
+function readablePropertyNames(widget: Gtk.Widget): string[] {
+    const names = prototypesFor(widget).flatMap((prototype) => getReadableNames(prototype));
+
+    return [...new Set(names)].toSorted(byName);
+}
+
+const requireReadableProperty = (widget: Gtk.Widget, property: string): void => {
+    if (getAccessor(widget, camelCase(property))?.get !== undefined) {
+        return;
+    }
+
+    throw propertyNotFoundError(widgetTypeName(widget), property, readablePropertyNames(widget));
+};
+
+function readNativeProperty(widget: Gtk.Widget, property: string): NativeProperty {
+    const value = new GObject.Value();
+    widget.getProperty(property, value);
+    const handle = getHandle(value);
+
+    return { type: getValueType(handle), handle };
+}
+
+function describeObjectValue(value: unknown, registry: WidgetRegistry): PropertyRepresentation {
+    if (typeof value !== "object" || value === null) {
+        return { value: String(value) };
+    }
+
+    const name = typeName(getInstanceType(value)) ?? value.constructor.name;
+
+    if (!(value instanceof Gtk.Widget)) {
+        return { value: name };
+    }
+
+    registry.register(value);
+
+    return { value: name, widgetId: registry.getOrCreateId(value) };
+}
+
+function representValue(value: unknown, registry: WidgetRegistry): PropertyRepresentation {
+    if (isScalar(value)) {
+        return { value };
+    }
+
+    if (typeof value === "bigint") {
+        return { value: value.toString() };
+    }
+
+    if (Array.isArray(value)) {
+        return { value: value.map(String) };
+    }
+
+    return describeObjectValue(value, registry);
+}
+
+function representNativeProperty(native: NativeProperty, registry: WidgetRegistry): PropertyRepresentation {
+    if (typeIsA(native.type, TYPE_ENUM)) {
+        return { value: GObject.enumToString(native.type, Number(fromValue(native.handle))) };
+    }
+
+    if (typeIsA(native.type, TYPE_FLAGS)) {
+        return { value: GObject.flagsToString(native.type, Number(fromValue(native.handle))) };
+    }
+
+    return representValue(fromValue(native.handle), registry);
+}
+
+function serializeProperty(widget: Gtk.Widget, property: string, registry: WidgetRegistry): SerializedProperty {
+    const native = readNativeProperty(widget, property);
+    const type = typeName(native.type) ?? String(native.type);
+
+    try {
+        return { type, ...representNativeProperty(native, registry) };
+    } catch (error) {
+        return { type, value: null, note: `cannot be represented over MCP: ${errorMessage(error)}` };
+    }
+}
+
+function readWidgetProperties(
+    widget: Gtk.Widget,
+    properties: string[],
+    registry: WidgetRegistry,
+): Record<string, SerializedProperty> {
+    const values: Record<string, SerializedProperty> = {};
+
+    for (const name of properties) {
+        const property = canonicalName(name);
+        requireReadableProperty(widget, property);
+        values[property] = serializeProperty(widget, property, registry);
+    }
+
+    return values;
+}
+
+export { readWidgetProperties };

package/src/refresh-runtime.ts

@@ -1,8 +1,13 @@
-import RefreshRuntime from "react-refresh/runtime";
+import RefreshRuntime, { type Family } from "react-refresh/runtime";
 import "./refresh-globals.js";
 
 type ComponentType = (...args: unknown[]) => unknown;
 
+type PatchedExports = {
+    values: Set<unknown>;
+    families: Set<Family>;
+};
+
 function createModuleRegistration(moduleId: string): {
     $RefreshReg$: (type: ComponentType, id: string) => void;
     $RefreshSig$: typeof RefreshRuntime.createSignatureFunctionForTransform;
@@ -40,8 +45,49 @@ function isRefreshBoundary(moduleExports: Record<string, unknown>): boolean {
     return Object.keys(moduleExports).some((k) => k !== "__esModule");
 }
 
+const exportedFamilies = (moduleExports: Record<string, unknown>): Set<Family> => {
+    const families: Set<Family> = new Set();
+
+    for (const key in moduleExports) {
+        const family = RefreshRuntime.getFamilyByType(moduleExports[key]);
+
+        if (family) {
+            families.add(family);
+        }
+    }
+
+    return families;
+};
+
+const patchedExports = (moduleExports: Record<string, unknown>): PatchedExports => ({
+    values: new Set(Object.values(moduleExports)),
+    families: exportedFamilies(moduleExports),
+});
+
+const isPatchedExport = (patched: PatchedExports, value: unknown): boolean => {
+    if (patched.values.has(value)) {
+        return true;
+    }
+
+    const family = RefreshRuntime.getFamilyByType(value);
+
+    return family !== undefined && patched.families.has(family);
+};
+
+const staleExportName = (previous: Record<string, unknown>, current: Record<string, unknown>): string | null => {
+    const patched = patchedExports(current);
+
+    for (const key in previous) {
+        if (!isPatchedExport(patched, previous[key])) {
+            return key;
+        }
+    }
+
+    return null;
+};
+
 function performRefresh(): void {
     RefreshRuntime.performReactRefresh();
 }
 
-export { createModuleRegistration, isRefreshBoundary, performRefresh };
+export { createModuleRegistration, isRefreshBoundary, performRefresh, staleExportName };

package/src/settings/compile.ts

@@ -1,22 +1,19 @@
-import { formatChildProcessError } from "@gtkx/utils";
-import { execFileSync } from "node:child_process";
-import { resolveCliTool } from "../internal/resolve-cli-tool.js";
+import { runCliTool } from "../internal/run-cli-tool.js";
 
 const SCHEMA_COMPILER = "glib-compile-schemas";
 const SCHEMA_COMPILE_TIMEOUT_MS = 30_000;
 
 const compileSchemas = (dir: string): void => {
-    try {
-        execFileSync(resolveCliTool(SCHEMA_COMPILER), ["--strict", dir], {
+    runCliTool({
+        tool: SCHEMA_COMPILER,
+        args: ["--strict", dir],
+        target: dir,
+        options: {
             stdio: ["ignore", "pipe", "pipe"],
             timeout: SCHEMA_COMPILE_TIMEOUT_MS,
             encoding: "utf8",
-        });
-    } catch (error) {
-        const details = formatChildProcessError(error);
-        const suffix = details ? `:\n${details}` : "";
-        throw new Error(`glib-compile-schemas failed for ${dir}${suffix}`, { cause: error });
-    }
+        },
+    });
 };
 
 export { compileSchemas };

package/src/settings/schema.ts

@@ -164,6 +164,5 @@ export {
     stageSchema,
     findSchemaFiles,
     stageAndCompileProjectSchemas,
-    schemaEnvPath,
     emitSchemaEnv,
 };

package/src/vite-plugins/asset-emitter.ts

@@ -0,0 +1,5 @@
+type AssetEmitter = {
+    emitFile: (file: { type: "asset"; fileName: string; source: Buffer }) => void;
+};
+
+export { type AssetEmitter };