# 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, k)`, `run(a, action)`, `selectRegex(a, pattern, how)`, `setText(a, bytes)`, `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. ## 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: `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: 537 of 658 against helix's goldens and 617 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, expand_node 1). 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-sitter walks (Alt-o and kin, `]f`) and tree indents: they read the file's kept tree; the library parses in `Syntax`, so they come back as actions (a later step: hand the tree in the context). ## 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) = .{} }; pub const Session = struct { syn: pe.Syntax = .{}, arena: std.heap.ArenaAllocator = .init(std.heap.page_allocator) }; /// 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(); 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(arena.allocator(), k)) { .action => |a| if (a.role == .select_regex) {}, // open my prompt; then s.ed.selectRegex(...) .refused => {}, // the DSL is full: say so else => {}, } } } pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void { const a = f.scratch; if (f.in.jumped) ss.syn.forget(); // new code: the grammar's pointers are stale const lang: pe.Language = .{ .name = "mydsl", .ext = ".mydsl", .ts = tree_sitter_mydsl(), .highlights = dsl_highlights }; const text = s.ed.bytes(a) catch return; const colors = pe.Syntax.colors(a, &s.ed, lang, 0, text.len) catch &.{}; _ = ss.syn.parse(a, &s.ed, lang); // 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; } ```