# The text pane as a library: `pardes-editor` > the basic text pane of pardes as a library … embeddable but taken from > pardes … the end goal is to make the sketch a live environment for > iterating and experimenting Decided 2026-11-17 on the coordinator's leans (survey: `.scratch/sketch/reports/editor-lib.md`); built the same day. One source of truth: the library runs the functions pardes runs, compiled from the same files with `pardes_config.lib` set; nothing is copied for it. ## The calls, as built `library()` exports `pardes-editor` (src/lib_editor.zig) to a package that passes `.editor = true` (it then fetches uucode, mvzr and vaxis, of which it compiles the grapheme width); a `pardes-syntax` package fetches what it did. The module has `pardes-syntax` in it as `.syntax`. - `Editor(cap)`: `key(a, syn, k)`, `run(a, syn, action)`, `selectRegex(a, pattern, how)`, `setText(a, bytes)`, `replace(a, from, to, with, join)`, `setRegister(a, name, value)` give an `Outcome`: `done`, `pending`, `unbound: Key`, `action: Action` (the caller's), `refused: Refusal` (`text_full`, `registers_full`, `selections_full`, `out_of_memory`). Read back: `read(buf)`, `bytes(a)`, `len()`, `ranges(a, &out)`, `mode()`, `pending()`, `register(a, name)`, `revision`. `load(bytes)` starts a text over. - `Language` (syntax.zig's run-time grammar: `ts`, `ext`, query sources) and `Syntax` (`parse`, `colors`, `forget`): derived, rebuilt when `revision` moves; `forget` at a reload drops the handed-in grammars. - `a` is any allocator the call may drop after it; `syn` a `?*Syntax`. - `replace` rewrites the bytes `from..to` as one step to undo, the ranges following as an edit moves them (one inside the bytes goes to their start: edit.replaceBytes, one sam op the ranges are mapped through as `&`'s are); `join` makes it part of the step before instead: a drag passes false on its first frame and true on the rest, and one undo takes it all back. **The tree handed in** (`syn`): the walks read a `Syntax`, which keeps its `lang` (the last `parse`'s, or set), the tree, parsed on the first walk after `revision` moves, and helix's object_selections, Alt-o's history for Alt-i to go back by (the page allocator: it holds nothing of the code that made it). With it, Alt-o, Alt-i, Alt-n, Alt-p, Alt-a, Alt-I, Alt-e, Alt-b and `]f` and kin are the text's and run in the library on pardes's own nodeSelect and objectJump, and `mif` and kin find the `Language`'s `textobjects`; with no `lang` they do nothing, as in a text without a grammar. Without `syn` they come back as actions (`mif` does nothing). An argument, not a field of the value: the tree holds pointers into the grammar's code, and an argument is the least code (the context of the call carries it, `Editor.syntax`; no interface). `normal.nodeTree` is the one seam: a file's `fileTree` in pardes, the `Syntax` in the library, `Editor.Tree` what both give. ## The flat form, as built Fields of `Editor(cap)` (defaults: text 64 KiB, undo and redo 256 KiB each, registers 16 KiB, 256 selections; about 1.2 MiB at `.{ .text = 128 KiB, .undo = 512 KiB }`): | field | what | |---|---| | `text`, `front`, `back` | a gap buffer; the gap is put where the key's edit ended, so typing changes the page it lands in | | `revision` | one more a key that changed the text | | `cursor` | Text's own fields by name (cells, anchor, mode, select, pending parse state, find, sticky column, `last_edit`) | | `sels` | the other ranges, `[cap.selections - 1]SelRange` | | `undo`, `redo` | byte rings of `[len][snapshot][len]`, the oldest dropped to make room; a key thaws the undo top and the two newest redos (two tell a redo from an edit forgetting them all) | | `registers`, `registers_len`, `last_search` | every register's values as records | **At capacity** a key is refused whole: `keep` checks text, selections and registers before it writes anything. A ring never refuses: it drops its oldest snapshots, never part of one (an undo ring holds at least one whole text, checked at compile time). **Measured** (test/lib `zig build bench`, a text in C's shape, a key typed into its middle, 200 keys, this machine): a key at 1, 16, 64 KiB is 13, 173 and 692 µs in Debug (270k, 3.1M, 12.2M instructions) and 0.7, 7.7 and 30 µs in ReleaseFast: the 64 KiB key is 4% of a 16 ms frame in Debug. A typed character changes 2 of the value's 4 KiB pages on average (the text's and the cursor's); the first after a jump moves the gap, 3, 5 and 10 at most. A full parse is 0.2, 3.1 and 11.3 ms (tree-sitter is built optimised in every mode): once a changed key, not a frame, so no incremental re-parse. A package taking the editor (test/lib) compiles cold in 6.4 s (126e9 instructions), an edit of its own file in 0.95 s plainly and 0.09-0.11 s under `--watch -fincremental`. pardes itself: core-test's full recompile 238.8e9 instructions before and after; the typing cells of `zig build perf` (50k lines, whole runs) 0.13-0.29% fewer instructions; codeloc's far share 0.5666 before, 0.5658 after. The Debug core-test binary grew from 353 to 381 MB (shell-test's 448 to 454 MB): not looked into. ## The seam, as built - `Editor` (src/Editor.zig) is gathered per call: `p.editor()` in pardes, `Live.context` in the library. No field of `Pardes`, `View` or `Text` moved, so the dump is as it was (an embedded field would have renamed `registers` in it). - normal.zig and edit.zig: 57 functions take `e: Editor` (10 and 47); the 22 left on `*Pardes` are the core's (the pointer's selections, the clipboard, a terminal's rows, prompts, jump labels, the file's tree); 119 calls outside hand `p.editor()`. `textAction` has the text's 58 roles, `executeNormalAction` the core's 34, `textRole` says which. `textKey` is the mode dispatch keys.zig and the library share; `runAction` and `selectByRegex` are the parts of handleNormal and applySelRegex the library calls. - `if (comptime Editor.lib)` in: `nodeTree` (the parse handed in), `Text.pane` (null, inline, so what a pane does is not compiled), flatSurface, editText, setEditTextSpan, paneCursorLines, pushUndo, undoStep (the body's characters and undo are its own), bodyFile and filePane (none), replaySels, Esc and `*` (the text's part), setYank (`+` is a plain register), handleNormal (the core's roles come back), Editor.reportError (`failed`), and config.zig's check of the builtins' leader paths. **Held to parity**: `zig build hxlib` runs every hxdiff case on the library: 538 of 658 against helix's goldens and 618 of 738 against the file pane, 0 mismatches, the rest reaching an action the caller does (n and N 64, macros and `.` 14, views 34, gw 7, an insert-mode page key); it hands each case a `Syntax` with no grammar, as a case's text has none, so the walks' one case (expand_node) is compared. What it found was fixed: paneCursorLines gave the library no lines; `s` keeps its pattern in `/`. ## Left out, and why Files, commands, builtins, LSP, look/exec, prompts, views, sam's Edit, terminals, replicas, dumps. Macros and `.`: their log is keys.zig's (the core's dispatcher) and recording replays through it; keeping them meant moving it, more code than leaving them out. `n`/`N`: pardes decides between the look ring, a query's places and the register, the core's. Tree indents: they read the file's tree through `fileTree`, not `nodeTree`; a new line's indent in the library is the plain one. Alt-o's history across calls lives in the `Syntax`, so a caller that makes one per call (a sketch's `update` sees only State) has Alt-i go to the first child instead, as helix does with no history. ## An editor in a sketch (not compiled against sketchbook) ```zig const sk = @import("sketch"); const pe = @import("pardes-editor"); const Ed = pe.Editor(.{ .text = 32 * 1024, .undo = 128 * 1024 }); extern fn tree_sitter_mydsl() *const pe.syntax.ts.Language; // the DSL's parser.c, in build.zig const dsl_highlights = @embedFile("highlights.scm"); pub const State = struct { ed: Ed = .{}, run: sk.Request(u32) = .{}, hear: sk.Request([2]usize) = .{}, drag: ?Drag = null }; const Drag = struct { at: u32, from: f32, value: f64, moved: bool = false }; /// The parse: derived, so not in State; a module's var, as `update` sees only /// State (a reload starts it again with the code; the old tree is leaked). var syn: pe.Syntax = .{}; fn dsl() pe.Language { return .{ .name = "mydsl", .ext = ".mydsl", .ts = tree_sitter_mydsl(), .highlights = dsl_highlights }; } /// printables from `text` events only (a key_down comes with them too) fn toKey(e: sk.Event) ?pe.Key { return switch (e.kind) { .text => .{ .cp = @intCast(e.value), .text = utf8(e.value) }, // the codepoint's bytes, kept in State or a static .key_down => switch (e.key()) { .escape => .{ .cp = pe.Key.escape }, .enter => .{ .cp = pe.Key.enter }, .backspace => .{ .cp = pe.Key.backspace }, .left => .{ .cp = pe.Key.left }, // and the rest of the specials else => null, // ctrl and alt chords: `.{ .cp = letter, .ctrl = mods & ctrl != 0 }` }, else => null, }; } pub fn update(s: *State, in: *const sk.Input) void { var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator); // no allocator reaches State defer arena.deinit(); const a = arena.allocator(); syn.lang = dsl(); for (in.events) |e| { const k = toKey(e) orelse continue; if (k.cp == pe.Key.enter and k.ctrl) { s.run.send(s.ed.revision); continue; } // mine, before helix switch (s.ed.key(a, &syn, k)) { // Alt-o, Alt-i... run here, on `syn` .action => |act| if (act.role == .select_regex) {}, // open my prompt; then s.ed.selectRegex(...) .refused => {}, // the DSL is full: say so else => {}, } // "hear this subexpression": after Alt-o or Alt-i, the primary range if (k.alt and (k.cp == 'o' or k.cp == 'i')) { var out: [pe.max_selections]pe.Selection = undefined; const got = s.ed.ranges(a, &out) catch continue; const r = out[got.primary]; s.hear.send(.{ @min(r.anchor, r.head), @max(r.anchor, r.head) }); } } // "drag a number": the number token under the pointer, rewritten each // frame of the drag, the whole drag one step to undo if (in.mouse.pressed) s.drag = .{ .at = byteUnder(s, in.mouse), .from = in.mouse.x, .value = 0 }; // byteUnder: my layout's if (s.drag) |*d| if (in.mouse.down) { const tree = syn.parse(a, &s.ed, dsl()) orelse return; const n = tree.rootNode().descendantForByteRange(d.at, d.at) orelse return; if (!std.mem.eql(u8, n.kind(), "number")) return; const text = s.ed.bytes(a) catch return; if (!d.moved) d.value = std.fmt.parseFloat(f64, text[n.startByte()..n.endByte()]) catch return; var buf: [32]u8 = undefined; const num = std.fmt.bufPrint(&buf, "{d}", .{d.value + (in.mouse.x - d.from) * 0.01}) catch return; _ = s.ed.replace(a, n.startByte(), n.endByte(), num, d.moved); // the first frame a step, the rest joined d.moved = true; } else { s.drag = null; }; } pub fn draw(s: *const State, f: *sk.Frame) void { const a = f.scratch; const text = s.ed.bytes(a) catch return; const colors = pe.Syntax.colors(a, &s.ed, dsl(), 0, text.len) catch &.{}; _ = syn.parse(a, &s.ed, dsl()); // the tree, for sizes by node, an inline Typst block... // lines, coloured by `colors[i]`; then the ranges and a caret var out: [pe.max_selections]pe.Selection = undefined; const got = s.ed.ranges(a, &out) catch return; for (out[0..got.n], 0..) |r, i| drawRange(f, text, r, i == got.primary); // f.fill under the bytes, f.text over _ = colors; } ```