A fourth platform: pardes as ESP32-P4 firmware, bytes in and bytes out

`-Dplatform=p4 -Dtarget=riscv32-freestanding` emits a single freestanding OBJECT
exporting a seven-function C ABI, not an executable. The board's toolchain
(../05-zig-p4) owns `_start`, the linker script and the UART driver and links this
in. The seam is bytes rather than types, so neither side can accidentally depend
on the other's internals, and a signature that drifts fails at link time.

The serial line is the whole of the I/O. `src/p4.zig` drives vaxis unchanged over
it: the renderer is a byte writer and `queryTerminalSend` is a byte writer, so the
terminal emulator on the host answers the capability handshake and the firmware
sees a real terminal. Measured going out over the wire on attach: alt screen,
in-band resize, cursor report, kitty keyboard, kitty graphics, DA1.

THREE WORDS EXIST ONLY HERE. `src/board_memory.zig` implements `Peek`, `Poke` and
`Hexdump`, gated on `builtin.os.tag == .freestanding and !isWasm()` - derived from
the TARGET, because they are a property of running with no OS under you rather
than a product option, and because wasm is freestanding too and is exactly what
must be excluded: in a browser an address is an offset into the linear memory this
editor's own heap lives in. Every access goes through `*allowzero volatile`: a
peripheral register is not memory, and address 0 is an ordinary unmapped address
on this bus. One 4 KiB cap per command, set by the console rather than the memory -
an unbounded dump would wedge the only console the board has for eleven hours.

Measured on ESP32-P4 rev v1.3 silicon, driven from a host terminal:

  Peek 0x501101a4              0x0e63ce71, then 0xaeaa6919 on a second read - the
                               RNG register, so the volatile loads are not folded
  Poke 0x5011002c 0xdeadbeef   LP_STORE0; a later Peek returned 0xdeadbeef
  Hexdump 0x5011002c 32        16 bytes a row, hex columns and an ASCII gutter
  Peek 0x50110001              `peek: MisalignedAddress` on the message row

That last line is the one that matters. A misaligned 32-bit access traps, and a
trap in firmware is a watchdog reset that takes the session with it, so the check
that turns it into a message is the reason the file is hand-written rather than a
generic reader.

BARE METAL BOOTS AN EMPTY OUTPUT BUFFER. Every other boot layout in `init` makes a
shell, and on this platform that is not a preference but an impossibility: nothing
to fork, no pty to give a terminal pane. Booting one anyway produced precisely what
that describes - a pane whose tag ends in `Filter`, no gutter, no buffer, and every
keystroke vanishing into the Fallback's silent pty. An output buffer is also what
the platform's own words want, since Peek, Poke and Hexdump each fill one.

Sized for the board rather than for a desktop:

* `allocators.zig` gains a p4 tier that is ALL fallback - every capacity is zero,
  so each arena spills immediately to the 384 KiB heap the firmware hands over,
  and no megabyte-shaped static reservation lands in `.bss`.
* `source_manifest.zig`'s allowlist is EMPTY on p4. The table is ~0.95 MiB of
  rodata against a 1.5 MiB flash partition; the firmware's filesystem is the
  serial host's, through the Host vtable.
* The grid is clamped and the clamp is measured, not guessed: every cell is paid
  for four times (vaxis Screen + InternalScreen, pardes Surface + previous_cells),
  so 40x12 fits and 80x24 exhausts the heap during `Pardes.init`.
* `Vaxis.resize` deinits both screens before allocating replacements, so a failed
  resize leaves vaxis rendering nothing. The p4 shell keeps the previous geometry
  on failure instead of leaving a half-applied one.

Also here: `output_pane_integration_test.zig` had an exhaustive switch over
`Platform` that adding `.p4` left unhandled, which broke `zig build unit-test`
outright - the native test binary is the one consumer no platform build compiles.
346 tests pass again.

1 files changed, 578 insertions, 0 deletions

diff --git a/src/p4.zig b/src/p4.zig
new file mode 100644
index 00000000..7356dc73
--- /dev/null
+++ b/src/p4.zig
@@ -0,0 +1,578 @@
+//! The ESP32-P4 firmware shell: pardes as one freestanding object, bytes in and bytes out.
+//!
+//! This is the fourth platform, and the only one that is not an executable. `zig build
+//! -Dplatform=p4 -Dtarget=riscv32-freestanding` emits this file as a single object exporting the C
+//! ABI below; the `zig-p4` package links it beside its own `_start`, its generated linker script,
+//! and its UART driver. Nothing here knows what a UART is.
+//!
+//! **Why an object and not a module.** The obvious arrangement was for zig-p4 to declare this
+//! package in its `build.zig.zon` and import `pardes_p4`. That was built, and it broke every build
+//! in that repo: nesting this package's ~30-package graph under one whose own claim is "host
+//! dependencies: Zig, that is the whole list" made `std/Build.zig:2091` exceed its 1000-branch
+//! comptime quota (through ghostty's `SharedDeps.zig:874` `lazyImport`), dragged in seven cached
+//! tree-sitter versions whose `build.zig` uses APIs removed in 0.16, and materialised 2.6 GB across
+//! 42,736 files into that repo's working copy. A linked object has none of those properties and one
+//! extra virtue: the seam is bytes, so neither side can accidentally depend on the other's types.
+//!
+//! **Where the terminal is.** On the host. The board writes ANSI and reads ANSI; the terminal
+//! emulator at the far end of the serial line does the font rendering, and answers this program's
+//! own capability queries. That is why `vaxis` works here unmodified: `Vaxis.render`,
+//! `queryTerminalSend` and `enableDetectedFeatures` all take a bare `*std.Io.Writer`
+//! (`Vaxis.zig:375,278,329`), so the transport is a parameter. `vaxis.Tty` and `vaxis.Loop` are
+//! termios/ioctl/SIGWINCH bound and are not used.
+//!
+//! **Where the memory is.** Not here either. The firmware measured its own RAM (240 KiB low,
+//! 384 KiB high, and a 128 KiB region that turned out to be L2 cache) and owns the allocator; this
+//! file receives four function pointers and rebuilds a `std.mem.Allocator` from them. Everything
+//! the editor allocates comes from there.
+//!
+//! **Window size** arrives as DEC mode 2048 in-band resize reports, parsed by `vaxis.Parser` like
+//! any other input. Firmware has no `TIOCGWINSZ`, so the host-side bridge synthesises the first one.
+
+const std = @import("std");
+const pardes = @import("pardes.zig");
+const vaxis = @import("vaxis");
+
+// ------------------------------------------------------------------ what a freestanding root owes
+//
+// These are ROOT-module declarations: std reads them off whichever file is the compilation root, and
+// as of the build change that emits this file as the object, that is this file. They are not
+// ceremony - each one was discovered by the build failing without it.
+
+/// The board has no MMU and no pages, but std derives allocator alignment from these two. 4 KiB is
+/// the ESP32-P4's cache and DMA granularity. Without them: "riscv32-freestanding has unknown
+/// page_size_min" from std/heap.zig:48.
+///
+/// `logFn` is the load-bearing one. std's DEFAULT log implementation reaches `std.debug_io`, which
+/// instantiates `std.Io.Threaded` - a thread pool, `getrandom`, `IOV_MAX`, `mremap` - none of which
+/// exist on this target, and ONE `log.warn` anywhere in the core or in vaxis is enough to drag the
+/// whole thing in and fail the build with "no member named 'getrandom'".
+pub const std_options: std.Options = .{
+    .page_size_min = 4096,
+    .page_size_max = 4096,
+    .logFn = logFn,
+};
+
+/// Logs go out the same byte sink as the frames, which is the only sink there is. Truncated rather
+/// than allocated: a log line is never worth an allocation on a 384 KiB heap, and a logger that can
+/// fail on OOM is a logger that disappears exactly when it is needed.
+fn logFn(
+    comptime level: std.log.Level,
+    comptime scope: @EnumLiteral(),
+    comptime fmt: []const u8,
+    args: anytype,
+) void {
+    if (out_ctx == null and @intFromPtr(out_write) == 0) return;
+    var buf: [256]u8 = undefined;
+    const line = std.fmt.bufPrint(
+        &buf,
+        "\r\n[" ++ level.asText() ++ "/" ++ @tagName(scope) ++ "] " ++ fmt ++ "\r\n",
+        args,
+    ) catch "\r\n[log truncated]\r\n";
+    out_write(out_ctx, line.ptr, line.len);
+}
+
+pub const panic = std.debug.FullPanic(panicImpl);
+
+/// A panic here cannot unwind and has nowhere to go, so it reports through the write callback and
+/// stops. `@trap` and not a spin: the firmware's own panic handler prints through the mask ROM,
+/// which shares nothing with this path but the FIFO, so a trap leaves that diagnostic route intact.
+fn panicImpl(msg: []const u8, _: ?usize) noreturn {
+    const prefix = "\r\nMARK PARDES_CORE_PANIC ";
+    out_write(out_ctx, prefix.ptr, prefix.len);
+    out_write(out_ctx, msg.ptr, msg.len);
+    out_write(out_ctx, "\r\n", 2);
+    @trap();
+}
+
+// ---------------------------------------------------------------------------------- the C ABI
+//
+// Deliberately tiny, and versioned. Linkers do not type-check C symbols, so a signature that drifts
+// on one side of this seam links cleanly and then corrupts the stack. `pardes_p4_abi_version` is the
+// cheapest possible defence: the firmware calls it first and refuses to continue on a mismatch.
+
+/// Bumped whenever any signature below changes, including a type.
+const abi_version: u32 = 1;
+
+export fn pardes_p4_abi_version() callconv(.c) u32 {
+    return abi_version;
+}
+
+/// The firmware's allocator, as C function pointers. `alignment` is a log2 value, matching
+/// `std.mem.Alignment`'s own representation, so no translation table is needed.
+///
+/// `remap` is absent on purpose: this allocator cannot move a block without copying it, so
+/// `std.mem.Allocator`'s remap is implemented locally as "resize in place, or fail" and the caller's
+/// own alloc/copy/free path handles the rest.
+pub const Allocator = extern struct {
+    ctx: ?*anyopaque,
+    alloc: *const fn (ctx: ?*anyopaque, len: usize, log2_align: u8) callconv(.c) ?[*]u8,
+    resize: *const fn (ctx: ?*anyopaque, ptr: [*]u8, len: usize, log2_align: u8, new_len: usize) callconv(.c) bool,
+    free: *const fn (ctx: ?*anyopaque, ptr: [*]u8, len: usize, log2_align: u8) callconv(.c) void,
+};
+
+/// How finished runs of ANSI leave this object.
+pub const WriteFn = *const fn (ctx: ?*anyopaque, ptr: [*]const u8, len: usize) callconv(.c) void;
+
+// ------------------------------------------------------------------- the allocator, rebuilt
+// One `std.mem.Allocator` whose vtable forwards to the four pointers above. The indirection is the
+// price of the seam and it is paid once per allocation, which on a first-fit heap is already the
+// cheap part (measured on the die: 8,229 cycles for one allocation across 257 free blocks).
+
+var host_alloc: Allocator = undefined;
+
+fn hostAlloc(_: *anyopaque, len: usize, alignment: std.mem.Alignment, _: usize) ?[*]u8 {
+    return host_alloc.alloc(host_alloc.ctx, len, @intFromEnum(alignment));
+}
+
+fn hostResize(_: *anyopaque, mem: []u8, alignment: std.mem.Alignment, new_len: usize, _: usize) bool {
+    return host_alloc.resize(host_alloc.ctx, mem.ptr, mem.len, @intFromEnum(alignment), new_len);
+}
+
+fn hostRemap(_: *anyopaque, mem: []u8, alignment: std.mem.Alignment, new_len: usize, _: usize) ?[*]u8 {
+    return if (host_alloc.resize(host_alloc.ctx, mem.ptr, mem.len, @intFromEnum(alignment), new_len)) mem.ptr else null;
+}
+
+fn hostFree(_: *anyopaque, mem: []u8, alignment: std.mem.Alignment, _: usize) void {
+    host_alloc.free(host_alloc.ctx, mem.ptr, mem.len, @intFromEnum(alignment));
+}
+
+const host_vtable: std.mem.Allocator.VTable = .{
+    .alloc = hostAlloc,
+    .resize = hostResize,
+    .remap = hostRemap,
+    .free = hostFree,
+};
+
+/// `ptr` is never dereferenced - the four forwarders read the file-scope `host_alloc` - but
+/// `std.mem.Allocator` requires a non-null context, so it points at the record itself.
+fn gpa() std.mem.Allocator {
+    return .{ .ptr = @ptrCast(&host_alloc), .vtable = &host_vtable };
+}
+
+// ------------------------------------------------------------------------------- the ANSI sink
+// A `std.Io.Writer` over the firmware's write callback. Buffered, because vaxis emits a frame as a
+// long run of small writes - cursor move, SGR run, grapheme, repeat - and an unbuffered writer would
+// make a C call per fragment.
+
+var out_write: WriteFn = undefined;
+var out_ctx: ?*anyopaque = null;
+var out_buf: [8192]u8 = undefined;
+var out: std.Io.Writer = undefined;
+
+fn drain(w: *std.Io.Writer, data: []const []const u8, splat: usize) std.Io.Writer.Error!usize {
+    // The shape std documents at Io/Writer.zig:46-63: buffer first, then every slice of `data`, with
+    // the LAST slice repeated `splat` times, and the count returned excluding the buffered bytes.
+    if (w.end > 0) {
+        out_write(out_ctx, w.buffer.ptr, w.end);
+        w.end = 0;
+    }
+    const head = data[0 .. data.len - 1];
+    const pattern = data[head.len];
+    var written: usize = 0;
+    for (head) |bytes| {
+        if (bytes.len > 0) out_write(out_ctx, bytes.ptr, bytes.len);
+        written += bytes.len;
+    }
+    var i: usize = 0;
+    while (i < splat) : (i += 1) {
+        if (pattern.len > 0) out_write(out_ctx, pattern.ptr, pattern.len);
+    }
+    return written + pattern.len * splat;
+}
+
+// ------------------------------------------------------------------------------------ the state
+
+var core: ?*pardes.Pardes = null;
+var vx: vaxis.Vaxis = undefined;
+var parser: vaxis.Parser = .{};
+
+/// vaxis wants an environment map. There is no environment; an empty one is the honest answer and
+/// the only thing vaxis reads it for is TERM-derived heuristics, which the capability queries
+/// supersede.
+var env_map: std.process.Environ.Map = undefined;
+
+/// Input that arrived mid-sequence. An escape sequence can be split across UART reads, and the
+/// parser reports "incomplete" by consuming nothing, so the tail has to survive until more arrives.
+var in_buf: [1024]u8 = undefined;
+var in_len: usize = 0;
+
+/// Bracketed paste: between the markers, keys are DATA and never commands.
+var paste_buf: std.ArrayListUnmanaged(u8) = .empty;
+var in_paste: bool = false;
+
+/// Set by anything that could change the screen; cleared by a render. The firmware asks before
+/// rendering, because on a 115200-baud link an unconditional repaint per loop saturates the wire and
+/// starves input.
+var dirty: bool = true;
+
+/// The largest grid this board can render, and the reason it is not the host's terminal size.
+///
+/// Every cell is paid for four times over: vaxis keeps a `Screen` and an `InternalScreen`, pardes
+/// keeps its own `Surface` and `previous_cells`. Against a 384 KiB heap that puts a hard ceiling on
+/// the geometry, and it was measured rather than guessed - 40x12 initialises with room to spare,
+/// 80x24 exhausts the heap and `Pardes.init` returns OutOfMemory with 9,128 bytes left.
+///
+/// Raising these is what PSRAM would buy: this board has 32 MB fitted and untrained.
+pub const max_cols: u16 = 40;
+pub const max_rows: u16 = 12;
+
+var cur_winsize: vaxis.Winsize = .{ .rows = max_rows, .cols = max_cols, .x_pixel = 0, .y_pixel = 0 };
+
+
+// -------------------------------------------------------------------------------------- exports
+
+/// Hand over the allocator and the output sink, state the initial window size, and bring the editor
+/// up. Returns 0, or a small non-zero code the firmware can only report.
+export fn pardes_p4_init(
+    alloc: *const Allocator,
+    write: WriteFn,
+    ctx: ?*anyopaque,
+    cols: u16,
+    rows: u16,
+) callconv(.c) u32 {
+    host_alloc = alloc.*;
+    out_write = write;
+    out_ctx = ctx;
+    out = .{ .vtable = &.{ .drain = drain }, .buffer = &out_buf };
+
+    const a = gpa();
+    env_map = .{ .array_hash_map = .empty, .allocator = a };
+    // Clamped, so a firmware asking for more than the heap affords still starts. See `max_cols`.
+    cur_winsize = .{
+        .rows = @min(rows, max_rows),
+        .cols = @min(cols, max_cols),
+        .x_pixel = 0,
+        .y_pixel = 0,
+    };
+
+    const allocs = pardes.allocators.init(a);
+    // `std.Io.failing` and not a real Io: every path in the core that would perform I/O is behind
+    // the Host vtable, and the ones that are not are the ones this platform does not have.
+    pardes.image.start(std.Io.failing, allocs.image);
+    pardes.syntax.start(allocs.tree_sitter);
+
+    vx = vaxis.init(std.Io.failing, a, &env_map, .{}) catch |err| return errCode(err);
+    vx.resize(a, &out, cur_winsize) catch |err| return errCode(err);
+
+    // Ask the terminal what it is. Both halves are pure byte writers, which is the whole reason this
+    // works over a serial line: the replies arrive as ordinary input and are parsed like any key.
+    vx.enterAltScreen(&out) catch |err| return errCode(err);
+    vx.queryTerminalSend(&out) catch |err| return errCode(err);
+    out.flush() catch |err| return errCode(err);
+
+    // The CLAMPED geometry, because the core and vaxis must agree on the grid and vaxis was just
+    // sized to `cur_winsize`.
+    core = pardes.Pardes.init(allocs.pardes, .{
+        .cols = cur_winsize.cols,
+        .rows = cur_winsize.rows,
+        .frame_allocator = allocs.frame,
+        .image_allocator = allocs.image,
+        .tree_sitter_allocator = allocs.tree_sitter,
+    }) catch |err| return errCode(err);
+
+    dirty = true;
+    return 0;
+}
+
+/// Raw bytes off the wire: keystrokes, capability replies, and in-band resize reports. All three are
+/// the same kind of thing to `vaxis.Parser`, and this function does not distinguish them.
+export fn pardes_p4_input(ptr: [*]const u8, len: usize) callconv(.c) void {
+    const c = core orelse return;
+
+    // Append, dropping the oldest on overflow: a full buffer means the parser is stuck on a
+    // malformed sequence, and keeping the tail is what lets it resynchronise.
+    const room = in_buf.len - in_len;
+    const take = @min(room, len);
+    if (take < len) {
+        in_len = 0;
+        @memcpy(in_buf[0..@min(len, in_buf.len)], ptr[0..@min(len, in_buf.len)]);
+        in_len = @min(len, in_buf.len);
+    } else {
+        @memcpy(in_buf[in_len..][0..take], ptr[0..take]);
+        in_len += take;
+    }
+
+    var off: usize = 0;
+    while (off < in_len) {
+        const res = parser.parse(in_buf[off..in_len], gpa()) catch break;
+        if (res.n == 0) break; // incomplete: wait for more bytes
+        off += res.n;
+        if (res.event) |ev| apply(c, ev);
+    }
+    // Keep whatever was not consumed: the tail of a split escape sequence.
+    if (off > 0) {
+        std.mem.copyForwards(u8, in_buf[0 .. in_len - off], in_buf[off..in_len]);
+        in_len -= off;
+    }
+}
+
+/// One parsed vaxis event applied to the core. Mirrors the tty shell's `apply`
+/// (`src/tty/tty.zig:926-985`), minus everything that needs an OS.
+fn apply(c: *pardes.Pardes, ev: vaxis.Event) void {
+    switch (ev) {
+        .key_press => |key| if (in_paste) {
+            // Between the brackets a key is DATA, never a command. vaxis gives control bytes no
+            // text at all, so a line break inside a paste arrives as a bare CR (Key.enter) or, from
+            // a terminal that does not translate them, as ctrl+j.
+            const text = key.text orelse "";
+            const cp = mapKey(effCp(key));
+            const bytes: []const u8 = if (text.len > 0)
+                text
+            else if (cp == pardes.Key.tab)
+                "\t"
+            else if (cp == pardes.Key.enter or (key.mods.ctrl and cp == 'j'))
+                "\n"
+            else
+                "";
+            if (bytes.len > 0) paste_buf.appendSlice(gpa(), bytes) catch {};
+        } else {
+            c.update(.{ .key = .{
+                .cp = mapKey(effCp(key)),
+                .text = key.text orelse "",
+                .ctrl = key.mods.ctrl,
+                .alt = key.mods.alt,
+                .shift = key.mods.shift,
+            } });
+            dirty = true;
+        },
+        .paste_start => {
+            paste_buf.clearRetainingCapacity();
+            in_paste = true;
+        },
+        .paste_end => {
+            in_paste = false;
+            if (paste_buf.items.len > 0) {
+                c.update(.{ .paste = paste_buf.items });
+                dirty = true;
+            }
+            paste_buf.clearRetainingCapacity();
+        },
+        // OSC 52. The bytes are the parser's, allocated from our own allocator, so they are freed
+        // here rather than leaked - the core copies whatever it keeps.
+        .paste => |text| {
+            c.update(.{ .paste = text });
+            gpa().free(text);
+            dirty = true;
+        },
+        .mouse => |m| {
+            const button: ?pardes.Mouse.Button = switch (m.button) {
+                .left => .left,
+                .middle => .middle,
+                .right => .right,
+                .wheel_up => .wheel_up,
+                .wheel_down => .wheel_down,
+                .wheel_left => .wheel_left,
+                .wheel_right => .wheel_right,
+                .none => .none,
+                else => null,
+            };
+            if (button) |b| {
+                c.update(.{ .mouse = .{
+                    .button = b,
+                    .kind = switch (m.type) {
+                        .press => .press,
+                        .release => .release,
+                        .motion => .motion,
+                        .drag => .drag,
+                    },
+                    .col = @intCast(m.col),
+                    .row = @intCast(m.row),
+                    .ctrl = m.mods.ctrl,
+                } });
+                dirty = true;
+            }
+        },
+        // The only way this platform learns its size, and the one place a 384 KiB heap shows through
+        // to the user. Two things happen here that the tty shell does not need.
+        //
+        // CLAMPED, because the grids do not fit an arbitrary terminal: vaxis keeps a `Screen` and an
+        // `InternalScreen`, pardes keeps its own `Surface` and `previous_cells`, so every cell is
+        // paid for four times. Measured on the die - 40x12 initialises with room to spare, 80x24
+        // exhausts the heap and `Pardes.init` returns OutOfMemory with 9,128 bytes left. The host's
+        // terminal is normally larger than the board can render, so the editor takes a corner of it
+        // instead of refusing to start.
+        //
+        // ATOMIC, because `Vaxis.resize` deinits both screens BEFORE allocating the replacements
+        // (Vaxis.zig:194-206), so a failed resize leaves vaxis with freed screens and renders
+        // nothing at all. That is exactly how this was found: the host bridge injects a size report
+        // on attach, the 80x24 it reported could not be allocated, and an editor that had just drawn
+        // its interface went silent. A failure now puts the previous geometry back.
+        .winsize => |ws| {
+            const want: vaxis.Winsize = .{
+                .rows = @min(ws.rows, max_rows),
+                .cols = @min(ws.cols, max_cols),
+                .x_pixel = ws.x_pixel,
+                .y_pixel = ws.y_pixel,
+            };
+            if (want.cols == cur_winsize.cols and want.rows == cur_winsize.rows) return;
+            const previous = cur_winsize;
+            vx.resize(gpa(), &out, want) catch {
+                vx.resize(gpa(), &out, previous) catch {};
+                return;
+            };
+            cur_winsize = want;
+            c.update(.{ .resize = .{ .cols = want.cols, .rows = want.rows } });
+            dirty = true;
+        },
+        // A TTY cannot report a pointer leaving its grid, so losing focus is the only reliable
+        // pointer-leave signal there is.
+        .focus_out => {
+            c.update(.pointer_leave);
+            dirty = true;
+        },
+        .focus_in, .mouse_leave => {},
+        // Capability replies. vaxis's own Loop sets these fields directly (`Loop.zig:377-403`);
+        // with no Loop, this is where they land. DA1 is the terminator: every terminal answers it
+        // last, so it is the signal that the whole handshake is in and the detected features can be
+        // switched on.
+        .cap_kitty_keyboard => vx.caps.kitty_keyboard = true,
+        .cap_kitty_graphics => vx.caps.kitty_graphics = true,
+        .cap_rgb => vx.caps.rgb = true,
+        .cap_unicode => {
+            vx.caps.unicode = .unicode;
+            vx.screen.width_method = .unicode;
+        },
+        .cap_sgr_pixels => vx.caps.sgr_pixels = true,
+        .cap_color_scheme_updates => vx.caps.color_scheme_updates = true,
+        .cap_multi_cursor => vx.caps.multi_cursor = true,
+        .cap_da1 => {
+            vx.enableDetectedFeatures(&out) catch {};
+            out.flush() catch {};
+            dirty = true;
+        },
+        .color_report, .color_scheme => {},
+        .key_release => {},
+    }
+}
+
+/// The effective codepoint the way vaxis's own `Key.matches` sees it: a single-character `text`
+/// wins, because the terminal has already resolved shift; otherwise the shifted codepoint.
+fn effCp(key: vaxis.Key) u21 {
+    if (key.text) |t| {
+        const view = std.unicode.Utf8View.init(t) catch return key.codepoint;
+        var it = view.iterator();
+        if (it.nextCodepoint()) |cp| {
+            if (it.nextCodepoint() == null) return cp;
+        }
+    }
+    return key.shifted_codepoint orelse key.codepoint;
+}
+
+/// vaxis functional-key codepoints -> core constants. The ASCII ones already coincide, so
+/// enter/tab/escape/backspace pass straight through.
+fn mapKey(cp: u21) u21 {
+    return switch (cp) {
+        vaxis.Key.up => pardes.Key.up,
+        vaxis.Key.down => pardes.Key.down,
+        vaxis.Key.left => pardes.Key.left,
+        vaxis.Key.right => pardes.Key.right,
+        vaxis.Key.home => pardes.Key.home,
+        vaxis.Key.end => pardes.Key.end,
+        vaxis.Key.page_up => pardes.Key.page_up,
+        vaxis.Key.page_down => pardes.Key.page_down,
+        vaxis.Key.delete => pardes.Key.delete,
+        else => cp,
+    };
+}
+
+export fn pardes_p4_tick(now_ms: u64) callconv(.c) void {
+    const c = core orelse return;
+    _ = now_ms;
+    if (c.animationActive()) {
+        c.update(.tick);
+        dirty = true;
+    }
+}
+
+export fn pardes_p4_wants_frame() callconv(.c) bool {
+    const c = core orelse return false;
+    return dirty or c.animationActive();
+}
+
+export fn pardes_p4_render() callconv(.c) u32 {
+    const c = core orelse return 0;
+    c.pump(.{ .ctx = null, .vtable = &pardes_host }) catch |err| return errCode(err);
+    dirty = false;
+    return 0;
+}
+
+export fn pardes_p4_quit() callconv(.c) bool {
+    const c = core orelse return true;
+    return c.quit;
+}
+
+// ------------------------------------------------------------------------------------ the host
+
+const pardes_host: pardes.Host.VTable = .{ .push_present = present };
+
+/// The canonical surface -> vaxis, cell for cell, then one render. Same shape as the tty shell's
+/// (`src/tty/tty.zig:1096`) minus the panel compositor and the kitty image path: neither has a
+/// reason to exist on a board with no pixels.
+fn present(_: ?*anyopaque, surface: *const pardes.Surface) void {
+    const win = vx.window();
+    win.clear();
+    var y: u16 = 0;
+    while (y < surface.rows) : (y += 1) {
+        var x: u16 = 0;
+        while (x < surface.cols) : (x += 1) {
+            // `at` takes a mutable Surface but only reads; the tty shell does the same const-cast
+            // for the same reason (src/tty/tty.zig:1105).
+            const cell = @constCast(surface).at(x, y);
+            if (cell.default) continue;
+            win.writeCell(x, y, .{
+                .char = .{ .grapheme = cell.grapheme() },
+                .style = vaxisStyle(cell.style),
+            });
+        }
+    }
+    if (surface.cursor) |cur| {
+        win.showCursor(cur.x, cur.y);
+    } else win.hideCursor();
+
+    // vaxis diffs against its own shadow grid, so this writes only what changed - which is what
+    // makes an editor usable at 11.9 KB/s.
+    vx.render(&out) catch return;
+    out.flush() catch return;
+}
+
+fn vaxisStyle(s: pardes.CellStyle) vaxis.Style {
+    return .{
+        .fg = vaxisColor(s.fg),
+        .bg = vaxisColor(s.bg),
+        .bold = s.bold,
+        .dim = s.dim,
+        .italic = s.italic,
+        .blink = s.blink,
+        .reverse = s.reverse,
+        .invisible = s.invisible,
+        .strikethrough = s.strikethrough,
+        .ul_style = switch (s.ul) {
+            .off => .off,
+            .single => .single,
+            .double => .double,
+            .curly => .curly,
+            .dotted => .dotted,
+            .dashed => .dashed,
+        },
+    };
+}
+
+fn vaxisColor(c: pardes.Color) vaxis.Color {
+    return switch (c) {
+        .default => .default,
+        .index => |i| .{ .index = i },
+        .rgb => |rgb| .{ .rgb = rgb },
+    };
+}
+
+/// Errors cross the ABI as small non-zero integers. `@intFromError` is not stable across builds, so
+/// it is not used: the firmware only reports the number, and a stable-looking value that silently
+/// changed meaning would be worse than an opaque one.
+fn errCode(err: anyerror) u32 {
+    return switch (err) {
+        error.OutOfMemory => 1,
+        error.WriteFailed => 2,
+        else => 255,
+    };
+}