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
|
# 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`). One source of truth: the library
runs the functions pardes runs, compiled from the same files; nothing is
copied or rewritten for it.
## The calls
`library()` in build.zig exports `pardes-editor` (src/lib_editor.zig) beside
`pardes-syntax`, only when the depending package asks for it
(`.editor = true`): a `pardes-syntax` consumer fetches and compiles what it
did. `pardes-editor` re-exports `pardes-syntax` as `.syntax` (a file belongs
to one module, so a package imports one of the two).
```zig
const pe = @import("pardes-editor");
const Ed = pe.Editor(.{}); // capacities in the type
s.ed = .{}; // or Ed.init(text) once
switch (s.ed.key(scratch, k)) { // parse + run, as a pane does
.done, .pending => {},
.unbound => |k| ..., // helix binds nothing to it
.action => |a| ..., // bound, but the app's: view, `:`, LSP, `/`, `s`...
.refused => |why| ..., // .text_full, .registers_full, .selections_full
}
s.ed.run(scratch, action) // a role the app built, or one it took back
s.ed.selectRegex(scratch, pattern, .select)
s.ed.text(scratch) s.ed.ranges(&out) s.ed.mode() s.ed.pending()
s.ed.setText(scratch, bytes) // one undo step
```
`scratch` is any allocator the call may use and drop (a frame's arena);
nothing outlives the call in it.
## The stored form, flat
`Editor(cap)` is plain data, every capacity in its type: valid after a
memcpy, after the code that made it is unloaded, with no pointer and no
allocator. Defaults: text 64 KiB, undo and redo 256 KiB each, registers 16
KiB, selections 256.
- **text**: a gap buffer, `front` bytes at the start and `back` at the end
of `[cap.text]u8`. The gap is put where the last edit was, so a typed
character changes the page it lands in and the stored ints, not the
pages after it (a shift would rewrite every page from the cursor on).
- **selections and mode**: Text's own fields, copied by name: the primary's
cells, its anchor, the other ranges (`[cap.selections - 1]SelRange`), the
modal state (`normal`, `select`, `mode`, find, sticky column, `last_edit`).
- **undo, redo**: two byte rings of whole-text snapshots with their cursor,
as Text keeps an own text's (`remember`, `step`), the oldest dropped when
full. A key thaws only each ring's top: `remember` compares with it,
`step` pops it.
- **registers**: `[cap.registers]u8` of records (name, values per range),
`last_search`.
**Thaw and freeze.** Each call copies the value into the structures pardes
edits (a `Text` of what `.body` with its characters its own, `Registers`) in
`scratch`, runs pardes's code on them, and writes them back. That is
O(document) a key, right for a DSL of a few KiB; the ceiling is marked
`// ponytail:` with the way up (a shared Buffer under File and the
library, the survey's R3).
**At capacity** the key is refused: freeze checks every part fits before it
writes any, the value is left as it was before the key, and the outcome is
`.refused`. Nothing is truncated. A ring drops its oldest snapshots, never
part of one; an undo ring is at least the text's capacity, so a text that
fits is a snapshot that fits.
**Syntax is derived**, never stored: `pe.Syntax` is rebuilt from the bytes
and a `pe.Language` handed in at run time (its `TSLanguage` and query
sources, syntax.zig's run-time `Spec`), dropped at a reload.
## The seam in pardes
- **R1.** `Editor` (src/Editor.zig): the context an edit runs with, gathered
per call (`p.editor()`): the allocators, pointers to the registers, the
named register and the replay's state (`multi_*`), the retired text, and
`p: *Pardes` (void in the library). The fields stay where they are on
`Pardes` and its view: no dump changes, registers kept across an Upgrade.
The embedded `ed: Editor` field with `@fieldParentPtr` would have moved
`registers` in the dump (fields are matched by name) and lost them at an
Upgrade from an older build.
- **R2.** The text functions of normal.zig and edit.zig take `e: Editor`;
`executeNormalAction` splits into `run` (the text's roles, returning the
rest) and the core's switch.
- **Library build.** `pardes_config.lib` is true only in `library()`. The
routing functions branch on it at compile time: `Text.pane()` is null, a
body's characters are its own, its undo is Text's own. Zig analyses only
the branch taken, so the library never compiles panes, tags or LSP.
## Not in the library
Files, commands, builtins, LSP, look/exec, prompts and their UI, view and
scroll keys (`zz`, C-f, `gt`), the clipboard (`+` is a plain register the
app fills), sam's Edit, terminals, replicas, dumps; macros and `.` (their
recording lives in keys.zig, the core's dispatcher: keeping them would mean
moving it, more code than leaving them out). These come back as `.action`.
## What a dump from before loads as
The same: no field of `Pardes`, `View` or `Text` changes name or type.
|