summaryrefslogtreecommitdiff
path: root/docs/next-daemon.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-29 17:58:06 -0300
committerGabriel Schneider <[email protected]>2026-10-29 19:38:53 -0300
commit74286e81e88a6df7586ead9e8bcd503d44446a85 (patch)
tree0c03cdcc8cd61096d53d6610ef0f0fc9698cfb6e /docs/next-daemon.md
parent3a5db21504a653cc5e97b98edad59a6262a3b8e9 (diff)
downloadpardes-74286e81e88a6df7586ead9e8bcd503d44446a85.tar.gz
pardes-74286e81e88a6df7586ead9e8bcd503d44446a85.zip
docs: views in the guide and reference (a session attached already takes another view, up to four; Detach lets one go); phase 4 notes in docs/next-daemon.md; tty: Screen.hungUp reads a test terminal's fd as the test build has it
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Diffstat (limited to 'docs/next-daemon.md')
-rw-r--r--docs/next-daemon.md124
1 files changed, 124 insertions, 0 deletions
diff --git a/docs/next-daemon.md b/docs/next-daemon.md
index e3be6af8..b5939b9d 100644
--- a/docs/next-daemon.md
+++ b/docs/next-daemon.md
@@ -271,6 +271,130 @@ termios` into Zig's `std.c.termios`, which is 44 (the kernel's layout),
and overran the stack, clobbering a neighbouring local in the forked
child; `std.posix.tcgetattr` (an ioctl on that layout) is the right one.
+## Phase 4 notes
+
+Built 2026-10-29 (`src/views.zig`, the tty and GUI hosts, `daemon.zig`,
+the snapshot harness and the monkey). Decisions taken at the forks, with
+the ponytail lens:
+
+- **A view is swapped in, not pointed at.** The ~1,900 references to the
+ core's layout, focus and pane state stay as they are: the core sees one
+ view, the live one, in the fields it always had. A view's share of the
+ session is a list of field names (`views.fields`, ~60) made into a struct
+ by one comptime `@Struct` (`Part`), and of each pane a struct beside it
+ (`PaneView`, in `Pane.pv`); going into view `k` copies the live one's out
+ (`park`) and `k`'s in (`unpark`). Copies, not swaps: a slot is stale
+ while its view is live and written whenever it goes out, so no two places
+ own a selection's heap. One view never parks: the single client pays
+ `views.several` (an AND and a compare) in the pump, the step's sync and an
+ edit, and one store a key (`typedInto`). Rejected: a `*View` the core
+ reads through (every reference rewritten, an indirection on every
+ access); a twin pane per view (Zerox exists only for files, and a
+ terminal's pty is its pane's slot).
+- **Where each piece of state went.**
+ - Each view's own (`views.fields`): the screen size and cell metrics;
+ the columns, their weights, panes, serials, tags and the finder; rects;
+ `active`, `active_column` and the header focus; the jump list (kakoune's
+ is per client); the pointer, hover, drag, mouse grab, clicks and chords;
+ key prefixes (`"x` register name, leader, Ctrl-w, window pick); a
+ pending clipboard read; the presentation and the animations (lifts,
+ cursor glide); `windowed`, `native_images` and `native_image_patches`,
+ which the census had as watched host writes: a tty view on kitty and
+ one on a plain terminal differ. The 223 comptime platform branches stay
+ comptime: a session is one build, which the semantics hash says.
+ - Each pane's, each view's own (`PaneView`): `vweight`, `collapsed` and
+ `attached_to` (a layout's); `focus`; the body's mode, cursor,
+ selections, sticky column, pending normal command and find; a document's
+ scroll, `hscroll` and size; and what the step measured for that view
+ (`tag_rows`, `tag_top`, `tag_scroll`, `view`, `notices`), so a view drawn
+ without a step of its own draws its own geometry.
+ - The session's, every view's: the panes' text, undo, terminals and
+ their scroll (tmux shares a pane's copy mode too), tags (acme's are
+ per window; one tag per buffer is one text, its caret included), the
+ workspace tag, prompts, messages, registers (decided), the macro being
+ recorded, look-hover (one pointer at a time), mouse sweeps, query
+ panes, search state, settings and theme, the effect and input queues,
+ `needs_frame` (any change draws every view).
+- **A terminal shown at two sizes** takes the size of the view that typed
+ into it last (`Pane.sized_by`, set by a key or a paste; a new pane's is
+ its maker's; a closed view's goes to the next to sync it). The others show
+ it at that size: `sync` resizes no pty for them, and `pane.cols/rows`
+ stay the terminal's own, so the terminal code's invariant (pane size is
+ the emulator's) holds. ponytail: a smaller view sees its top rows, cut;
+ panning to the cursor as tmux does is the upgrade, if a small view must
+ follow a shell it never types into.
+- **Panes come and go under parked views.** A view keeps the serial of
+ each slot when it goes out; unparked, the ids whose serial changed leave
+ its layout and its keyboard moves to its first pane left. A pane focused
+ in a view that does not show it (a Look at a file another view opened, a
+ jump, a 9P focus) is placed in the view's active column (`views.show`,
+ kakoune's buffer shown in the window that asked). A text edited in one
+ view moves every other view's cursor and scroll with the splice, as a
+ Zerox twin's (`File.ParkedPlaces`); their selections go, as a twin's do.
+- **Drawing the other views stays out of the digest.** The pump draws each
+ other view by unparking it, rendering and presenting, and restores the
+ live one exactly (`drawOthers`): no digested field moves, so the headless
+ replica, which draws nothing and skips it, agrees. What drawing a view
+ makes of its own (its animations, its presentation) is kept; what its
+ unpark normalised (a cursor clamped inside a changed text, a pruned
+ layout) is not, and is done again when it next goes live by an input,
+ in every replica alike. `parked` and `pv` are `.local`: a parked view is
+ checked when it is live again. Found by `pardes-monkey --views=3 --tape`:
+ a drawn view's `post_present` (acknowledgePanelPresentation, which moves
+ the pointer's hover) was applied by the headless replica to the live view;
+ other views take no post_present, their panels acknowledged when they
+ are live and drawn.
+- **Inputs.** `toView`, `openView` and `closeView` are taped. A host goes
+ into a view before the input its client sent: the tty's terminal readers
+ post through a `Poster` that puts a `from` ahead of a terminal's input
+ whenever another terminal posted last (so one terminal posts none, and
+ coalesced motions never cross views); the GUI asks SDL which window an
+ event is for (`route`), which also takes a window's resize to its view
+ (the GUI sizes the live view from its window each frame).
+- **The tty.** Each terminal is a `Screen` of its own: its vaxis, input
+ reader, frame answer (`FrameAck`, was global), kitty images and shm probe
+ (were global), glide, trail and flash, its stub and its Killed slot. The
+ primary's stub stays `daemon.stub`. A SIGWINCH asks every terminal its
+ size (attach stubs forward theirs; another view's terminal is no one's
+ controlling terminal); a SIGHUP asks each whether its terminal or stub's
+ pipe hung up, where it used to mean the one terminal. Detach, or a
+ terminal's end, with views left closes only that view and tells its stub
+ `d`; the session's end tells every stub. ponytail: a bracketed paste in
+ progress is the shell's, not a terminal's: keys from another terminal
+ during it join it.
+- **The GUI.** One `Gui` (device, atlas, fonts, pipelines) and its
+ window's share swapped like the core's (`window_fields`: the SDL window
+ and its presenting, scroll and glide, scene and post chain, pointer,
+ blink, captures); `Shell.follow` keeps the Gui on the core's live view.
+ Closing a window while others stay closes its view; Restore closes the
+ others. ponytail: a second window's compositor hit test reads whichever
+ window's state is in the Gui (the workspace tag is in the same place in
+ every view).
+- **The daemon.** `attach` names an attached session too: it takes another
+ view (a terminal, or a window). With no name, the detached sessions are
+ asked first, then the only session of that kind.
+- **Harnesses, extended not new.** A snapshot script's `start ... views=N`
+ gives the app N-1 more ptys (PARDES_TEST_VIEWS, opened as attached ones
+ from the start), `view <k>` types into and captures terminal k, and every
+ wait reads all of them (a pty nobody reads would block the session's
+ frame); a `resize` there SIGWINCHes the app, as a stub would.
+ `pardes-monkey --views=N` switches among N terminals a quarter of its
+ steps, each with its own size; `zig build replay` runs its seeds at one
+ view and at three. The GUI's test feed takes `ESC]777;view;<k>BEL`, and
+ PARDES_TEST_VIEWS=N opens N more hidden windows, captured under view-k.
+- **What proved wrong in the design.** "Views" in the design were a
+ struct the core reads through; the swap made them cheaper and kept every
+ reference. Its rollback copy (phase 5) is the same list of fields. The
+ design's view-local state assumed a step per view; the step's
+ measurements (`tag_rows`, `notices`, the pane's geometry key) had to
+ become per view too, or a view drawn after another's step drew the
+ other's tag heights. And the census's single "frontend kind" leak is not
+ per process but per client: kitty graphics are a terminal's.
+
+Measured: PERF_TABLE
+
+Gates: GATES_TABLE
+
## FreeBSD notes
Groundwork for phase 5's main test, a client here and the session on the