feat: thread image processing (#19)

This PR threads the image processing code in an attempt to reduce the terminal freezing when scrolling past or loading large images

closes to #4

CHANGELOG.md

···
 # Changelog
 
+## v1.1.0 (2025-05-21)
+- fix(images): Improve performance by only locking critical parts of image loading
+- fix(images): Thread the image loading process as not to block user input
+
 ## v1.0.1 (2025-04-14)
 - fix(errors): Ensure logged enums are wrapped in `@tagName()` for readability.
 

PROJECT_BOARD.md

···
 - `[x]` Done
 
 ## Backlog
-- [ ] Improve image reading.
-      Current reading can be slow which pauses users movement if they are simply
-      scrolling past.
 - [ ] Keybind to unzip archives.

build.zig

···
 const builtin = @import("builtin");
 
 ///Must match the `version` in `build.zig.zon`.
-const version = std.SemanticVersion{ .major = 1, .minor = 0, .patch = 1 };
+const version = std.SemanticVersion{ .major = 1, .minor = 1, .patch = 0 };
 
 const targets: []const std.Target.Query = &.{
     .{ .cpu_arch = .aarch64, .os_tag = .macos },

build.zig.zon

···
 .{
     .name = .jido,
     .fingerprint = 0xee45eabe36cafb57,
-    .version = "1.0.1",
+    .version = "1.1.0",
     .minimum_zig_version = "0.14.0",
 
     .dependencies = .{

src/app.zig

···
 };
 
 pub const Event = union(enum) {
+    image_ready,
     key_press: Key,
     winsize: vaxis.Winsize,
 };
···
 should_quit: bool,
 vx: vaxis.Vaxis = undefined,
 tty: vaxis.Tty = undefined,
+loop: vaxis.Loop(Event) = undefined,
 state: State = .normal,
 actions: CircStack(Action, actions_len),
 command_history: CommandHistory = CommandHistory{},
···
 text_input_buf: [std.fs.max_path_bytes]u8 = undefined,
 
 yanked: ?struct { dir: []const u8, entry: std.fs.Dir.Entry } = null,
-image: ?vaxis.Image = null,
 last_known_height: usize,
 
+image: struct {
+    mutex: std.Thread.Mutex = .{},
+    data: ?vaxis.zigimg.Image = null,
+    path: ?[]const u8 = null,
+} = .{},
+
 pub fn init(alloc: std.mem.Allocator) !App {
     var vx = try vaxis.init(alloc, .{
         .kitty_keyboard_flags = .{
···
     var help_menu = List([]const u8).init(alloc);
     try help_menu.fromArray(&help_menu_items);
 
-    return App{
+    var app: App = .{
         .alloc = alloc,
         .should_quit = false,
         .vx = vx,
···
         .actions = CircStack(Action, actions_len).init(),
         .last_known_height = vx.window().height,
     };
+
+    app.loop = vaxis.Loop(Event){
+        .vaxis = &app.vx,
+        .tty = &app.tty,
+    };
+
+    return app;
 }
 
 pub fn deinit(self: *App) void {
···
     self.vx.deinit(self.alloc, self.tty.anyWriter());
     self.tty.deinit();
     if (self.file_logger) |file_logger| file_logger.deinit();
+    if (self.image.path) |path| self.alloc.free(path);
+    if (self.image.data) |data| {
+        var img_data = data;
+        img_data.deinit();
+    }
 }
 
 pub fn inputToSlice(self: *App) []const u8 {
···
 
 pub fn run(self: *App) !void {
     try self.repopulateDirectory("");
-
-    var loop: vaxis.Loop(Event) = .{
-        .vaxis = &self.vx,
-        .tty = &self.tty,
-    };
-    try loop.start();
-    defer loop.stop();
+    try self.loop.start();
+    defer self.loop.stop();
 
     try self.vx.enterAltScreen(self.tty.anyWriter());
     try self.vx.queryTerminal(self.tty.anyWriter(), 1 * std.time.ns_per_s);
+    self.vx.caps.kitty_graphics = true;
 
     while (!self.should_quit) {
-        loop.pollEvent();
-        while (loop.tryEvent()) |event| {
+        self.loop.pollEvent();
+        while (self.loop.tryEvent()) |event| {
             // Global keybinds.
             switch (event) {
                 .key_press => |key| {
···
             // State specific keybinds.
             switch (self.state) {
                 .normal => {
-                    try EventHandlers.handleNormalEvent(self, event, &loop);
+                    try EventHandlers.handleNormalEvent(self, event);
                 },
                 .help_menu => {
                     try EventHandlers.handleHelpMenuEvent(self, event);

src/drawer.zig

···
                 }
                 if (!match) break :unsupported;
 
-                if (std.mem.eql(u8, self.last_item_path, self.current_item_path)) break :unsupported;
+                {
+                    app.image.mutex.lock();
+                    defer app.image.mutex.unlock();
 
-                var image = vaxis.zigimg.Image.fromFilePath(
-                    app.alloc,
-                    self.current_item_path,
-                ) catch {
-                    break :unsupported;
-                };
-                defer image.deinit();
+                    if (std.mem.eql(u8, self.current_item_path, app.image.path orelse "")) {
+                        if (app.image.data == null) break :unsupported;
 
-                if (app.vx.transmitImage(app.alloc, app.tty.anyWriter(), &image, .rgba)) |img| {
-                    app.image = img;
-                } else |_| {
-                    if (app.image) |img| {
-                        app.vx.freeImage(app.tty.anyWriter(), img.id);
-                    }
-                    app.image = null;
-                    break :unsupported;
-                }
-
-                if (app.image) |img| {
-                    img.draw(preview_win, .{ .scale = .contain }) catch |err| {
-                        const message = try std.fmt.allocPrint(app.alloc, "Failed to draw image to screen - {}.", .{err});
-                        defer app.alloc.free(message);
-                        app.notification.write(message, .err) catch {};
-                        if (app.file_logger) |file_logger| file_logger.write(message, .err) catch {};
+                        if (app.vx.transmitImage(app.alloc, app.tty.anyWriter(), &app.image.data.?, .rgba)) |img| {
+                            img.draw(preview_win, .{ .scale = .contain }) catch |err| {
+                                const message = try std.fmt.allocPrint(app.alloc, "Failed to draw image to screen - {}.", .{err});
+                                defer app.alloc.free(message);
+                                app.notification.write(message, .err) catch {};
+                                if (app.file_logger) |file_logger| file_logger.write(message, .err) catch {};
 
-                        _ = preview_win.print(&.{
-                            .{ .text = "Failed to draw image to screen. No preview available." },
-                        }, .{});
+                                _ = preview_win.print(&.{
+                                    .{ .text = "Failed to draw image to screen. No preview available." },
+                                }, .{});
+                            };
+                        } else |_| {
+                            break :unsupported;
+                        }
 
                         break :file;
-                    };
+                    }
+
+                    const path = try app.alloc.dupe(u8, self.current_item_path);
+                    const load_img_thread = std.Thread.spawn(.{}, loadImage, .{
+                        app,
+                        path,
+                    }) catch break :unsupported;
+                    load_img_thread.detach();
                 }
 
                 break :file;
···
         .style = config.styles.notification.box,
     }, .{ .wrap = .word });
 }
+
+fn loadImage(app: *App, path: []const u8) error{ Unsupported, OutOfMemory }!void {
+    const image = vaxis.zigimg.Image.fromFilePath(app.alloc, path) catch {
+        return error.Unsupported;
+    };
+
+    app.image.mutex.lock();
+    if (app.image.data) |data| {
+        var img_data = data;
+        img_data.deinit();
+    }
+    app.image.data = image;
+
+    if (app.image.path) |p| app.alloc.free(p);
+    app.image.path = path;
+    app.image.mutex.unlock();
+
+    app.loop.postEvent(.image_ready);
+}

src/event_handlers.zig

···
 pub fn handleNormalEvent(
     app: *App,
     event: App.Event,
-    loop: *vaxis.Loop(App.Event),
 ) !void {
     switch (event) {
         .key_press => |key| {
···
             } else {
                 switch (key.codepoint) {
                     '-', 'h', Key.left => try events.traverseLeft(app),
-                    Key.enter, 'l', Key.right => try events.traverseRight(app, loop),
+                    Key.enter, 'l', Key.right => try events.traverseRight(app),
                     'j', Key.down => app.directories.entries.next(),
                     'k', Key.up => app.directories.entries.previous(),
                     'u' => try events.undo(app),
···
                 }
             }
         },
+        .image_ready => {},
         .winsize => |ws| try app.vx.resize(app.alloc, app.tty.anyWriter(), ws),
     }
 }
···
                 },
             }
         },
+        .image_ready => {},
         .winsize => |ws| try app.vx.resize(app.alloc, app.tty.anyWriter(), ws),
     }
 }
···
                 else => {},
             }
         },
+        .image_ready => {},
         .winsize => |ws| try app.vx.resize(app.alloc, app.tty.anyWriter(), ws),
     }
 }

src/events.zig

···
     }
 }
 
-pub fn traverseRight(app: *App, loop: *vaxis.Loop(App.Event)) !void {
+pub fn traverseRight(app: *App) !void {
     var message: ?[]const u8 = null;
     defer if (message) |msg| app.alloc.free(msg);
 
···
             if (environment.getEditor()) |editor| {
                 try app.vx.exitAltScreen(app.tty.anyWriter());
                 try app.vx.resetState(app.tty.anyWriter());
-                loop.stop();
+                app.loop.stop();
 
                 environment.openFile(app.alloc, app.directories.dir, entry.name, editor) catch |err| {
                     message = try std.fmt.allocPrint(app.alloc, "Failed to open file '{s}' - {}.", .{ entry.name, err });
···
                     if (app.file_logger) |file_logger| file_logger.write(message.?, .err) catch {};
                 };
 
-                try loop.start();
+                try app.loop.start();
                 try app.vx.enterAltScreen(app.tty.anyWriter());
                 try app.vx.enableDetectedFeatures(app.tty.anyWriter());
                 app.vx.queueRefresh();