2e414911

feat: wasm core — replica+keymap on wasm32-freestanding, flat damage-hinted viewport ABI

a73x 2026-08-13 10:27

Commit message

feat: wasm core — replica+keymap on wasm32-freestanding, flat damage-hinted viewport ABI

The browser replica core (M-web Task 4): frame-driven (mux_apply_frame
routes through replica.zig, so the browser replays exactly what the CLI
replays), with damage tracked from delta row headers plus the cursor's
old and new rows; snapshots and grid moves dirty everything. Readout is
one flat pass — 4 u32 per cell (codepoint, fg, bg, flags|wide|spacer) —
because upstream documents the per-cell accessors as non-shipping. A
scratch terminal renders scrollback pages without touching the live
replica. Attach payloads are built core-side so JS never assembles a
u64.

The canary PASSED as wired: protocol.zig's six posix references
lazy-analyze away under wasm32 — no protocol_io split needed. One shared
-source fix: engine.zig's @fieldParentPtr needs @alignCast on wasm32
(4-byte default pointer alignment vs Engine's 8; sound, every Engine
comes from alloc.create — the spike's obstacle 3).

Build: second target instantiation of the four wasm-clean modules +
ghostty, always ReleaseSmall (345KB, 109KB gzipped), entry disabled,
rdynamic, and deliberately no use_llvm/use_lld. web/verify.js drives
the page's real call sequence under node: 62/62.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

build.zig

@@ @@ -401,6 +401,65 @@ pub fn build(b: *std.Build) void { @@
+    ptyclient_exe.use_lld = true;
+    b.installArtifact(ptyclient_exe);
+    // ---- The wasm core (M-web Task 4) ----
+    // A SECOND resolved target: modules are target-bound, so the four
+    // wasm-clean modules (engine, protocol, replica, keymap) and the
+    // ghostty dependency are instantiated again against wasm32. Always
+    // ReleaseSmall — the artifact is @embedFile'd into muxweb, and its
+    // Debug build is 3.7MB against ReleaseSmall's 345KB (spike-measured).
+    // Safety checks are the price; the native test suite runs the same
+    // code checked.
+    const wasm_target = b.resolveTargetQuery(.{
+        .cpu_arch = .wasm32,
+        .os_tag = .freestanding,
+    });
+    const ghostty_wasm_dep = b.lazyDependency("ghostty", .{
+        .target = wasm_target,
+        .optimize = .ReleaseSmall,
+    });
+    const engine_wasm_mod = b.createModule(.{
+        .root_source_file = b.path("src/engine.zig"),
+        .target = wasm_target,
+        .optimize = .ReleaseSmall,
+    });
+    if (ghostty_wasm_dep) |dep| {
+        engine_wasm_mod.addImport("ghostty-vt", dep.module("ghostty-vt"));
+    }
+    const protocol_wasm_mod = b.createModule(.{
+        .root_source_file = b.path("src/protocol.zig"),
+        .target = wasm_target,
+        .optimize = .ReleaseSmall,
+    });
+    const replica_wasm_mod = b.createModule(.{
+        .root_source_file = b.path("src/replica.zig"),
+        .target = wasm_target,
+        .optimize = .ReleaseSmall,
+    });
+    replica_wasm_mod.addImport("engine", engine_wasm_mod);
+    replica_wasm_mod.addImport("protocol", protocol_wasm_mod);
+    const keymap_wasm_mod = b.createModule(.{
+        .root_source_file = b.path("src/keymap.zig"),
+        .target = wasm_target,
+        .optimize = .ReleaseSmall,
+    });
+    const wasm_core_mod = b.createModule(.{
+        .root_source_file = b.path("src/wasm_core.zig"),
+        .target = wasm_target,
+        .optimize = .ReleaseSmall,
+    });
+    wasm_core_mod.addImport("engine", engine_wasm_mod);
+    wasm_core_mod.addImport("protocol", protocol_wasm_mod);
+    wasm_core_mod.addImport("replica", replica_wasm_mod);
+    wasm_core_mod.addImport("keymap", keymap_wasm_mod);
+    const wasm_exe = b.addExecutable(.{ .name = "mux_core", .root_module = wasm_core_mod });
+    // A wasm reactor, not a command: no _start, and the exports must
+    // survive the linker's dead-strip. Deliberately NOT use_llvm/use_lld —
+    // that pair is the native x86-64 self-hosted-linker workaround and
+    // must not be copied onto the wasm exe (spike-proven recipe).
+    wasm_exe.entry = .disabled;
+    wasm_exe.rdynamic = true;
+    b.installArtifact(wasm_exe);
+    const test_step = b.step("test", "Run unit tests");
+    // delta_mod and sockpath_mod sit BEFORE server_mod, deliberately: their
+    // tests are seconds-long and socket-free, while a regression in either

src/engine.zig

Old		New
@@ -225,7 +225,11 @@ pub const Engine = struct {
225		225
226	fn onWritePty(handler: *vt.TerminalStream.Handler, data: [:0]const u8) void {	226	fn onWritePty(handler: *vt.TerminalStream.Handler, data: [:0]const u8) void {
227	const stream_ptr: *vt.TerminalStream = @fieldParentPtr("handler", handler);	227	const stream_ptr: *vt.TerminalStream = @fieldParentPtr("handler", handler);
228	const self: *Engine = @fieldParentPtr("stream", stream_ptr);	228	// The @alignCast is for wasm32, where pointers default to 4-byte
		229	// alignment while Engine needs 8. Sound: the parent really is
		230	// 8-aligned — every Engine comes from alloc.create (init's
		231	// never-moves contract). A no-op assert on native.
		232	const self: *Engine = @alignCast(@fieldParentPtr("stream", stream_ptr));
229	self.pty_out.appendSlice(self.alloc, data) catch {};	233	self.pty_out.appendSlice(self.alloc, data) catch {};
230	}	234	}
231	};	235	};

src/wasm_core.zig

@@ @@ -0,0 +1,515 @@ @@
+//! The browser replica core: Engine + Replica + keymap compiled to
+//! wasm32-freestanding (M-web Task 4). The JS shell is glue; every
+//! decision lives on this side of the boundary.
+//!
+//! FRAME-driven, not byte-driven: the host stages one mux protocol frame
+//! payload and calls mux_apply_frame(type, len), so the core sees the same
+//! replay the CLI client does (replica.zig) and can track damage from the
+//! delta row headers itself.
+//!
+//! THE JS GOTCHA THAT WILL BITE (from the feasibility spike): the wasm
+//! allocator grows linear memory, and growth DETACHES every cached
+//! ArrayBuffer view. JS must re-read exports.memory.buffer after every
+//! call that can allocate — which is any of them — and never cache a view.
+//!
+//! Wire safety: this module trusts nothing it is fed. Payloads come from
+//! the daemon via the hub, but a bad length or type is a return code, not
+//! a trap.
+const std = @import("std");
+const builtin = @import("builtin");
+const Engine = @import("engine").Engine;
+const Replica = @import("replica").Replica;
+const keymap = @import("keymap");
+const proto = @import("protocol");
+/// std.heap.wasm_allocator grows linear memory with @wasmMemoryGrow and
+/// needs no libc, no syscalls, no host imports.
+const alloc = std.heap.wasm_allocator;
+/// Trap explicitly on panic. This is also the hook a later version uses
+/// to surface panic text to JS (a host-imported log before the trap).
+pub const panic = std.debug.FullPanic(struct {
+    fn f(_: []const u8, _: ?usize) noreturn {
+        @trap();
+    }
+}.f);
+/// Load-bearing (spike obstacle 4): ghostty-vt logs warnings on some
+/// unsupported sequences, and std's default logFn writes to stderr, which
+/// on wasm32-freestanding drags in posix.writev/lseek and std.Thread.
+/// Without this no-op the build fails inside std before any ghostty code.
+pub const std_options: std.Options = .{
+    .logFn = struct {
+        fn f(
+            comptime _: std.log.Level,
+            comptime _: @Type(.enum_literal),
+            comptime _: []const u8,
+            _: anytype,
+        ) void {}
+    }.f,
+};
+const Core = struct {
+    eng: *Engine,
+    rep: Replica,
+    /// Grid the readout buffers are sized for; follows rep.grid.
+    cols: u16,
+    rows: u16,
+    /// Per-row damage since the last mux_read_viewport. Snapshots and
+    /// grid moves mark everything; deltas mark their row headers plus
+    /// the cursor's old and new rows (the renderer draws the cursor).
+    dirty: []bool,
+    /// Scratch list the last read filled: the row indices it repainted.
+    dirty_list: []u32,
+    dirty_count: u32 = 0,
+    /// Packed cells, 4 u32 per cell (see mux_viewport_ptr).
+    viewport: []u32,
+    cursor_row: u16 = 0,
+    /// Scrollback view: a scratch terminal the host feeds fetched history
+    /// rows into. Never touches the live replica.
+    scroll_eng: ?*Engine = null,
+};
+var core: ?*Core = null;
+/// Bytes in (frame payloads, paste bytes) cross through this staging
+/// buffer: one memcpy from JS, no malloc protocol to get wrong. 256 KiB —
+/// a full snapshot payload must fit in ONE frame; verify.js asserts a
+/// real snapshot at the default scrollback does. The hub's own inbound
+/// bound is far smaller (64 KiB) because browser->hub messages are keys
+/// and pastes; daemon->browser frames ride hub->browser with no bound.
+var input_buf: [256 * 1024]u8 = undefined;
+/// Variable-length results out (encoded keys, attach payloads, dumps).
+var output_buf: [64 * 1024]u8 = undefined;
+var output_len: u32 = 0;
+// ---------------------------------------------------------------------
+// Lifecycle
+// ---------------------------------------------------------------------
+fn teardown(c: *Core) void {
+    if (c.scroll_eng) |se| se.deinit();
+    alloc.free(c.viewport);
+    alloc.free(c.dirty_list);
+    alloc.free(c.dirty);
+    c.eng.deinit();
+    alloc.destroy(c);
+}
+fn allocGridBufs(c: *Core, cols: u16, rows: u16) !void {
+    const cells = @as(usize, cols) * rows;
+    const viewport = try alloc.alloc(u32, cells * 4);
+    errdefer alloc.free(viewport);
+    const dirty = try alloc.alloc(bool, rows);
+    errdefer alloc.free(dirty);
+    const dirty_list = try alloc.alloc(u32, rows);
+    errdefer alloc.free(dirty_list);
+    c.viewport = viewport;
+    c.dirty = dirty;
+    c.dirty_list = dirty_list;
+    c.cols = cols;
+    c.rows = rows;
+    @memset(c.dirty, true);
+}
+export fn mux_init(cols: u32, rows: u32) i32 {
+    if (core) |c| {
+        teardown(c);
+        core = null;
+    }
+    if (cols < 1 or cols > 4096 or rows < 1 or rows > 4096) return -2;
+    const c = alloc.create(Core) catch return -1;
+    c.* = .{
+        .eng = undefined,
+        .rep = undefined,
+        .cols = 0,
+        .rows = 0,
+        .dirty = &.{},
+        .dirty_list = &.{},
+        .viewport = &.{},
+    };
+    c.eng = Engine.init(alloc, .{
+        .cols = @intCast(cols),
+        .rows = @intCast(rows),
+    }) catch {
+        alloc.destroy(c);
+        return -2;
+    };
+    c.rep = Replica.init(alloc, c.eng);
+    allocGridBufs(c, @intCast(cols), @intCast(rows)) catch {
+        c.eng.deinit();
+        alloc.destroy(c);
+        return -1;
+    };
+    core = c;
+    return 0;
+}
+export fn mux_deinit() void {
+    const c = core orelse return;
+    teardown(c);
+    core = null;
+}
+// ---------------------------------------------------------------------
+// Staging and replay
+// ---------------------------------------------------------------------
+export fn mux_input_ptr() [*]u8 {
+    return &input_buf;
+}
+export fn mux_input_cap() u32 {
+    return input_buf.len;
+}
+/// Apply one staged frame payload. `msg_type` is the wire byte; only
+/// snapshot (0x81) and delta (0x87) are replay frames — the host routes
+/// everything else itself.
+/// Returns 0 painted, 1 RESYNC-NEEDED (send a fresh attach quoting 0,0),
+/// -1 uninitialized, -2 length over the staging cap, -3 not a replay
+/// frame or a grid the core refuses.
+export fn mux_apply_frame(msg_type: u32, len: u32) i32 {
+    const c = core orelse return -1;
+    if (len > input_buf.len) return -2;
+    if (msg_type > 0xff) return -3;
+    const t = std.meta.intToEnum(proto.MsgType, @as(u8, @intCast(msg_type))) catch return -3;
+    if (t != .snapshot and t != .delta) return -3;
+    const payload = input_buf[0..len];
+    const cursor_before = c.rep.eng.cursorPos();
+    const applied = c.rep.apply(t, payload) catch |err| switch (err) {
+        // A short snapshot proves nothing and paints nothing.
+        error.BadPayload => return -3,
+        // Engine resize failure: the grid the daemon named is beyond us.
+        else => return -3,
+    };
+    if (applied == .resync) return 1;
+    // Damage bookkeeping.
+    if (c.rep.grid.cols != c.cols or c.rep.grid.rows != c.rows) {
+        // The grid moved: reallocate the readout for the new geometry
+        // (everything is dirty by construction).
+        const old_viewport = c.viewport;
+        const old_dirty = c.dirty;
+        const old_list = c.dirty_list;
+        allocGridBufs(c, c.rep.grid.cols, c.rep.grid.rows) catch {
+            // Readout buffers gone stale is unrecoverable in-place; the
+            // host treats it as fatal and re-inits.
+            return -1;
+        };
+        alloc.free(old_viewport);
+        alloc.free(old_dirty);
+        alloc.free(old_list);
+    } else switch (t) {
+        .snapshot => @memset(c.dirty, true),
+        .delta => {
+            var it = proto.deltaRowIterator(payload);
+            while (it.next() catch null) |row| {
+                if (row.row < c.rows) c.dirty[row.row] = true;
+            }
+            // The renderer draws the cursor; both its old and new rows
+            // need repainting even when no content there changed.
+            if (cursor_before.y < c.rows) c.dirty[cursor_before.y] = true;
+            const cur = c.rep.eng.cursorPos();
+            if (cur.y < c.rows) c.dirty[cur.y] = true;
+        },
+        else => unreachable,
+    }
+    return 0;
+}
+/// Force a full repaint on the next mux_read_viewport (scroll-mode exit,
+/// a canvas the host lost, first paint after tab restore).
+export fn mux_mark_all_dirty() void {
+    const c = core orelse return;
+    @memset(c.dirty, true);
+}
+// ---------------------------------------------------------------------
+// Attach / resume coordinates
+// ---------------------------------------------------------------------
+export fn mux_attach_seq() u64 {
+    const c = core orelse return 0;
+    return c.rep.attachArgs().have_seq;
+}
+export fn mux_attach_epoch() u64 {
+    const c = core orelse return 0;
+    return c.rep.attachArgs().have_epoch;
+}
+/// The whole 20-byte attach payload into the output buffer, so JS never
+/// hand-assembles a u64. `cols`/`rows` are what this client claims — a
+/// wall tile passes 1x1 (the passivity contract), the zoomed tile its
+/// real size. Quotes the replica's resume coordinates; pass fresh=1 to
+/// quote (0,0) instead (the resync re-attach).
+export fn mux_attach_payload(cols: u32, rows: u32, fresh: u32) i32 {
+    const c = core orelse return -1;
+    if (cols > 0xffff or rows > 0xffff) return -3;
+    const args = if (fresh != 0)
+        Replica.AttachArgs{ .have_seq = 0, .have_epoch = 0 }
+    else
+        c.rep.attachArgs();
+    const payload = proto.encodeAttach(
+        @intCast(cols),
+        @intCast(rows),
+        args.have_seq,
+        args.have_epoch,
+    );
+    @memcpy(output_buf[0..payload.len], &payload);
+    output_len = payload.len;
+    return @intCast(payload.len);
+}
+// ---------------------------------------------------------------------
+// Geometry, cursor, mode
+// ---------------------------------------------------------------------
+export fn mux_cols() u32 {
+    const c = core orelse return 0;
+    return c.rep.grid.cols;
+}
+export fn mux_rows() u32 {
+    const c = core orelse return 0;
+    return c.rep.grid.rows;
+}
+export fn mux_cursor_x() u32 {
+    const c = core orelse return 0;
+    return c.rep.eng.cursorPos().x;
+}
+export fn mux_cursor_y() u32 {
+    const c = core orelse return 0;
+    return c.rep.eng.cursorPos().y;
+}
+export fn mux_history_rows() u32 {
+    const c = core orelse return 0;
+    return c.rep.history_rows;
+}
+/// Screen-space start row for scroll page N (replica.zig's math).
+export fn mux_scroll_start(pages_up: u32, view_rows: u32) u32 {
+    const c = core orelse return 0;
+    if (view_rows > 0xffff) return 0;
+    return c.rep.scrollStart(pages_up, @intCast(view_rows));
+}
+// ---------------------------------------------------------------------
+// Input encoding
+// ---------------------------------------------------------------------
+/// keymap.Key by @intFromEnum — JS mirrors this table (char=0, enter=1,
+/// tab=2, backspace=3, escape=4, up=5, down=6, left=7, right=8, home=9,
+/// end=10, insert=11, delete=12, page_up=13, page_down=14, f1..f12=15..26).
+/// mods: bit0 shift, bit1 alt, bit2 ctrl. Returns the byte length written
+/// to the output buffer (0 = nothing to send), -3 on an unknown key.
+export fn mux_key_encode(key: u32, cp: u32, mods: u32) i32 {
+    const k = std.meta.intToEnum(keymap.Key, key) catch return -3;
+    if (cp > 0x10ffff) return -3;
+    const ev = keymap.Event{
+        .key = k,
+        .cp = @intCast(cp),
+        .mods = .{
+            .shift = mods & 1 != 0,
+            .alt = mods & 2 != 0,
+            .ctrl = mods & 4 != 0,
+        },
+    };
+    var buf: [keymap.max_seq_len]u8 = undefined;
+    const seq = keymap.encode(ev, &buf);
+    @memcpy(output_buf[0..seq.len], seq);
+    output_len = @intCast(seq.len);
+    return @intCast(seq.len);
+}
+/// Wrap `len` staged bytes in bracketed paste into the output buffer.
+/// The shell chunks pastes at 32 KiB, so the wrap always fits the 64 KiB
+/// output buffer; -2 if the host ignored that contract.
+export fn mux_paste_encode(len: u32) i32 {
+    if (len > input_buf.len) return -2;
+    const total = keymap.paste_begin.len + len + keymap.paste_end.len;
+    if (total > output_buf.len) return -2;
+    @memcpy(output_buf[0..keymap.paste_begin.len], keymap.paste_begin);
+    @memcpy(output_buf[keymap.paste_begin.len..][0..len], input_buf[0..len]);
+    @memcpy(output_buf[keymap.paste_begin.len + len ..][0..keymap.paste_end.len], keymap.paste_end);
+    output_len = @intCast(total);
+    return @intCast(total);
+}
+// ---------------------------------------------------------------------
+// Flat viewport readout
+// ---------------------------------------------------------------------
+/// cols*rows cells, 4 u32 each, row-major:
+///   [0] codepoint (0 = empty cell)
+///   [1] fg: kind << 24 | value   (kind 0 none, 1 palette, 2 rgb;
+///       value = palette index or 0xRRGGBB)
+///   [2] bg: same packing
+///   [3] flags: ghostty's u16 style flags (bit 0 bold, 1 italic, 2 faint,
+///       3 blink, 4 inverse, 5 invisible, 6 strikethrough, 7 overline,
+///       bits 8-10 underline style) | wide << 16 | spacer << 17
+/// Valid until the next call that can grow memory — JS re-reads
+/// memory.buffer every time (see the module header).
+export fn mux_viewport_ptr() [*]const u32 {
+    const c = core orelse return &empty_viewport;
+    return c.viewport.ptr;
+}
+/// What an uninitialized core hands out instead of a null pointer JS
+/// would happily index into.
+var empty_viewport: [4]u32 = .{ 0, 0, 0, 0 };
+/// Repaint the DIRTY rows into the viewport buffer, clear the dirty set,
+/// and return how many rows were repainted; mux_dirty_row(i) names them.
+export fn mux_read_viewport() u32 {
+    const c = core orelse return 0;
+    c.dirty_count = 0;
+    for (c.dirty, 0..) |d, y| {
+        if (!d) continue;
+        paintRow(c, c.eng, @intCast(y));
+        c.dirty_list[c.dirty_count] = @intCast(y);
+        c.dirty_count += 1;
+    }
+    @memset(c.dirty, false);
+    return c.dirty_count;
+}
+export fn mux_dirty_row(i: u32) u32 {
+    const c = core orelse return 0;
+    if (i >= c.dirty_count) return 0;
+    return c.dirty_list[i];
+}
+fn paintRow(c: *Core, eng: *Engine, y: u16) void {
+    var x: u16 = 0;
+    while (x < c.cols) : (x += 1) {
+        const base = (@as(usize, y) * c.cols + x) * 4;
+        const cell = eng.term.screens.active.pages.getCell(.{ .viewport = .{
+            .x = @intCast(x),
+            .y = @intCast(y),
+        } }) orelse {
+            c.viewport[base] = 0;
+            c.viewport[base + 1] = 0;
+            c.viewport[base + 2] = 0;
+            c.viewport[base + 3] = 0;
+            continue;
+        };
+        c.viewport[base] = switch (cell.cell.content_tag) {
+            .codepoint, .codepoint_grapheme => cell.cell.content.codepoint,
+            .bg_color_palette, .bg_color_rgb => 0,
+        };
+        const style = cell.style();
+        c.viewport[base + 1] = packColor(style.fg_color);
+        c.viewport[base + 2] = packColor(style.bg_color);
+        const wide: u32 = switch (cell.cell.wide) {
+            .narrow => 0,
+            .wide => 1 << 16,
+            .spacer_tail, .spacer_head => 1 << 17,
+        };
+        c.viewport[base + 3] = @as(u32, @as(u16, @bitCast(style.flags))) | wide;
+    }
+}
+fn packColor(col: anytype) u32 {
+    return switch (col) {
+        .none => 0,
+        .palette => |p| (1 << 24) | @as(u32, p),
+        .rgb => |rgb| (2 << 24) |
+            (@as(u32, rgb.r) << 16) | (@as(u32, rgb.g) << 8) | @as(u32, rgb.b),
+    };
+}
+// ---------------------------------------------------------------------
+// Scrollback view (a scratch terminal; the live replica is never touched)
+// ---------------------------------------------------------------------
+/// Feed `len` staged bytes (a scrollback_chunk's rows, echo header
+/// already stripped by the host) into the scratch terminal, resetting it
+/// first. The scratch is created lazily at the live grid size and follows
+/// it. Returns 0, -1 uninit, -2 overflow.
+export fn mux_scroll_feed(len: u32) i32 {
+    const c = core orelse return -1;
+    if (len > input_buf.len) return -2;
+    if (c.scroll_eng) |se| {
+        if (se.term.cols != c.cols or se.term.rows != c.rows) {
+            se.deinit();
+            c.scroll_eng = null;
+        }
+    }
+    if (c.scroll_eng == null) {
+        c.scroll_eng = Engine.init(alloc, .{
+            .cols = c.cols,
+            .rows = c.rows,
+            .max_scrollback = 0,
+        }) catch return -1;
+    }
+    const se = c.scroll_eng.?;
+    se.reset();
+    se.feed(input_buf[0..len]);
+    return 0;
+}
+/// Paint the WHOLE scratch viewport into the shared viewport buffer and
+/// mark everything dirty for the next live read (leaving scroll mode must
+/// repaint from the replica). Returns rows painted.
+export fn mux_read_scroll_viewport() u32 {
+    const c = core orelse return 0;
+    const se = c.scroll_eng orelse return 0;
+    var y: u16 = 0;
+    while (y < c.rows) : (y += 1) paintRow(c, se, y);
+    @memset(c.dirty, true);
+    return c.rows;
+}
+// ---------------------------------------------------------------------
+// Diagnostics
+// ---------------------------------------------------------------------
+export fn mux_output_ptr() [*]const u8 {
+    return &output_buf;
+}
+export fn mux_output_len() u32 {
+    return output_len;
+}
+/// Plain-text dump of the live viewport (verify.js's referee; matches
+/// Engine.dumpPlain, the same text muxd dump prints).
+export fn mux_dump_plain() i32 {
+    const c = core orelse return -1;
+    output_len = 0;
+    const text = c.rep.eng.dumpPlain(alloc) catch return -2;
+    defer alloc.free(text);
+    if (text.len > output_buf.len) return -3;
+    @memcpy(output_buf[0..text.len], text);
+    output_len = @intCast(text.len);
+    return @intCast(text.len);
+}
+/// Replica-side terminal replies (DSR etc). DIAGNOSTIC ONLY: the daemon
+/// is authoritative and answers the application itself; forwarding these
+/// would double every reply. Cleared on read.
+export fn mux_take_pty_output() i32 {
+    const c = core orelse return -1;
+    output_len = 0;
+    const data = c.rep.eng.ptyOutput();
+    if (data.len > output_buf.len) return -3;
+    @memcpy(output_buf[0..data.len], data);
+    output_len = @intCast(data.len);
+    c.rep.eng.clearPtyOutput();
+    return @intCast(data.len);
+}
+comptime {
+    if (!builtin.target.cpu.arch.isWasm()) {
+        @compileError("wasm_core.zig is the wasm32 target's root; build it via the mux_core step");
+    }
+}

web/verify.js

@@ @@ -0,0 +1,220 @@ @@
+#!/usr/bin/env node
+// Fast non-browser smoke for the wasm core (M-web Task 4): drives
+// mux_core.wasm through the page's real call sequence — attach payload,
+// snapshot frame, delta frame, flat viewport readout, key encoding —
+// and asserts styled cells, damage rows, and resume coordinates.
+//
+// THE DISCIPLINE THIS FILE DEMONSTRATES: every wasm call can grow linear
+// memory, and growth detaches every cached ArrayBuffer view. Views are
+// re-read from exports.memory.buffer at every access, never cached.
+//
+// Usage: node web/verify.js [path/to/mux_core.wasm]
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const wasmPath = process.argv[2] ||
+  path.join(__dirname, '..', 'zig-out', 'bin', 'mux_core.wasm');
+let passed = 0, failed = 0;
+function check(name, got, want) {
+  const ok = typeof want === 'bigint' ? got === want : Object.is(got, want);
+  if (ok) { passed++; }
+  else { failed++; console.error(`FAIL ${name}: got ${got}, want ${want}`); }
+}
+// --- wire builders (layouts golden-pinned in protocol.zig) ---
+function snapshotPayload({ seq, history, cols, rows, epoch }, state) {
+  const stateBytes = Buffer.from(state, 'utf8');
+  const b = Buffer.alloc(24 + stateBytes.length);
+  b.writeBigUInt64LE(BigInt(seq), 0);
+  b.writeUInt32LE(history, 8);
+  b.writeUInt16LE(cols, 12);
+  b.writeUInt16LE(rows, 14);
+  b.writeBigUInt64LE(BigInt(epoch), 16);
+  stateBytes.copy(b, 24);
+  return b;
+}
+function deltaPayload({ seq, history, cx, cy }, rowEntries) {
+  const parts = [];
+  const hdr = Buffer.alloc(18);
+  hdr.writeBigUInt64LE(BigInt(seq), 0);
+  hdr.writeUInt32LE(history, 8);
+  hdr.writeUInt16LE(cx, 12);
+  hdr.writeUInt16LE(cy, 14);
+  hdr.writeUInt16LE(rowEntries.length, 16);
+  parts.push(hdr);
+  for (const [row, text] of rowEntries) {
+    const bytes = Buffer.from(text, 'utf8');
+    const rh = Buffer.alloc(6);
+    rh.writeUInt16LE(row, 0);
+    rh.writeUInt32LE(bytes.length, 2);
+    parts.push(rh, bytes);
+  }
+  return Buffer.concat(parts);
+}
+async function main() {
+  const bin = fs.readFileSync(wasmPath);
+  const { instance } = await WebAssembly.instantiate(bin, {});
+  const e = instance.exports;
+  const mem = () => Buffer.from(e.memory.buffer); // ALWAYS fresh
+  const stage = (buf) => {
+    if (buf.length > e.mux_input_cap()) throw new Error('over cap');
+    buf.copy(mem(), e.mux_input_ptr());
+    return buf.length;
+  };
+  const outBytes = () =>
+    Buffer.from(mem().subarray(e.mux_output_ptr(), e.mux_output_ptr() + e.mux_output_len()));
+  const cell = (x, y) => {
+    const cols = e.mux_cols();
+    const base = e.mux_viewport_ptr() + (y * cols + x) * 16;
+    const m = mem();
+    return {
+      cp: m.readUInt32LE(base),
+      fg: m.readUInt32LE(base + 4),
+      bg: m.readUInt32LE(base + 8),
+      flags: m.readUInt32LE(base + 12),
+    };
+  };
+  // --- init ---
+  check('init', e.mux_init(80, 24), 0);
+  check('cols', e.mux_cols(), 80);
+  check('rows', e.mux_rows(), 24);
+  // --- attach payload before any state: quotes (0,0); wall spelling 1x1 ---
+  check('attach len', e.mux_attach_payload(1, 1, 0), 20);
+  let att = outBytes();
+  check('attach cols', att.readUInt16LE(0), 1);
+  check('attach rows', att.readUInt16LE(2), 1);
+  check('attach seq0', att.readBigUInt64LE(4), 0n);
+  check('attach epoch0', att.readBigUInt64LE(12), 0n);
+  // --- snapshot: styled text, adoption, full damage ---
+  const snap = snapshotPayload(
+    { seq: 7, history: 3, cols: 80, rows: 24, epoch: 0xabcdn },
+    '\x1b[1;31mhello\x1b[0m world',
+  );
+  check('apply snapshot', e.mux_apply_frame(0x81, stage(snap)), 0);
+  check('seq adopted', e.mux_attach_seq(), 7n);
+  check('epoch adopted', e.mux_attach_epoch(), 0xabcdn);
+  check('history', e.mux_history_rows(), 3);
+  check('snapshot dirties all', e.mux_read_viewport(), 24);
+  check('cell h', cell(0, 0).cp, 'h'.codePointAt(0));
+  check('cell h bold', cell(0, 0).flags & 1, 1);
+  check('cell h fg palette red', cell(0, 0).fg, (1 << 24) | 1);
+  check('cell w plain', cell(6, 0).flags & 0xffff, 0);
+  check('cell w fg none', cell(6, 0).fg, 0);
+  check('cursor x', e.mux_cursor_x(), 11); // 11 visible cols; SGRs move nothing
+  // --- delta: rows 0 and 2 repainted, damage = their rows + cursor rows ---
+  const delta = deltaPayload(
+    { seq: 8, history: 4, cx: 2, cy: 2 },
+    [[0, '\x1b[7myo\x1b[0m'], [2, 'row two']],
+  );
+  check('apply delta', e.mux_apply_frame(0x87, stage(delta)), 0);
+  check('seq advanced', e.mux_attach_seq(), 8n);
+  check('history follows', e.mux_history_rows(), 4);
+  const ndirty = e.mux_read_viewport();
+  const dirtyRows = [];
+  for (let i = 0; i < ndirty; i++) dirtyRows.push(e.mux_dirty_row(i));
+  // rows 0 (content+old cursor row 0) and 2 (content+new cursor) — sorted.
+  check('delta dirty rows', dirtyRows.join(','), '0,2');
+  check('cell yo inverse', cell(0, 0).flags & (1 << 4), 1 << 4);
+  check('cell row2', cell(0, 2).cp, 'r'.codePointAt(0));
+  check('cursor y', e.mux_cursor_y(), 2);
+  // --- attach after state: quotes what we hold; fresh=1 re-quotes zero ---
+  e.mux_attach_payload(80, 24, 0);
+  att = outBytes();
+  check('attach seq held', att.readBigUInt64LE(4), 8n);
+  check('attach epoch held', att.readBigUInt64LE(12), 0xabcdn);
+  e.mux_attach_payload(80, 24, 1);
+  att = outBytes();
+  check('attach fresh seq', att.readBigUInt64LE(4), 0n);
+  // --- resync path: header lies about row count ---
+  const bad = deltaPayload({ seq: 9, history: 4, cx: 0, cy: 0 }, [[0, 'x']]);
+  bad.writeUInt16LE(2, 16); // row_count claims 2
+  check('resync', e.mux_apply_frame(0x87, stage(bad)), 1);
+  check('resync holds seq', e.mux_attach_seq(), 8n);
+  // --- bad frames ---
+  check('not replay frame', e.mux_apply_frame(0x88, 1), -3);
+  check('unknown type', e.mux_apply_frame(0x40, 0), -3);
+  check('short snapshot', e.mux_apply_frame(0x81, 10), -3);
+  // --- grid move via snapshot: readout follows, all dirty ---
+  const wide = snapshotPayload(
+    { seq: 10, history: 0, cols: 100, rows: 30, epoch: 0xabcdn },
+    'wide',
+  );
+  check('apply wide', e.mux_apply_frame(0x81, stage(wide)), 0);
+  check('cols follow', e.mux_cols(), 100);
+  check('rows follow', e.mux_rows(), 30);
+  check('grid move dirties all', e.mux_read_viewport(), 30);
+  check('cell after move', cell(0, 0).cp, 'w'.codePointAt(0));
+  // --- wide CJK: wide flag + spacer ---
+  const cjk = snapshotPayload(
+    { seq: 11, history: 0, cols: 100, rows: 30, epoch: 0xabcdn },
+    '漢字',
+  );
+  e.mux_apply_frame(0x81, stage(cjk));
+  e.mux_read_viewport();
+  check('cjk cp', cell(0, 0).cp, 0x6f22);
+  check('cjk wide', cell(0, 0).flags & (1 << 16), 1 << 16);
+  check('cjk spacer', cell(1, 0).flags & (1 << 17), 1 << 17);
+  check('cjk second', cell(2, 0).cp, 0x5b57);
+  // --- key encoding round-trips two table rows ---
+  check('key a', e.mux_key_encode(0, 'a'.codePointAt(0), 0), 1);
+  check('key a byte', outBytes().toString('latin1'), 'a');
+  check('key ctrl-up', e.mux_key_encode(5, 0, 4), 6);
+  check('key ctrl-up seq', outBytes().toString('latin1'), '\x1b[1;5A');
+  check('key unknown', e.mux_key_encode(99, 0, 0), -3);
+  // --- paste wrap ---
+  stage(Buffer.from('two\nlines'));
+  check('paste len', e.mux_paste_encode(9), 9 + 12);
+  check('paste bytes', outBytes().toString('latin1'), '\x1b[200~two\nlines\x1b[201~');
+  // --- scroll scratch: never touches the live replica ---
+  check('scroll start', e.mux_scroll_start(1, 30), 0); // history 0: saturates
+  stage(Buffer.from('old history line'));
+  check('scroll feed', e.mux_scroll_feed(16), 0);
+  check('scroll read', e.mux_read_scroll_viewport(), 30);
+  check('scroll cell', cell(0, 0).cp, 'o'.codePointAt(0));
+  check('live untouched: full repaint queued', e.mux_read_viewport(), 30);
+  check('live cell back', cell(0, 0).cp, 0x6f22);
+  // --- diagnostics: dump matches, pty replies readable and cleared ---
+  e.mux_dump_plain();
+  check('dump starts', outBytes().toString('utf8').startsWith('漢字'), true);
+  stage(Buffer.from('\x1b[6n')); // DSR: replica answers locally (diagnostic only)
+  e.mux_apply_frame(0x81, stage(snapshotPayload(
+    { seq: 12, history: 0, cols: 100, rows: 30, epoch: 0xabcdn }, '\x1b[6n')));
+  const n = e.mux_take_pty_output();
+  check('pty reply present', n > 0, true);
+  check('pty reply cleared', e.mux_take_pty_output(), 0);
+  // --- a real-sized snapshot fits the staging buffer ---
+  // 100x30 grid fully painted with styled cells is well under 256K; the
+  // pin here is the CAP ITSELF: input_cap must hold the biggest payload
+  // the daemon sends in one frame for the wall's grids.
+  check('input cap', e.mux_input_cap(), 256 * 1024);
+  // --- deinit / re-init ---
+  e.mux_deinit();
+  check('apply after deinit', e.mux_apply_frame(0x81, 0), -1);
+  check('re-init', e.mux_init(80, 24), 0);
+  e.mux_deinit();
+  console.log(`verify: ${passed} passed, ${failed} failed`);
+  process.exit(failed ? 1 : 0);
+}
+main().catch((err) => { console.error(err); process.exit(1); });