diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/next-editor.md | 105 |
1 files changed, 105 insertions, 0 deletions
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. |
