//! The terminal as the core sees it (docs/next-terminal.md, Phase 0): the //! entries the core calls and the plain records they take and give. A //! terminal pane holds a `*State` the core never looks into: what it knows //! of one it is told here, as numbers, bytes and text. The emulator //! (ghostty-vt) and what it brings stay behind this file, in src/term/; //! this is the one file outside it that names a file inside it (and so //! the one place Phase 1 turns into the module's registration). const std = @import("std"); const terminal = @import("term/terminal.zig"); /// A terminal pane's emulator, its parse and what pardes keeps beside it. pub const State = terminal.State; // ---- lifecycle ---- /// A new emulator, `cols` by `rows`, allocated with `gpa` (its own from /// then on). pub const open = terminal.open; /// Its emulator and what it holds, freed; the kitty images' caches were /// `gpa`'s. pub const close = terminal.close; /// 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. pub const due = terminal.due; /// Loaded from a dump without its shell: its program's modes reset, its /// history marked off from what the next shell prints. pub const revive = terminal.revive; /// The PNG resize workers kitty images are decoded with, started and /// stopped with the host. pub const start = terminal.TerminalImages.start; pub const stop = terminal.TerminalImages.stop; // ---- output and view ---- /// One read of its program's output (`Told` says where the tracked rows /// went). pub const feed = terminal.feed; /// Where the view and the cursor are (`Grid`). pub const grid = terminal.grid; /// Its view to a row of its history, or onto its output (null). pub const viewTo = terminal.viewTo; /// Its view moved by a number of rows (negative scrolls back). pub const scroll = terminal.scroll; /// Its view back onto its output. pub const follow = terminal.follow; /// Its grid reflowed, now or when `resizeDeferred` makes it. pub const resize = terminal.resize; pub const resizeDeferred = terminal.resizeDeferred; /// Its cells' size in pixels (kitty graphics, CSI 14/16 t). pub const cellPixels = terminal.cellPixels; /// What it answered its program since the last call, to be written to its /// pty. pub const replies = terminal.replies; /// 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, }; /// 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 }; // ---- input ---- /// One key for its program, as the program's keyboard protocol and modes /// ask for it, written out. pub const key = terminal.key; /// One mouse event for its program, as the mode and format it set ask for /// it; empty when the program does not hear of it. pub const mouse = terminal.mouse; /// A wheel turn for its program; null when the wheel is not the program's. pub const wheel = terminal.wheel; /// A paste as xterm makes one: three parts, the text between the brackets /// when the program set 2004. pub const paste = terminal.paste; /// The modes its program set that the core decides by (`Modes`). pub const modes = terminal.modes; /// How far left or right a click on the prompt line moves the shell's /// cursor, at the prompt the cursor is at. pub const promptMoves = terminal.promptMoves; /// The key a frontend read (Event.zig). pub const Key = @import("Event.zig").Key; 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, }; // ---- prompt and commands ---- /// Where its shell is in its command cycle (`Prompt`). pub const prompt = terminal.prompt; /// What the newest finished command printed (`CommandOutput`), read from /// at most so many rows above its end. pub const commandOutput = terminal.commandOutput; /// The shell exited in the middle of a command: its output ends at the /// cursor. pub const endOutputHere = terminal.endOutputHere; /// 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: enum { none, prompt, input, running } = .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: ?struct { seq: u32, status: ?i32 } = 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, }; /// 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, }; // ---- text ---- /// Its whole scrollback as plain text, logical lines (rows it wrapped /// joined again), ending in a newline: what its body reads and Save /// writes. The caller's. pub const scrollback = terminal.scrollback; /// How long `scrollback` would be, counted without keeping it. pub const scrollbackLen = terminal.scrollbackLen; /// Its rows from the top of its history as text, a prompt's own cells cut /// off (`Rows`). pub const textRows = terminal.textRows; /// The rows its view shows as text, prompts cut off or not. pub const viewport = terminal.viewport; /// How many bytes of one of its rows, as `viewport` and `textRows` give it /// uncut, are the prompt it starts with. pub const promptPrefix = terminal.promptPrefix; /// A step read its rows: its replicas must hold them for the step's /// replay. pub const markRead = terminal.markRead; /// 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, };