linecraft 0.1.0

package/src/zig/test_buffer.zig

@@ -0,0 +1,82 @@
+const std = @import("std");
+const buffer = @import("buffer.zig");
+const testing = std.testing;
+
+test "Buffer: initialization" {
+    const stdout = std.fs.File{ .handle = 1 }; // stdout handle
+    var buf = buffer.RenderBuffer.init(testing.allocator, stdout);
+    defer buf.deinit();
+
+    try testing.expect(buf.data.items.len == 0);
+    std.debug.print("  ✓ Buffer initialized\n", .{});
+}
+
+test "Buffer: write" {
+    const stdout = std.fs.File{ .handle = 1 }; // stdout handle
+    var buf = buffer.RenderBuffer.init(testing.allocator, stdout);
+    defer buf.deinit();
+
+    try buf.write("hello");
+    try buf.write(" world");
+
+    try testing.expectEqualStrings("hello world", buf.data.items);
+    std.debug.print("  ✓ Buffer write: {s}\n", .{buf.data.items});
+}
+
+test "Buffer: clear" {
+    const stdout = std.fs.File{ .handle = 1 }; // stdout handle
+    var buf = buffer.RenderBuffer.init(testing.allocator, stdout);
+    defer buf.deinit();
+
+    try buf.write("test");
+    buf.clear();
+
+    try testing.expect(buf.data.items.len == 0);
+    std.debug.print("  ✓ Buffer cleared\n", .{});
+}
+
+test "Buffer: flush" {
+    // Use stderr for test output to avoid conflicts with test runner
+    // In production, this would be stdout, but for tests stderr is safer
+    const stderr = std.fs.File{ .handle = 2 };
+    var buf = buffer.RenderBuffer.init(testing.allocator, stderr);
+    defer buf.deinit();
+
+    try buf.write("flush test\n");
+    // Flush to stderr - this should work and be visible
+    try buf.flush();
+
+    try testing.expect(buf.data.items.len == 0);
+    std.debug.print("  ✓ Buffer flushed (wrote to stderr)\n", .{});
+}
+
+test "Buffer: write large content" {
+    const stdout = std.fs.File{ .handle = 1 }; // stdout handle
+    var buf = buffer.RenderBuffer.init(testing.allocator, stdout);
+    defer buf.deinit();
+
+    const large_content = "x" ** 1000;
+    try buf.write(large_content);
+
+    try testing.expect(buf.data.items.len == 1000);
+    std.debug.print("  ✓ Buffer handles large content: {} bytes\n", .{buf.data.items.len});
+}
+
+test "Buffer: multiple writes and flush" {
+    // Use stderr for test output
+    const stderr = std.fs.File{ .handle = 2 };
+    var buf = buffer.RenderBuffer.init(testing.allocator, stderr);
+    defer buf.deinit();
+
+    try buf.write("part1");
+    try buf.write("part2");
+    try buf.write("part3\n");
+
+    // Verify all parts are in buffer
+    try testing.expectEqualStrings("part1part2part3\n", buf.data.items);
+
+    // Flush to stderr - should be visible
+    try buf.flush();
+    try testing.expect(buf.data.items.len == 0);
+    std.debug.print("  ✓ Buffer multiple writes and flush works\n", .{});
+}

package/src/zig/test_diff.zig

@@ -0,0 +1,220 @@
+const std = @import("std");
+const diff = @import("diff.zig");
+const testing = std.testing;
+
+test "Diff: identical frames" {
+    const allocator = testing.allocator;
+
+    var prev = std.ArrayList([]u8){};
+    defer {
+        for (prev.items) |line| allocator.free(line);
+        prev.deinit(allocator);
+    }
+
+    var curr = std.ArrayList([]u8){};
+    defer {
+        for (curr.items) |line| allocator.free(line);
+        curr.deinit(allocator);
+    }
+
+    try prev.append(allocator, try allocator.dupe(u8, "line1"));
+    try prev.append(allocator, try allocator.dupe(u8, "line2"));
+
+    try curr.append(allocator, try allocator.dupe(u8, "line1"));
+    try curr.append(allocator, try allocator.dupe(u8, "line2"));
+
+    const ops = try diff.diff_frames(prev.items, curr.items, allocator);
+    defer allocator.free(ops);
+
+    try testing.expect(ops.len == 2);
+    for (ops) |op| {
+        try testing.expect(op == .no_change);
+    }
+    std.debug.print("  ✓ Diff identical frames: {} no_change ops\n", .{ops.len});
+}
+
+test "Diff: changed line" {
+    const allocator = testing.allocator;
+
+    var prev = std.ArrayList([]u8){};
+    defer {
+        for (prev.items) |line| allocator.free(line);
+        prev.deinit(allocator);
+    }
+
+    var curr = std.ArrayList([]u8){};
+    defer {
+        for (curr.items) |line| allocator.free(line);
+        curr.deinit(allocator);
+    }
+
+    try prev.append(allocator, try allocator.dupe(u8, "line1"));
+    try prev.append(allocator, try allocator.dupe(u8, "line2"));
+
+    try curr.append(allocator, try allocator.dupe(u8, "line1"));
+    try curr.append(allocator, try allocator.dupe(u8, "line2_changed"));
+
+    const ops = try diff.diff_frames(prev.items, curr.items, allocator);
+    defer allocator.free(ops);
+
+    try testing.expect(ops.len == 2);
+    try testing.expect(ops[0] == .no_change);
+    try testing.expect(ops[1] == .update_line);
+    if (ops[1] == .update_line) {
+        try testing.expectEqual(@as(u32, 1), ops[1].update_line.line);
+        try testing.expectEqualStrings("line2_changed", ops[1].update_line.content);
+    }
+    std.debug.print("  ✓ Diff changed line detected\n", .{});
+}
+
+test "Diff: inserted line" {
+    const allocator = testing.allocator;
+
+    var prev = std.ArrayList([]u8){};
+    defer {
+        for (prev.items) |line| allocator.free(line);
+        prev.deinit(allocator);
+    }
+
+    var curr = std.ArrayList([]u8){};
+    defer {
+        for (curr.items) |line| allocator.free(line);
+        curr.deinit(allocator);
+    }
+
+    try prev.append(allocator, try allocator.dupe(u8, "line1"));
+
+    try curr.append(allocator, try allocator.dupe(u8, "line1"));
+    try curr.append(allocator, try allocator.dupe(u8, "line2"));
+
+    const ops = try diff.diff_frames(prev.items, curr.items, allocator);
+    defer allocator.free(ops);
+
+    try testing.expect(ops.len == 2);
+    try testing.expect(ops[0] == .no_change);
+    try testing.expect(ops[1] == .insert_line);
+    if (ops[1] == .insert_line) {
+        try testing.expectEqual(@as(u32, 1), ops[1].insert_line.line);
+        try testing.expectEqualStrings("line2", ops[1].insert_line.content);
+    }
+    std.debug.print("  ✓ Diff inserted line detected\n", .{});
+}
+
+test "Diff: deleted line" {
+    const allocator = testing.allocator;
+
+    var prev = std.ArrayList([]u8){};
+    defer {
+        for (prev.items) |line| allocator.free(line);
+        prev.deinit(allocator);
+    }
+
+    var curr = std.ArrayList([]u8){};
+    defer {
+        for (curr.items) |line| allocator.free(line);
+        curr.deinit(allocator);
+    }
+
+    try prev.append(allocator, try allocator.dupe(u8, "line1"));
+    try prev.append(allocator, try allocator.dupe(u8, "line2"));
+
+    try curr.append(allocator, try allocator.dupe(u8, "line1"));
+
+    const ops = try diff.diff_frames(prev.items, curr.items, allocator);
+    defer allocator.free(ops);
+
+    try testing.expect(ops.len == 2);
+    try testing.expect(ops[0] == .no_change);
+    try testing.expect(ops[1] == .delete_line);
+    if (ops[1] == .delete_line) {
+        try testing.expectEqual(@as(u32, 1), ops[1].delete_line);
+    }
+    std.debug.print("  ✓ Diff deleted line detected\n", .{});
+}
+
+test "Diff: multiple changes" {
+    const allocator = testing.allocator;
+
+    var prev = std.ArrayList([]u8){};
+    defer {
+        for (prev.items) |line| allocator.free(line);
+        prev.deinit(allocator);
+    }
+
+    var curr = std.ArrayList([]u8){};
+    defer {
+        for (curr.items) |line| allocator.free(line);
+        curr.deinit(allocator);
+    }
+
+    try prev.append(allocator, try allocator.dupe(u8, "line1"));
+    try prev.append(allocator, try allocator.dupe(u8, "line2"));
+    try prev.append(allocator, try allocator.dupe(u8, "line3"));
+
+    try curr.append(allocator, try allocator.dupe(u8, "line1_changed"));
+    try curr.append(allocator, try allocator.dupe(u8, "line2"));
+    try curr.append(allocator, try allocator.dupe(u8, "line3"));
+    try curr.append(allocator, try allocator.dupe(u8, "line4"));
+
+    const ops = try diff.diff_frames(prev.items, curr.items, allocator);
+    defer allocator.free(ops);
+
+    try testing.expect(ops.len == 4);
+    try testing.expect(ops[0] == .update_line);
+    try testing.expect(ops[1] == .no_change);
+    try testing.expect(ops[2] == .no_change);
+    try testing.expect(ops[3] == .insert_line);
+    std.debug.print("  ✓ Diff multiple changes: {} ops\n", .{ops.len});
+}
+
+test "Diff: empty frames" {
+    const allocator = testing.allocator;
+
+    var prev = std.ArrayList([]u8){};
+    defer {
+        for (prev.items) |line| allocator.free(line);
+        prev.deinit(allocator);
+    }
+
+    var curr = std.ArrayList([]u8){};
+    defer {
+        for (curr.items) |line| allocator.free(line);
+        curr.deinit(allocator);
+    }
+
+    const ops = try diff.diff_frames(prev.items, curr.items, allocator);
+    defer allocator.free(ops);
+
+    try testing.expect(ops.len == 0);
+    std.debug.print("  ✓ Diff empty frames: {} ops\n", .{ops.len});
+}
+
+test "Diff: completely different frames" {
+    const allocator = testing.allocator;
+
+    var prev = std.ArrayList([]u8){};
+    defer {
+        for (prev.items) |line| allocator.free(line);
+        prev.deinit(allocator);
+    }
+
+    var curr = std.ArrayList([]u8){};
+    defer {
+        for (curr.items) |line| allocator.free(line);
+        curr.deinit(allocator);
+    }
+
+    try prev.append(allocator, try allocator.dupe(u8, "old1"));
+    try prev.append(allocator, try allocator.dupe(u8, "old2"));
+
+    try curr.append(allocator, try allocator.dupe(u8, "new1"));
+    try curr.append(allocator, try allocator.dupe(u8, "new2"));
+
+    const ops = try diff.diff_frames(prev.items, curr.items, allocator);
+    defer allocator.free(ops);
+
+    try testing.expect(ops.len == 2);
+    try testing.expect(ops[0] == .update_line);
+    try testing.expect(ops[1] == .update_line);
+    std.debug.print("  ✓ Diff completely different frames: {} update ops\n", .{ops.len});
+}

package/src/zig/test_integration.zig

@@ -0,0 +1,76 @@
+// Integration tests that test multiple modules together
+const std = @import("std");
+const region = @import("region.zig");
+const testing = std.testing;
+
+test "Integration: region with diff and throttle" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 2, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    // Set initial lines
+    try r.set_line(1, "initial line 1");
+    try r.set_line(2, "initial line 2");
+
+    // Change one line
+    try r.set_line(1, "updated line 1");
+
+    // Verify pending frame has updates
+    try testing.expectEqualStrings("updated line 1", r.pending_frame.items[0]);
+    try testing.expectEqualStrings("initial line 2", r.pending_frame.items[1]);
+
+    std.debug.print("  ✓ Integration: region diff and throttle work together\n", .{});
+}
+
+test "Integration: region expansion with multiple operations" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 1, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    // Start with 1 line, expand to 5
+    try r.set_line(1, "line1");
+    try r.set_line(2, "line2");
+    try r.set_line(3, "line3");
+    try r.set_line(4, "line4");
+    try r.set_line(5, "line5");
+
+    try testing.expect(r.height >= 5);
+    try testing.expect(r.pending_frame.items.len >= 5);
+
+    // Verify all lines are correct
+    try testing.expectEqualStrings("line1", r.pending_frame.items[0]);
+    try testing.expectEqualStrings("line2", r.pending_frame.items[1]);
+    try testing.expectEqualStrings("line3", r.pending_frame.items[2]);
+    try testing.expectEqualStrings("line4", r.pending_frame.items[3]);
+    try testing.expectEqualStrings("line5", r.pending_frame.items[4]);
+
+    std.debug.print("  ✓ Integration: region expansion with multiple operations\n", .{});
+}
+
+test "Integration: set then set_line" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 1, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    // Set entire content
+    try r.set("line1\nline2\nline3");
+
+    // Then update individual line
+    try r.set_line(2, "line2_updated");
+
+    try testing.expect(r.pending_frame.items.len >= 3);
+    try testing.expectEqualStrings("line1", r.pending_frame.items[0]);
+    try testing.expectEqualStrings("line2_updated", r.pending_frame.items[1]);
+    try testing.expectEqualStrings("line3", r.pending_frame.items[2]);
+
+    std.debug.print("  ✓ Integration: set then set_line works correctly\n", .{});
+}

package/src/zig/test_region.zig

@@ -0,0 +1,191 @@
+const std = @import("std");
+const region = @import("region.zig");
+const testing = std.testing;
+
+test "Region: initialization" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 5, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    try testing.expectEqual(@as(u32, 0), r.x);
+    try testing.expectEqual(@as(u32, 0), r.y);
+    try testing.expectEqual(@as(u32, 80), r.width);
+    try testing.expectEqual(@as(u32, 5), r.height);
+    try testing.expect(r.pending_frame.items.len == 5);
+    try testing.expect(r.previous_frame.items.len == 5);
+    std.debug.print("  ✓ Region initialized: {}x{} at ({}, {})\n", .{ r.width, r.height, r.x, r.y });
+}
+
+test "Region: set_line expands automatically" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 1, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    // Set line 1 (should work)
+    try r.set_line(1, "line1");
+    try testing.expectEqual(@as(u32, 1), r.height);
+
+    // Set line 5 (should expand)
+    try r.set_line(5, "line5");
+    try testing.expect(r.height >= 5);
+    try testing.expect(r.pending_frame.items.len >= 5);
+    std.debug.print("  ✓ Region expanded from 1 to {} lines\n", .{r.height});
+}
+
+test "Region: set_line rejects line 0" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 1, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    const result = r.set_line(0, "invalid");
+    try testing.expectError(error.InvalidLineNumber, result);
+    std.debug.print("  ✓ Region correctly rejects line 0\n", .{});
+}
+
+test "Region: set with newlines" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 1, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    try r.set("line1\nline2\nline3");
+    try testing.expect(r.height >= 3);
+    try testing.expect(r.pending_frame.items.len >= 3);
+    try testing.expectEqualStrings("line1", r.pending_frame.items[0]);
+    try testing.expectEqualStrings("line2", r.pending_frame.items[1]);
+    try testing.expectEqualStrings("line3", r.pending_frame.items[2]);
+    std.debug.print("  ✓ Region set with {} lines\n", .{r.pending_frame.items.len});
+}
+
+test "Region: expand_to" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 2, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    try r.expand_to(10);
+    try testing.expectEqual(@as(u32, 10), r.height);
+    try testing.expect(r.pending_frame.items.len == 10);
+    try testing.expect(r.previous_frame.items.len == 10);
+    std.debug.print("  ✓ Region expanded to {} lines\n", .{r.height});
+}
+
+test "Region: clear_line" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 3, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    try r.set_line(2, "test");
+    try r.clear_line(2);
+    try testing.expectEqualStrings("", r.pending_frame.items[1]);
+    std.debug.print("  ✓ Region clear_line works\n", .{});
+}
+
+test "Region: throttle configuration" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 1, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    r.set_throttle_fps(30);
+    try testing.expectEqual(@as(u32, 30), r.throttle_state.fps);
+    std.debug.print("  ✓ Region throttle set to {} FPS\n", .{r.throttle_state.fps});
+}
+
+test "Region: set_line with empty string" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 2, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    try r.set_line(1, "test");
+    try r.set_line(1, "");
+    try testing.expectEqualStrings("", r.pending_frame.items[0]);
+    std.debug.print("  ✓ Region set_line with empty string works\n", .{});
+}
+
+test "Region: set with empty content" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 1, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    try r.set("");
+    try testing.expect(r.pending_frame.items.len >= 1);
+    std.debug.print("  ✓ Region set with empty content works\n", .{});
+}
+
+test "Region: set with single line (no newline)" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 1, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    try r.set("single line");
+    try testing.expect(r.pending_frame.items.len >= 1);
+    try testing.expectEqualStrings("single line", r.pending_frame.items[0]);
+    std.debug.print("  ✓ Region set with single line works\n", .{});
+}
+
+test "Region: multiple set_line calls" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 1, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    try r.set_line(1, "line1");
+    try r.set_line(2, "line2");
+    try r.set_line(3, "line3");
+
+    try testing.expect(r.height >= 3);
+    try testing.expectEqualStrings("line1", r.pending_frame.items[0]);
+    try testing.expectEqualStrings("line2", r.pending_frame.items[1]);
+    try testing.expectEqualStrings("line3", r.pending_frame.items[2]);
+    std.debug.print("  ✓ Multiple set_line calls work correctly\n", .{});
+}
+
+test "Region: clear all lines" {
+    const allocator = testing.allocator;
+    const stdout = std.fs.File{ .handle = 2 }; // Use stderr for tests to avoid blocking
+
+    var r = try region.Region.init(allocator, 0, 0, 80, 3, stdout);
+    r.disable_rendering = true; // Disable actual rendering in tests
+    defer r.deinit();
+
+    try r.set_line(1, "line1");
+    try r.set_line(2, "line2");
+    try r.set_line(3, "line3");
+    try r.clear();
+
+    // All lines should be empty
+    for (r.pending_frame.items) |line| {
+        try testing.expectEqualStrings("", line);
+    }
+    std.debug.print("  ✓ Region clear works for all lines\n", .{});
+}

package/src/zig/test_runner.zig

@@ -0,0 +1,27 @@
+// Test runner that imports and runs all test modules
+// Zig's built-in test runner will discover all test functions
+const std = @import("std");
+
+// Import all test modules so their tests are discovered
+// Zig's test runner automatically discovers all test functions in imported modules
+// We use unique names to avoid duplicate declaration errors
+const _test_ansi = @import("test_ansi.zig");
+const _test_throttle = @import("test_throttle.zig");
+const _test_buffer = @import("test_buffer.zig");
+const _test_diff = @import("test_diff.zig");
+const _test_region = @import("test_region.zig");
+const _test_integration = @import("test_integration.zig");
+
+// Suppress unused variable warnings
+comptime {
+    _ = _test_ansi;
+    _ = _test_throttle;
+    _ = _test_buffer;
+    _ = _test_diff;
+    _ = _test_region;
+    _ = _test_integration;
+}
+
+// This file serves as the root for test discovery
+// All test functions in imported modules will be run
+// Each test prints its own output using std.debug.print() for visibility

package/src/zig/test_throttle.zig

@@ -0,0 +1,59 @@
+const std = @import("std");
+const throttle = @import("throttle.zig");
+const testing = std.testing;
+
+test "Throttle: initialization" {
+    const t = throttle.Throttle.init(60);
+    try testing.expectEqual(@as(u32, 60), t.fps);
+    try testing.expect(t.min_frame_interval > 0);
+    std.debug.print("  ✓ Throttle initialized: {} FPS, {}ns interval\n", .{ t.fps, t.min_frame_interval });
+}
+
+test "Throttle: set_fps" {
+    var t = throttle.Throttle.init(30);
+    t.set_fps(120);
+    try testing.expectEqual(@as(u32, 120), t.fps);
+    std.debug.print("  ✓ Throttle FPS changed to: {}\n", .{t.fps});
+}
+
+test "Throttle: should_render allows first frame" {
+    var t = throttle.Throttle.init(60);
+    // First call should always allow render
+    const should = t.should_render();
+    try testing.expect(should);
+    std.debug.print("  ✓ First frame allowed\n", .{});
+}
+
+test "Throttle: should_render respects interval" {
+    var t = throttle.Throttle.init(1000); // 1 FPS = 1 second interval
+    _ = t.should_render(); // First frame
+
+    // Immediately after, should not render
+    const should = t.should_render();
+    try testing.expect(!should);
+    std.debug.print("  ✓ Throttle correctly blocks immediate second frame\n", .{});
+}
+
+test "Throttle: time_until_next_frame" {
+    var t = throttle.Throttle.init(10); // 10 FPS = 100ms interval
+    _ = t.should_render();
+
+    const remaining = t.time_until_next_frame();
+    try testing.expect(remaining > 0);
+    try testing.expect(remaining <= 100_000_000); // Should be <= 100ms in nanoseconds
+    std.debug.print("  ✓ Time until next frame: {}ns\n", .{remaining});
+}
+
+test "Throttle: very high FPS" {
+    const t = throttle.Throttle.init(1000); // 1000 FPS
+    try testing.expectEqual(@as(u32, 1000), t.fps);
+    try testing.expect(t.min_frame_interval > 0);
+    std.debug.print("  ✓ Throttle handles high FPS: {} FPS, {}ns interval\n", .{ t.fps, t.min_frame_interval });
+}
+
+test "Throttle: very low FPS" {
+    const t = throttle.Throttle.init(1); // 1 FPS
+    try testing.expectEqual(@as(u32, 1), t.fps);
+    try testing.expect(t.min_frame_interval == 1_000_000_000); // 1 second
+    std.debug.print("  ✓ Throttle handles low FPS: {} FPS, {}ns interval\n", .{ t.fps, t.min_frame_interval });
+}

package/src/zig/throttle.zig

@@ -0,0 +1,38 @@
+// Throttling for frame rate limiting
+const std = @import("std");
+
+pub const Throttle = struct {
+    last_frame_time: i64,
+    min_frame_interval: i64, // nanoseconds
+    fps: u32,
+
+    pub fn init(fps: u32) Throttle {
+        const interval_ns = @divTrunc(1_000_000_000, @as(i64, fps));
+        return .{
+            .last_frame_time = 0,
+            .min_frame_interval = interval_ns,
+            .fps = fps,
+        };
+    }
+
+    pub fn set_fps(self: *Throttle, fps: u32) void {
+        self.fps = fps;
+        self.min_frame_interval = @divTrunc(1_000_000_000, @as(i64, fps));
+    }
+
+    pub fn should_render(self: *Throttle) bool {
+        const now = @as(i64, @intCast(std.time.nanoTimestamp()));
+        if (now - self.last_frame_time >= self.min_frame_interval) {
+            self.last_frame_time = now;
+            return true;
+        }
+        return false;
+    }
+
+    pub fn time_until_next_frame(self: *Throttle) i64 {
+        const now = @as(i64, @intCast(std.time.nanoTimestamp()));
+        const elapsed = now - self.last_frame_time;
+        const remaining = self.min_frame_interval - elapsed;
+        return if (remaining > 0) @as(i64, @intCast(remaining)) else 0;
+    }
+};