usecomputer 0.0.4 → 0.1.0

package/zig/src/lib.zig

@@ -1,4 +1,4 @@
-// Native N-API module for usecomputer commands on macOS using Zig.
+// Native N-API module for usecomputer desktop automation commands.
 // Exports direct typed methods (no string command dispatcher) so TS can call
 // high-level native functions and receive structured error objects.
 
@@ -6,7 +6,12 @@ const std = @import("std");
 const builtin = @import("builtin");
 const scroll_impl = @import("scroll.zig");
 const window = @import("window.zig");
-const napigen = if (builtin.is_test) undefined else @import("napigen");
+// napigen is only available when building as N-API library.
+// The build system provides a "napigen" module for the library target but not
+// for the standalone exe or test targets. We detect availability at comptime
+// via the build options module.
+const build_options = @import("build_options");
+const napigen = if (build_options.enable_napigen) @import("napigen") else undefined;
 const c_macos = if (builtin.target.os.tag == .macos) @cImport({
     @cInclude("CoreGraphics/CoreGraphics.h");
     @cInclude("CoreFoundation/CoreFoundation.h");
@@ -19,8 +24,13 @@ const c_windows = if (builtin.target.os.tag == .windows) @cImport({
 
 const c_x11 = if (builtin.target.os.tag == .linux) @cImport({
     @cInclude("X11/Xlib.h");
+    @cInclude("X11/Xutil.h");
     @cInclude("X11/keysym.h");
+    @cInclude("X11/extensions/XShm.h");
     @cInclude("X11/extensions/XTest.h");
+    @cInclude("sys/ipc.h");
+    @cInclude("sys/shm.h");
+    @cInclude("png.h");
 }) else struct {};
 
 const c = c_macos;
@@ -191,7 +201,7 @@ fn todoNotImplemented(command: []const u8) CommandResult {
     return failCommand(command, "TODO_NOT_IMPLEMENTED", "TODO not implemented");
 }
 
-const Point = struct {
+pub const Point = struct {
     x: f64,
     y: f64,
 };
@@ -221,7 +231,7 @@ const DragInput = struct {
     button: ?[]const u8 = null,
 };
 
-const ScreenshotRegion = struct {
+pub const ScreenshotRegion = struct {
     x: f64,
     y: f64,
     width: f64,
@@ -236,7 +246,7 @@ const ScreenshotInput = struct {
     annotate: ?bool = null,
 };
 
-const ScreenshotOutput = struct {
+pub const ScreenshotOutput = struct {
     path: []const u8,
     desktopIndex: f64,
     captureX: f64,
@@ -247,25 +257,51 @@ const ScreenshotOutput = struct {
     imageHeight: f64,
 };
 
-const SelectedDisplay = struct {
+const SelectedDisplay = if (builtin.target.os.tag == .macos) struct {
     id: c.CGDirectDisplayID,
     index: usize,
     bounds: c.CGRect,
+} else struct {
+    id: u32,
+    index: usize,
+    bounds: struct {
+        x: f64,
+        y: f64,
+        width: f64,
+        height: f64,
+    },
 };
 
-const ScreenshotCapture = struct {
+const ScreenshotCapture = if (builtin.target.os.tag == .macos) struct {
     image: c.CGImageRef,
     capture_x: f64,
     capture_y: f64,
     capture_width: f64,
     capture_height: f64,
     desktop_index: usize,
+} else struct {
+    image: RawRgbaImage,
+    capture_x: f64,
+    capture_y: f64,
+    capture_width: f64,
+    capture_height: f64,
+    desktop_index: usize,
 };
 
-const ScaledScreenshotImage = struct {
+const ScaledScreenshotImage = if (builtin.target.os.tag == .macos) struct {
     image: c.CGImageRef,
     width: f64,
     height: f64,
+} else struct {
+    image: RawRgbaImage,
+    width: f64,
+    height: f64,
+};
+
+const RawRgbaImage = struct {
+    pixels: []u8,
+    width: usize,
+    height: usize,
 };
 
 const TypeTextInput = struct {
@@ -290,13 +326,50 @@ const ClipboardSetInput = struct {
 };
 
 pub fn screenshot(input: ScreenshotInput) DataResult(ScreenshotOutput) {
-    if (builtin.target.os.tag != .macos) {
-        return failData(ScreenshotOutput, "screenshot", "UNSUPPORTED_PLATFORM", "screenshot is only supported on macOS");
-    }
-
     _ = input.annotate;
     const output_path = input.path orelse "./screenshot.png";
 
+    if (builtin.target.os.tag == .linux) {
+        if (input.window != null) {
+            return failData(ScreenshotOutput, "screenshot", "UNSUPPORTED_INPUT", "window screenshots are not supported on Linux yet");
+        }
+
+        const capture = createLinuxScreenshotImage(.{
+            .display_index = input.display,
+            .region = input.region,
+        }) catch |err| {
+            return failData(ScreenshotOutput, "screenshot", linuxScreenshotErrorCode(err), linuxScreenshotErrorMessage(err));
+        };
+        defer std.heap.c_allocator.free(capture.image.pixels);
+
+        const scaled_image = scaleLinuxScreenshotImageIfNeeded(capture.image) catch {
+            return failData(ScreenshotOutput, "screenshot", "SCALE_FAILED", "failed to scale screenshot image");
+        };
+        defer std.heap.c_allocator.free(scaled_image.image.pixels);
+
+        writeLinuxScreenshotPng(.{
+            .image = scaled_image.image,
+            .output_path = output_path,
+        }) catch {
+            return failData(ScreenshotOutput, "screenshot", "WRITE_FAILED", "failed to write screenshot file");
+        };
+
+        return okData(ScreenshotOutput, .{
+            .path = output_path,
+            .desktopIndex = @floatFromInt(capture.desktop_index),
+            .captureX = capture.capture_x,
+            .captureY = capture.capture_y,
+            .captureWidth = capture.capture_width,
+            .captureHeight = capture.capture_height,
+            .imageWidth = scaled_image.width,
+            .imageHeight = scaled_image.height,
+        });
+    }
+
+    if (builtin.target.os.tag != .macos) {
+        return failData(ScreenshotOutput, "screenshot", "UNSUPPORTED_PLATFORM", "screenshot is only supported on macOS and Linux X11");
+    }
+
     const capture = createScreenshotImage(.{
         .display_index = input.display,
         .window_id = input.window,
@@ -330,11 +403,388 @@ pub fn screenshot(input: ScreenshotInput) DataResult(ScreenshotOutput) {
     });
 }
 
-pub fn click(input: ClickInput) CommandResult {
-    if (builtin.target.os.tag != .macos) {
-        return failCommand("click", "UNSUPPORTED_PLATFORM", "click is only supported on macOS");
+fn linuxScreenshotErrorCode(err: anyerror) []const u8 {
+    return switch (err) {
+        error.InvalidDisplayIndex, error.InvalidRegion, error.RegionOutOfBounds => "INVALID_INPUT",
+        error.DisplayOpenFailed, error.MissingDisplayEnv, error.NoScreens, error.XShmUnavailable => "X11_UNAVAILABLE",
+        error.CaptureFailed, error.ImageCreateFailed, error.ShmGetFailed, error.ShmAttachFailed, error.ShmAllocFailed => "CAPTURE_FAILED",
+        else => "CAPTURE_FAILED",
+    };
+}
+
+fn linuxScreenshotErrorMessage(err: anyerror) []const u8 {
+    return switch (err) {
+        error.InvalidDisplayIndex => "Linux screenshots currently support only display 0",
+        error.InvalidRegion => "invalid screenshot region",
+        error.RegionOutOfBounds => "screenshot region is outside the X11 root window bounds",
+        error.MissingDisplayEnv => "DISPLAY is not set; Linux screenshots require an X11 session",
+        error.DisplayOpenFailed => "failed to open X11 display",
+        error.NoScreens => "X11 display has no screens",
+        error.XShmUnavailable => "X11 shared memory extension is unavailable",
+        error.ImageCreateFailed, error.ShmAllocFailed, error.ShmAttachFailed, error.ShmGetFailed, error.CaptureFailed => "failed to capture screenshot image",
+        else => "failed to capture screenshot image",
+    };
+}
+
+fn createLinuxScreenshotImage(input: struct {
+    display_index: ?f64,
+    region: ?ScreenshotRegion,
+}) !ScreenshotCapture {
+    if (builtin.target.os.tag != .linux) {
+        return error.UnsupportedPlatform;
     }
+    if (input.display_index) |value| {
+        const normalized = @as(i64, @intFromFloat(std.math.round(value)));
+        if (normalized != 0) {
+            return error.InvalidDisplayIndex;
+        }
+    }
+    if (std.posix.getenv("DISPLAY") == null) {
+        return error.MissingDisplayEnv;
+    }
+
+    const display = c_x11.XOpenDisplay(null) orelse return error.DisplayOpenFailed;
+    defer _ = c_x11.XCloseDisplay(display);
+
+    const screen_index = c_x11.XDefaultScreen(display);
+    if (screen_index < 0) {
+        return error.NoScreens;
+    }
+    const root = c_x11.XRootWindow(display, screen_index);
+    const screen_width_i = c_x11.XDisplayWidth(display, screen_index);
+    const screen_height_i = c_x11.XDisplayHeight(display, screen_index);
+    if (screen_width_i <= 0 or screen_height_i <= 0) {
+        return error.CaptureFailed;
+    }
+
+    const screen_width = @as(usize, @intCast(screen_width_i));
+    const screen_height = @as(usize, @intCast(screen_height_i));
+    const capture_rect = try resolveLinuxCaptureRect(.{
+        .screen_width = screen_width,
+        .screen_height = screen_height,
+        .region = input.region,
+    });
+
+    // Try XShm first (fast), fall back to XGetImage (slow but always works).
+    // XShm fails on XWayland when processes don't share SHM namespaces.
+    const image = captureWithXShm(display, screen_index, root, capture_rect) orelse
+        captureWithXGetImage(display, root, capture_rect) orelse
+        return error.CaptureFailed;
+    // XDestroyImage is a C macro: ((*((ximage)->f.destroy_image))((ximage)))
+    // Zig's @cImport can't translate it, so call the function pointer directly.
+    defer _ = image.*.f.destroy_image.?(image);
+
+    const rgba = try convertX11ImageToRgba(image, capture_rect.width, capture_rect.height);
+    return .{
+        .image = rgba,
+        .capture_x = @floatFromInt(capture_rect.x),
+        .capture_y = @floatFromInt(capture_rect.y),
+        .capture_width = @floatFromInt(capture_rect.width),
+        .capture_height = @floatFromInt(capture_rect.height),
+        .desktop_index = 0,
+    };
+}
+
+const LinuxCaptureRect = struct {
+    x: usize,
+    y: usize,
+    width: usize,
+    height: usize,
+};
+
+// X error handler state for detecting X errors during screenshot capture.
+// XSetErrorHandler is process-global, so this is necessarily a global.
+var x_capture_error_occurred: bool = false;
+
+fn captureErrorHandler(_: ?*c_x11.Display, _: ?*c_x11.XErrorEvent) callconv(.c) c_int {
+    x_capture_error_occurred = true;
+    return 0;
+}
+
+/// Fast screenshot path using XShm (shared memory). Returns null if XShm is
+/// unavailable or fails (common on XWayland with different SHM namespaces).
+fn captureWithXShm(
+    display: *c_x11.Display,
+    screen_index: c_int,
+    root: c_x11.Window,
+    capture_rect: LinuxCaptureRect,
+) ?*c_x11.XImage {
+    if (c_x11.XShmQueryExtension(display) == 0) {
+        return null;
+    }
+
+    const visual = c_x11.XDefaultVisual(display, screen_index);
+    const depth = @as(c_uint, @intCast(c_x11.XDefaultDepth(display, screen_index)));
+    var shm_info: c_x11.XShmSegmentInfo = undefined;
+    shm_info.shmid = -1;
+    shm_info.shmaddr = null;
+    shm_info.readOnly = 0;
+
+    const image = c_x11.XShmCreateImage(
+        display,
+        visual,
+        depth,
+        c_x11.ZPixmap,
+        null,
+        &shm_info,
+        @as(c_uint, @intCast(capture_rect.width)),
+        @as(c_uint, @intCast(capture_rect.height)),
+    ) orelse return null;
+
+    const bytes_per_image = @as(usize, @intCast(image.*.bytes_per_line)) * capture_rect.height;
+    const shmget_result = c_x11.shmget(c_x11.IPC_PRIVATE, bytes_per_image, c_x11.IPC_CREAT | 0o600);
+    if (shmget_result < 0) {
+        image.*.data = null;
+        _ = image.*.f.destroy_image.?(image);
+        return null;
+    }
+    shm_info.shmid = shmget_result;
+
+    const shmaddr = c_x11.shmat(shm_info.shmid, null, 0);
+    if (@intFromPtr(shmaddr) == std.math.maxInt(usize)) {
+        _ = c_x11.shmctl(shm_info.shmid, c_x11.IPC_RMID, null);
+        image.*.data = null;
+        _ = image.*.f.destroy_image.?(image);
+        return null;
+    }
+    shm_info.shmaddr = @ptrCast(shmaddr);
+    image.*.data = shm_info.shmaddr;
+
+    // Install custom error handler to catch BadAccess from XShmAttach
+    // (happens on XWayland when SHM namespaces don't match).
+    x_capture_error_occurred = false;
+    const old_handler = c_x11.XSetErrorHandler(captureErrorHandler);
+
+    _ = c_x11.XShmAttach(display, &shm_info);
+    _ = c_x11.XSync(display, 0);
+
+    if (x_capture_error_occurred) {
+        // Restore original handler and clean up
+        _ = c_x11.XSetErrorHandler(old_handler);
+        _ = c_x11.shmdt(shmaddr);
+        _ = c_x11.shmctl(shm_info.shmid, c_x11.IPC_RMID, null);
+        image.*.data = null;
+        _ = image.*.f.destroy_image.?(image);
+        return null;
+    }
+
+    if (c_x11.XShmGetImage(
+        display,
+        root,
+        image,
+        @as(c_int, @intCast(capture_rect.x)),
+        @as(c_int, @intCast(capture_rect.y)),
+        c_x11.AllPlanes,
+    ) == 0) {
+        _ = c_x11.XSetErrorHandler(old_handler);
+        _ = c_x11.XShmDetach(display, &shm_info);
+        _ = c_x11.shmdt(shmaddr);
+        _ = c_x11.shmctl(shm_info.shmid, c_x11.IPC_RMID, null);
+        image.*.data = null;
+        _ = image.*.f.destroy_image.?(image);
+        return null;
+    }
+
+    // Copy image data to a separate allocation so we can detach SHM.
+    // The caller owns the XImage and will free it via destroy_image.
+    const data_copy = std.heap.c_allocator.alloc(u8, bytes_per_image) catch {
+        _ = c_x11.XSetErrorHandler(old_handler);
+        _ = c_x11.XShmDetach(display, &shm_info);
+        _ = c_x11.shmdt(shmaddr);
+        _ = c_x11.shmctl(shm_info.shmid, c_x11.IPC_RMID, null);
+        image.*.data = null;
+        _ = image.*.f.destroy_image.?(image);
+        return null;
+    };
+    @memcpy(data_copy, @as([*]const u8, @ptrCast(shmaddr))[0..bytes_per_image]);
+    image.*.data = @ptrCast(data_copy.ptr);
 
+    _ = c_x11.XSetErrorHandler(old_handler);
+    _ = c_x11.XShmDetach(display, &shm_info);
+    _ = c_x11.shmdt(shmaddr);
+    _ = c_x11.shmctl(shm_info.shmid, c_x11.IPC_RMID, null);
+
+    return image;
+}
+
+/// Slow but reliable fallback: XGetImage copies pixels over the X connection.
+/// Works everywhere including XWayland regardless of SHM namespace.
+/// Installs a temporary X error handler to catch BadMatch errors (common
+/// on XWayland when the capture region doesn't match the root drawable).
+fn captureWithXGetImage(
+    display: *c_x11.Display,
+    root: c_x11.Window,
+    capture_rect: LinuxCaptureRect,
+) ?*c_x11.XImage {
+    x_capture_error_occurred = false;
+    const old_handler = c_x11.XSetErrorHandler(captureErrorHandler);
+    defer _ = c_x11.XSetErrorHandler(old_handler);
+
+    const image = c_x11.XGetImage(
+        display,
+        root,
+        @as(c_int, @intCast(capture_rect.x)),
+        @as(c_int, @intCast(capture_rect.y)),
+        @as(c_uint, @intCast(capture_rect.width)),
+        @as(c_uint, @intCast(capture_rect.height)),
+        c_x11.AllPlanes,
+        c_x11.ZPixmap,
+    );
+    _ = c_x11.XSync(display, 0);
+
+    if (x_capture_error_occurred) {
+        if (image) |img| {
+            _ = img.*.f.destroy_image.?(img);
+        }
+        return null;
+    }
+    return image;
+}
+
+fn resolveLinuxCaptureRect(input: struct {
+    screen_width: usize,
+    screen_height: usize,
+    region: ?ScreenshotRegion,
+}) !LinuxCaptureRect {
+    if (input.region) |region| {
+        const x = @as(i64, @intFromFloat(std.math.round(region.x)));
+        const y = @as(i64, @intFromFloat(std.math.round(region.y)));
+        const width = @as(i64, @intFromFloat(std.math.round(region.width)));
+        const height = @as(i64, @intFromFloat(std.math.round(region.height)));
+        if (x < 0 or y < 0 or width <= 0 or height <= 0) {
+            return error.InvalidRegion;
+        }
+        const max_x = x + width;
+        const max_y = y + height;
+        if (max_x > input.screen_width or max_y > input.screen_height) {
+            return error.RegionOutOfBounds;
+        }
+        return .{
+            .x = @as(usize, @intCast(x)),
+            .y = @as(usize, @intCast(y)),
+            .width = @as(usize, @intCast(width)),
+            .height = @as(usize, @intCast(height)),
+        };
+    }
+
+    return .{
+        .x = 0,
+        .y = 0,
+        .width = input.screen_width,
+        .height = input.screen_height,
+    };
+}
+
+fn convertX11ImageToRgba(image: *c_x11.XImage, width: usize, height: usize) !RawRgbaImage {
+    const pixels = try std.heap.c_allocator.alloc(u8, width * height * 4);
+    errdefer std.heap.c_allocator.free(pixels);
+
+    var y: usize = 0;
+    while (y < height) : (y += 1) {
+        var x: usize = 0;
+        while (x < width) : (x += 1) {
+            // XGetPixel is a C macro: ((*((ximage)->f.get_pixel))((ximage), (x), (y)))
+            const pixel = image.*.f.get_pixel.?(image, @as(c_int, @intCast(x)), @as(c_int, @intCast(y)));
+            const red = normalizeX11Channel(.{ .pixel = pixel, .mask = image.*.red_mask });
+            const green = normalizeX11Channel(.{ .pixel = pixel, .mask = image.*.green_mask });
+            const blue = normalizeX11Channel(.{ .pixel = pixel, .mask = image.*.blue_mask });
+            const offset = (y * width + x) * 4;
+            pixels[offset] = red;
+            pixels[offset + 1] = green;
+            pixels[offset + 2] = blue;
+            pixels[offset + 3] = 255;
+        }
+    }
+
+    return .{ .pixels = pixels, .width = width, .height = height };
+}
+
+fn normalizeX11Channel(input: struct {
+    pixel: c_ulong,
+    mask: c_ulong,
+}) u8 {
+    if (input.mask == 0) {
+        return 0;
+    }
+    // @ctz returns u7 on 64-bit c_ulong (aarch64-linux), but >> needs u6.
+    // The shift can't exceed 63 since mask != 0 and is at most 64 bits.
+    const shift: std.math.Log2Int(c_ulong) = @intCast(@ctz(input.mask));
+    const bits: std.math.Log2Int(c_ulong) = @intCast(@min(@popCount(input.mask), @bitSizeOf(c_ulong) - 1));
+    const raw = (input.pixel & input.mask) >> shift;
+    const max_value = (@as(u64, 1) << @intCast(bits)) - 1;
+    if (max_value == 0) {
+        return 0;
+    }
+    return @as(u8, @intCast((raw * 255) / max_value));
+}
+
+fn scaleLinuxScreenshotImageIfNeeded(image: RawRgbaImage) !ScaledScreenshotImage {
+    const image_width = @as(f64, @floatFromInt(image.width));
+    const image_height = @as(f64, @floatFromInt(image.height));
+    const long_edge = @max(image_width, image_height);
+    if (long_edge <= screenshot_max_long_edge_px) {
+        const copy = try std.heap.c_allocator.dupe(u8, image.pixels);
+        return .{
+            .image = .{ .pixels = copy, .width = image.width, .height = image.height },
+            .width = image_width,
+            .height = image_height,
+        };
+    }
+
+    const scale = screenshot_max_long_edge_px / long_edge;
+    const target_width = @max(1, @as(usize, @intFromFloat(std.math.round(image_width * scale))));
+    const target_height = @max(1, @as(usize, @intFromFloat(std.math.round(image_height * scale))));
+    const scaled_pixels = try std.heap.c_allocator.alloc(u8, target_width * target_height * 4);
+    errdefer std.heap.c_allocator.free(scaled_pixels);
+
+    var y: usize = 0;
+    while (y < target_height) : (y += 1) {
+        const source_y = @min(image.height - 1, @as(usize, @intFromFloat((@as(f64, @floatFromInt(y)) * image_height) / @as(f64, @floatFromInt(target_height)))));
+        var x: usize = 0;
+        while (x < target_width) : (x += 1) {
+            const source_x = @min(image.width - 1, @as(usize, @intFromFloat((@as(f64, @floatFromInt(x)) * image_width) / @as(f64, @floatFromInt(target_width)))));
+            const source_offset = (source_y * image.width + source_x) * 4;
+            const target_offset = (y * target_width + x) * 4;
+            @memcpy(scaled_pixels[target_offset .. target_offset + 4], image.pixels[source_offset .. source_offset + 4]);
+        }
+    }
+
+    return .{
+        .image = .{ .pixels = scaled_pixels, .width = target_width, .height = target_height },
+        .width = @floatFromInt(target_width),
+        .height = @floatFromInt(target_height),
+    };
+}
+
+fn writeLinuxScreenshotPng(input: struct {
+    image: RawRgbaImage,
+    output_path: []const u8,
+}) !void {
+    var png: c_x11.png_image = std.mem.zeroes(c_x11.png_image);
+    png.version = c_x11.PNG_IMAGE_VERSION;
+    png.width = @as(c_x11.png_uint_32, @intCast(input.image.width));
+    png.height = @as(c_x11.png_uint_32, @intCast(input.image.height));
+    png.format = c_x11.PNG_FORMAT_RGBA;
+
+    const output_path_z = try std.heap.c_allocator.dupeZ(u8, input.output_path);
+    defer std.heap.c_allocator.free(output_path_z);
+
+    const write_result = c_x11.png_image_write_to_file(
+        &png,
+        output_path_z.ptr,
+        0,
+        input.image.pixels.ptr,
+        @as(c_int, @intCast(input.image.width * 4)),
+        null,
+    );
+    if (write_result == 0) {
+        c_x11.png_image_free(&png);
+        return error.PngWriteFailed;
+    }
+    c_x11.png_image_free(&png);
+}
+
+pub fn click(input: ClickInput) CommandResult {
     const click_count: u32 = if (input.count) |count| blk: {
         const normalized = @as(i64, @intFromFloat(std.math.round(count)));
         if (normalized <= 0) {
@@ -347,40 +797,86 @@ pub fn click(input: ClickInput) CommandResult {
         return failCommand("click", "INVALID_INPUT", "invalid click button");
     };
 
-    const point: c.CGPoint = .{
-        .x = input.point.x,
-        .y = input.point.y,
-    };
+    switch (builtin.target.os.tag) {
+        .macos => {
+            const point: c.CGPoint = .{
+                .x = input.point.x,
+                .y = input.point.y,
+            };
 
-    var index: u32 = 0;
-    while (index < click_count) : (index += 1) {
-        const click_state = @as(i64, @intCast(index + 1));
-        postClickPair(point, button_kind, click_state) catch {
-            return failCommand("click", "EVENT_POST_FAILED", "failed to post click event");
-        };
+            var index: u32 = 0;
+            while (index < click_count) : (index += 1) {
+                const click_state = @as(i64, @intCast(index + 1));
+                postClickPair(point, button_kind, click_state) catch {
+                    return failCommand("click", "EVENT_POST_FAILED", "failed to post click event");
+                };
 
-        if (index + 1 < click_count) {
-            std.Thread.sleep(80 * std.time.ns_per_ms);
-        }
-    }
+                if (index + 1 < click_count) {
+                    std.Thread.sleep(80 * std.time.ns_per_ms);
+                }
+            }
 
-    return okCommand();
+            return okCommand();
+        },
+        .linux => {
+            const display = openX11Display() catch {
+                return failCommand("click", "EVENT_POST_FAILED", "failed to open X11 display");
+            };
+            defer _ = c_x11.XCloseDisplay(display);
+
+            moveCursorToPointX11(.{ .x = input.point.x, .y = input.point.y }, display) catch {
+                return failCommand("click", "EVENT_POST_FAILED", "failed to move mouse cursor");
+            };
+
+            var index: u32 = 0;
+            while (index < click_count) : (index += 1) {
+                postClickPairX11(.{ .x = input.point.x, .y = input.point.y }, button_kind, display) catch {
+                    return failCommand("click", "EVENT_POST_FAILED", "failed to post click event");
+                };
+
+                if (index + 1 < click_count) {
+                    std.Thread.sleep(80 * std.time.ns_per_ms);
+                }
+            }
+
+            _ = c_x11.XFlush(display);
+            return okCommand();
+        },
+        else => {
+            return failCommand("click", "UNSUPPORTED_PLATFORM", "click is unsupported on this platform");
+        },
+    }
 }
 
 pub fn mouseMove(input: MouseMoveInput) CommandResult {
-    if (builtin.target.os.tag != .macos) {
-        return failCommand("mouse-move", "UNSUPPORTED_PLATFORM", "mouse-move is only supported on macOS");
-    }
+    switch (builtin.target.os.tag) {
+        .macos => {
+            const point: c.CGPoint = .{
+                .x = input.x,
+                .y = input.y,
+            };
+            moveCursorToPoint(point) catch {
+                return failCommand("mouse-move", "EVENT_POST_FAILED", "failed to move mouse cursor");
+            };
 
-    const point: c.CGPoint = .{
-        .x = input.x,
-        .y = input.y,
-    };
-    moveCursorToPoint(point) catch {
-        return failCommand("mouse-move", "EVENT_POST_FAILED", "failed to move mouse cursor");
-    };
+            return okCommand();
+        },
+        .linux => {
+            const display = openX11Display() catch {
+                return failCommand("mouse-move", "EVENT_POST_FAILED", "failed to open X11 display");
+            };
+            defer _ = c_x11.XCloseDisplay(display);
 
-    return okCommand();
+            moveCursorToPointX11(.{ .x = input.x, .y = input.y }, display) catch {
+                return failCommand("mouse-move", "EVENT_POST_FAILED", "failed to move mouse cursor");
+            };
+            _ = c_x11.XFlush(display);
+            return okCommand();
+        },
+        else => {
+            return failCommand("mouse-move", "UNSUPPORTED_PLATFORM", "mouse-move is unsupported on this platform");
+        },
+    }
 }
 
 pub fn mouseDown(input: MouseButtonInput) CommandResult {
@@ -395,35 +891,66 @@ fn handleMouseButtonInput(args: struct {
     input: MouseButtonInput,
     is_down: bool,
 }) CommandResult {
-    if (builtin.target.os.tag != .macos) {
-        return failCommand("mouse-button", "UNSUPPORTED_PLATFORM", "mouse button events are only supported on macOS");
-    }
-
     const button_kind = resolveMouseButton(args.input.button orelse "left") catch {
         return failCommand("mouse-button", "INVALID_INPUT", "invalid mouse button");
     };
 
-    const point = currentCursorPoint() catch {
-        return failCommand("mouse-button", "CURSOR_READ_FAILED", "failed to read cursor position");
-    };
+    switch (builtin.target.os.tag) {
+        .macos => {
+            const point = currentCursorPoint() catch {
+                return failCommand("mouse-button", "CURSOR_READ_FAILED", "failed to read cursor position");
+            };
 
-    postMouseButtonEvent(point, button_kind, args.is_down, 1) catch {
-        return failCommand("mouse-button", "EVENT_POST_FAILED", "failed to post mouse button event");
-    };
+            postMouseButtonEvent(point, button_kind, args.is_down, 1) catch {
+                return failCommand("mouse-button", "EVENT_POST_FAILED", "failed to post mouse button event");
+            };
 
-    return okCommand();
+            return okCommand();
+        },
+        .linux => {
+            const display = openX11Display() catch {
+                return failCommand("mouse-button", "EVENT_POST_FAILED", "failed to open X11 display");
+            };
+            defer _ = c_x11.XCloseDisplay(display);
+
+            postMouseButtonEventX11(button_kind, args.is_down, display) catch {
+                return failCommand("mouse-button", "EVENT_POST_FAILED", "failed to post mouse button event");
+            };
+            _ = c_x11.XFlush(display);
+
+            return okCommand();
+        },
+        else => {
+            return failCommand("mouse-button", "UNSUPPORTED_PLATFORM", "mouse button events are unsupported on this platform");
+        },
+    }
 }
 
 pub fn mousePosition() DataResult(Point) {
-    if (builtin.target.os.tag != .macos) {
-        return failData(Point, "mouse-position", "UNSUPPORTED_PLATFORM", "mouse-position is only supported on macOS");
-    }
+    switch (builtin.target.os.tag) {
+        .macos => {
+            const point = currentCursorPoint() catch {
+                return failData(Point, "mouse-position", "CURSOR_READ_FAILED", "failed to read cursor position");
+            };
 
-    const point = currentCursorPoint() catch {
-        return failData(Point, "mouse-position", "CURSOR_READ_FAILED", "failed to read cursor position");
-    };
+            return okData(Point, .{ .x = std.math.round(point.x), .y = std.math.round(point.y) });
+        },
+        .linux => {
+            const display = openX11Display() catch {
+                return failData(Point, "mouse-position", "EVENT_POST_FAILED", "failed to open X11 display");
+            };
+            defer _ = c_x11.XCloseDisplay(display);
+
+            const point = currentCursorPointX11(display) catch {
+                return failData(Point, "mouse-position", "CURSOR_READ_FAILED", "failed to read cursor position");
+            };
 
-    return okData(Point, .{ .x = std.math.round(point.x), .y = std.math.round(point.y) });
+            return okData(Point, .{ .x = @floatFromInt(point.x), .y = @floatFromInt(point.y) });
+        },
+        else => {
+            return failData(Point, "mouse-position", "UNSUPPORTED_PLATFORM", "mouse-position is unsupported on this platform");
+        },
+    }
 }
 
 pub fn hover(input: Point) CommandResult {
@@ -431,25 +958,9 @@ pub fn hover(input: Point) CommandResult {
 }
 
 pub fn drag(input: DragInput) CommandResult {
-    if (builtin.target.os.tag != .macos) {
-        return failCommand("drag", "UNSUPPORTED_PLATFORM", "drag is only supported on macOS");
-    }
-
     const button_kind = resolveMouseButton(input.button orelse "left") catch {
         return failCommand("drag", "INVALID_INPUT", "invalid drag button");
     };
-
-    const from: c.CGPoint = .{ .x = input.from.x, .y = input.from.y };
-    const to: c.CGPoint = .{ .x = input.to.x, .y = input.to.y };
-
-    moveCursorToPoint(from) catch {
-        return failCommand("drag", "EVENT_POST_FAILED", "failed to move cursor to drag origin");
-    };
-
-    postMouseButtonEvent(from, button_kind, true, 1) catch {
-        return failCommand("drag", "EVENT_POST_FAILED", "failed to post drag mouse-down");
-    };
-
     const duration_ms = if (input.durationMs) |value| blk: {
         const normalized = @as(i64, @intFromFloat(std.math.round(value)));
         if (normalized <= 0) {
@@ -461,33 +972,152 @@ pub fn drag(input: DragInput) CommandResult {
     const step_count: u64 = 16;
     const step_duration_ns = if (step_count == 0) 0 else total_duration_ns / step_count;
 
-    var index: u64 = 1;
-    while (index <= step_count) : (index += 1) {
-        const fraction = @as(f64, @floatFromInt(index)) / @as(f64, @floatFromInt(step_count));
-        const next_point: c.CGPoint = .{
-            .x = from.x + (to.x - from.x) * fraction,
-            .y = from.y + (to.y - from.y) * fraction,
+    switch (builtin.target.os.tag) {
+        .macos => {
+            const from: c.CGPoint = .{ .x = input.from.x, .y = input.from.y };
+            const to: c.CGPoint = .{ .x = input.to.x, .y = input.to.y };
+
+            moveCursorToPoint(from) catch {
+                return failCommand("drag", "EVENT_POST_FAILED", "failed to move cursor to drag origin");
+            };
+
+            postMouseButtonEvent(from, button_kind, true, 1) catch {
+                return failCommand("drag", "EVENT_POST_FAILED", "failed to post drag mouse-down");
+            };
+
+            var index: u64 = 1;
+            while (index <= step_count) : (index += 1) {
+                const fraction = @as(f64, @floatFromInt(index)) / @as(f64, @floatFromInt(step_count));
+                const next_point: c.CGPoint = .{
+                    .x = from.x + (to.x - from.x) * fraction,
+                    .y = from.y + (to.y - from.y) * fraction,
+                };
+
+                moveCursorToPoint(next_point) catch {
+                    return failCommand("drag", "EVENT_POST_FAILED", "failed during drag cursor movement");
+                };
+
+                if (step_duration_ns > 0 and index < step_count) {
+                    std.Thread.sleep(step_duration_ns);
+                }
+            }
+
+            postMouseButtonEvent(to, button_kind, false, 1) catch {
+                return failCommand("drag", "EVENT_POST_FAILED", "failed to post drag mouse-up");
+            };
+
+            return okCommand();
+        },
+        .linux => {
+            const display = openX11Display() catch {
+                return failCommand("drag", "EVENT_POST_FAILED", "failed to open X11 display");
+            };
+            defer _ = c_x11.XCloseDisplay(display);
+
+            moveCursorToPointX11(.{ .x = input.from.x, .y = input.from.y }, display) catch {
+                return failCommand("drag", "EVENT_POST_FAILED", "failed to move cursor to drag origin");
+            };
+
+            postMouseButtonEventX11(button_kind, true, display) catch {
+                return failCommand("drag", "EVENT_POST_FAILED", "failed to post drag mouse-down");
+            };
+
+            var index: u64 = 1;
+            while (index <= step_count) : (index += 1) {
+                const fraction = @as(f64, @floatFromInt(index)) / @as(f64, @floatFromInt(step_count));
+                const next_point = Point{
+                    .x = input.from.x + (input.to.x - input.from.x) * fraction,
+                    .y = input.from.y + (input.to.y - input.from.y) * fraction,
+                };
+
+                moveCursorToPointX11(next_point, display) catch {
+                    return failCommand("drag", "EVENT_POST_FAILED", "failed during drag cursor movement");
+                };
+
+                if (step_duration_ns > 0 and index < step_count) {
+                    std.Thread.sleep(step_duration_ns);
+                }
+            }
+
+            postMouseButtonEventX11(button_kind, false, display) catch {
+                return failCommand("drag", "EVENT_POST_FAILED", "failed to post drag mouse-up");
+            };
+            _ = c_x11.XFlush(display);
+
+            return okCommand();
+        },
+        else => {
+            return failCommand("drag", "UNSUPPORTED_PLATFORM", "drag is unsupported on this platform");
+        },
+    }
+}
+
+pub fn displayList() DataResult([]const u8) {
+    if (builtin.target.os.tag == .linux) {
+        const display = openX11Display() catch {
+            return failData([]const u8, "display-list", "DISPLAY_QUERY_FAILED", "failed to open X11 display");
         };
+        defer _ = c_x11.XCloseDisplay(display);
 
-        moveCursorToPoint(next_point) catch {
-            return failCommand("drag", "EVENT_POST_FAILED", "failed during drag cursor movement");
+        const screen_count: usize = @intCast(c_x11.XScreenCount(display));
+        if (screen_count == 0) {
+            return failData([]const u8, "display-list", "DISPLAY_QUERY_FAILED", "failed to query active displays");
+        }
+
+        const primary_screen = c_x11.XDefaultScreen(display);
+
+        var write_buffer: [32 * 1024]u8 = undefined;
+        var stream = std.io.fixedBufferStream(&write_buffer);
+        const writer = stream.writer();
+
+        writer.writeByte('[') catch {
+            return failData([]const u8, "display-list", "SERIALIZE_FAILED", "failed to serialize display list");
         };
 
-        if (step_duration_ns > 0 and index < step_count) {
-            std.Thread.sleep(step_duration_ns);
+        var i: usize = 0;
+        while (i < screen_count) : (i += 1) {
+            if (i > 0) {
+                writer.writeByte(',') catch {
+                    return failData([]const u8, "display-list", "SERIALIZE_FAILED", "failed to serialize display list");
+                };
+            }
+
+            var name_buffer: [64]u8 = undefined;
+            const display_name = std.fmt.bufPrint(&name_buffer, "Display {d}", .{i}) catch "Display";
+            const screen_index: c_int = @intCast(i);
+            const root = c_x11.XRootWindow(display, screen_index);
+            const width = c_x11.XDisplayWidth(display, screen_index);
+            const height = c_x11.XDisplayHeight(display, screen_index);
+
+            const item = DisplayInfoOutput{
+                .id = @as(u32, @truncate(@as(u64, @intCast(root)))),
+                .index = @intCast(i),
+                .name = display_name,
+                .x = 0,
+                .y = 0,
+                .width = @floatFromInt(width),
+                .height = @floatFromInt(height),
+                .scale = 1,
+                .isPrimary = screen_index == primary_screen,
+            };
+
+            writer.print("{f}", .{std.json.fmt(item, .{})}) catch {
+                return failData([]const u8, "display-list", "SERIALIZE_FAILED", "failed to serialize display list");
+            };
         }
-    }
 
-    postMouseButtonEvent(to, button_kind, false, 1) catch {
-        return failCommand("drag", "EVENT_POST_FAILED", "failed to post drag mouse-up");
-    };
+        writer.writeByte(']') catch {
+            return failData([]const u8, "display-list", "SERIALIZE_FAILED", "failed to serialize display list");
+        };
 
-    return okCommand();
-}
+        const payload = std.heap.c_allocator.dupe(u8, stream.getWritten()) catch {
+            return failData([]const u8, "display-list", "ALLOC_FAILED", "failed to allocate display list response");
+        };
+        return okData([]const u8, payload);
+    }
 
-pub fn displayList() DataResult([]const u8) {
     if (builtin.target.os.tag != .macos) {
-        return failData([]const u8, "display-list", "UNSUPPORTED_PLATFORM", "display-list is only supported on macOS");
+        return failData([]const u8, "display-list", "UNSUPPORTED_PLATFORM", "display-list is unsupported on this platform");
     }
 
     var display_ids: [16]c.CGDirectDisplayID = undefined;
@@ -1458,6 +2088,81 @@ fn moveCursorToPoint(point: c.CGPoint) !void {
     c.CGEventPost(c.kCGHIDEventTap, move_event);
 }
 
+fn openX11Display() !*c_x11.Display {
+    if (builtin.target.os.tag != .linux) {
+        return error.UnsupportedPlatform;
+    }
+    return c_x11.XOpenDisplay(null) orelse error.XOpenDisplayFailed;
+}
+
+fn resolveX11ButtonCode(button: MouseButtonKind) c_uint {
+    return switch (button) {
+        .left => 1,
+        .middle => 2,
+        .right => 3,
+    };
+}
+
+fn normalizedCoordinate(value: f64) !c_int {
+    if (!std.math.isFinite(value)) {
+        return error.InvalidPoint;
+    }
+    const rounded = @as(i64, @intFromFloat(std.math.round(value)));
+    if (rounded < std.math.minInt(c_int) or rounded > std.math.maxInt(c_int)) {
+        return error.InvalidPoint;
+    }
+    return @as(c_int, @intCast(rounded));
+}
+
+fn moveCursorToPointX11(point: Point, display: *c_x11.Display) !void {
+    const x = try normalizedCoordinate(point.x);
+    const y = try normalizedCoordinate(point.y);
+    _ = c_x11.XWarpPointer(display, 0, c_x11.XDefaultRootWindow(display), 0, 0, 0, 0, x, y);
+}
+
+fn postMouseButtonEventX11(button: MouseButtonKind, is_down: bool, display: *c_x11.Display) !void {
+    const button_code = resolveX11ButtonCode(button);
+    const press_state: c_int = if (is_down) c_x11.True else c_x11.False;
+    const posted = c_x11.XTestFakeButtonEvent(display, button_code, press_state, c_x11.CurrentTime);
+    if (posted == 0) {
+        return error.EventPostFailed;
+    }
+}
+
+fn postClickPairX11(point: Point, button: MouseButtonKind, display: *c_x11.Display) !void {
+    try moveCursorToPointX11(point, display);
+    try postMouseButtonEventX11(button, true, display);
+    try postMouseButtonEventX11(button, false, display);
+}
+
+fn currentCursorPointX11(display: *c_x11.Display) !struct { x: c_int, y: c_int } {
+    const root_window = c_x11.XDefaultRootWindow(display);
+    var root_return: c_x11.Window = 0;
+    var child_return: c_x11.Window = 0;
+    var root_x: c_int = 0;
+    var root_y: c_int = 0;
+    var win_x: c_int = 0;
+    var win_y: c_int = 0;
+    var mask_return: c_uint = 0;
+
+    const ok = c_x11.XQueryPointer(
+        display,
+        root_window,
+        &root_return,
+        &child_return,
+        &root_x,
+        &root_y,
+        &win_x,
+        &win_y,
+        &mask_return,
+    );
+    if (ok == 0) {
+        return error.CursorReadFailed;
+    }
+
+    return .{ .x = root_x, .y = root_y };
+}
+
 fn initModule(js: *napigen.JsContext, exports: napigen.napi_value) !napigen.napi_value {
     try js.setNamedProperty(exports, "screenshot", try js.createFunction(screenshot));
     try js.setNamedProperty(exports, "click", try js.createFunction(click));
@@ -1478,7 +2183,7 @@ fn initModule(js: *napigen.JsContext, exports: napigen.napi_value) !napigen.napi
 }
 
 comptime {
-    if (!builtin.is_test) {
+    if (build_options.enable_napigen) {
         napigen.defineModule(initModule);
     }
 }