From a22b579ad2df8d1811f0e194fa1bbc06e2282cf8 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 03:44:57 -0300 Subject: term: the terminal a module of its own (docs/next-terminal.md, Phase 1): src/term/term.zig roots it, importing std, ghostty-vt, wuffs, zstbi and plain, never the core, and gives the core one table, `ops` (plain.term.Ops: about 60 entries, the records they take and give and the opaque handles State, Encoder, Track and Replica, in src/plain/term.zig), its own functions put in it through a cast refused at compile time unless each parameter and result matches the table's but for the handles and every error is one the table names; src/Term.zig, the core's side, takes `ops` from the term module when the build's term_options say the core has one (every core module but core-test's), null otherwise, and Term.State is a handle with the walk's hooks, so a dump keeps a terminal as it did (its Parts by name through walk.save, then ghostty's snapshot) and the digest is the emulator's; echo.zig comes back to the core (src/echo.zig: predicted echo is the replica's presentation, its five reads of the emulator through Term.grid, modes, prompt and Term.echoCell); screen_state's Peer is a plain record both sides name (its noteSent a function of screen_state's), its Encoder, Track and Replica handles made and freed through the table (replica.Screens makes its encoder at the first encode); a prompt's cut is told in columns and measured in its row's text by the core (Term.promptPrefix, File.rawAtDisplay); TerminalImages' decode bound moves from memory.limits to the decoder it bounds; build.zig: core_lean, the core module without the terminal, is core-test's, and wireCore no longer gives any core module ghostty-vt, wuffs or zstbi (the term module has them), so core-test's compile names none of ghostty, wuffs, zstbi, simdutf, highway or -lc++ (from --verbose); term-test runs the module's own tests (the pager's, screen_state's, the luminance table's); the tests of a terminal through a core move as they were to test/terminal.zig, in pane-test, which imports both (`of` reads the emulator behind a handle; the dump round trip frees through State.dumpFree), and tests elsewhere that read the emulator do it through Term.emulatorOf, a test in core-test skipping first; core-test skips a test whose terminal Term.open refuses; Authority.init releases its tape when the core it boots fails (it leaked); tests: core-test (no terminal) 409 of 941, 532 skipped, shell-test (the same tests with the terminal) 984 of 984, pane-test 180 of 181 (1 skipped, as before), term-test 15 of 15, kitty-test 45 of 45, replicas checked/wrong 0, hxdiff 658 cases 0 mismatches, behaviour-test 268 of 272 (the base's four addon ABI tests), lib-test --- src/plain/plain.zig | 3 +- src/plain/term.zig | 326 +++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 326 insertions(+), 3 deletions(-) (limited to 'src/plain') diff --git a/src/plain/plain.zig b/src/plain/plain.zig index 6dc75f94..6ca96fe9 100644 --- a/src/plain/plain.zig +++ b/src/plain/plain.zig @@ -5,7 +5,8 @@ //! Event.zig, under their old names) and the terminal (src/term/) both //! import it, and neither imports the other. const std = @import("std"); -/// The terminal as the core sees it: the records it takes and gives. +/// The terminal as the core sees it: its entries and the records they +/// take and give. pub const term = @import("term.zig"); pub const Color = union(enum) { default, index: u8, rgb: [3]u8 }; diff --git a/src/plain/term.zig b/src/plain/term.zig index 2f1323f0..dbc4fc87 100644 --- a/src/plain/term.zig +++ b/src/plain/term.zig @@ -1,11 +1,121 @@ //! The terminal as the core sees it (docs/next-terminal.md, Phase 1): the -//! records its draw group takes and gives, plain data. src/Term.zig is the -//! core's side of it. +//! entries (`Ops`) a terminal module gives the core, and the records they +//! take and give. A terminal's state, its replicas' encoder and tracks are +//! handles the core holds and never looks into; what it knows of them it is +//! told here, as numbers, bytes, text and cells. src/term/term.zig is the +//! one implementation (ghostty-vt behind it); src/Term.zig is the core's +//! side of it. const std = @import("std"); const plain = @import("plain.zig"); const Color = plain.Color; const CellStyle = plain.CellStyle; +/// A terminal: its emulator, its parse and what is kept beside it. +pub const State = opaque {}; +/// What a session's authority keeps to encode its terminals for its peers +/// (one for all of them), and what it keeps of one terminal for them. +pub const Encoder = opaque {}; +pub const Track = opaque {}; +/// A replica's side of one terminal: what it was sent. +pub const Replica = opaque {}; + +/// Where the view and the cursor are, in rows counted from the top of the +/// history: `total` rows, the view's top at `offset`, `len` of them shown. +/// All zero without a terminal. +pub const Grid = struct { + total: usize = 0, + offset: usize = 0, + len: usize = 0, + /// The cursor, in cells of the active area (the history's last `len` + /// rows). + cursor_x: u16 = 0, + cursor_y: u16 = 0, + /// The program shows the cursor (DECTCEM). + cursor_visible: bool = false, + /// The view's top row while it is scrolled to one, null while it + /// follows the output. + view: ?usize = null, + /// Its grid's width (a pane's may differ while a resize is deferred). + cols: u16 = 0, +}; + +/// What a `feed` told the rows the core keeps positions on: each tracked +/// row where it is after the read, whether the program erased it, whether +/// it cleared the screen, whether the pages the rows were on lived through +/// it (a reset can take them) and whether a row could not be followed (no +/// memory for its pin). Taped: a screen-state replica, which feeds +/// nothing, is told its authority's. +pub const Told = struct { rows: []const i32, erased: []const bool, cleared: bool, alive: bool, failed: bool }; + +pub const MouseMods = struct { shift: bool = false, alt: bool = false, ctrl: bool = false }; +pub const MouseButton = enum { left, middle, right, wheel_up, wheel_down, wheel_left, wheel_right }; +pub const MouseAction = enum { press, release, motion }; +/// Cursor-key presses: so many left, so many right. +pub const Moves = struct { left: usize = 0, right: usize = 0 }; + +/// The modes a program set that the core decides by. +pub const Modes = struct { + /// It tracks the mouse itself (1000, 1002, 1003). + mouse: bool = false, + /// ...every move of it (1003). + all_motion: bool = false, + /// A wheel over it is its own: it tracks the mouse, or it is on the + /// alternate screen with alternate scroll (1007). + wheel: bool = false, + /// It wants to hear focus in and out (1004). + focus: bool = false, + /// It wants its pastes bracketed (2004). + bracketed_paste: bool = false, + /// It has the alternate screen (1049). + alternate: bool = false, +}; + +/// Where a shell is in its command cycle, as pardes's own OSC 133 marks +/// tell it (marks carrying its `aid` alone: a nested shell's pass it by), +/// and what is at its cursor. All zero without a terminal. +pub const Prompt = struct { + phase: Phase = .none, + /// Commands started (C at the input phase), prompts drawn (B), and D + /// marks outside a running command (a line the shell handled without + /// starting it). + started: u32 = 0, + prompts: u32 = 0, + declined: u32 = 0, + /// The newest prompt continues an unfinished line (bash's PS2). + continuation: bool = false, + /// The newest command to end: which one, and its status if given. + finished: ?Finished = null, + /// The cursor is at a prompt's input, on either screen. + input_ready: bool = false, + /// ...and nothing is typed on its line up to the cursor. + input_empty: bool = false, + /// The cursor is on a prompt's row or at its input, on the primary + /// screen. + at_prompt: bool = false, + + pub const Phase = enum { none, prompt, input, running }; + pub const Finished = struct { seq: u32, status: ?i32 }; +}; + +/// What a command printed. `text` is the caller's. +pub const CommandOutput = struct { + text: [:0]const u8, + /// Whether `text` starts where the command did. It does not when that + /// start is not there to read: cut off by the rows asked for, scrolled + /// out of the history or erased from it (ED 3), erased under it while + /// it ran, or never marked (a C or D on the alternate screen). + whole: bool, +}; + +/// A terminal's rows as text: `rows` slices into `text`, which is a prefix +/// of `text_alloc` (a prompt cut off shortens the join), the last row the +/// empty one after the cursor's. +pub const Rows = struct { + text_alloc: []u8, + text: []const u8, + rows: [][]const u8, +}; + /// How much of a row the prompt it starts with is. pub const PromptCut = union(enum) { /// no prompt: the row as the emulator dumps it @@ -17,6 +127,20 @@ pub const PromptCut = union(enum) { cut: usize, }; +/// A program's output, as a terminal reads it, paged (`pardes -`, a +/// /pager write): its printed text and its SGR colours as spans over it. +pub const Page = struct { + text: []u8, + spans: []Span, + + pub fn deinit(page: Page, gpa: std.mem.Allocator) void { + gpa.free(page.text); + gpa.free(page.spans); + } +}; +/// Bytes `start..end` of a page's text, drawn in `style`. +pub const Span = struct { start: u32, end: u32, style: CellStyle }; + // ---- its colours on the body ---- /// A theme's colours as a terminal's paint takes them. @@ -108,3 +232,201 @@ pub const ImagesAt = struct { cell_w: u32, cell_h: u32, }; + +/// What a predicted echo reads of a cell: its codepoint, whether the shell +/// marked it input, and its style's identity. +pub const EchoCell = struct { cp: u21, input: bool, style: u32 }; + +// ---- its replicas ---- + +/// Deltas a peer may have in flight. At 207 ms and 60 frames a second about +/// 13 are; past the bound a peer gets nothing until an acknowledgement, and +/// then the newest state, the ones between skipped. +pub const flight_bound = 32; + +/// What the authority knows of one peer of one terminal. +pub const Peer = struct { + /// The version last sent, which the next delta is against; 0: none, so + /// the next starts the replica afresh. + sent: u32 = 0, + /// The versions in flight, oldest first. + flight: [flight_bound]u32 = undefined, + n: u8 = 0, + /// The history rows its replica holds as holes, absolute, as the + /// replica keeps them (Replica.apply's rule, from what it was sent): + /// what `fill` sends before a step reads them. + top: u64 = 0, + holes: std.ArrayListUnmanaged([2]u64) = .empty, + + pub fn deinit(peer: *Peer, gpa: std.mem.Allocator) void { + peer.holes.deinit(gpa); + } + + /// Every version up to `seq` has landed. + pub fn ack(peer: *Peer, seq: u32) void { + var i: u8 = 0; + while (i < peer.n and peer.flight[i] <= seq) i += 1; + std.mem.copyForwards(u32, peer.flight[0 .. peer.n - i], peer.flight[i..peer.n]); + peer.n -= i; + } + + /// Start the peer afresh: it lost its state, or never had one. + pub fn reset(peer: *Peer) void { + var holes = peer.holes; + holes.clearRetainingCapacity(); + peer.* = .{ .holes = holes }; + } +}; + +/// A delta applied: its version, and what its authority sent beside it. +pub const Applied = struct { seq: u32, extra: []const u8 }; + +/// What the dump keeps of a terminal beside its emulator, by name as every +/// dump is (src/walk.zig, through the core's `Term.State`). +pub const Parts = struct { + reply: []const u8 = "", + reply_dropped: u32 = 0, + mouse_cell: ?Coordinate = null, + petscii: bool = false, + /// The view's top row, counted from the top of the history. + view: usize = 0, + phase: Prompt.Phase = .none, + started: u32 = 0, + prompts: u32 = 0, + declined: u32 = 0, + continuation: bool = false, + lost: bool = false, + finished: ?Prompt.Finished = null, + out_start: ?Coordinate = null, + out_end: ?Coordinate = null, + + /// A cell's place on a screen (ghostty's `Coordinate`, as it dumps). + pub const Coordinate = extern struct { x: u16 = 0, y: u32 = 0 }; +}; + +/// What reading its text can fail with. +pub const TextError = error{ OutOfMemory, WriteFailed, UnknownPoint }; + +/// The entries, as `term.ops` gives them. An error set named here is what +/// the core's callers name (the tape's `Failure` reads `open`'s, the text +/// readers' are edit.zig's); `anyerror` where the core only passes one on +/// or reports it. Each takes the handles above +/// (none is made without a terminal module: the core asks `Term.ops` +/// first). +pub const Ops = struct { + // ---- lifecycle ---- + /// A new terminal, `cols` by `rows`, allocated with `gpa` (its own from + /// then on). + open: *const fn (gpa: std.mem.Allocator, cols: u16, rows: u16) error{ OutOfMemory, InvalidValue }!*State, + /// It and what it holds, freed. + close: *const fn (s: *State, gpa: std.mem.Allocator) void, + /// When its next kitty animation frame is due (ms on the core's clock), + /// as its last drawn frame left it; null when nothing plays. + due: *const fn (s: *const State) ?u64, + /// Loaded from a dump without its shell: its program's modes reset, its + /// history marked off from what the next shell prints. + revive: *const fn (s: *State) void, + /// The PNG resize workers kitty images are decoded with, started and + /// stopped with the host. + start: *const fn (gpa: std.mem.Allocator) void, + stop: *const fn () void, + /// The allocator it was opened with. + gpa: *const fn (s: *const State) std.mem.Allocator, + + // ---- the dump and the digest (`Term.State`'s walk hooks) ---- + /// Its screen into the replay digest (`view`: where its view is too). + digest: *const fn (s: *const State, h: *std.hash.Wyhash, view: bool) void, + /// What the dump keeps of it beside its emulator. + parts: *const fn (s: *const State) Parts, + /// Its emulator as the dump keeps it (ghostty's snapshot); `slim`: its + /// size alone (a join's dump, its first delta replaces it). + snapshot: *const fn (s: *const State, gpa: std.mem.Allocator, w: *std.Io.Writer, slim: bool) anyerror!void, + /// `snapshot`'s bytes and `parts` back into a new terminal. + load: *const fn (gpa: std.mem.Allocator, snapshot: []const u8, parts: *const Parts) anyerror!*State, + + // ---- output and view ---- + /// One read of its program's output (`Told` says where the tracked + /// rows went). + feed: *const fn (s: *State, bytes: []const u8, track: []const i32, rows: []i32, erased: []bool) Told, + // A null handle: what a pane without a terminal is told (all zero). + grid: *const fn (s: ?*const State) Grid, + viewTo: *const fn (s: *State, at: ?usize) void, + scroll: *const fn (s: *State, delta: i32) void, + follow: *const fn (s: *State) void, + resize: *const fn (s: *State, cols: u16, rows: u16, later: bool) void, + resizeDeferred: *const fn (s: *State) bool, + cellPixels: *const fn (s: *State, w: u32, h: u32) void, + replies: *const fn (s: *State) []const u8, + + // ---- input ---- + key: *const fn (s: *State, k: plain.Key, out: *std.Io.Writer) error{WriteFailed}!void, + mouse: *const fn (s: *State, buf: *[64]u8, action: MouseAction, button: ?MouseButton, mods: MouseMods, col: i32, row: i32, any_pressed: bool) []const u8, + wheel: *const fn (s: *State, buf: *[64]u8, turn: MouseButton, col: u16, row: u16, mods: MouseMods) ?[]const u8, + paste: *const fn (s: ?*const State, text: []u8) [3][]const u8, + modes: *const fn (s: ?*const State) Modes, + promptMoves: *const fn (s: *State, row: i32, col: i32) ?Moves, + + // ---- prompt and commands ---- + prompt: *const fn (s: ?*State) Prompt, + commandOutput: *const fn (s: ?*State, gpa: std.mem.Allocator, max_rows: usize) error{OutOfMemory}!CommandOutput, + endOutputHere: *const fn (s: *State) void, + + // ---- text ---- + scrollback: *const fn (s: ?*State, gpa: std.mem.Allocator) error{ OutOfMemory, WriteFailed }![]const u8, + scrollbackLen: *const fn (s: ?*State) usize, + textRows: *const fn (s: *State, alloc: std.mem.Allocator, scratch: std.mem.Allocator) TextError!Rows, + viewport: *const fn (s: *State, arena: std.mem.Allocator, cut: bool) TextError![]const []const u8, + /// Its rows `first` and the `count` after it (from the top of its + /// history) as text, a prompt's own cells cut off: `arena`'s. + editRows: *const fn (s: *State, arena: std.mem.Allocator, first: usize, count: usize) (TextError || error{ NoRow })![]const []const u8, + /// How much of its row `row` (from the top of its history) the prompt + /// it starts with is; null for a row no prompt starts. + promptCut: *const fn (s: *State, row: i32) ?PromptCut, + markRead: *const fn (s: *State) void, + /// What a predicted echo reads of cell `x`, `y` of its active area. + echoCell: *const fn (s: *const State, x: u16, y: u16) ?EchoCell, + + // ---- the pager ---- + /// `raw`, a program's output, as a terminal reads it: its text and its + /// SGR spans, every other control dropped. `gpa`'s. + page: *const fn (gpa: std.mem.Allocator, raw: []const u8) error{OutOfMemory}!Page, + /// The filter a +Pager's spans are drawn through (`spanColor`). + filter: *const fn (ink: *const Ink, palette: *FilterPalette) Filter, + spanColor: *const fn (f: *Filter, color: Color, is_bg: bool) Color, + + // ---- draw ---- + /// Its view's rows, `rows.len` of them, `cols` cells each, into + /// `cells`: each cell's style in the theme's colours (through the + /// filter when `filtered`), its bytes and width. + paint: *const fn (s: *State, ink: *const Ink, palette: *FilterPalette, filtered: bool, cols: u16, cells: []Painted, rows: []PaintedRow) void, + /// Its kitty images over the body's rows, appended to `out`, and their + /// placeholder cells blanked in `frame` (`frame_cols` wide). + images: *const fn (s: *State, gpa: std.mem.Allocator, at: ImagesAt, out: *std.ArrayList(plain.Placement), frame: []plain.Cell, frame_cols: u16) void, + petscii: *const fn (s: ?*const State) ?bool, + togglePetscii: *const fn (s: *State) void, + hasImages: *const fn (s: ?*const State) bool, + + // ---- its replicas ---- + encoder: *const fn (gpa: std.mem.Allocator) error{OutOfMemory}!*Encoder, + encoderFree: *const fn (e: *Encoder) void, + track: *const fn (gpa: std.mem.Allocator) error{OutOfMemory}!*Track, + /// A peer's track of it let go (`s` null: it is gone). + untrack: *const fn (t: *Track, gpa: std.mem.Allocator, s: ?*State) void, + /// What a peer is owed of it, a delta against what the peer was sent. + encode: *const fn (s: *State, e: *Encoder, t: *Track, peer: *Peer, out: *std.Io.Writer) anyerror!bool, + /// Rows of it a replica holds as holes. + encodeRows: *const fn (s: *State, e: *Encoder, t: *Track, lo: u64, hi: u64, out: *std.Io.Writer) anyerror!void, + wasRead: *const fn (s: *const State) bool, + clearRead: *const fn (s: *State) void, + replica: *const fn (gpa: std.mem.Allocator) error{OutOfMemory}!*Replica, + replicaFree: *const fn (r: *Replica, gpa: std.mem.Allocator) void, + /// The absolute row its replica's active area begins at. + replicaTop: *const fn (r: *const Replica) u64, + /// History rows `lo..hi` it does not hold. + missing: *const fn (r: *const Replica, lo: u64, hi: u64, out: *std.ArrayList([2]u64), gpa: std.mem.Allocator) error{OutOfMemory}!void, + apply: *const fn (s: *State, r: *Replica, bytes: []const u8) anyerror!Applied, + applyRows: *const fn (s: *State, r: *Replica, bytes: []const u8) anyerror!void, + shown: *const fn (s: *State, r: *const Replica) [2]u64, + blank: *const fn (s: *State, r: *const Replica, lo: u64, hi: u64) void, + dumpScreen: *const fn (s: *State, w: *std.Io.Writer) error{WriteFailed}!void, +}; -- cgit v1.3