pardes v2: the rewrite, complete and organized. src/ (core + three shells), test/ (snapshot parity harness + 18 frozen goldens). One sans-IO core, vaxis tty + SDL3 GPU native + wasm web shells, 18/18 parity with the purged prototype, 7.6k lines vs 12.1k. Fix: gui shell pre-sized the core at init so the greet-releasing resize never fired (blank panes until first interaction); live sessions now init at defaults and get the real grid as a resize event (the shell contract, documented on Options).

1 files changed, 412 insertions, 0 deletions

diff --git a/src/tutor.txt b/src/tutor.txt
new file mode 100644
index 00000000..5a93d388
--- /dev/null
+++ b/src/tutor.txt
@@ -0,0 +1,412 @@
+
+                               PARDES TUTOR
+                     tmux + vi + acme, from scratch.
+
+        The model is acme's: EVERYTHING is text, editable and executable
+        the same way. Modal editing (helix-style) lives on top of that.
+        Press j until you reach the introduction.
+
+
+=================================================================
+=                      INTRODUCTION                              =
+=================================================================
+
+ Pardes is tmux + vi + acme, made from scratch. The foundation is
+ the acme model: a pane is just text on screen. There is no separate
+ "buffer" type — what you see is what you edit. Some panes happen to
+ be live terminals (tty mode); most are text you can move a cursor
+ over. Modal editing (helix-style) is layered on top of that.
+
+ Three modes (the tag shows which):
+   nm  NORMAL   block cursor, keys move/edit.  DEFAULT on startup.
+   in  INSERT   keys type text at the cursor.
+   sy  TTY      keys go straight to the shell.  (terminals only)
+
+ This tutor is in THREE parts, ordered by what's most different from
+ editors you may know:
+   PART 1 — the MOUSE. Acme's three buttons; nothing like Vim/Helix.
+   PART 2 — the TTY.  A terminal is just a pane; Ctrl-b drops into it
+             by default.
+   PART 3 — the KEYS.  Helix-style modal (with the Pardes differences).
+
+ PRACTICE BLOCKS (part 3): the "# keys:" line lists keystrokes
+ (space-separated; esc/enter/bs are special, the rest type each char).
+ The clean lines under "# before" are what you practice on; the lines
+ under "# after" are what you should end up with. "# at: row,col"
+ (right after # keys:) sets where the cursor starts. These blocks are also run as unit
+ tests (generated from this file by tutor_gen).
+
+ Hold j to reach part 1.
+
+
+=================================================================
+=   PART 1 — THE MOUSE (acme chording; the most different part)  =
+=================================================================
+
+ Acme's central idea: the THREE mouse buttons each ACT on text, and the
+ keyboard mirrors them. Pardes inherits this. (Vim and Helix have almost
+ none of it — their mouse is selection/scroll only.)
+
+      ┌─────────┬─────────┬─────────┐
+      │    L    │    M    │    R    │
+      │   (1)   │   (2)   │   (3)   │
+      ├─────────┴─────────┴─────────┤
+      │                             │
+      │            ( o )            │   the wheel scrolls the pane
+      │                             │
+      └─────────────────────────────┘
+
+   L  select   a plain click also FOCUSES the pane and PINS the modal
+               cursor where you click, so you can edit there next.
+   M  execute  run the selected text: a builtin name runs it, anything
+               else is SENT to the shell the pane runs. This is how you
+               run a command you typed in a text mode.
+   R  look     open the word under the cursor as a path: a directory
+               opens/focuses a terminal there and ls's it; a file opens
+               a file pane (scrolled to a ":line" suffix if present).
+
+ SELECT-THEN-ACT: there is no held-button chord. Instead:
+   - MIDDLE-drag over text selects AND runs it on release (one gesture);
+     a no-drag middle click auto-expands to the word under the cursor.
+   - or select with the keyboard (`v` chars / `x` lines), then press
+     Tab to execute or Enter to look — the acme chords on the keyboard.
+
+ THE TAG: each pane has a one-line tag: its MODE (nm/in/sy) + directory
+ or file path + builtins. File panes show "Save Del" by default; Save
+ writes the current file to disk, Del closes the window. Terminal and
+ image panes show "Del". "Delcol" still exists as a command: type it in
+ a tag or body and execute it to close the whole column. A SEPARATE bar
+ across the top of the screen holds the window-agnostic builtins:
+   Kill  Newcol  Tutor  Debug  Colors  NextColor
+ Middle-click "Newcol" for a new column, "Tutor" to spawn this tutor,
+ "Kill" to quit; Debug/Colors/NextColor toggle the stats overlay, the
+ syntax/ansi recolor, and the theme.
+ Right-click a directory in any body to open a terminal there.
+
+ LAYOUT: columns split the screen; windows stack within a column. Panes
+ abut with no wasted gap — a pane's own trailing edge (its last column, or
+ last row above the next tag) IS the resize handle: hover it and a dashed
+ line overlays that edge (keeping the underlying colors) to mark the drag.
+   - drag a column's right edge to resize it against its neighbour
+   - drag a window's bottom edge to resize it against the one below
+   - drag the accent box (top-left of a pane; indigo-purple, brighter
+     when the pane is focused) to MOVE a window between columns / reorder
+   - the scrollbar is the gutter below the box: left-click scrolls UP
+     to that point, right-click scrolls DOWN
+
+ (Mouse actions are hard to unit-test from text; they're covered by
+ the e2e suite: middle-click execute, right-click dir/file open, tag
+ builtins, drag-rearrange. See tests.zig steps 6-8.)
+
+
+=================================================================
+=   PART 2 — THE TTY (a terminal is just a pane)                =
+=================================================================
+
+ This is the headline difference from Vim/Helix: there is no "open a
+ terminal in a split" that's separate from "edit a file in a split".
+ A TERMINAL IS A PANE. The same modal keys that edit a file navigate
+ the terminal's screen, and dropping into tty REUSES the shell's own
+ prompt model rather than layering an editor cursor on top.
+
+ On a terminal pane:
+   NORMAL (nm)  prompt rows are HIDDEN — a clean acme-style page. You
+                navigate it with the same h/j/k/l/w/b/e as a file.
+   INSERT (in)  same clean page; keys type an insertion overlay (the
+                command you're composing). Prompts still hidden.
+   TTY    (sy)  the REAL shell — prompts + typed input shown, and keys
+                go straight to the pty as terminal input.
+
+ ESC:    insert -> normal.  (Esc never reaches tty.)
+ Ctrl-b: toggles TTY on a terminal by default — the ONLY way in or out.
+         Use `pardes --tty-toggle=g` (or another letter) to make Ctrl-g
+         the toggle instead. Entering is tty-native: if the shell is at
+         a prompt and your modal cursor sits on the input line, it first
+         moves the shell's REAL cursor to that spot —
+           - empty input  -> shell cursor at the prompt START
+           - typed text   -> shell cursor at/after the char you were on
+         via the shell's OSC 133 semantic prompt (ghostty promptClickMove;
+         our rc opts in with cl=line). The shell moves its own cursor with
+         arrow keys it understands — Pardes doesn't fake one on top.
+
+ ENTER / TAB (in normal) are NOT a way into tty — they're the acme mouse
+ chords on the keyboard: Enter = "look" (open the path under the cursor),
+ Tab = "execute". Both act on the selection if one is active.
+
+ So the flow is: navigate the hidden-prompt page in normal, hit the tty
+ toggle where you want to keep typing, and you're IN the live shell at
+ that spot. No separate "terminal mode cursor" to reconcile.
+
+ (The cursor positioning is enterTty's promptClickMove; it needs a live
+ shell at a prompt. Mouse/tty behavior is exercised by the e2e suite.)
+
+
+=================================================================
+=   PART 3 — THE KEYS (helix-style modal, Pardes differences)    =
+=================================================================
+
+ Same core as Helix and Vim: a block cursor you move with h/j/k/l,
+ motions w/b/e, and you enter insert with i/a/o. The differences:
+
+   - Selection is LINE-first: `x` grows a line selection downward.
+     There's also `v` for a CHARACTER range. No multi-cursor. d/c/y act
+     on whichever selection is active (else the current line).
+   - NO verb+noun (Vim's dw, cw). Motions only MOVE. To delete a word,
+     select it (`v` then motions, or `x` for whole lines) then `d`.
+   - ESC never reaches tty; it only does insert -> normal. Dropping a
+     terminal into the live shell is the tty toggle (Ctrl-b by default;
+     see Part 2).
+   - Enter / Tab in normal mirror the mouse: Enter = look (open the path
+     under the cursor), Tab = execute. `u` undo, `U` redo.
+   - Editing a file pane MUTATES real content; a terminal pane yanks
+     rendered text and pastes it as an insertion run (shell output
+     can't be deleted, only pasted text can).
+
+ PRACTICE: run the keys on the "# before" lines; you should get the
+ "# after" lines. (These blocks are unit tests too.)
+
+
+-----------------------------------------------------------------
+= 3.1 MOVING THE CURSOR (h j k l)                                =
+-----------------------------------------------------------------
+
+          k          * h = left, l = right
+      h     l         * j = down, k = up (also: arrow keys)
+          j
+
+ The cursor sits ON a character (block). Motions only move.
+
+ # keys: l l l
+ # before
+ abcdef
+ # after
+ abcdef
+
+
+-----------------------------------------------------------------
+= 3.2 ENTERING INSERT: i a A I o O                               =
+-----------------------------------------------------------------
+
+ `i` insert at cursor.  `a` insert AFTER the cursor.
+ `A` insert at end of line.  `I` insert at first non-blank.
+ `o` open line BELOW + insert.  `O` open line ABOVE + insert.
+ (All match Vim and Helix.)
+
+ # keys: i X esc
+ # before
+ bcdef
+ # after
+ Xbcdef
+
+ Cursor on 'b' (col 0). `i` inserts before 'b'.
+
+ # keys: a Z esc
+ # before
+ abc
+ # after
+ aZbc
+
+ Cursor on 'a' (col 0). `a` inserts after 'a'.
+
+ # keys: A Z esc
+ # before
+ abc
+ # after
+ abcZ
+
+ `A` jumps to end then inserts — appends 'Z'.
+
+ # keys: I Z esc
+ # before
+   abc
+ # after
+   Zabc
+
+ `I` goes to the first non-blank ('a'), inserts before it.
+
+ # keys: o line2 esc
+ # before
+ line1
+ # after
+ line1
+ line2
+
+ `o` makes a blank line below, enters insert, "line2" typed, Esc.
+
+ # keys: O top esc
+ # before
+ bot
+ # after
+ top
+ bot
+
+
+-----------------------------------------------------------------
+= 3.3 WORD MOTIONS: w b e  (W B E long)                          =
+-----------------------------------------------------------------
+
+ `w` next word start, `b` prev word start, `e` next word END.
+ W/B/E treat punctuation as part of the word. Same as Vim & Helix.
+
+ # keys: w i Z esc
+ # before
+ foo bar
+ # after
+ foo Zbar
+
+ `w` from 'f'(col0) lands on 'b'(col4). Insert before 'b'.
+
+ # keys: e i Z esc
+ # before
+ foo bar
+ # after
+ foZo bar
+
+ `e` from 'f' lands on 'o'(col2, end of "foo"). Insert before it.
+
+ # keys: b i Z esc
+ # at: 0,4
+ # before
+ foo bar
+ # after
+ Zfoo bar
+
+ Cursor on 'b'(col4, "bar"). `b` -> start of previous word = 'f'(col0).
+
+
+-----------------------------------------------------------------
+= 3.4 LINE BOUNDS: 0 $ ^  g g  G                                 =
+-----------------------------------------------------------------
+
+ `0` start of line, `$` end, `^` first non-blank.
+ `gg` first line, `G` last line. Same as Vim/Helix.
+
+ # keys: $ i Z esc
+ # before
+ abcde
+ # after
+ abcdZe
+
+ `$` to last char 'e', insert before it. (Cursor ON a char, so "end" =
+ last char, not past it.)
+
+ # keys: 0 i Z esc
+ # before
+ abcde
+ # after
+ Zabcde
+
+ # keys: ^ i Z esc
+ # before
+   abcde
+ # after
+   Zabcde
+
+
+-----------------------------------------------------------------
+= 3.5 LINE SELECTION + EDIT: x d c y p                           =
+-----------------------------------------------------------------
+
+ The Pardes difference is LINE-first selection: `x` grows a line
+ selection downward; d/c/y act on it. `v` is still available for a
+ character range when you need one.
+
+   `x` start/extend a line selection
+   `d` delete the selected lines (yanked)
+   `c` clear the line + insert (change)
+   `y` yank the selection (or current line)
+   `p` paste the yank as a new line below
+
+ # keys: x d
+ # at: 1,0
+ # before
+ keep
+ gone
+ # after
+ keep
+
+ Cursor on "gone" (row 1). `x` selects it, `d` deletes it.
+
+ # keys: x x d
+ # at: 1,0
+ # before
+ a
+ b
+ c
+ # after
+ a
+
+ `x` selects "b", `x` extends to "c", `d` removes both.
+
+ # keys: x y j p
+ # before
+ orig
+ dupe
+ # after
+ orig
+ dupe
+ orig
+
+ `x` selects "orig", `y` yanks it, `j` to "dupe", `p` pastes below.
+
+ # keys: x c typed esc
+ # before
+ old
+ # after
+ typed
+
+ `x` selects "old", `c` clears it to an empty line + insert, type.
+
+ # keys: c Q esc
+ # at: 0,1
+ # before
+ ab
+ # after
+ aQ
+
+ No selection: cursor on 'b'(col1). `c` deletes 'b' + insert; type 'Q'.
+
+
+-----------------------------------------------------------------
+= 3.6 VIEWPORT + PANES                                           =
+-----------------------------------------------------------------
+
+   zt / zz / zb     scroll so the cursor is at top/center/bottom
+   Ctrl-d / Ctrl-u  half-page down / up
+   Ctrl-f           full page down.  (Ctrl-b pages up on a file pane;
+                    on a terminal it is the default tty toggle. If you
+                    start with --tty-toggle=g, Ctrl-g takes that role.)
+   Ctrl-w h/j/k/l   focus the pane left/down/up/right
+   Alt-n            new terminal below the active one
+   Alt-c            move the active terminal into a fresh column
+
+ (No practice blocks: these are viewport/layout, not text edits.)
+
+
+=================================================================
+=             SUMMARY                                            =
+=================================================================
+
+ MOUSE (acme):  L select/focus+pin   M execute   R look(open)
+                select-then-act: middle-drag, or v/x then Tab
+                file tag = mode + path + "Save Del"; other tags show Del
+                top bar = Kill Newcol Tutor Debug Colors NextColor
+ TTY:           a terminal IS a pane;  Ctrl-b toggles the live shell by default,
+                landing its cursor where you navigated (prompt start if
+                the input is empty, mid-text otherwise)
+ KEYS (helix):  h j k l  w b e  0 $ ^  gg G  v x  d c y p  i a I A o O
+                u undo  U redo   Enter=look  Tab=execute
+                zt zz zb  Ctrl-d/u  Ctrl-f  Ctrl-w hjkl  Alt-n/c
+
+ vs Helix: no multi-cursor; selection is LINE-first (x), plus v chars.
+ vs Vim:  no verb+noun (dw); motions only move; Esc never reaches tty.
+ vs both: a terminal is just a pane; the same keys edit text and
+          navigate the shell screen, and the tty toggle reuses the
+          shell's own prompt to position you precisely.
+
+ To spawn THIS tutor again from anywhere: middle-click "Tutor" in the
+ top bar (next to Kill / Newcol).
+
+ Quit the tutor: this is a file pane — `:q` isn't wired; close the
+ window (middle-click "Del" in its tag), "Kill" (top bar) to quit
+ everything, or Ctrl-c the app.