1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
# 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;
}
```
|