summaryrefslogtreecommitdiff
path: root/docs/next-editor.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 07:44:55 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commit0db7861d9da09e059fa1b9e40fff5cd52add27f2 (patch)
tree6e95dfa36e07b3234b1d5cdb990b11f95c184a3f /docs/next-editor.md
parentd3742ddf2b3a85eb3935cb35e958fa27f1293a6b (diff)
parentdee94c740bdaea61ff35b4e0a7f1d2815c9ee441 (diff)
downloadpardes-0db7861d9da09e059fa1b9e40fff5cd52add27f2.tar.gz
pardes-0db7861d9da09e059fa1b9e40fff5cd52add27f2.zip
integration: the text pane a library (pardes-editor), with the GPU move, the terminal, the plumber and the diff work
A merge of pardes-next (wmrtztwl) and editor-lib (rlumrxuq), no conflicts. Gated against the baseline of the integration line (.scratch/sketch/gpu/mbase): the merge with the library before its follow-up, in full: frame corpus 77/77 identical in Debug and in ReleaseFast, the gated window -0.019% instructions (threshold 0.5%), unit-test on gui 1584/1592 with no failure the baseline has not; this merge: corpus 77/77 in Debug, unit-test on gui 1584/1592, on tui core-test 811/950 (139 skipped), shell-test 990/993, lib-test, hxdiff 658, parity 738, hxgolf 124, hxlib 538 and its parity 618, all 0 mismatches, replicas pass. Co-Authored-By: Claude Fable 5.2 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
Diffstat (limited to 'docs/next-editor.md')
-rw-r--r--docs/next-editor.md217
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;
+}
+```