@gtkx/vitest 0.20.0 → 1.0.0-rc.1

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,kBAAkB,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAA2C,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAIrG,MAAM,CAAC,MAAM,gBAAgB,GAAa,CAAC,mBAAmB,EAAE,kBAAkB,CAAC,CAAC;AAQpF,MAAM,gBAAgB,GAAG,GAAQ,EAAE;IAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC1G,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC,CAAC;AAEF,MAAM,wBAAwB,GAAG,CAAC,OAA0B,EAAU,EAAE;IACpE,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS;YAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC;AACpB,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,GAAW,EAAE;IACjC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAC7D,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAC;AACtG,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,IAAI,GAAG,CAAC,OAAO,GAAsB,EAAE,EAAU,EAAE,CACrD,kBAAkB,CAAC;IACf,IAAI,EAAE,aAAa;IACnB,MAAM;QACF,OAAO;YACH,IAAI,EAAE;gBACF,OAAO,EAAE,IAAI;gBACb,QAAQ,EAAE,CAAC,UAAU,EAAE,wBAAwB,CAAC,OAAO,CAAC,CAAC;gBACzD,UAAU,EAAE,CAAC,eAAe,EAAE,CAAC;gBAC/B,WAAW,EAAE,KAAK;gBAClB,WAAW,EAAE,KAAK;gBAClB,IAAI,EAAE,OAAO;gBACb,GAAG,EAAE,mBAAmB;gBACxB,MAAM,EAAE;oBACJ,IAAI,EAAE;wBACF,MAAM,EAAE,gBAAgB;qBAC3B;iBACJ;aACJ;SACJ,CAAC;IACN,CAAC;CACJ,CAAC,CAAC;AAEP,eAAe,IAAI,CAAC","sourcesContent":["import { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\n\nimport createConfigPlugin from \"@gtkx/config/vite-plugin\";\nimport type { Plugin } from \"vitest/config\";\nimport { type CompositorId, type HeadlessOptions, STATIC_HEADLESS_ENV } from \"./headless-display.js\";\n\nexport type { CompositorId, HeadlessOptions };\n\nexport const GTKX_INLINE_DEPS: RegExp[] = [/@gtkx\\/(?!native)/, /[/\\\\]\\.gtkx[/\\\\]/];\n\n/**\n * Options accepted by the {@link gtkx} Vitest plugin. Every headless display\n * setting is optional and falls back to a built-in default when omitted.\n */\nexport type GtkxPluginOptions = Partial<HeadlessOptions>;\n\nconst workerPreloadUrl = (): URL => {\n    const sibling = join(import.meta.dirname, \"worker-preload.js\");\n    const path = existsSync(sibling) ? sibling : join(import.meta.dirname, \"..\", \"dist\", \"worker-preload.js\");\n    return pathToFileURL(path);\n};\n\nconst headlessPreloadSpecifier = (options: GtkxPluginOptions): string => {\n    const url = workerPreloadUrl();\n    for (const [key, value] of Object.entries(options)) {\n        if (value !== undefined) url.searchParams.set(key, value);\n    }\n    return url.href;\n};\n\nconst workerSetupPath = (): string => {\n    const sibling = join(import.meta.dirname, \"worker-setup.js\");\n    return existsSync(sibling) ? sibling : join(import.meta.dirname, \"..\", \"dist\", \"worker-setup.js\");\n};\n\n/**\n * Vitest plugin that runs each test worker against its own isolated headless\n * Wayland display. It configures the forks pool, injects the worker preload and\n * setup files, and sets the environment needed for headless GTK4 rendering.\n *\n * @param options Headless display settings (size, compositor) forwarded to each worker.\n * @returns A Vitest config plugin.\n */\nconst gtkx = (options: GtkxPluginOptions = {}): Plugin =>\n    createConfigPlugin({\n        name: \"gtkx:vitest\",\n        config() {\n            return {\n                test: {\n                    globals: true,\n                    execArgv: [\"--import\", headlessPreloadSpecifier(options)],\n                    setupFiles: [workerSetupPath()],\n                    testTimeout: 30000,\n                    hookTimeout: 30000,\n                    pool: \"forks\",\n                    env: STATIC_HEADLESS_ENV,\n                    server: {\n                        deps: {\n                            inline: GTKX_INLINE_DEPS,\n                        },\n                    },\n                },\n            };\n        },\n    });\n\nexport default gtkx;\n"]}

package/dist/notification-service.d.ts

@@ -0,0 +1,2 @@
+export declare const startNotificationService: (busAddress: string) => Promise<() => void>;
+//# sourceMappingURL=notification-service.d.ts.map

package/dist/notification-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-service.d.ts","sourceRoot":"","sources":["../src/notification-service.ts"],"names":[],"mappings":"AAyCA,eAAO,MAAM,wBAAwB,eAAsB,MAAM,KAAG,OAAO,CAAC,MAAM,IAAI,CAYrF,CAAC"}

package/dist/notification-service.js

@@ -0,0 +1,47 @@
+/// <reference path="./dbus-native.d.ts" />
+import { EventEmitter } from "node:events";
+import { sessionBus } from "@homebridge/dbus-native";
+const NOTIFICATIONS_NAME = "org.freedesktop.Notifications";
+const NOTIFICATIONS_PATH = "/org/freedesktop/Notifications";
+const DESCRIPTOR = {
+    name: NOTIFICATIONS_NAME,
+    methods: {
+        Notify: [
+            "susssasa{sv}i",
+            "u",
+            ["app_name", "replaces_id", "app_icon", "summary", "body", "actions", "hints", "expire_timeout"],
+            ["id"],
+        ],
+        CloseNotification: ["u", "", ["id"], []],
+        GetCapabilities: ["", "as", [], ["capabilities"]],
+    },
+    signals: {
+        NotificationClosed: ["uu", "id", "reason"],
+        ActionInvoked: ["us", "id", "action_key"],
+    },
+};
+class NotificationService extends EventEmitter {
+    lastId = 0;
+    Notify() {
+        this.lastId += 1;
+        return this.lastId;
+    }
+    CloseNotification() { }
+    GetCapabilities() {
+        return ["body", "actions"];
+    }
+}
+export const startNotificationService = async (busAddress) => {
+    const bus = sessionBus({ busAddress });
+    bus.exportInterface(new NotificationService(), NOTIFICATIONS_PATH, DESCRIPTOR);
+    await new Promise((resolve, reject) => {
+        bus.requestName(NOTIFICATIONS_NAME, 0, (error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+    return () => bus.connection.stream.destroy();
+};
+//# sourceMappingURL=notification-service.js.map

package/dist/notification-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-service.js","sourceRoot":"","sources":["../src/notification-service.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAA4B,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE/E,MAAM,kBAAkB,GAAG,+BAA+B,CAAC;AAC3D,MAAM,kBAAkB,GAAG,gCAAgC,CAAC;AAE5D,MAAM,UAAU,GAAwB;IACpC,IAAI,EAAE,kBAAkB;IACxB,OAAO,EAAE;QACL,MAAM,EAAE;YACJ,eAAe;YACf,GAAG;YACH,CAAC,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,CAAC;YAChG,CAAC,IAAI,CAAC;SACT;QACD,iBAAiB,EAAE,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QACxC,eAAe,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC;KACpD;IACD,OAAO,EAAE;QACL,kBAAkB,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC;QAC1C,aAAa,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,YAAY,CAAC;KAC5C;CACJ,CAAC;AAEF,MAAM,mBAAoB,SAAQ,YAAY;IAClC,MAAM,GAAG,CAAC,CAAC;IAEnB,MAAM;QACF,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,iBAAiB,KAAU,CAAC;IAE5B,eAAe;QACX,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC/B,CAAC;CACJ;AAED,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,EAAE,UAAkB,EAAuB,EAAE;IACtF,MAAM,GAAG,GAAG,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;IACvC,GAAG,CAAC,eAAe,CAAC,IAAI,mBAAmB,EAAE,EAAE,kBAAkB,EAAE,UAAU,CAAC,CAAC;IAE/E,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,GAAG,CAAC,WAAW,CAAC,kBAAkB,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE;YAC7C,IAAI,KAAK;gBAAE,MAAM,CAAC,KAAK,CAAC,CAAC;;gBACpB,OAAO,EAAE,CAAC;QACnB,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;IAEH,OAAO,GAAG,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;AACjD,CAAC,CAAC","sourcesContent":["/// <reference path=\"./dbus-native.d.ts\" />\n\nimport { EventEmitter } from \"node:events\";\nimport { type InterfaceDescriptor, sessionBus } from \"@homebridge/dbus-native\";\n\nconst NOTIFICATIONS_NAME = \"org.freedesktop.Notifications\";\nconst NOTIFICATIONS_PATH = \"/org/freedesktop/Notifications\";\n\nconst DESCRIPTOR: InterfaceDescriptor = {\n    name: NOTIFICATIONS_NAME,\n    methods: {\n        Notify: [\n            \"susssasa{sv}i\",\n            \"u\",\n            [\"app_name\", \"replaces_id\", \"app_icon\", \"summary\", \"body\", \"actions\", \"hints\", \"expire_timeout\"],\n            [\"id\"],\n        ],\n        CloseNotification: [\"u\", \"\", [\"id\"], []],\n        GetCapabilities: [\"\", \"as\", [], [\"capabilities\"]],\n    },\n    signals: {\n        NotificationClosed: [\"uu\", \"id\", \"reason\"],\n        ActionInvoked: [\"us\", \"id\", \"action_key\"],\n    },\n};\n\nclass NotificationService extends EventEmitter {\n    private lastId = 0;\n\n    Notify(): number {\n        this.lastId += 1;\n        return this.lastId;\n    }\n\n    CloseNotification(): void {}\n\n    GetCapabilities(): string[] {\n        return [\"body\", \"actions\"];\n    }\n}\n\nexport const startNotificationService = async (busAddress: string): Promise<() => void> => {\n    const bus = sessionBus({ busAddress });\n    bus.exportInterface(new NotificationService(), NOTIFICATIONS_PATH, DESCRIPTOR);\n\n    await new Promise<void>((resolve, reject) => {\n        bus.requestName(NOTIFICATIONS_NAME, 0, (error) => {\n            if (error) reject(error);\n            else resolve();\n        });\n    });\n\n    return () => bus.connection.stream.destroy();\n};\n"]}

package/dist/worker-preload.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worker-preload.d.ts.map

package/dist/worker-preload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-preload.d.ts","sourceRoot":"","sources":["../src/worker-preload.ts"],"names":[],"mappings":""}

package/dist/worker-preload.js

@@ -0,0 +1,6 @@
+import { readHeadlessOptions, resolveHeadlessOptions, startHeadlessDisplay } from "./headless-display.js";
+const options = readHeadlessOptions(new URL(import.meta.url).searchParams);
+const teardown = await startHeadlessDisplay(resolveHeadlessOptions(options));
+process.on("exit", teardown);
+globalThis.gtkxHeadlessTeardown = teardown;
+//# sourceMappingURL=worker-preload.js.map

package/dist/worker-preload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-preload.js","sourceRoot":"","sources":["../src/worker-preload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE1G,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,GAAG,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;AAC3E,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC;AAE7E,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAC7B,UAAU,CAAC,oBAAoB,GAAG,QAAQ,CAAC","sourcesContent":["import { readHeadlessOptions, resolveHeadlessOptions, startHeadlessDisplay } from \"./headless-display.js\";\n\nconst options = readHeadlessOptions(new URL(import.meta.url).searchParams);\nconst teardown = await startHeadlessDisplay(resolveHeadlessOptions(options));\n\nprocess.on(\"exit\", teardown);\nglobalThis.gtkxHeadlessTeardown = teardown;\n"]}

package/dist/worker-setup.d.ts

@@ -0,0 +1,6 @@
+declare global {
+    var gtkxHeadlessTeardown: (() => void) | undefined;
+    var gtkxHeadlessShutdownInstalled: boolean | undefined;
+}
+export declare const installHeadlessShutdown: () => void;
+//# sourceMappingURL=worker-setup.d.ts.map

package/dist/worker-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-setup.d.ts","sourceRoot":"","sources":["../src/worker-setup.ts"],"names":[],"mappings":"AAEA,OAAO,CAAC,MAAM,CAAC;IACX,IAAI,oBAAoB,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IACnD,IAAI,6BAA6B,EAAE,OAAO,GAAG,SAAS,CAAC;CAC1D;AAED,eAAO,MAAM,uBAAuB,QAAO,IAK1C,CAAC"}

package/dist/worker-setup.js

@@ -0,0 +1,10 @@
+import { installGracefulShutdown } from "@gtkx/utils";
+export const installHeadlessShutdown = () => {
+    const teardown = globalThis.gtkxHeadlessTeardown;
+    if (teardown === undefined || globalThis.gtkxHeadlessShutdownInstalled === true)
+        return;
+    globalThis.gtkxHeadlessShutdownInstalled = true;
+    installGracefulShutdown({ onSignal: teardown });
+};
+installHeadlessShutdown();
+//# sourceMappingURL=worker-setup.js.map

package/dist/worker-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-setup.js","sourceRoot":"","sources":["../src/worker-setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAOtD,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAS,EAAE;IAC9C,MAAM,QAAQ,GAAG,UAAU,CAAC,oBAAoB,CAAC;IACjD,IAAI,QAAQ,KAAK,SAAS,IAAI,UAAU,CAAC,6BAA6B,KAAK,IAAI;QAAE,OAAO;IACxF,UAAU,CAAC,6BAA6B,GAAG,IAAI,CAAC;IAChD,uBAAuB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;AACpD,CAAC,CAAC;AAEF,uBAAuB,EAAE,CAAC","sourcesContent":["import { installGracefulShutdown } from \"@gtkx/utils\";\n\ndeclare global {\n    var gtkxHeadlessTeardown: (() => void) | undefined;\n    var gtkxHeadlessShutdownInstalled: boolean | undefined;\n}\n\nexport const installHeadlessShutdown = (): void => {\n    const teardown = globalThis.gtkxHeadlessTeardown;\n    if (teardown === undefined || globalThis.gtkxHeadlessShutdownInstalled === true) return;\n    globalThis.gtkxHeadlessShutdownInstalled = true;\n    installGracefulShutdown({ onSignal: teardown });\n};\n\ninstallHeadlessShutdown();\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gtkx/vitest",
-  "version": "0.20.0",
-  "description": "Vitest plugin for GTKX applications with Xvfb display isolation",
+  "version": "1.0.0-rc.1",
+  "description": "Vitest plugin for GTKX applications with headless Wayland display isolation",
   "keywords": [
     "gtkx",
     "gtk",
@@ -9,7 +9,7 @@
     "vitest",
     "testing",
     "plugin",
-    "xvfb",
+    "wayland",
     "linux",
     "desktop"
   ],
@@ -19,7 +19,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/gtkx-org/gtkx.git",
+    "url": "git+https://github.com/gtkx-org/gtkx.git",
     "directory": "packages/vitest"
   },
   "license": "MPL-2.0",
@@ -37,14 +37,23 @@
     "dist",
     "src"
   ],
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@homebridge/dbus-native": "^0.7.7",
+    "@gtkx/config": "1.0.0-rc.1",
+    "@gtkx/utils": "1.0.0-rc.1"
+  },
   "devDependencies": {
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "vitest": ">=4"
   },
   "scripts": {
-    "build": "tsc -b && cp ../../README.md .",
-    "typecheck": "tsc -b --emitDeclarationOnly"
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -b --emitDeclarationOnly",
+    "release": "tsx ../../scripts/release-package.ts"
   }
 }

package/src/dbus-native.d.ts

@@ -0,0 +1,17 @@
+import "@homebridge/dbus-native";
+
+declare module "@homebridge/dbus-native" {
+    export type InterfaceDescriptor = {
+        name: string;
+        methods: { [member: string]: [string, string, string[], string[]] };
+        signals?: { [member: string]: [string, ...string[]] };
+        properties?: { [name: string]: string };
+    };
+
+    export interface MessageBus {
+        exportInterface(implementation: object, path: string, descriptor: InterfaceDescriptor): void;
+        requestName(name: string, flags: number, callback: (error: Error | null, result?: number) => void): void;
+    }
+
+    export function sessionBus(options?: { busAddress?: string }): MessageBus;
+}

package/src/headless-display.ts

@@ -0,0 +1,330 @@
+import { type ChildProcess, type StdioOptions, spawn, spawnSync } from "node:child_process";
+import { chmodSync, createWriteStream, existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { Socket } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { startNotificationService } from "./notification-service.js";
+
+/**
+ * Wayland compositors that can back a headless display.
+ */
+export type CompositorId = "sway" | "weston";
+
+export const DEFAULT_HEADLESS_SIZE = "1024x768";
+
+/**
+ * Settings for the per-worker headless Wayland display.
+ */
+export type HeadlessOptions = {
+    /** Output resolution as a "WIDTHxHEIGHT" string, for example "1024x768". */
+    size: string;
+    /** Wayland compositor used to back the headless display. */
+    compositor: CompositorId;
+};
+
+const DEFAULT_HEADLESS_COMPOSITOR: CompositorId = "weston";
+
+export const resolveHeadlessOptions = (provided: Partial<HeadlessOptions>): HeadlessOptions => ({
+    size: provided.size ?? DEFAULT_HEADLESS_SIZE,
+    compositor: provided.compositor ?? DEFAULT_HEADLESS_COMPOSITOR,
+});
+
+type EnvSnapshot = { [name: string]: string | undefined };
+
+const applyEnv = (snapshot: EnvSnapshot, values: { [name: string]: string }): void => {
+    for (const [name, value] of Object.entries(values)) {
+        if (!(name in snapshot)) snapshot[name] = process.env[name];
+        process.env[name] = value;
+    }
+};
+
+const restoreEnv = (snapshot: EnvSnapshot): void => {
+    for (const [name, previous] of Object.entries(snapshot)) {
+        if (previous === undefined) delete process.env[name];
+        else process.env[name] = previous;
+    }
+};
+
+const spawnWithParentDeathSignal = (command: string, args: string[], stdio: StdioOptions): ChildProcess => {
+    const child = spawn("setpriv", ["--pdeathsig", "SIGKILL", command, ...args], { stdio });
+    child.unref();
+    return child;
+};
+
+let westonFakeSeatSupport: boolean | undefined;
+
+const westonSupportsFakeSeat = (): boolean => {
+    if (westonFakeSeatSupport === undefined) {
+        const help = spawnSync("weston", ["--help"], { encoding: "utf8" });
+        westonFakeSeatSupport = `${help.stdout}${help.stderr}`.includes("--fake-seat");
+    }
+    return westonFakeSeatSupport;
+};
+
+type CompositorDescriptor = {
+    socket: string;
+    env: { [name: string]: string };
+    start: (runtimeDir: string, width: string, height: string) => ChildProcess;
+};
+
+const compositorRegistry: { [K in CompositorId]: CompositorDescriptor } = {
+    sway: {
+        socket: "wayland-1",
+        env: {
+            WLR_BACKENDS: "headless",
+            WLR_RENDERER: "pixman",
+            WLR_RENDERER_ALLOW_SOFTWARE: "1",
+            WLR_LIBINPUT_NO_DEVICES: "1",
+            WLR_HEADLESS_OUTPUTS: "1",
+        },
+        start: (runtimeDir, width, height) => {
+            const configPath = join(runtimeDir, "sway.conf");
+            writeFileSync(
+                configPath,
+                [
+                    "xwayland disable",
+                    "default_border none",
+                    "default_floating_border none",
+                    `output HEADLESS-1 resolution ${width}x${height}`,
+                    "output HEADLESS-1 bg #000000 solid_color",
+                    'for_window [app_id=".*"] floating enable, border none',
+                    'for_window [title=".*"] floating enable, border none',
+                    "",
+                ].join("\n"),
+            );
+            return spawnWithParentDeathSignal("sway", ["-c", configPath], ["ignore", "ignore", "pipe"]);
+        },
+    },
+    weston: {
+        socket: "wayland-0",
+        env: {},
+        start: (_runtimeDir, width, height) =>
+            spawnWithParentDeathSignal(
+                "weston",
+                [
+                    "--backend=headless",
+                    "--renderer=pixman",
+                    ...(westonSupportsFakeSeat() ? ["--fake-seat"] : []),
+                    `--width=${width}`,
+                    `--height=${height}`,
+                    "--socket=wayland-0",
+                ],
+                ["ignore", "ignore", "pipe"],
+            ),
+    },
+};
+
+const isCompositorId = (value: string): value is CompositorId => Object.hasOwn(compositorRegistry, value);
+
+export const readHeadlessOptions = (params: URLSearchParams): Partial<HeadlessOptions> => {
+    const options: Partial<HeadlessOptions> = {};
+    const size = params.get("size");
+    if (size !== null) options.size = size;
+    const compositor = params.get("compositor");
+    if (compositor !== null && isCompositorId(compositor)) options.compositor = compositor;
+    return options;
+};
+
+type SpawnedCompositor = {
+    child: ChildProcess;
+    socket: string;
+};
+
+const startCompositor = (runtimeDir: string, options: HeadlessOptions, env: EnvSnapshot): SpawnedCompositor => {
+    const descriptor = compositorRegistry[options.compositor];
+
+    const [width = "", height = ""] = options.size.split("x");
+    applyEnv(env, descriptor.env);
+
+    return { child: descriptor.start(runtimeDir, width, height), socket: descriptor.socket };
+};
+
+const writeBusConfig = (busConfigPath: string, busSocketPath: string): void => {
+    writeFileSync(
+        busConfigPath,
+        `<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
+<busconfig>
+  <type>session</type>
+  <listen>unix:path=${busSocketPath}</listen>
+  <auth>EXTERNAL</auth>
+  <policy context="default">
+    <allow send_destination="*" eavesdrop="true"/>
+    <allow eavesdrop="true"/>
+    <allow own="*"/>
+  </policy>
+</busconfig>`,
+    );
+};
+
+type WaitForSocketOptions = {
+    label: string;
+    timeout?: number;
+    child?: ChildProcess;
+    signal?: AbortSignal;
+};
+
+const waitForSocket = (path: string, { label, timeout = 15000, child, signal }: WaitForSocketOptions): Promise<void> =>
+    new Promise((resolve, reject) => {
+        let log = "";
+        const stderr = child?.stderr ?? null;
+        stderr?.setEncoding("utf8");
+        stderr?.on("data", (chunk: string) => {
+            log += chunk;
+        });
+        let timer: ReturnType<typeof setTimeout>;
+        let poll: ReturnType<typeof setInterval>;
+        const stopListening = (): void => {
+            clearTimeout(timer);
+            clearInterval(poll);
+            child?.removeListener("exit", onExit);
+            child?.removeListener("error", onError);
+            signal?.removeEventListener("abort", onAbort);
+            stderr?.removeAllListeners("data");
+            stderr?.resume();
+            if (stderr instanceof Socket) stderr.unref();
+        };
+        const onExit = (code: number | null, terminationSignal: NodeJS.Signals | null): void => {
+            stopListening();
+            reject(
+                new Error(
+                    `${label} exited (code ${code ?? "null"}, signal ${terminationSignal ?? "null"}) before ${path} appeared\n${log}`,
+                ),
+            );
+        };
+        const onError = (cause: Error): void => {
+            stopListening();
+            reject(new Error(`${label} failed to spawn: ${cause.message}\n${log}`));
+        };
+        const onAbort = (): void => {
+            stopListening();
+            reject(new Error(`${label} startup aborted before ${path} appeared`));
+        };
+        poll = setInterval(() => {
+            if (existsSync(path)) {
+                stopListening();
+                resolve();
+            }
+        }, 50);
+        timer = setTimeout(() => {
+            stopListening();
+            const suffix = child ? `\n${log}` : "";
+            reject(new Error(`${label} did not become available within ${timeout}ms${suffix}`));
+        }, timeout);
+        child?.on("exit", onExit);
+        child?.on("error", onError);
+        if (signal) {
+            if (signal.aborted) {
+                onAbort();
+                return;
+            }
+            signal.addEventListener("abort", onAbort);
+        }
+    });
+
+export const STATIC_HEADLESS_ENV = {
+    GDK_BACKEND: "wayland",
+    GDK_DISABLE: "vulkan",
+    GDK_DEBUG: "no-vsync",
+    GSK_RENDERER: "cairo",
+    GTK_A11Y: "test",
+    LIBGL_ALWAYS_SOFTWARE: "1",
+    GST_GL_WINDOW: "none",
+    GSETTINGS_BACKEND: "memory",
+    ALSOFT_DRIVERS: "null",
+    ALSOFT_LOGLEVEL: "0",
+};
+
+const captureCompositorStderr = (child: ChildProcess, logPath: string): string[] => {
+    const captured: string[] = [];
+    const stderr = child.stderr;
+    if (stderr !== null) {
+        stderr.setEncoding("utf8");
+        const logStream = createWriteStream(logPath);
+        logStream.on("error", () => {});
+        stderr.on("data", (chunk: string) => {
+            captured.push(chunk);
+            logStream.write(chunk);
+        });
+    }
+    return captured;
+};
+
+const reportUnexpectedCompositorExit = (child: ChildProcess, capturedStderr: string[]): void => {
+    if (child.exitCode === null && child.signalCode === null) return;
+    process.stderr.write(
+        `[gtkx] headless compositor died before teardown (code ${child.exitCode ?? "null"}, ` +
+            `signal ${child.signalCode ?? "null"}); the worker's Wayland client was severed.\n${capturedStderr.join("")}`,
+    );
+};
+
+const makeTeardown = (
+    compositor: ChildProcess,
+    capturedStderr: string[],
+    stopNotifications: () => void,
+    removeRuntime: () => void,
+): (() => void) => {
+    let torndown = false;
+    return (): void => {
+        if (torndown) return;
+        torndown = true;
+        reportUnexpectedCompositorExit(compositor, capturedStderr);
+        stopNotifications();
+        removeRuntime();
+    };
+};
+
+export const startHeadlessDisplay = async (options: HeadlessOptions): Promise<() => void> => {
+    const env: EnvSnapshot = {};
+    const runtimeDir = mkdtempSync(join(tmpdir(), "gtkx-xdg-"));
+    chmodSync(runtimeDir, 0o700);
+    const spawned: ChildProcess[] = [];
+
+    const removeRuntime = (): void => {
+        restoreEnv(env);
+        rmSync(runtimeDir, { recursive: true, force: true });
+    };
+
+    try {
+        applyEnv(env, { XDG_RUNTIME_DIR: runtimeDir });
+
+        const busConfigPath = join(runtimeDir, "session.conf");
+        const busSocketPath = join(runtimeDir, "bus");
+        writeBusConfig(busConfigPath, busSocketPath);
+
+        const busChild = spawnWithParentDeathSignal(
+            "dbus-daemon",
+            [`--config-file=${busConfigPath}`],
+            ["ignore", "ignore", "pipe"],
+        );
+        spawned.push(busChild);
+        applyEnv(env, { DBUS_SESSION_BUS_ADDRESS: `unix:path=${busSocketPath}` });
+
+        const compositor = startCompositor(runtimeDir, options, env);
+        spawned.push(compositor.child);
+
+        applyEnv(env, { WAYLAND_DISPLAY: compositor.socket });
+
+        const abort = new AbortController();
+        try {
+            await Promise.all([
+                waitForSocket(join(runtimeDir, compositor.socket), {
+                    label: "Compositor",
+                    child: compositor.child,
+                    signal: abort.signal,
+                }),
+                waitForSocket(busSocketPath, { label: "D-Bus session bus", child: busChild, signal: abort.signal }),
+            ]);
+        } finally {
+            abort.abort();
+        }
+
+        const stopNotifications = await startNotificationService(`unix:path=${busSocketPath}`);
+
+        const capturedStderr = captureCompositorStderr(compositor.child, join(runtimeDir, "weston.stderr.log"));
+        return makeTeardown(compositor.child, capturedStderr, stopNotifications, removeRuntime);
+    } catch (cause) {
+        for (const child of spawned) child.kill("SIGKILL");
+        removeRuntime();
+        throw cause;
+    }
+};

package/src/index.ts

@@ -1 +1,69 @@
-export { default } from "./plugin.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import createConfigPlugin from "@gtkx/config/vite-plugin";
+import type { Plugin } from "vitest/config";
+import { type CompositorId, type HeadlessOptions, STATIC_HEADLESS_ENV } from "./headless-display.js";
+
+export type { CompositorId, HeadlessOptions };
+
+export const GTKX_INLINE_DEPS: RegExp[] = [/@gtkx\/(?!native)/, /[/\\]\.gtkx[/\\]/];
+
+/**
+ * Options accepted by the {@link gtkx} Vitest plugin. Every headless display
+ * setting is optional and falls back to a built-in default when omitted.
+ */
+export type GtkxPluginOptions = Partial<HeadlessOptions>;
+
+const workerPreloadUrl = (): URL => {
+    const sibling = join(import.meta.dirname, "worker-preload.js");
+    const path = existsSync(sibling) ? sibling : join(import.meta.dirname, "..", "dist", "worker-preload.js");
+    return pathToFileURL(path);
+};
+
+const headlessPreloadSpecifier = (options: GtkxPluginOptions): string => {
+    const url = workerPreloadUrl();
+    for (const [key, value] of Object.entries(options)) {
+        if (value !== undefined) url.searchParams.set(key, value);
+    }
+    return url.href;
+};
+
+const workerSetupPath = (): string => {
+    const sibling = join(import.meta.dirname, "worker-setup.js");
+    return existsSync(sibling) ? sibling : join(import.meta.dirname, "..", "dist", "worker-setup.js");
+};
+
+/**
+ * Vitest plugin that runs each test worker against its own isolated headless
+ * Wayland display. It configures the forks pool, injects the worker preload and
+ * setup files, and sets the environment needed for headless GTK4 rendering.
+ *
+ * @param options Headless display settings (size, compositor) forwarded to each worker.
+ * @returns A Vitest config plugin.
+ */
+const gtkx = (options: GtkxPluginOptions = {}): Plugin =>
+    createConfigPlugin({
+        name: "gtkx:vitest",
+        config() {
+            return {
+                test: {
+                    globals: true,
+                    execArgv: ["--import", headlessPreloadSpecifier(options)],
+                    setupFiles: [workerSetupPath()],
+                    testTimeout: 30000,
+                    hookTimeout: 30000,
+                    pool: "forks",
+                    env: STATIC_HEADLESS_ENV,
+                    server: {
+                        deps: {
+                            inline: GTKX_INLINE_DEPS,
+                        },
+                    },
+                },
+            };
+        },
+    });
+
+export default gtkx;

package/src/notification-service.ts

@@ -0,0 +1,54 @@
+/// <reference path="./dbus-native.d.ts" />
+
+import { EventEmitter } from "node:events";
+import { type InterfaceDescriptor, sessionBus } from "@homebridge/dbus-native";
+
+const NOTIFICATIONS_NAME = "org.freedesktop.Notifications";
+const NOTIFICATIONS_PATH = "/org/freedesktop/Notifications";
+
+const DESCRIPTOR: InterfaceDescriptor = {
+    name: NOTIFICATIONS_NAME,
+    methods: {
+        Notify: [
+            "susssasa{sv}i",
+            "u",
+            ["app_name", "replaces_id", "app_icon", "summary", "body", "actions", "hints", "expire_timeout"],
+            ["id"],
+        ],
+        CloseNotification: ["u", "", ["id"], []],
+        GetCapabilities: ["", "as", [], ["capabilities"]],
+    },
+    signals: {
+        NotificationClosed: ["uu", "id", "reason"],
+        ActionInvoked: ["us", "id", "action_key"],
+    },
+};
+
+class NotificationService extends EventEmitter {
+    private lastId = 0;
+
+    Notify(): number {
+        this.lastId += 1;
+        return this.lastId;
+    }
+
+    CloseNotification(): void {}
+
+    GetCapabilities(): string[] {
+        return ["body", "actions"];
+    }
+}
+
+export const startNotificationService = async (busAddress: string): Promise<() => void> => {
+    const bus = sessionBus({ busAddress });
+    bus.exportInterface(new NotificationService(), NOTIFICATIONS_PATH, DESCRIPTOR);
+
+    await new Promise<void>((resolve, reject) => {
+        bus.requestName(NOTIFICATIONS_NAME, 0, (error) => {
+            if (error) reject(error);
+            else resolve();
+        });
+    });
+
+    return () => bus.connection.stream.destroy();
+};

package/src/worker-preload.ts

@@ -0,0 +1,7 @@
+import { readHeadlessOptions, resolveHeadlessOptions, startHeadlessDisplay } from "./headless-display.js";
+
+const options = readHeadlessOptions(new URL(import.meta.url).searchParams);
+const teardown = await startHeadlessDisplay(resolveHeadlessOptions(options));
+
+process.on("exit", teardown);
+globalThis.gtkxHeadlessTeardown = teardown;