summaryrefslogtreecommitdiff
path: root/docs/typ
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-31 06:28:48 -0300
committerGabriel Schneider <[email protected]>2026-10-31 06:28:48 -0300
commita479792a1ab2b593642d7f648194bfa23ce01dba (patch)
tree96ddee7d879a9084daa07db43b0b7910b072a785 /docs/typ
parente179cc44fe5060c76a5b00c41e53f11209f5acd9 (diff)
parent4c761893e5b3fdae422622cfa02104ab36633045 (diff)
downloadpardes-a479792a1ab2b593642d7f648194bfa23ce01dba.tar.gz
pardes-a479792a1ab2b593642d7f648194bfa23ce01dba.zip
Merge the upstream daemon and replicated client/server refactor
Diffstat (limited to 'docs/typ')
-rw-r--r--docs/typ/building.typ79
-rw-r--r--docs/typ/builtins-gui.json5
-rw-r--r--docs/typ/builtins-tty.json5
-rw-r--r--docs/typ/cheatsheet.typ5
-rw-r--r--docs/typ/guide.typ27
-rw-r--r--docs/typ/reference.typ80
6 files changed, 136 insertions, 65 deletions
diff --git a/docs/typ/building.typ b/docs/typ/building.typ
index d551c251..d8c089f6 100644
--- a/docs/typ/building.typ
+++ b/docs/typ/building.typ
@@ -1,6 +1,6 @@
// Building pardes, for contributors: platforms, options, tests, the
// release gates and sending patches, then how the pieces fit: the core
-// and its shells, the threads, detached sessions, the 9P engine, the
+// and its shells, the threads, the daemon and its sessions, the 9P engine, the
// listeners and mounts.
#import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs
@@ -19,7 +19,7 @@ builds MuPDF and is on by default (`-Dmupdf=false` drops it). 9P over QUIC
[`zig build`], [the terminal shell and the SDL window together, *installed into `~/.local/bin`* (`pardes`, `pardes-gui`, and `pardes-v9fs`, the #word("Tty9p") helper)],
[`zig build -Dplatform=tty`], [the terminal shell alone],
[`zig build -Dplatform=gui`], [the SDL3 window alone],
- [`zig build web -Dplatform=web -Dtarget=wasm32-freestanding -Ddump=<dump.zon>`], [a freestanding wasm core plus vanilla JavaScript (`docs/web.md`)],
+ [`zig build web -Dplatform=web -Dtarget=wasm32-freestanding -Ddump=<file>`], [a freestanding wasm core plus vanilla JavaScript (`docs/web.md`)],
[`zig build -Dplatform=macos`], [an AppKit and CoreText app over a static `libpardes.a` (`docs/macos.md`)],
[`zig build -Dplatform=esp32p4`], [a freestanding riscv32 editor object for the ESP32-P4, with a 384 KiB heap],
)
@@ -31,7 +31,8 @@ leaves that copy out. Zig 0.17 keeps the prefix from the build script, so
so always pass `-Dplatform` while developing. Test, benchmark and run steps build what they need
without installing. `pardes --version` prints `pardes <version>` (from
`build.zig.zon`), plus the commit for release builds and the `~/.local`
-install; `pardes --help` lists every flag.
+install, and on a second line the build's semantics hash, which a replica
+must share with its session; `pardes --help` lists every flag.
The ESP32-P4 firmware is linked in the sibling `../05-zig-p4` toolchain,
which needs ESP-IDF register headers: after building the editor object
@@ -58,7 +59,7 @@ there; its namespace is in `src/esp32p4_gpio.zig`.
[`-Dprebuilt-shaders`], [bool: embed the committed SPIR-V; on for a bare `zig build`, off with `-Dplatform`; `zig build shaders` refreshes it with glslc],
[`-Dtracy`], [path to a Tracy checkout; off],
[`-Dmacos-identity`], [codesigning identity for `pardes.app`; `-` (ad hoc)],
- [`-Ddump`], [a `dump.zon` to embed in the web shell],
+ [`-Ddump`], [a Dump to embed in the web shell],
[`-Dtest-filter`], [run only tests whose name contains it; a filter that matches nothing fails],
[`-Dtest-rebuild`], [bool: fresh Zig test compilation],
[`-Dhelix-harness`], [reference executable for live differential tests; `HX_HARNESS`, else `hx-harness` on `PATH`],
@@ -177,8 +178,9 @@ Code map: `src/panes.zig` and the pane kinds it names (`src/File.zig`,
`src/Terminal.zig`, ...), `src/layout.zig`, `src/fs.zig` (host access,
mounts and resolution) and `src/pardes.zig` (input), with one file per
thing beside them (`edit.zig`, `normal.zig`, `look.zig`, `exec.zig`,
-`mouse.zig`, ...). `src/ninep/` is the control tree, `src/detached/` the
-wire, the detached core and the frontend client, `src/lsp/` the
+`mouse.zig`, ...). `src/ninep/` is the control tree, `src/daemon.zig` the
+per-user daemon and a terminal's stub, `src/detached/wire.zig` the input
+wire a remote client will speak, `src/lsp/` the
language-server client; `test/` holds harnesses, goldens and helix cases,
`build/` the snapshot suite's build step.
@@ -197,26 +199,55 @@ reading the live core, and a request id, the pane's serial and (for an
edit) the file's revision reject a stale reply. A process that never calls
`turn.start` (the tests, the ESP32-P4, the browser) has no second thread.
-== Detached sessions
+== The daemon and detached sessions
-One poll loop in `src/detached/server.zig` owns core mutation, frontend
-connections, pty I/O and file watches. The frontend socket is
-`pardes-detached-<name>.sock` beside the session's 9P socket; a second
-session cannot take a live name. Up to 32 frontends attach; frames go to
-every one, while clipboard reads, browser opens and #word("Detach") go to
-the frontend that asked (else the first attached). Frames are full grids
-or changes against what each frontend last received, never queued: a
-frontend with unsent bytes skips that frame, and one that stops draining
-past 1 MiB of control backlog is closed, its peers untouched. Frontends
-never spawn shells, write session files or watch files. #word("Attach")
-connects first and swaps second: only after the handshake does a shell
-give up its own core. #word("Restore") builds the replacement core before touching
-the current one.
+One `pardes --daemon` per user (`src/daemon.zig`) listens on
+`pardes-daemon.sock` in the runtime directory, its `.lock` flocked for its
+life; the first session that finds none starts it (a double fork and an
+exec) and it exits a second after it holds nothing. It is nobody's parent:
+a session registers on one connection, sends it a dup of every pty master
+it forks (so a session killed outright never hangs its shells up, and
+#word("Adopt") takes them into another), says whether a terminal or a
+window shows it, and is handed a terminal (`pardes --attach`) or a window
+request (`pardes-gui --attach`) through it. Messages are `SOCK_SEQPACKET`
+datagrams: a line of words and the fds it carries.
-`src/detached/wire.zig` is the versioned protocol (version 10): fixed-width
-little-endian fields, a 5-byte header (tag, then a u32 length), payloads up
-to 16 MiB and grids up to 512 by 128. A comptime hash of `pardes.Chrome`
-forces a version bump when that struct changes.
+`pardes` in a terminal forks its session off before anything starts: the
+session, in a session of its own (`setsid`), draws on the terminal it
+opened, and the process the shell waits on stays as its stub, passing it
+`SIGWINCH`, `SIGTERM`, `SIGINT` and `SIGQUIT` and ending with its status.
+#word("Detach"), or the terminal's end (EIO, a hangup), puts
+the terminal back and lets it go; the stub ends (exit 0) and the session
+runs on with nothing drawn, until `pardes --attach` hands it another
+terminal. A window's #word("Detach") closes the window and keeps the
+process; `pardes-gui --attach` opens one again. `PARDES_DAEMON=off` (the
+snapshot harness) runs a session as before the daemon: in the terminal's
+own process, ended by its hangup.
+
+A replica (a client running its own copy of the core, phase 5 of
+`docs/next-daemon.md`) connects to `pardes-replica.sock`, a stream socket
+beside it that `ssh -L` can forward. `src/detached/wire.zig` is its
+protocol (version 14): fixed-width little-endian fields, a 5-byte header
+(tag, then a u32 length), the hello, a ping, the input events. The hello
+names a session and carries the client's semantics hash (the protocol,
+release, commit, platform, build options and every dependency's hash); the
+daemon refuses another build's, or a session nobody has, in words, and
+hands an accepted connection to its session (`SCM_RIGHTS`), which welcomes
+it and from then on is the one it talks to. Today the session answers
+pings and nothing more.
+
+#word("Upgrade") (`src/upgrade.zig`) execs the path the session was started
+from, at a step boundary, after asking it `--version`: the session's dump
+goes to the DumpDir (`pardes-upgrade-<pid>.dump`), and its pty masters,
+terminals, stubs and daemon link stay open across the exec, named in a
+record on the new command line (`--upgraded=`) ahead of the arguments it
+was started with. The pid stays, so the shells stay its children; the new
+process loads the dump with every view and takes the fds back. One that
+cannot load it execs the old binary again (kept open from
+`/proc/self/exe`), or with none starts afresh with the shells adopted and
+the dump left for a Restore. The daemon re-execs the same way, its
+registry on its command line. `python3 -B test/daemon.py --upgrade <old>
+<new>` (and `--upgrade --gui`) is the end-to-end test.
= 9P
diff --git a/docs/typ/builtins-gui.json b/docs/typ/builtins-gui.json
index db1031a0..e731b75e 100644
--- a/docs/typ/builtins-gui.json
+++ b/docs/typ/builtins-gui.json
@@ -1,6 +1,6 @@
[
+ {"name": "Adopt", "leader": null, "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Take in the shells of a session that died holding them, each as a terminal pane here: the pardes daemon kept their terminals open."},
{"name": "Ascii", "leader": "SPC t a", "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "add the printable ASCII bitmaps to the matcher's glyph set"},
- {"name": "Attach", "leader": "SPC s a", "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "Attach this terminal to a detached pardes session by name."},
{"name": "Back", "leader": "SPC j o", "also": ["C-o"], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Ctrl-o: one step back into the history."},
{"name": "Bloom", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off, 0-3", "doc": "The brightest ink glows a little: a level, 0 (off) through 3."},
{"name": "BootShell", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "keep, replace", "doc": "A document dropped where a lone untouched shell stands: keep the shell, or replace it."},
@@ -29,7 +29,7 @@
{"name": "DelAbove", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Close the pane, giving its rows to the pane above it."},
{"name": "DelBelow", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Close the pane, giving its rows to the pane below it."},
{"name": "Delcol", "leader": "SPC c d", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Close this column and its panes, refusing once over unsaved text."},
- {"name": "Detach", "leader": "SPC s D", "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Detach this pardes from its terminal, leaving the session running."},
+ {"name": "Detach", "leader": "SPC s D", "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Detach this pardes from its terminal or window, leaving the session running: `pardes --attach` (or `pardes-gui --attach`) takes it back."},
{"name": "Diagnostics", "leader": "SPC l d", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "List the file's diagnostics from the language server."},
{"name": "Diff", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Stack a diff's hunks as a diff viewer shows them, each under its place and the declarations around it, in a +Diff; on a +Diff, show the diff itself as text."},
{"name": "DiffLook", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "hunks, text", "doc": "A .diff or .patch looked at: hunks, a +Diff stacking its hunks, or text, the file itself; Diff goes from one to the other."},
@@ -152,6 +152,7 @@
{"name": "Undo", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "acme's Undo and Redo: step the pane's body back or forward through its edits, from a tag, a pane ctl or exec."},
{"name": "Unmount", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "Unmount the 9P tree mounted under /n/<name>."},
{"name": "Up", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Move the keyboard to the pane above, and from a column's top pane to its tag."},
+ {"name": "Upgrade", "leader": "SPC s U", "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Move this session onto the pardes installed since it started, in place: its text, undo, views, terminals with their running shells, and its terminals and windows come along."},
{"name": "Verbose", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "A builtin says its own name on the message row as it runs, on or off."},
{"name": "Vignette", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off, 0-3", "doc": "The window's corners fall into shade: a level, 0 (off) through 3."},
{"name": "Window", "leader": "SPC w", "also": ["C-w"], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Window mode: h/j/k/l move an outline between the panes; Enter or Esc focuses the outlined pane, `:` its tag, the letter shown on a pane that one; d is Del on it (then k or j between two), c Collapse."},
diff --git a/docs/typ/builtins-tty.json b/docs/typ/builtins-tty.json
index 6bdca598..fe81b3fa 100644
--- a/docs/typ/builtins-tty.json
+++ b/docs/typ/builtins-tty.json
@@ -1,6 +1,6 @@
[
+ {"name": "Adopt", "leader": null, "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Take in the shells of a session that died holding them, each as a terminal pane here: the pardes daemon kept their terminals open."},
{"name": "Ascii", "leader": "SPC t a", "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "add the printable ASCII bitmaps to the matcher's glyph set"},
- {"name": "Attach", "leader": "SPC s a", "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "Attach this terminal to a detached pardes session by name."},
{"name": "Back", "leader": "SPC j o", "also": ["C-o"], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Ctrl-o: one step back into the history."},
{"name": "BootShell", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "keep, replace", "doc": "A document dropped where a lone untouched shell stands: keep the shell, or replace it."},
{"name": "Callees", "leader": "SPC l C", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "List the functions the function under the cursor calls."},
@@ -26,7 +26,7 @@
{"name": "DelAbove", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Close the pane, giving its rows to the pane above it."},
{"name": "DelBelow", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Close the pane, giving its rows to the pane below it."},
{"name": "Delcol", "leader": "SPC c d", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Close this column and its panes, refusing once over unsaved text."},
- {"name": "Detach", "leader": "SPC s D", "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Detach this pardes from its terminal, leaving the session running."},
+ {"name": "Detach", "leader": "SPC s D", "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Detach this pardes from its terminal or window, leaving the session running: `pardes --attach` (or `pardes-gui --attach`) takes it back."},
{"name": "Diagnostics", "leader": "SPC l d", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "List the file's diagnostics from the language server."},
{"name": "Diff", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Stack a diff's hunks as a diff viewer shows them, each under its place and the declarations around it, in a +Diff; on a +Diff, show the diff itself as text."},
{"name": "DiffLook", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "hunks, text", "doc": "A .diff or .patch looked at: hunks, a +Diff stacking its hunks, or text, the file itself; Diff goes from one to the other."},
@@ -135,6 +135,7 @@
{"name": "Undo", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "acme's Undo and Redo: step the pane's body back or forward through its edits, from a tag, a pane ctl or exec."},
{"name": "Unmount", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "Unmount the 9P tree mounted under /n/<name>."},
{"name": "Up", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Move the keyboard to the pane above, and from a column's top pane to its tag."},
+ {"name": "Upgrade", "leader": "SPC s U", "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Move this session onto the pardes installed since it started, in place: its text, undo, views, terminals with their running shells, and its terminals and windows come along."},
{"name": "Verbose", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "A builtin says its own name on the message row as it runs, on or off."},
{"name": "Window", "leader": "SPC w", "also": ["C-w"], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Window mode: h/j/k/l move an outline between the panes; Enter or Esc focuses the outlined pane, `:` its tag, the letter shown on a pane that one; d is Del on it (then k or j between two), c Collapse."},
{"name": "Wrap", "leader": "SPC t w", "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "Long lines wrap onto the next row, on or off."},
diff --git a/docs/typ/cheatsheet.typ b/docs/typ/cheatsheet.typ
index 43162f52..9dc9c473 100644
--- a/docs/typ/cheatsheet.typ
+++ b/docs/typ/cheatsheet.typ
@@ -72,7 +72,7 @@ Helix-style: motions *select*, then an edit acts on the selection. Mode box: bla
== Keys: panes
#pairs(
[#key("Ctrl-w")], [window mode: #keys("h", "j", "k", "l") move the outline, #key("d") deletes it (then #key("k")/#key("j") between two), #key("c") collapses it, #key("Enter")/#key("Esc") or a pane's letter focuses (not in insert or raw `$`)],
- [#key("Esc")], [back to the previous pane (insert: to normal)],
+ [#key("Esc")], [back to the previous pane (insert: to normal; a PDF: its selection and search highlights go first)],
[#key("Shift-Esc")], [back to the previous pane from any mode but raw, where it is the program's Esc; needs the kitty keyboard protocol or the GUI, elsewhere a plain Esc],
[#keys("Ctrl-o", "Ctrl-i")], [jump history back, forward; this file first. #key("Ctrl-i") is #key("Tab") without the kitty protocol: #key("SPC j i")],
[#key("Alt-n")], [new terminal below],
@@ -105,7 +105,6 @@ Helix-style: motions *select*, then an edit acts on the selection. Mode box: bla
key("SPC c p"), word("Placement"),
key("SPC s d"), word("Dump"),
key("SPC s r"), word("Restore"),
- key("SPC s a"), word("Attach"),
key("SPC s D"), word("Detach"),
key("SPC h t"), word("Tutor"),
key("SPC h m"), word("Messages"),
@@ -124,7 +123,7 @@ Helix-style: motions *select*, then an edit acts on the selection. Mode box: bla
- A query pane under the pane: line 1 the query, its first word the source: `/pat`, `Find name` (fuzzy), `Grep text` (literal), `Recent`, `Panes`, `Symbols`, `All`. #keys("Ctrl-n", "Ctrl-p") step, #key("Enter") lands and keeps the rows, #key("Esc") puts things back. #word("Help"), #word("Tutor").
== Sessions
-`pardes --detach=work`; `--attach=work` or #word("Attach") `work`; #word("Detach") leaves it running. #doc("detached")
+`pardes --detach=work`; `--attach=work` (`pardes-gui --attach=work`) takes it back; #word("Detach") leaves it running; #word("Adopt") takes in a killed session's shells. #doc("detached")
== Config
#word("Config") (#key("SPC f c")): `~/.config/pardes/init`, a builtin a line (#word("Theme") `atelier`). #word("DumpConfig"): every setting. #word("Dump") / #word("Restore"): the workspace. #doc("config")
diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ
index 58e5d907..56fe3ebd 100644
--- a/docs/typ/guide.typ
+++ b/docs/typ/guide.typ
@@ -43,7 +43,7 @@ steps raw, normal, insert.
[#mode-box(" ") normal], [#key("Esc"): back to the previous pane (#word("Last")), unlike helix. #key("Shift-Esc"): the same.],
[#mode-box("^") insert], [#key("Esc"): back to normal. #key("Shift-Esc"): out of insert and back to the previous pane.],
[#mode-box("$") raw], [#key("Esc"): back to the previous pane. #key("Shift-Esc"): an Esc to the program. Either way the terminal stays raw. #word("ProgramEsc") `on` swaps them back: #key("Esc") goes to the program, except at a shell prompt with nothing typed on it, and #key("Shift-Esc") always goes back.],
- [a PDF], [#key("Esc"): clears the selection and the search highlights. #key("Shift-Esc"): back to the previous pane.],
+ [a PDF], [#key("Esc"): clears the selection and the search highlights, and with none shown goes back to the previous pane. #key("Shift-Esc"): back at once.],
)
In acme, Esc selects the text typed since the last click; here it leaves
@@ -343,12 +343,29 @@ cheatsheet (#doc("cheatsheet")) say so.
```
pardes --detach=work & a session with no screen of its own
pardes --attach=work show it here
+pardes-gui --attach=work a window session's window again
+pardes --ps every session the daemon keeps, and its shells
+pardes --kill=work end it and its shells (--kill-all: every one)
```
-The session owns the panes, shells and files; frontends come and go, and
-all of them see the same screen. #word("Attach") `work` (#key("SPC s a"))
-switches this window to it; #word("Detach") (#key("SPC s D")) leaves it
-running.
+#word("Detach") (#key("SPC s D")) lets the terminal or the window go and
+leaves the session running, its panes, shells and files kept; so does a
+terminal that closes. `pardes --attach` takes it back in any terminal,
+`pardes-gui --attach` a window session's window: a terminal session takes
+a terminal, a window session a window. Attached already, it takes another
+view: each terminal or window has its own columns, focus, cursors and
+scroll over the same panes, texts and registers, and a terminal shown in
+two takes the size of the one that last typed into it. #word("Detach") in
+one lets only that one go. A session is named by `--9p=` or
+`--detach=`, else its pid. A session killed outright leaves its shells
+running; #word("Adopt") in another takes them in as terminal panes, what
+they showed gone. One `pardes --daemon` per user keeps all of it, and
+leaves once nothing is kept. After a rebuild, #word("Upgrade")
+(#key("SPC s U")) moves a running session onto the pardes now installed
+where it was started from, in place: its text and undo, its views, its
+terminals with their running shells, and its terminals and windows come
+along, and the daemon moves too. A build that cannot read the session
+hands it back to the one that ran it.
= Config <config>
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index b83b4a83..4de57d64 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -338,7 +338,13 @@ nothing answers (`dial failed: no answer`, `timed out`, `hung up`); with no
dial it is `wrong #args`, and any other `x!y` `bad dial address`, both
EINVAL. There are eight named mounts; `os` and `self` are reserved.
#word("Unmount") refuses a mount a pane, a working directory or a pending
-#word("Save") still uses. Mounts are dumped.
+#word("Save") still uses. Mounts are dumped. A mount keeps its connection,
+and sends each walk, open and first read or write together: an operation
+through it costs one round trip (a directory, or a file of no stated
+length, one more to see its end). A session on another machine mounts
+through a forwarded socket: `ssh -C -N -L /tmp/box.sock:<its socket> host`,
+then #word("Mount") `box /tmp/box.sock` (`-C`: a link far away carries
+fewer bytes in each round trip).
A session may open its own tree through a mount (a #word("Look") of `$m/pane/2/body`
from the editor serving `$m`): requests are answered on the connection's
@@ -368,27 +374,25 @@ Writes take settings and session builtins (`scope = .session` in
#word("Delcol") and a pane's `get` refuse the same way with their own
word, except that #word("Delcol") opens no `+Unsaved` pane: it names the
panes only in its `unsaved` records and its notice.
-- #word("Dump") writes `pardes-<date>-<time>.zon` (UTC) in #word("DumpDir"),
+- #word("Dump") writes `pardes-<date>-<time>.dump` (UTC) in #word("DumpDir"),
logs `dump <path>`, and adds a #word("Restore") `<path>` word naming it to the
workspace tag (the last dump's, replacing an earlier one's).
#word("Restore") `[path]` replaces every pane (bare: the last dump this session
wrote). The #word("Restore") write is answered, then *every connection is hung
up*: dial again, and restart a 9ns mount. The new log has a `new` per
- pane, `restore <path>`, then `restored <old> <new>` per pane and
- `restoredcol <old> <new>` per column. A dump keeps an unsaved pane's
- text and the hash of the file it was read against; a clean file pane's
- text is read from disk at #word("Restore"), so a file changed since comes back as
- it is now. An unsaved one whose file changed comes back with its own
- text, marked changed on disk, and its first #word("Save") asks before
- overwriting. A PDF's fit and tint are kept too. A #word("Restore") that fails says why in
- the parser's words, a ZON error with its line (`line 3: expected ','`),
- so the errno a mount gives depends on them (usually EIO): read the `err`
- record for why. A #word("ThemeFile") the dump names that fails to load changes
+ pane, then `restore <path>`. Its panes and columns keep the serials they
+ had when dumped; one made after takes a serial past every one the old
+ session handed out. A dump keeps every pane's text and undo: a clean
+ file changed on disk since comes back as it is now, an unsaved one with
+ its own text, marked changed on disk, and its first #word("Save") asks
+ before overwriting. A #word("Restore") of a file that is no dump fails
+ before anything is replaced (`not a pardes dump: it is cut short`), with
+ EIO: read the `err` record for why. A #word("ThemeFile") the dump names that fails to load changes
nothing.
- #word("Kill") `[word...]` (above), #word("Mount") `name dial`, #word("Unmount") `name`, #word("Theme") `x`.
-- `size C R` sizes a `--detach` session no frontend is attached to (160x50
- until then): from 20x6 to 4096x4096, else `invalid size`; refused while a
- frontend owns the size, and when a column would lose its panes' minimum
+- `size C R` sizes a session no terminal or window is attached to (160x50
+ for a `--detach` one until then): from 20x6 to 4096x4096, else `invalid
+ size`; refused while a terminal or window owns the size, and when a column would lose its panes' minimum
rows (`size: too small for the panes, each its tag and 2 rows`). A bad
`size` is refused quoting the value it got (`"5 2"`).
@@ -454,8 +458,7 @@ turning it off: #word("PanelSlide"), #word("PanelZoom"),
#word("PanelDissolve"), #word("PanelAscii"), #word("PanelVertical"),
#word("PanelEdges"), #word("PanelFall"), #word("PanelWave"),
#word("PanelCurtain"), #word("PanelScramble"), #word("PanelType"); all
-start off, and the web shell has none. Scene passes (the SDL window, and
-one attached to a detached session), each at a level 0-3 (`on` is 2), all
+start off, and the web shell has none. Scene passes (the SDL window), each at a level 0-3 (`on` is 2), all
off: #word("Crt"), #word("Bloom"), #word("Vignette"), #word("Grain").
#word("Shader") `<file.glsl>` adds a Shadertoy file written for ghostty to the
chain (#word("Shader") `off` removes it; it recompiles when saved);
@@ -891,7 +894,6 @@ just before the #word("Restore") are not lost.
[`changed <serial> [reloaded|deleted]`], [its file changed on disk (bare: under unsaved edits)],
[`unsaved <serial> <name>`], [a pane an #word("Exit"), #word("Restore"), #word("Del") or #word("Delcol") refused over, before the `err`],
[`dump <path>`, `restore <path>`], [a #word("Dump") written; a #word("Restore"), after its panes' `new`s],
- [`restored <old> <new>`, `restoredcol <old> <new>`], [serial maps after a #word("Restore")],
)
The serial is the pane the line ran at (the pane with the keyboard for the root's
@@ -1010,12 +1012,28 @@ to its end before the write is answered, and one that finds nothing fails,
another; a removed line's `-` goes to the line now standing where it was.
git's `a/` `b/` (and `c/ i/ w/ o/`) prefixes are dropped; a
`--no-prefix` diff's paths are kept.
-- *Sessions.* Bare `--detach` names the session after its pid; bare
- `--attach` needs exactly one session; a second `--detach=NAME` while NAME
- runs (a plain session is named by its pid) says so in words and exits 1. Frontends share the smallest common size. With
- none attached, `size C R` sets the screen, messages clear by the clock,
- and a pty reports its size in pixels at the last frontend's cell size
- (8×16 before any), as CSI 14, 16 and 18 t do.
+- *Sessions.* `pardes --ps` prints what the daemon keeps: each session
+ (its pid, terminal or window, attached or detached, name) with the pids
+ and commands of the shells it holds, then the shells no session holds,
+ which #word("Adopt") takes. `--kill=NAME` ends that session and its
+ shells (a TERM, then a KILL 2 s later; unsaved changes are lost),
+ `--kill-all` every session and every kept shell; with no daemon running
+ each says so and exits 1. Bare `--detach` names the session after its pid; bare
+ `--attach` needs exactly one detached session of its kind (a terminal's
+ for `pardes`, a window's for `pardes-gui`), or with none detached the
+ only session of that kind; a second `--detach=NAME`
+ while NAME runs (a plain session is named by its pid) says so in words
+ and exits 1. A session attached already takes another view, up to four:
+ each terminal or window its own layout, focus, cursors, selections,
+ modes, scroll and jumps, over the panes, texts, tags, terminals,
+ messages and registers they share. A terminal pane shown in two takes the
+ size of the view that typed into it last; a shorter view shows the
+ rows down to its cursor, an arrow in the gutter when rows are above. #word("Detach"), or a terminal closing, lets that view go and
+ leaves the others. With none
+ attached, `size C R` sets the screen, messages clear by the clock, and a
+ pty reports its size in pixels at the last cell size (8×16 before any),
+ as CSI 14, 16 and 18 t do. Attaching from another machine is gone until
+ the replicated clients (docs/next-daemon.md, phase 5).
- *Config.* The startup file is `$XDG_CONFIG_HOME/pardes/init` when that is
absolute, else `~/.config/pardes/init` (macOS:
`~/Library/Application Support/pardes/init`). A line that fails is a
@@ -1023,11 +1041,15 @@ to its end before the write is answered, and one that finds nothing fails,
setting only the other frontend has (#word("Font") in a terminal) is skipped;
text that is no builtin is not run; saving the init file in a pane
applies its settings again and says a bad line as startup does
- (`err - init file line N: why`), its commands not run again. A dump keeps panes, columns, tags,
- selections, the theme and changed settings, but not a picture or a PDF
- that is on disk (#word("Restore") reads it from there); a terminal
- comes back with its last MiB of output and a new shell in its old
- directory; undo history and REPL bindings are not kept. A crash appends
+ (`err - init file line N: why`), its commands not run again. A dump keeps the whole
+ session: panes with their text, undo, selections and places, terminals
+ with their screens, history and kitty images, pictures, registers,
+ columns, tags, the theme and settings. A terminal comes back with a new
+ shell in its old directory under its history (not the REPL it ran), a
+ PDF read from its file.
+ A dump made by another build loads: a field added since takes its
+ default, and what cannot be read (a pane whose kind changed) is left out
+ and said in a notice. A crash appends
two lines (build, time, platform, pid; the panic message) to `crashes`
beside `init`.