285ceedf

feat: the seed — the sidecar's cut before any host has answered

a73x 2026-08-30 16:31

Commit message

feat: the seed — the sidecar's cut before any host has answered

`seedLayout` turns sidecar bytes into a SeedPlan: the parsed tree
installed with leaves remapped to pending panes, orientation and
weights intact. The file stays a match key, never an address — a leaf
is dropped unless its host part equals a wall host's spelling byte for
byte — and a cut too big for this terminal drops panes until it fits,
because the boot's first flatten has no TooSmall degrade of its own.

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

src/tui/wall_layout.zig

@@ @@ -9,6 +9,7 @@ const interact = @import("interact.zig"); @@
+const layout = @import("client").layout;
+const wall_host = @import("wall_host.zig");
+const wv = @import("wallview.zig");
+const Host = wall_host.Host;
+const Resolved = wall_host.Resolved;
+const Shared = wv.Shared;
+const Tile = wv.Tile;
@@ @@ -333,6 +334,195 @@ pub fn saveSidecar(w: Wall) void { @@
+    saveLayoutTo(w.alloc, path, w.liveTiles(), w.livePresent(), w.shared);
+pub const SeedPane = struct { host: usize, session: []u8, label: []u8 };
+const SeedKeep = struct { saved: usize, host: usize };
+/// What a seeded wall is made of, index = tile index. A null pane is the
+/// ENTRY tile's own slot: real from birth, never pending.
+pub const SeedPlan = struct {
+    panes: []?SeedPane,
+    focus: ?usize,
+    dropped: usize,
+    pub fn deinit(self: *SeedPlan, alloc: std.mem.Allocator) void {
+        for (self.panes) |mp| {
+            if (mp) |pane| {
+                alloc.free(pane.session);
+                alloc.free(pane.label);
+            }
+        }
+        alloc.free(self.panes);
+    }
+};
+/// The sidecar's cut before any host answers; every failure degrades
+/// silently, leaf by leaf or file whole, to the default cut.
+pub fn seedLayout(
+    alloc: std.mem.Allocator,
+    table: []const Host,
+    shared: *Shared,
+    bytes: []const u8,
+    entry_spelling: ?[]const u8,
+) ?SeedPlan {
+    // Pass 1: read the spellings once and give each leaf its fate.
+    var probe = layout.parse(alloc, bytes) orelse return null;
+    var keeps = std.ArrayListUnmanaged(SeedKeep){};
+    defer keeps.deinit(alloc);
+    var entry_at: ?usize = null;
+    var dropped: usize = 0;
+    for (probe.spellings.items, 0..) |sp, i| {
+        if (entry_spelling) |es| {
+            if (entry_at == null and std.mem.eql(u8, sp, es)) {
+                entry_at = i;
+                continue;
+            }
+        }
+        const cut = std.mem.lastIndexOfScalar(u8, sp, '#') orelse {
+            dropped += 1;
+            continue;
+        };
+        const sess = sp[cut + 1 ..];
+        if (!proto.validSessionName(sess)) {
+            dropped += 1;
+            continue;
+        }
+        // The host part must be ON the wall, byte for byte: the file is a
+        // match key, never an address, so nothing here can be resurrected.
+        const hi = for (table, 0..) |*h, j| {
+            if (std.mem.eql(u8, h.spec.spelling, sp[0..cut])) break j;
+        } else {
+            dropped += 1;
+            continue;
+        };
+        // The shell's own session would wait forever: never birthed
+        // (`showsSelf`) and named by every list, so never collapsed.
+        if (table[hi].self_name) |self| {
+            if (std.mem.eql(u8, self, sess)) {
+                dropped += 1;
+                continue;
+            }
+        }
+        // A host's list names a session once; a second pane on the same
+        // (host, session) could never bind.
+        const dup = blk: {
+            if (entry_spelling) |es| {
+                if (std.mem.eql(u8, sp, es)) break :blk true;
+            }
+            for (keeps.items) |k| {
+                if (std.mem.eql(u8, probe.spellings.items[k.saved], sp)) break :blk true;
+            }
+            break :blk false;
+        };
+        if (dup) {
+            dropped += 1;
+            continue;
+        }
+        keeps.append(alloc, .{ .saved = i, .host = hi }) catch {
+            probe.deinit(alloc);
+            return null;
+        };
+    }
+    const base: usize = if (entry_spelling != null) 1 else 0;
+    while (base + keeps.items.len > wv.max_tiles) {
+        _ = keeps.pop();
+        dropped += 1;
+    }
+    probe.deinit(alloc);
+    if (keeps.items.len == 0) return null;
+    // A tree cut on a big screen must not refuse the boot on a laptop:
+    // drop the last pane and retry until the terminal can hold what is
+    // left, or nothing is left and today's default cut runs.
+    var n = keeps.items.len;
+    while (n >= 1) : (n -= 1) {
+        if (seedAttempt(alloc, shared, bytes, entry_at, keeps.items[0..n], base)) |plan| {
+            var out = plan;
+            out.dropped = dropped + (keeps.items.len - n);
+            return out;
+        }
+    }
+    return null;
+}
+/// One sizing attempt over the first `keeps` panes; the tree is
+/// installed only if the terminal can cut it.
+fn seedAttempt(
+    alloc: std.mem.Allocator,
+    shared: *Shared,
+    bytes: []const u8,
+    entry_at: ?usize,
+    keeps: []const SeedKeep,
+    base: usize,
+) ?SeedPlan {
+    var parsed = layout.parse(alloc, bytes) orelse return null;
+    const map = alloc.alloc(?u8, parsed.spellings.items.len) catch {
+        parsed.deinit(alloc);
+        return null;
+    };
+    defer alloc.free(map);
+    @memset(map, null);
+    if (entry_at) |e| map[e] = 0;
+    for (keeps, 0..) |k, i| map[k.saved] = @intCast(base + i);
+    var focus: ?usize = null;
+    if (parsed.focus) |k| {
+        if (k < map.len) {
+            if (map[k]) |f| focus = f;
+        }
+    }
+    const total = base + keeps.len;
+    var plan: SeedPlan = .{
+        .panes = alloc.alloc(?SeedPane, total) catch {
+            parsed.deinit(alloc);
+            return null;
+        },
+        .focus = focus,
+        .dropped = 0,
+    };
+    @memset(plan.panes, null);
+    // Duped: a wall tile owns its two copies, and the birth that reuses a
+    // collapsed pane's digit frees them with the wall's allocator.
+    const ok = blk: {
+        for (keeps, 0..) |k, i| {
+            const sp = parsed.spellings.items[k.saved];
+            const cut = std.mem.lastIndexOfScalar(u8, sp, '#').?;
+            const sess = alloc.dupe(u8, sp[cut + 1 ..]) catch break :blk false;
+            const label = alloc.dupe(u8, sp) catch {
+                alloc.free(sess);
+                break :blk false;
+            };
+            plan.panes[base + i] = .{ .host = k.host, .session = sess, .label = label };
+        }
+        break :blk true;
+    };
+    if (!ok) {
+        plan.deinit(alloc);
+        parsed.deinit(alloc);
+        return null;
+    }
+    parsed.tree.remapLeaves(map);
+    if (base == 1 and entry_at == null) {
+        const anchor: u8 = if (focus) |f| @intCast(f) else @intCast(base);
+        parsed.tree.insert(anchor, 0) catch {
+            plan.deinit(alloc);
+            parsed.deinit(alloc);
+            return null;
+        };
+    }
+    if (parsed.tree.flatten(alloc, shared.size.rows, shared.size.cols, wallFloors(total), null)) |flat| {
+        var f = flat;
+        f.deinit(alloc);
+    } else |_| {
+        plan.deinit(alloc);
+        parsed.deinit(alloc);
+        return null;
+    }
+    shared.tree.deinit();
+    shared.tree = parsed.tree;
+    for (parsed.spellings.items) |sp| alloc.free(sp);
+    parsed.spellings.deinit(alloc);
+    return plan;
+}
+/// The saved layout over the tiles the hosts turned out to have; null
+/// when nothing matched.
+pub fn restoreSidecar(w: Wall, focus_out: *?usize) ?void {

src/tui/wall_test_layout.zig

+    defer alloc.free(q);
+    try std.testing.expectEqualStrings("/home/u/.local/state/mux/layout", q);
+// ---- the seed: the sidecar's cut before any host has answered ----
+/// Two hosts and a three-leaf sidecar — beside(a, stacked(b, c)) with
+/// UNEQUAL weights — so orientation, weight and host aliasing are all
+/// dimensions every seed test exercises by default.
+const seed_bytes = "mux-layout 1\nbeside 0\n leaf 70 --sock /tmp/h0.sock#a\n stacked 29\n  leaf 20 --sock /tmp/h0.sock#b\n  leaf 8 --sock /tmp/h1.sock#a\nfocus 1\n";
+fn seedShared(alloc: std.mem.Allocator, shared: *Shared) void {
+    shared.* = Shared{ .out_fd = -1, .size = .{ .cols = 100, .rows = 30 }, .is_tty = false };
+    shared.tree = layout.Tree.init(alloc);
+    shared.flat_alloc = alloc;
+}
+test "seed: the saved cut is the tree before any host has answered - orientation and weights both" {
+    const alloc = std.testing.allocator;
+    var shared: Shared = undefined;
+    seedShared(alloc, &shared);
+    defer shared.tree.deinit();
+    var table = [_]wall_host.Host{
+        fixture.testHost(&shared, "--sock /tmp/h0.sock", "/tmp/h0.sock"),
+        fixture.testHost(&shared, "--sock /tmp/h1.sock", "/tmp/h1.sock"),
+    };
+    var plan = wall_layout.seedLayout(alloc, &table, &shared, seed_bytes, null) orelse
+        return error.SeedRefusedAValidSidecar;
+    defer plan.deinit(alloc);
+    try std.testing.expectEqual(@as(usize, 3), plan.panes.len);
+    try std.testing.expectEqual(@as(usize, 0), plan.dropped);
+    try std.testing.expectEqual(@as(usize, 0), plan.panes[0].?.host);
+    try std.testing.expectEqualStrings("a", plan.panes[0].?.session);
+    try std.testing.expectEqual(@as(usize, 1), plan.panes[2].?.host);
+    var f = try shared.tree.flatten(alloc, 30, 100, wall_layout.wallFloors(3), null);
+    defer f.deinit(alloc);
+    // The saved orientation: pane 0 beside the stack of 1 over 2. The old
+    // heal lost both to the default cut; the rects are the pin.
+    const r0 = f.rectOf(0).?;
+    const r1 = f.rectOf(1).?;
+    const r2 = f.rectOf(2).?;
+    try std.testing.expect(r1.left > 0 and r1.top == 0);
+    try std.testing.expect(r2.left == r1.left and r2.top > 0);
+    // The saved weights: 70/29 is not an even cut.
+    try std.testing.expect(r0.cols > 2 * r1.cols);
+}
+test "seed: a leaf whose host is not on the wall is dropped and the rest keep their cut" {
+    const alloc = std.testing.allocator;
+    var shared: Shared = undefined;
+    seedShared(alloc, &shared);
+    defer shared.tree.deinit();
+    var table = [_]wall_host.Host{
+        fixture.testHost(&shared, "--sock /tmp/h0.sock", "/tmp/h0.sock"),
+    };
+    var plan = wall_layout.seedLayout(alloc, &table, &shared, seed_bytes, null) orelse
+        return error.SeedRefusedAValidSidecar;
+    defer plan.deinit(alloc);
+    try std.testing.expectEqual(@as(usize, 2), plan.panes.len);
+    try std.testing.expectEqual(@as(usize, 1), plan.dropped);
+    try std.testing.expectEqualStrings("--sock /tmp/h0.sock#a", plan.panes[0].?.label);
+    try std.testing.expectEqualStrings("--sock /tmp/h0.sock#b", plan.panes[1].?.label);
+    try std.testing.expectEqual(@as(usize, 2), shared.tree.count());
+}
+test "seed: a leaf naming no session, or a name the wire grammar refuses, is dropped" {
+    const alloc = std.testing.allocator;
+    var shared: Shared = undefined;
+    seedShared(alloc, &shared);
+    defer shared.tree.deinit();
+    var table = [_]wall_host.Host{
+        fixture.testHost(&shared, "--sock /tmp/h0.sock", "/tmp/h0.sock"),
+    };
+    const bytes = "mux-layout 1\nstacked 0\n leaf 10 --sock /tmp/h0.sock#a\n leaf 10 no-hash-at-all\n leaf 10 --sock /tmp/h0.sock#ha sh\n";
+    var plan = wall_layout.seedLayout(alloc, &table, &shared, bytes, null) orelse
+        return error.SeedRefusedAValidSidecar;
+    defer plan.deinit(alloc);
+    try std.testing.expectEqual(@as(usize, 1), plan.panes.len);
+    try std.testing.expectEqual(@as(usize, 2), plan.dropped);
+}
+test "seed: two leaves naming one host's one session become one pane" {
+    const alloc = std.testing.allocator;
+    var shared: Shared = undefined;
+    seedShared(alloc, &shared);
+    defer shared.tree.deinit();
+    var table = [_]wall_host.Host{
+        fixture.testHost(&shared, "--sock /tmp/h0.sock", "/tmp/h0.sock"),
+    };
+    const bytes = "mux-layout 1\nstacked 0\n leaf 10 --sock /tmp/h0.sock#a\n leaf 10 --sock /tmp/h0.sock#a\n";
+    var plan = wall_layout.seedLayout(alloc, &table, &shared, bytes, null) orelse
+        return error.SeedRefusedAValidSidecar;
+    defer plan.deinit(alloc);
+    try std.testing.expectEqual(@as(usize, 1), plan.panes.len);
+    try std.testing.expectEqual(@as(usize, 1), plan.dropped);
+}
+test "seed: the session this shell is standing in is never seeded" {
+    const alloc = std.testing.allocator;
+    var shared: Shared = undefined;
+    seedShared(alloc, &shared);
+    defer shared.tree.deinit();
+    var table = [_]wall_host.Host{
+        fixture.testHost(&shared, "--sock /tmp/h0.sock", "/tmp/h0.sock"),
+        fixture.testHost(&shared, "--sock /tmp/h1.sock", "/tmp/h1.sock"),
+    };
+    table[0].self_name = "a";
+    var plan = wall_layout.seedLayout(alloc, &table, &shared, seed_bytes, null) orelse
+        return error.SeedRefusedAValidSidecar;
+    defer plan.deinit(alloc);
+    try std.testing.expectEqual(@as(usize, 2), plan.panes.len);
+    try std.testing.expectEqual(@as(usize, 1), plan.dropped);
+    // Host 1's aliasing "a" is another host's session and stays.
+    try std.testing.expectEqualStrings("--sock /tmp/h0.sock#b", plan.panes[0].?.label);
+    try std.testing.expectEqualStrings("--sock /tmp/h1.sock#a", plan.panes[1].?.label);
+}
+test "seed: garbage, an empty file and a wall with no matching host all leave the tree exactly as it was" {
+    const alloc = std.testing.allocator;
+    var shared: Shared = undefined;
+    seedShared(alloc, &shared);
+    defer shared.tree.deinit();
+    try shared.tree.addFirst(7);
+    var table = [_]wall_host.Host{
+        fixture.testHost(&shared, "--sock /tmp/other.sock", "/tmp/other.sock"),
+    };
+    const cases = [_][]const u8{ "not a layout at all", "", seed_bytes };
+    for (cases) |bytes| {
+        try std.testing.expectEqual(
+            @as(?wall_layout.SeedPlan, null),
+            wall_layout.seedLayout(alloc, &table, &shared, bytes, null),
+        );
+        try std.testing.expectEqual(@as(usize, 1), shared.tree.count());
+    }
+}
+test "seed: more leaves than the terminal can cut seeds what fits and counts the rest" {
+    const alloc = std.testing.allocator;
+    var shared: Shared = undefined;
+    seedShared(alloc, &shared);
+    // Nine stacked panes at 3 rows each need 27; give them 13 rows, which
+    // holds four. The boot must not refuse - relayout's TooSmall degrade
+    // never runs on the first flatten, so the seed carries its own.
+    shared.size = .{ .cols = 100, .rows = 13 };
+    defer shared.tree.deinit();
+    var table = [_]wall_host.Host{
+        fixture.testHost(&shared, "--sock /tmp/h0.sock", "/tmp/h0.sock"),
+    };
+    var buf = std.ArrayListUnmanaged(u8){};
+    defer buf.deinit(alloc);
+    try buf.appendSlice(alloc, "mux-layout 1\nstacked 0\n");
+    for (0..9) |i| try buf.writer(alloc).print(" leaf 10 --sock /tmp/h0.sock#s{d}\n", .{i});
+    var plan = wall_layout.seedLayout(alloc, &table, &shared, buf.items, null) orelse
+        return error.SeedRefusedAFittableSidecar;
+    defer plan.deinit(alloc);
+    try std.testing.expectEqual(@as(usize, 4), plan.panes.len);
+    try std.testing.expectEqual(@as(usize, 5), plan.dropped);
+    try std.testing.expectEqual(@as(usize, 4), shared.tree.count());
+}
+test "seed: more leaves than max_tiles seeds max_tiles" {
+    const alloc = std.testing.allocator;
+    var shared: Shared = undefined;
+    seedShared(alloc, &shared);
+    // Tall enough that every kept pane fits: the cap under test is the
+    // wall's, not the terminal's.
+    shared.size = .{ .cols = 100, .rows = 500 };
+    defer shared.tree.deinit();
+    var table = [_]wall_host.Host{
+        fixture.testHost(&shared, "--sock /tmp/h0.sock", "/tmp/h0.sock"),
+    };
+    var buf = std.ArrayListUnmanaged(u8){};
+    defer buf.deinit(alloc);
+    try buf.appendSlice(alloc, "mux-layout 1\nstacked 0\n");
+    for (0..40) |i| try buf.writer(alloc).print(" leaf 10 --sock /tmp/h0.sock#s{d}\n", .{i});
+    var plan = wall_layout.seedLayout(alloc, &table, &shared, buf.items, null) orelse
+        return error.SeedRefusedAFittableSidecar;
+    defer plan.deinit(alloc);
+    try std.testing.expectEqual(wv.max_tiles, plan.panes.len);
+    try std.testing.expectEqual(@as(usize, 8), plan.dropped);
+}
+test "seed: the saved focus comes back as the pane that carries it, and is null when that leaf was dropped" {
+    const alloc = std.testing.allocator;
+    var shared: Shared = undefined;
+    seedShared(alloc, &shared);
+    defer shared.tree.deinit();
+    var table = [_]wall_host.Host{
+        fixture.testHost(&shared, "--sock /tmp/h0.sock", "/tmp/h0.sock"),
+        fixture.testHost(&shared, "--sock /tmp/h1.sock", "/tmp/h1.sock"),
+    };
+    var plan = wall_layout.seedLayout(alloc, &table, &shared, seed_bytes, null) orelse
+        return error.SeedRefusedAValidSidecar;
+    try std.testing.expectEqual(@as(?usize, 1), plan.focus);
+    plan.deinit(alloc);
+    // The focused leaf (saved index 1, host 0's "b") dropped with its host
+    // gone from the wall: nothing carries the focus record.
+    shared.tree.deinit();
+    shared.tree = layout.Tree.init(alloc);
+    var one = [_]wall_host.Host{
+        fixture.testHost(&shared, "--sock /tmp/h1.sock", "/tmp/h1.sock"),
+    };
+    var plan2 = wall_layout.seedLayout(alloc, &one, &shared, seed_bytes, null) orelse
+        return error.SeedRefusedAValidSidecar;
+    defer plan2.deinit(alloc);
+    try std.testing.expectEqual(@as(?usize, null), plan2.focus);
+}
+test "seed: the entry tile's own pane is not pending; a sidecar that does not know it inserts it" {
+    const alloc = std.testing.allocator;
+    var shared: Shared = undefined;
+    seedShared(alloc, &shared);
+    defer shared.tree.deinit();
+    var table = [_]wall_host.Host{
+        fixture.testHost(&shared, "--sock /tmp/h0.sock", "/tmp/h0.sock"),
+        fixture.testHost(&shared, "--sock /tmp/h1.sock", "/tmp/h1.sock"),
+    };
+    // Matched: the entry stands where its saved pane was, id 0, not
+    // pending, and no second pane claims its (host, session).
+    var plan = wall_layout.seedLayout(alloc, &table, &shared, seed_bytes, "--sock /tmp/h0.sock#a") orelse
+        return error.SeedRefusedAValidSidecar;
+    try std.testing.expectEqual(@as(usize, 3), plan.panes.len);
+    try std.testing.expectEqual(@as(?wall_layout.SeedPane, null), plan.panes[0]);
+    try std.testing.expect(plan.panes[1] != null and plan.panes[2] != null);
+    try std.testing.expectEqual(@as(usize, 3), shared.tree.count());
+    plan.deinit(alloc);
+    // Unmatched: the sidecar predates this entry; its pane is inserted
+    // beside the saved focus, and every saved leaf is still a pane.
+    shared.tree.deinit();
+    shared.tree = layout.Tree.init(alloc);
+    var plan2 = wall_layout.seedLayout(alloc, &table, &shared, seed_bytes, "--sock /tmp/h9.sock#z") orelse
+        return error.SeedRefusedAValidSidecar;
+    defer plan2.deinit(alloc);
+    try std.testing.expectEqual(@as(usize, 4), plan2.panes.len);
+    try std.testing.expectEqual(@as(?wall_layout.SeedPane, null), plan2.panes[0]);
+    try std.testing.expectEqual(@as(usize, 4), shared.tree.count());
+}