diff options
Diffstat (limited to 'docs/next-editor.md')
| -rw-r--r-- | docs/next-editor.md | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/docs/next-editor.md b/docs/next-editor.md new file mode 100644 index 00000000..af0ee537 --- /dev/null +++ b/docs/next-editor.md @@ -0,0 +1,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; +} +``` |
