From 55dbff5aced5c62f47be39fbc01276b6e36d7dd5 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 05:37:59 -0300 Subject: docs/next-editor.md: the text pane as a library, the record before the code (.scratch/sketch/reports/editor-lib.md, the coordinator's leans): the calls as they will ship (key, run, selectRegex, text, ranges, mode, pending, setText; Outcome done, pending, unbound, action, refused), the flat stored form and its capacities (a gap buffer for the text, Text's fields by name, two rings of snapshots, registers as records), thaw and freeze O(document) a key, a key refused whole at capacity, syntax derived from a language handed in at run time, the seam (a context of pointers gathered per call, not an embedded field: the dump matches fields by name), what is left out and why, and that a dump from before loads as it did --- docs/next-editor.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 docs/next-editor.md diff --git a/docs/next-editor.md b/docs/next-editor.md new file mode 100644 index 00000000..c08a63e7 --- /dev/null +++ b/docs/next-editor.md @@ -0,0 +1,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. -- cgit v1.3