0c91e8f4
Add frame-callback throttling implementation plan
a73x 2026-04-16 10:38
14-task plan following the spec's rollout order. Task 8 is where the hidden-workspace freeze gets fixed; tasks 9-13 consolidate the remaining Wayland modes and add regression tests.
diff --git a/docs/superpowers/plans/2026-04-16-frame-callback-throttling-implementation.md b/docs/superpowers/plans/2026-04-16-frame-callback-throttling-implementation.md new file mode 100644 index 0000000..a0902d7 --- /dev/null +++ b/docs/superpowers/plans/2026-04-16-frame-callback-throttling-implementation.md @@ -0,0 +1,1793 @@ # Frame-Callback Throttling Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Eliminate the hidden-workspace freeze in waystty by adopting canonical `wl_surface.frame`-callback throttling, and consolidate four near-duplicate Wayland main loops into a shared `FrameLoop` readiness primitive. **Architecture:** Introduce a `FrameLoop` module that owns the poll/dispatch/armed/pending-callback bookkeeping. It is parameterized over a `DisplayOps` trait (fn-pointer vtable) so it can be unit-tested with a mock compositor. Introduce a `SurfaceState` struct on the window that tracks `configured`/`suspended`/entered-outputs. The main loop gates all Vulkan work on `frame_loop.canRender()` — including `deviceWaitIdle`, `recreateSwapchain`, and `rebuildFaceForScale`, not just `drawCells`. Each of the four Wayland modes (`runTerminal`, `runTextCoverageCompare`, `runDrawSmokeTest`, bench mode via `WAYSTTY_BENCH`) migrates to the shared loop. Bench mode gets an opt-out env var. **Tech Stack:** Zig, zig-wayland bindings (already at xdg_wm_base v6 via build.zig:31 scanner call — only the `registry.bind` version needs bumping), Vulkan WSI via vulkan-zig, xkbcommon. **Spec:** `docs/superpowers/specs/2026-04-16-frame-callback-throttling-design.md` --- ## File Structure **New files:** - `src/frame_loop.zig` — FrameLoop + DisplayOps trait + MockDisplayOps for tests (~250 LOC) **Modified files:** - `src/scale_tracker.zig` — add `enteredCount()` (~10 LOC) - `src/wayland.zig` — add `SurfaceState`, bump wm_base bind v5→v6, handle xdg_toplevel `.suspended`, wire FrameLoop transitions into surfaceListener (~120 LOC delta) - `src/main.zig` — four loop sites migrated; split resize handling into observeResize/applyPendingResize (~600 LOC net reduction) - `build.zig` — wire `frame_loop` module and its test step (~30 LOC) **Unchanged:** `src/renderer.zig`, `src/vt.zig`, `src/pty.zig`, `src/font.zig`, `src/config.zig`, shaders. --- ## Task 1: Add `enteredCount()` to ScaleTracker **Files:** - Modify: `src/scale_tracker.zig` - [ ] **Step 1: Write failing test** Append to the existing test block in `src/scale_tracker.zig`: ```zig test "enteredCount reflects the entered-output set" { var t = ScaleTracker.init(std.testing.allocator); defer t.deinit(); try std.testing.expectEqual(@as(usize, 0), t.enteredCount()); try t.addOutput(1); try t.addOutput(2); try std.testing.expectEqual(@as(usize, 0), t.enteredCount()); try t.enterOutput(1); try std.testing.expectEqual(@as(usize, 1), t.enteredCount()); try t.enterOutput(2); try std.testing.expectEqual(@as(usize, 2), t.enteredCount()); t.leaveOutput(1); try std.testing.expectEqual(@as(usize, 1), t.enteredCount()); t.removeOutput(2); try std.testing.expectEqual(@as(usize, 0), t.enteredCount()); } ``` - [ ] **Step 2: Run to verify failure** Run: `make test` Expected: compile error — `enteredCount` not defined on `ScaleTracker`. - [ ] **Step 3: Implement** Insert in `src/scale_tracker.zig` after the existing `bufferScale` method (around line 54): ```zig pub fn enteredCount(self: *const ScaleTracker) usize { return self.entered.count(); } ``` - [ ] **Step 4: Run to verify pass** Run: `make test` Expected: all tests pass, including the new `enteredCount reflects the entered-output set`. - [ ] **Step 5: Commit** ```bash git add src/scale_tracker.zig git commit -m "$(cat <<'EOF' Add ScaleTracker.enteredCount Exposes the size of the entered-output set so higher layers can gate rendering on surface visibility. EOF )" ``` --- ## Task 2: Add `SurfaceState` struct **Files:** - Modify: `src/wayland.zig` - [ ] **Step 1: Write failing test** Append to the tests at the bottom of `src/wayland.zig`: ```zig test "SurfaceState.visible requires configured && !suspended && enteredCount > 0" { var tracker = ScaleTracker.init(std.testing.allocator); defer tracker.deinit(); try tracker.addOutput(1); var state = SurfaceState{ .tracker = &tracker }; // Unconfigured → not visible try std.testing.expect(!state.visible()); state.configured = true; // No entered outputs yet → not visible try std.testing.expect(!state.visible()); try tracker.enterOutput(1); // Configured + entered + not suspended → visible try std.testing.expect(state.visible()); state.suspended = true; try std.testing.expect(!state.visible()); state.suspended = false; tracker.leaveOutput(1); try std.testing.expect(!state.visible()); } ``` - [ ] **Step 2: Run to verify failure** Run: `make test` Expected: compile error — `SurfaceState` undefined. - [ ] **Step 3: Implement** Add near the top of `src/wayland.zig` (after imports, before `pub const Connection`): ```zig pub const SurfaceState = struct { configured: bool = false, suspended: bool = false, tracker: *ScaleTracker, pub fn visible(self: *const SurfaceState) bool { return self.configured and !self.suspended and self.tracker.enteredCount() > 0; } }; ``` - [ ] **Step 4: Run to verify pass** Run: `make test` Expected: all tests pass. - [ ] **Step 5: Commit** ```bash git add src/wayland.zig git commit -m "$(cat <<'EOF' Add SurfaceState struct for visibility tracking Single source of truth for whether the surface is currently mapped, configured, and not suspended. Not yet wired into Window — that happens in a follow-up. EOF )" ``` --- ## Task 3: Wire SurfaceState into Window **Files:** - Modify: `src/wayland.zig` - [ ] **Step 1: Add SurfaceState to Window** In `src/wayland.zig`, modify the `Window` struct to own a `SurfaceState` and drop the existing `configured: bool` field. Find the struct definition (around line 545, look for `pub const Window = struct`). Replace the old `configured` field with: ```zig state: SurfaceState, ``` - [ ] **Step 2: Update Window initialization** In `createWindow` (around wayland.zig:658), after setting up the window fields but before returning, initialize `state`: ```zig window.* = .{ .alloc = alloc, .surface = try compositor.createSurface(), .xdg_surface = undefined, .xdg_toplevel = undefined, .tracker = &self.scale_tracker, .outputs = &self.outputs, .state = .{ .tracker = &self.scale_tracker }, // ... preserve other existing fields (width, height, etc.) }; ``` (Keep all other existing fields. Just add `.state = .{ .tracker = &self.scale_tracker }`.) - [ ] **Step 3: Update xdgSurfaceListener to set configured** In `src/wayland.zig`, locate `fn xdgSurfaceListener` (around line 1041) and update: ```zig fn xdgSurfaceListener(surface: *xdg.Surface, event: xdg.Surface.Event, window: *Window) void { switch (event) { .configure => |cfg| { surface.ackConfigure(cfg.serial); window.state.configured = true; }, } } ``` (Removes the old `window.configured = true` assignment if it existed under a different name. If the old code used a boolean field called `configured`, replace all references throughout `wayland.zig` with `window.state.configured`.) - [ ] **Step 4: Remove or redirect any remaining `window.configured` references** Search for `window.configured` and `self.configured` in `src/wayland.zig` and update to `window.state.configured` / `self.state.configured`. Run: `grep -n "\.configured" src/wayland.zig` from the shell to find them. In `src/main.zig`, search for any `window.configured` references and update similarly. Run: `grep -n "window\.configured" src/main.zig`. - [ ] **Step 5: Run tests + build** Run: `make test && make build` Expected: all tests pass, main binary compiles. - [ ] **Step 6: Commit** ```bash git add src/wayland.zig src/main.zig git commit -m "$(cat <<'EOF' Wire SurfaceState into Window Replaces the bare Window.configured flag with a SurfaceState embedded on the Window. Visibility queries now go through state.visible(), which is a no-op change today but will gate rendering once FrameLoop lands. EOF )" ``` --- ## Task 4: Bump wm_base to v6 and handle `xdg_toplevel.configure.states.suspended` **Files:** - Modify: `src/wayland.zig` - [ ] **Step 1: Write failing test** Append to the tests at the bottom of `src/wayland.zig`: ```zig test "SurfaceState.suspended toggles from xdg_toplevel.configure.states" { var tracker = ScaleTracker.init(std.testing.allocator); defer tracker.deinit(); try tracker.addOutput(1); try tracker.enterOutput(1); var state = SurfaceState{ .tracker = &tracker, .configured = true }; try std.testing.expect(state.visible()); // Helper function under test — applies xdg_toplevel state array to SurfaceState. const states_suspended = [_]u32{@intFromEnum(xdg.Toplevel.State.suspended)}; applyToplevelStates(&state, std.mem.sliceAsBytes(&states_suspended)); try std.testing.expect(state.suspended); try std.testing.expect(!state.visible()); const states_none = [_]u32{}; applyToplevelStates(&state, std.mem.sliceAsBytes(&states_none)); try std.testing.expect(!state.suspended); try std.testing.expect(state.visible()); } ``` - [ ] **Step 2: Run to verify failure** Run: `make test` Expected: compile error — `applyToplevelStates` undefined. - [ ] **Step 3: Bump wm_base bind version** In `src/wayland.zig` at line 1092, change: ```zig } else if (std.mem.eql(u8, iface, std.mem.span(xdg.WmBase.interface.name))) { conn.globals.wm_base = registry.bind(g.name, xdg.WmBase, 5) catch return; ``` to: ```zig } else if (std.mem.eql(u8, iface, std.mem.span(xdg.WmBase.interface.name))) { conn.globals.wm_base = registry.bind(g.name, xdg.WmBase, 6) catch return; ``` (The scanner already generates v6 bindings per build.zig:31. Only the runtime bind version changes.) - [ ] **Step 4: Implement `applyToplevelStates`** Add to `src/wayland.zig` (near `xdgToplevelListener`, around line 1067): ```zig fn applyToplevelStates(state: *SurfaceState, state_bytes: []const u8) void { // xdg_toplevel.configure delivers the state array as a wl_array of u32. // Re-interpret to u32 slice and scan for `.suspended`. const u32_count = state_bytes.len / @sizeOf(u32); const states = std.mem.bytesAsSlice(u32, state_bytes[0 .. u32_count * @sizeOf(u32)]); var suspended = false; for (states) |raw| { if (raw == @intFromEnum(xdg.Toplevel.State.suspended)) { suspended = true; break; } } state.suspended = suspended; } ``` - [ ] **Step 5: Wire into xdgToplevelListener** Update `xdgToplevelListener` (around wayland.zig:1067): ```zig fn xdgToplevelListener(_: *xdg.Toplevel, event: xdg.Toplevel.Event, window: *Window) void { switch (event) { .configure => |cfg| { if (cfg.width > 0) window.width = @intCast(cfg.width); if (cfg.height > 0) window.height = @intCast(cfg.height); applyToplevelStates(&window.state, std.mem.sliceAsBytes(cfg.states.slice())); }, .close => window.should_close = true, .configure_bounds => {}, .wm_capabilities => {}, } } ``` (The exact access pattern for `cfg.states` depends on the zig-wayland binding shape. If `cfg.states` is already a `[]u32` or similar, skip the `sliceAsBytes` and pass directly; adjust `applyToplevelStates` to match. Verify by reading the generated binding in `zig-cache/` or by attempting both and keeping whichever compiles.) - [ ] **Step 6: Run tests** Run: `make test` Expected: all tests pass, including `SurfaceState.suspended toggles from xdg_toplevel.configure.states`. - [ ] **Step 7: Build** Run: `make build` Expected: clean compile. Older sway versions simply never send `.suspended` — backwards-compatible. - [ ] **Step 8: Commit** ```bash git add src/wayland.zig git commit -m "$(cat <<'EOF' Bump xdg_wm_base to v6 and honor toplevel suspended state The scanner already generates v6 bindings (build.zig:31); this commit bumps the runtime bind version and hooks xdg_toplevel.configure.states into SurfaceState.suspended. Compositors that don't send .suspended (pre-v6 impls) see no behavior change. EOF )" ``` --- ## Task 5: Create `DisplayOps` trait and real-world shim **Files:** - Create: `src/frame_loop.zig` - Modify: `build.zig` - [ ] **Step 1: Wire new module into build.zig** In `build.zig`, after the `scale_tracker_mod` creation (around line 16), add: ```zig const frame_loop_mod = b.createModule(.{ .root_source_file = b.path("src/frame_loop.zig"), .target = target, .optimize = optimize, }); frame_loop_mod.addImport("wayland", wayland_generated_mod); frame_loop_mod.addImport("scale_tracker", scale_tracker_mod); ``` Wire it as a dependency of `wayland_mod` (so wayland.zig can call into FrameLoop hooks) — after `wayland_mod.addImport("scale_tracker", scale_tracker_mod);`: ```zig wayland_mod.addImport("frame_loop", frame_loop_mod); ``` And make `frame_loop` importable by main: ```zig exe_mod.addImport("frame_loop", frame_loop_mod); ``` Then add a test step for it. After the `scale_tracker_tests` block (around line 121): ```zig // Test frame_loop.zig const frame_loop_test_mod = b.createModule(.{ .root_source_file = b.path("src/frame_loop.zig"), .target = target, .optimize = optimize, }); frame_loop_test_mod.addImport("wayland", wayland_generated_mod); frame_loop_test_mod.addImport("scale_tracker", scale_tracker_mod); const frame_loop_tests = b.addTest(.{ .root_module = frame_loop_test_mod, }); test_step.dependOn(&b.addRunArtifact(frame_loop_tests).step); ``` - [ ] **Step 2: Create initial `src/frame_loop.zig` with the DisplayOps trait** Create `src/frame_loop.zig`: ```zig const std = @import("std"); const wl = @import("wayland").client.wl; const scale_tracker = @import("scale_tracker"); // Mirror of wayland.SurfaceState. Using a structural duplicate here instead of // importing wayland.zig avoids a circular module dependency (wayland depends on // frame_loop). The real wayland.SurfaceState embeds one of these by reference. pub const SurfaceStateView = struct { configured_ptr: *const bool, suspended_ptr: *const bool, tracker: *const scale_tracker.ScaleTracker, pub fn visible(self: SurfaceStateView) bool { return self.configured_ptr.* and !self.suspended_ptr.* and self.tracker.enteredCount() > 0; } }; // Opaque handle to a frame callback. Real path holds a *wl.Callback cast here; // mock holds a usize cast here. Identity is pointer equality. pub const CallbackToken = *const anyopaque; pub const DisplayOps = struct { ctx: *anyopaque, // All fn pointers receive the same ctx so the caller can carry whatever // concrete objects it needs (wl.Display, wl.Surface, test mock, etc). flushFn: *const fn (*anyopaque) void, prepareReadFn: *const fn (*anyopaque) bool, readEventsFn: *const fn (*anyopaque) void, dispatchPendingFn: *const fn (*anyopaque) void, getFdFn: *const fn (*anyopaque) std.posix.fd_t, // Requests a wl_surface.frame() and sets its done listener. Returns the // token identifying the new callback. FrameLoop compares the token // delivered by onFrameCallbackDone against pending_token. requestFrameFn: *const fn (*anyopaque, *FrameLoop) anyerror!CallbackToken, // Destroys a previously issued frame callback (for hide-path cleanup). // Must tolerate being called on a token the compositor has already // consumed — real path: wl.Callback.destroy is idempotent on the client. destroyCallbackFn: *const fn (*anyopaque, CallbackToken) void, }; pub const FrameLoop = struct { ops: DisplayOps, state: SurfaceStateView, pending_token: ?CallbackToken = null, armed: bool = true, pub fn init(ops: DisplayOps, state: SurfaceStateView) FrameLoop { return .{ .ops = ops, .state = state }; } pub fn deinit(self: *FrameLoop) void { if (self.pending_token) |t| self.ops.destroyCallbackFn(self.ops.ctx, t); self.pending_token = null; } pub fn canRender(self: *const FrameLoop) bool { return self.armed and self.state.visible(); } pub fn commitRender(self: *FrameLoop) !void { std.debug.assert(self.canRender()); if (self.pending_token) |t| self.ops.destroyCallbackFn(self.ops.ctx, t); self.pending_token = try self.ops.requestFrameFn(self.ops.ctx, self); self.armed = false; } pub fn onFrameCallbackDone(self: *FrameLoop, token: CallbackToken) void { if (self.pending_token == null or self.pending_token.? != token) return; self.ops.destroyCallbackFn(self.ops.ctx, token); self.pending_token = null; self.armed = true; } pub fn onSurfaceHidden(self: *FrameLoop) void { if (self.pending_token) |t| self.ops.destroyCallbackFn(self.ops.ctx, t); self.pending_token = null; // armed unchanged — canRender() is false while hidden regardless. } pub fn onSurfaceShown(self: *FrameLoop) void { self.armed = true; } pub fn forceArm(self: *FrameLoop) void { if (self.pending_token) |t| self.ops.destroyCallbackFn(self.ops.ctx, t); self.pending_token = null; self.armed = true; } /// Blocks on wl_fd + extra pollfds with `timeout_ms`, then reads + dispatches /// any pending Wayland events. Safe to call in any state. pub fn waitForWork( self: *FrameLoop, extra: []std.posix.pollfd, timeout_ms: i32, ) !void { self.ops.flushFn(self.ops.ctx); const wl_fd = self.ops.getFdFn(self.ops.ctx); // Build a small on-stack pollfd array: wl_fd + extras. // Cap extras at 8 — waystty never polls more than pty+wl. var all: [9]std.posix.pollfd = undefined; all[0] = .{ .fd = wl_fd, .events = std.posix.POLL.IN, .revents = 0 }; std.debug.assert(extra.len <= all.len - 1); for (extra, 0..) |fd, i| all[i + 1] = fd; const total = 1 + extra.len; _ = std.posix.poll(all[0..total], timeout_ms) catch {}; // Propagate revents back into caller's extra slice. for (extra, 0..) |*fd, i| fd.* = all[i + 1]; if (all[0].revents & std.posix.POLL.IN != 0) { if (self.ops.prepareReadFn(self.ops.ctx)) { self.ops.readEventsFn(self.ops.ctx); } } self.ops.dispatchPendingFn(self.ops.ctx); } }; ``` - [ ] **Step 3: Build to verify module wires up** Run: `make build` Expected: clean compile. The file has no tests yet. - [ ] **Step 4: Commit** ```bash git add build.zig src/frame_loop.zig git commit -m "$(cat <<'EOF' Introduce FrameLoop module and DisplayOps trait Pure readiness primitive for the wl_surface.frame-callback pacing pattern. Not yet used by any loop — next commits add a mock DisplayOps for tests, then migrate the real loops one at a time. EOF )" ``` --- ## Task 6: Add MockDisplayOps and unit tests for FrameLoop **Files:** - Modify: `src/frame_loop.zig` - [ ] **Step 1: Add MockDisplayOps and failing tests** Append to `src/frame_loop.zig`: ```zig // --------------------------------------------------------------------------- // Test-only mock below this line. // --------------------------------------------------------------------------- const Mock = struct { next_token: usize = 1, frame_requests: usize = 0, callbacks_destroyed: usize = 0, flushed: usize = 0, dispatched: usize = 0, // A fake fd that never becomes ready — tests call waitForWork with a // 0ms timeout so poll returns immediately. pipe_fds: [2]std.posix.fd_t = .{ -1, -1 }, fn init() !Mock { const pipes = try std.posix.pipe(); return .{ .pipe_fds = pipes }; } fn deinit(self: *Mock) void { if (self.pipe_fds[0] >= 0) std.posix.close(self.pipe_fds[0]); if (self.pipe_fds[1] >= 0) std.posix.close(self.pipe_fds[1]); } fn flushThunk(ctx: *anyopaque) void { const self: *Mock = @ptrCast(@alignCast(ctx)); self.flushed += 1; } fn prepareReadThunk(_: *anyopaque) bool { return false; } fn readEventsThunk(_: *anyopaque) void {} fn dispatchPendingThunk(ctx: *anyopaque) void { const self: *Mock = @ptrCast(@alignCast(ctx)); self.dispatched += 1; } fn getFdThunk(ctx: *anyopaque) std.posix.fd_t { const self: *Mock = @ptrCast(@alignCast(ctx)); return self.pipe_fds[0]; } fn requestFrameThunk(ctx: *anyopaque, _: *FrameLoop) anyerror!CallbackToken { const self: *Mock = @ptrCast(@alignCast(ctx)); const tok: CallbackToken = @ptrFromInt(self.next_token); self.next_token += 1; self.frame_requests += 1; return tok; } fn destroyCallbackThunk(ctx: *anyopaque, _: CallbackToken) void { const self: *Mock = @ptrCast(@alignCast(ctx)); self.callbacks_destroyed += 1; } fn ops(self: *Mock) DisplayOps { return .{ .ctx = self, .flushFn = flushThunk, .prepareReadFn = prepareReadThunk, .readEventsFn = readEventsThunk, .dispatchPendingFn = dispatchPendingThunk, .getFdFn = getFdThunk, .requestFrameFn = requestFrameThunk, .destroyCallbackFn = destroyCallbackThunk, }; } }; const TestState = struct { configured: bool = true, suspended: bool = false, tracker: scale_tracker.ScaleTracker, fn init(alloc: std.mem.Allocator) !TestState { var t = scale_tracker.ScaleTracker.init(alloc); try t.addOutput(1); try t.enterOutput(1); return .{ .tracker = t }; } fn deinit(self: *TestState) void { self.tracker.deinit(); } fn view(self: *const TestState) SurfaceStateView { return .{ .configured_ptr = &self.configured, .suspended_ptr = &self.suspended, .tracker = &self.tracker, }; } }; test "initial state: armed and can render when visible" { var mock = try Mock.init(); defer mock.deinit(); var ts = try TestState.init(std.testing.allocator); defer ts.deinit(); var loop = FrameLoop.init(mock.ops(), ts.view()); defer loop.deinit(); try std.testing.expect(loop.armed); try std.testing.expect(loop.canRender()); try std.testing.expectEqual(@as(?CallbackToken, null), loop.pending_token); } test "commitRender requests a frame and disarms" { var mock = try Mock.init(); defer mock.deinit(); var ts = try TestState.init(std.testing.allocator); defer ts.deinit(); var loop = FrameLoop.init(mock.ops(), ts.view()); defer loop.deinit(); try loop.commitRender(); try std.testing.expect(!loop.armed); try std.testing.expect(!loop.canRender()); try std.testing.expect(loop.pending_token != null); try std.testing.expectEqual(@as(usize, 1), mock.frame_requests); } test "onFrameCallbackDone re-arms when token matches" { var mock = try Mock.init(); defer mock.deinit(); var ts = try TestState.init(std.testing.allocator); defer ts.deinit(); var loop = FrameLoop.init(mock.ops(), ts.view()); defer loop.deinit(); try loop.commitRender(); const tok = loop.pending_token.?; loop.onFrameCallbackDone(tok); try std.testing.expect(loop.armed); try std.testing.expectEqual(@as(?CallbackToken, null), loop.pending_token); try std.testing.expectEqual(@as(usize, 1), mock.callbacks_destroyed); } test "onFrameCallbackDone ignores stale token" { var mock = try Mock.init(); defer mock.deinit(); var ts = try TestState.init(std.testing.allocator); defer ts.deinit(); var loop = FrameLoop.init(mock.ops(), ts.view()); defer loop.deinit(); try loop.commitRender(); const stale_tok: CallbackToken = @ptrFromInt(0xDEAD); loop.onFrameCallbackDone(stale_tok); try std.testing.expect(!loop.armed); try std.testing.expect(loop.pending_token != null); } test "onSurfaceHidden destroys pending callback and leaves armed unchanged" { var mock = try Mock.init(); defer mock.deinit(); var ts = try TestState.init(std.testing.allocator); defer ts.deinit(); var loop = FrameLoop.init(mock.ops(), ts.view()); defer loop.deinit(); try loop.commitRender(); const armed_before = loop.armed; loop.onSurfaceHidden(); try std.testing.expectEqual(armed_before, loop.armed); // false, unchanged try std.testing.expectEqual(@as(?CallbackToken, null), loop.pending_token); try std.testing.expectEqual(@as(usize, 1), mock.callbacks_destroyed); } test "onSurfaceShown force-arms" { var mock = try Mock.init(); defer mock.deinit(); var ts = try TestState.init(std.testing.allocator); defer ts.deinit(); var loop = FrameLoop.init(mock.ops(), ts.view()); defer loop.deinit(); try loop.commitRender(); try std.testing.expect(!loop.armed); loop.onSurfaceShown(); try std.testing.expect(loop.armed); } test "canRender requires both armed and visible" { var mock = try Mock.init(); defer mock.deinit(); var ts = try TestState.init(std.testing.allocator); defer ts.deinit(); var loop = FrameLoop.init(mock.ops(), ts.view()); defer loop.deinit(); try std.testing.expect(loop.canRender()); // armed + visible ts.suspended = true; try std.testing.expect(!loop.canRender()); // visibility gate ts.suspended = false; try loop.commitRender(); try std.testing.expect(!loop.canRender()); // armed gate } test "forceArm recovers without a callback (OUT_OF_DATE path)" { var mock = try Mock.init(); defer mock.deinit(); var ts = try TestState.init(std.testing.allocator); defer ts.deinit(); var loop = FrameLoop.init(mock.ops(), ts.view()); defer loop.deinit(); try loop.commitRender(); try std.testing.expect(!loop.armed); loop.forceArm(); try std.testing.expect(loop.armed); try std.testing.expectEqual(@as(?CallbackToken, null), loop.pending_token); } test "deinit destroys any pending callback" { var mock = try Mock.init(); defer mock.deinit(); var ts = try TestState.init(std.testing.allocator); defer ts.deinit(); { var loop = FrameLoop.init(mock.ops(), ts.view()); defer loop.deinit(); try loop.commitRender(); } try std.testing.expectEqual(@as(usize, 1), mock.callbacks_destroyed); } ``` - [ ] **Step 2: Run tests** Run: `make test` Expected: all 9 new FrameLoop tests pass. - [ ] **Step 3: Commit** ```bash git add src/frame_loop.zig git commit -m "$(cat <<'EOF' Add MockDisplayOps + FrameLoop unit tests 9 tests covering: initial state, commit disarms, callback done re-arms, stale-token rejection, hidden cleanup, show force-arm, canRender gating, forceArm recovery, deinit cleanup. EOF )" ``` --- ## Task 7: Real-path DisplayOps adapter in wayland.zig **Files:** - Modify: `src/wayland.zig` - [ ] **Step 1: Add adapter at the top of `src/wayland.zig`** After the existing imports, add: ```zig const frame_loop_mod = @import("frame_loop"); pub const FrameLoop = frame_loop_mod.FrameLoop; pub const DisplayOps = frame_loop_mod.DisplayOps; pub const SurfaceStateView = frame_loop_mod.SurfaceStateView; pub const CallbackToken = frame_loop_mod.CallbackToken; ``` - [ ] **Step 2: Add the real-path adapter on Window** Append to the `Window` struct methods (in `src/wayland.zig`, inside the `pub const Window = struct { ... };` block, after the existing methods): ```zig /// Build a DisplayOps vtable that drives the real compositor. pub fn displayOps(self: *Window, display: *wl.Display) DisplayOps { // Carry both display and surface via an owned adapter struct. self.display_adapter = .{ .display = display, .surface = self.surface, .loop_ref = null, }; return .{ .ctx = &self.display_adapter, .flushFn = DisplayAdapter.flushThunk, .prepareReadFn = DisplayAdapter.prepareReadThunk, .readEventsFn = DisplayAdapter.readEventsThunk, .dispatchPendingFn = DisplayAdapter.dispatchPendingThunk, .getFdFn = DisplayAdapter.getFdThunk, .requestFrameFn = DisplayAdapter.requestFrameThunk, .destroyCallbackFn = DisplayAdapter.destroyCallbackThunk, }; } pub fn surfaceStateView(self: *const Window) SurfaceStateView { return .{ .configured_ptr = &self.state.configured, .suspended_ptr = &self.state.suspended, .tracker = self.tracker, }; } ``` And add a field to `Window`: ```zig display_adapter: DisplayAdapter = undefined, ``` - [ ] **Step 3: Implement the DisplayAdapter type** Add to `src/wayland.zig`, before the `pub const Window = struct` definition: ```zig pub const DisplayAdapter = struct { display: *wl.Display, surface: *wl.Surface, loop_ref: ?*FrameLoop, fn flushThunk(ctx: *anyopaque) void { const self: *DisplayAdapter = @ptrCast(@alignCast(ctx)); _ = self.display.flush(); } fn prepareReadThunk(ctx: *anyopaque) bool { const self: *DisplayAdapter = @ptrCast(@alignCast(ctx)); return self.display.prepareRead(); } fn readEventsThunk(ctx: *anyopaque) void { const self: *DisplayAdapter = @ptrCast(@alignCast(ctx)); _ = self.display.readEvents(); } fn dispatchPendingThunk(ctx: *anyopaque) void { const self: *DisplayAdapter = @ptrCast(@alignCast(ctx)); _ = self.display.dispatchPending(); } fn getFdThunk(ctx: *anyopaque) std.posix.fd_t { const self: *DisplayAdapter = @ptrCast(@alignCast(ctx)); return self.display.getFd(); } fn requestFrameThunk(ctx: *anyopaque, loop: *FrameLoop) anyerror!CallbackToken { const self: *DisplayAdapter = @ptrCast(@alignCast(ctx)); self.loop_ref = loop; const cb = try self.surface.frame(); cb.setListener(*FrameLoop, frameCallbackListener, loop); return @ptrCast(cb); } fn destroyCallbackThunk(_: *anyopaque, token: CallbackToken) void { const cb: *wl.Callback = @constCast(@ptrCast(@alignCast(token))); cb.destroy(); } }; fn frameCallbackListener(cb: *wl.Callback, event: wl.Callback.Event, loop: *FrameLoop) void { switch (event) { .done => { const tok: CallbackToken = @ptrCast(cb); loop.onFrameCallbackDone(tok); }, } } ``` - [ ] **Step 4: Verify build** Run: `make build` Expected: clean compile. No new tests yet — integration is exercised in Task 8+. - [ ] **Step 5: Commit** ```bash git add src/wayland.zig git commit -m "$(cat <<'EOF' Add real-path DisplayOps adapter on Window DisplayAdapter thinly wraps wl.Display + wl.Surface and satisfies the DisplayOps vtable. frameCallbackListener receives wl_callback.done and forwards it to FrameLoop.onFrameCallbackDone, which performs the identity check. EOF )" ``` --- ## Task 8: Migrate main terminal loop to FrameLoop (fixes the freeze) **Files:** - Modify: `src/main.zig` This is the largest task. It does three things: (1) creates a `FrameLoop` in `runTerminal`, (2) splits the scale/resize handling into observe (non-Vulkan) and apply (Vulkan) halves, (3) gates all Vulkan work on `canRender()`. - [ ] **Step 1: Add imports and FrameLoop instantiation** At the top of `src/main.zig`, ensure these imports exist (add missing): ```zig const wayland_client = @import("wayland-client"); const frame_loop_mod = @import("frame_loop"); ``` In `runTerminal`, after the `window` creation block and after `conn.display.roundtrip()` (around main.zig:137), add: ```zig var frame_loop = frame_loop_mod.FrameLoop.init( window.displayOps(conn.display), window.surfaceStateView(), ); defer frame_loop.deinit(); ``` - [ ] **Step 2: Wire FrameLoop into surface enter/leave listeners** In `src/wayland.zig`, extend `surfaceListener` (around line 1050) so it can notify a FrameLoop. Add a FrameLoop pointer field on `Window`: ```zig frame_loop: ?*FrameLoop = null, ``` Update `surfaceListener` to call show/hide hooks when visibility transitions: ```zig fn surfaceListener(_: *wl.Surface, event: wl.Surface.Event, window: *Window) void { const was_visible = window.state.visible(); switch (event) { .enter => |e| { const wl_out = e.output orelse return; window.handleSurfaceEnter(wl_out); window.scale_generation += 1; }, .leave => |e| { const wl_out = e.output orelse return; window.handleSurfaceLeave(wl_out); window.scale_generation += 1; }, .preferred_buffer_scale => {}, .preferred_buffer_transform => {}, } const now_visible = window.state.visible(); if (window.frame_loop) |loop| { if (was_visible and !now_visible) loop.onSurfaceHidden(); if (!was_visible and now_visible) loop.onSurfaceShown(); } } ``` Do the same for `xdgToplevelListener` (so the suspended flag transition fires the hook): ```zig fn xdgToplevelListener(_: *xdg.Toplevel, event: xdg.Toplevel.Event, window: *Window) void { const was_visible = window.state.visible(); switch (event) { .configure => |cfg| { if (cfg.width > 0) window.width = @intCast(cfg.width); if (cfg.height > 0) window.height = @intCast(cfg.height); applyToplevelStates(&window.state, std.mem.sliceAsBytes(cfg.states.slice())); }, .close => window.should_close = true, .configure_bounds => {}, .wm_capabilities => {}, } const now_visible = window.state.visible(); if (window.frame_loop) |loop| { if (was_visible and !now_visible) loop.onSurfaceHidden(); if (!was_visible and now_visible) loop.onSurfaceShown(); } } ``` And for `xdgSurfaceListener` (configured transitions from false→true): ```zig fn xdgSurfaceListener(surface: *xdg.Surface, event: xdg.Surface.Event, window: *Window) void { const was_visible = window.state.visible(); switch (event) { .configure => |cfg| { surface.ackConfigure(cfg.serial); window.state.configured = true; }, } const now_visible = window.state.visible(); if (window.frame_loop) |loop| { if (!was_visible and now_visible) loop.onSurfaceShown(); } } ``` Back in `src/main.zig`, right after `frame_loop` init, set: ```zig window.frame_loop = &frame_loop; defer window.frame_loop = null; ``` - [ ] **Step 3: Split the main loop's scale/resize block** Locate the main loop in `src/main.zig` (starts around line 246 `while (!window.should_close and p.isChildAlive())`). Identify the two blocks: - Scale-change block (around line 317-346): `if (current_scale != last_scale) { ... deviceWaitIdle ... recreateSwapchain ... }` - Size-change block (around line 348-380): `if (window.width != last_window_w or window.height != last_window_h) { ... deviceWaitIdle ... recreateSwapchain ... resize term/pty ... }` Replace the entire main loop body (from `while (!window.should_close ...)` to the closing `}` around line 596) with the shape below. Keep all the non-Vulkan logic unchanged (pty read, keyboard, pointer, selection, snapshot/render). The key change: Vulkan calls move inside an `if (frame_loop.canRender())` gate. ```zig var pollfds_extra = [_]std.posix.pollfd{ .{ .fd = p.master_fd, .events = std.posix.POLL.IN, .revents = 0 }, }; var read_buf: [8192]u8 = undefined; var key_buf: [32]u8 = undefined; var last_window_w = window.width; var last_window_h = window.height; var last_scale: i32 = geom.buffer_scale; var render_pending = true; var resize_pending = false; var scale_pending = false; while (!window.should_close and p.isChildAlive()) { const repeat_timeout_ms = remainingRepeatTimeoutMs(keyboard.nextRepeatDeadlineNs()); const timeout = computePollTimeoutMs(repeat_timeout_ms, render_pending and frame_loop.canRender()); try frame_loop.waitForWork(&pollfds_extra, timeout); // PTY output if (pollfds_extra[0].revents & std.posix.POLL.IN != 0) { while (true) { const n = p.read(&read_buf) catch |err| switch (err) { error.WouldBlock => break, error.InputOutput => break, else => return err, }; if (n == 0) break; term.write(read_buf[0..n]); render_pending = true; } } // Pointer events const ptr_cell_w = cell_w / @as(u32, @intCast(geom.buffer_scale)); const ptr_cell_h = cell_h / @as(u32, @intCast(geom.buffer_scale)); const prev_selection = activeSelectionSpan(selection); for (pointer.event_queue.items) |ev| { handlePointerSelectionEvent(&selection, ev, ptr_cell_w, ptr_cell_h, cols, rows); } const selection_changed = !std.meta.eql(activeSelectionSpan(selection), prev_selection); if (pointer.event_queue.items.len > 0) { pointer.event_queue.clearRetainingCapacity(); render_pending = true; } // Keyboard events (identical to existing body — paste/copy/encode) keyboard.tickRepeat(); for (keyboard.event_queue.items) |ev| { if (ev.action == .release) continue; if (isClipboardPasteEvent(ev)) { if (clipboard) |cb| { if (try cb.receiveSelectionText(alloc)) |text| { defer alloc.free(text); const encoded = term.encodePaste(text); for (encoded) |chunk| { if (chunk.len == 0) continue; _ = try p.write(chunk); } } } continue; } if (isClipboardCopyEvent(ev)) { _ = try copySelectionText(alloc, clipboard, term, activeSelectionSpan(selection), ev.serial); continue; } if (ev.utf8_len > 0) { _ = try p.write(ev.utf8[0..ev.utf8_len]); } else if (try encodeKeyboardEvent(term, ev, &key_buf)) |encoded| { _ = try p.write(encoded); } } keyboard.event_queue.clearRetainingCapacity(); // observeResize — detect changes, record pending flag, no Vulkan. const current_scale = window.bufferScale(); if (current_scale != last_scale) { scale_pending = true; render_pending = true; } if (window.width != last_window_w or window.height != last_window_h) { resize_pending = true; render_pending = true; } if (!shouldRenderFrame(render_pending, false, false)) continue; if (!frame_loop.canRender()) continue; // hidden — no Vulkan at all // applyPendingResize / applyPendingScale — Vulkan work, gated. if (scale_pending) { _ = try ctx.vkd.deviceWaitIdle(ctx.device); geom = try rebuildFaceForScale( &face, &atlas, font_lookup.path, font_lookup.index, font_size, window.bufferScale(), ); cell_w = geom.cell_w_px; cell_h = geom.cell_h_px; baseline = geom.baseline_px; render_cache.invalidateAfterResize(); term.render_state.dirty = .full; window.surface.setBufferScale(geom.buffer_scale); const buf_w = window.width * @as(u32, @intCast(geom.buffer_scale)); const buf_h = window.height * @as(u32, @intCast(geom.buffer_scale)); try ctx.recreateSwapchain(buf_w, buf_h); last_scale = geom.buffer_scale; scale_pending = false; } if (resize_pending) { const surf_cell_w = cell_w / @as(u32, @intCast(geom.buffer_scale)); const surf_cell_h = cell_h / @as(u32, @intCast(geom.buffer_scale)); const new_grid = gridSizeForWindow(window.width, window.height, surf_cell_w, surf_cell_h); const buf_w = window.width * @as(u32, @intCast(geom.buffer_scale)); const buf_h = window.height * @as(u32, @intCast(geom.buffer_scale)); if (new_grid.cols != cols or new_grid.rows != rows) { _ = try ctx.vkd.deviceWaitIdle(ctx.device); try ctx.recreateSwapchain(buf_w, buf_h); try term.resize(new_grid.cols, new_grid.rows); try p.resize(new_grid.cols, new_grid.rows); cols = new_grid.cols; rows = new_grid.rows; term.setReportedSize(.{ .rows = rows, .columns = cols, .cell_width = cell_w, .cell_height = cell_h, }); selection.committed = if (selection.committed) |span| clampSelectionSpan(span, cols, rows) else null; selection.active = if (selection.active) |span| clampSelectionSpan(span, cols, rows) else null; selection.anchor = if (selection.anchor) |point| clampGridPoint(point, cols, rows) else null; selection.hover = if (selection.hover) |point| clampGridPoint(point, cols, rows) else null; } else { _ = try ctx.vkd.deviceWaitIdle(ctx.device); try ctx.recreateSwapchain(buf_w, buf_h); } last_window_w = window.width; last_window_h = window.height; resize_pending = false; } // === render === (identical to existing body from snapshot through clearConsumedDirtyFlags) var frame_timing: FrameTiming = .{}; const previous_cursor = term.render_state.cursor; var section_timer = std.time.Timer.start() catch unreachable; try term.snapshot(); frame_timing.snapshot_us = usFromTimer(§ion_timer); section_timer = std.time.Timer.start() catch unreachable; const default_bg = term.backgroundColor(); const bg_uv = atlas.cursorUV(); const term_rows = term.render_state.row_data.items(.cells); const dirty_rows = term.render_state.row_data.items(.dirty); try render_cache.resizeRows(alloc, term_rows.len); const refresh_plan = planRowRefresh( if (term.render_state.dirty == .full or selection_changed) .full else .partial, dirty_rows, .{ .cursor = .{ .old_row = if (previous_cursor.viewport) |cursor| @intCast(cursor.y) else null, .new_row = if (term.render_state.cursor.viewport) |cursor| @intCast(cursor.y) else null, .old_col = if (previous_cursor.viewport) |cursor| @intCast(cursor.x) else null, .new_col = if (term.render_state.cursor.viewport) |cursor| @intCast(cursor.x) else null, .old_visible = previous_cursor.visible, .new_visible = term.render_state.cursor.visible, }, }, ); // PRESERVE the existing render body from line ~415 ("var rows_rebuilt") // through line ~584 ("frame_timing.gpu_submit_us = ..."). Those lines // are unchanged — copy them verbatim from the pre-refactor main loop. // The only change is the OUT_OF_DATE handler at the end of drawCells: // ctx.drawCells(...) catch |err| switch (err) { // error.OutOfDateKHR => { // _ = try ctx.vkd.deviceWaitIdle(ctx.device); // const buf_w = window.width * @as(u32, @intCast(geom.buffer_scale)); // const buf_h = window.height * @as(u32, @intCast(geom.buffer_scale)); // try ctx.recreateSwapchain(buf_w, buf_h); // frame_loop.forceArm(); // <-- ADDED // render_pending = true; // continue; // }, // else => return err, // }; frame_ring.push(frame_timing); if (sigusr1_received.swap(false, .acq_rel)) { printFrameStats(computeFrameStats(&frame_ring)); } clearConsumedDirtyFlags(&term.render_state.dirty, dirty_rows, refresh_plan); // Commit is already inside ctx.drawCells via queuePresentKHR. The // wl_surface.commit that backs it happens inside Vulkan WSI. We // explicitly request the next frame callback here. try frame_loop.commitRender(); render_pending = false; } printFrameStats(computeFrameStats(&frame_ring)); _ = try ctx.vkd.deviceWaitIdle(ctx.device); ``` **Important:** The rendering body (rows_rebuilt loop, atlas upload, instance upload, drawCells, frame_timing updates) between `planRowRefresh(...)` and `frame_ring.push(frame_timing)` is unchanged — copy it verbatim from the pre-refactor version. Only the OUT_OF_DATE switch arm gains `frame_loop.forceArm();`. - [ ] **Step 4: Build** Run: `make build` Expected: clean compile. - [ ] **Step 5: Run tests** Run: `make test` Expected: all existing + new tests pass. - [ ] **Step 6: Manual smoke test — launch waystty, verify normal operation** Run: `make run` Expected: waystty window opens, prompt appears, typing echoes, Ctrl-D exits cleanly. - [ ] **Step 7: Manual freeze regression test — the reason for this whole change** Run: `make run` Then in sway: 1. Start typing in waystty. 2. Switch workspaces (mod+2 or equivalent). 3. Wait 10 seconds. 4. Switch back. Expected: waystty is responsive on return; no hang, no stale display. - [ ] **Step 8: Commit** ```bash git add src/main.zig src/wayland.zig git commit -m "$(cat <<'EOF' Migrate main terminal loop to FrameLoop; fix hidden-workspace freeze Splits the scale/resize handler into observeResize (non-Vulkan, always runs) and applyPendingResize/Scale (Vulkan, gated on canRender). All Vulkan calls — deviceWaitIdle, recreateSwapchain, rebuildFaceForScale, drawCells — now happen only when the surface is visible. OUT_OF_DATE path calls forceArm() to retry without a callback. Fixes: waystty hanging when its window is moved to a hidden sway workspace. EOF )" ``` --- ## Task 9: Synthetic hidden-freeze regression test **Files:** - Modify: `src/frame_loop.zig` - [ ] **Step 1: Add regression test** Append to `src/frame_loop.zig`: ```zig test "hidden-freeze regression: pty flood while hidden never blocks" { var mock = try Mock.init(); defer mock.deinit(); var ts = try TestState.init(std.testing.allocator); defer ts.deinit(); var loop = FrameLoop.init(mock.ops(), ts.view()); defer loop.deinit(); // Initial render. try loop.commitRender(); const first_tok = loop.pending_token.?; loop.onFrameCallbackDone(first_tok); // Hide the surface: tracker leaves all outputs. ts.tracker.leaveOutput(1); loop.onSurfaceHidden(); try std.testing.expect(!loop.canRender()); // Simulate 100 iterations of "pty wrote more data, we want to render". // Under the gate, canRender is false every iteration and we never call // commitRender — so no Vulkan work, no blocking. var i: usize = 0; while (i < 100) : (i += 1) { try std.testing.expect(!loop.canRender()); } // Show again: tracker re-enters an output. try ts.tracker.enterOutput(1); loop.onSurfaceShown(); try std.testing.expect(loop.canRender()); // Normal render resumes. try loop.commitRender(); try std.testing.expect(loop.pending_token != null); const tok = loop.pending_token.?; loop.onFrameCallbackDone(tok); try std.testing.expect(loop.armed); } ``` - [ ] **Step 2: Run tests** Run: `make test` Expected: regression test passes alongside the existing FrameLoop tests. - [ ] **Step 3: Commit** ```bash git add src/frame_loop.zig git commit -m "$(cat <<'EOF' Add synthetic hidden-freeze regression test Exercises the hide → pty-flood → show sequence through the FrameLoop state machine. Verifies no canRender() call returns true while hidden, and that normal pacing resumes on show. EOF )" ``` --- ## Task 10: Migrate `runTextCoverageCompare` to FrameLoop **Files:** - Modify: `src/main.zig` - [ ] **Step 1: Replace the text-compare main loop body** In `src/main.zig`, locate `runTextCoverageCompare` (around line 2490). Replace its main loop block (the `while (!window.should_close) { ... }` around lines 2549-2623) with the FrameLoop-based version: ```zig var frame_loop = frame_loop_mod.FrameLoop.init( window.displayOps(conn.display), window.surfaceStateView(), ); defer frame_loop.deinit(); window.frame_loop = &frame_loop; defer window.frame_loop = null; var last_window_w = window.width; var last_window_h = window.height; var last_scale: i32 = geom.buffer_scale; while (!window.should_close) { try frame_loop.waitForWork(&.{}, 16); if (!frame_loop.canRender()) continue; const current_scale = window.bufferScale(); const scale_changed = current_scale != last_scale; const size_changed = window.width != last_window_w or window.height != last_window_h; if (scale_changed or size_changed) { _ = try ctx.vkd.deviceWaitIdle(ctx.device); if (scale_changed) { geom = try rebuildFaceForScale( &face, &atlas, font_lookup.path, font_lookup.index, config.font_size_px, current_scale, ); scene.deinit(alloc); scene = try buildTextCoverageCompareScene(alloc, &face, &atlas); window.surface.setBufferScale(geom.buffer_scale); try ctx.uploadAtlas(atlas.pixels); atlas.dirty = false; try ctx.uploadInstances(scene.instances.items); last_scale = current_scale; } const buf_w = window.width * @as(u32, @intCast(geom.buffer_scale)); const buf_h = window.height * @as(u32, @intCast(geom.buffer_scale)); try ctx.recreateSwapchain(buf_w, buf_h); last_window_w = window.width; last_window_h = window.height; } drawTextCoverageCompareFrame( &ctx, &scene, geom.cell_w_px, geom.cell_h_px, .{ 0.0, 0.0, 0.0, 1.0 }, ) catch |err| switch (err) { error.OutOfDateKHR => { _ = try ctx.vkd.deviceWaitIdle(ctx.device); const buf_w = window.width * @as(u32, @intCast(geom.buffer_scale)); const buf_h = window.height * @as(u32, @intCast(geom.buffer_scale)); try ctx.recreateSwapchain(buf_w, buf_h); last_window_w = window.width; last_window_h = window.height; frame_loop.forceArm(); continue; }, else => return err, }; try frame_loop.commitRender(); } _ = try ctx.vkd.deviceWaitIdle(ctx.device); ``` - [ ] **Step 2: Build and run the mode to verify** Run: `make build` Expected: clean compile. Run: `./zig-out/bin/waystty --text-compare` Expected: the text-coverage comparison window opens and renders normally. - [ ] **Step 3: Commit** ```bash git add src/main.zig git commit -m "$(cat <<'EOF' Migrate runTextCoverageCompare to FrameLoop Drops the manual 16ms sleep and prepareRead/cancelRead dance in favor of the shared readiness primitive. Same visual output; now also freeze-safe under workspace change. EOF )" ``` --- ## Task 11: Migrate `runDrawSmokeTest` to FrameLoop **Files:** - Modify: `src/main.zig` - [ ] **Step 1: Replace the draw-smoke main loop** In `src/main.zig`, locate `runDrawSmokeTest` (around line 2628). Replace the `var i: u32 = 0; while (i < 900) : (i += 1) { ... }` block with a FrameLoop-paced version that still runs for ~15 seconds. Before the loop: ```zig var frame_loop = frame_loop_mod.FrameLoop.init( window.displayOps(conn.display), window.surfaceStateView(), ); defer frame_loop.deinit(); window.frame_loop = &frame_loop; defer window.frame_loop = null; ``` Then the loop body becomes: ```zig const deadline_ns = @as(i128, std.time.nanoTimestamp()) + 15 * std.time.ns_per_s; while (std.time.nanoTimestamp() < deadline_ns and !window.should_close) { try frame_loop.waitForWork(&.{}, 16); if (!frame_loop.canRender()) continue; const baseline_coverage = renderer.coverageVariantParams(.baseline); ctx.drawCells(1, .{ cell_w, cell_h }, .{ 0.0, 0.0, 0.0, 1.0 }, baseline_coverage) catch |err| switch (err) { error.OutOfDateKHR => { _ = try ctx.vkd.deviceWaitIdle(ctx.device); try ctx.recreateSwapchain(window.width, window.height); frame_loop.forceArm(); continue; }, else => return err, }; try frame_loop.commitRender(); } ``` - [ ] **Step 2: Build and run** Run: `make build` Expected: clean compile. Run: `./zig-out/bin/waystty --draw-smoke-test` Expected: renders the 'M' glyph for ~15 seconds, then exits. - [ ] **Step 3: Commit** ```bash git add src/main.zig git commit -m "$(cat <<'EOF' Migrate runDrawSmokeTest to FrameLoop Replaces the fixed 900-iteration + manual event-pump pattern with FrameLoop pacing. Uses a 15-second wall-clock deadline instead of a frame count. EOF )" ``` --- ## Task 12: Add `WAYSTTY_BENCH_UNTHROTTLED` env var for bench mode **Files:** - Modify: `src/main.zig` - [ ] **Step 1: Read env var at bench setup** In `src/main.zig`, inside `runTerminal`, near where `WAYSTTY_BENCH` is read (around line 201), add: ```zig const bench_unthrottled = std.posix.getenv("WAYSTTY_BENCH_UNTHROTTLED") != null and std.posix.getenv("WAYSTTY_BENCH") != null; ``` - [ ] **Step 2: Gate FrameLoop.canRender in the main loop** In the main loop, change the visibility gate line: ```zig if (!frame_loop.canRender()) continue; // hidden — no Vulkan at all ``` to: ```zig if (!bench_unthrottled and !frame_loop.canRender()) continue; ``` And change the `commitRender` call near the end of the loop to: ```zig if (!bench_unthrottled) try frame_loop.commitRender(); ``` (When unthrottled, we never gate and never request frame callbacks — effectively the pre-refactor eager loop. Freeze-safety is forfeit, which is documented.) - [ ] **Step 3: Emit a banner on bench startup** Near the top of `runTerminal`, after reading `bench_unthrottled`, add: ```zig if (std.posix.getenv("WAYSTTY_BENCH") != null) { if (bench_unthrottled) { std.debug.print("[bench] mode: UNTHROTTLED (not freeze-safe)\n", .{}); } else { std.debug.print("[bench] mode: THROTTLED (vsync-paced)\n", .{}); } } ``` - [ ] **Step 4: Run bench twice to verify both paths work** Run: `make bench` Expected: bench runs, prints `[bench] mode: THROTTLED`, produces frame timing output. Run: `WAYSTTY_BENCH=1 WAYSTTY_BENCH_UNTHROTTLED=1 ./zig-out/bin/waystty 2>bench.log || true; grep -A 12 "waystty frame timing" bench.log` Expected: bench runs, prints `[bench] mode: UNTHROTTLED`, produces frame timing output (typically more frames/sec than throttled). - [ ] **Step 5: Commit** ```bash git add src/main.zig git commit -m "$(cat <<'EOF' Add WAYSTTY_BENCH_UNTHROTTLED escape hatch Bypasses FrameLoop gating and callback requests in bench mode for raw throughput measurement. Explicitly not freeze-safe — documented in the spec. Emits a banner on startup so bench logs are unambiguous. EOF )" ``` --- ## Task 13: Add `--hidden-freeze-regression` manual mode **Files:** - Modify: `src/main.zig` - [ ] **Step 1: Register the flag and function** In `src/main.zig` `pub fn main`, add after the existing mode dispatches (around line 91): ```zig if (args.len >= 2 and std.mem.eql(u8, args[1], "--hidden-freeze-regression")) { return runHiddenFreezeRegression(alloc); } ``` - [ ] **Step 2: Implement the mode** Add at the bottom of `src/main.zig`: ```zig fn runHiddenFreezeRegression(alloc: std.mem.Allocator) !void { const stdout = std.io.getStdOut().writer(); try stdout.writeAll( \\ \\hidden-freeze regression mode \\----------------------------- \\1. This process will spawn waystty and start writing to its pty. \\2. Move the window to a different workspace. \\3. Wait 5 seconds. \\4. Move the window back. \\5. The window should be responsive and show fresh output. \\ \\Press enter to start, Ctrl-C to abort. \\ ); var buf: [16]u8 = undefined; _ = try std.io.getStdIn().reader().read(&buf); // Reuse runTerminal — it is the code path we're validating. The regression // is whether it freezes; manual observation by the operator confirms. return runTerminal(alloc); } ``` - [ ] **Step 3: Build and smoke-test** Run: `make build && ./zig-out/bin/waystty --hidden-freeze-regression` Expected: help text prints; on enter, waystty window opens normally. Follow the instructions manually under sway to confirm. - [ ] **Step 4: Commit** ```bash git add src/main.zig git commit -m "$(cat <<'EOF' Add --hidden-freeze-regression manual test mode Prints operator instructions and spawns a normal waystty session. The freeze fix is validated by moving the window to another workspace and back; the mode is purely for documentation and repeatable manual QA. EOF )" ``` --- ## Task 14: Final verification pass - [ ] **Step 1: Full test suite** Run: `make test` Expected: all tests pass (pty, scale_tracker, wayland, main, vt, font, renderer, frame_loop). - [ ] **Step 2: Clean build** Run: `make clean && make build` Expected: clean compile from scratch. - [ ] **Step 3: Manual multi-workspace verification** Run: `make run` Then under sway: 1. Type in waystty. 2. Switch to another workspace (mod+2). 3. Wait 30 seconds. 4. Switch back (mod+1). 5. Confirm: responsive, fresh prompt state. 6. Resize the window. 7. Move to another workspace mid-resize, switch back. 8. Confirm: correct size, no crash. - [ ] **Step 4: Bench smoke** Run: `make bench` Expected: bench runs to completion, throttled-mode banner, timing output printed. - [ ] **Step 5: If all green, push** Ask the user: "All steps green. Want me to push to origin?" Wait for explicit yes before pushing. --- ## Notes for the implementer - **Zig idioms.** `catch |err| switch (err) { ... }` is the idiom for handling specific errors. `_ = try foo()` discards non-error results. `std.debug.assert` in Zig is compiled out in ReleaseFast — use it for preconditions, not correctness. - **zig-wayland bindings.** Method signatures on `*wl.Display`, `*wl.Surface`, `*wl.Callback` are what the scanner generates. If a name in this plan doesn't match (e.g. `setListener` signature), read `zig-cache/.../wayland.zig` (the generated bindings) and adapt. - **Listeners run synchronously.** Inside `dispatchPending`, every listener call is synchronous on the main thread. No locks needed anywhere in FrameLoop. - **Commit hygiene.** Each task ends with a commit. Do not squash; each commit should compile and pass tests independently so bisect works. - **If a task fails to compile.** Do not amend the prior commit. Add the fix as a new commit so history shows the trial. - **If tests pass but the freeze still reproduces.** Return to Task 8 Step 7 — something in the gate isn't covering a Vulkan call. Use `RUST_BACKTRACE=full` equivalent (`ZIG_DEBUG` or attach gdb `thread apply all bt`) during freeze to find the stuck frame.