summaryrefslogtreecommitdiff
path: root/docs/typ/reference.typ
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-30 17:35:06 -0300
committerGabriel Schneider <[email protected]>2026-10-30 17:35:06 -0300
commit6d8da8721141284cf33bb901168b26135893eb86 (patch)
tree791d63401d4e85fbca1d597a8ce0326e70efd545 /docs/typ/reference.typ
parentefd43a3a2cf03bb741366331158b368abf9ac583 (diff)
parentbf6810a8f9d6cc82050e7d9c0cfb06358301b574 (diff)
downloadpardes-6d8da8721141284cf33bb901168b26135893eb86.tar.gz
pardes-6d8da8721141284cf33bb901168b26135893eb86.zip
Merge latest upstream into the macOS branch for Zig 0.17
Retain the macOS branch history and local Acme selection color while adopting upstream's current core and platform changes. Pin Zig and ZLS to 0.17.0, and fetch the existing zstbi compatibility commit through upstream after its original fork was removed.
Diffstat (limited to 'docs/typ/reference.typ')
-rw-r--r--docs/typ/reference.typ1146
1 files changed, 1146 insertions, 0 deletions
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
new file mode 100644
index 00000000..b83b4a83
--- /dev/null
+++ b/docs/typ/reference.typ
@@ -0,0 +1,1146 @@
+// The reference: every file the virtual filesystem serves over 9P, what it
+// does, how it fails, and the limits. How pardes behaves on screen is the
+// guide's; recipes and traps are scripting's; how a mount cuts writes and
+// the listeners are building's.
+#import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs, fstree
+
+Every native session is a virtual filesystem, served as 9P2000 (not .u,
+not .L) and modelled on acme's (#doc("reference", section: "from-acme")):
+panes, columns, tags and the session are files. Paths here are the served ones (#file("/pane/2/body")); through a
+mount they sit under the session's directory (`$m`; #doc("scripting", section: "find-the-session")
+says how to find it). The served #file("/README") is a
+one-screen summary of this page. Two builtins: #word("Look") (right-click): open what the
+text names, or else find it; #word("Exec") (middle-click): run the builtin
+it names, or else run it as a shell line. The files #file("look") and
+#file("exec") take a line each, as those clicks would.
+
+= The tree <tree>
+
+#fstree(```
+README the one-screen summary (src/fs-help.txt) @other-files
+index a line per pane: serial kind dirty name column @rules
+status pid, version, panes @other-files
+look write a line: a #word("Look") at the pane with the keyboard; read: the serials touched @look-and-exec
+exec write a line: an #word("Exec") there; read: the serials touched @look-and-exec
+pager write a directory: a new +Pager there; read: its serial @pardes-stdin
+log the event log; write follow to wait for more @log
+screen the rendered screen as JSON @on-screen
+listeners dial addresses @other-files
+focus the serial of the pane with the keyboard; write one to move it @columns-and-tags
+ctl settings and session builtins @root-ctl
+commands every builtin, one a line @other-files
+recent files opened lately: open|closed <path> @other-files
+layout a line per column, then active <serial> @columns-and-tags
+tag the workspace tag @columns-and-tags
+tagexec a word clicked in the workspace tag @columns-and-tags
+col/ the columns @columns-and-tags
+ <n>/ column <n>; rmdir closes it when empty @columns-and-tags
+ tag its tag
+ ctl its builtins (Delcol Joincol New Tty)
+ exec a word clicked in its tag
+pane/ the panes @panes
+ new open it to make a pane; read answers the serial @panes
+ <n>/ pane <n>; rmdir closes it @panes
+ name the file name; write to rename @panes
+ body the text; a write appends, > replaces @panes
+ tag its path, then its words; a write replaces the words @panes
+ ctl builtins and ctl words, a line each @panes
+ addr the address data and xdata work on @addresses
+ dot the selection, as an address @addresses
+ limit where a forward search stops @addresses
+ data the text at addr; a write replaces it @addresses
+ xdata the text in addr's range only @addresses
+ sel the selected text; a write replaces it @panes
+ dirty 1 while the text differs from its file @flags
+ mark 0 or 1; a write marks an undo point @flags
+ scroll 0 or 1; a write scrolls the pane @flags
+ errors write-only: text for the directory's +Errors @panes
+ event the pane's clicks and keys, as acme's event file @event
+ look a #word("Look") at this pane @look-and-exec
+ exec an #word("Exec") at this pane @look-and-exec
+ tagexec a word clicked in this pane's tag @look-and-exec
+ pty/ terminals only @pty
+ ctl winsize, sig, exec @pty
+ status cols rows busy @pty
+ data the live stream: bytes in as typed, output out @pty
+ run write a command line; read: exit N, then its output @pty
+os/ the host filesystem @mounts
+src/ the editor's sources (only with -Dembed-sources=true) @mounts
+```)
+
+Panes and columns are named by serials the editor gives: stable while they
+live, never reused (so they can have gaps). Nothing is created by a listing, stat, walk or read:
+only an open of #file("/pane/new") makes a pane (so `ls -l` and `find` are
+safe), only `rmdir` of #file("/pane/<n>") or an empty #file("/col/<n>")
+removes. Tcreate is refused everywhere.
+
+#file("/index") rows are `serial kind dirty name column`, kind `text`,
+`term` (a shell), `cmd` (a command's pane, no shell to type into), `pdf` or
+`image`, the name `<dir>/+New` for an unnamed scratch.
+Names may hold blanks, so split `head, col = row.rsplit(maxsplit=1)`, then
+`serial, kind, dirty, name = head.split(maxsplit=3)`. Names in
+#file("/index"), the log and a terminal's tag are escaped: a newline `\n`, a
+backslash `\\`, and any other control byte, DEL, a C1 control or a byte that
+is not UTF-8 `\xNN`, so a name decodes to the bytes it is.
+
+= Rules for every file <rules>
+
+*Failure.* A write fails whenever what it asked for fails, and logs one
+`err <serial|-> <file>: <why>` record, with no `msg`; a write that succeeds
+logs none. A refused write says why in the log's last `err` record, found
+with `grep '^err' log | tail -1`: after a refused #word("Del"), #word("Exit") or #word("Restore") the
+newest line may be `new N .../+Unsaved`. Only writes log: a
+refused open or truncation (an OTRUNC open such as `> data` after a failed
+`addr`), create or remove answers its error alone, as do a write to
+#file("pane/new") (`permission denied`) and a write on a read-only fid
+(`bad use of fid`). Errors are words (Plan 9's where pardes has none of its
+own), never a C library string; a bad setting value is quoted, the value
+itself (`bad value in control message; takes on, off "maybe"`); a ctl
+refusal quotes the offending word alone (`wrong #args in control message "Newcol"`). Through 9ns the kernel sees an errno 9ns reads
+from those words (cloud9's `fs.enameErrno`): the first of these that the
+words hold, case aside, wins, and anything else is EIO (`Modified`, a
+sam command pardes's #word("Edit") leaves out, `B <cmd`):
+
+#pairs(
+ [`control message`], [EINVAL],
+ [`interrupt`], [EINTR],
+ [`shut down`], [EIO],
+ [`not exist`, `not found`, `no such`], [ENOENT],
+ [`exists`], [EEXIST],
+ [`not empty`], [ENOTEMPTY],
+ [`not a dir`], [ENOTDIR],
+ [`is a dir`], [EISDIR],
+ [`permission`, `denied`], [EACCES],
+ [`read-only`, `read only`, `readonly`], [EROFS],
+ [`no space`], [ENOSPC],
+ [`not allowed`, `not permitted`, `cannot`], [EPERM],
+ [`fid`], [EBADF],
+ [`bad offset`, `invalid`, `bad `], [EINVAL],
+ [`busy`, `in use`], [EBUSY],
+ [`too long`], [ENAMETOOLONG],
+ [`too many open files`], [EMFILE],
+ [`not supported`, `unsupported`], [EOPNOTSUPP],
+ [acme's address and argument words: `no match for regexp`, `no previous regular expression`, `address out of range`, `addresses out of order`, `past end of body`, `written to addr failed`, `not locked by this open`, `too small for the panes`, `owns the size`, `no question asked`, `answer takes`], [EINVAL],
+)
+
+A file pardes reads (#word("Get"), #word("Look"), #word("Edit")'s `e` and `r`) that is a directory where a file is wanted says `is a directory` (EISDIR), an unreadable one `permission denied` (EACCES), and a device (`/dev/zero`, a tty) `not a regular file` (EIO), never read to the stream limit; #word("Incl") of a file says `not a directory` (ENOTDIR).
+
+The `err` record has the words; a shell sees only the errno.
+
+Not failures: a #word("Look") that finds nothing (it answers nothing and logs one
+`err`), an #word("Edit") `x` that matches nothing, #word("Undo") with nothing to
+undo (a `msg`), and a command pane's command, which ends in its own time
+with an `exit` record.
+
+*Command lines.* #file("look"), #file("exec"), #file("tagexec"), the three
+kinds of #file("ctl") and a column's #file("exec") take one command a line.
+The whole write is checked first (a control character other than a tab
+fails it all, EINVAL); then lines run in order, and a failing line fails
+the write after the lines before it took effect, as acme's ctl does. Blank
+lines are skipped. A line runs at its newline; the last one, unended, runs
+after its open is closed, the close answered first, so its failure is only
+its `err` in the log: end a write with a newline when its result matters
+(#doc("building", section: "writes-through-a-mount")). `> exec` (a
+truncating open) is fine through a mount. An #word("Edit") whose `{` or `a`/`c`/`i` text is still
+open waits for the next write on that open. A line or #word("Edit") block over
+1 MiB is refused once (EINVAL), and the rest of it, through its newline,
+is dropped.
+
+*Answers.* Reading #file("look"), #file("exec") or #file("tagexec") answers
+the serials the last command made, or else the pane it acted on or
+focused, one a line; nothing when it did none of these (#word("Newcol") at
+#file("/tagexec")). A read answers the panes touched by this open's last
+write. An open that never wrote reads the session's last answer, from
+whichever client wrote it, so read on the open you wrote. A read is a stream: once read,
+the next read on that fid is EOF until the next write (or seek to 0). With
+other clients about, write and read on one open:
+#cmd("exec 3<>$m/pane/$n/look; echo x >&3; cat <&3; exec 3<&-")
+
+*Snapshots.* #file("/index"), #file("/layout"), #file("/recent"),
+#file("/commands"), #file("/status"), #file("/listeners"), a read-only
+#file("ctl"), #file("/log"), #file("/screen") and a terminal's
+#file("body") freeze at the open, so one read in several chunks never
+splices two moments; open again for now.
+
+*Open records.* A session holds 64 open records, shared by every client.
+An open that keeps state takes one: such a snapshot, a #file("run"),
+#file("event") or #file("pty/data") open, a write open of #file("data"),
+#file("xdata"), #file("sel") or a text pane's #file("body"), and every
+write open of a command file (#file("look"), #file("exec"),
+#file("tagexec"), a #file("ctl")). A plain read of a pane's text takes
+none. Past 64 an open is refused `too many open files`, which a mount
+reports as EMFILE. Close what you open: a shell's `exec 3>$m/exec` holds
+its record until fd 3 is closed.
+
+*Held reads.* A read with nothing to give yet (a followed #file("log"),
+#file("event"), #file("pty/data"), #file("pty/run") before its answer)
+waits in the editor and is answered when news comes. A second read on that
+open meanwhile fails `file in use`. A read the client flushed is dropped.
+One connection holds at most 128 reads at once; the next is refused `too many reads waiting: 128`. Every held read is on an open that keeps state,
+and those are 64 in the session (above), so 64 is the real cap on reads
+held at once, through one connection or many. A mount (9ns) is one
+connection, and it keeps answering everything else beside its held reads.
+
+*Stats.* A file whose text is kept has its real length: a pane's
+#file("body"), #file("tag"), #file("name"), #file("ctl"), #file("sel") and
+the range and flag files, the workspace's #file("tag"), the root
+#file("ctl"), #file("status"), #file("commands"), #file("README"), the
+#file("look")/#file("exec") answers, #file("focus"); #file("event") and
+#file("pty/data") the next record's, zero when none waits. A stream and a
+view generated by each read stat 0, as acme's do: #file("log"), #file("screen"), #file("data"), #file("xdata"), #file("index"),
+#file("layout"), #file("recent"), #file("listeners"), #file("pane/new").
+Read those to the end rather than trust a length (`cat` does). The qid
+version of #file("body"), #file("data") and #file("xdata") is the pane's
+revision, so a stat sees an edit land. Modes are 0644/0666, 0444
+read-only, 0222 write-only.
+
+= look and exec <look-and-exec>
+
+A line written to #file("look") is #word("Look") on it, on the line as
+written: its leading blanks are its own (` return x` finds that
+indented line, and a diff's blank context line ` ` is a #word("Look") too); only its
+newline and `\r` go. An #file("exec") line's blanks at either end are
+trimmed. The guide says what #word("Look") opens and where it finds a relative path (#doc("tags", section: "looking")); here is what is particular to the
+files.
+
+- `file:12` selects line 12, newline included; `file:12:5` puts the caret
+ at line 12, byte column 5; `file:<addr>` takes any address (below),
+ *evaluated from the file's dot*: `file:/re/` finds the next match after
+ the selection, `file:0/re/` the first. A bare `:N` or `:N:M` (or any `:addr`) addresses the pane the #word("Look") came from.
+ `@p<serial>:<addr>` addresses a pane by serial, a terminal's logical
+ lines too.
+- A leading `~` is the home directory (`$HOME`, else the passwd entry's;
+ `~user` that user's) here and wherever a path is typed (#file("name"),
+ #word("Save"), #word("ThemeFile"), #word("DumpDir"), #word("Restore"),
+ `pardes '~/x'`), even beside a file named `~`: write `./~` for that.
+- A path to no file is a miss, as a search that finds nothing is: said on
+ the message row and logged as an `err`, the write still answered. A file
+ that is there but will not open fails the write and is named:
+ `look: <path>: permission denied`. A zero column is refused, `file:0:0`
+ included: columns count from 1.
+- A whole line of a diff pane written to #file("look") is the #word("Look") on its first column. The line is matched in the
+ pane from its cursor row on, wrapping, and the first match wins.
+- On a PDF pane `:P:H` is hit H of the pane's search on page P, as
+ `file.pdf:P:H` is; a hit not there, or any H with no search active, is a
+ miss, `has no search hit H on page P`. Only a `+PdfSections` row's
+ second number is a section,
+ `file.pdf:PAGE:SECTION`, and only such rows are checked against the
+ outline: a section not there, or not on that page, is a miss.
+- A plain word selects its next place after dot, wrapping. #word("LookWord") `list`
+ on the root ctl lists a row per line holding it in a `+Search` pane
+ instead; the next word given to #word("Look") in that directory refills it. In a
+ terminal a word is always listed, rows spelled `@p3:12:5-9`.
+
+A miss logs `err <serial> look: ...` (`no match for "zzq:#3"` quoting what
+was written when nothing by that name exists; `<path>:99 has no line 99`
+for a line past a file's end, `<path> has no page 99` for a PDF's page;
+`<path>: no match for regexp` or `<path>: address out of range` when an
+address fails), opens nothing, and leaves #file("look") reading empty; the
+write succeeds. A `./x` or `../x` that is not there is such a miss too
+(`look: ./x: no such file`). A #word("Look") whose address fails says so and leaves open no file
+it opened. A #word("Look") of `file:12:` reads as `file:12`: a trailing colon is
+dropped, as a click leaves it off. A path too long to repeat whole gives up
+its middle to `…`.
+
+A line written to #file("exec") is #word("Exec"):
+
+- A builtin word runs (#file("/commands") lists them). A builtin that needs
+ its argument (#word("Msg"), #word("Mount"), #word("Find")) written bare is
+ `wrong #args in control message "Msg"`, and so is one that takes none
+ written with one (#word("Config") `extra`).
+- A line starting with `#` is a comment, as in a shell: it runs as nothing,
+ silently, here and in every ctl.
+- The language server's words ask about a file pane's text at its cursor
+ (set it with #file("addr") and `dot=addr` first): #word("Hover") fills
+ `+Hover`; #word("Def") and #word("Refs"), in the tag of a file a server
+ speaks for, are `gd` and `gr`, and given a symbol (a 2-1 chord's
+ selection) ask at its occurrence nearest the cursor; #word("Rename") `new` renames the symbol in the file and says how many
+ ranges it changed (on the message row, and so in the log) without listing
+ them, and fails when there is nothing to rename. One that reaches other
+ files applies nothing: it opens a `+Search` preview of the edits, which
+ is the pane the write answers, and says how many it lists. So does one
+ the server answers in this file alone while another open file of its
+ language still holds the old name, a row per such file (zls renaming at
+ a declaration; from a use it reaches every file);
+ #word("Callstack") (#key("g c") or #key("SPC l b")) opens and focuses `+Callstack`,
+ with static caller ancestry, tree-sitter signatures and Look locations
+ for callers and call sites, test callers after the rest at each level; run
+ in `+Callstack` itself, it shows the next page of a tree too big for one.
+ #word("CallstackDepth") reports or sets the
+ runtime depth (1–64, default 8) for subsequent queries.
+ `CallstackLayout stacked` (the default) aligns snippets below their locations;
+ `CallstackLayout inline` places the snippets beside them.
+ `CallstackCorners rounded` (the default) or `CallstackCorners square`
+ selects the tree corner style for the next query; bare, it switches styles.
+ #word("Callers") and #word("Callees") keep their short
+ lists and single-result jumps.
+ #word("Diagnostics") and #word("Symbols") list the file's in `+Search`;
+ #word("Lspinfo") fills `+Lsp`, the pane its write answers, with which
+ server serves the file and its state (`not started yet` until its first
+ query starts it, `<server> failed recently; retry in Ns` while it backs
+ off);
+ #word("Lspwhy") narrates the last query step by step (in `+Lsp`). The
+ write returns once the answer is in; a pane with no file is refused.
+- acme's words run as pardes's where it has one (`Put` is #word("Save"),
+ `Load` is #word("Restore"), `Delete` a #word("Del") that does not ask);
+ `Get`, `Putall`, `Zerox`, `Tab` and `Incl` are builtins of their own; the
+ rest (`Snarf`, `Cut`, `Paste`, `Sort`, `ID`, `Send`, `Indent`, `Local`,
+ `Abort`) are refused, `invalid: acme's Snarf is not a pardes builtin: ...`,
+ never run as commands. So is a GUI-only builtin (#word("Fonts")) on
+ another frontend.
+- Anything else is a command line (a typo ends `exit 127`), at most 1024 bytes, run as the guide
+ says (#doc("tags", section: "command-panes")): typed into a terminal idle
+ at an empty prompt, else run in a command pane. #file("exec") reads back
+ the command pane's serial, and while that open stays open the pane is its
+own: another client's command in the same directory gets a pane of its
+own. The log says `run <serial> <line>` and `exit <serial> <N|?>`. A
+reused pane's #file("body") keeps every earlier run
+ above a `% <line>` row naming each command, so to take only the last
+ run's output read from after the last `% ` row, leaving out its `exit N`:
+ #cmd("awk '/^% /{out=\"\"; next} /^exit [0-9?]+/{next} {out = out $0 \"\\n\"} END {printf \"%s\", out}' body")
+ From a pane whose directory is gone nothing runs: `exec: <dir>: no such directory` (ENOENT).
+
+The root's #file("look") and #file("exec") act at the pane with the keyboard and log as
+that pane's (with no pane at all, in the session's directory: a #word("Look") opens its file, making a column as #word("New") does, and an exec runs its
+command there); #file("/pane/<n>/look") and #file("exec") at pane n;
+#file("/tagexec") and #file("/col/<n>/exec") click in the workspace's or
+that column's tag, run commands in the session's directory, and log as
+`-`. A pane's word (#word("Undo"), #word("Msg"), #word("Save")) is refused
+at #file("/tagexec") and a column's exec: `not a session control message "Undo": write it to pane/<n>/ctl`.
+
+A background job (`&`) outlives a command that exits on its own; its
+output goes on below `exit N` until it lets go of the pty. #word("Kill")
+(root ctl) stops the commands pardes started: bare, all; #word("Kill") `make ls`,
+those whose line starts with one of the words. For a command pane it
+signals the whole line, `&` jobs included; for a line typed into a shell
+only the foreground job (SIGTERM), and the shell decides the rest. With
+nothing running, named or not, it says `Kill: nothing running` and the
+write succeeds; words that name none of what runs fail it (`Kill: no running command has that first word`). #word("Kill") does not reach a
+REPL's code: use `sig INT` on its #file("pty/ctl").
+
+== Paths and mounts <mounts>
+
+#word("Look") resolves the OS filesystem first, then the editor's own tree.
+Explicit paths skip that search:
+
+#pairs(
+ [`/n/os/proc/self`], [the host filesystem, served as #file("/os/proc/self")],
+ [`/n/self/pane/2/body`, `/virtual/pane/2/body`], [this session's tree, #file("/pane/2/body")],
+ [`/virtual/src/pardes.zig`], [sources embedded with `-Dembed-sources=true`, #file("/src/pardes.zig")],
+ [`/n/peer/pane/2/body`], [a mounted session: the peer's #file("/pane/2/body")],
+)
+
+`--mount=peer=work` or #word("Mount") `peer <dial>` mounts a dial: `unix!/path`,
+`/path`, `tcp!<numeric-ip>!<port>`, a session name, or with `-Dquic`
+`quic!…`; a missing socket is ENOENT, `no such socket`;
+#word("Unmount") `peer` removes it. #word("Mount") dials at once and fails if
+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.
+
+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
+task while the editor waits in its syscall. Through QUIC that still hangs.
+
+= The root ctl <root-ctl>
+
+Reading #file("/ctl") gives every setting, one a line, in the words a write
+takes (#word("Theme") `orchard`, #word("Verbose") `on`, #word("Placement") `acme`, #word("DumpDir") `<dir>`,
+#word("Shell") `/bin/bash`, ...), so writing back what it reads changes nothing.
+Writes take settings and session builtins (`scope = .session` in
+`src/builtins.zig`), acting at the pane with the keyboard:
+
+- A setting written bare steps to its next value (a switch flips; so do
+ #word("Placement"), #word("BootShell"), #word("Crt")). A value it does not
+ take is `bad value in control message; ...` naming what it takes;
+ #file("/commands") lists them. A setting the frontend cannot show is
+ refused (`Lift is GUI-only, invalid here`).
+- #word("Newcol") makes an empty column right of the keyboard's, halving
+ it. #word("Joincol") folds the keyboard's column into the one on its
+ right (its panes go below that column's), `Joincol: no column to the right`.
+- #word("Exit") quits. While panes hold unsaved text it refuses once
+ (#doc("tags", section: "unsaved-panes")): one `unsaved <serial> <name>`
+ record per pane, then the write fails `<name>: Modified (Exit again to discard)` or `4 unsaved panes: Modified (Exit again to discard)` (EIO),
+ and the list stays in a `+Unsaved` pane (in the directory of the pane with the keyboard,
+ or the session's when that directory is not on disk). #word("Restore"), #word("Del"),
+ #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"),
+ 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
+ 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
+ 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"`).
+
+A word that takes its argument after a `+` (#word("Tty+bash")) works on a ctl as
+in a tag. A write is refused whole, before anything runs, in Plan 9's
+words:
+`unknown control message "X"`, `wrong #args in control message "X"`, `bad value in control message ...`, or a word of the other ctl: `not a session control message "Undo": write it to pane/<n>/ctl`, `... "Delcol": write it to col/<serial>/ctl`, `not a window control message "X": write it to /ctl`. A builtin that would open a prompt (#word("Save") on a scratch)
+fails `control message needs its argument "Save"`. A line that fails as it
+runs fails with the editor's words (`Mount: already mounted`, `Save /root/x: access denied`), changing nothing.
+
+== Settings <settings>
+
+A setting that chooses among words (`on`/`off` switches,
+#word("Placement"), #word("BootShell"), #word("Crt"), #word("Bloom"),
+#word("Vignette"), #word("Grain"), #word("Lift"), #word("Motion"),
+#word("ShaderAnimation")) steps to its next value when given bare, as its
+word clicked in a tag does. The same lines go in the startup file
+(#doc("config")).
+
+#pairs(
+ [#word("Theme") `<name>`], [`orchard`; names as #word("Themes") lists them, #word("NextColor") steps to the next in that list (#doc("themes"))],
+ [#word("ThemeFile") `<path>`], [a `.zon` theme, relative to the config directory; reloads live when saved],
+ [#word("FocusTint")], [on: tint the focused pane's and column's tags],
+ [#word("SyntaxBold")], [off: bold syntax keywords],
+ [#word("Verbose")], [on: a builtin announces its name on the message row],
+ [#word("MessageAnimation")], [on: messages ease in and dissolve],
+ [#word("MessageLinger"), #word("MessageFall"), #word("MessageDissolve")], [800, 180, 150 milliseconds, at most 60000],
+ [#word("PagerColor")], [on: the next paged text keeps its colours],
+ [#word("ProgramEsc")], [off: in a raw terminal #key("Esc") goes back a pane and #key("Shift-Esc") is the program's Esc; on swaps them, and #key("Esc") goes back only at an empty shell prompt],
+ [#word("Pager") `pardes|off`], [`pardes`: what a terminal's commands page through, `pardes -`; `off` leaves `PAGER`, `GIT_PAGER` and `SYSTEMD_PAGER` as the environment has them (#doc("fs", section: "pardes-stdin")). It applies to terminals started after it],
+ [#word("Placement") `acme|pardes`], [`acme`: where new panes go (#doc("fs", section: "placement"))],
+ [#word("BootShell") `keep|replace`], [`keep`; `replace` closes the untouched lone shell a dragged document lands beside],
+ [#word("LookWord") `search|list`], [`search`: a word given to #word("Look") selects its next place, or lists all in `+Search`],
+ [#word("DirLook") `pane|terminal`], [`pane`: #word("Look") on a directory opens a pane listing it, as acme's directory window (#doc("reference", section: "from-acme")); `terminal` types `ls` into a terminal idle there, else opens one],
+ [#word("JumpScope") `file|all`], [`file`: #word("Back") and #word("Forward") keep to the focused pane's file, that pane's places first, then the file's in another pane, and go to another file only when the file has no place left that way; from a terminal or a pane with no file they step through every place; `all`: every place, in the order it was jumped to],
+ [#word("TermImages") `real|petscii`], [`real`: a new terminal draws its program's kitty graphics (yazi's previews) as pixels where the shell can; #word("Petscii") flips one terminal; a tty under a terminal without kitty graphics draws them as glyph art either way],
+ [#word("Shell") `<name or path>`], [`$SHELL` when it is executable, else `/bin/sh`: the shell the next terminal and command pane run; a bare name is searched for in the usual bin directories, not `$PATH`; bare #word("Shell"): `$SHELL` if it is executable, else `/bin/sh`],
+ [#word("DumpDir") `<dir>`], [`$XDG_DATA_HOME/pardes`, else `~/.local/share/pardes`: where #word("Dump") writes, an absolute or `~` path to a directory that may be written (made if missing); a relative one, or one under a directory that may not be written, is refused; bare returns to the default],
+ [#word("TreeContext")], [off: sticky declaration headers in a source pane (per pane, dumped)],
+ [#word("TreeContextTagStyle")], [on: draw those headers in the tagline style],
+ [#word("LocationsConfig") `...`], [the layout of #word("Grep"), search and language-server results (below)],
+ [#word("Wrap"), #word("Colors"), #word("Tagbottom"), #word("Debug")], [toggles],
+ [#word("Font") `<name>[:<size>]`, #word("Fonts")], [SDL and macOS only; size 8-72 (pixels in SDL, points on macOS)],
+ [#word("TaglineSize") `<1-100>`], [82: tagline face, percent; SDL and macOS],
+ [#word("WindowOpacity") `<0-100>`], [100; SDL only: everything but text and the cursor],
+ [#word("Ligatures")], [on; SDL only, macOS draws CoreText's own],
+ [#word("Pet") `cat|frog|off`], [off; SDL only: a sprite in the workspace tag's blank space],
+)
+
+#word("LocationsConfig") with no argument prints the current settings as a line
+that can be run again; with fields it changes only those:
+#word("LocationsConfig") `context:5 tscontext:on tslocations:off layout:stacked`.
+`context` (0) is the source lines shown above and below each match;
+`tscontext` (off) includes the enclosing tree-sitter declaration headers;
+`tslocations` (on) shows a location on each declaration header; `layout`
+(`stacked`) puts the location on its own line, `inline` beside the source,
+padded in groups of eight matches. An invalid field rejects the whole line;
+a repeated field's last value wins. The settings survive #word("Dump") and #word("Restore").
+Source analysis is cached for 64 files and 64 MiB.
+
+*Effects.* Panel transitions, one at a time, running the active one again
+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
+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);
+#word("ShaderAnimation") `off|on|always` says when the chain animates by itself. The
+focused pane can stand off the page: #word("Lift") `shadow|rim|auto|off`,
+#word("InactiveDim") `<percent>`, #word("Motion") `off|crisp|smooth|bouncy|playful` (default
+`smooth`), #word("SelectionGlow"), #word("HoverGlow"), #word("Occlusion"),
+#word("Parallax"), #word("JumpTrail"), #word("ChipShadow"),
+#word("ThumbFlash"), #word("CursorBlink"), #word("GripWidth") `<50-300>`. Most are
+the GUI's; #word("InactiveDim") works everywhere, and #word("JumpTrail"),
+#word("ChipShadow") and #word("ThumbFlash") are the terminal's. No effect
+may lower the contrast of text, the selection or a focus indicator.
+#word("EffectCode") `<effect>` lists that effect's sources under `/virtual` when the
+build embeds them.
+
+Resting the pointer on text for about 32 ms (`look_preview_delay_frames`,
+2 frames, in `src/config.zig`; `null` turns it off) tints what #word("Look") would take, with no other effect. A terminal's or a `+Pager`'s
+#word("Filter") keeps each foreground at least `tty_filter_min_contrast`
+(WCAG 1.5, `src/config.zig`) against its background.
+
+= Columns and tags <columns-and-tags>
+
+#file("/layout") has a line per column, left to right: `serial index x width current|notcurrent empty|full pane-serials...`, then `active <serial>` (the active column: where #file("pane/new") and a look put the
+next pane; `-` when none). `current` is the column with the keyboard now,
+which may differ from the active one (#doc("tags", section: "command-panes")).
+#file("/index")'s last field is each pane's column serial.
+
+A session holds 16 columns (`no space for a column: 16 max`, ENOSPC), each
+at least 10 cells wide, so 16 wants a window 160 cells wide or more.
+#word("Newcol") halves the column it is run from, and one under 20 cells
+does not split (`this one is too narrow to split`): reach 16 by writing
+#word("Newcol") to the widest column's #file("exec") each time, not to the
+root's, which keeps halving the one just made. #word("Newcol") is refused
+as well when a narrower column would wrap its panes' tags onto more rows
+and leave one under its tag and two rows (`Newcol: no space for a column: the panes' tags would not fit`); a refused #word("Newcol") logs its `err`
+alone and uses up no column serial.
+
+#file("/col/<n>/ctl") takes #word("Delcol"), #word("Joincol"),
+#word("New") and #word("Tty") for that column; #file("/col/<n>/exec") is
+a click in its tag; `rmdir /col/<n>` closes an empty column (one with
+panes: ENOTEMPTY). Closing a column's last pane leaves it empty (the
+keyboard goes to its tag, #file("focus") reads empty, the log says only
+`del`); closing the session's last pane quits pardes. The log says
+`newcol <serial>` and `delcol <serial>`.
+
+#file("tag") files (#file("/tag"), #file("/col/<n>/tag"),
+#file("/pane/<n>/tag")) read the whole tag, with no newline after it. A
+pane's starts with its computed path (an image's with its mode words, a
+PDF's with its page), then the editable text. `>` replaces the editable
+text (the default words too: `echo Make > tag` leaves only `Make`) and
+drops the one newline that ends it; `>>` appends, so
+`printf ' Make' >> tag` (the blank matters; `echo` would start a second
+line). A pane tag may hold several lines; a column or workspace tag is
+one, a newline written into it becoming a space. Control characters other
+than tab, DEL, C1 controls and non-UTF-8 bytes are refused (`invalid tag text`). The editable text is at most 4096 bytes (`no space: over 4096 bytes`, ENOSPC; the log says `err <serial> tag: no space: ...`). All
+three kinds take the same checks, whole or not at all, and a `>` whose
+write is refused changes nothing: its truncation is done with the write
+that fits, or at the close (or a read) when none came. Each write stands
+on its own: in a `>` cut into several writes, those taken before a refused
+one stay in the tag; only the refused write changes nothing. A clear is an
+ordinary edit and #key("u") in the tag undoes it.
+
+= Panes <panes>
+
+*Making and closing.* Opening #file("/pane/new") makes a scratch
+`<dir>/+New` (the session's directory), and reading that open answers its
+serial: `n=$(cat $m/pane/new)`. *Each open makes another pane*; two reads
+of one open answer the same serial. It goes where a #word("New") from a
+tag would (#doc("fs", section: "placement")): in the active column,
+filling it if empty, else the bottom half of its last pane. A session
+holds 64 panes (`no space for a pane: 64 max`), and every pane keeps its
+tag and 2 rows (`no space for a pane in that column: each keeps its tag and 2 rows`); both are ENOSPC, for this open and for #word("Look"), #word("Exec"),
+#word("New") or #word("Tty") alike. A #file("pane/new") whose column is
+full takes its rows from a pane in another column that has them, last
+column first, as acme does, and is refused only when no pane anywhere can
+give them. `rmdir /pane/<n>` closes the pane, unsaved or not.
+
+*#file("name")* reads the file name (a terminal's directory); a write
+renames the buffer (relative to the pane's directory) and marks nothing
+dirty; #word("Save") then writes under the new name. A name takes any byte
+a file name can hold, blanks, control bytes and bytes not UTF-8 included,
+so what #file("name") reads writes back as it was; refused (EINVAL) are
+an empty name, a NUL (`bad character in file name: an
+empty name`, `...: a NUL`) and a second line, by the write that brings it (`invalid file name: one name a write, on one line`). Up to
+255 bytes a component. A name that can never be valid (a terminal's, a
+component over 255 bytes, a path too long) is refused by the write that
+holds it. The ctl word `name x` takes all after its one
+blank; a second blank there is refused rather than read as the name's
+first byte. A directory (`/`, `~`, `foo/`) is no file name: refused,
+EISDIR (`name: /home/u is a directory, not a file`).
+
+*#file("body")* reads the text; a write appends; `>` (OTRUNC) replaces it
+all. A terminal's body is its history as plain text in logical lines
+(wrapped rows joined), frozen per open; writing it sends input to the
+child as typed keys, never a paste: no bracketed-paste marks around it,
+even when the program asked for them, so a newline in it is Enter. A PDF's
+body is the text layer of the page shown, each line of the page's text a
+line of the body, read-only: it is no text of the
+pane's, so #file("addr"), #file("data"), #file("dot") and a `file:<addr>` #word("Look") do not address it (a PDF's `:<n>` is its page); images and PDFs take
+no write (`this pane has no text`).
+
+*Image panes.* An image pane's tag reads `img petscii:on|off
+palette:commodore|terminal ascii:on|off <path>`. `petscii` says what is
+drawn: glyph art (`on`) or pixels (`off`). With no graphics it is always
+`on`; #word("Petscii") `on|off` chooses for when graphics are there. `palette` is which 16
+colours the glyph art uses, the C64's (`commodore`) or the terminal
+theme's own 16 (#word("Palette") toggles it); `ascii` is whether the
+printable ASCII bitmaps join the glyph set the matcher picks from
+(#word("Ascii") toggles it). #word("Palette") and ascii only change the glyph art.
+#word("Petscii") and #word("Ascii") (`on|off`) and #word("Palette")
+(`commodore|terminal`) take the value their tag word shows and set it, as
+a PDF's #word("PdfFit") (`width|height`) and #word("PdfTint")
+(`disabled|filtered|full`) take the value its ctl read shows; bare, they
+step to the next.
+A terminal pane showing kitty graphics shows `petscii:on|off` after its
+directory in its tag, saying the same, and #word("Petscii") chooses there
+too. A terminal with no images shows the word only while #word("Petscii")
+is on.
+
+*#file("sel")* reads the selected text; a write replaces it and leaves
+the written text selected, and one open's writes run on from the last.
+*#file("errors")* is write-only: text appended to the directory's
+`+Errors` pane (logged as `msg` records when no column has room).
+
+*#file("focus")* (root): a serial written gives that pane the keyboard and
+makes its column the active one (a folded pane stays folded); `no such pane`, or `ill-formed control message` for a non-number. It reads empty
+while a column or workspace tag has the keyboard.
+
+*Pane ctl.* Reading it gives acme's status line: serial, tag length, body
+length, isdir (1 for a directory pane, else 0), dirty, width in cells, font, tab width, undo available,
+redo available, then `current`/`notcurrent`, a REPL's id if bound,
+`collapsed` when it is, and for a PDF `fit:width|height
+tint:disabled|filtered|full`. Each field ends in a blank and the line has
+no newline, as acme's has none (`cat ctl; echo`). It
+takes:
+
+- the pane builtins: #word("Del") (from the keyboard between two panes it
+ asks which takes the rows, the question on the notice band after 400 ms
+ and in the log at once as `ask`; a click, a ctl write or an `init` line never
+ asks and gives them to the pane above; #word("Del") `k`/#word("Del") `j`, or
+ #word("DelAbove")/#word("DelBelow"), give its rows to the pane above or
+ below), #word("Save") `[path]` (bare, on a `+`-named pane that is no output,
+ such as `+Tutor`, it asks for a path; making the directories the file goes in first,
+ whichever name it writes), #word("Collapse"), #word("Undo")/#word("Redo")
+ (256 steps each), #word("Find") `pat`, #word("Edit") `...`, #word("Tty") `[shell]` (a new terminal
+ in its directory), #word("Delcol") for its column, and
+ #word("Left")/#word("Right")/#word("Up")/#word("Down"), which give the
+ keyboard to the pane beside it that way, up from a column's top pane to
+ its tag; #word("Window") (#key("Ctrl-w"), #key("SPC w")) picks the pane
+ first: #keys("h", "j", "k", "l") move an outline, #key("Enter") or
+ #key("Esc") or a pane's letter focuses, #key("d") is #word("Del") and
+ #key("c") #word("Collapse") on the outlined pane.
+- `get`: reload from the file (refused once over unsaved edits, `<name>: Modified (get again to discard)`). It is an undo step, so #word("Undo") brings back what was there: the sure way back to the file on disk.
+- `lock`/`unlock` (acme's). The lock binds only clients that take it and
+ belongs to the open that wrote it: `exec 3>$pane/ctl; echo lock >&3; ...; exec 3>&-`. A `lock` another open holds fails at once, `file in use`
+ (EBUSY): retry.
+- `answer <choice>` to the question the pane asks on its message row,
+ logged `ask <serial> <what> <choices>` (`ask 4 del k j`, `ask 4 repl a b`, `ask 4 save path`); `answer -` takes it back.
+- acme's lowercase ctl words, done by what replaces each: `name x`, `put`
+ (#word("Save")), `clean`/`dirty`, `del`, `delete` (no asking), `dot=addr`,
+ `addr=dot`, `limit=addr`, `mark`/`nomark`, `show`, `cleartag`. `dump`,
+ `dumpdir`, `font`, `menu`, `nomenu` are refused, EINVAL. These lowercase
+ words are ctl-only: written to an #file("exec"), `del` is a command line.
+
+A file changed on disk reloads by itself only when the buffer has no
+unsaved edits; otherwise it stays dirty, says `<name> changed on disk (get reloads it, Save overwrites it)`, logs `changed <serial>`, and its next
+#word("Save") warns once. A file whose disk text is what the pane was read or saved as is no change: an #word("Undo") back across #word("Get") `file` or `e` to unsaved edits says nothing changed, and #word("Save") writes it.
+
+== Addresses and data <addresses>
+
+#file("addr"), #file("dot") and #file("limit") read the pair of byte
+offsets they take, so copying one onto another (`cp $p/addr $p/dot`) is
+acme's `dot=addr`. A write is a pair or an address expression; a pair is
+checked as an address is, `addresses out of order` (`5 2`) or `address out of range` (past the text), never clamped. #file("addr") names where
+#file("data") reads (to the end of text) and the range #file("xdata")
+reads; #file("dot") is the selection (moving it scrolls the pane there);
+#file("limit") bounds the end of a forward search and reads empty until
+set. Truncating #file("dot") empties it, truncating #file("limit") lifts
+it.
+
+- A write to #file("data") or #file("xdata") *replaces* the #file("addr")
+ range (`>` and `>>` alike); `: > data` deletes it. Truncating
+ #file("data") is pardes's own (acme ignores OTRUNC there); only
+ truncating #file("body") empties the buffer.
+- A write leaves #file("addr") just past what it wrote, so a second
+ `echo x > data` inserts after the first: write #file("addr") before each
+ replacement. A read of #file("data")/#file("xdata") moves #file("addr")
+ past what it read.
+- #file("addr") belongs to the pane, not the client, and neither an open
+ nor a truncation resets it (acme resets on first open): each
+ `echo /re/ > addr` searches on from the last, so a find loop advances.
+ Write `0` to start at the top; searches wrap, so stop a loop when the
+ address comes back or set #file("limit").
+- A failed address leaves *no address*: #file("addr") reads empty and
+ #file("data")/#file("xdata") refuse (`no address: the last one written to addr failed`) until a standalone address (`2`, `#0`, `/re/`) is written,
+ so a missed target is never written at the old one.
+
+Addresses are sam's: `#n`, a line number, `/re/`, `?re?`, `-/re/`, `$`,
+`.`, `0`, ranges `a,b` and `a;b`, `+`/`-`. They are evaluated from the
+current address (the last written to #file("addr"), or just past the last
+#file("data") write), not from the selection. pardes adds `12:5`: line 12,
+*byte* column 5 from 1, clamped to the line's end (`12:0` is `address out of range: a column counts from 1`); it composes (`12:5,14:1`). A tool's
+character column matches only on an ASCII line; elsewhere use `12/name/`
+or `#n`. A row of #word("Recent"), `+Search` or the #word("Jumplist")
+spells a range `12:5-14:2` (through 14:2 inclusive) and #file("addr")
+takes it as such.
+
+Offsets and counts are bytes everywhere (acme counts runes), but every
+address lands on a rune boundary: `#n` or `L:C` inside a rune snaps to its
+start, a match covers the runes it touches, and a combining mark or a
+CRLF's `\r` is addressable alone.
+
+Refusals: `invalid address: this pane has no text to address` (#file("addr"), #file("dot")
+and #file("limit") on a terminal, an image or a PDF), `bad address syntax`, `no match for regexp`, `address out of range`, `addresses out of order` (`#100,#50`), `bad regular expression`.
+
+sam details kept: `$-1` is the last line when the text ends in a newline,
+else the one before; with a final newline the empty place after it is a
+line (`1` of an empty text is `#0,#0`, so #word("Edit") `1i/x/` works on an empty
+file); `2,1` is an empty range at line 2's start; `/^/` finds the empty
+place after a final newline; a pattern that can match empty (`^`) passes
+over the match where the search starts.
+
+== Regular expressions <regexp>
+
+Patterns are mvzr's (classes, `\d\w\s`, `{m,n}`, lazy `*?`), searched as
+sam searches, line by line: `^` and `$` match at any line's start and end,
+`.` and `[^...]` never match a newline. The same code (`src/regexp.zig`)
+serves addresses, #word("Edit"), and normal mode's #key("s") and #key("S"). The
+ceiling:
+
+- The leftmost match wins, but among alternatives the first that matches,
+ not sam's longest (`/gam|gamma/` finds `gam`). mvzr keeps no submatches,
+ so #word("Edit")'s `s` has no `\1`-`\9`.
+- A pattern holding `\n` runs over the whole text: there `^` may only come
+ first and `$` only just before a `\n`, else it is refused.
+- An alternation must anchor every branch with `^` or none (`^def|^ `
+ works, `^def|x` is refused: `an alternation anchors every branch with ^ or none`). A `$` does not count: `foo$|bar` is fine.
+- A class may hold non-ASCII runes (`[éa-z]`, a range up to 256 runes); a
+ wider range or a negated class with one (`[^é]`) is refused.
+- At most 512 operations (about 512 characters, counted after that
+ rewriting): `bad regular expression: longer than mvzr's 512 operations (about 512 pattern characters)`.
+- Each search has a step budget (about 300 ms; each search of an #word("Edit") `x`
+ its own): `regular expression search took too much time, gave up`. What
+ runs out is exponential backtracking (`a?` twenty times then twenty
+ `a`s) or a quadratic pattern over a very long line.
+
+== Edit <edit>
+
+#word("Edit") `<sam commands>` on a pane's #file("ctl") or #file("exec") (or the
+root's, at the pane with the keyboard) runs acme's #word("Edit") over the open text
+panes, from that pane's body. Addresses are as above, and `"re"` is the one
+open file whose line matches. Commands:
+
+- `x y g v c a i d s p = m t u` and `{ }`.
+- `X`/`Y` run a command in each open file whose line (` +. /path`, `'` when
+ edited) matches, or does not, in the order the panes were opened (as
+ #file("index") lists them): `X/'/w` writes every edited file.
+- `b` makes a file current; `B` opens files, every name checked before any
+ opens; `D` closes panes (an edited one on the second asking, as
+ #word("Del")).
+- `e` loads a file over the whole text as #word("Get") `file` does, once the
+ rest of the Edit is done: the pane takes its name and is clean, one undo
+ step puts both back, and unsaved edits are asked about once (a scratch
+ under 100 bytes is not); the file
+ takes no other command in that Edit. `r` reads a file over dot. `w` writes
+ all of it, or the address, to its file or a name; all of it to its own
+ name leaves it clean. A `w` to its own file changed on disk since it was
+ read is refused once, as #word("Save") is (`modified on disk since read (w
+ again to overwrite)`), and the next `w` writes it; in an `X` the other
+ files are written, and the refusal names those it left. `f` names the pane and prints its line. File names
+ are relative to the file's directory, and `~` is the home directory.
+- `<cmd` replaces dot with what `cmd` writes, `|cmd` pipes dot through it,
+ `>cmd` sends dot to it and prints what it writes.
+
+Each command runs in its file's directory through #word("Shell"), off the
+loop, so the editor goes on, with what a pane's command is given:
+`$PARDES_MOUNT`, `$PARDES_9P`, `$PARDES_PID`, and `$winid` the Edit's pane. The write that ran the Edit is held and
+answered when they are done, its connection serving other requests
+meanwhile (a command may read the session through its mount). A command
+that writes the #file("ctl") its Edit came by needs `<>` on both sides, the
+Edit's write (`exec 3<>$p/ctl; echo 'Edit ...' >&3`) and its own (`1<>`):
+with `>` or `>>` on either, the kernel holds the second write until the
+first is answered, the command is stopped at its 10-second limit, and the
+Edit fails (EIO), changing nothing. For the same reason a second Edit written
+with `>` to that #file("ctl") waits for the first to finish rather than being
+refused; through its own `<>` open, or another pane's #file("ctl"), it is
+refused `busy` (EBUSY) at once. A flush of the Edit's write (an interrupted
+writer) kills the commands and changes nothing.
+Such an Edit is a write of its own: one with other lines is refused before
+any runs. One Edit's commands run at a time in a session, at most 1024 of
+them. While they run, an Edit with no commands runs as usual unless it
+would change, undo, rename, close or write a file the running one changes;
+that, and a second Edit with commands, is refused `busy` (EBUSY), as are
+#word("Del") (acme's `delete`), `rmdir`, #word("Undo"), #word("Redo"), #word("Get") and #word("Zerox") on a pane
+it changes or runs a command on; a session that ends lets the commands go. A command that fails (an exit status, 10 seconds, 1 MiB of output)
+fails the Edit, its stderr in `+Errors`. Each file's changes are one undo step, applied only if
+every command succeeds; a failure changes nothing and fails the write with
+acme's words (`Edit: no substitution`), as does a file edited while the
+commands ran. An `x` that finds nothing succeeds silently. `p`, `=` and `>`
+print to the directory's `+Errors`. Not there: `B <cmd`, `D <cmd`, the `'`
+address, `\1`-`\9`. In `s`, `&` is the match (`\&` a literal); in `c`, `a`,
+`i` it is a literal. `y` yields the stretch before the first match too.
+Braces take a command a line, so a block goes on one open, in one write or
+several:
+#cmd("printf 'Edit ,x/foo/{\\ni/</\\na/>/\\n}\\n' > $p/ctl")
+
+== Flags and undo <flags>
+
+#file("dirty"), #file("mark") and #file("scroll") read and take `0` or
+`1`: the buffer differs from its file (a file deleted on disk counts); a
+write pushes an undo point (writing `1` pushes one now); a write scrolls
+the pane. #file("/index")'s dirty flag is #file("dirty"); a `+New` scratch
+reads 1 but holds up nothing under 100 bytes.
+
+The writes of one open of #file("data"), #file("xdata") or #file("body")
+are one undo step (so a multi-line `printf` is one), as long as no other
+client or keystroke edits the pane between them: such an edit ends the
+step, and the open's next write starts another. To make a loop of opens
+one step: `echo 1 > mark` (a point now), `echo 0 > mark`, the writes,
+`echo 1 > mark`.
+
+== event <event>
+
+Holding #file("event") open takes the pane's #word("Look") and #word("Exec") clicks: they
+come to the reader as records instead of acting, as do lines written to
+the pane's own #file("look")/#file("exec") (or the root's while it has the
+keyboard). A record is acme's `<origin><action><q0> <q1> <flag> <n> <text>\n`; read `n` *bytes* of text, which may hold newlines. Reads may be shorter
+than a record: a record arrives in pieces across reads, so a shell's
+`read` loop works. One open
+reads a pane's #file("event") at a time, as acme's is one window's: a
+second open for reading fails `file in use` (EBUSY) until the first is
+closed. A reader whose pane has closed reads EOF.
+
+- origin: `E` a 9P write to body or tag, `F` other files and the editor's
+ own lines, `K` keyboard, `M` mouse.
+- action: `X`/`L` #word("Exec")/#word("Look") in the body, `x`/`l` in the tag (offsets
+ into the whole tag, path included), `I`/`D` body text inserted/deleted,
+ `i`/`d` the tag's.
+- flag: 1 the text's first word is a builtin, 4 (#word("Look")) a file name or
+ address, 8 (exec) chorded: two records follow, the argument and where it
+ came from. pardes never sends flag 2.
+- A written line, or a click in a terminal's body, has no place: `0 0`
+ with its text (`FX0 0 1 6 Msg hi`).
+
+Write a record back to have it done as the click would: `<o><a><q0> <q1>\n` acts on that range (the last record of a write needs no newline),
+and an empty one (`MX12 12`) on the word or file name a click there expands
+to; the whole record as read acts on its text (the only way for `0 0`). A
+chorded record with its two follow-ups, in one write or three, runs once
+with its argument. A record written back that runs a builtin which fails
+(a refused #word("Del")) fails the write, EIO with its `err`, as an
+#file("exec") write would. `I`, `D`, `i`, `d` are refused; the origin must be `E`, `F`, `K` or `M`,
+and a number larger than a range can hold is refused `bad number`,
+EINVAL. A helper holding
+#file("event") that writes its own pane's #file("exec") gets its command
+back as a record: run it through #file("ctl") instead.
+
+== REPLs <repls>
+
+#word("Repl") `python` on a terminal's #file("ctl") (or in its tag) binds it as
+that language's REPL: #word("Exec") (or #key("Tab")) on a `.py` body
+then types the text into the REPL instead of running it; builtin words,
+tag words, #word("Exec") `<text>` and #raw("@`cmd`") words still run. #word("Repl")
+takes the languages a code fence names (ada, bash, c, c_sharp, clojure,
+cpp, css, elixir, erlang, fortran, go, haskell, html, java, javascript,
+json, kotlin, ocaml, markdown, pascal, php, powershell, python, ruby, rust,
+scala, typst, zig) and aliases such as `py` and `sh`. Its tag and
+#file("ctl") line show its id, `python-a`. #word("Repl") `-` unbinds, bare
+#word("Repl") says the binding. With several bound, the pane asks (`ask <serial> repl a b`). Bindings are not dumped.
+
+A 9P #file("exec") is never sent to a REPL. A script either writes the
+event record `MX<q0> <q1>` to the `.py` pane's #file("event") (sent as the
+click would be), or writes the REPL's #file("pty/data") itself: multi-line
+code as a bracketed paste, `\e[200~<code>\e[201~`, then `\r` in a separate
+write once the REPL has echoed the paste; a paste of more than one line
+not ending in a newline needs a second `\r`. Line by line, a blank line
+ends a Python block and Python 3.14 auto-indents each line.
+
+= Terminals <pty>
+
+Terminal panes also have #file("pty/"):
+
+- #file("pty/data"): write bytes as typed (`printf 'ls\r'`, `\x03` is
+ Ctrl-C); read the live output stream (a consuming queue shared by
+ readers, not a replay).
+- #file("pty/status"): one line, `cols rows busy`; busy is 1 while a
+ command runs or text is typed at the prompt. A terminal whose program was
+ killed on the alternate screen is at its prompt once the shell draws one
+ there: busy is 0, and the next #file("pty/run") reads its output whole.
+- #file("pty/ctl"): `winsize C R` (at least 2 rows, fewer refused `invalid winsize: at least 2 rows`; at most 4096 a side), `sig INT|TERM|HUP|QUIT|KILL`, `exec` (restart the shell in its directory:
+ refused on a command pane, `a command pane does not restart`; `exec: <dir>: no such directory` if it is gone; a shell that cannot start fails
+ and leaves the old one running).
+- #file("pty/run"): one line a write (two lines in one write are refused
+ whole; through a mount a shell's `printf` of two lines arrives as two
+ writes, so the first runs and the second is refused EINVAL), at the
+ shell's prompt, answered on the same
+ open: #cmd("exec 3<>$m/pane/$n/pty/run; echo make >&3; cat <&3; exec 3<&-")
+ The answer's first line is the header: `exit N` then the command's output
+ (as the screen showed it: no colour, tabs expanded to blanks, `\r`
+ progress collapsed, trailing blanks dropped; a paging command's text
+ goes to a `+Pager` pane through the terminal's `pardes -` pager; the last 64 KiB, `exit N cut M` when M bytes were left
+ out, bare `cut` only when the start of that output scrolled out of the
+ scrollback; after a `clear`, the answer is what the command printed from
+ the clear onward). Or: `busy: <program> is running` (bare `busy` when text is typed at the prompt, `busy alternate screen` on the alternate screen with no prompt drawn),
+ `exit ?` (no status reported, not a success), `error not run` (the shell
+ refused the line, e.g. a fish syntax error), `error shell gone`, `error no prompt marks`, and on a command pane `error a command runs here, not a shell` (`error command done; not a shell` once it ended). A line written
+ before a fresh terminal's first prompt waits for it. One line per run; a
+ second line before the answer is refused.
+
+#file("pty/run") relies on the OSC 133 marks pardes injects into bash and
+fish; `exec zsh` or a continuation prompt never reports an end, so cancel
+the read. A program on the alternate screen (vim, less) leaves no output.
+A program holding the terminal (a REPL, `less`) takes no run: write to
+#file("pty/data").
+
+= The log <log>
+
+One 64 KiB ring, one record a line, kept whether or not anyone reads it.
+An open freezes it and reads to EOF. Write `follow` to that open to then
+wait for each new record (`follow new` skips the history, as `tail -n0 -f`); `tail -f` never writes `follow`, so it sees nothing new. A follower
+the 64 KiB ring outran (it keeps only the newest records) reads `lost N` first. A #word("Restore") hangs the follower up: dial
+again and read from `restore <path>`. A follower's read held when the
+#word("Restore") comes takes every queued record that fits first, so records written
+just before the #word("Restore") are not lost.
+
+#pairs(
+ [`new <serial> <name>`, `del`, `rename`, `save`], [a pane made, closed, renamed (a terminal's too, as its shell changes directory), saved (#word("Save") `path` of a copy: `save <serial> <path>`, the path written)],
+ [`newcol <serial>`, `delcol <serial>`], [a column made or closed],
+ [`msg <serial|-> <text>`], [the editor said something (not a builtin's own name under #word("Verbose"))],
+ [`err <serial|-> <file>: <why>`], [a write was refused or failed],
+ [`run <serial> <line>`, `exit <serial> <N|?>`], [a command pane's command started and ended; also a terminal whose shell exited, before its `del`],
+ [`send <from> <to> <repl-id>`], [text went to a REPL],
+ [`ask <serial> <what> <choices>`, `answer <serial> <choice|->`], [a pane asked, and was answered (`-`: taken back, or the pane closed)],
+ [`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
+#file("look")/#file("exec")), `-` for the root #file("ctl"),
+#file("/tagexec") and column files. A record said again straight after
+itself is counted, `err 3 addr: no match for regexp (x4)`; a follower sees
+each count as a new line. A `msg` is cut at 256 bytes and an `err` reason
+at 200, ending in `…`. Control characters become spaces.
+
+= Other files <other-files>
+
+- #file("/screen"): JSON `cols`, `rows`, `cursor`, `styles`, and row-major
+ `cells` of `[grapheme, style_index]`; one frame per open. Compare a
+ cell's style through `styles`, not the index.
+- #file("/commands"): `Word [arg] root|pane|both [values] -- sentence`, one
+ a line, generated from the builtin registry (`both`: #word("Edit"), at the active
+ pane from the root).
+- #file("/recent"): up to 200 files, PDFs and images, most recent first,
+ `open <path>` or `closed <path>` (open in this window or not), every
+ window's: kept in `$XDG_STATE_HOME/pardes/store`, shared by every pardes
+ process, each reading what the others wrote when it is next read.
+ #word("Recent") lists them in a query pane (line 1 `Recent`, the rest
+ narrowing them by a fuzzy match), an open one at its dot now and a
+ closed one at its last (a PDF's is its page); a #word("Look") of a row reopens it
+ there.
+- #file("/status"): `pid`, `version`, `panes`.
+- #file("/pager"): write a directory, `~` expanded and resolved (an empty
+ line is the session's; one not there is refused ENOENT, a relative one
+ EINVAL, one you may not write `permission denied`, a regular file `not
+ a directory`, ENOTDIR), one line; what follows that line, on the same open, is the text to
+ page, escapes and all. A read of that open answers the serial of a new
+ `+Pager` in the directory, once the text is in. This is what
+ `pardes -` uses; from a directory you may not write, it pages into a
+ `+Pager` of the session's.
+- #file("/listeners"): the session's dial addresses, a line each
+ (#doc("building", section: "listeners")).
+- #file("/os/"): existing regular files take read, write and truncation to
+ zero; create, remove, rename and mode changes are refused as not
+ permitted (`permission denied`, EACCES through a mount); ownership is
+ synthetic. Linux v9fs's truncation `mtime` hint is accepted and dropped.
+- #file("/src/") (and #file("/shaders") on GUI builds) with
+ `-Dembed-sources=true`; #word("EffectCode") `<effect>` lists an effect's files
+ under `/virtual`.
+
+= The pardes command <command-line>
+
+In a pane's shell (`PARDES_PID`, `PARDES_9P` and `PARDES_PANE` set),
+`pardes FILE` writes FILE to that pane's #file("look") and returns at once;
+a FILE not there yet opens an empty pane that #word("Save") creates, making
+its directories. What the session refuses (a bad name; a name under a
+directory you may not search or write, `permission denied`) is printed and
+the exit is 1. `--` ends the options (`pardes -- -name`).
+`pardes --wait FILE` (`-w`; bare, it says it needs a FILE) returns 0 when the pane showing FILE is
+deleted, 1 when the session goes away (against a dead `$PARDES_9P` it
+says the session is gone); with
+`PARDES_9P` set but no pane of its own it opens FILE in that session and
+waits there. Bare `pardes` in a pane refuses and names `--nested`, which
+starts a separate session whose shells do not forward to it.
+
+= Placement <placement>
+
+#word("Placement") `acme` (the default) puts a new pane in the column whose tag
+asked, else the active column (last typed or left-clicked in,
+dropped into, its tag given the keyboard, or given the last new pane),
+never a new column. An empty column it takes whole; #word("New") and
+#file("pane/new") take the bottom half of the column's last pane; a pane
+opened from a pane's text (#word("Look"), #word("Tty"), #key("Alt-n")) goes under
+the pane with the most blank rows, or halves the biggest. #word("New") in a
+pane's tag names its `+New` in that pane's directory and column; from a
+column tag, in that column and the session's directory. A command pane
+goes to the last column, or the column whose tag ran it, under either
+placement. #word("Placement") `pardes` fills an empty column whose tag asked or has
+the keyboard, puts a scratch or a shell under the pane that asked, and a
+document beside the last one read (or in a column of its own on a wide
+screen). No pane is made shorter than its tag and two rows; with no room
+the pane is refused.
+
+A command pane runs in the directory it started in, whatever its command
+does with `cd`, and a relative #word("Look") in it resolves there. The next command
+for that directory reuses a finished one (from a column tag, only one in
+that column); one still running, one a background job still prints to, or
+one a #file("exec") open still holds is never reused. In a command pane, #key("n") walks that pane's own `file:line` places first (make's errors), whichever pane was walked last, then on through the others.
+
+= Find and Grep <find-grep>
+
+Both fill the asking pane's query pane (#doc("guide", section: "search")),
+line 1 `Find name` or `Grep text`, and run on a worker thread, never on
+the loop that draws: `rg` when it is on `PATH` (`rg --files` and `rg --json
+--fixed-strings --smart-case`, so `.gitignore` is honoured and hidden files
+are passed over), else pardes's own walk, sorted, 16 deep, passing over
+dot-directories, `.git`, `.jj`, `target`, `node_modules`, `.venv`,
+`__pycache__`, `.zig-cache` and `zig-out`. #word("Find") lists the files once
+and matches their names fuzzily at each key (the best first, 200 shown);
+#word("Grep") matches the text of lines literally, any case unless the text
+has a capital, once the typing pauses (80 ms), and stops at 2000 lines:
+#word("More") (in the query pane's tag) goes on for 2000 more. A directory the
+walk could not open is said under the rows: `N directories skipped:
+permission denied`. A new query cancels the last; rows of a query no
+longer asked never land. Written to #file("exec") (a script) the search runs
+to its end before the write is answered, and one that finds nothing fails,
+`Grep: text not found`, `Find: name not found`, its query pane's count `0`.
+
+= On screen <on-screen>
+
+- *Esc at a prompt* (with #word("ProgramEsc") on). pardes knows a shell prompt with nothing typed on it
+ from the OSC 133 marks it injects into bash and fish (marks a shell sends
+ itself do not count); for other shells, from no program holding the
+ terminal, typed text or not.
+- *A program's mouse.* A program that tracks the mouse (htop, vim with
+ `mouse=a`) gets the left button's clicks and drags and the wheel over its
+ grid; Shift-#btn("B1") selects and Shift-wheel scrolls pardes's
+ scrollback, while Shift-#btn("B2") and Shift-#btn("B3") go to the program.
+ A full-screen program that does not track the mouse gets the wheel as
+ arrow keys. Tags, grips and gutters stay pardes's.
+- *Diffs.* A `---` line opens the old file unless the `+++` under it names
+ 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.
+- *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
+ notice and `err - init file line N: why`, and the rest still run; a
+ 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
+ two lines (build, time, platform, pid; the panic message) to `crashes`
+ beside `init`.
+
+= pardes - <pardes-stdin>
+
+`pardes -` reads stdin to its end and shows it in a new `+Pager` pane of
+the directory, left clean, opening at its top, with no line numbers; a
+`+Pager` already there keeps its page. The session parses the text with
+ghostty-vt: SGR colours become the `+Pager`'s own display, never part of
+its body or any read (#word("PagerColor") `off` pages plain), mapped
+through the theme as a terminal's are until its #word("Filter") shows them
+as sent; every other escape is dropped; a carriage return keeps a progress line's last state,
+and CRLF becomes LF. Empty stdin shows nothing. Inside a pardes pane it returns at once; a text the session cannot
+take is printed to stderr with why, and the exit is 1. From a directory
+whose name holds a newline or control byte, the pane is the session
+directory's. Outside a pardes pane it starts a new editor whose first pane
+the text is. Stdin up to a file's limit (256 MiB) arrives whole; past that
+it is cut, with a note saying so.
+
+With #word("Pager") `pardes`, a terminal's shell gets `PAGER`, `GIT_PAGER` and
+`SYSTEMD_PAGER` set to this pardes plus ` -` (the path quoted only when it
+needs it), and `SYSTEMD_PAGERSECURE=0` (it has no shell escape), each only
+where your environment does not set it. `man` pages through `MANPAGER`
+first, then `PAGER`; your own `MANPAGER` wins.
+
+= Other ways in <other-clients>
+
+A session listens on `$XDG_RUNTIME_DIR/pardes-9p-<name>.sock` (else under
+`~/.local/state/pardes`), `<name>` the pid, the `--detach=NAME` or
+`--9p=NAME`, and posts it in the 9P registry as
+`$XDG_RUNTIME_DIR/9p/pardes/<name>`. Its pane shells get `PARDES_PID`,
+`PARDES_9P` and `PARDES_PANE`. A dead session's registry entry stays
+listed and answers `Input/output error`: name the session, never glob.
+Under `9ns --mntgen` (which sets `NINE_MNTGEN=1`) a session is at
+`$NINE_MOUNT/<service>/<name>`, pardes's `$NINE_MOUNT/pardes/<name>`, and
+every pane pardes spawns gets it as `$PARDES_MOUNT`. Under `9ns --unix SOCK
+-- cmd` the session is `$NINE_MOUNT` itself, and `$PARDES_MOUNT` is unset.
+plan9port's `9p write` opens with OTRUNC, so on #file("body") it replaces
+the whole text. To append, use `>>` through a mount. Through a FUSE mount
+bash's `read -t` cannot time out: wrap a follow loop in `timeout`. The
+scripting chapter's rule (a mount, else `9p`) covers most uses. Two more:
+
+- #word("Tty9p") (#key("SPC n 9")) opens a terminal with the session
+ kernel-mounted (Linux v9fs): it asks for your sudo password in the pane,
+ mounts the socket in a private mount namespace and starts your shell as
+ you, with `PARDES_MOUNT` naming the mount. Only that shell sees it, and
+ each takes one of the session's 16 connections. It needs the `9p` and
+ `9pnet_fd` kernel modules and the `pardes-v9fs` helper the build installs
+ beside `pardes`.
+- `test/ninep.py` is a Python 9P client that exists only in the source tree
+ (it is not installed). It is for when nothing is mounted and `9p` is not
+ there, or when a fid must stay open (#file("event"), #file("pty/data"), a
+ followed #file("log")). Its paths are the served root:
+
+```python
+import sys
+from ninep import Client # PYTHONPATH=test
+with Client(sys.argv[1]) as c: # a socket path, or (ip, port)
+ print(c.read('/index').decode(), end='')
+ n = int(c.read('/pane/new'))
+ fid = c.open(f'/pane/{n}/event', 0) # hold event: clicks come here
+ c.write(f'/pane/{n}/exec', b'Msg hi\n')
+ print(c.read_fid(fid, 0, 4096)) # b'FX0 0 1 6 Msg hi\n'
+ c.close(fid)
+ c.remove(f'/pane/{n}')
+```
+
+`client.screen()` returns the parsed #file("/screen").
+
+= Coming from acme <from-acme>
+
+#pairs(
+ [`$NAMESPACE/acme`], [not posted there: a session is `$XDG_RUNTIME_DIR/9p/pardes/<name>`; reach it with `9p -a "unix!$PARDES_9P"` or a `9ns --mntgen` mount (#doc("fs", section: "other-clients"))],
+ [`N/`], [#file("pane/N/"), N the pane's serial],
+ [`new/ctl`], [read #file("pane/new"): it makes a pane and answers its serial; `rmdir pane/N` closes it],
+ [`index`], [#file("index") lines are serial, kind, dirty, name, column (acme: id, tag and body lengths, isdir, dirty, tag)],
+ [rune offsets], [bytes everywhere, event offsets and counts included; addresses snap to rune boundaries],
+ [`addr` reset on first open], [#file("addr") is the pane's; no open resets it (write `0`)],
+ [OTRUNC on `data` ignored], [`: > data` deletes the addressed text; OTRUNC on #file("body") (`9p write`) replaces it all],
+ [event flags 1, 2, 4, 8], [1, 4 and 8; never 2, so no expansion record follows],
+ [`Get`], [#word("Get") reads the file again, refusing unsaved edits once (a scratch under 100 bytes unasked, as #word("Del") closes it; a file not there, or a directory, is said first); `Get file` loads that file into the pane, which takes its name, and one that fails changes nothing; #word("Undo") after it, or after #word("Edit")'s `e`, puts the old name back with the old text and its saved state; in a directory pane #word("Get") reads the directory again and `Get file` is refused (#word("Look") opens the file) (also `get` on #file("ctl"))],
+ [`Put`, `Delete`, `Load`], [#word("Save"); a #word("Del") that does not ask; #word("Restore")],
+ [`Putall`], [#word("Putall"): every pane with unsaved edits to a file is saved, a #word("Zerox") pair once, a refused one said; with a refusal, its write is answered once the other saves have landed],
+ [`Zerox`], [#word("Zerox"): a second pane on the buffer, one text, undo and unsaved state, its own scroll and cursor; an event reader on one hears no edit made through the other; the twins are kept across #word("Dump") and #word("Restore")],
+ [`Tab`], [#word("Tab") `N`, 1-16: for every pane, not per window; bare, it says the width, from the root's #file("ctl") as from a pane's #file("exec")],
+ [`Incl`], [#word("Incl"): for the session, not per window, seeded with `/usr/include` and `/usr/local/include`; it takes absolute (or `~`) directories that exist, and `Incl -` alone clears the list; a name found nowhere else (`stdio.h`, `<stdio.h>`) is tried there],
+ [`Indent`], [always on: #key("Enter"), #key("o") and #key("O") keep the line's indent as it is],
+ [`Snarf`, `Cut`, `Paste`], [refused: the chords, #key("y"), #key("p")],
+ [`Font`, `Send`, `ID`], [#word("Font"); #word("Repl") and #word("Exec"); `$winid`],
+ [acme's other builtins], [refused: `Sort`, `Local`, `Abort` (plan9port's debugging word)],
+ [Edit], [every acme command but `B <cmd`, `D <cmd` and the `'` address; no `\1`-`\9`, and an alternation takes the first branch that matches, not the longest; a failing `< | >` command changes nothing, where acme puts in what it wrote (#doc("fs", section: "edit"))],
+ [`win`], [#word("Tty") is a VT terminal pane; #file("pty/run") runs a line at its prompt and answers `exit N` and the output; with #word("Repl") bound, #word("Exec") on a source pane types the text into it],
+ [a directory window], [as acme's: a text pane named `dir/` (#file("index") kind `text`, #file("ctl") isdir 1), its entries in columns sorted bytewise, dotfiles shown, a directory's marked `/`; blanks pad the columns where acme's tabs do; a #word("Look") at an entry is from that directory, `Get` or a look at it again reads it again, and an edit is kept until then rather than lost to a resize; never dirty, #word("Save") refuses it; #word("DirLook") `terminal` types `ls` into a terminal there instead],
+ [the plumber], [none: #word("Look") on an `http://` or `https://` URL runs `xdg-open` (`open` on macOS); files, addresses and directories follow built-in rules],
+ [#key("Esc") selects what was typed], [#key("Esc") leaves insert mode, or goes back a pane (#doc("tags", section: "modes"))],
+)
+
+= Limits <limits>
+
+#pairs(
+ [panes], [64],
+ [columns], [16, each at least 10 cells wide],
+ [rows a pane keeps], [its tag and 2],
+ [msize], [65536 (64 KiB) offered],
+ [connections], [16 Unix and TCP, 16 QUIC],
+ [open records], [64 a session, every client's together],
+ [held reads a connection], [128],
+ [named mounts], [8],
+ [command line], [1024 bytes; a held line or #word("Edit") block 1 MiB],
+ [tag text], [4096 bytes],
+ [regular expression], [512 operations; a step budget per search (about 300 ms)],
+ [undo], [256 steps],
+ [log], [64 KiB ring; `msg` 256 bytes, `err` reason 200],
+ [`pty/run` output], [64 KiB],
+ [file name component], [255 bytes],
+)