c05013f9

Add waystty implementation plan

a73x 2026-04-08 05:30

Commit message

Add waystty implementation plan

Monolithic plan covering all seven phases: scaffolding, PTY, VT wrapper,
headless proof-of-life, font rendering, Wayland protocol, Vulkan
renderer, and full integration. TDD with bite-sized tasks.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/superpowers/plans/2026-04-07-waystty-implementation.md

@@ @@ -0,0 +1,4288 @@ @@
+# waystty 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:** Build waystty — a minimal, hackable Wayland terminal emulator in Zig — using libghostty-vt for terminal emulation, Vulkan for rendering, and freetype for glyph rasterization.
+**Architecture:** Six modules (`main`, `wayland`, `vt`, `pty`, `font`, `renderer`). Single-threaded `poll()` event loop multiplexing Wayland and PTY file descriptors. Vulkan renders the terminal grid via a single instanced draw call per frame, sampling a glyph atlas texture.
+**Tech Stack:** Zig 0.15, libghostty-vt (Zig module), zig-wayland, vulkan-zig, freetype2, fontconfig, xkbcommon, wayland-client, glslc.
+## Important Deviation From Spec
+The spec describes wrapping libghostty-vt via `@cImport <ghostty/vt.h>`. During planning research we discovered that **ghostty-vt is published as a native Zig module** with an idiomatic Zig API. We use the Zig module directly — no `@cImport` needed. This simplifies `vt.zig` significantly.
+The reference for the Zig module API is `example/zig-vt/` in the ghostty repo. Engineers executing this plan should consult that example when the API shape isn't clear from this plan.
+## Reference Files
+When in doubt, consult these external references:
+- **ghostty-vt Zig API**: `ghostty-org/ghostty:example/zig-vt/src/main.zig` and `build.zig`
+- **ghostty-vt C headers** (for semantics reference): `ghostty-org/ghostty:include/ghostty/vt.h`
+- **Ghostling C reference**: `ghostty-org/ghostling:main.c` — full end-to-end terminal
+- **zig-wayland example**: `ifreund/zig-wayland:example/hello/hello.zig`
+- **vulkan-zig examples**: `Snektron/vulkan-zig:examples/`
+---
+## Phase 0: Project Scaffolding
+### Task 0.1: Initialize project and git
+**Files:**
+- Create: `.gitignore`
+- Already exists: `docs/superpowers/specs/2026-04-07-waystty-design.md`
+- Already exists: `.git/`
+- [ ] **Step 1: Create .gitignore**
+```
+zig-out/
+.zig-cache/
+*.o
+*.swp
+```
+- [ ] **Step 2: Commit**
+```bash
+git add .gitignore
+git commit -m "chore: add gitignore"
+```
+---
+### Task 0.2: Create build.zig.zon with dependencies
+**Files:**
+- Create: `build.zig.zon`
+- [ ] **Step 1: Write build.zig.zon**
+```zig
+.{
+    .name = .waystty,
+    .version = "0.0.1",
+    .fingerprint = 0x1234567890abcdef,
+    .minimum_zig_version = "0.15.0",
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "src",
+        "shaders",
+    },
+    .dependencies = .{
+        .wayland = .{
+            .url = "git+https://github.com/ifreund/zig-wayland",
+            .hash = "",
+        },
+        .vulkan = .{
+            .url = "git+https://github.com/Snektron/vulkan-zig",
+            .hash = "",
+        },
+        .vulkan_headers = .{
+            .url = "git+https://github.com/KhronosGroup/Vulkan-Headers",
+            .hash = "",
+        },
+        .ghostty = .{
+            .url = "git+https://github.com/ghostty-org/ghostty",
+            .hash = "",
+            .lazy = true,
+        },
+    },
+}
+```
+- [ ] **Step 2: Fetch dependencies to populate hashes**
+```bash
+zig fetch --save git+https://github.com/ifreund/zig-wayland
+zig fetch --save git+https://github.com/Snektron/vulkan-zig
+zig fetch --save git+https://github.com/KhronosGroup/Vulkan-Headers
+zig fetch --save git+https://github.com/ghostty-org/ghostty
+```
+Expected: each command updates `build.zig.zon` with the correct hash.
+- [ ] **Step 3: Generate fingerprint**
+Edit `build.zig.zon` and change the `.fingerprint` value to a unique `u64`. Zig will print an error with the expected value when you first try to build — use that.
+- [ ] **Step 4: Commit**
+```bash
+git add build.zig.zon
+git commit -m "chore: add build.zig.zon with dependencies"
+```
+---
+### Task 0.3: Create minimal build.zig
+**Files:**
+- Create: `build.zig`
+- Create: `src/main.zig`
+- [ ] **Step 1: Write minimal src/main.zig**
+```zig
+const std = @import("std");
+pub fn main() !void {
+    std.debug.print("waystty\n", .{});
+}
+```
+- [ ] **Step 2: Write initial build.zig (executable only, deps added later)**
+```zig
+const std = @import("std");
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+    const exe = b.addExecutable(.{
+        .name = "waystty",
+        .root_source_file = b.path("src/main.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    b.installArtifact(exe);
+    const run_cmd = b.addRunArtifact(exe);
+    run_cmd.step.dependOn(b.getInstallStep());
+    if (b.args) |args| run_cmd.addArgs(args);
+    const run_step = b.step("run", "Run waystty");
+    run_step.dependOn(&run_cmd.step);
+    const test_step = b.step("test", "Run unit tests");
+    const tests = b.addTest(.{
+        .root_source_file = b.path("src/main.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    test_step.dependOn(&b.addRunArtifact(tests).step);
+}
+```
+- [ ] **Step 3: Build and run**
+```bash
+zig build run
+```
+Expected: prints `waystty`.
+- [ ] **Step 4: Commit**
+```bash
+git add build.zig src/main.zig
+git commit -m "chore: minimal build.zig and main.zig"
+```
+---
+### Task 0.4: Add ghostty-vt Zig module to build.zig
+**Files:**
+- Modify: `build.zig`
+- [ ] **Step 1: Create src/vt.zig stub that imports ghostty-vt**
+```zig
+const std = @import("std");
+const ghostty_vt = @import("ghostty-vt");
+test "ghostty-vt module imports" {
+    // Smoke test — just reference the module
+    _ = ghostty_vt;
+}
+```
+- [ ] **Step 2: Modify build.zig to expose the ghostty-vt module**
+Add after `const exe = b.addExecutable(...)` and before `b.installArtifact(exe);`:
+```zig
+if (b.lazyDependency("ghostty", .{
+    .target = target,
+    .optimize = optimize,
+})) |ghostty_dep| {
+    exe.root_module.addImport("ghostty-vt", ghostty_dep.module("ghostty-vt"));
+}
+```
+Also add the same for the test step, and add `src/vt.zig` as a module that `main.zig` can import:
+```zig
+const vt_module = b.addModule("vt", .{
+    .root_source_file = b.path("src/vt.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+if (b.lazyDependency("ghostty", .{
+    .target = target,
+    .optimize = optimize,
+})) |ghostty_dep| {
+    vt_module.addImport("ghostty-vt", ghostty_dep.module("ghostty-vt"));
+}
+exe.root_module.addImport("vt", vt_module);
+```
+- [ ] **Step 3: Update main.zig to import vt**
+```zig
+const std = @import("std");
+const vt = @import("vt");
+pub fn main() !void {
+    std.debug.print("waystty\n", .{});
+    _ = vt;
+}
+```
+- [ ] **Step 4: Build**
+```bash
+zig build
+```
+Expected: builds successfully. First build will be slow as it compiles ghostty-vt.
+- [ ] **Step 5: Commit**
+```bash
+git add build.zig src/main.zig src/vt.zig
+git commit -m "build: wire ghostty-vt module"
+```
+---
+## Phase 1: PTY Module
+### Task 1.1: Create pty.zig with forkpty wrapper — failing test first
+**Files:**
+- Create: `src/pty.zig`
+- Modify: `build.zig` (add pty module and test step)
+- [ ] **Step 1: Write failing test for Pty.spawn**
+Create `src/pty.zig`:
+```zig
+const std = @import("std");
+const c = @cImport({
+    @cInclude("pty.h");
+    @cInclude("termios.h");
+    @cInclude("unistd.h");
+    @cInclude("sys/ioctl.h");
+    @cInclude("fcntl.h");
+    @cInclude("sys/wait.h");
+});
+pub const Pty = struct {
+    master_fd: std.posix.fd_t,
+    child_pid: std.posix.pid_t,
+    pub const SpawnOptions = struct {
+        cols: u16,
+        rows: u16,
+        shell: []const u8,
+    };
+    pub fn spawn(opts: SpawnOptions) !Pty {
+        _ = opts;
+        return error.NotImplemented;
+    }
+    pub fn deinit(self: *Pty) void {
+        _ = self;
+    }
+};
+test "Pty.spawn launches /bin/sh and returns valid fd" {
+    var pty = try Pty.spawn(.{
+        .cols = 80,
+        .rows = 24,
+        .shell = "/bin/sh",
+    });
+    defer pty.deinit();
+    try std.testing.expect(pty.master_fd >= 0);
+    try std.testing.expect(pty.child_pid > 0);
+}
+```
+- [ ] **Step 2: Register pty module and test step in build.zig**
+Add to `build.zig` (alongside the `vt_module` section):
+```zig
+const pty_module = b.addModule("pty", .{
+    .root_source_file = b.path("src/pty.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+pty_module.link_libc = true;
+exe.root_module.addImport("pty", pty_module);
+```
+And extend the test step to also run pty tests:
+```zig
+const pty_tests = b.addTest(.{
+    .root_source_file = b.path("src/pty.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+pty_tests.linkLibC();
+pty_tests.linkSystemLibrary("util"); // for forkpty
+test_step.dependOn(&b.addRunArtifact(pty_tests).step);
+```
+- [ ] **Step 3: Run the failing test**
+```bash
+zig build test
+```
+Expected: FAIL with `error.NotImplemented`.
+- [ ] **Step 4: Implement Pty.spawn using forkpty**
+Replace the body of `spawn`:
+```zig
+pub fn spawn(opts: SpawnOptions) !Pty {
+    var master: c_int = undefined;
+    var winsize = c.struct_winsize{
+        .ws_row = opts.rows,
+        .ws_col = opts.cols,
+        .ws_xpixel = 0,
+        .ws_ypixel = 0,
+    };
+    const pid = c.forkpty(&master, null, null, &winsize);
+    if (pid < 0) return error.ForkptyFailed;
+    if (pid == 0) {
+        // Child process
+        _ = c.setenv("TERM", "xterm-256color", 1);
+        const shell_z = std.heap.page_allocator.dupeZ(u8, opts.shell) catch std.process.exit(1);
+        const argv = [_:null]?[*:0]const u8{ shell_z.ptr, null };
+        const envp: [*:null]?[*:0]const u8 = @ptrCast(std.c.environ);
+        _ = std.c.execve(shell_z.ptr, &argv, envp);
+        std.process.exit(1);
+    }
+    // Parent: set master fd non-blocking
+    const flags = try std.posix.fcntl(master, std.posix.F.GETFL, 0);
+    _ = try std.posix.fcntl(master, std.posix.F.SETFL, flags | @as(u32, @bitCast(std.posix.O{ .NONBLOCK = true })));
+    return .{
+        .master_fd = master,
+        .child_pid = pid,
+    };
+}
+pub fn deinit(self: *Pty) void {
+    std.posix.close(self.master_fd);
+    _ = std.c.kill(self.child_pid, std.c.SIG.TERM);
+    _ = std.c.waitpid(self.child_pid, null, 0);
+}
+```
+- [ ] **Step 5: Run test**
+```bash
+zig build test
+```
+Expected: PASS.
+- [ ] **Step 6: Commit**
+```bash
+git add src/pty.zig build.zig
+git commit -m "feat(pty): spawn child shell via forkpty"
+```
+---
+### Task 1.2: Add Pty.read/write helpers
+**Files:**
+- Modify: `src/pty.zig`
+- [ ] **Step 1: Write failing test**
+Add to `src/pty.zig`:
+```zig
+test "Pty.write and read echoes through shell" {
+    var pty = try Pty.spawn(.{
+        .cols = 80,
+        .rows = 24,
+        .shell = "/bin/sh",
+    });
+    defer pty.deinit();
+    // Give shell a moment to start
+    std.Thread.sleep(100 * std.time.ns_per_ms);
+    // Write a command
+    _ = try pty.write("echo hello\n");
+    // Drain output for up to 1 second
+    var buf: [4096]u8 = undefined;
+    var seen_hello = false;
+    const deadline = std.time.nanoTimestamp() + 1 * std.time.ns_per_s;
+    while (std.time.nanoTimestamp() < deadline) {
+        const n = pty.read(&buf) catch |err| switch (err) {
+            error.WouldBlock => {
+                std.Thread.sleep(10 * std.time.ns_per_ms);
+                continue;
+            },
+            else => return err,
+        };
+        if (std.mem.indexOf(u8, buf[0..n], "hello") != null) {
+            seen_hello = true;
+            break;
+        }
+    }
+    try std.testing.expect(seen_hello);
+}
+```
+- [ ] **Step 2: Run failing test**
+```bash
+zig build test
+```
+Expected: FAIL (read/write don't exist yet).
+- [ ] **Step 3: Implement read and write**
+Add methods to `Pty`:
+```zig
+pub fn read(self: *Pty, buf: []u8) !usize {
+    return std.posix.read(self.master_fd, buf) catch |err| switch (err) {
+        error.WouldBlock => error.WouldBlock,
+        else => err,
+    };
+}
+pub fn write(self: *Pty, data: []const u8) !usize {
+    return std.posix.write(self.master_fd, data);
+}
+```
+- [ ] **Step 4: Run test**
+```bash
+zig build test
+```
+Expected: PASS.
+- [ ] **Step 5: Commit**
+```bash
+git add src/pty.zig
+git commit -m "feat(pty): add read/write helpers"
+```
+---
+### Task 1.3: Add Pty.resize
+**Files:**
+- Modify: `src/pty.zig`
+- [ ] **Step 1: Write failing test**
+Add to `src/pty.zig`:
+```zig
+test "Pty.resize sets winsize via ioctl" {
+    var pty = try Pty.spawn(.{
+        .cols = 80,
+        .rows = 24,
+        .shell = "/bin/sh",
+    });
+    defer pty.deinit();
+    try pty.resize(120, 40);
+    var ws: c.struct_winsize = undefined;
+    const rc = c.ioctl(pty.master_fd, c.TIOCGWINSZ, &ws);
+    try std.testing.expectEqual(@as(c_int, 0), rc);
+    try std.testing.expectEqual(@as(c_ushort, 120), ws.ws_col);
+    try std.testing.expectEqual(@as(c_ushort, 40), ws.ws_row);
+}
+```
+- [ ] **Step 2: Run failing test**
+```bash
+zig build test
+```
+Expected: FAIL (resize doesn't exist).
+- [ ] **Step 3: Implement resize**
+```zig
+pub fn resize(self: *Pty, cols: u16, rows: u16) !void {
+    var ws = c.struct_winsize{
+        .ws_row = rows,
+        .ws_col = cols,
+        .ws_xpixel = 0,
+        .ws_ypixel = 0,
+    };
+    if (c.ioctl(self.master_fd, c.TIOCSWINSZ, &ws) < 0) {
+        return error.IoctlFailed;
+    }
+}
+```
+- [ ] **Step 4: Run test**
+```bash
+zig build test
+```
+Expected: PASS.
+- [ ] **Step 5: Commit**
+```bash
+git add src/pty.zig
+git commit -m "feat(pty): add resize"
+```
+---
+## Phase 2: VT Module (libghostty-vt wrapper)
+**⚠️ Implementer note:** The exact ghostty-vt Zig API must be discovered from the upstream example. Before writing Task 2.x steps, read `ghostty-org/ghostty:example/zig-vt/src/main.zig` to confirm the exact type and function names. The code below uses plausible names that match the C API semantics — adjust to match the real Zig API.
+### Task 2.1: Discover the ghostty-vt Zig API
+**Files:**
+- Modify: `src/vt.zig` (documentation comments)
+- [ ] **Step 1: Fetch the upstream example**
+```bash
+cd .zig-cache/p && find . -name "main.zig" -path "*example/zig-vt*" | head -1
+```
+Expected: prints a path inside the fetched ghostty dependency.
+- [ ] **Step 2: Read the example and take notes in src/vt.zig**
+Read the `main.zig` and `build.zig` of `example/zig-vt`. At the top of `src/vt.zig`, write a doc comment listing the actual types and methods you found:
+```zig
+//! vt.zig — wrapper around the ghostty-vt Zig module.
+//!
+//! Upstream API observed from example/zig-vt/src/main.zig:
+//!   const ghostty_vt = @import("ghostty-vt");
+//!   ghostty_vt.Terminal — init/deinit, write(bytes), resize(cols, rows)
+//!   ghostty_vt.KeyEncoder — init, syncFromTerminal, encode
+//!   ghostty_vt.MouseEncoder — init, syncFromTerminal, encode
+//!   ghostty_vt.RenderState — init, update, rowIterator
+//!
+//! The implementer should update these notes with the exact type and
+//! method names found in the pinned version of ghostty-vt before
+//! continuing to Task 2.2. If upstream names differ, tasks 2.2-2.7
+//! must be adjusted to match.
+```
+- [ ] **Step 3: Commit notes**
+```bash
+git add src/vt.zig
+git commit -m "docs(vt): note upstream ghostty-vt API shape"
+```
+---
+### Task 2.2: Wrap Terminal lifecycle
+**Files:**
+- Modify: `src/vt.zig`
+- [ ] **Step 1: Write failing test**
+Add to `src/vt.zig`:
+```zig
+test "Terminal init/deinit" {
+    var term = try Terminal.init(std.testing.allocator, .{
+        .cols = 80,
+        .rows = 24,
+        .max_scrollback = 1000,
+    });
+    defer term.deinit();
+    try std.testing.expectEqual(@as(u16, 80), term.cols);
+    try std.testing.expectEqual(@as(u16, 24), term.rows);
+}
+```
+- [ ] **Step 2: Register vt tests in build.zig**
+Add a `vt_tests` block alongside `pty_tests` in `build.zig`:
+```zig
+const vt_tests = b.addTest(.{
+    .root_source_file = b.path("src/vt.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+if (b.lazyDependency("ghostty", .{
+    .target = target,
+    .optimize = optimize,
+})) |ghostty_dep| {
+    vt_tests.root_module.addImport("ghostty-vt", ghostty_dep.module("ghostty-vt"));
+}
+test_step.dependOn(&b.addRunArtifact(vt_tests).step);
+```
+- [ ] **Step 3: Run failing test**
+```bash
+zig build test
+```
+Expected: FAIL (Terminal not defined).
+- [ ] **Step 4: Implement Terminal.init/deinit**
+Replace the body of `src/vt.zig`:
+```zig
+const std = @import("std");
+const ghostty_vt = @import("ghostty-vt");
+pub const InitOptions = struct {
+    cols: u16,
+    rows: u16,
+    max_scrollback: u32 = 1000,
+};
+pub const Terminal = struct {
+    inner: ghostty_vt.Terminal,
+    cols: u16,
+    rows: u16,
+    pub fn init(allocator: std.mem.Allocator, opts: InitOptions) !Terminal {
+        const inner = try ghostty_vt.Terminal.init(allocator, .{
+            .cols = opts.cols,
+            .rows = opts.rows,
+            .max_scrollback = opts.max_scrollback,
+        });
+        return .{
+            .inner = inner,
+            .cols = opts.cols,
+            .rows = opts.rows,
+        };
+    }
+    pub fn deinit(self: *Terminal) void {
+        self.inner.deinit();
+    }
+};
+```
+**If the upstream Terminal.init signature differs from this** (e.g. it returns a pointer, or the options struct has different fields), adjust to match the real signature from `example/zig-vt`.
+- [ ] **Step 5: Run test**
+```bash
+zig build test
+```
+Expected: PASS.
+- [ ] **Step 6: Commit**
+```bash
+git add src/vt.zig build.zig
+git commit -m "feat(vt): Terminal init/deinit wrapper"
+```
+---
+### Task 2.3: Terminal.write (feed bytes to VT parser)
+**Files:**
+- Modify: `src/vt.zig`
+- [ ] **Step 1: Write failing test**
+Add to `src/vt.zig`:
+```zig
+test "Terminal.write feeds bytes to VT parser" {
+    var term = try Terminal.init(std.testing.allocator, .{
+        .cols = 80,
+        .rows = 24,
+    });
+    defer term.deinit();
+    try term.write("Hello");
+    // We can't easily assert on internal state here yet — that's Task 2.4.
+    // Just verify the call succeeds.
+}
+```
+- [ ] **Step 2: Run failing test**
+```bash
+zig build test
+```
+Expected: FAIL (`write` not defined on Terminal).
+- [ ] **Step 3: Implement Terminal.write**
+Add to `Terminal`:
+```zig
+pub fn write(self: *Terminal, bytes: []const u8) !void {
+    try self.inner.write(bytes);
+}
+```
+Adjust to match the actual upstream method name if different (e.g. `vtWrite`, `feed`, etc.).
+- [ ] **Step 4: Run test**
+```bash
+zig build test
+```
+Expected: PASS.
+- [ ] **Step 5: Commit**
+```bash
+git add src/vt.zig
+git commit -m "feat(vt): Terminal.write"
+```
+---
+### Task 2.4: Render state snapshot and row iteration
+**Files:**
+- Modify: `src/vt.zig`
+- [ ] **Step 1: Write failing test**
+Add to `src/vt.zig`:
+```zig
+test "RenderState iterates cells after write" {
+    var term = try Terminal.init(std.testing.allocator, .{
+        .cols = 80,
+        .rows = 24,
+    });
+    defer term.deinit();
+    try term.write("Hi");
+    var render_state = try RenderState.init(std.testing.allocator);
+    defer render_state.deinit();
+    try render_state.update(&term);
+    // First row should contain 'H' at col 0, 'i' at col 1.
+    var row_iter = try render_state.rowIterator();
+    defer row_iter.deinit();
+    const first_row = (try row_iter.next()) orelse return error.NoRow;
+    defer first_row.deinit();
+    var cells = first_row.cells();
+    defer cells.deinit();
+    const cell0 = (try cells.next()) orelse return error.NoCell;
+    try std.testing.expectEqual(@as(u21, 'H'), cell0.codepoint);
+    const cell1 = (try cells.next()) orelse return error.NoCell;
+    try std.testing.expectEqual(@as(u21, 'i'), cell1.codepoint);
+}
+```
+- [ ] **Step 2: Run failing test**
+```bash
+zig build test
+```
+Expected: FAIL (RenderState etc. not defined).
+- [ ] **Step 3: Implement RenderState wrapper**
+Add to `src/vt.zig`:
+```zig
+pub const Cell = struct {
+    codepoint: u21,
+    fg: Rgb,
+    bg: Rgb,
+    bold: bool,
+    italic: bool,
+    inverse: bool,
+    underline: bool,
+};
+pub const Rgb = struct { r: u8, g: u8, b: u8 };
+pub const RenderState = struct {
+    inner: ghostty_vt.RenderState,
+    pub fn init(allocator: std.mem.Allocator) !RenderState {
+        return .{ .inner = try ghostty_vt.RenderState.init(allocator) };
+    }
+    pub fn deinit(self: *RenderState) void {
+        self.inner.deinit();
+    }
+    pub fn update(self: *RenderState, term: *Terminal) !void {
+        try self.inner.update(&term.inner);
+    }
+    pub fn rowIterator(self: *RenderState) !RowIterator {
+        return .{ .inner = try self.inner.rowIterator() };
+    }
+};
+pub const RowIterator = struct {
+    inner: ghostty_vt.RenderState.RowIterator,
+    pub fn deinit(self: *RowIterator) void {
+        self.inner.deinit();
+    }
+    pub fn next(self: *RowIterator) !?Row {
+        const row = (try self.inner.next()) orelse return null;
+        return .{ .inner = row };
+    }
+};
+pub const Row = struct {
+    inner: ghostty_vt.RenderState.Row,
+    pub fn deinit(self: *Row) void {
+        self.inner.deinit();
+    }
+    pub fn cells(self: *Row) CellIterator {
+        return .{ .inner = self.inner.cells() };
+    }
+};
+pub const CellIterator = struct {
+    inner: ghostty_vt.RenderState.CellIterator,
+    pub fn deinit(self: *CellIterator) void {
+        self.inner.deinit();
+    }
+    pub fn next(self: *CellIterator) !?Cell {
+        const c = (try self.inner.next()) orelse return null;
+        return .{
+            .codepoint = c.codepoint,
+            .fg = .{ .r = c.fg.r, .g = c.fg.g, .b = c.fg.b },
+            .bg = .{ .r = c.bg.r, .g = c.bg.g, .b = c.bg.b },
+            .bold = c.bold,
+            .italic = c.italic,
+            .inverse = c.inverse,
+            .underline = c.underline,
+        };
+    }
+};
+```
+**⚠️ This code assumes an API shape. Adjust every field name and method to match what's in `example/zig-vt/src/main.zig`.** The structure (init/deinit/iterator-of-iterator) is correct based on the C API; the exact Zig names may differ.
+- [ ] **Step 4: Run test**
+```bash
+zig build test
+```
+Expected: PASS (after adjusting to real API).
+- [ ] **Step 5: Commit**
+```bash
+git add src/vt.zig
+git commit -m "feat(vt): RenderState with row/cell iteration"
+```
+---
+### Task 2.5: Key encoder
+**Files:**
+- Modify: `src/vt.zig`
+- [ ] **Step 1: Write failing test**
+Add to `src/vt.zig`:
+```zig
+test "KeyEncoder encodes a keystroke" {
+    var term = try Terminal.init(std.testing.allocator, .{
+        .cols = 80,
+        .rows = 24,
+    });
+    defer term.deinit();
+    var encoder = try KeyEncoder.init(std.testing.allocator);
+    defer encoder.deinit();
+    try encoder.syncFromTerminal(&term);
+    var buf: [64]u8 = undefined;
+    const n = try encoder.encode(&buf, .{
+        .keysym = 'a',
+        .modifiers = .{},
+        .action = .press,
+    });
+    try std.testing.expect(n >= 1);
+    try std.testing.expectEqual(@as(u8, 'a'), buf[0]);
+}
+```
+- [ ] **Step 2: Run failing test**
+```bash
+zig build test
+```
+Expected: FAIL.
+- [ ] **Step 3: Implement KeyEncoder**
+Add to `src/vt.zig`:
+```zig
+pub const Modifiers = struct {
+    ctrl: bool = false,
+    shift: bool = false,
+    alt: bool = false,
+    super: bool = false,
+};
+pub const KeyAction = enum { press, release, repeat };
+pub const KeyEvent = struct {
+    keysym: u32,
+    modifiers: Modifiers,
+    action: KeyAction,
+};
+pub const KeyEncoder = struct {
+    inner: ghostty_vt.KeyEncoder,
+    pub fn init(allocator: std.mem.Allocator) !KeyEncoder {
+        return .{ .inner = try ghostty_vt.KeyEncoder.init(allocator) };
+    }
+    pub fn deinit(self: *KeyEncoder) void {
+        self.inner.deinit();
+    }
+    pub fn syncFromTerminal(self: *KeyEncoder, term: *Terminal) !void {
+        try self.inner.syncFromTerminal(&term.inner);
+    }
+    pub fn encode(self: *KeyEncoder, buf: []u8, ev: KeyEvent) !usize {
+        const inner_ev = ghostty_vt.KeyEvent{
+            .keysym = ev.keysym,
+            .modifiers = .{
+                .ctrl = ev.modifiers.ctrl,
+                .shift = ev.modifiers.shift,
+                .alt = ev.modifiers.alt,
+                .super = ev.modifiers.super,
+            },
+            .action = switch (ev.action) {
+                .press => .press,
+                .release => .release,
+                .repeat => .repeat,
+            },
+        };
+        return try self.inner.encode(buf, inner_ev);
+    }
+};
+```
+- [ ] **Step 4: Run test**
+```bash
+zig build test
+```
+Expected: PASS.
+- [ ] **Step 5: Commit**
+```bash
+git add src/vt.zig
+git commit -m "feat(vt): KeyEncoder wrapper"
+```
+---
+### Task 2.6: Mouse encoder
+**Files:**
+- Modify: `src/vt.zig`
+- [ ] **Step 1: Write failing test**
+```zig
+test "MouseEncoder encodes a click" {
+    var term = try Terminal.init(std.testing.allocator, .{ .cols = 80, .rows = 24 });
+    defer term.deinit();
+    var encoder = try MouseEncoder.init(std.testing.allocator);
+    defer encoder.deinit();
+    try encoder.syncFromTerminal(&term);
+    var buf: [64]u8 = undefined;
+    // With no mouse tracking mode enabled, encode should return 0
+    const n = try encoder.encode(&buf, .{
+        .x = 10,
+        .y = 5,
+        .button = .left,
+        .action = .press,
+        .modifiers = .{},
+    });
+    try std.testing.expectEqual(@as(usize, 0), n);
+}
+```
+- [ ] **Step 2: Run failing test**
+```bash
+zig build test
+```
+Expected: FAIL.
+- [ ] **Step 3: Implement MouseEncoder**
+```zig
+pub const MouseButton = enum { left, middle, right, none };
+pub const MouseAction = enum { press, release, motion, scroll_up, scroll_down };
+pub const MouseEvent = struct {
+    x: u16,
+    y: u16,
+    button: MouseButton,
+    action: MouseAction,
+    modifiers: Modifiers,
+};
+pub const MouseEncoder = struct {
+    inner: ghostty_vt.MouseEncoder,
+    pub fn init(allocator: std.mem.Allocator) !MouseEncoder {
+        return .{ .inner = try ghostty_vt.MouseEncoder.init(allocator) };
+    }
+    pub fn deinit(self: *MouseEncoder) void {
+        self.inner.deinit();
+    }
+    pub fn syncFromTerminal(self: *MouseEncoder, term: *Terminal) !void {
+        try self.inner.syncFromTerminal(&term.inner);
+    }
+    pub fn encode(self: *MouseEncoder, buf: []u8, ev: MouseEvent) !usize {
+        const inner_ev = ghostty_vt.MouseEvent{
+            .x = ev.x,
+            .y = ev.y,
+            .button = switch (ev.button) {
+                .left => .left,
+                .middle => .middle,
+                .right => .right,
+                .none => .none,
+            },
+            .action = switch (ev.action) {
+                .press => .press,
+                .release => .release,
+                .motion => .motion,
+                .scroll_up => .scroll_up,
+                .scroll_down => .scroll_down,
+            },
+            .modifiers = .{
+                .ctrl = ev.modifiers.ctrl,
+                .shift = ev.modifiers.shift,
+                .alt = ev.modifiers.alt,
+                .super = ev.modifiers.super,
+            },
+        };
+        return try self.inner.encode(buf, inner_ev);
+    }
+};
+```
+- [ ] **Step 4: Run test**
+```bash
+zig build test
+```
+Expected: PASS.
+- [ ] **Step 5: Commit**
+```bash
+git add src/vt.zig
+git commit -m "feat(vt): MouseEncoder wrapper"
+```
+---
+### Task 2.7: Terminal.resize
+**Files:**
+- Modify: `src/vt.zig`
+- [ ] **Step 1: Write failing test**
+```zig
+test "Terminal.resize updates dimensions" {
+    var term = try Terminal.init(std.testing.allocator, .{ .cols = 80, .rows = 24 });
+    defer term.deinit();
+    try term.resize(120, 40);
+    try std.testing.expectEqual(@as(u16, 120), term.cols);
+    try std.testing.expectEqual(@as(u16, 40), term.rows);
+}
+```
+- [ ] **Step 2: Run failing test**
+```bash
+zig build test
+```
+Expected: FAIL.
+- [ ] **Step 3: Implement Terminal.resize**
+Add to `Terminal`:
+```zig
+pub fn resize(self: *Terminal, cols: u16, rows: u16) !void {
+    try self.inner.resize(cols, rows);
+    self.cols = cols;
+    self.rows = rows;
+}
+```
+- [ ] **Step 4: Run test**
+```bash
+zig build test
+```
+Expected: PASS.
+- [ ] **Step 5: Commit**
+```bash
+git add src/vt.zig
+git commit -m "feat(vt): Terminal.resize"
+```
+---
+## Phase 3: Headless Integration — Proof Of Life
+Before touching Wayland or Vulkan, we wire PTY + VT together into a headless tool that proves libghostty is working.
+### Task 3.1: Headless mode — dump grid to stdout
+**Files:**
+- Modify: `src/main.zig`
+- [ ] **Step 1: Write main loop that spawns shell, feeds output to terminal, dumps grid**
+Replace `src/main.zig`:
+```zig
+const std = @import("std");
+const vt = @import("vt");
+const pty = @import("pty");
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+    const alloc = gpa.allocator();
+    const args = try std.process.argsAlloc(alloc);
+    defer std.process.argsFree(alloc, args);
+    if (args.len >= 2 and std.mem.eql(u8, args[1], "--headless")) {
+        return runHeadless(alloc);
+    }
+    std.debug.print("waystty (run with --headless for CLI dump mode)\n", .{});
+}
+fn runHeadless(alloc: std.mem.Allocator) !void {
+    const shell = std.posix.getenv("SHELL") orelse "/bin/sh";
+    var p = try pty.Pty.spawn(.{
+        .cols = 80,
+        .rows = 24,
+        .shell = shell,
+    });
+    defer p.deinit();
+    var term = try vt.Terminal.init(alloc, .{
+        .cols = 80,
+        .rows = 24,
+    });
+    defer term.deinit();
+    // Run command: echo hello; exit
+    _ = try p.write("echo hello; exit\n");
+    // Drain output
+    var buf: [4096]u8 = undefined;
+    const deadline = std.time.nanoTimestamp() + 2 * std.time.ns_per_s;
+    while (std.time.nanoTimestamp() < deadline) {
+        const n = p.read(&buf) catch |err| switch (err) {
+            error.WouldBlock => {
+                std.Thread.sleep(10 * std.time.ns_per_ms);
+                continue;
+            },
+            else => return err,
+        };
+        if (n == 0) break;
+        try term.write(buf[0..n]);
+    }
+    // Dump the grid
+    var render_state = try vt.RenderState.init(alloc);
+    defer render_state.deinit();
+    try render_state.update(&term);
+    var row_iter = try render_state.rowIterator();
+    defer row_iter.deinit();
+    const stdout = std.io.getStdOut().writer();
+    while (try row_iter.next()) |row_| {
+        var row = row_;
+        defer row.deinit();
+        var cells = row.cells();
+        defer cells.deinit();
+        while (try cells.next()) |cell| {
+            var utf8: [4]u8 = undefined;
+            const len = try std.unicode.utf8Encode(cell.codepoint, &utf8);
+            try stdout.writeAll(utf8[0..len]);
+        }
+        try stdout.writeAll("\n");
+    }
+}
+```
+- [ ] **Step 2: Build and run**
+```bash
+zig build run -- --headless
+```
+Expected: dumps a grid with `hello` visible in the output (and trailing spaces/empty rows). This proves PTY + VT are working together.
+- [ ] **Step 3: Commit**
+```bash
+git add src/main.zig
+git commit -m "feat: headless mode — pty + vt proof of life"
+```
+---
+## Phase 4: Font Rendering
+### Task 4.1: fontconfig lookup
+**Files:**
+- Create: `src/font.zig`
+- Modify: `build.zig` (add font module, link fontconfig, freetype)
+- [ ] **Step 1: Write failing test**
+Create `src/font.zig`:
+```zig
+const std = @import("std");
+const c = @cImport({
+    @cInclude("fontconfig/fontconfig.h");
+    @cInclude("ft2build.h");
+    @cInclude("freetype/freetype.h");
+});
+pub const FontLookup = struct {
+    path: [:0]u8,
+    index: c_int,
+    pub fn deinit(self: *FontLookup, alloc: std.mem.Allocator) void {
+        alloc.free(self.path);
+    }
+};
+pub fn lookupMonospace(alloc: std.mem.Allocator) !FontLookup {
+    _ = alloc;
+    return error.NotImplemented;
+}
+test "lookupMonospace returns a valid font path" {
+    var lookup = try lookupMonospace(std.testing.allocator);
+    defer lookup.deinit(std.testing.allocator);
+    // Just check the file exists
+    const file = try std.fs.openFileAbsolute(lookup.path, .{});
+    file.close();
+}
+```
+- [ ] **Step 2: Register font module and tests in build.zig**
+```zig
+const font_module = b.addModule("font", .{
+    .root_source_file = b.path("src/font.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+font_module.link_libc = true;
+font_module.linkSystemLibrary("fontconfig", .{});
+font_module.linkSystemLibrary("freetype2", .{});
+exe.root_module.addImport("font", font_module);
+const font_tests = b.addTest(.{
+    .root_source_file = b.path("src/font.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+font_tests.linkLibC();
+font_tests.linkSystemLibrary("fontconfig");
+font_tests.linkSystemLibrary("freetype2");
+test_step.dependOn(&b.addRunArtifact(font_tests).step);
+```
+- [ ] **Step 3: Run failing test**
+```bash
+zig build test
+```
+Expected: FAIL.
+- [ ] **Step 4: Implement lookupMonospace**
+```zig
+pub fn lookupMonospace(alloc: std.mem.Allocator) !FontLookup {
+    if (c.FcInit() == c.FcFalse) return error.FcInitFailed;
+    const pattern = c.FcPatternCreate() orelse return error.FcPatternCreate;
+    defer c.FcPatternDestroy(pattern);
+    _ = c.FcPatternAddString(pattern, c.FC_FAMILY, "monospace");
+    _ = c.FcPatternAddInteger(pattern, c.FC_WEIGHT, c.FC_WEIGHT_REGULAR);
+    _ = c.FcPatternAddInteger(pattern, c.FC_SLANT, c.FC_SLANT_ROMAN);
+    _ = c.FcConfigSubstitute(null, pattern, c.FcMatchPattern);
+    c.FcDefaultSubstitute(pattern);
+    var result: c.FcResult = undefined;
+    const matched = c.FcFontMatch(null, pattern, &result) orelse return error.FcFontMatchFailed;
+    defer c.FcPatternDestroy(matched);
+    var file_cstr: [*c]c.FcChar8 = null;
+    if (c.FcPatternGetString(matched, c.FC_FILE, 0, &file_cstr) != c.FcResultMatch) {
+        return error.FcGetFileFailed;
+    }
+    var index: c_int = 0;
+    _ = c.FcPatternGetInteger(matched, c.FC_INDEX, 0, &index);
+    const slice = std.mem.span(@as([*:0]const u8, @ptrCast(file_cstr)));
+    const dup = try alloc.dupeZ(u8, slice);
+    return .{ .path = dup, .index = index };
+}
+```
+- [ ] **Step 5: Run test**
+```bash
+zig build test
+```
+Expected: PASS (requires fontconfig installed + a monospace font on the system).
+- [ ] **Step 6: Commit**
+```bash
+git add src/font.zig build.zig
+git commit -m "feat(font): fontconfig monospace lookup"
+```
+---
+### Task 4.2: Freetype face loading and glyph rasterization
+**Files:**
+- Modify: `src/font.zig`
+- [ ] **Step 1: Write failing test**
+Add to `src/font.zig`:
+```zig
+test "Face rasterizes glyph 'M'" {
+    var lookup = try lookupMonospace(std.testing.allocator);
+    defer lookup.deinit(std.testing.allocator);
+    var face = try Face.init(std.testing.allocator, lookup.path, lookup.index, 14);
+    defer face.deinit();
+    const glyph = try face.rasterize('M');
+    try std.testing.expect(glyph.width > 0);
+    try std.testing.expect(glyph.height > 0);
+    try std.testing.expect(glyph.bitmap.len == @as(usize, glyph.width) * @as(usize, glyph.height));
+}
+```
+- [ ] **Step 2: Run failing test**
+```bash
+zig build test
+```
+Expected: FAIL.
+- [ ] **Step 3: Implement Face**
+Add to `src/font.zig`:
+```zig
+pub const Glyph = struct {
+    codepoint: u21,
+    width: u32,
+    height: u32,
+    bearing_x: i32,
+    bearing_y: i32,
+    advance_x: i32,
+    bitmap: []u8, // R8, owned
+};
+pub const Face = struct {
+    alloc: std.mem.Allocator,
+    library: c.FT_Library,
+    face: c.FT_Face,
+    px_size: u32,
+    pub fn init(alloc: std.mem.Allocator, path: [:0]const u8, index: c_int, px_size: u32) !Face {
+        var library: c.FT_Library = null;
+        if (c.FT_Init_FreeType(&library) != 0) return error.FtInitFailed;
+        errdefer _ = c.FT_Done_FreeType(library);
+        var face: c.FT_Face = null;
+        if (c.FT_New_Face(library, path.ptr, index, &face) != 0) return error.FtNewFaceFailed;
+        errdefer _ = c.FT_Done_Face(face);
+        if (c.FT_Set_Pixel_Sizes(face, 0, px_size) != 0) return error.FtSetPixelSizesFailed;
+        return .{
+            .alloc = alloc,
+            .library = library,
+            .face = face,
+            .px_size = px_size,
+        };
+    }
+    pub fn deinit(self: *Face) void {
+        _ = c.FT_Done_Face(self.face);
+        _ = c.FT_Done_FreeType(self.library);
+    }
+    pub fn rasterize(self: *Face, codepoint: u21) !Glyph {
+        const glyph_index = c.FT_Get_Char_Index(self.face, codepoint);
+        if (c.FT_Load_Glyph(self.face, glyph_index, c.FT_LOAD_RENDER) != 0) {
+            return error.FtLoadGlyphFailed;
+        }
+        const slot = self.face.*.glyph;
+        const bitmap = slot.*.bitmap;
+        const w: u32 = bitmap.width;
+        const h: u32 = bitmap.rows;
+        const pixels = try self.alloc.alloc(u8, @as(usize, w) * @as(usize, h));
+        // bitmap.buffer may be null if width/height are 0
+        if (w > 0 and h > 0) {
+            const pitch: i32 = bitmap.pitch;
+            const abs_pitch: u32 = @intCast(@abs(pitch));
+            var y: u32 = 0;
+            while (y < h) : (y += 1) {
+                const src_row = bitmap.buffer + @as(usize, y) * abs_pitch;
+                const dst_row = pixels.ptr + @as(usize, y) * w;
+                @memcpy(dst_row[0..w], src_row[0..w]);
+            }
+        }
+        return .{
+            .codepoint = codepoint,
+            .width = w,
+            .height = h,
+            .bearing_x = slot.*.bitmap_left,
+            .bearing_y = slot.*.bitmap_top,
+            .advance_x = @intCast(slot.*.advance.x >> 6),
+            .bitmap = pixels,
+        };
+    }
+    pub fn freeGlyph(self: *Face, glyph: Glyph) void {
+        self.alloc.free(glyph.bitmap);
+    }
+    pub fn cellWidth(self: *Face) u32 {
+        // Measure advance of 'M' for monospace cell width
+        const m_index = c.FT_Get_Char_Index(self.face, 'M');
+        _ = c.FT_Load_Glyph(self.face, m_index, c.FT_LOAD_DEFAULT);
+        return @intCast(self.face.*.glyph.*.advance.x >> 6);
+    }
+    pub fn cellHeight(self: *Face) u32 {
+        const metrics = self.face.*.size.*.metrics;
+        return @intCast((metrics.ascender - metrics.descender) >> 6);
+    }
+};
+```
+- [ ] **Step 4: Run test**
+```bash
+zig build test
+```
+Expected: PASS.
+- [ ] **Step 5: Commit**
+```bash
+git add src/font.zig
+git commit -m "feat(font): freetype face + rasterize"
+```
+---
+### Task 4.3: Glyph atlas
+**Files:**
+- Modify: `src/font.zig`
+- [ ] **Step 1: Write failing test**
+```zig
+test "Atlas packs multiple glyphs and returns UVs" {
+    var lookup = try lookupMonospace(std.testing.allocator);
+    defer lookup.deinit(std.testing.allocator);
+    var face = try Face.init(std.testing.allocator, lookup.path, lookup.index, 14);
+    defer face.deinit();
+    var atlas = try Atlas.init(std.testing.allocator, 512, 512);
+    defer atlas.deinit();
+    const uv_m = try atlas.getOrInsert(&face, 'M');
+    const uv_a = try atlas.getOrInsert(&face, 'a');
+    // Both should have valid UVs within [0, 1]
+    try std.testing.expect(uv_m.u0 >= 0.0 and uv_m.u1 <= 1.0);
+    try std.testing.expect(uv_a.u0 >= 0.0 and uv_a.u1 <= 1.0);
+    // Second call for 'M' should return cached UV (same values)
+    const uv_m2 = try atlas.getOrInsert(&face, 'M');
+    try std.testing.expectEqual(uv_m.u0, uv_m2.u0);
+    try std.testing.expectEqual(uv_m.v0, uv_m2.v0);
+}
+```
+- [ ] **Step 2: Run failing test**
+```bash
+zig build test
+```
+Expected: FAIL.
+- [ ] **Step 3: Implement Atlas**
+Add to `src/font.zig`:
+```zig
+pub const GlyphUV = struct {
+    u0: f32,
+    v0: f32,
+    u1: f32,
+    v1: f32,
+    width: u32,
+    height: u32,
+    bearing_x: i32,
+    bearing_y: i32,
+    advance_x: i32,
+};
+pub const Atlas = struct {
+    alloc: std.mem.Allocator,
+    width: u32,
+    height: u32,
+    pixels: []u8, // R8
+    // Row-based packer state
+    cursor_x: u32,
+    cursor_y: u32,
+    row_height: u32,
+    cache: std.AutoHashMap(u21, GlyphUV),
+    dirty: bool,
+    pub fn init(alloc: std.mem.Allocator, width: u32, height: u32) !Atlas {
+        const pixels = try alloc.alloc(u8, @as(usize, width) * @as(usize, height));
+        @memset(pixels, 0);
+        return .{
+            .alloc = alloc,
+            .width = width,
+            .height = height,
+            .pixels = pixels,
+            .cursor_x = 0,
+            .cursor_y = 0,
+            .row_height = 0,
+            .cache = std.AutoHashMap(u21, GlyphUV).init(alloc),
+            .dirty = true,
+        };
+    }
+    pub fn deinit(self: *Atlas) void {
+        self.alloc.free(self.pixels);
+        self.cache.deinit();
+    }
+    pub fn getOrInsert(self: *Atlas, face: *Face, codepoint: u21) !GlyphUV {
+        if (self.cache.get(codepoint)) |uv| return uv;
+        const glyph = try face.rasterize(codepoint);
+        defer face.freeGlyph(glyph);
+        // Advance to next row if this glyph doesn't fit
+        if (self.cursor_x + glyph.width > self.width) {
+            self.cursor_x = 0;
+            self.cursor_y += self.row_height;
+            self.row_height = 0;
+        }
+        if (self.cursor_y + glyph.height > self.height) {
+            return error.AtlasFull;
+        }
+        // Blit glyph into atlas
+        var y: u32 = 0;
+        while (y < glyph.height) : (y += 1) {
+            const src = glyph.bitmap.ptr + @as(usize, y) * glyph.width;
+            const dst = self.pixels.ptr + (@as(usize, self.cursor_y + y) * self.width) + self.cursor_x;
+            @memcpy(dst[0..glyph.width], src[0..glyph.width]);
+        }
+        const uv = GlyphUV{
+            .u0 = @as(f32, @floatFromInt(self.cursor_x)) / @as(f32, @floatFromInt(self.width)),
+            .v0 = @as(f32, @floatFromInt(self.cursor_y)) / @as(f32, @floatFromInt(self.height)),
+            .u1 = @as(f32, @floatFromInt(self.cursor_x + glyph.width)) / @as(f32, @floatFromInt(self.width)),
+            .v1 = @as(f32, @floatFromInt(self.cursor_y + glyph.height)) / @as(f32, @floatFromInt(self.height)),
+            .width = glyph.width,
+            .height = glyph.height,
+            .bearing_x = glyph.bearing_x,
+            .bearing_y = glyph.bearing_y,
+            .advance_x = glyph.advance_x,
+        };
+        try self.cache.put(codepoint, uv);
+        self.cursor_x += glyph.width;
+        if (glyph.height > self.row_height) self.row_height = glyph.height;
+        self.dirty = true;
+        return uv;
+    }
+};
+```
+- [ ] **Step 4: Run test**
+```bash
+zig build test
+```
+Expected: PASS.
+- [ ] **Step 5: Commit**
+```bash
+git add src/font.zig
+git commit -m "feat(font): glyph atlas with row-based packing"
+```
+---
+## Phase 5: Wayland Module
+### Task 5.1: Wire zig-wayland into build.zig
+**Files:**
+- Create: `src/wayland.zig`
+- Modify: `build.zig`
+- [ ] **Step 1: Create src/wayland.zig stub**
+```zig
+const std = @import("std");
+const wayland = @import("wayland");
+const wl = wayland.client.wl;
+const xdg = wayland.client.xdg;
+test "wayland module imports" {
+    _ = wl;
+    _ = xdg;
+}
+```
+- [ ] **Step 2: Set up the zig-wayland scanner in build.zig**
+Add near the top of `build` function:
+```zig
+const Scanner = @import("wayland").Scanner;
+pub fn build(b: *std.Build) void {
+    // ... existing code ...
+    const scanner = Scanner.create(b, .{});
+    scanner.addSystemProtocol("stable/xdg-shell/xdg-shell.xml");
+    scanner.addSystemProtocol("staging/cursor-shape/cursor-shape-v1.xml");
+    scanner.addSystemProtocol("staging/fractional-scale/fractional-scale-v1.xml");
+    // Viewporter is required by fractional-scale
+    scanner.addSystemProtocol("stable/viewporter/viewporter.xml");
+    scanner.generate("wl_compositor", 6);
+    scanner.generate("wl_shm", 1);
+    scanner.generate("wl_seat", 9);
+    scanner.generate("wl_output", 4);
+    scanner.generate("xdg_wm_base", 6);
+    scanner.generate("wp_cursor_shape_manager_v1", 1);
+    scanner.generate("wp_fractional_scale_manager_v1", 1);
+    scanner.generate("wp_viewporter", 1);
+    // The wayland module from the dependency
+    const wayland_dep = b.dependency("wayland", .{});
+    const wayland_module = b.createModule(.{
+        .root_source_file = scanner.result,
+    });
+    _ = wayland_dep;
+    // ... create exe ...
+    const wayland_src_module = b.addModule("wayland", .{
+        .root_source_file = b.path("src/wayland.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    wayland_src_module.addImport("wayland", wayland_module);
+    wayland_src_module.link_libc = true;
+    wayland_src_module.linkSystemLibrary("wayland-client", .{});
+    exe.root_module.addImport("wayland-client", wayland_src_module);
+}
+```
+**Note:** this scanner block is approximate — consult the current `ifreund/zig-wayland` README, as the exact build.zig integration has changed over Zig releases. Adjust to match the version you pinned.
+- [ ] **Step 3: Build**
+```bash
+zig build
+```
+Expected: builds successfully. Zig-wayland scans the protocol XMLs and generates bindings.
+- [ ] **Step 4: Commit**
+```bash
+git add src/wayland.zig build.zig
+git commit -m "build(wayland): wire zig-wayland scanner"
+```
+---
+### Task 5.2: Connect to wl_display and bind globals
+**Files:**
+- Modify: `src/wayland.zig`
+- [ ] **Step 1: Write a minimal Wayland client that binds compositor, xdg_wm_base, seat**
+```zig
+const std = @import("std");
+const wayland = @import("wayland");
+const wl = wayland.client.wl;
+const xdg = wayland.client.xdg;
+pub const Globals = struct {
+    compositor: ?*wl.Compositor = null,
+    wm_base: ?*xdg.WmBase = null,
+    seat: ?*wl.Seat = null,
+};
+pub const Connection = struct {
+    display: *wl.Display,
+    registry: *wl.Registry,
+    globals: Globals,
+    pub fn init() !Connection {
+        const display = try wl.Display.connect(null);
+        const registry = try display.getRegistry();
+        var globals = Globals{};
+        registry.setListener(*Globals, registryListener, &globals);
+        _ = display.roundtrip();
+        if (globals.compositor == null) return error.NoCompositor;
+        if (globals.wm_base == null) return error.NoXdgWmBase;
+        if (globals.seat == null) return error.NoSeat;
+        return .{
+            .display = display,
+            .registry = registry,
+            .globals = globals,
+        };
+    }
+    pub fn deinit(self: *Connection) void {
+        self.display.disconnect();
+    }
+};
+fn registryListener(
+    registry: *wl.Registry,
+    event: wl.Registry.Event,
+    globals: *Globals,
+) void {
+    switch (event) {
+        .global => |g| {
+            const iface = std.mem.span(g.interface);
+            if (std.mem.eql(u8, iface, wl.Compositor.interface.name)) {
+                globals.compositor = registry.bind(g.name, wl.Compositor, 6) catch return;
+            } else if (std.mem.eql(u8, iface, xdg.WmBase.interface.name)) {
+                globals.wm_base = registry.bind(g.name, xdg.WmBase, 6) catch return;
+            } else if (std.mem.eql(u8, iface, wl.Seat.interface.name)) {
+                globals.seat = registry.bind(g.name, wl.Seat, 9) catch return;
+            }
+        },
+        .global_remove => {},
+    }
+}
+```
+**Adjust the exact interface names, versions, and event field names to match the generated `zig-wayland` bindings.** If `g.interface` is `[*:0]const u8`, `std.mem.span` works; if it's a different type, use the matching accessor.
+- [ ] **Step 2: Build**
+```bash
+zig build
+```
+Expected: builds. Won't crash without a live Wayland session because we aren't running it yet.
+- [ ] **Step 3: Smoke-test under a live Wayland session**
+In your Wayland session, run:
+```bash
+zig build
+./zig-out/bin/waystty --wayland-smoke-test
+```
+For now, add a `--wayland-smoke-test` branch to `main.zig` that calls `wayland.Connection.init()` and prints "connected" on success. Commit both the branch and the connection wiring together.
+Expected: prints `connected`.
+- [ ] **Step 4: Commit**
+```bash
+git add src/wayland.zig src/main.zig
+git commit -m "feat(wayland): connect to display and bind globals"
+```
+---
+### Task 5.3: Create surface and xdg_toplevel
+**Files:**
+- Modify: `src/wayland.zig`
+- [ ] **Step 1: Extend Connection with createWindow**
+```zig
+pub const Window = struct {
+    surface: *wl.Surface,
+    xdg_surface: *xdg.Surface,
+    xdg_toplevel: *xdg.Toplevel,
+    configured: bool = false,
+    should_close: bool = false,
+    width: u32 = 800,
+    height: u32 = 600,
+    pub fn deinit(self: *Window) void {
+        self.xdg_toplevel.destroy();
+        self.xdg_surface.destroy();
+        self.surface.destroy();
+    }
+};
+pub fn createWindow(self: *Connection, title: [*:0]const u8) !*Window {
+    const compositor = self.globals.compositor orelse return error.NoCompositor;
+    const wm_base = self.globals.wm_base orelse return error.NoXdgWmBase;
+    const window = try std.heap.c_allocator.create(Window);
+    window.* = .{
+        .surface = try compositor.createSurface(),
+        .xdg_surface = undefined,
+        .xdg_toplevel = undefined,
+    };
+    window.xdg_surface = try wm_base.getXdgSurface(window.surface);
+    window.xdg_toplevel = try window.xdg_surface.getToplevel();
+    window.xdg_toplevel.setTitle(title);
+    window.xdg_toplevel.setAppId("waystty");
+    window.xdg_surface.setListener(*Window, xdgSurfaceListener, window);
+    window.xdg_toplevel.setListener(*Window, xdgToplevelListener, window);
+    wm_base.setListener(*xdg.WmBase, wmBaseListener, wm_base);
+    window.surface.commit();
+    _ = self.display.roundtrip();
+    return window;
+}
+fn wmBaseListener(wm_base: *xdg.WmBase, event: xdg.WmBase.Event, _: *xdg.WmBase) void {
+    switch (event) {
+        .ping => |p| wm_base.pong(p.serial),
+    }
+}
+fn xdgSurfaceListener(surface: *xdg.Surface, event: xdg.Surface.Event, window: *Window) void {
+    switch (event) {
+        .configure => |c| {
+            surface.ackConfigure(c.serial);
+            window.configured = true;
+        },
+    }
+}
+fn xdgToplevelListener(_: *xdg.Toplevel, event: xdg.Toplevel.Event, window: *Window) void {
+    switch (event) {
+        .configure => |c| {
+            if (c.width > 0) window.width = @intCast(c.width);
+            if (c.height > 0) window.height = @intCast(c.height);
+        },
+        .close => window.should_close = true,
+        else => {},
+    }
+}
+```
+- [ ] **Step 2: Extend smoke test to create window**
+In `main.zig --wayland-smoke-test`, after connecting, create a window and call `display.roundtrip()` twice, then print `window created`.
+- [ ] **Step 3: Run smoke test**
+```bash
+zig build run -- --wayland-smoke-test
+```
+Expected: prints `connected`, `window created`, exits cleanly.
+- [ ] **Step 4: Commit**
+```bash
+git add src/wayland.zig src/main.zig
+git commit -m "feat(wayland): create surface + xdg_toplevel"
+```
+---
+### Task 5.4: Keyboard input with xkbcommon
+**Files:**
+- Modify: `src/wayland.zig`
+- Modify: `build.zig` (link xkbcommon)
+- [ ] **Step 1: Link xkbcommon in build.zig**
+In the `wayland_src_module` block:
+```zig
+wayland_src_module.linkSystemLibrary("xkbcommon", .{});
+```
+- [ ] **Step 2: Add xkbcommon cImport and keyboard struct**
+At top of `src/wayland.zig`:
+```zig
+const c = @cImport({
+    @cInclude("xkbcommon/xkbcommon.h");
+    @cInclude("sys/mman.h");
+    @cInclude("unistd.h");
+});
+pub const KeyboardEvent = struct {
+    keysym: u32,
+    modifiers: Modifiers,
+    action: Action,
+    utf8: [8]u8,
+    utf8_len: u8,
+    pub const Modifiers = struct {
+        ctrl: bool = false,
+        shift: bool = false,
+        alt: bool = false,
+        super: bool = false,
+    };
+    pub const Action = enum { press, release, repeat };
+};
+pub const Keyboard = struct {
+    wl_keyboard: *wl.Keyboard,
+    xkb_ctx: ?*c.xkb_context,
+    xkb_keymap: ?*c.xkb_keymap = null,
+    xkb_state: ?*c.xkb_state = null,
+    event_queue: std.ArrayList(KeyboardEvent),
+    // repeat info
+    repeat_rate: u32 = 25,  // keys per second
+    repeat_delay: u32 = 500, // ms
+    last_key: ?u32 = null,
+    last_key_time_ns: i128 = 0,
+    has_focus: bool = false,
+    pub fn init(alloc: std.mem.Allocator, seat: *wl.Seat) !*Keyboard {
+        const kb = try alloc.create(Keyboard);
+        kb.* = .{
+            .wl_keyboard = try seat.getKeyboard(),
+            .xkb_ctx = c.xkb_context_new(c.XKB_CONTEXT_NO_FLAGS),
+            .event_queue = std.ArrayList(KeyboardEvent).init(alloc),
+        };
+        kb.wl_keyboard.setListener(*Keyboard, keyboardListener, kb);
+        return kb;
+    }
+    pub fn deinit(self: *Keyboard, alloc: std.mem.Allocator) void {
+        if (self.xkb_state) |s| c.xkb_state_unref(s);
+        if (self.xkb_keymap) |m| c.xkb_keymap_unref(m);
+        if (self.xkb_ctx) |ctx| c.xkb_context_unref(ctx);
+        self.wl_keyboard.release();
+        self.event_queue.deinit();
+        alloc.destroy(self);
+    }
+};
+fn keyboardListener(_: *wl.Keyboard, event: wl.Keyboard.Event, kb: *Keyboard) void {
+    switch (event) {
+        .keymap => |k| {
+            if (k.format != .xkb_v1) return;
+            const map_mem = c.mmap(
+                null,
+                k.size,
+                c.PROT_READ,
+                c.MAP_PRIVATE,
+                k.fd,
+,
+            );
+            defer _ = c.munmap(map_mem, k.size);
+            defer _ = c.close(k.fd);
+            if (map_mem == c.MAP_FAILED) return;
+            const new_keymap = c.xkb_keymap_new_from_string(
+                kb.xkb_ctx,
+                @ptrCast(map_mem),
+                c.XKB_KEYMAP_FORMAT_TEXT_V1,
+                c.XKB_KEYMAP_COMPILE_NO_FLAGS,
+            ) orelse return;
+            const new_state = c.xkb_state_new(new_keymap) orelse {
+                c.xkb_keymap_unref(new_keymap);
+                return;
+            };
+            if (kb.xkb_state) |s| c.xkb_state_unref(s);
+            if (kb.xkb_keymap) |m| c.xkb_keymap_unref(m);
+            kb.xkb_keymap = new_keymap;
+            kb.xkb_state = new_state;
+        },
+        .enter => {
+            kb.has_focus = true;
+        },
+        .leave => {
+            kb.has_focus = false;
+            kb.last_key = null;
+        },
+        .key => |k| {
+            const state = kb.xkb_state orelse return;
+            const keycode: u32 = k.key + 8; // evdev -> xkb offset
+            const keysym = c.xkb_state_key_get_one_sym(state, keycode);
+            var utf8: [8]u8 = undefined;
+            const len = c.xkb_state_key_get_utf8(state, keycode, &utf8, utf8.len);
+            const action: KeyboardEvent.Action = if (k.state == .pressed) .press else .release;
+            const mods = KeyboardEvent.Modifiers{
+                .ctrl = c.xkb_state_mod_name_is_active(state, "Control", c.XKB_STATE_MODS_EFFECTIVE) > 0,
+                .shift = c.xkb_state_mod_name_is_active(state, "Shift", c.XKB_STATE_MODS_EFFECTIVE) > 0,
+                .alt = c.xkb_state_mod_name_is_active(state, "Mod1", c.XKB_STATE_MODS_EFFECTIVE) > 0,
+                .super = c.xkb_state_mod_name_is_active(state, "Mod4", c.XKB_STATE_MODS_EFFECTIVE) > 0,
+            };
+            var ev = KeyboardEvent{
+                .keysym = keysym,
+                .modifiers = mods,
+                .action = action,
+                .utf8 = utf8,
+                .utf8_len = @intCast(@min(len, 8)),
+            };
+            kb.event_queue.append(ev) catch return;
+            if (action == .press) {
+                kb.last_key = keycode;
+                kb.last_key_time_ns = std.time.nanoTimestamp();
+            } else if (kb.last_key == keycode) {
+                kb.last_key = null;
+            }
+        },
+        .modifiers => |m| {
+            const state = kb.xkb_state orelse return;
+            _ = c.xkb_state_update_mask(
+                state,
+                m.mods_depressed,
+                m.mods_latched,
+                m.mods_locked,
+,
+,
+                m.group,
+            );
+        },
+        .repeat_info => |r| {
+            kb.repeat_rate = @intCast(r.rate);
+            kb.repeat_delay = @intCast(r.delay);
+        },
+    }
+}
+```
+- [ ] **Step 3: Build**
+```bash
+zig build
+```
+Expected: builds.
+- [ ] **Step 4: Commit**
+```bash
+git add src/wayland.zig build.zig
+git commit -m "feat(wayland): keyboard input with xkbcommon"
+```
+---
+### Task 5.5: Key repeat tick
+**Files:**
+- Modify: `src/wayland.zig`
+- [ ] **Step 1: Add tickRepeat method**
+Add to `Keyboard`:
+```zig
+/// Called from the main loop. If a key is currently held and enough time has
+/// passed, push a synthetic repeat event to the queue.
+pub fn tickRepeat(self: *Keyboard) void {
+    const last_key = self.last_key orelse return;
+    const state = self.xkb_state orelse return;
+    const now = std.time.nanoTimestamp();
+    const elapsed_ms = @divTrunc(now - self.last_key_time_ns, std.time.ns_per_ms);
+    if (elapsed_ms < @as(i128, self.repeat_delay)) return;
+    const interval_ms: i128 = @divTrunc(1000, @as(i128, self.repeat_rate));
+    const repeats_due = @divTrunc(elapsed_ms - self.repeat_delay, interval_ms) + 1;
+    _ = repeats_due;
+    // Simple approach: fire one repeat per tick, advance last_key_time_ns
+    const keysym = c.xkb_state_key_get_one_sym(state, last_key);
+    var utf8: [8]u8 = undefined;
+    const len = c.xkb_state_key_get_utf8(state, last_key, &utf8, utf8.len);
+    const ev = KeyboardEvent{
+        .keysym = keysym,
+        .modifiers = .{},
+        .action = .repeat,
+        .utf8 = utf8,
+        .utf8_len = @intCast(@min(len, 8)),
+    };
+    self.event_queue.append(ev) catch return;
+    self.last_key_time_ns = now;
+}
+```
+- [ ] **Step 2: Build**
+```bash
+zig build
+```
+Expected: builds.
+- [ ] **Step 3: Commit**
+```bash
+git add src/wayland.zig
+git commit -m "feat(wayland): client-side key repeat"
+```
+---
+## Phase 6: Vulkan Renderer
+### Task 6.1: Wire vulkan-zig into build.zig
+**Files:**
+- Create: `src/renderer.zig`
+- Modify: `build.zig`
+- [ ] **Step 1: Create renderer.zig stub**
+```zig
+const std = @import("std");
+const vk = @import("vulkan");
+test "vulkan module imports" {
+    _ = vk;
+}
+```
+- [ ] **Step 2: Wire vulkan-zig in build.zig**
+```zig
+const vulkan_headers_dep = b.dependency("vulkan_headers", .{});
+const vulkan_zig_dep = b.dependency("vulkan", .{
+    .registry = vulkan_headers_dep.path("registry/vk.xml"),
+});
+const vulkan_module = vulkan_zig_dep.module("vulkan-zig");
+const renderer_module = b.addModule("renderer", .{
+    .root_source_file = b.path("src/renderer.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+renderer_module.addImport("vulkan", vulkan_module);
+exe.root_module.addImport("renderer", renderer_module);
+```
+- [ ] **Step 3: Build**
+```bash
+zig build
+```
+Expected: builds. vulkan-zig generates bindings from vk.xml.
+- [ ] **Step 4: Commit**
+```bash
+git add src/renderer.zig build.zig
+git commit -m "build(renderer): wire vulkan-zig"
+```
+---
+### Task 6.2: Shaders — cell.vert and cell.frag
+**Files:**
+- Create: `shaders/cell.vert`
+- Create: `shaders/cell.frag`
+- Modify: `build.zig` (add glslc build step)
+- [ ] **Step 1: Write cell.vert (GLSL)**
+```glsl
+#version 450
+layout(push_constant) uniform PushConstants {
+    vec2 viewport_size;
+    vec2 cell_size;
+} pc;
+layout(location = 0) in vec2 in_unit_pos; // [0,1] quad corner
+layout(location = 1) in vec2 in_cell_pos;    // cell grid coords
+layout(location = 2) in vec4 in_uv_rect;     // u0,v0,u1,v1
+layout(location = 3) in vec4 in_fg_color;
+layout(location = 4) in vec4 in_bg_color;
+layout(location = 0) out vec2 out_uv;
+layout(location = 1) out vec4 out_fg;
+layout(location = 2) out vec4 out_bg;
+void main() {
+    vec2 pixel_pos = (in_cell_pos + in_unit_pos) * pc.cell_size;
+    vec2 ndc = (pixel_pos / pc.viewport_size) * 2.0 - 1.0;
+    gl_Position = vec4(ndc, 0.0, 1.0);
+    out_uv = mix(in_uv_rect.xy, in_uv_rect.zw, in_unit_pos);
+    out_fg = in_fg_color;
+    out_bg = in_bg_color;
+}
+```
+- [ ] **Step 2: Write cell.frag (GLSL)**
+```glsl
+#version 450
+layout(binding = 0) uniform sampler2D glyph_atlas;
+layout(location = 0) in vec2 in_uv;
+layout(location = 1) in vec4 in_fg;
+layout(location = 2) in vec4 in_bg;
+layout(location = 0) out vec4 out_color;
+void main() {
+    float alpha = texture(glyph_atlas, in_uv).r;
+    out_color = mix(in_bg, in_fg, alpha);
+}
+```
+- [ ] **Step 3: Add glslc build step in build.zig**
+```zig
+fn compileShader(b: *std.Build, comptime name: []const u8) std.Build.LazyPath {
+    const glslc = b.addSystemCommand(&.{ "glslc", "--target-env=vulkan1.2" });
+    glslc.addFileArg(b.path("shaders/" ++ name));
+    glslc.addArg("-o");
+    return glslc.addOutputFileArg(name ++ ".spv");
+}
+// In build():
+const vert_spv = compileShader(b, "cell.vert");
+const frag_spv = compileShader(b, "cell.frag");
+renderer_module.addAnonymousImport("cell_vert_spv", .{
+    .root_source_file = vert_spv,
+});
+renderer_module.addAnonymousImport("cell_frag_spv", .{
+    .root_source_file = frag_spv,
+});
+```
+Then in `renderer.zig` access via `@embedFile` equivalent — vulkan-zig expects a byte slice. The above uses `addAnonymousImport` which isn't right for raw bytes. Actually use this simpler approach:
+```zig
+const vert_install = b.addInstallFile(vert_spv, "shaders/cell.vert.spv");
+const frag_install = b.addInstallFile(frag_spv, "shaders/cell.frag.spv");
+exe.step.dependOn(&vert_install.step);
+exe.step.dependOn(&frag_install.step);
+```
+And in `renderer.zig` load at runtime, OR use Zig's `@embedFile` by copying SPV into `src/` via the build step. The cleanest approach for embed-at-compile-time:
+```zig
+const install_shaders = b.addWriteFiles();
+_ = install_shaders.addCopyFile(vert_spv, "cell.vert.spv");
+_ = install_shaders.addCopyFile(frag_spv, "cell.frag.spv");
+renderer_module.addIncludePath(install_shaders.getDirectory());
+```
+Then in Zig use `@embedFile` with a path resolved via the include path. If this turns out not to work cleanly, fall back to `@import` of a generated `.zig` file that contains `pub const cell_vert_spv = @embedFile("cell.vert.spv");`.
+**This task is intentionally flexible** — the exact mechanism depends on Zig version. The key deliverable: at the end of this task, renderer.zig can reference `const vert_spv = @embedFile("cell.vert.spv");` and it works.
+- [ ] **Step 4: Verify with a test**
+In `renderer.zig`:
+```zig
+test "shaders are embedded" {
+    const vert = @embedFile("cell.vert.spv");
+    const frag = @embedFile("cell.frag.spv");
+    try std.testing.expect(vert.len > 0);
+    try std.testing.expect(frag.len > 0);
+    // SPIR-V magic number
+    try std.testing.expectEqual(@as(u32, 0x07230203), std.mem.bytesAsSlice(u32, vert[0..4])[0]);
+}
+```
+- [ ] **Step 5: Build and test**
+```bash
+zig build test
+```
+Expected: PASS.
+- [ ] **Step 6: Commit**
+```bash
+git add shaders/ src/renderer.zig build.zig
+git commit -m "build(shaders): glslc compile + embed"
+```
+---
+### Task 6.3: Vulkan instance + wayland surface
+**Files:**
+- Modify: `src/renderer.zig`
+- [ ] **Step 1: Create Vulkan instance with wayland extension**
+```zig
+const std = @import("std");
+const vk = @import("vulkan");
+const apis: []const vk.ApiInfo = &.{
+    vk.features.version_1_0,
+    vk.features.version_1_1,
+    vk.features.version_1_2,
+    vk.extensions.khr_surface,
+    vk.extensions.khr_wayland_surface,
+    vk.extensions.khr_swapchain,
+};
+const BaseDispatch = vk.BaseWrapper(apis);
+const InstanceDispatch = vk.InstanceWrapper(apis);
+const DeviceDispatch = vk.DeviceWrapper(apis);
+pub const Renderer = struct {
+    alloc: std.mem.Allocator,
+    vkb: BaseDispatch,
+    vki: InstanceDispatch,
+    instance: vk.Instance,
+    pub fn init(alloc: std.mem.Allocator, loader: anytype) !Renderer {
+        const vkb = try BaseDispatch.load(loader);
+        const app_info = vk.ApplicationInfo{
+            .p_application_name = "waystty",
+            .application_version = vk.makeApiVersion(0, 0, 0, 1),
+            .p_engine_name = "waystty",
+            .engine_version = vk.makeApiVersion(0, 0, 0, 1),
+            .api_version = vk.API_VERSION_1_2,
+        };
+        const extensions = [_][*:0]const u8{
+            vk.extensions.khr_surface.name,
+            vk.extensions.khr_wayland_surface.name,
+        };
+        const instance = try vkb.createInstance(&.{
+            .p_application_info = &app_info,
+            .enabled_extension_count = extensions.len,
+            .pp_enabled_extension_names = &extensions,
+        }, null);
+        const vki = try InstanceDispatch.load(instance, vkb.dispatch.vkGetInstanceProcAddr);
+        return .{
+            .alloc = alloc,
+            .vkb = vkb,
+            .vki = vki,
+            .instance = instance,
+        };
+    }
+    pub fn deinit(self: *Renderer) void {
+        self.vki.destroyInstance(self.instance, null);
+    }
+    pub fn createWaylandSurface(
+        self: *Renderer,
+        display: *anyopaque,
+        surface: *anyopaque,
+    ) !vk.SurfaceKHR {
+        return try self.vki.createWaylandSurfaceKHR(self.instance, &.{
+            .display = @ptrCast(display),
+            .surface = @ptrCast(surface),
+        }, null);
+    }
+};
+```
+**The exact vulkan-zig API (apis tuple, function names, field names) must be verified against the current version of vulkan-zig. Adjust as needed.**
+- [ ] **Step 2: Build**
+```bash
+zig build
+```
+Expected: builds. Will fail on many small API mismatches that need to be fixed.
+- [ ] **Step 3: Commit**
+```bash
+git add src/renderer.zig
+git commit -m "feat(renderer): Vulkan instance + wayland surface creation"
+```
+---
+### Task 6.4: Physical device + logical device + queues
+**Files:**
+- Modify: `src/renderer.zig`
+- [ ] **Step 1: Add device selection**
+Extend `Renderer`:
+```zig
+pub const DeviceInfo = struct {
+    physical: vk.PhysicalDevice,
+    graphics_queue_family: u32,
+    present_queue_family: u32,
+};
+pub fn pickPhysicalDevice(self: *Renderer, surface: vk.SurfaceKHR) !DeviceInfo {
+    var count: u32 = 0;
+    _ = try self.vki.enumeratePhysicalDevices(self.instance, &count, null);
+    const devices = try self.alloc.alloc(vk.PhysicalDevice, count);
+    defer self.alloc.free(devices);
+    _ = try self.vki.enumeratePhysicalDevices(self.instance, &count, devices.ptr);
+    for (devices[0..count]) |pd| {
+        var qf_count: u32 = 0;
+        self.vki.getPhysicalDeviceQueueFamilyProperties(pd, &qf_count, null);
+        const qfs = try self.alloc.alloc(vk.QueueFamilyProperties, qf_count);
+        defer self.alloc.free(qfs);
+        self.vki.getPhysicalDeviceQueueFamilyProperties(pd, &qf_count, qfs.ptr);
+        var graphics_idx: ?u32 = null;
+        var present_idx: ?u32 = null;
+        for (qfs[0..qf_count], 0..) |qf, i| {
+            if (qf.queue_flags.graphics_bit) graphics_idx = @intCast(i);
+            var supported: vk.Bool32 = vk.FALSE;
+            _ = try self.vki.getPhysicalDeviceSurfaceSupportKHR(pd, @intCast(i), surface, &supported);
+            if (supported == vk.TRUE) present_idx = @intCast(i);
+            if (graphics_idx != null and present_idx != null) break;
+        }
+        if (graphics_idx != null and present_idx != null) {
+            return .{
+                .physical = pd,
+                .graphics_queue_family = graphics_idx.?,
+                .present_queue_family = present_idx.?,
+            };
+        }
+    }
+    return error.NoSuitableDevice;
+}
+```
+- [ ] **Step 2: Add logical device creation**
+```zig
+pub const Device = struct {
+    vkd: DeviceDispatch,
+    handle: vk.Device,
+    graphics_queue: vk.Queue,
+    present_queue: vk.Queue,
+};
+pub fn createDevice(self: *Renderer, info: DeviceInfo) !Device {
+    const priority: f32 = 1.0;
+    var unique_families = [_]u32{ info.graphics_queue_family, info.present_queue_family };
+    // deduplicate
+    var unique_count: u32 = 1;
+    if (info.graphics_queue_family != info.present_queue_family) unique_count = 2;
+    var queue_infos: [2]vk.DeviceQueueCreateInfo = undefined;
+    for (0..unique_count) |i| {
+        queue_infos[i] = .{
+            .queue_family_index = unique_families[i],
+            .queue_count = 1,
+            .p_queue_priorities = @ptrCast(&priority),
+        };
+    }
+    const exts = [_][*:0]const u8{vk.extensions.khr_swapchain.name};
+    const device = try self.vki.createDevice(info.physical, &.{
+        .queue_create_info_count = unique_count,
+        .p_queue_create_infos = &queue_infos,
+        .enabled_extension_count = exts.len,
+        .pp_enabled_extension_names = &exts,
+    }, null);
+    const vkd = try DeviceDispatch.load(device, self.vki.dispatch.vkGetDeviceProcAddr);
+    return .{
+        .vkd = vkd,
+        .handle = device,
+        .graphics_queue = vkd.getDeviceQueue(device, info.graphics_queue_family, 0),
+        .present_queue = vkd.getDeviceQueue(device, info.present_queue_family, 0),
+    };
+}
+```
+- [ ] **Step 3: Build**
+```bash
+zig build
+```
+Expected: builds.
+- [ ] **Step 4: Commit**
+```bash
+git add src/renderer.zig
+git commit -m "feat(renderer): physical + logical device selection"
+```
+---
+### Task 6.5: Swapchain
+**Files:**
+- Modify: `src/renderer.zig`
+- [ ] **Step 1: Implement swapchain creation**
+```zig
+pub const Swapchain = struct {
+    handle: vk.SwapchainKHR,
+    format: vk.Format,
+    extent: vk.Extent2D,
+    images: []vk.Image,
+    image_views: []vk.ImageView,
+};
+pub fn createSwapchain(
+    self: *Renderer,
+    device: *Device,
+    info: DeviceInfo,
+    surface: vk.SurfaceKHR,
+    width: u32,
+    height: u32,
+) !Swapchain {
+    const caps = try self.vki.getPhysicalDeviceSurfaceCapabilitiesKHR(info.physical, surface);
+    var fmt_count: u32 = 0;
+    _ = try self.vki.getPhysicalDeviceSurfaceFormatsKHR(info.physical, surface, &fmt_count, null);
+    const formats = try self.alloc.alloc(vk.SurfaceFormatKHR, fmt_count);
+    defer self.alloc.free(formats);
+    _ = try self.vki.getPhysicalDeviceSurfaceFormatsKHR(info.physical, surface, &fmt_count, formats.ptr);
+    var chosen_format = formats[0];
+    for (formats[0..fmt_count]) |f| {
+        if (f.format == .b8g8r8a8_srgb and f.color_space == .srgb_nonlinear_khr) {
+            chosen_format = f;
+            break;
+        }
+    }
+    var extent = caps.current_extent;
+    if (extent.width == 0xFFFFFFFF) {
+        extent = .{ .width = width, .height = height };
+    }
+    var image_count: u32 = caps.min_image_count + 1;
+    if (caps.max_image_count > 0 and image_count > caps.max_image_count) {
+        image_count = caps.max_image_count;
+    }
+    const same_family = info.graphics_queue_family == info.present_queue_family;
+    const families = [_]u32{ info.graphics_queue_family, info.present_queue_family };
+    const handle = try device.vkd.createSwapchainKHR(device.handle, &.{
+        .surface = surface,
+        .min_image_count = image_count,
+        .image_format = chosen_format.format,
+        .image_color_space = chosen_format.color_space,
+        .image_extent = extent,
+        .image_array_layers = 1,
+        .image_usage = .{ .color_attachment_bit = true },
+        .image_sharing_mode = if (same_family) .exclusive else .concurrent,
+        .queue_family_index_count = if (same_family) 0 else 2,
+        .p_queue_family_indices = if (same_family) null else &families,
+        .pre_transform = caps.current_transform,
+        .composite_alpha = .{ .opaque_bit_khr = true },
+        .present_mode = .fifo_khr,
+        .clipped = vk.TRUE,
+    }, null);
+    var sc_image_count: u32 = 0;
+    _ = try device.vkd.getSwapchainImagesKHR(device.handle, handle, &sc_image_count, null);
+    const images = try self.alloc.alloc(vk.Image, sc_image_count);
+    _ = try device.vkd.getSwapchainImagesKHR(device.handle, handle, &sc_image_count, images.ptr);
+    const image_views = try self.alloc.alloc(vk.ImageView, sc_image_count);
+    for (images, image_views) |img, *view| {
+        view.* = try device.vkd.createImageView(device.handle, &.{
+            .image = img,
+            .view_type = .@"2d",
+            .format = chosen_format.format,
+            .components = .{ .r = .identity, .g = .identity, .b = .identity, .a = .identity },
+            .subresource_range = .{
+                .aspect_mask = .{ .color_bit = true },
+                .base_mip_level = 0,
+                .level_count = 1,
+                .base_array_layer = 0,
+                .layer_count = 1,
+            },
+        }, null);
+    }
+    return .{
+        .handle = handle,
+        .format = chosen_format.format,
+        .extent = extent,
+        .images = images,
+        .image_views = image_views,
+    };
+}
+```
+- [ ] **Step 2: Build**
+```bash
+zig build
+```
+Expected: builds.
+- [ ] **Step 3: Commit**
+```bash
+git add src/renderer.zig
+git commit -m "feat(renderer): swapchain with FIFO present mode"
+```
+---
+### Task 6.6: Render pass + framebuffers
+**Files:**
+- Modify: `src/renderer.zig`
+- [ ] **Step 1: Implement render pass**
+```zig
+pub fn createRenderPass(device: *Device, format: vk.Format) !vk.RenderPass {
+    const color_attachment = vk.AttachmentDescription{
+        .format = format,
+        .samples = .{ .@"1_bit" = true },
+        .load_op = .clear,
+        .store_op = .store,
+        .stencil_load_op = .dont_care,
+        .stencil_store_op = .dont_care,
+        .initial_layout = .undefined,
+        .final_layout = .present_src_khr,
+    };
+    const color_ref = vk.AttachmentReference{
+        .attachment = 0,
+        .layout = .color_attachment_optimal,
+    };
+    const subpass = vk.SubpassDescription{
+        .pipeline_bind_point = .graphics,
+        .color_attachment_count = 1,
+        .p_color_attachments = @ptrCast(&color_ref),
+    };
+    const dep = vk.SubpassDependency{
+        .src_subpass = vk.SUBPASS_EXTERNAL,
+        .dst_subpass = 0,
+        .src_stage_mask = .{ .color_attachment_output_bit = true },
+        .dst_stage_mask = .{ .color_attachment_output_bit = true },
+        .src_access_mask = .{},
+        .dst_access_mask = .{ .color_attachment_write_bit = true },
+    };
+    return try device.vkd.createRenderPass(device.handle, &.{
+        .attachment_count = 1,
+        .p_attachments = @ptrCast(&color_attachment),
+        .subpass_count = 1,
+        .p_subpasses = @ptrCast(&subpass),
+        .dependency_count = 1,
+        .p_dependencies = @ptrCast(&dep),
+    }, null);
+}
+pub fn createFramebuffers(
+    alloc: std.mem.Allocator,
+    device: *Device,
+    render_pass: vk.RenderPass,
+    swapchain: *const Swapchain,
+) ![]vk.Framebuffer {
+    const fbs = try alloc.alloc(vk.Framebuffer, swapchain.image_views.len);
+    for (swapchain.image_views, fbs) |view, *fb| {
+        fb.* = try device.vkd.createFramebuffer(device.handle, &.{
+            .render_pass = render_pass,
+            .attachment_count = 1,
+            .p_attachments = @ptrCast(&view),
+            .width = swapchain.extent.width,
+            .height = swapchain.extent.height,
+            .layers = 1,
+        }, null);
+    }
+    return fbs;
+}
+```
+- [ ] **Step 2: Build**
+```bash
+zig build
+```
+Expected: builds.
+- [ ] **Step 3: Commit**
+```bash
+git add src/renderer.zig
+git commit -m "feat(renderer): render pass + framebuffers"
+```
+---
+### Task 6.7: Graphics pipeline
+**Files:**
+- Modify: `src/renderer.zig`
+- [ ] **Step 1: Define vertex/instance formats and pipeline**
+Add to `src/renderer.zig`:
+```zig
+pub const Instance = extern struct {
+    cell_pos: [2]f32,
+    uv_rect: [4]f32,
+    fg: [4]f32,
+    bg: [4]f32,
+};
+pub const Vertex = extern struct {
+    unit_pos: [2]f32,
+};
+pub fn createPipeline(
+    device: *Device,
+    render_pass: vk.RenderPass,
+    pipeline_layout: vk.PipelineLayout,
+) !vk.Pipeline {
+    const vert_spv align(4) = @embedFile("cell.vert.spv").*;
+    const frag_spv align(4) = @embedFile("cell.frag.spv").*;
+    const vert_module = try device.vkd.createShaderModule(device.handle, &.{
+        .code_size = vert_spv.len,
+        .p_code = @ptrCast(&vert_spv),
+    }, null);
+    defer device.vkd.destroyShaderModule(device.handle, vert_module, null);
+    const frag_module = try device.vkd.createShaderModule(device.handle, &.{
+        .code_size = frag_spv.len,
+        .p_code = @ptrCast(&frag_spv),
+    }, null);
+    defer device.vkd.destroyShaderModule(device.handle, frag_module, null);
+    const stages = [_]vk.PipelineShaderStageCreateInfo{
+        .{
+            .stage = .{ .vertex_bit = true },
+            .module = vert_module,
+            .p_name = "main",
+        },
+        .{
+            .stage = .{ .fragment_bit = true },
+            .module = frag_module,
+            .p_name = "main",
+        },
+    };
+    const binding_descs = [_]vk.VertexInputBindingDescription{
+        .{ .binding = 0, .stride = @sizeOf(Vertex), .input_rate = .vertex },
+        .{ .binding = 1, .stride = @sizeOf(Instance), .input_rate = .instance },
+    };
+    const attr_descs = [_]vk.VertexInputAttributeDescription{
+        .{ .location = 0, .binding = 0, .format = .r32g32_sfloat, .offset = 0 },
+        .{ .location = 1, .binding = 1, .format = .r32g32_sfloat, .offset = @offsetOf(Instance, "cell_pos") },
+        .{ .location = 2, .binding = 1, .format = .r32g32b32a32_sfloat, .offset = @offsetOf(Instance, "uv_rect") },
+        .{ .location = 3, .binding = 1, .format = .r32g32b32a32_sfloat, .offset = @offsetOf(Instance, "fg") },
+        .{ .location = 4, .binding = 1, .format = .r32g32b32a32_sfloat, .offset = @offsetOf(Instance, "bg") },
+    };
+    const vertex_input = vk.PipelineVertexInputStateCreateInfo{
+        .vertex_binding_description_count = binding_descs.len,
+        .p_vertex_binding_descriptions = &binding_descs,
+        .vertex_attribute_description_count = attr_descs.len,
+        .p_vertex_attribute_descriptions = &attr_descs,
+    };
+    const input_assembly = vk.PipelineInputAssemblyStateCreateInfo{
+        .topology = .triangle_list,
+        .primitive_restart_enable = vk.FALSE,
+    };
+    const viewport_state = vk.PipelineViewportStateCreateInfo{
+        .viewport_count = 1,
+        .scissor_count = 1,
+    };
+    const rasterizer = vk.PipelineRasterizationStateCreateInfo{
+        .depth_clamp_enable = vk.FALSE,
+        .rasterizer_discard_enable = vk.FALSE,
+        .polygon_mode = .fill,
+        .cull_mode = .{},
+        .front_face = .counter_clockwise,
+        .depth_bias_enable = vk.FALSE,
+        .depth_bias_constant_factor = 0,
+        .depth_bias_clamp = 0,
+        .depth_bias_slope_factor = 0,
+        .line_width = 1.0,
+    };
+    const multisampling = vk.PipelineMultisampleStateCreateInfo{
+        .rasterization_samples = .{ .@"1_bit" = true },
+        .sample_shading_enable = vk.FALSE,
+        .min_sample_shading = 1.0,
+        .alpha_to_coverage_enable = vk.FALSE,
+        .alpha_to_one_enable = vk.FALSE,
+    };
+    const color_blend_attachment = vk.PipelineColorBlendAttachmentState{
+        .blend_enable = vk.FALSE,
+        .src_color_blend_factor = .one,
+        .dst_color_blend_factor = .zero,
+        .color_blend_op = .add,
+        .src_alpha_blend_factor = .one,
+        .dst_alpha_blend_factor = .zero,
+        .alpha_blend_op = .add,
+        .color_write_mask = .{ .r_bit = true, .g_bit = true, .b_bit = true, .a_bit = true },
+    };
+    const color_blend = vk.PipelineColorBlendStateCreateInfo{
+        .logic_op_enable = vk.FALSE,
+        .logic_op = .copy,
+        .attachment_count = 1,
+        .p_attachments = @ptrCast(&color_blend_attachment),
+        .blend_constants = [_]f32{ 0, 0, 0, 0 },
+    };
+    const dynamic_states = [_]vk.DynamicState{ .viewport, .scissor };
+    const dynamic_state = vk.PipelineDynamicStateCreateInfo{
+        .dynamic_state_count = dynamic_states.len,
+        .p_dynamic_states = &dynamic_states,
+    };
+    var pipeline: vk.Pipeline = undefined;
+    _ = try device.vkd.createGraphicsPipelines(
+        device.handle,
+        .null_handle,
+,
+        @ptrCast(&vk.GraphicsPipelineCreateInfo{
+            .stage_count = stages.len,
+            .p_stages = &stages,
+            .p_vertex_input_state = &vertex_input,
+            .p_input_assembly_state = &input_assembly,
+            .p_viewport_state = &viewport_state,
+            .p_rasterization_state = &rasterizer,
+            .p_multisample_state = &multisampling,
+            .p_color_blend_state = &color_blend,
+            .p_dynamic_state = &dynamic_state,
+            .layout = pipeline_layout,
+            .render_pass = render_pass,
+            .subpass = 0,
+            .base_pipeline_index = -1,
+        }),
+        null,
+        @ptrCast(&pipeline),
+    );
+    return pipeline;
+}
+```
+- [ ] **Step 2: Build**
+```bash
+zig build
+```
+Expected: builds.
+- [ ] **Step 3: Commit**
+```bash
+git add src/renderer.zig
+git commit -m "feat(renderer): graphics pipeline with instanced input"
+```
+---
+### Task 6.8: Glyph atlas texture upload
+**Files:**
+- Modify: `src/renderer.zig`
+- [ ] **Step 1: Implement uploadAtlas**
+Add helpers for buffer allocation and staging upload:
+```zig
+pub const GpuAtlas = struct {
+    image: vk.Image,
+    memory: vk.DeviceMemory,
+    view: vk.ImageView,
+    sampler: vk.Sampler,
+    width: u32,
+    height: u32,
+};
+pub fn findMemoryType(
+    vki: InstanceDispatch,
+    physical: vk.PhysicalDevice,
+    type_filter: u32,
+    properties: vk.MemoryPropertyFlags,
+) !u32 {
+    const mem_props = vki.getPhysicalDeviceMemoryProperties(physical);
+    var i: u32 = 0;
+    while (i < mem_props.memory_type_count) : (i += 1) {
+        if ((type_filter & (@as(u32, 1) << @intCast(i))) != 0 and
+            mem_props.memory_types[i].property_flags.contains(properties))
+        {
+            return i;
+        }
+    }
+    return error.NoSuitableMemoryType;
+}
+pub fn createAtlasTexture(
+    vki: InstanceDispatch,
+    physical: vk.PhysicalDevice,
+    device: *Device,
+    width: u32,
+    height: u32,
+) !GpuAtlas {
+    const image = try device.vkd.createImage(device.handle, &.{
+        .image_type = .@"2d",
+        .format = .r8_unorm,
+        .extent = .{ .width = width, .height = height, .depth = 1 },
+        .mip_levels = 1,
+        .array_layers = 1,
+        .samples = .{ .@"1_bit" = true },
+        .tiling = .optimal,
+        .usage = .{ .transfer_dst_bit = true, .sampled_bit = true },
+        .sharing_mode = .exclusive,
+        .initial_layout = .undefined,
+    }, null);
+    const mem_reqs = device.vkd.getImageMemoryRequirements(device.handle, image);
+    const mem_type = try findMemoryType(
+        vki,
+        physical,
+        mem_reqs.memory_type_bits,
+        .{ .device_local_bit = true },
+    );
+    const memory = try device.vkd.allocateMemory(device.handle, &.{
+        .allocation_size = mem_reqs.size,
+        .memory_type_index = mem_type,
+    }, null);
+    try device.vkd.bindImageMemory(device.handle, image, memory, 0);
+    const view = try device.vkd.createImageView(device.handle, &.{
+        .image = image,
+        .view_type = .@"2d",
+        .format = .r8_unorm,
+        .components = .{ .r = .identity, .g = .identity, .b = .identity, .a = .identity },
+        .subresource_range = .{
+            .aspect_mask = .{ .color_bit = true },
+            .base_mip_level = 0,
+            .level_count = 1,
+            .base_array_layer = 0,
+            .layer_count = 1,
+        },
+    }, null);
+    const sampler = try device.vkd.createSampler(device.handle, &.{
+        .mag_filter = .nearest,
+        .min_filter = .nearest,
+        .mipmap_mode = .nearest,
+        .address_mode_u = .clamp_to_edge,
+        .address_mode_v = .clamp_to_edge,
+        .address_mode_w = .clamp_to_edge,
+        .mip_lod_bias = 0,
+        .anisotropy_enable = vk.FALSE,
+        .max_anisotropy = 1,
+        .compare_enable = vk.FALSE,
+        .compare_op = .always,
+        .min_lod = 0,
+        .max_lod = 0,
+        .border_color = .int_opaque_black,
+        .unnormalized_coordinates = vk.FALSE,
+    }, null);
+    return .{
+        .image = image,
+        .memory = memory,
+        .view = view,
+        .sampler = sampler,
+        .width = width,
+        .height = height,
+    };
+}
+/// Upload CPU pixel data to GPU atlas texture via staging buffer.
+/// Caller provides command pool + queue for one-shot submit.
+pub fn uploadAtlasPixels(
+    vki: InstanceDispatch,
+    physical: vk.PhysicalDevice,
+    device: *Device,
+    atlas: *GpuAtlas,
+    pixels: []const u8,
+    command_pool: vk.CommandPool,
+) !void {
+    // Create staging buffer
+    const staging = try device.vkd.createBuffer(device.handle, &.{
+        .size = pixels.len,
+        .usage = .{ .transfer_src_bit = true },
+        .sharing_mode = .exclusive,
+    }, null);
+    defer device.vkd.destroyBuffer(device.handle, staging, null);
+    const staging_reqs = device.vkd.getBufferMemoryRequirements(device.handle, staging);
+    const staging_mem_type = try findMemoryType(
+        vki,
+        physical,
+        staging_reqs.memory_type_bits,
+        .{ .host_visible_bit = true, .host_coherent_bit = true },
+    );
+    const staging_mem = try device.vkd.allocateMemory(device.handle, &.{
+        .allocation_size = staging_reqs.size,
+        .memory_type_index = staging_mem_type,
+    }, null);
+    defer device.vkd.freeMemory(device.handle, staging_mem, null);
+    try device.vkd.bindBufferMemory(device.handle, staging, staging_mem, 0);
+    const mapped = try device.vkd.mapMemory(device.handle, staging_mem, 0, pixels.len, .{});
+    @memcpy(@as([*]u8, @ptrCast(mapped))[0..pixels.len], pixels);
+    device.vkd.unmapMemory(device.handle, staging_mem);
+    // One-shot command buffer
+    var cmd: vk.CommandBuffer = undefined;
+    _ = try device.vkd.allocateCommandBuffers(device.handle, &.{
+        .command_pool = command_pool,
+        .level = .primary,
+        .command_buffer_count = 1,
+    }, @ptrCast(&cmd));
+    defer device.vkd.freeCommandBuffers(device.handle, command_pool, 1, @ptrCast(&cmd));
+    try device.vkd.beginCommandBuffer(cmd, &.{ .flags = .{ .one_time_submit_bit = true } });
+    // Transition: undefined -> transfer_dst_optimal
+    const barrier_to_dst = vk.ImageMemoryBarrier{
+        .src_access_mask = .{},
+        .dst_access_mask = .{ .transfer_write_bit = true },
+        .old_layout = .undefined,
+        .new_layout = .transfer_dst_optimal,
+        .src_queue_family_index = vk.QUEUE_FAMILY_IGNORED,
+        .dst_queue_family_index = vk.QUEUE_FAMILY_IGNORED,
+        .image = atlas.image,
+        .subresource_range = .{
+            .aspect_mask = .{ .color_bit = true },
+            .base_mip_level = 0,
+            .level_count = 1,
+            .base_array_layer = 0,
+            .layer_count = 1,
+        },
+    };
+    device.vkd.cmdPipelineBarrier(
+        cmd,
+        .{ .top_of_pipe_bit = true },
+        .{ .transfer_bit = true },
+        .{},
+, null,
+, null,
+, @ptrCast(&barrier_to_dst),
+    );
+    const region = vk.BufferImageCopy{
+        .buffer_offset = 0,
+        .buffer_row_length = 0,
+        .buffer_image_height = 0,
+        .image_subresource = .{
+            .aspect_mask = .{ .color_bit = true },
+            .mip_level = 0,
+            .base_array_layer = 0,
+            .layer_count = 1,
+        },
+        .image_offset = .{ .x = 0, .y = 0, .z = 0 },
+        .image_extent = .{ .width = atlas.width, .height = atlas.height, .depth = 1 },
+    };
+    device.vkd.cmdCopyBufferToImage(cmd, staging, atlas.image, .transfer_dst_optimal, 1, @ptrCast(&region));
+    // Transition: transfer_dst_optimal -> shader_read_only_optimal
+    const barrier_to_shader = vk.ImageMemoryBarrier{
+        .src_access_mask = .{ .transfer_write_bit = true },
+        .dst_access_mask = .{ .shader_read_bit = true },
+        .old_layout = .transfer_dst_optimal,
+        .new_layout = .shader_read_only_optimal,
+        .src_queue_family_index = vk.QUEUE_FAMILY_IGNORED,
+        .dst_queue_family_index = vk.QUEUE_FAMILY_IGNORED,
+        .image = atlas.image,
+        .subresource_range = .{
+            .aspect_mask = .{ .color_bit = true },
+            .base_mip_level = 0,
+            .level_count = 1,
+            .base_array_layer = 0,
+            .layer_count = 1,
+        },
+    };
+    device.vkd.cmdPipelineBarrier(
+        cmd,
+        .{ .transfer_bit = true },
+        .{ .fragment_shader_bit = true },
+        .{},
+, null,
+, null,
+, @ptrCast(&barrier_to_shader),
+    );
+    try device.vkd.endCommandBuffer(cmd);
+    const submit = vk.SubmitInfo{
+        .command_buffer_count = 1,
+        .p_command_buffers = @ptrCast(&cmd),
+    };
+    _ = try device.vkd.queueSubmit(device.graphics_queue, 1, @ptrCast(&submit), .null_handle);
+    _ = try device.vkd.queueWaitIdle(device.graphics_queue);
+}
+```
+- [ ] **Step 2: Build**
+```bash
+zig build
+```
+Expected: builds.
+- [ ] **Step 3: Commit**
+```bash
+git add src/renderer.zig
+git commit -m "feat(renderer): glyph atlas texture upload via staging buffer"
+```
+---
+### Task 6.9: Per-frame draw — instance buffer + draw call
+**Files:**
+- Modify: `src/renderer.zig`
+- [ ] **Step 1: Implement drawFrame**
+Add a high-level draw function that takes:
+- An array of `Instance` (one per visible cell)
+- The descriptor set bound to the glyph atlas
+- The current swapchain image index
+- The framebuffer, pipeline, pipeline_layout, command buffer
+```zig
+pub const FrameContext = struct {
+    command_buffer: vk.CommandBuffer,
+    framebuffer: vk.Framebuffer,
+    render_pass: vk.RenderPass,
+    pipeline: vk.Pipeline,
+    pipeline_layout: vk.PipelineLayout,
+    descriptor_set: vk.DescriptorSet,
+    viewport_size: [2]f32,
+    cell_size: [2]f32,
+    extent: vk.Extent2D,
+    instance_buffer: vk.Buffer,
+    quad_vertex_buffer: vk.Buffer,
+    instance_count: u32,
+};
+pub const PushConstants = extern struct {
+    viewport_size: [2]f32,
+    cell_size: [2]f32,
+};
+pub fn recordFrame(device: *Device, ctx: FrameContext) !void {
+    try device.vkd.beginCommandBuffer(ctx.command_buffer, &.{});
+    const clear_value = vk.ClearValue{
+        .color = .{ .float_32 = .{ 0.05, 0.05, 0.05, 1.0 } },
+    };
+    device.vkd.cmdBeginRenderPass(ctx.command_buffer, &.{
+        .render_pass = ctx.render_pass,
+        .framebuffer = ctx.framebuffer,
+        .render_area = .{ .offset = .{ .x = 0, .y = 0 }, .extent = ctx.extent },
+        .clear_value_count = 1,
+        .p_clear_values = @ptrCast(&clear_value),
+    }, .@"inline");
+    device.vkd.cmdBindPipeline(ctx.command_buffer, .graphics, ctx.pipeline);
+    const viewport = vk.Viewport{
+        .x = 0, .y = 0,
+        .width = @floatFromInt(ctx.extent.width),
+        .height = @floatFromInt(ctx.extent.height),
+        .min_depth = 0, .max_depth = 1,
+    };
+    const scissor = vk.Rect2D{ .offset = .{ .x = 0, .y = 0 }, .extent = ctx.extent };
+    device.vkd.cmdSetViewport(ctx.command_buffer, 0, 1, @ptrCast(&viewport));
+    device.vkd.cmdSetScissor(ctx.command_buffer, 0, 1, @ptrCast(&scissor));
+    const pc = PushConstants{
+        .viewport_size = ctx.viewport_size,
+        .cell_size = ctx.cell_size,
+    };
+    device.vkd.cmdPushConstants(
+        ctx.command_buffer,
+        ctx.pipeline_layout,
+        .{ .vertex_bit = true },
+,
+        @sizeOf(PushConstants),
+        @ptrCast(&pc),
+    );
+    device.vkd.cmdBindDescriptorSets(
+        ctx.command_buffer,
+        .graphics,
+        ctx.pipeline_layout,
+,
+,
+        @ptrCast(&ctx.descriptor_set),
+,
+        null,
+    );
+    const buffers = [_]vk.Buffer{ ctx.quad_vertex_buffer, ctx.instance_buffer };
+    const offsets = [_]vk.DeviceSize{ 0, 0 };
+    device.vkd.cmdBindVertexBuffers(ctx.command_buffer, 0, 2, &buffers, &offsets);
+    device.vkd.cmdDraw(ctx.command_buffer, 6, ctx.instance_count, 0, 0);
+    device.vkd.cmdEndRenderPass(ctx.command_buffer);
+    try device.vkd.endCommandBuffer(ctx.command_buffer);
+}
+```
+- [ ] **Step 2: Build**
+```bash
+zig build
+```
+Expected: builds.
+- [ ] **Step 3: Commit**
+```bash
+git add src/renderer.zig
+git commit -m "feat(renderer): recordFrame with instanced draw"
+```
+---
+## Phase 7: Full Integration
+### Task 7.1: main.zig — init all subsystems
+**Files:**
+- Modify: `src/main.zig`
+- [ ] **Step 1: Write full initialization sequence**
+```zig
+const std = @import("std");
+const vt = @import("vt");
+const pty = @import("pty");
+const font = @import("font");
+const wayland_mod = @import("wayland-client");
+const renderer_mod = @import("renderer");
+const FontSize = 14;
+const Cols = 80;
+const Rows = 24;
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+    const alloc = gpa.allocator();
+    // 1. Wayland connection
+    var conn = try wayland_mod.Connection.init();
+    defer conn.deinit();
+    // 2. Font
+    var lookup = try font.lookupMonospace(alloc);
+    defer lookup.deinit(alloc);
+    var face = try font.Face.init(alloc, lookup.path, lookup.index, FontSize);
+    defer face.deinit();
+    const cell_w = face.cellWidth();
+    const cell_h = face.cellHeight();
+    // 3. Window (sized to match grid)
+    const win_w: u32 = @as(u32, Cols) * cell_w;
+    const win_h: u32 = @as(u32, Rows) * cell_h;
+    var window = try conn.createWindow("waystty");
+    defer window.deinit();
+    window.width = win_w;
+    window.height = win_h;
+    // 4. Vulkan renderer (init instance, pick device, create swapchain, etc.)
+    //    This is the big block — see Task 7.2 for the details wired together.
+    // 5. Atlas
+    var atlas = try font.Atlas.init(alloc, 1024, 1024);
+    defer atlas.deinit();
+    // 6. Terminal
+    var term = try vt.Terminal.init(alloc, .{
+        .cols = Cols,
+        .rows = Rows,
+        .max_scrollback = 1000,
+    });
+    defer term.deinit();
+    // 7. PTY
+    const shell = std.posix.getenv("SHELL") orelse "/bin/sh";
+    var p = try pty.Pty.spawn(.{
+        .cols = Cols,
+        .rows = Rows,
+        .shell = shell,
+    });
+    defer p.deinit();
+    // 8. Encoders
+    var key_encoder = try vt.KeyEncoder.init(alloc);
+    defer key_encoder.deinit();
+    // 9. Main loop — see Task 7.3
+    std.debug.print("waystty init complete\n", .{});
+}
+```
+- [ ] **Step 2: Build**
+```bash
+zig build
+```
+Expected: builds (won't have a working terminal yet — just init).
+- [ ] **Step 3: Commit**
+```bash
+git add src/main.zig
+git commit -m "feat(main): initialize all subsystems"
+```
+---
+### Task 7.2: Vulkan renderer wire-up
+**Files:**
+- Modify: `src/main.zig`
+- Modify: `src/renderer.zig` (add a high-level `Context` bundling all Vulkan state)
+- [ ] **Step 1: Add a high-level Renderer.Context that owns everything**
+Add to `src/renderer.zig`:
+```zig
+pub const Context = struct {
+    alloc: std.mem.Allocator,
+    renderer: Renderer,
+    device_info: DeviceInfo,
+    device: Device,
+    surface: vk.SurfaceKHR,
+    swapchain: Swapchain,
+    render_pass: vk.RenderPass,
+    framebuffers: []vk.Framebuffer,
+    pipeline_layout: vk.PipelineLayout,
+    pipeline: vk.Pipeline,
+    descriptor_pool: vk.DescriptorPool,
+    descriptor_set_layout: vk.DescriptorSetLayout,
+    descriptor_set: vk.DescriptorSet,
+    command_pool: vk.CommandPool,
+    command_buffer: vk.CommandBuffer,
+    image_available: vk.Semaphore,
+    render_finished: vk.Semaphore,
+    in_flight_fence: vk.Fence,
+    quad_vertex_buffer: vk.Buffer,
+    quad_vertex_memory: vk.DeviceMemory,
+    instance_buffer: vk.Buffer,
+    instance_memory: vk.DeviceMemory,
+    instance_capacity: u32,
+    gpu_atlas: GpuAtlas,
+    pub fn init(
+        alloc: std.mem.Allocator,
+        display: *anyopaque,
+        surface: *anyopaque,
+        width: u32,
+        height: u32,
+        loader: anytype,
+    ) !Context {
+        var r = try Renderer.init(alloc, loader);
+        errdefer r.deinit();
+        const vk_surface = try r.createWaylandSurface(display, surface);
+        const info = try r.pickPhysicalDevice(vk_surface);
+        var device = try r.createDevice(info);
+        var sc = try r.createSwapchain(&device, info, vk_surface, width, height);
+        const rp = try createRenderPass(&device, sc.format);
+        const fbs = try createFramebuffers(alloc, &device, rp, &sc);
+        // descriptor set layout (single combined image sampler)
+        const binding = vk.DescriptorSetLayoutBinding{
+            .binding = 0,
+            .descriptor_type = .combined_image_sampler,
+            .descriptor_count = 1,
+            .stage_flags = .{ .fragment_bit = true },
+        };
+        const dsl = try device.vkd.createDescriptorSetLayout(device.handle, &.{
+            .binding_count = 1,
+            .p_bindings = @ptrCast(&binding),
+        }, null);
+        // push constants
+        const push_range = vk.PushConstantRange{
+            .stage_flags = .{ .vertex_bit = true },
+            .offset = 0,
+            .size = @sizeOf(PushConstants),
+        };
+        const pl = try device.vkd.createPipelineLayout(device.handle, &.{
+            .set_layout_count = 1,
+            .p_set_layouts = @ptrCast(&dsl),
+            .push_constant_range_count = 1,
+            .p_push_constant_ranges = @ptrCast(&push_range),
+        }, null);
+        const pipeline = try createPipeline(&device, rp, pl);
+        // descriptor pool + set
+        const pool_size = vk.DescriptorPoolSize{
+            .type = .combined_image_sampler,
+            .descriptor_count = 1,
+        };
+        const dp = try device.vkd.createDescriptorPool(device.handle, &.{
+            .max_sets = 1,
+            .pool_size_count = 1,
+            .p_pool_sizes = @ptrCast(&pool_size),
+        }, null);
+        var ds: vk.DescriptorSet = undefined;
+        _ = try device.vkd.allocateDescriptorSets(device.handle, &.{
+            .descriptor_pool = dp,
+            .descriptor_set_count = 1,
+            .p_set_layouts = @ptrCast(&dsl),
+        }, @ptrCast(&ds));
+        // command pool + buffer
+        const cp = try device.vkd.createCommandPool(device.handle, &.{
+            .flags = .{ .reset_command_buffer_bit = true },
+            .queue_family_index = info.graphics_queue_family,
+        }, null);
+        var cb: vk.CommandBuffer = undefined;
+        _ = try device.vkd.allocateCommandBuffers(device.handle, &.{
+            .command_pool = cp,
+            .level = .primary,
+            .command_buffer_count = 1,
+        }, @ptrCast(&cb));
+        // sync
+        const sem_info = vk.SemaphoreCreateInfo{};
+        const fence_info = vk.FenceCreateInfo{ .flags = .{ .signaled_bit = true } };
+        const ia = try device.vkd.createSemaphore(device.handle, &sem_info, null);
+        const rf = try device.vkd.createSemaphore(device.handle, &sem_info, null);
+        const iff = try device.vkd.createFence(device.handle, &fence_info, null);
+        // GPU atlas
+        const gpu_atlas = try createAtlasTexture(r.vki, info.physical, &device, 1024, 1024);
+        // Update descriptor set to point at atlas
+        const img_info = vk.DescriptorImageInfo{
+            .sampler = gpu_atlas.sampler,
+            .image_view = gpu_atlas.view,
+            .image_layout = .shader_read_only_optimal,
+        };
+        const write = vk.WriteDescriptorSet{
+            .dst_set = ds,
+            .dst_binding = 0,
+            .dst_array_element = 0,
+            .descriptor_count = 1,
+            .descriptor_type = .combined_image_sampler,
+            .p_image_info = @ptrCast(&img_info),
+            .p_buffer_info = undefined,
+            .p_texel_buffer_view = undefined,
+        };
+        device.vkd.updateDescriptorSets(device.handle, 1, @ptrCast(&write), 0, null);
+        // Static quad vertex buffer (6 vertices: two triangles forming unit quad)
+        const quad_verts = [_]Vertex{
+            .{ .unit_pos = .{ 0, 0 } },
+            .{ .unit_pos = .{ 1, 0 } },
+            .{ .unit_pos = .{ 1, 1 } },
+            .{ .unit_pos = .{ 0, 0 } },
+            .{ .unit_pos = .{ 1, 1 } },
+            .{ .unit_pos = .{ 0, 1 } },
+        };
+        const quad_vb_result = try createHostVisibleBuffer(
+            r.vki, info.physical, &device,
+            @sizeOf(@TypeOf(quad_verts)),
+            .{ .vertex_buffer_bit = true },
+        );
+        {
+            const mapped = try device.vkd.mapMemory(device.handle, quad_vb_result.memory, 0, @sizeOf(@TypeOf(quad_verts)), .{});
+            @memcpy(
+                @as([*]Vertex, @ptrCast(@alignCast(mapped)))[0..quad_verts.len],
+                &quad_verts,
+            );
+            device.vkd.unmapMemory(device.handle, quad_vb_result.memory);
+        }
+        // Pre-allocate instance buffer (large enough for 200x80 grid)
+        const max_instances: u32 = 200 * 80;
+        const instance_buffer_size: vk.DeviceSize = @sizeOf(Instance) * max_instances;
+        const inst_result = try createHostVisibleBuffer(
+            r.vki, info.physical, &device,
+            instance_buffer_size,
+            .{ .vertex_buffer_bit = true },
+        );
+        return .{
+            .alloc = alloc,
+            .renderer = r,
+            .device_info = info,
+            .device = device,
+            .surface = vk_surface,
+            .swapchain = sc,
+            .render_pass = rp,
+            .framebuffers = fbs,
+            .pipeline_layout = pl,
+            .pipeline = pipeline,
+            .descriptor_pool = dp,
+            .descriptor_set_layout = dsl,
+            .descriptor_set = ds,
+            .command_pool = cp,
+            .command_buffer = cb,
+            .image_available = ia,
+            .render_finished = rf,
+            .in_flight_fence = iff,
+            .quad_vertex_buffer = quad_vb_result.buffer,
+            .quad_vertex_memory = quad_vb_result.memory,
+            .instance_buffer = inst_result.buffer,
+            .instance_memory = inst_result.memory,
+            .instance_capacity = max_instances,
+            .gpu_atlas = gpu_atlas,
+        };
+    }
+    pub fn deinit(self: *Context) void {
+        _ = self.device.vkd.deviceWaitIdle(self.device.handle) catch {};
+        // free all vulkan objects in reverse order
+        self.device.vkd.destroyFence(self.device.handle, self.in_flight_fence, null);
+        self.device.vkd.destroySemaphore(self.device.handle, self.render_finished, null);
+        self.device.vkd.destroySemaphore(self.device.handle, self.image_available, null);
+        self.device.vkd.destroyCommandPool(self.device.handle, self.command_pool, null);
+        self.device.vkd.destroyDescriptorPool(self.device.handle, self.descriptor_pool, null);
+        self.device.vkd.destroyDescriptorSetLayout(self.device.handle, self.descriptor_set_layout, null);
+        self.device.vkd.destroySampler(self.device.handle, self.gpu_atlas.sampler, null);
+        self.device.vkd.destroyImageView(self.device.handle, self.gpu_atlas.view, null);
+        self.device.vkd.destroyImage(self.device.handle, self.gpu_atlas.image, null);
+        self.device.vkd.freeMemory(self.device.handle, self.gpu_atlas.memory, null);
+        self.device.vkd.destroyBuffer(self.device.handle, self.quad_vertex_buffer, null);
+        self.device.vkd.freeMemory(self.device.handle, self.quad_vertex_memory, null);
+        self.device.vkd.destroyBuffer(self.device.handle, self.instance_buffer, null);
+        self.device.vkd.freeMemory(self.device.handle, self.instance_memory, null);
+        self.device.vkd.destroyPipeline(self.device.handle, self.pipeline, null);
+        self.device.vkd.destroyPipelineLayout(self.device.handle, self.pipeline_layout, null);
+        for (self.framebuffers) |fb| self.device.vkd.destroyFramebuffer(self.device.handle, fb, null);
+        self.alloc.free(self.framebuffers);
+        self.device.vkd.destroyRenderPass(self.device.handle, self.render_pass, null);
+        for (self.swapchain.image_views) |iv| self.device.vkd.destroyImageView(self.device.handle, iv, null);
+        self.alloc.free(self.swapchain.image_views);
+        self.alloc.free(self.swapchain.images);
+        self.device.vkd.destroySwapchainKHR(self.device.handle, self.swapchain.handle, null);
+        self.device.vkd.destroyDevice(self.device.handle, null);
+        self.renderer.vki.destroySurfaceKHR(self.renderer.instance, self.surface, null);
+        self.renderer.deinit();
+    }
+    pub fn uploadInstances(self: *Context, instances: []const Instance) !void {
+        if (instances.len > self.instance_capacity) return error.InstanceBufferTooSmall;
+        const size = @sizeOf(Instance) * instances.len;
+        const mapped = try self.device.vkd.mapMemory(self.device.handle, self.instance_memory, 0, size, .{});
+        @memcpy(
+            @as([*]Instance, @ptrCast(@alignCast(mapped)))[0..instances.len],
+            instances,
+        );
+        self.device.vkd.unmapMemory(self.device.handle, self.instance_memory);
+    }
+};
+pub const BufferResult = struct { buffer: vk.Buffer, memory: vk.DeviceMemory };
+pub fn createHostVisibleBuffer(
+    vki: InstanceDispatch,
+    physical: vk.PhysicalDevice,
+    device: *Device,
+    size: vk.DeviceSize,
+    usage: vk.BufferUsageFlags,
+) !BufferResult {
+    const buf = try device.vkd.createBuffer(device.handle, &.{
+        .size = size,
+        .usage = usage,
+        .sharing_mode = .exclusive,
+    }, null);
+    const reqs = device.vkd.getBufferMemoryRequirements(device.handle, buf);
+    const idx = try findMemoryType(
+        vki, physical,
+        reqs.memory_type_bits,
+        .{ .host_visible_bit = true, .host_coherent_bit = true },
+    );
+    const mem = try device.vkd.allocateMemory(device.handle, &.{
+        .allocation_size = reqs.size,
+        .memory_type_index = idx,
+    }, null);
+    try device.vkd.bindBufferMemory(device.handle, buf, mem, 0);
+    return .{ .buffer = buf, .memory = mem };
+}
+```
+- [ ] **Step 2: Build**
+```bash
+zig build
+```
+Expected: builds.
+- [ ] **Step 3: Commit**
+```bash
+git add src/renderer.zig
+git commit -m "feat(renderer): Context bundle with full Vulkan lifecycle"
+```
+---
+### Task 7.3: Main event loop
+**Files:**
+- Modify: `src/main.zig`
+- [ ] **Step 1: Wire up the full poll() loop**
+Replace `src/main.zig`:
+```zig
+const std = @import("std");
+const vt = @import("vt");
+const pty = @import("pty");
+const font = @import("font");
+const wayland_mod = @import("wayland-client");
+const renderer_mod = @import("renderer");
+const FontSize = 14;
+const Cols = 80;
+const Rows = 24;
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+    const alloc = gpa.allocator();
+    // === Wayland ===
+    var conn = try wayland_mod.Connection.init();
+    defer conn.deinit();
+    // === Font ===
+    var lookup = try font.lookupMonospace(alloc);
+    defer lookup.deinit(alloc);
+    var face = try font.Face.init(alloc, lookup.path, lookup.index, FontSize);
+    defer face.deinit();
+    const cell_w = face.cellWidth();
+    const cell_h = face.cellHeight();
+    // === Window ===
+    const win_w: u32 = @as(u32, Cols) * cell_w;
+    const win_h: u32 = @as(u32, Rows) * cell_h;
+    var window = try conn.createWindow("waystty");
+    defer window.deinit();
+    window.width = win_w;
+    window.height = win_h;
+    _ = conn.display.roundtrip();
+    // === Vulkan ===
+    var ctx = try renderer_mod.Context.init(
+        alloc,
+        @ptrCast(conn.display),
+        @ptrCast(window.surface),
+        win_w,
+        win_h,
+        vkGetInstanceProcAddrStub,
+    );
+    defer ctx.deinit();
+    // === Atlas ===
+    var atlas = try font.Atlas.init(alloc, 1024, 1024);
+    defer atlas.deinit();
+    // === Terminal ===
+    var term = try vt.Terminal.init(alloc, .{
+        .cols = Cols,
+        .rows = Rows,
+        .max_scrollback = 1000,
+    });
+    defer term.deinit();
+    // === Encoders ===
+    var key_encoder = try vt.KeyEncoder.init(alloc);
+    defer key_encoder.deinit();
+    // === PTY ===
+    const shell = std.posix.getenv("SHELL") orelse "/bin/sh";
+    var p = try pty.Pty.spawn(.{
+        .cols = Cols,
+        .rows = Rows,
+        .shell = shell,
+    });
+    defer p.deinit();
+    // === Keyboard ===
+    var keyboard = try wayland_mod.Keyboard.init(alloc, conn.globals.seat.?);
+    defer keyboard.deinit(alloc);
+    // === Main loop ===
+    const wl_fd = conn.display.getFd();
+    var pollfds = [_]std.posix.pollfd{
+        .{ .fd = wl_fd, .events = std.posix.POLL.IN, .revents = 0 },
+        .{ .fd = p.master_fd, .events = std.posix.POLL.IN, .revents = 0 },
+    };
+    var render_state = try vt.RenderState.init(alloc);
+    defer render_state.deinit();
+    var read_buf: [8192]u8 = undefined;
+    var encode_buf: [64]u8 = undefined;
+    while (!window.should_close and p.child_pid > 0) {
+        // Flush pending wayland requests before polling
+        _ = conn.display.flush();
+        _ = std.posix.poll(&pollfds, 10) catch continue;
+        if (pollfds[0].revents & std.posix.POLL.IN != 0) {
+            _ = conn.display.dispatch();
+        }
+        if (pollfds[1].revents & std.posix.POLL.IN != 0) {
+            const n = p.read(&read_buf) catch |err| switch (err) {
+                error.WouldBlock => 0,
+                else => return err,
+            };
+            if (n > 0) try term.write(read_buf[0..n]);
+        }
+        // Drain keyboard events
+        keyboard.tickRepeat();
+        for (keyboard.event_queue.items) |kev| {
+            if (kev.action == .release) continue;
+            try key_encoder.syncFromTerminal(&term);
+            const len = try key_encoder.encode(&encode_buf, .{
+                .keysym = kev.keysym,
+                .modifiers = .{
+                    .ctrl = kev.modifiers.ctrl,
+                    .shift = kev.modifiers.shift,
+                    .alt = kev.modifiers.alt,
+                    .super = kev.modifiers.super,
+                },
+                .action = switch (kev.action) {
+                    .press => .press,
+                    .repeat => .repeat,
+                    .release => .release,
+                },
+            });
+            if (len > 0) _ = try p.write(encode_buf[0..len]);
+        }
+        keyboard.event_queue.clearRetainingCapacity();
+        // Render
+        try render_state.update(&term);
+        var instances = std.ArrayList(renderer_mod.Instance).init(alloc);
+        defer instances.deinit();
+        var row_iter = try render_state.rowIterator();
+        defer row_iter.deinit();
+        var row_y: u32 = 0;
+        while (try row_iter.next()) |row_| {
+            var row = row_;
+            defer row.deinit();
+            var cells = row.cells();
+            defer cells.deinit();
+            var col_x: u32 = 0;
+            while (try cells.next()) |cell| {
+                if (cell.codepoint == ' ' and cell.bg.r == 0 and cell.bg.g == 0 and cell.bg.b == 0) {
+                    col_x += 1;
+                    continue;
+                }
+                const uv = try atlas.getOrInsert(&face, cell.codepoint);
+                try instances.append(.{
+                    .cell_pos = .{ @floatFromInt(col_x), @floatFromInt(row_y) },
+                    .uv_rect = .{ uv.u0, uv.v0, uv.u1, uv.v1 },
+                    .fg = .{
+                        @as(f32, @floatFromInt(cell.fg.r)) / 255.0,
+                        @as(f32, @floatFromInt(cell.fg.g)) / 255.0,
+                        @as(f32, @floatFromInt(cell.fg.b)) / 255.0,
+.0,
+                    },
+                    .bg = .{
+                        @as(f32, @floatFromInt(cell.bg.r)) / 255.0,
+                        @as(f32, @floatFromInt(cell.bg.g)) / 255.0,
+                        @as(f32, @floatFromInt(cell.bg.b)) / 255.0,
+.0,
+                    },
+                });
+                col_x += 1;
+            }
+            row_y += 1;
+        }
+        // If atlas got new glyphs, reupload
+        if (atlas.dirty) {
+            try renderer_mod.uploadAtlasPixels(
+                ctx.renderer.vki,
+                ctx.device_info.physical,
+                &ctx.device,
+                &ctx.gpu_atlas,
+                atlas.pixels,
+                ctx.command_pool,
+            );
+            atlas.dirty = false;
+        }
+        try ctx.uploadInstances(instances.items);
+        try renderFrame(&ctx, @intCast(instances.items.len), cell_w, cell_h);
+    }
+}
+fn renderFrame(ctx: *renderer_mod.Context, instance_count: u32, cell_w: u32, cell_h: u32) !void {
+    const vk = @import("vulkan");
+    _ = vk;
+    _ = try ctx.device.vkd.waitForFences(ctx.device.handle, 1, @ptrCast(&ctx.in_flight_fence), 1, std.math.maxInt(u64));
+    try ctx.device.vkd.resetFences(ctx.device.handle, 1, @ptrCast(&ctx.in_flight_fence));
+    var image_index: u32 = 0;
+    _ = try ctx.device.vkd.acquireNextImageKHR(
+        ctx.device.handle,
+        ctx.swapchain.handle,
+        std.math.maxInt(u64),
+        ctx.image_available,
+        .null_handle,
+        &image_index,
+    );
+    try ctx.device.vkd.resetCommandBuffer(ctx.command_buffer, .{});
+    try renderer_mod.recordFrame(&ctx.device, .{
+        .command_buffer = ctx.command_buffer,
+        .framebuffer = ctx.framebuffers[image_index],
+        .render_pass = ctx.render_pass,
+        .pipeline = ctx.pipeline,
+        .pipeline_layout = ctx.pipeline_layout,
+        .descriptor_set = ctx.descriptor_set,
+        .viewport_size = .{
+            @floatFromInt(ctx.swapchain.extent.width),
+            @floatFromInt(ctx.swapchain.extent.height),
+        },
+        .cell_size = .{ @floatFromInt(cell_w), @floatFromInt(cell_h) },
+        .extent = ctx.swapchain.extent,
+        .instance_buffer = ctx.instance_buffer,
+        .quad_vertex_buffer = ctx.quad_vertex_buffer,
+        .instance_count = instance_count,
+    });
+    const wait_stage = @import("vulkan").PipelineStageFlags{ .color_attachment_output_bit = true };
+    const submit = @import("vulkan").SubmitInfo{
+        .wait_semaphore_count = 1,
+        .p_wait_semaphores = @ptrCast(&ctx.image_available),
+        .p_wait_dst_stage_mask = @ptrCast(&wait_stage),
+        .command_buffer_count = 1,
+        .p_command_buffers = @ptrCast(&ctx.command_buffer),
+        .signal_semaphore_count = 1,
+        .p_signal_semaphores = @ptrCast(&ctx.render_finished),
+    };
+    _ = try ctx.device.vkd.queueSubmit(ctx.device.graphics_queue, 1, @ptrCast(&submit), ctx.in_flight_fence);
+    const present = @import("vulkan").PresentInfoKHR{
+        .wait_semaphore_count = 1,
+        .p_wait_semaphores = @ptrCast(&ctx.render_finished),
+        .swapchain_count = 1,
+        .p_swapchains = @ptrCast(&ctx.swapchain.handle),
+        .p_image_indices = @ptrCast(&image_index),
+    };
+    _ = try ctx.device.vkd.queuePresentKHR(ctx.device.present_queue, &present);
+}
+// vulkan-zig needs a loader. On Linux we use dlsym on libvulkan.so.1
+fn vkGetInstanceProcAddrStub(instance: anytype, name: [*:0]const u8) ?*const fn () callconv(.C) void {
+    // Use dlopen + dlsym to get vkGetInstanceProcAddr from libvulkan.so.1
+    const dl = @cImport({
+        @cInclude("dlfcn.h");
+    });
+    const handle = dl.dlopen("libvulkan.so.1", dl.RTLD_NOW) orelse return null;
+    const get_proc: *const fn (instance: anytype, name: [*:0]const u8) ?*const fn () callconv(.C) void =
+        @ptrCast(@alignCast(dl.dlsym(handle, "vkGetInstanceProcAddr") orelse return null));
+    return get_proc(instance, name);
+}
+```
+**Note:** The `vkGetInstanceProcAddrStub` is approximate — the exact signature expected by vulkan-zig's `BaseDispatch.load()` varies. Consult vulkan-zig examples for the correct loader. On Linux, dlopen libvulkan.so.1 and dlsym `vkGetInstanceProcAddr` is the standard approach.
+- [ ] **Step 2: Link libdl (for dlopen)**
+Add to exe in build.zig:
+```zig
+exe.linkSystemLibrary("dl");
+exe.linkSystemLibrary("wayland-client");
+```
+- [ ] **Step 3: Build and run**
+```bash
+zig build run
+```
+Expected: opens a window showing a shell prompt. Typing and seeing text appear proves the full loop works.
+- [ ] **Step 4: Commit**
+```bash
+git add src/main.zig build.zig
+git commit -m "feat(main): full event loop integration"
+```
+---
+### Task 7.4: Resize handling
+**Files:**
+- Modify: `src/main.zig`
+- Modify: `src/renderer.zig` (add `recreateSwapchain`)
+- [ ] **Step 1: Add recreateSwapchain to Context**
+In `src/renderer.zig`:
+```zig
+pub fn recreateSwapchain(self: *Context, width: u32, height: u32) !void {
+    _ = try self.device.vkd.deviceWaitIdle(self.device.handle);
+    // Destroy old
+    for (self.framebuffers) |fb| self.device.vkd.destroyFramebuffer(self.device.handle, fb, null);
+    self.alloc.free(self.framebuffers);
+    for (self.swapchain.image_views) |iv| self.device.vkd.destroyImageView(self.device.handle, iv, null);
+    self.alloc.free(self.swapchain.image_views);
+    self.alloc.free(self.swapchain.images);
+    self.device.vkd.destroySwapchainKHR(self.device.handle, self.swapchain.handle, null);
+    // Recreate
+    self.swapchain = try self.renderer.createSwapchain(&self.device, self.device_info, self.surface, width, height);
+    self.framebuffers = try createFramebuffers(self.alloc, &self.device, self.render_pass, &self.swapchain);
+}
+```
+- [ ] **Step 2: Handle configure events in main loop**
+In the main loop (before render), check if window dimensions changed:
+```zig
+var last_w: u32 = win_w;
+var last_h: u32 = win_h;
+// ... inside loop, after dispatch:
+if (window.width != last_w or window.height != last_h) {
+    try ctx.recreateSwapchain(window.width, window.height);
+    const new_cols: u16 = @intCast(window.width / cell_w);
+    const new_rows: u16 = @intCast(window.height / cell_h);
+    try term.resize(new_cols, new_rows);
+    try p.resize(new_cols, new_rows);
+    last_w = window.width;
+    last_h = window.height;
+}
+```
+- [ ] **Step 3: Build and test resize**
+```bash
+zig build run
+```
+Expected: resize the window; it should not crash and the grid should adjust.
+- [ ] **Step 4: Commit**
+```bash
+git add src/main.zig src/renderer.zig
+git commit -m "feat: handle window resize"
+```
+---
+### Task 7.5: Frame timing instrumentation
+**Files:**
+- Modify: `src/main.zig`
+- [ ] **Step 1: Add frame timer with debug warning**
+In the main loop, wrap the render portion:
+```zig
+var frame_timer = try std.time.Timer.start();
+// ... render ...
+const frame_ns = frame_timer.read();
+if (std.debug.runtime_safety and frame_ns > 16 * std.time.ns_per_ms) {
+    std.debug.print("slow frame: {d}ms\n", .{@divTrunc(frame_ns, std.time.ns_per_ms)});
+}
+```
+- [ ] **Step 2: Build**
+```bash
+zig build
+```
+Expected: builds. In debug mode, slow frames print a warning.
+- [ ] **Step 3: Commit**
+```bash
+git add src/main.zig
+git commit -m "feat: frame timing warning in debug builds"
+```
+---
+## Self-Review Checklist
+After completing the plan above, the reviewer should verify:
+- [ ] `zig build` succeeds
+- [ ] `zig build test` passes (pty, vt, font tests)
+- [ ] `zig build run -- --headless` dumps a grid including "hello"
+- [ ] `zig build run` opens a window with a working shell
+- [ ] Typing in the window produces expected characters
+- [ ] Resizing the window doesn't crash and adjusts the grid
+- [ ] Running `vim` inside waystty works (tests key encoding, cursor movement, redraws)
+- [ ] Running `htop` inside waystty works (tests refresh rate, color, block characters)
+- [ ] Exit via `exit` command closes the window cleanly
+## Spec Coverage Map
+| Spec Section | Implementing Tasks |
+|--------------|-------------------|
+| Architecture: 6 modules | 0.3, 1.x, 2.x, 4.x, 5.x, 6.x, 7.x |
+| wayland.zig protocols | 5.1, 5.2, 5.3 |
+| Key repeat | 5.5 |
+| Focus events | 5.4 (enter/leave) |
+| Cursor shape | *Deferred — add as follow-up task* |
+| DPI scaling | *Deferred — add as follow-up task* |
+| Clipboard | *Phase 2 per spec* |
+| pty.zig | 1.x |
+| vt.zig all handles | 2.1–2.7 |
+| Effect callbacks | *Implementer must wire these in 2.2+ per observed upstream API* |
+| font.zig (fontconfig, freetype) | 4.1, 4.2 |
+| Glyph atlas R8 | 4.3 |
+| Harfbuzz | *Phase 2 per spec* |
+| Cell metrics | 4.2 (cellWidth/cellHeight) |
+| renderer.zig Vulkan | 6.1–6.9, 7.2 |
+| Shaders glslc | 6.2 |
+| Instanced draw | 6.9, 7.3 |
+| Swapchain recreation | 7.4 |
+| Event loop with poll | 7.3 |
+| Resize handling | 7.4 |
+| Hardcoded defaults | 7.3 (constants at top of main.zig) |
+| Build system (build.zig only) | 0.2, 0.3, 0.4, 1.1, 2.2, 4.1, 5.1, 6.1, 6.2 |
+| Testing (zig test) | throughout via `zig build test` |
+| Frame timing | 7.5 |
+### Known Gaps (acknowledge before starting)
+. **Cursor shape + DPI scaling** — spec mentions these but no tasks. Add as follow-up tasks after the terminal is functional.
+. **Focus encoding via ghostty_focus_encode** — spec mentions this; implementer must add to the keyboard enter/leave handler in Task 5.4 or as a follow-up.
+. **`GHOSTTY_TERMINAL_OPT_*` effect callbacks** — the exact registration happens via the upstream Zig API, which we don't fully know until Task 2.1. The implementer must set WRITE_PTY at minimum, along with DA, SIZE, XTVERSION, TITLE_CHANGED, COLOR_SCHEME per spec.
+. **vulkan-zig loader** — the `vkGetInstanceProcAddrStub` in Task 7.3 is approximate. Must be adjusted to match vulkan-zig's expected signature.
+. **zig-wayland scanner API** — has churned across Zig versions. The build.zig snippets in Task 5.1 are approximate and must be adapted to the pinned dependency version.
+These gaps are called out because this plan covers a very large surface (Wayland + Vulkan + libghostty-vt + freetype + xkb), and small API drift in any of the five dependencies will need small adjustments during implementation.