summaryrefslogtreecommitdiff
path: root/docs/next-editor.md
blob: af0ee537ddb7f58065049258b174323332dd0358 (plain) (blame)
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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
# 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;
}
```