From f3591d48a16086dd4b3b081da00804d2541fefcc Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 01:53:25 -0300 Subject: The tree describes itself: README and commands from the tables; ctl takes input live README is made at each open from the tables (pinned per open, as the traces are): a line a file from control.zig's `files`, ctl's verbs indented under ctl (ctl's own, the script's input verbs, the console's, each with its args and doc from its row), and a line per State file under state/, from the layout (its path with for an index, its type, an enum's tags, a row's length), in the shape cloud9's `help` reads: `help ctl` prints the verbs, `help state/tracker` the state/ line and every file under it. `commands` is the verb lines alone, unindented, the sketch's own words (App.commands) last. A ctl read points at both. ctl takes the script's input verbs live: click, move, down, up, wheel, wheel-x, cancel, key, hold, release, type route their events at the wall clock through script.input, the same code a script runs, with no frame of their own: the next frame feeds them to update. Order: ctl's own words, then the input verbs, then a console line (and through it the sketch's); so a sketch command named like an input verb is shadowed over ctl (none is today). Tests: test-control, a new test: ctl's click and hold reach the pending events, a short click is refused (ExpectedPoint), README and commands read the rows and the layout: 40/40 steps, 10/10 tests. Live with the replay fixture: README read over 9P, `down 5 5` written to ctl moved state/pressing. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- src/host/control.zig | 97 ++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 91 insertions(+), 6 deletions(-) (limited to 'src/host/control.zig') diff --git a/src/host/control.zig b/src/host/control.zig index 1a8da92..bf1e12d 100644 --- a/src/host/control.zig +++ b/src/host/control.zig @@ -2,9 +2,12 @@ const std = @import("std"); const c9 = @import("cloud9"); const c = @import("c"); +const abi = @import("abi"); const Host = @import("Host.zig"); const Presentation = @import("Presentation.zig"); const state_files = @import("state_files.zig"); +const script = @import("script.zig"); +const Console = @import("Console.zig"); const fs = c9.fs; const transport = c9.transport; const Backend = struct { @@ -15,10 +18,10 @@ const Server = fs.Server(Backend, .{ .fid_capacity = 32, .slot_capacity = 4, .na const msize = 16384; /// The files, a row each: what lookup, readdir and getattr answer. A /// file's node is its number here. -const File = enum(u64) { @"/" = 1, ctl, status, log, @"screen.png", profile, @"profile-trace", @"timing-trace", @"presentation-trace", state = @bitCast(state_files.root) }; +const File = enum(u64) { @"/" = 1, ctl, status, log, @"screen.png", profile, @"profile-trace", @"timing-trace", @"presentation-trace", README, commands, state = @bitCast(state_files.root) }; const files = std.enums.EnumArray(File, struct { mode: u16 = 0o400, doc: []const u8 }).init(.{ .@"/" = .{ .mode = 0o700, .doc = "" }, - .ctl = .{ .mode = 0o600, .doc = "write console lines, a line each; screenshot captures the next frame, profile-reset clears profile" }, + .ctl = .{ .mode = 0o600, .doc = "write a verb a line, of those below: ctl's own, the input a script plays (live, no frame of its own), the console's; any other line goes to the sketch (commands lists its words)" }, .status = .{ .doc = "name, canvas size, playback mode, gpu, and the screenshot's state" }, .log = .{ .doc = "the console's last five lines" }, .@"screen.png" = .{ .doc = "the frame screenshot captured, as PNG; each open pins its own copy" }, @@ -26,6 +29,8 @@ const files = std.enums.EnumArray(File, struct { mode: u16 = 0o400, doc: []const .@"profile-trace" = .{ .doc = "with --profile-gpu: label,sample,ns, the samples kept, as CSV" }, .@"timing-trace" = .{ .doc = "index,frame_ns,work_ns,outside_work_ns, the frames kept, as CSV" }, .@"presentation-trace" = .{ .doc = "on Wayland: presentation feedback per frame, as CSV" }, + .README = .{ .doc = "this: a line a file, ctl's verbs under it, a line a State file under state/" }, + .commands = .{ .doc = "every verb ctl takes, a line each, the sketch's words last" }, .state = .{ .mode = 0o700, .doc = "the sketch's State: a directory per struct and array, a file per value; a read is the value, a write what set does (a jump); an array of numbers is one file of its values, blank-separated" }, }); @@ -161,7 +166,7 @@ pub const Control = struct { }, .getattr => reply.attr = self.attr(req.node), .open => { - if (file == .@"screen.png" or file == .@"profile-trace" or file == .@"timing-trace" or file == .@"presentation-trace") { + if (file == .@"screen.png" or file == .@"profile-trace" or file == .@"timing-trace" or file == .@"presentation-trace" or file == .README or file == .commands) { if (file == .@"screen.png") { if (self.capture_pending) return error.CapturePending; if (self.capture_error) |err| return err; @@ -172,6 +177,12 @@ pub const Control = struct { .@"screen.png" => try self.allocator.dupe(u8, self.png), .@"profile-trace" => try self.trace(host), .@"timing-trace" => try self.timingTrace(host), + .README, .commands => blk: { + var text: std.Io.Writer.Allocating = .init(self.allocator); + defer text.deinit(); + if (file == .README) try readme(host, &text.writer) else try verbLines(&text.writer, "", host.completions); + break :blk try text.toOwnedSlice(); + }, else => try self.presentationTrace(host), }; reply.handle = @intCast(handle); @@ -202,7 +213,7 @@ pub const Control = struct { .read => { var writer: std.Io.Writer = .fixed(buffer); const bytes: []const u8 = switch (file) { - .ctl => "Write one console command per line. screenshot captures the next frame.\n", + .ctl => "Write a verb a line: commands lists them, README says what each does.\n", .status => blk: { try writer.print("name {s}\nsize {d} {d}\nmode {t}\ngpu {s}\nscreenshot_pending {}\nscreenshot_generation {d}\nscreenshot_error {s}\n", .{ host.name, host.canvas[0], host.canvas[1], host.timeline.mode, if (host.gpu != null) "yes" else "no", self.capture_pending, self.generation, if (self.capture_error) |err| @errorName(err) else "none" }); break :blk writer.buffered(); @@ -214,7 +225,7 @@ pub const Control = struct { } break :blk writer.buffered(); }, - .@"screen.png", .@"profile-trace", .@"timing-trace", .@"presentation-trace" => if (req.handle > 0 and req.handle <= conn.snapshots.len) conn.snapshots[req.handle - 1] orelse return error.InvalidHandle else return error.InvalidHandle, + .@"screen.png", .@"profile-trace", .@"timing-trace", .@"presentation-trace", .README, .commands => if (req.handle > 0 and req.handle <= conn.snapshots.len) conn.snapshots[req.handle - 1] orelse return error.InvalidHandle else return error.InvalidHandle, .profile => blk: { const gpu = if (host.passes) |*gpu| gpu else return error.ProfilingDisabled; const profile = if (gpu.profile) |*profile| profile else return error.ProfilingDisabled; @@ -239,7 +250,11 @@ pub const Control = struct { while (lines.next()) |raw| { const line = std.mem.trim(u8, raw, " \t\r"); const verb = std.meta.stringToEnum(Verb, line) orelse { - try host.runLine(line, c.SDL_GetTicksNS()); + var words = std.mem.tokenizeAny(u8, line, " \t"); + const input = std.meta.stringToEnum(script.Verb, words.next() orelse ""); + if (input != null and script.verbs.get(input.?).input) { + try script.input(host, input.?, &words, c.SDL_GetTicksNS()); + } else try host.runLine(line, c.SDL_GetTicksNS()); continue; }; switch (verb) { @@ -332,6 +347,34 @@ pub const Control = struct { } }; +/// The README: a line a file, ctl's verbs indented under it and the +/// State's files under state/, in the shape cloud9's `help` reads. +fn readme(host: *Host, w: *std.Io.Writer) !void { + for (std.enums.values(File)[1..]) |f| { + const name = @tagName(f); + try w.print("{s}{s}", .{ name, if (f == .state) "/" else "" }); + try w.splatByteAll(' ', @max(1, 41 -| (name.len + @intFromBool(f == .state)))); + try w.print("{s}\n", .{files.get(f).doc}); + if (f == .ctl) try verbLines(w, " ", &.{}); + if (f == .state) try state_files.readme(host.state.layout, w); + } +} + +/// A line a verb ctl takes: ctl's own, the input verbs, the console's, +/// then `sketch`'s words. +fn verbLines(w: *std.Io.Writer, indent: []const u8, sketch: []const []const u8) !void { + for (std.enums.values(Verb)) |v| try verbLine(w, indent, @tagName(v), "", verbs.get(v)); + for (std.enums.values(script.Verb)) |v| if (script.verbs.get(v).input) try verbLine(w, indent, @tagName(v), script.verbs.get(v).args, script.verbs.get(v).doc); + for (std.enums.values(Console.Verb)) |v| try verbLine(w, indent, @tagName(v), Console.verbs.get(v).args, Console.verbs.get(v).doc); + for (sketch) |word| try w.print("{s}{s}\n", .{ indent, word }); +} + +fn verbLine(w: *std.Io.Writer, indent: []const u8, name: []const u8, args: []const u8, doc: []const u8) !void { + try w.print("{s}{s}{s}{s}", .{ indent, name, if (args.len > 0) " " else "", args }); + try w.splatByteAll(' ', @max(1, 37 -| (name.len + args.len + @intFromBool(args.len > 0)))); + try w.print("{s}\n", .{doc}); +} + /// Under `state/`: the live State as files (state_files.zig), a write /// run as the console's `set`. fn stateRespond(host: *Host, req: fs.Req, reply: *fs.Reply, buffer: []u8) ![]const u8 { @@ -526,3 +569,45 @@ test "control writes reject presentation trace mutations and opens own independe _ = try control.respond(&host, &conn, .{ .tag = 1, .op = .release, .node = 9, .handle = second, .opened = true }, &reply, &buf); try std.testing.expect(conn.snapshots[first - 1] == null and conn.snapshots[second - 1] == null); } + +test "control writes take input verbs live, and the README and commands read the tables" { + const a = std.testing.allocator; + var control: Control = .{ .allocator = a, .path = undefined, .listener = -1 }; + var host: Host = undefined; + host.gpa = a; + host.console = .{}; + host.input = .{}; + host.pending = .empty; + defer host.pending.deinit(a); + const S = struct { scene: enum(u8) { room, street } = .room, talk: struct { text: [3]u8 = @splat(0) } = .{} }; + var arena: std.heap.ArenaAllocator = .init(a); + defer arena.deinit(); + host.state.layout = try @import("memory.zig").Layout.copy(arena.allocator(), @import("abi").layout.of(S, .state)); + host.completions = &.{ "scene room", "scene street" }; + var conn: Connection = .{}; + var reply: fs.Reply = .{ .tag = 1 }; + var buf: [512]u8 = undefined; + _ = try control.respond(&host, &conn, .{ .tag = 1, .op = .write, .node = 2, .data = "click 10 20\nhold left_shift\n" }, &reply, &buf); + try std.testing.expectEqual(@as(usize, 4), host.pending.items.len); + try std.testing.expectEqual(abi.Event.Kind.mouse_up, host.pending.items[2].kind); + try std.testing.expectEqual(@as(f32, 20), host.pending.items[2].y); + try std.testing.expectEqual(abi.Event.Kind.key_down, host.pending.items[3].kind); + try std.testing.expectError(error.ExpectedPoint, control.respond(&host, &conn, .{ .tag = 1, .op = .write, .node = 2, .data = "click 10" }, &reply, &buf)); + for ([_]File{ .README, .commands }) |f| { + _ = try control.respond(&host, &conn, .{ .tag = 1, .op = .open, .node = @intFromEnum(f) }, &reply, &buf); + const handle = reply.handle; + const text = conn.snapshots[handle - 1].?; + if (f == .README) { + try std.testing.expect(std.mem.startsWith(u8, text, "ctl write a verb a line")); + try std.testing.expect(std.mem.indexOf(u8, text, "\n screenshot captures the next frame") != null); + try std.testing.expect(std.mem.indexOf(u8, text, "\n click X Y move there") != null); + try std.testing.expect(std.mem.indexOf(u8, text, "\n set FIELD VALUE... a field to a value") != null); + try std.testing.expect(std.mem.indexOf(u8, text, "\nstate/ the sketch's State") != null); + try std.testing.expect(std.mem.endsWith(u8, text, "\nstate/scene .room .street\nstate/talk/text 3 u8, blank-separated\n")); + } else { + try std.testing.expect(std.mem.startsWith(u8, text, "screenshot captures")); + try std.testing.expect(std.mem.endsWith(u8, text, "\nscene room\nscene street\n")); + } + _ = try control.respond(&host, &conn, .{ .tag = 1, .op = .release, .node = @intFromEnum(f), .handle = handle, .opened = true }, &reply, &buf); + } +} -- cgit v1.3