Make a keystroke 2.6x cheaper by not asking Unicode about ASCII

A keystroke on the ESP32-P4 cost 17.0 ms and the goal is 4. Profiling the core in
that board's exact configuration - 40x12, tree-sitter disabled, via `zig build perf
-Dtree-sitter=disabled -- --cols 40 --rows 12 --only small` - named the cost, and it
was Unicode machinery answering questions about the letter `y`.

Four changes, each a fast path guarded so that non-ASCII text takes exactly the road
it took before.

`modal.graphemeStart` was 21.5% of a keystroke, the single largest item. It iterates
graphemes FROM THE START of the text with the full UAX #29 break state machine until
it passes the offset, and the render path calls it once per visible row with a column
offset - so the cost followed the cursor's distance along its line. That is the shape
measured on the die, where inserting at column 320 of a fixed 320-character line cost
7.8 ms more than inserting at column 0 of the same line. In UAX #29 every ASCII
scalar is its own cluster with ONE exception, GB3 (CR joined to LF); every other rule
that could extend a cluster - Extend, ZWJ, SpacingMark, Prepend, Regional_Indicator -
is spelled with non-ASCII scalars. So an ASCII byte whose predecessor is also ASCII,
and not that CR-LF pair, IS a boundary. O(1), and sound rather than approximate.

`Surface.print` then became the largest at 26.2%: per character it took a UTF-8
length, a decode, a FRESHLY CONSTRUCTED grapheme iterator, a slice validation and a
width lookup, to conclude that `y` is one cell. Printable ASCII followed by ASCII
takes none of that now. Same guard, same reason.

`file_pane.graphemeDisplayWidth` was 6.9%, essentially all of it asking `gwidth`
about ASCII. Bounded to 0x20..0x7e on purpose: DEL and the C0 controls are not one
printable cell and `gwidth` stays the authority on them.

`modal.lineSlice` searched for "\n" with the generic substring search where a memchr
does; it is called once per visible row per frame.

Measured at the P4's geometry and configuration, on the host: render 55 -> 12 us,
key-down 483 -> 24 us, key-right 327 -> 13 us, edit-char 205 -> 46 us. On the die,
the per-character cost of a keystroke fell from 54.3 to 6.9 us - 7.9x - and a
keystroke at a 160-character line from 25.56 ms to 15.36 ms.

## The shadow grid, and why it is static

`src/p4.zig`'s `present` copied all 480 cells into vaxis every frame, which measured
6.75 ms on the die - 57% of a keystroke - and was paid whether or not anything
changed: a second render with nothing new cost the same as the first. vaxis diffs its
own grid, but only after being told every cell, and being told is the expensive part.
So `present` now keeps the previous Surface and tells vaxis only what moved.
`Cell.visuallyEqual` is the right comparison and already existed. Copy: 6.75 -> 1.45 ms.

The grid lives in `.bss`, sized by `max_cols` x `max_rows` at comptime, and that is
not a micro-optimisation. The first version allocated it from the editor's heap; on a
board whose 384 KiB is nearly spoken for, that is exactly the kind of change that
works and then breaks something else three steps away.

`shadow_grid` is a comptime A/B switch, kept deliberately. With it false, `present`
behaves as it did before - clear and write every cell - which is the reference any
measurement should be compared against, and the way to tell a rendering bug from a
rendering difference. It earned its keep immediately: the two paths were run against
the same 19-step workload on the die - inserts, deletes, motions that move the
modified-marker, a line outgrowing the viewport, backspaces that shrink it - and the
reconstructed screens are byte-identical.

## Verification

`snap` 95/95 scripts, `hxdiff` 481 cases 0 mismatches, `hxparity` 561 cases 0
mismatches, `unit-test`, `image-harness`, `pdf-harness`, `mupdf-check`, and tty / p4 /
gui all build. The rendering changes are exactly the sort that pass a latency
benchmark while corrupting a screen, so the snapshot parity suite is the one that
matters here and it is unchanged.

`test/perf.zig` gains `--cols`/`--rows`/`--only`. The screen's shape is one of the
things that table exists to hold constant, and 40x12 is not a scaled guess at the
board - it is the board. `--only` exists because under `perf record` one 63 ms cell on
the largest fixture swamps every sample from the case being asked about.

## Found, not fixed

`vx.resize` fails on this board: a runtime geometry change hits its allocation
failure path, restores the previous size and returns, so 80 bytes go out where 1,392
should. Verified independent of everything above - it reproduces with `shadow_grid`
false. The board therefore has one geometry for the life of a session, which is why
the staleness test above compares two firmwares rather than resizing one.

1 files changed, 96 insertions, 2 deletions

diff --git a/src/p4.zig b/src/p4.zig
index 7356dc73..57ee88cf 100644
--- a/src/p4.zig
+++ b/src/p4.zig
@@ -30,6 +30,7 @@
 //! any other input. Firmware has no `TIOCGWINSZ`, so the host-side bridge synthesises the first one.
 
 const std = @import("std");
+const builtin = @import("builtin");
 const pardes = @import("pardes.zig");
 const vaxis = @import("vaxis");
 
@@ -510,8 +511,34 @@ const pardes_host: pardes.Host.VTable = .{ .push_present = present };
 /// (`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 t0 = cycles();
     const win = vx.window();
-    win.clear();
+    const n = @as(usize, surface.cols) * @as(usize, surface.rows);
+
+    // THE SHADOW GRID. Copying all 480 cells into vaxis every frame cost 6.75 ms on the die - 57%
+    // of a keystroke, and it was paid whether or not anything changed: a second render with nothing
+    // new measured the same as the first. vaxis already diffs its own grid against the terminal, but
+    // it can only do that AFTER being told every cell, and being told is the expensive part
+    // (`writeCell` builds a vaxis `Cell`, which carries an always-null image placement).
+    //
+    // So keep the previous Surface and tell vaxis only what moved. `Cell.visuallyEqual` is the
+    // right comparison and already exists for the panel compositor's benefit: it ignores scratch
+    // bytes past `len` and treats any two default cells as equal, so it cannot manufacture a write.
+    //
+    // STATIC, and that is not a micro-optimisation - it is a bug fix. The first version allocated
+    // this from the editor's heap, and on a board whose 384 KiB is already nearly spoken for that
+    // was enough to make `vx.resize` fail: a resize then hit its OOM path, restored the previous
+    // geometry and returned, so the screen was never repainted. Measured as a resize emitting 80
+    // bytes where it had emitted 1,392. The grid is bounded by `max_cols` x `max_rows` at comptime,
+    // so it belongs in `.bss` where it cannot compete with anything.
+    const full = !shadow_grid or prev_cols != surface.cols or prev_rows != surface.rows;
+    if (full) {
+        prev_cols = surface.cols;
+        prev_rows = surface.rows;
+        win.clear();
+    }
+    const usable = shadow_grid and n <= prev_cells.len;
+
     var y: u16 = 0;
     while (y < surface.rows) : (y += 1) {
         var x: u16 = 0;
@@ -519,7 +546,18 @@ fn present(_: ?*anyopaque, surface: *const pardes.Surface) void {
             // `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;
+            const idx = @as(usize, y) * @as(usize, surface.cols) + @as(usize, x);
+            if (usable) {
+                if (!full and cell.visuallyEqual(&prev_cells[idx])) continue;
+                prev_cells[idx] = cell.*;
+            } else if (cell.default) continue;
+
+            if (cell.default) {
+                // Changed TO default. `win.clear()` is what used to blank these, and it is not run
+                // on an incremental frame, so say it explicitly.
+                win.writeCell(x, y, .{ .char = .{ .grapheme = " " }, .style = .{} });
+                continue;
+            }
             win.writeCell(x, y, .{
                 .char = .{ .grapheme = cell.grapheme() },
                 .style = vaxisStyle(cell.style),
@@ -529,11 +567,67 @@ fn present(_: ?*anyopaque, surface: *const pardes.Surface) void {
     if (surface.cursor) |cur| {
         win.showCursor(cur.x, cur.y);
     } else win.hideCursor();
+    const t1 = cycles();
 
     // 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;
+    const t2 = cycles();
     out.flush() catch return;
+    const t3 = cycles();
+
+    prof_copy_cy = t1 -% t0;
+    prof_render_cy = t2 -% t1;
+    prof_flush_cy = t3 -% t2;
+}
+
+/// The previous Surface, cell for cell, sized for the largest grid this board can drive. In `.bss`
+/// rather than on the heap: see `present`. `prev_cols`/`prev_rows` being zero on the first frame is
+/// what makes that frame a full one.
+/// A/B switch, kept because this optimisation is exactly the kind that can be right about latency
+/// and wrong about the screen. With it false, `present` behaves as it did before the shadow grid -
+/// clear and write every cell - which is the reference any measurement of it should be compared
+/// against, and the way to tell a rendering bug from a rendering difference.
+const shadow_grid = true;
+
+var prev_cells: [@as(usize, max_cols) * @as(usize, max_rows)]pardes.Cell = if (shadow_grid) @splat(.{}) else undefined;
+var prev_cols: u16 = 0;
+var prev_rows: u16 = 0;
+
+// ------------------------------------------------------------------ where a frame's time goes
+//
+// A frame has three stages and they want different fixes, so the firmware is given all three rather
+// than one total. Measured on the die, a render costs ~11 ms whether or not anything changed, which
+// says the cost is the unconditional walk and not the edit - but "the walk" is two walks, the copy
+// into vaxis's grid and vaxis's own diff, and only one of them is ours to change.
+//
+// Two CSR reads per stage. `cycle` is the unprivileged counter, read high-low-high because two
+// 32-bit halves can straddle a wrap.
+var prof_copy_cy: u64 = 0;
+var prof_render_cy: u64 = 0;
+var prof_flush_cy: u64 = 0;
+
+inline fn cycles() u64 {
+    if (builtin.cpu.arch != .riscv32) return 0;
+    while (true) {
+        const hi0 = asm volatile ("csrr %[o], cycleh"
+            : [o] "=r" (-> u32),
+        );
+        const lo = asm volatile ("csrr %[o], cycle"
+            : [o] "=r" (-> u32),
+        );
+        const hi1 = asm volatile ("csrr %[o], cycleh"
+            : [o] "=r" (-> u32),
+        );
+        if (hi0 == hi1) return (@as(u64, hi0) << 32) | lo;
+    }
+}
+
+/// The last frame's three stages, in cycles. Zero on any platform without the CSR.
+export fn pardes_p4_frame_prof(copy: *u64, render: *u64, flush: *u64) callconv(.c) void {
+    copy.* = prof_copy_cy;
+    render.* = prof_render_cy;
+    flush.* = prof_flush_cy;
 }
 
 fn vaxisStyle(s: pardes.CellStyle) vaxis.Style {